**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.