Estensibilità e personalizzazione

Cosa imparerai

Come personalizzare ed estendere Verdent for VS Code usando tre potenti metodi di estensibilità: sottoagenti personalizzati, sistemi di regole e integrazione MCP.

Panoramica sull'estensibilità

Verdent for VS Code offre tre metodi principali per estendere le sue funzionalità e personalizzarne il comportamento:

1. Sottoagenti personalizzati - Crea agenti AI specializzati per attività specifiche di dominio
2. Sistema di regole - Guida il comportamento tramite VERDENT.md, AGENTS.md e plan_rules.md
3. Integrazione MCP - Collega strumenti e servizi esterni tramite Model Context Protocol

Ogni metodo risponde a esigenze di personalizzazione diverse e può essere combinato per un'ottimizzazione completa del flusso di lavoro.

Metodo 1: sottoagenti personalizzati

Panoramica

I sottoagenti personalizzati sono agenti AI specializzati con prompt di sistema dedicati, criteri di invocazione ed esperienza specifica per determinate attività. Estendono i sottoagenti integrati di Verdent (@Verifier, @Explorer, @Code-reviewer) con funzionalità specifiche del progetto.

Posizione di archiviazione: ~/.verdent/subagents/

Creare sottoagenti personalizzati

Struttura dei file:

---
name: subagent-name
description: One-line purpose description
---
# System Prompt

[Behavior definition, personality, task interpretation approach]

Invocation policy (strict|flexible): Policy description

When to use:
- Scenario 1
- Scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2

Metodi di creazione:

Metodo 1: menu delle impostazioni

1. Settings → Subagents
2. "Create new subagent"
3. Definisci nome, descrizione e prompt di sistema
4. Configura i criteri di invocazione
5. Salva in ~/.verdent/subagents/

Metodo 2: creazione diretta del file

1. Vai in ~/.verdent/subagents/
2. Crea un file markdown (ad esempio security-reviewer.md)
3. Aggiungi il frontmatter YAML
4. Scrivi il prompt di sistema e le linee guida d'uso

Casi d'uso per i sottoagenti personalizzati

Competenze specifiche di dominio:

• Calcoli finanziari: conformità fiscale, normative finanziarie
• Conformità HIPAA in ambito sanitario: standard per la gestione dei dati dei pazienti
• Crittografia: best practice per l'implementazione della sicurezza

Flussi di lavoro specifici del team:

• Applicatori di stile del codice: standard di codifica del team oltre alle regole del linter
• Coerenza della documentazione: garantire che la documentazione segua i modelli del team
• Auditor delle dipendenze: monitorare i pacchetti di terze parti rispetto agli elenchi approvati

Specialisti dello stack tecnologico:

• Ottimizzatori delle prestazioni di React: individuare i re-render non necessari
• Ottimizzatori delle query SQL: analizzare e migliorare le prestazioni del database
• Revisori della configurazione Docker: validare le pratiche di containerizzazione

Garanzia di qualità:

• Analizzatori della copertura dei test: individuare i percorsi di codice non testati
• Revisori della gestione degli errori: garantire una gestione completa delle eccezioni
• Applicatori degli standard di logging: verificare le pratiche di logging

Esempio: generatore di documentazione API

---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt

You are an API documentation specialist.

Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides

When NOT to use:
- Inline code comments
- User-facing documentation

Utilizzo:

@api-documenter document the /api/users endpoints

Esempio: revisore delle migrazioni del database

---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt

You are a database migration safety specialist.

Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables

Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures

When NOT to use:
- Schema design from scratch
- Query optimization

Criteri di invocazione

Criterio rigido:

• Il sottoagente viene eseguito solo quando richiesto esplicitamente tramite @-menzione
• L'utente mantiene il pieno controllo sull'invocazione
• Ideale per sottoagenti specializzati e a uso occasionale

Criterio flessibile:

• Consente l'invocazione automatica basata sul rilevamento di pattern nelle attività
• L'agente principale instrada automaticamente le attività corrispondenti
• Ideale per sottoagenti usati di frequente e ben definiti

