laboratori-cloud/CLAUDE.md

Versione: 3.3 (Hybrid Agent-Based + Sequential Thinking)

Ambito: Sviluppo Materiale Didattico e Infrastruttura Locale per "Corso Lab Soluzioni Cloud" (Framework Diátaxis).

Architettura: GSD (Orchestration) + Universal Skills Manager (Specialized Agents).

Guida Suprema: Safety first, little often, double check.

---

1. Filosofia di Sviluppo

1.1 Spec-Driven Infrastructure (SDI)

Nessun laboratorio o configurazione viene scritto senza una specifica architetturale approvata.

• Contratto: Ogni modulo (Lab) deve avere un PRD che ne definisca l'obiettivo didattico, la topologia di rete, i limiti di risorse e il parallelismo con il servizio Cloud reale (es. AWS VPC, RDS).
• Validazione: Si usa docker-compose config e validatori YAML formali per garantire che i file di infrastruttura siano corretti prima dell'esecuzione.

1.2 Test-Driven Infrastructure (TDI)

L'infrastruttura nasce dai test. Seguiamo rigorosamente il ciclo per verificare i criteri di accettazione.

1. RED: Scrittura dello script di test fallimentare (es. uno script bash che fa curl o nc verso una porta che deve essere isolata o esposta).
2. GREEN: Scrittura del minimo codice infrastrutturale (docker-compose.yml, regole iptables, permessi file) per far passare il test.
3. REFACTOR: Ottimizzazione delle immagini Docker, pulizia dei layer e hardening della sicurezza senza rompere i test.

1.3 Hybrid Agent-Assisted Development

Lo sviluppo è orchestrato da un Agente Primario che genera i contenuti didattici e l'infrastruttura, delegando dove necessario.

• Fasi: Raccolta Requisiti → Pianificazione Architettura → Creazione Test → Stesura Documentazione (Diátaxis) → Validazione.
• Delega: L'Agente valuta se usare skill specifiche per l'ottimizzazione di Dockerfile o la generazione di script Bash complessi consultando lo Universal Skills Manager (USM).
• Controllo: L'uso di skill è soggetto al protocollo di sicurezza "Curated Skills" (Sezione 7.5).

---

2. Standard di Documentazione Obbligatoria (Framework Diátaxis)

2.1 Output Didattico a 4 Quadranti

Per ogni Laboratorio, l'agente deve generare obbligatoriamente quattro tipologie di documento:

