Sistemi di regole e guida al comportamento

I file di regole sono documenti Markdown che definiscono come Verdent si comporta e risponde durante le sessioni di codifica. Guidano il comportamento dell'agente AI, la formattazione dell'output, il processo decisionale e l'aderenza agli standard del progetto.

Scopo: le regole ti permettono di personalizzare il comportamento di Verdent senza modificare codice o impostazioni. Stabiliscono convenzioni di codifica, pattern preferiti, stile di comunicazione e preferenze di esecuzione delle attività che persistono tra le sessioni.

Come funzionano le regole: Verdent fa costantemente riferimento ai file di regole durante le conversazioni, applicando le linee guida alla generazione di codice, all'analisi, alla documentazione e al processo decisionale. Le regole influenzano ogni risposta dell'agente per garantire coerenza con le preferenze dell'utente.

Tre categorie:

• Preferenze globali (VERDENT.md) - Stile di codifica personale, preferenze linguistiche
• Standard specifici del progetto (AGENTS.md) - Convenzioni del team, pattern architetturali
• Personalizzazione del piano (Plan.md) - Formato e contenuto dell'output di Plan Mode

Precedenza delle regole: quando le regole entrano in conflitto, Verdent applica la precedenza: AGENTS.md (più alta) → VERDENT.md (media) → impostazioni predefinite (più bassa)

Regole utente (VERDENT.md)

VERDENT.md definisce le preferenze globali che si applicano a tutti i progetti e le sessioni. Stabilisce lo stile di codifica personale, gli strumenti preferiti, le preferenze di comunicazione e i comportamenti predefiniti.

Posizione e ambito

Posizione del file: ~/.verdent/VERDENT.md

Ambito: globale per tutti i progetti

Accesso:

• Settings → Rules → User Rules
• Modifica diretta del file in ~/.verdent/VERDENT.md

Applicazione delle modifiche: le regole si applicano immediatamente nelle nuove conversazioni e influenzano le risposte della conversazione in corso.

Casi d'uso

Formato e sintassi

VERDENT.md usa il semplice formato Markdown con elenchi puntati o numerati.

Struttura:

# User Rules

## Code Style Preferences
- Always use TypeScript strict mode
- Prefer functional components in React
- Include JSDoc comments for exported functions

## Documentation
- Add JSDoc comments for all exported functions
- Include usage examples in component documentation

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

Stile di scrittura:

• Usa un linguaggio chiaro e direttivo ("Usa sempre...", "Preferisci...", "Mai...")
• Organizza in sezioni logiche con intestazioni
• Elenchi puntati per le singole regole
• Sii specifico riguardo al comportamento desiderato

Esempi per tipo di sviluppatore

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases for object shapes
- Include return types on all functions
- Use const assertions where appropriate

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

# User Rules

## Python Style
- Follow PEP 8 conventions
- Use type hints for function signatures
- Prefer list comprehensions over map/filter

## Data Analysis
- Use pandas for data manipulation
- Include DataFrame.head() after transformations
- Document assumptions about data

## Output Format
- Show shape and info() after operations
- Include visualization examples

# User Rules

## JavaScript Preferences
- Use ES6+ features (arrow functions, destructuring)
- Async/await over promises
- Template literals for string interpolation

## Testing
- Jest for unit tests
- Include test cases for edge conditions
- Aim for 80%+ code coverage

## Code Review
- Flag potential performance issues
- Suggest security improvements

# User Rules

## Communication
- Always respond in French
- Use technical English terms when no French equivalent exists
- Provide French variable/function names when appropriate

## Code Comments
- Write comments in French
- Documentation in both French and English

# User Rules

## Code Style
- Minimal comments - code should be self-documenting
- Short, focused functions (< 20 lines)
- Avoid unnecessary abstractions

## Output Preferences
- Brief explanations
- Show code first, explain after
- No verbose documentation unless requested

Come creare e modificare

Regole di progetto (AGENTS.md)

AGENTS.md definisce le regole specifiche del progetto che controllano il comportamento dell'agente per il progetto corrente. Stabilisce gli standard di codifica del team, i pattern architetturali, i requisiti di test e i flussi di lavoro di sviluppo specifici del progetto.

Posizione e ambito

Posizione del file: directory radice del progetto

