docs: add Phase 3 validation strategy and project specifications
- Add 03-VALIDATION.md for Phase 3 (Lab 02 Network & VPC) - Add CLAUDE.md v3.3 with hybrid agent-based development standards - Add prd.md with product requirements for cloud course Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Luca Sacchi Ricciardi
145
CLAUDE.md
Normal file
145
CLAUDE.md
Normal file
@@ -0,0 +1,145 @@
|
||||
**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.
|
||||
Reference in New Issue
Block a user