1. Tutorials: Guida passo-passo incrementale (little often) per guidare l'allievo.
2. How-to Guides: Procedure specifiche (es. "Come generare chiavi SSH", "Come ripulire i volumi Docker").
3. Reference: Specifiche tecniche nude e crude (mappe IP, tabelle porte esposte, spiegazione direttive docker-compose).
4. Explanation: Il raccordo concettuale (parallelismo tra l'ambiente locale simulato e i veri servizi Cloud managed).

2.2 File di Gestione Progetto

• ARCHITECTURE.md: Tracciabilità delle scelte. Perché abbiamo scelto MinIO per simulare S3? Perché usiamo bridge networks isolate?
• BUGS.md: Registro storico. Es. Conflitti di porte sull'host, container andati in OOM kill durante gli stress test. (Errore, Causa Radice, Soluzione).
• PROGRESS.md: Tracciamento operativo. Log delle attività e stesura dei moduli completati.

---

3. Gestione del Codice (Git Workflow)

3.1 Branching Strategy

• main: Solo laboratori completi, testati e documentati.
• develop: Ramo di integrazione.
• Lab Branches (lab-01-iam, lab-02-network): Sviluppo isolato del singolo modulo didattico.

3.2 Conventional Commits

Commit atomici per guidare gli allievi con l'esempio: feat: add private vpc network, test: verify db connection via pg_isready, docs: write explanation for S3 simulation.

---

4. Stack Tecnologico (Infrastruttura e Simulazione)

L'infrastruttura si basa su tecnologie open-source standard per simulare i cloud provider.

Categoria	Tecnologia	Perché?
Orchestrazione	docker, docker-compose	Setup riproducibile, isolamento nativo e standard di mercato.
Networking	bridge networks, iptables	Simulazione di VPC, Subnets pubbliche/private e NAT Gateway.
Object Storage	MinIO	Compatibilità 100% con le API di AWS S3.
Database	PostgreSQL / MySQL	Simulazione di servizi RDS managed con script di init pre-configurati.
Testing	bash, curl, nc, nmap	Double Check della connettività e dei confini di sicurezza.

⚙️ Prerequisiti di Sistema (Host)

Il sistema host o la VM base di laboratorio deve avere installato:

• Docker Engine >= 24.0
• Docker Compose V2
• Utility di rete standard (netcat, curl, iproute2)

---

5. Standard Sistemistici (Safety First)

1. Minimo Privilegio (IAM): I container non devono mai girare come root (usare direttiva user: o configurare l'utente nel Dockerfile).
2. Isolamento di Rete (VPC): Le reti private non devono esporre porte sull'host (127.0.0.1:port:port al massimo, mai 0.0.0.0).
3. Enforcement delle Risorse (Compute): Obbligatorio impostare cpus e mem_limit nei file compose per simulare le "size" delle istanze cloud ed evitare il blocco della macchina host.
4. Persistenza (Storage): I dati devono sopravvivere al riavvio dei container tramite l'uso esplicito di Docker Volumes nominativi.

---

6. Checklist di Qualità (Double Check)

Prima di completare un laboratorio e fare il merge:

• I 4 documenti del framework Diátaxis sono stati redatti con un tono diretto e semplice.
• Il parallelismo Cloud <-> Locale è spiegato chiaramente nella sezione Explanation.
• Il file docker-compose.yml rispetta i vincoli di sicurezza (no root, limiti risorse, reti separate).
• Lo script di test del laboratorio (TDI) esegue correttamente i controlli previsti (es. ping fallito tra reti isolate).
• I file ARCHITECTURE.md e PROGRESS.md sono aggiornati.
• Il ragionamento logico per le architetture di rete complesse è stato validato con Sequential Thinking (sezione 7.2).
• Le configurazioni e le porte standard sono state verificate con Context7 / zread (sezione 7.3 e 7.4).

---

7. Integrazione MCP, ZAI Tools e Agenti Specializzati

L'ambiente è potenziato da strumenti e agenti specializzati. È vietato indovinare configurazioni Docker o di rete quando strumenti specifici sono disponibili.

7.1 Memoria Persistente (claude-mem)

• Uso: Interroga la memoria prima di modificare topologie di rete per mantenere la coerenza degli IP (es. 10.0.x.0/24) decisa nei laboratori precedenti.

7.2 Ragionamento Passo-Passo (sequential-thinking)

• Obbligatorio: Mandatorio per configurare regole di routing, NAT tramite iptables o quando si impostano i limiti di memoria che potrebbero causare OOM kill incrociati.

7.3 Documentazione Tecnica (context7)

• Uso: Usalo per verificare le direttive più recenti di Docker Compose V2 o le flag di MinIO.

7.4 Accesso a Repositori Open Source (zread)

• Uso: Valida le implementazioni di container di test o tool di rete guardando i Dockerfile ufficiali (es. Alpine, Nginx).

7.5 Universal Skills Manager (USM) e Protocollo "Curated Skills"

• Regole di delega per task come: l'ottimizzazione di un Dockerfile personalizzato per il Lab, o la generazione di script di validazione bash. Applicare il processo di whitelist e l'approvazione utente come da standard.

---

8. Flussi Operativi Obbligatori (Workflows)

(I flussi 8.1 - 8.6 rimangono operativi identici alla specifica core, focalizzati sui file markdown, l'infrastruttura Docker e l'USM)

8.7 Protocollo di Selezione del Modello (Model Escalation)

Valutazione della Complessità: Un task è definito "Alta Complessità" se coinvolge:

• Progettazione di reti bridge interconnesse con regole di iptables personalizzate.
• Scrittura di guide concettuali (Explanation) che richiedono una profonda conoscenza comparata dei servizi AWS/Azure/GCP.
• Debug di problemi di permessi tra host Linux e container sui volumi bind-mounted.

Protocollo Operativo: Se il task è di Alta Complessità, l'agente deve fermarsi e richiedere l'upgrade del modello (RTU) avvisando l'utente.