# Extensibilidade e personalização (/pt/docs/verdent-for-vscode/advanced-features/extensibility)

> Estenda os recursos do Verdent por meio de subagentes personalizados, regras e integração com MCP



### O que você vai aprender [#o-que-você-vai-aprender]

Como personalizar e estender o Verdent for VS Code usando três poderosos métodos de extensibilidade: subagentes personalizados, sistemas de regras e integração com MCP.

***

## Visão geral da extensibilidade [#visão-geral-da-extensibilidade]

O Verdent for VS Code oferece três métodos principais para estender seus recursos e personalizar o comportamento:

1. **Subagentes personalizados** - Crie agentes de IA especializados para tarefas específicas de domínio
2. **Sistema de regras** - Oriente o comportamento por meio de VERDENT.md, AGENTS.md e plan\_rules.md
3. **Integração com MCP** - Conecte ferramentas e serviços externos via Model Context Protocol

Cada método atende a diferentes necessidades de personalização e pode ser combinado para uma otimização abrangente do fluxo de trabalho.

***

## Método 1: subagentes personalizados [#método-1-subagentes-personalizados]

### Visão geral [#visão-geral]

Subagentes personalizados são agentes de IA especializados com prompts de sistema dedicados, políticas de invocação e expertise específica para tarefas. Eles estendem os subagentes integrados do Verdent (`@Verifier`, `@Explorer`, `@Code-reviewer`) com recursos específicos do projeto.

**Local de armazenamento:** `~/.verdent/subagents/`

### Criando subagentes personalizados [#criando-subagentes-personalizados]

**Estrutura de arquivos:**

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

**Métodos de criação:**

**Método 1: menu de configurações**

1. Settings → Subagents
2. "Create new subagent"
3. Defina o nome, a descrição e o prompt de sistema
4. Configure a política de invocação
5. Salve em `~/.verdent/subagents/`

**Método 2: criação direta de arquivo**

1. Navegue até `~/.verdent/subagents/`
2. Crie um arquivo markdown (por exemplo, `security-reviewer.md`)
3. Adicione o frontmatter YAML
4. Escreva o prompt de sistema e as diretrizes de uso

### Casos de uso para subagentes personalizados [#casos-de-uso-para-subagentes-personalizados]

**Expertise específica de domínio:**

* **Cálculos financeiros:** Conformidade tributária, regulamentações financeiras
* **Conformidade HIPAA na área de saúde:** Padrões de manuseio de dados de pacientes
* **Criptografia:** Melhores práticas de implementação de segurança

**Fluxos de trabalho específicos da equipe:**

* **Aplicadores de estilo de código:** Padrões de codificação da equipe além das regras do linter
* **Consistência de documentação:** Garantir que os docs sigam os modelos da equipe
* **Auditores de dependências:** Monitorar pacotes de terceiros em relação a listas aprovadas

**Especialistas em stack de tecnologia:**

* **Otimizadores de desempenho React:** Identificar re-renderizações desnecessárias
* **Otimizadores de consultas SQL:** Analisar e melhorar o desempenho do banco de dados
* **Revisores de configuração Docker:** Validar práticas de conteinerização

**Garantia de qualidade:**

* **Analisadores de cobertura de testes:** Identificar caminhos de código não testados
* **Revisores de tratamento de erros:** Garantir tratamento abrangente de exceções
* **Aplicadores de padrões de logging:** Verificar práticas de logging