Metodo 2: sistema di regole

Panoramica

I file di regole sono documenti Markdown che guidano il comportamento di Verdent, la formattazione dell'output e il processo decisionale senza modifiche al codice. Tre tipi di regole offrono una personalizzazione completa:

Precedenza delle regole

In caso di conflitti:

1. AGENTS.md (massima) - Le regole del progetto prevalgono sulle preferenze utente
2. VERDENT.md (media) - Applicata quando non c'è conflitto con il progetto
3. Comportamento predefinito (minima) - Le impostazioni predefinite integrate di Verdent

Esempio di conflitto:

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

VERDENT.md (preferenze globali)

Scopo: stile di codifica e preferenze personali su tutti i progetti

Esempio:

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases
- Include return types on all functions

## 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

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

Accesso: Settings → Rules → User Rules

AGENTS.md (regole del progetto)

Scopo: standard di codifica a livello di team e convenzioni specifiche del progetto

Esempio:

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to navigate
- Run `pnpm install --filter <project_name>` for dependencies
- Check package.json name field for correct package name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- 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

Accesso: directory radice del progetto (sotto controllo di versione)

plan_rules.md (personalizzazione dei piani)

Scopo: controllare il formato dell'output e il livello di dettaglio di Plan Mode

Esempio:

# Plan Rules

## 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

Accesso: Settings → Rules → Plan Rules

Best practice per scrivere le regole

Sii specifico e direttivo:

✓ Good: "Always use async/await for asynchronous operations"
✗ Vague: "Try to use modern JavaScript"

Organizza in modo logico:

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

Dai priorità alle regole critiche:

• Metti le regole importanti per prime in ogni sezione
• Usa l'enfasi per gli standard non negoziabili: **NEVER** commit credentials
• Concentrati sulla prevenzione dei bug e sulla sicurezza

Verifica l'efficacia:

• Avvia una nuova conversazione per verificare l'applicazione delle regole
• Perfeziona le regole in base al comportamento effettivo dell'agente
• Aggiorna man mano che il progetto evolve

Metodo 3: integrazione MCP

Panoramica

Model Context Protocol (MCP) estende Verdent collegando strumenti, fonti di dati e servizi esterni. I server MCP fungono da ponte tra Verdent e i sistemi esterni.

Configurazione: ~/.verdent/mcp.json tramite Settings → MCP Servers

Funzionalità di MCP

Accesso a sistemi esterni:

• Strumenti di query per database (PostgreSQL, MySQL, MongoDB)
• API di servizi cloud (AWS, Azure, GCP)
• Gestione dei progetti (Jira, Linear, Asana)
• Pipeline CI/CD (Jenkins, GitHub Actions)
• Servizi di monitoraggio (Datadog, New Relic)

Sviluppo di strumenti personalizzati: Crea server MCP per sistemi proprietari:

• Integrazioni con API interne
• Ponti verso sistemi legacy
• Fonti di dati specializzate
• Strumenti di automazione dei flussi di lavoro

MCP vs. sottoagenti personalizzati vs. regole

Esempio: combinare tutti e tre i metodi

Scenario: team di sviluppo full-stack con requisiti di conformità rigorosi

Sottoagente personalizzato:

---
name: compliance-auditor
description: Audits code for regulatory compliance (SOC2, HIPAA)
---
[System prompt for compliance checking]

AGENTS.md (regole del progetto):

## Security Standards
- All API endpoints must validate inputs
- Never log PII or credentials
- Encrypt sensitive data at rest and in transit

## Compliance
- Run @compliance-auditor before all PRs
- Document data retention policies in code comments
- Include audit trails for data access

Integrazione MCP:

• Server MCP del database di conformità: verifica le operazioni rispetto alle regole di conformità
• Server MCP del log di audit: registra ogni accesso a dati sensibili

Flusso di lavoro:

