75f40acb17
- Create src/openrouter_monitor/ package structure - Create models/, routers/, services/, utils/ subpackages - Create tests/unit/ and tests/integration/ structure - Create alembic/, docs/, scripts/ directories - Add test_project_structure.py with 13 unit tests - All tests passing (13/13) Refs: T01
222 lines
6.4 KiB
Markdown
222 lines
6.4 KiB
Markdown
---
|
|
name: project-guidelines
|
|
description: Linee guida per lo sviluppo del progetto. Usa questa skill per comprendere l'architettura, le convenzioni di codice e il workflow di sviluppo.
|
|
---
|
|
|
|
# Project Guidelines - [NOME PROGETTO]
|
|
|
|
> ⚠️ **NOTA**: Personalizza questo file con il nome e la descrizione del tuo progetto!
|
|
|
|
## Panoramica del Progetto
|
|
|
|
**[NOME PROGETTO]** è [breve descrizione del progetto - da personalizzare].
|
|
|
|
## Quick Start
|
|
|
|
### Leggere Prima
|
|
1. **Workflow**: `.opencode/WORKFLOW.md` - Flusso di lavoro obbligatorio
|
|
2. **PRD**: `prd.md` - Requisiti prodotto
|
|
3. **AGENTS.md**: Linee guida generali del progetto (se esiste)
|
|
|
|
### Agenti Disponibili (in `.opencode/agents/`)
|
|
|
|
| Agente | Ruolo | Quando Usare |
|
|
|--------|-------|--------------|
|
|
| `@spec-architect` | Definisce specifiche e architettura | Prima di nuove feature |
|
|
| `@tdd-developer` | Implementazione TDD | Durante sviluppo |
|
|
| `@git-manager` | Gestione commit Git | A fine task |
|
|
|
|
## Flusso di Lavoro (OBBLIGATORIO)
|
|
|
|
### Per Nuove Feature
|
|
|
|
```
|
|
1. @spec-architect → Legge PRD, definisce specifiche
|
|
↓
|
|
Crea/aggiorna:
|
|
- /export/prd.md
|
|
- /export/architecture.md
|
|
- /export/kanban.md
|
|
↓
|
|
2. @tdd-developer → Implementa seguendo TDD
|
|
↓
|
|
RED → GREEN → REFACTOR
|
|
↓
|
|
3. @git-manager → Commit atomico
|
|
↓
|
|
Conventional Commit
|
|
```
|
|
|
|
### Per Bug Fix
|
|
|
|
```
|
|
1. Leggi bug_ledger.md per pattern simili
|
|
2. Scrivi test che riproduce il bug
|
|
3. Implementa fix
|
|
4. Aggiorna bug_ledger.md
|
|
5. Commit con tipo "fix:"
|
|
```
|
|
|
|
## Regole Fondamentali
|
|
|
|
### 1. TDD (Test-Driven Development)
|
|
- **RED**: Scrivi test fallimentare PRIMA
|
|
- **GREEN**: Scrivi codice minimo per passare
|
|
- **REFACTOR**: Migliora mantenendo test verdi
|
|
|
|
### 2. Spec-Driven
|
|
- Leggi sempre `prd.md` prima di implementare
|
|
- Non implementare funzionalità non richieste
|
|
- Output specifiche in `/export/`
|
|
|
|
### 3. Little Often
|
|
- Task piccoli e verificabili
|
|
- Progresso incrementale
|
|
- Commit atomici
|
|
|
|
### 4. Memoria
|
|
- Bug complessi → `docs/bug_ledger.md`
|
|
- Decisioni design → `docs/architecture.md`
|
|
- Progresso task → `export/progress.md` (aggiorna inizio/fine task)
|
|
|
|
### 5. Git
|
|
- Conventional commits obbligatori
|
|
- Commit atomici
|
|
- Test verdi prima del commit
|
|
- Documenta contesto in `export/githistory.md`
|
|
|
|
## Struttura Progetto (Personalizza)
|
|
|
|
```
|
|
[nome-progetto]/
|
|
├── src/ # Codice sorgente
|
|
│ └── [nome_package]/
|
|
│ ├── [moduli]/ # Moduli applicativi
|
|
│ └── ...
|
|
├── tests/ # Test suite
|
|
│ ├── unit/
|
|
│ ├── integration/
|
|
│ └── e2e/
|
|
├── docs/ # Documentazione
|
|
│ ├── bug_ledger.md # Log bug risolti
|
|
│ └── architecture.md # Decisioni architetturali
|
|
├── export/ # Output spec-driven
|
|
│ ├── prd.md # Product Requirements
|
|
│ ├── architecture.md # Architettura
|
|
│ ├── kanban.md # Task breakdown
|
|
│ ├── progress.md # Tracciamento progresso
|
|
│ └── githistory.md # Storico commit
|
|
├── .opencode/ # Configurazione OpenCode
|
|
│ ├── WORKFLOW.md # Flusso di lavoro
|
|
│ ├── agents/ # Configurazioni agenti
|
|
│ └── skills/ # Skill condivise
|
|
├── scripts/ # Script utilità
|
|
├── prd.md # Product Requirements (root)
|
|
├── AGENTS.md # Linee guida generali (opzionale)
|
|
└── SKILL.md # Questo file
|
|
```
|
|
|
|
## Convenzioni di Codice (Personalizza)
|
|
|
|
### [Linguaggio - es. Python/JavaScript/Go]
|
|
- Versione: [es. 3.10+]
|
|
- Stile: [es. PEP 8 / StandardJS / gofmt]
|
|
- Type hints: [obbligatorio/consigliato]
|
|
- Line length: [es. 100 caratteri]
|
|
|
|
### Testing
|
|
- Framework: [pytest/jest/go test]
|
|
- Coverage target: ≥90%
|
|
- Pattern: AAA (Arrange-Act-Assert)
|
|
- Mock per dipendenze esterne
|
|
|
|
### Commit
|
|
```
|
|
<type>(<scope>): <description>
|
|
|
|
[body]
|
|
|
|
[footer]
|
|
```
|
|
|
|
**Tipi:** feat, fix, docs, test, refactor, chore, ci, style
|
|
**Scope:** [personalizza in base al progetto - es. api, db, ui, core]
|
|
|
|
## Risorse
|
|
|
|
| File | Scopo |
|
|
|------|-------|
|
|
| `prd.md` | Requisiti prodotto |
|
|
| `AGENTS.md` | Linee guida progetto (se esiste) |
|
|
| `.opencode/WORKFLOW.md` | Flusso di lavoro dettagliato |
|
|
| `.opencode/agents/` | Configurazioni agenti |
|
|
| `docs/bug_ledger.md` | Log bug risolti |
|
|
| `docs/architecture.md` | Decisioni architetturali |
|
|
| `export/progress.md` | Tracciamento progresso task |
|
|
| `export/githistory.md` | Storico commit con contesto |
|
|
| `CHANGELOG.md` | Changelog |
|
|
| `CONTRIBUTING.md` | Guida contribuzione |
|
|
|
|
## Comandi Utili (Personalizza)
|
|
|
|
```bash
|
|
# Test
|
|
[comando test] # Tutti i test
|
|
[comando test --coverage] # Con coverage
|
|
|
|
# Qualità
|
|
[comando lint] # Linting
|
|
[comando format] # Formattazione
|
|
[comando type-check] # Type checking
|
|
|
|
# Pre-commit
|
|
[comando pre-commit]
|
|
|
|
# Server/Run
|
|
[comando run]
|
|
```
|
|
|
|
## Checklist
|
|
|
|
### Setup Iniziale (da fare una volta)
|
|
- [ ] Personalizzato `SKILL.md` con nome progetto
|
|
- [ ] Creata struttura cartelle `src/`
|
|
- [ ] Configurato ambiente di sviluppo
|
|
- [ ] Inizializzato `prd.md` con requisiti
|
|
- [ ] Inizializzato `export/kanban.md` con task
|
|
|
|
### Pre-Implementazione
|
|
- [ ] Ho letto `prd.md`
|
|
- [ ] Ho compreso lo scope
|
|
- [ ] Ho letto `.opencode/WORKFLOW.md`
|
|
|
|
### Durante Implementazione
|
|
- [ ] Test scritto prima (RED)
|
|
- [ ] Codice minimo (GREEN)
|
|
- [ ] Refactoring (REFACTOR)
|
|
|
|
### Post-Implementazione
|
|
- [ ] Tutti i test passano
|
|
- [ ] Coverage ≥90%
|
|
- [ ] `bug_ledger.md` aggiornato (se bug)
|
|
- [ ] `architecture.md` aggiornato (se design)
|
|
- [ ] `progress.md` aggiornato (inizio/fine task)
|
|
- [ ] `githistory.md` aggiornato (contesto commit)
|
|
- [ ] Commit con conventional commits
|
|
|
|
---
|
|
|
|
*Per dettagli su flusso di lavoro, vedere `.opencode/WORKFLOW.md`*
|
|
|
|
---
|
|
|
|
## 📝 Note per l'Utente
|
|
|
|
Questo è un template. Per usarlo:
|
|
|
|
1. **Sostituisci** `[NOME PROGETTO]` con il nome reale
|
|
2. **Descrivi** il progetto nella sezione Panoramica
|
|
3. **Personalizza** la struttura cartelle in base al tuo stack
|
|
4. **Aggiungi** comandi specifici del tuo linguaggio/framework
|
|
5. **Definisci** gli scope dei commit pertinenti al tuo progetto
|