docs: update AGENTS.md with complete agent rules and workflow
This commit is contained in:
Luca Sacchi Ricciardi
103
AGENTS.md
103
AGENTS.md
@@ -1,51 +1,82 @@
|
|||||||
LogWhisperer AI - Agent Rules
|
# LogWhisperer AI - Agent Rules
|
||||||
|
|
||||||
Metodologia di Lavoro
|
Regole operative per gli agenti AI che collaborano su questo progetto.
|
||||||
|
|
||||||
Spec-Driven: Prima di ogni modifica, l'agente deve aggiornare o confermare le specifiche in docs/.
|
---
|
||||||
|
|
||||||
TDD (Test-Driven Development): Non scrivere logica senza un test fallimentare preventivo. Usa pytest.
|
## Metodologia di Lavoro
|
||||||
|
|
||||||
Sacchi Method: Applica sempre "Safety first, little often, double check". Verifica i permessi prima di eseguire comandi bash distruttivi.
|
### Spec-Driven
|
||||||
|
Prima di ogni modifica, l'agente deve aggiornare o confermare le specifiche in `docs/specs/`.
|
||||||
|
|
||||||
Git Workflow:
|
### TDD (Test-Driven Development)
|
||||||
|
Non scrivere logica senza un test fallimentare preventivo. Usa pytest.
|
||||||
|
|
||||||
Usa Conventional Commits (es. feat:, fix:, docs:, test:).
|
### Sacchi Method
|
||||||
|
Applica sempre "**Safety first, little often, double check**". Verifica i permessi prima di eseguire comandi bash distruttivi.
|
||||||
|
|
||||||
Ogni commit deve essere atomico.
|
### Git Workflow
|
||||||
|
- **Conventional Commits**: usa `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`
|
||||||
|
- **Atomic Commits**: un commit per singola modifica funzionale
|
||||||
|
- **Changelog**: aggiorna `CHANGELOG.md` seguendo lo standard Common Changelog
|
||||||
|
|
||||||
Aggiorna CHANGELOG.md seguendo lo standard Common Changelog.
|
---
|
||||||
|
|
||||||
Definizione dei Ruoli (Sub-agents)
|
## Staff di Agenti
|
||||||
|
|
||||||
@tech-lead: Responsabile dell'architettura e della validazione delle specifiche (PRD).
|
Configurazioni dettagliate in `.opencode/agents/`:
|
||||||
|
|
||||||
@developer: Scrive il codice Python e lo script Bash seguendo i test.
|
| Agente | Ruolo | Focus |
|
||||||
|
|--------|-------|-------|
|
||||||
|
| `@tech-lead` | L'Architetto | Validazione specifiche, architettura |
|
||||||
|
| `@product-manager` | Il Garante del Valore | PRD, roadmap, priorità |
|
||||||
|
| `@python-developer` | Il Costruttore TDD | Implementazione Python (PEP8) |
|
||||||
|
| `@bash-expert` | Lo Specialista Ingestion | Script Bash (low footprint) |
|
||||||
|
| `@security-auditor` | Il Guardiano | Vulnerabilità, protezione dati |
|
||||||
|
| `@qa-engineer` | Il Tester | Test suite, copertura, regressioni |
|
||||||
|
| `@documentation-agent` | Il Cronista | Changelog, docs, commit messages |
|
||||||
|
|
||||||
@qa-engineer: Scrive ed esegue i test, garantendo la copertura delle feature critiche.
|
---
|
||||||
|
|
||||||
|
## Workflow Operativo
|
||||||
|
|
||||||
### 3. Configurazione Tecnica (`opencode.json`)
|
|
||||||
Per gestire il progetto con Python e attivare le potenzialità agentiche, configura il file di impostazioni di OpenCode (solitamente in `~/.config/opencode/opencode.json` o localmente se supportato):
|
|
||||||
|
|
||||||
Assicurati che i **Tools** siano abilitati per permettere all'agente di usare il terminale nel tuo `venv`.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 4. Uso delle Skills (Il potenziamento)
|
|
||||||
Per un risultato eccellente, useremo le **Skills**. Le skills sono playbook che OpenCode carica on-demand. Crea una cartella `.opencode/skills/` e aggiungi questi file:
|
|
||||||
|
|
||||||
- **python_expert.md**: Istruzioni su come gestire il venv, installare dipendenze con `pip` e seguire il PEP8.
|
|
||||||
- **tdd_workflow.md**: Una guida passo-passo che obbliga l'agente a:
|
|
||||||
1. Creare il test.
|
|
||||||
2. Eseguire il test (deve fallire).
|
|
||||||
3. Scrivere il codice minimo.
|
|
||||||
4. Rieseguire il test (deve passare).
|
|
||||||
- **git_standard.md**: Istruzioni rigide su come scrivere i messaggi di commit e aggiornare il changelog.
|
|
||||||
|
|
||||||
### 5. Avvio e Operatività
|
|
||||||
Ora sei pronto. Avvia OpenCode nella root del progetto:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
opencode
|
|
||||||
```
|
```
|
||||||
|
1. @product-manager → definisce obiettivo
|
||||||
|
2. @tech-lead → scrive/valida specifica in docs/specs/
|
||||||
|
3. @qa-engineer → scrive test (RED phase)
|
||||||
|
4. @python-developer / @bash-expert → implementa (GREEN phase)
|
||||||
|
5. @security-auditor → valida sicurezza
|
||||||
|
6. @documentation-agent → aggiorna changelog e commit
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Struttura Configurazione
|
||||||
|
|
||||||
|
```
|
||||||
|
.opencode/
|
||||||
|
├── agents/ # Configurazioni agenti individuali
|
||||||
|
│ ├── tech-lead.md
|
||||||
|
│ ├── product-manager.md
|
||||||
|
│ ├── python-developer.md
|
||||||
|
│ ├── bash-expert.md
|
||||||
|
│ ├── security-auditor.md
|
||||||
|
│ ├── qa-engineer.md
|
||||||
|
│ └── documentation-agent.md
|
||||||
|
└── skills/ # Playbook condivisi
|
||||||
|
├── TDD_Python_Specialist/
|
||||||
|
└── Git_and_Changelog/
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Skills Disponibili
|
||||||
|
|
||||||
|
Skills condivise in `.opencode/skills/`:
|
||||||
|
|
||||||
|
- **TDD_Python_Specialist/**: Workflow TDD (RED → GREEN → REFACTOR)
|
||||||
|
- **Git_and_Changelog/**: Conventional commits, Common Changelog
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Per configurazioni dettagliate, vedere i file in `.opencode/agents/`*
|
||||||
|
|||||||
Reference in New Issue
Block a user