User: "Create endpoint for user profile updates"
Verdent: [Applies AGENTS.md rules]
         [Generates secure endpoint with validation]
         [Automatically invokes @compliance-auditor]
         [Uses MCP to log operation in audit system]
         Result: Compliant, secure, audited endpoint

Best practice per l'estensibilità

Inizia in modo semplice e cresci gradualmente

Adozione progressiva:

1. Fase 1: inizia con regole di base (VERDENT.md o AGENTS.md)
2. Fase 2: aggiungi sottoagenti personalizzati per attività specializzate ricorrenti
3. Fase 3: integra MCP per le connessioni a sistemi esterni

Combina i metodi in modo strategico

Esempi di sinergia:

Regole + sottoagenti:

• AGENTS.md specifica quando invocare i sottoagenti personalizzati
• Le regole impongono che i suggerimenti dei sottoagenti vengano seguiti

Regole + MCP:

• AGENTS.md definisce quali server MCP sono approvati per l'uso
• Le regole specificano quando è richiesto l'accesso a dati esterni

Sottoagenti + MCP:

• Il sottoagente personalizzato usa gli strumenti MCP per accedere a sistemi esterni
• Il sottoagente interpreta i risultati di MCP con competenze specializzate

Documenta le personalizzazioni

Documentazione del team: Per i sottoagenti personalizzati e le regole di progetto (AGENTS.md):

• Documenta le motivazioni delle regole o dei sottoagenti non ovvi
• Fornisci esempi di utilizzo corretto
• Includi guide alla risoluzione dei problemi
• Metti sotto controllo di versione insieme al codice

Documentazione personale: Per VERDENT.md e i sottoagenti personali:

• Commenta le regole complesse spiegandone il motivo
• Mantieni le regole organizzate e aggiornate
• Rimuovi tempestivamente le regole obsolete

Verifica a fondo

Processo di validazione:

1. Crea la personalizzazione (sottoagente/regola/configurazione MCP)
2. Avvia una nuova conversazione per testare
3. Verifica che il comportamento corrisponda alle aspettative
4. Perfeziona in base ai risultati
5. Documenta i pattern efficaci

Scenari di test comuni:

• Il sottoagente si invoca automaticamente quando previsto?
• Le regole del progetto prevalgono correttamente sulle regole utente?
• Il server MCP si connette ed esegue le operazioni?
• I metodi combinati interagiscono senza conflitti?

Risoluzione dei problemi di estensibilità

Problemi con i sottoagenti personalizzati

Il sottoagente non si invoca:

• Controlla i criteri di invocazione (il criterio rigido richiede una @-menzione esplicita)
• Verifica che le linee guida "When to use" corrispondano alla tua richiesta
• Assicurati che il file sia nella directory ~/.verdent/subagents/
• Controlla la sintassi del frontmatter YAML

Comportamento inaspettato del sottoagente:

• Rivedi il prompt di sistema per verificarne la chiarezza
• Perfeziona le linee guida "When to use" e "When NOT to use"
• Testa con una @-menzione esplicita per isolare il comportamento
• Itera sul prompt di sistema in base ai risultati

Conflitti tra regole

La regola non viene applicata:

• Controlla la precedenza delle regole (AGENTS.md > VERDENT.md)
• Verifica che il file sia nella posizione corretta
• Avvia una nuova conversazione per testare un'applicazione pulita
• Rendi le regole più specifiche e direttive

Comportamento inaspettato:

• Cerca regole contraddittorie nello stesso file
• Verifica se le regole sono troppo vaghe
• Verifica di modificare il file di regole corretto
• Usa un linguaggio esplicito ("Always", "Never", "Prefer")

Problemi di integrazione MCP

Errori di connessione:

• Verifica la sintassi di mcp.json
• Controlla le credenziali di autenticazione
• Assicurati che il server MCP sia in esecuzione e accessibile
• Valida la connettività di rete

Problemi di invocazione degli strumenti:

• Conferma che il server MCP esponga gli strumenti previsti
• Controlla i formati dei parametri degli strumenti
• Rivedi i log del server MCP per eventuali errori
• Testa il server MCP in modo indipendente

Vedi anche