# Estensibilità e personalizzazione (/it/docs/verdent-for-vscode/advanced-features/extensibility)

> Estendi le funzionalità di Verdent tramite sottoagenti personalizzati, regole e integrazione MCP



### Cosa imparerai [#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à [#panoramica-sullestensibilità]

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 [#metodo-1-sottoagenti-personalizzati]

### Panoramica [#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 [#creare-sottoagenti-personalizzati]

**Struttura dei file:**

```markdown
---
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 [#casi-duso-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 [#esempio-generatore-di-documentazione-api]

```markdown
---
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 [#esempio-revisore-delle-migrazioni-del-database]

```markdown
---
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 [#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 [#metodo-2-sistema-di-regole]

### Panoramica [#panoramica-1]

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:

| Tipo di regola     | Ambito                        | Priorità     | Archiviazione                 |
| ------------------ | ----------------------------- | ------------ | ----------------------------- |
| **VERDENT.md**     | Globale su tutti i progetti   | Media        | `~/.verdent/VERDENT.md`       |
| **AGENTS.md**      | Specifico del progetto (team) | Massima      | Directory radice del progetto |
| **plan\_rules.md** | Formattazione di Plan Mode    | Indipendente | `~/.verdent/plan_rules.md`    |

### Precedenza delle regole [#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) [#verdentmd-preferenze-globali]

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

**Esempio:**

```markdown
# 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) [#agentsmd-regole-del-progetto]

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

**Esempio:**

```markdown
# 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) [#plan_rulesmd-personalizzazione-dei-piani]

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

**Esempio:**

```markdown
# 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 [#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 [#metodo-3-integrazione-mcp]

### Panoramica [#panoramica-2]

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 [#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 [#mcp-vs-sottoagenti-personalizzati-vs-regole]

| Esigenza                                | Metodo migliore            | Perché                                               |
| --------------------------------------- | -------------------------- | ---------------------------------------------------- |
| Analisi AI specializzata                | Sottoagente personalizzato | Richiede ragionamento AI con contesto personalizzato |
| Applicazione degli standard di codifica | Regole (AGENTS.md)         | Semplice guida al comportamento                      |
| Accesso a database esterni              | Integrazione MCP           | Richiede la connessione a un sistema esterno         |
| Preferenze di codifica personali        | Regole (VERDENT.md)        | Personalizzazione globale del comportamento          |
| Convenzioni del team                    | Regole (AGENTS.md)         | Standard di progetto condivisi                       |
| Integrazione con API                    | Integrazione MCP           | Interazione con servizi esterni                      |
| Personalizzazione del formato dei piani | Regole (plan\_rules.md)    | Controllo dell'output di Plan Mode                   |
| Competenze di dominio (finanza, sanità) | Sottoagente personalizzato | Applicazione di conoscenze specializzate             |

### Esempio: combinare tutti e tre i metodi [#esempio-combinare-tutti-e-tre-i-metodi]

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

**Sottoagente personalizzato:**

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

**AGENTS.md (regole del progetto):**

```markdown
## 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à [#best-practice-per-lestensibilità]

### Inizia in modo semplice e cresci gradualmente [#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 [#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 [#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 [#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à [#risoluzione-dei-problemi-di-estensibilità]

### Problemi con i sottoagenti personalizzati [#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 [#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 [#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 [#vedi-anche]

<CardGroup cols="2">
  <Card title="Gestione dei sottoagenti" icon="users" href="/docs/verdent-for-vscode/agents-rules/subagent-management">
    Guida dettagliata alla creazione dei sottoagenti
  </Card>

  <Card title="Sistemi di regole" icon="book" href="/docs/verdent-for-vscode/agents-rules/rule-systems">
    Documentazione completa sulle regole
  </Card>

  <Card title="Integrazione MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    Configurazione e impostazione di MCP
  </Card>

  <Card title="Riferimento degli strumenti" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference">
    Funzionalità degli strumenti integrati
  </Card>
</CardGroup>