Ambito: solo il progetto corrente

Controllo di versione: può essere committato su git per la condivisione a livello di team

Accesso:

• Settings → Rules → Project Rules
• Modifica diretta in <project-root>/AGENTS.md

Casi d'uso

Collaborazione del team: AGENTS.md è memorizzato nella radice del progetto e può essere committato nel controllo di versione, garantendo che tutti i membri del team lavorino con un comportamento dell'agente coerente.

Formato e sintassi

AGENTS.md usa il formato Markdown con sezioni strutturate ed elenchi puntati, simile a VERDENT.md ma incentrato sui requisiti specifici del progetto.

Struttura:

# AGENTS.md

## Dev environment tips
- Command for navigating workspace
- Installation commands
- Environment setup instructions

## Testing instructions
- Test execution commands
- Coverage requirements
- CI/CD integration details

## PR instructions
- Title format requirements
- Pre-commit checklist
- Review guidelines

Stile di scrittura:

• Linguaggio imperativo e direttivo
• Organizzato per area di flusso di lavoro (sviluppo, test, deployment)
• Comandi e procedure specifici
• Standard a livello di team, non preferenze personali

Esempi per tipo di progetto

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add package to workspace
- Check the name field in package.json to confirm the right name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>` for all checks
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

# AGENTS.md

## Code Standards
- Use functional components with hooks
- TypeScript strict mode required
- Named exports only (no default exports)
- PropTypes or TypeScript interfaces for all components

## File Organization
- One component per file
- Components in `src/components/`
- Hooks in `src/hooks/`
- Utils in `src/utils/`

## Testing
- Jest + React Testing Library
- Test all user interactions
- 80%+ coverage required

# AGENTS.md

## API Standards
- All endpoints include input validation
- Use async/await for asynchronous operations
- Consistent error format: { error: string, code: number }
- Rate limiting on public endpoints

## Security
- Never log sensitive data (passwords, tokens, PII)
- Parameterized queries only (prevent SQL injection)
- Validate and sanitize all inputs

## Testing
- Unit tests for all business logic
- Integration tests for API endpoints
- Test success and error cases

# AGENTS.md

## Platform Support
- iOS 14+ and Android API 26+
- React Native 0.72+
- Test on both platforms before PR

## State Management
- Use Redux Toolkit
- Async operations with Redux Thunk
- Normalize state shape

## Performance
- Images: WebP format, max 500KB
- Bundle size: monitor with bundle analyzer
- FlatList for long lists (>20 items)

# AGENTS.md

## Django Conventions
- Follow Django best practices and PEP 8
- Class-based views preferred
- Django ORM for database operations
- Migrations: never edit generated files

## Testing
- pytest-django for all tests
- Factory Boy for test fixtures
- Coverage must be 90%+

## Deployment
- Docker compose for local development
- Environment variables in .env (never committed)
- Run migrations before deployment

Differenze rispetto a VERDENT.md

Ambito:

• VERDENT.md: preferenze personali su tutti i progetti
• AGENTS.md: standard del team solo per un progetto specifico

Priorità:

• AGENTS.md: precedenza più alta - sovrascrive user_rules per la coerenza del progetto
• VERDENT.md: precedenza più bassa - si applica quando nessuna regola di progetto è in conflitto

Focus del contenuto:

• VERDENT.md: stile di codifica individuale, preferenze di comunicazione, strumenti personali
• AGENTS.md: convenzioni del team, architettura del progetto, flussi di lavoro condivisi, stack tecnologico

Controllo di versione:

• VERDENT.md: non condiviso - rimane sulla macchina dell'individuo
• AGENTS.md: committato su git - condiviso con l'intero team

Archiviazione:

• VERDENT.md: ~/.verdent/VERDENT.md (globale)
• AGENTS.md: directory radice del progetto (specifico del progetto)

Esempio di risoluzione dei conflitti:

VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)

Quando usare quale:

• VERDENT.md: preferenze personali che vuoi su tutti i progetti
• AGENTS.md: standard che l'intero team deve seguire per questo progetto

Regole di piano (Plan.md)

Plan.md personalizza il contenuto e il formato dei piani generati in Plan Mode. Controlla il livello di dettaglio del piano, le sezioni incluse, le preferenze di formattazione e le informazioni visualizzate.

Posizione e ambito

Posizione del file: ~/.verdent/plan_settings.json

Ambito: globale per tutti i progetti

Applicazione: applicato solo durante Plan Mode quando si generano i piani

Accesso:

• Settings → Rules → Plan Rules
• Modifica diretta del file in ~/.verdent/plan_settings.json

Casi d'uso

Formato e sintassi

Plan.md usa il formato Markdown con sezioni che descrivono la struttura e il contenuto del piano desiderati.

Struttura:

---
name: Plan Rules
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes

Esempi per stile di pianificazione

---
name: Detailed Technical
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Executive summary (2-3 sentences)
- Prerequisites and dependencies
- Numbered implementation steps
- Testing and verification strategy
- Rollback procedures

## Level of Detail
- Break into 20-30 minute tasks
- Specific file paths for all modifications
- Function signatures for new code
- Database schema changes with migration steps

## Format
- Numbered lists for sequence
- Code blocks for complex logic
- Diagrams for architecture changes (describe verbally)

---
name: High-Level Strategic
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Brief overview (1 paragraph)
- Major phases only (3-5 high-level steps)
- Key decisions and trade-offs
- Success criteria

## Level of Detail
- High-level phases (1-2 hours each)
- Avoid implementation specifics
- Focus on approach and strategy

## Format
- Bullet points for flexibility
- Minimal code examples
- Emphasize "why" over "how"

---
name: Time-Conscious
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Time estimates for each step
- Total project duration estimate
- Parallel tasks identified
- Critical path highlighted

## Level of Detail
- Tasks sized to 30-minute increments
- Dependencies clearly marked
- Blocking operations identified

## Format
- Include time estimates inline
- Mark parallel tasks
- Highlight critical path with bold

---
name: Risk-Focused
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Risk assessment for each phase
- Mitigation strategies included
- Rollback procedures defined
- Testing requirements emphasized

## Level of Detail
- Identify potential failure points
- Document error handling approach
- Include recovery procedures

## Format
- Risk levels: low, medium, high
- Separate "Risks" section for each phase
- Mitigation steps in sub-bullets

---
name: Team Collaboration
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Role assignments for each task
- Coordination points identified
- Review checkpoints included
- Communication requirements

## Level of Detail
- Specify who handles each component
- List integration points between team members
- Include pair programming opportunities

## Format
- Use mentions for role assignments
- Mark collaboration points
- Include "Review required" markers

Quando vengono applicate le regole di piano?

Applicazione delle regole di piano:

• Tempistica: applicate solo durante Plan Mode quando si generano i piani
• Ambito: controlla il formato e il contenuto del piano, non la generazione del codice
• Indipendenza: non entra in conflitto con VERDENT.md o AGENTS.md

Applicazione di altri tipi di regole:

• VERDENT.md: applicato continuamente in tutte le modalità (Agent, Plan, Chat)
• AGENTS.md: applicato continuamente in tutte le modalità per il comportamento specifico del progetto

Esempio di interazione:

Plan Mode activated:
1. VERDENT.md: "Use TypeScript" → Applied to code in plan
2. AGENTS.md: "Follow project conventions" → Applied to approach
3. plan_rules.md: "Include time estimates" → Applied to plan format
→ Result: Plan shows TypeScript code following project conventions with time estimates

Comportamento specifico per modalità:

• Agent Mode: VERDENT.md + AGENTS.md applicati (nessun plan_rules.md)
• Plan Mode: VERDENT.md + AGENTS.md + Plan.md tutti applicati
• Chat Mode: VERDENT.md + AGENTS.md applicati (nessun Plan.md)

Precedenza delle regole e risoluzione dei conflitti

Quando le regole entrano in conflitto, Verdent applica la precedenza per garantire un comportamento coerente.

Ordine di precedenza

1. Regole di progetto (AGENTS.md) - Priorità più alta le regole specifiche del progetto sovrascrivono le preferenze globali. Gli standard del team hanno la precedenza sulle preferenze individuali per garantire la coerenza.

2. Regole utente (VERDENT.md) - Priorità media le preferenze globali si applicano quando nessuna regola specifica del progetto è in conflitto.

3. Comportamento predefinito - Priorità più bassa le impostazioni predefinite integrate di Verdent si applicano quando nessuna regola è specificata.

Esempio di risoluzione dei conflitti:

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: Verdent uses 4-space indentation (project rules win)

Regole di piano: Plan.md si applica in modo indipendente durante Plan Mode e non entra in conflitto con le regole utente/progetto. Controlla il formato del piano, mentre VERDENT.md e AGENTS.md controllano lo stile del codice all'interno del piano.

Risoluzione dei problemi con i conflitti tra regole

Quando osservi un comportamento inatteso che contraddice una regola, segui questa strategia di debug:

Passaggio 1: Identifica il conflitto

1. Osserva il comportamento inatteso che contraddice una regola
2. Verifica quali regole potrebbero applicarsi alla situazione
3. Cerca contraddizioni tra i file di regole

Passaggio 2: Verifica la precedenza delle regole

AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)

Le regole di progetto sovrascrivono le preferenze personali.

Passaggio 3: Testa in isolamento

Disabilita VERDENT.md: rinomina o svuota temporaneamente il file, verifica se il conflitto si risolve

Testa senza AGENTS.md: lavora nel progetto senza AGENTS.md per isolare il comportamento di user_rules

Nuova conversazione: avvia una sessione da zero per eliminare l'influenza del contesto della conversazione

Scenari di conflitto comuni

Scenario 1: Conflitto di formattazione

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation"
→ Resolution: AGENTS.md wins (project standard)
→ Fix: Accept project standard or discuss with team

Scenario 2: Regole contraddittorie nello stesso file

AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies

Esempio di correzione:

- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance

Scenario 3: Regola troppo vaga

"Write good tests"
→ Problem: What is "good"?
→ Fix: "Generate unit tests with 80%+ coverage, include edge cases"

Strategia di debug

1. Test esplicito: chiedi a Verdent "Quale regola stai seguendo per [comportamento specifico]?"

Esempio:

You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your VERDENT.md preference for 2-space indentation."

2. Perfezionamento incrementale: aggiungi specificità alle regole ambigue

Prima:

- Use appropriate error handling

Dopo:

- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)

3. Marcatori di priorità: usa "CRITICAL:" o "REQUIRED:" per le regole non negoziabili

## Security Rules
- **CRITICAL:** Never log passwords, API keys, or tokens
- **REQUIRED:** All user inputs must be validated and sanitized
- Preferred: Use parameterized queries for database operations

Best practice per scrivere le regole

Sii specifico e direttivo:

• Usa un linguaggio chiaro e imperativo ("Usa sempre...", "Mai...", "Preferisci...")
• Evita formulazioni ambigue ("Cerca di..." → "Sempre...")
• Indica esattamente cosa vuoi, non cosa non vuoi

Bene:

- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions

Da evitare:

- Try to use modern JavaScript features
- Add comments when necessary

Organizza logicamente:

• Raggruppa le regole correlate sotto intestazioni di sezione
• Separa le competenze (stile, test, documentazione, sicurezza)
• Usa una struttura coerente tra i file di regole

Mantieni le regole gestibili:

• Scrivi regole concise (un concetto per punto)
• Rivedi e aggiorna le regole man mano che il progetto evolve
• Rimuovi tempestivamente le regole obsolete

Dai priorità alle regole importanti:

• Colloca le regole critiche all'inizio di ogni sezione
• Usa l'enfasi per gli standard non negoziabili ("MAI committare le credenziali")
• Concentrati sulle regole che prevengono bug o problemi di sicurezza

Testa l'efficacia delle regole:

• Verifica che Verdent segua le regole nella pratica
• Avvia una nuova conversazione per testare l'applicazione delle regole
• Perfeziona le regole in base al comportamento effettivo dell'agente

Bilancia dettaglio e flessibilità:

• Troppo specifico → Comportamento rigido che non si adatta
• Troppo vago → Comportamento incoerente
• Punta a una guida chiara con spazio per decisioni adeguate al contesto

Considerazioni per il team (AGENTS.md):

• Coinvolgi il team nella creazione delle regole
• Documenta la motivazione delle regole non ovvie
• Mantieni le regole del team focalizzate sugli standard condivisi, non sulle preferenze personali

Vedi anche