### Exemplo: gerador de documentação API [#exemplo-gerador-de-documentação-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
```

**Uso:**

```
@api-documenter document the /api/users endpoints
```

### Exemplo: revisor de migração de banco de dados [#exemplo-revisor-de-migração-de-banco-de-dados]

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

### Políticas de invocação [#políticas-de-invocação]

**Política estrita:**

* O subagente só é executado quando solicitado explicitamente via @-menção
* O usuário mantém controle total sobre a invocação
* Ideal para subagentes especializados de uso ocasional

**Política flexível:**

* Permite invocação automática com base na detecção de padrões de tarefas
* O agente principal roteia automaticamente as tarefas correspondentes
* Ideal para subagentes bem definidos e usados com frequência

***

## Método 2: sistema de regras [#método-2-sistema-de-regras]

### Visão geral [#visão-geral-1]

Os arquivos de regras são documentos Markdown que orientam o comportamento do Verdent, a formatação de saída e a tomada de decisões sem alterações de código. Três tipos de regras oferecem personalização abrangente:

| Tipo de regra      | Escopo                         | Prioridade   | Armazenamento              |
| ------------------ | ------------------------------ | ------------ | -------------------------- |
| **VERDENT.md**     | Global em todos os projetos    | Média        | `~/.verdent/VERDENT.md`    |
| **AGENTS.md**      | Específico do projeto (equipe) | Mais alta    | Diretório raiz do projeto  |
| **plan\_rules.md** | Formatação do Plan Mode        | Independente | `~/.verdent/plan_rules.md` |

### Precedência de regras [#precedência-de-regras]

Quando ocorrem conflitos:

1. **AGENTS.md** (mais alta) - As regras do projeto substituem as preferências do usuário
2. **VERDENT.md** (média) - Aplicada quando não há conflito de projeto
3. **Comportamento padrão** (mais baixa) - Os padrões integrados do Verdent

**Exemplo de conflito:**

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

### VERDENT.md (preferências globais) [#verdentmd-preferências-globais]

**Finalidade:** Estilo e preferências pessoais de codificação em todos os projetos

**Exemplo:**

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

**Acesso:** Settings → Rules → User Rules

### AGENTS.md (regras do projeto) [#agentsmd-regras-do-projeto]

**Finalidade:** Padrões de codificação de toda a equipe e convenções específicas do projeto

**Exemplo:**

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

**Acesso:** Diretório raiz do projeto (sob controle de versão)

### plan\_rules.md (personalização do plano) [#plan_rulesmd-personalização-do-plano]

**Finalidade:** Controlar o formato de saída e o nível de detalhe do Plan Mode

**Exemplo:**

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

**Acesso:** Settings → Rules → Plan Rules

### Melhores práticas para escrever regras [#melhores-práticas-para-escrever-regras]

**Seja específico e diretivo:**

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

**Organize de forma lógica:**

* Agrupe regras relacionadas sob cabeçalhos de seção
* Separe as responsabilidades (estilo, testes, documentação, segurança)
* Use uma estrutura consistente entre os arquivos

**Priorize regras críticas:**

* Coloque as regras importantes primeiro em cada seção
* Use ênfase para padrões inegociáveis: `**NEVER** commit credentials`
* Concentre-se na prevenção de bugs e na segurança

**Teste a eficácia:**

* Inicie uma nova conversa para verificar a aplicação das regras
* Refine as regras com base no comportamento real do agente
* Atualize à medida que o projeto evolui

***

## Método 3: integração com MCP [#método-3-integração-com-mcp]

### Visão geral [#visão-geral-2]

O Model Context Protocol (MCP) estende o Verdent conectando ferramentas, fontes de dados e serviços externos. Os servidores MCP atuam como pontes entre o Verdent e os sistemas externos.

**Configuração:** `~/.verdent/mcp.json` via Settings → MCP Servers

### Recursos do MCP [#recursos-do-mcp]

**Acesso a sistemas externos:**

* Ferramentas de consulta a bancos de dados (PostgreSQL, MySQL, MongoDB)
* APIs de serviços em nuvem (AWS, Azure, GCP)
* Gerenciamento de projetos (Jira, Linear, Asana)
* Pipelines de CI/CD (Jenkins, GitHub Actions)
* Serviços de monitoramento (Datadog, New Relic)

**Desenvolvimento de ferramentas personalizadas:**
Crie servidores MCP para sistemas proprietários:

* Integrações internas de API
* Pontes para sistemas legados
* Fontes de dados especializadas
* Ferramentas de automação de fluxo de trabalho

### MCP vs. subagentes personalizados vs. regras [#mcp-vs-subagentes-personalizados-vs-regras]

| Necessidade                            | Melhor método           | Por quê                                            |
| -------------------------------------- | ----------------------- | -------------------------------------------------- |
| Análise de IA especializada            | Subagente personalizado | Requer raciocínio de IA com contexto personalizado |
| Aplicação de padrões de codificação    | Regras (AGENTS.md)      | Orientação simples de comportamento                |
| Acesso a banco de dados externo        | Integração com MCP      | Requer conexão com sistema externo                 |
| Preferências pessoais de codificação   | Regras (VERDENT.md)     | Personalização global de comportamento             |
| Convenções de equipe                   | Regras (AGENTS.md)      | Padrões de projeto compartilhados                  |
| Integração com API                     | Integração com MCP      | Interação com serviço externo                      |
| Personalização do formato do plano     | Regras (plan\_rules.md) | Controle de saída do Plan Mode                     |
| Expertise de domínio (finanças, saúde) | Subagente personalizado | Aplicação de conhecimento especializado            |

### Exemplo: combinando os três métodos [#exemplo-combinando-os-três-métodos]

**Cenário:** Equipe de desenvolvimento full-stack com requisitos rígidos de conformidade

**Subagente personalizado:**

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

**AGENTS.md (regras do projeto):**

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

**Integração com MCP:**

* **Servidor MCP de banco de dados de conformidade:** Verifica operações em relação às regras de conformidade
* **Servidor MCP de log de auditoria:** Registra todos os acessos a dados sensíveis

**Fluxo de trabalho:**

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

***

## Melhores práticas de extensibilidade [#melhores-práticas-de-extensibilidade]

### Comece simples, expanda depois [#comece-simples-expanda-depois]

**Adoção progressiva:**

1. **Fase 1:** Comece com regras básicas (VERDENT.md ou AGENTS.md)
2. **Fase 2:** Adicione subagentes personalizados para tarefas especializadas repetidas
3. **Fase 3:** Integre o MCP para conexões com sistemas externos

### Combine métodos estrategicamente [#combine-métodos-estrategicamente]

**Exemplos de sinergia:**

**Regras + subagentes:**

* O AGENTS.md especifica quando invocar subagentes personalizados
* As regras impõem que as recomendações dos subagentes sejam seguidas

**Regras + MCP:**

* O AGENTS.md define quais servidores MCP são aprovados para uso
* As regras especificam quando o acesso a dados externos é necessário

**Subagentes + MCP:**

* O subagente personalizado usa ferramentas MCP para acessar sistemas externos
* O subagente interpreta os resultados do MCP com expertise especializada

### Documente as personalizações [#documente-as-personalizações]

**Documentação da equipe:**
Para subagentes personalizados e regras do projeto (AGENTS.md):

* Documente a justificativa para regras ou subagentes não óbvios
* Forneça exemplos de uso correto
* Inclua guias de solução de problemas
* Mantenha sob controle de versão junto com o código

**Documentação pessoal:**
Para VERDENT.md e subagentes pessoais:

* Comente regras complexas com o raciocínio
* Mantenha as regras organizadas e atualizadas
* Remova prontamente as regras obsoletas

### Teste minuciosamente [#teste-minuciosamente]

**Processo de validação:**

1. Crie a personalização (subagente/regra/configuração do MCP)
2. Inicie uma conversa nova para testar
3. Verifique se o comportamento corresponde às expectativas
4. Refine com base nos resultados
5. Documente os padrões bem-sucedidos

**Cenários de teste comuns:**

* O subagente é invocado automaticamente quando esperado?
* As regras do projeto substituem corretamente as regras do usuário?
* O servidor MCP se conecta e executa operações?
* Os métodos combinados interagem sem conflitos?

***

## Solução de problemas de extensibilidade [#solução-de-problemas-de-extensibilidade]

### Problemas com subagentes personalizados [#problemas-com-subagentes-personalizados]

**Subagente não está sendo invocado:**

* Verifique a política de invocação (a estrita requer @-menção explícita)
* Confirme se as diretrizes "Quando usar" correspondem à sua solicitação
* Garanta que o arquivo esteja no diretório `~/.verdent/subagents/`
* Verifique a sintaxe do frontmatter YAML

**Comportamento inesperado do subagente:**

* Revise o prompt de sistema quanto à clareza
* Refine as diretrizes "Quando usar" e "Quando NÃO usar"
* Teste com @-menção explícita para isolar o comportamento
* Itere no prompt de sistema com base nos resultados

### Conflitos de regras [#conflitos-de-regras]

**Regra não está sendo aplicada:**

* Verifique a precedência das regras (AGENTS.md > VERDENT.md)
* Confirme se o arquivo está no local correto
* Inicie uma nova conversa para testar uma aplicação nova
* Torne as regras mais específicas e diretivas

**Comportamento inesperado:**

* Procure regras contraditórias no mesmo arquivo
* Verifique se as regras estão muito vagas
* Confirme se o arquivo de regras correto está sendo editado
* Use linguagem explícita ("Sempre", "Nunca", "Prefira")

### Problemas de integração com MCP [#problemas-de-integração-com-mcp]

**Falhas de conexão:**

* Verifique a sintaxe do `mcp.json`
* Verifique as credenciais de autenticação
* Garanta que o servidor MCP esteja em execução e acessível
* Valide a conectividade de rede

**Problemas de invocação de ferramentas:**

* Confirme se o servidor MCP expõe as ferramentas esperadas
* Verifique os formatos dos parâmetros das ferramentas
* Revise os logs do servidor MCP em busca de erros
* Teste o servidor MCP de forma independente

***

## Veja também [#veja-também]

<CardGroup cols="2">
  <Card title="Gerenciamento de subagentes" icon="users" href="/docs/verdent-for-vscode/agents-rules/subagent-management">
    Guia detalhado de criação de subagentes
  </Card>

  <Card title="Sistemas de regras" icon="book" href="/docs/verdent-for-vscode/agents-rules/rule-systems">
    Documentação completa de regras
  </Card>

  <Card title="Integração com MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    Configuração e instalação do MCP
  </Card>

  <Card title="Referência de ferramentas" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference">
    Recursos das ferramentas integradas
  </Card>
</CardGroup>