Extensibilidade e personalização

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

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

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

Estrutura de arquivos:

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

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

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

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

Visão geral

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:

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)

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

Exemplo:

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

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

Exemplo:

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

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

Exemplo:

# 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

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

Visão geral

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

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

Exemplo: combinando os três métodos

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

Subagente personalizado:

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

AGENTS.md (regras do projeto):

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

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

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

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

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

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

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

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