Extensibilidad y personalización

Lo que aprenderás

Cómo personalizar y ampliar Verdent for VS Code usando tres potentes métodos de extensibilidad: subagentes personalizados, sistemas de reglas e integración con MCP.

Descripción general de la extensibilidad

Verdent for VS Code ofrece tres métodos principales para ampliar sus capacidades y personalizar su comportamiento:

1. Subagentes personalizados: crea agentes de IA especializados para tareas específicas de un dominio
2. Sistema de reglas: guía el comportamiento mediante VERDENT.md, AGENTS.md y plan_rules.md
3. Integración con MCP: conecta herramientas y servicios externos a través del Model Context Protocol

Cada método responde a necesidades distintas de personalización y se puede combinar para optimizar el flujo de trabajo de forma integral.

Método 1: subagentes personalizados

Descripción general

Los subagentes personalizados son agentes de IA especializados con prompts de sistema dedicados, políticas de invocación y experiencia específica para cada tarea. Amplían los subagentes integrados de Verdent (@Verifier, @Explorer, @Code-reviewer) con capacidades específicas del proyecto.

Ubicación de almacenamiento: ~/.verdent/subagents/

Creación de subagentes personalizados

Estructura de archivos:

---
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 creación:

Método 1: menú de configuración

1. Configuración → Subagentes
2. "Crear nuevo subagente"
3. Define el nombre, la descripción y el prompt de sistema
4. Configura la política de invocación
5. Guarda en ~/.verdent/subagents/

Método 2: creación directa de archivos

1. Ve a ~/.verdent/subagents/
2. Crea un archivo markdown (por ejemplo, security-reviewer.md)
3. Agrega el frontmatter YAML
4. Escribe el prompt de sistema y las pautas de uso

Casos de uso de los subagentes personalizados

Experiencia específica de un dominio:

• Cálculos financieros: cumplimiento fiscal, regulaciones financieras
• Cumplimiento de HIPAA en el sector salud: estándares de manejo de datos de pacientes
• Criptografía: mejores prácticas de implementación de seguridad

Flujos de trabajo específicos del equipo:

• Aplicadores de estilo de código: estándares de codificación del equipo más allá de las reglas del linter
• Consistencia de la documentación: garantiza que la documentación siga las plantillas del equipo
• Auditores de dependencias: supervisan los paquetes de terceros frente a listas aprobadas

Especialistas en stacks tecnológicos:

• Optimizadores de rendimiento de React: identifican renderizados innecesarios
• Optimizadores de consultas SQL: analizan y mejoran el rendimiento de la base de datos
• Revisores de configuración de Docker: validan las prácticas de contenedorización

Aseguramiento de calidad:

• Analizadores de cobertura de pruebas: identifican rutas de código sin probar
• Revisores de manejo de errores: garantizan un manejo de excepciones completo
• Aplicadores de estándares de registro: verifican las prácticas de registro

Ejemplo: generador de documentación de 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

Ejemplo: revisor de migraciones de base de datos

---
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 invocación

Política estricta:

• El subagente solo se ejecuta cuando se solicita explícitamente mediante una @mención
• Mantienes el control total sobre la invocación
• Ideal para subagentes especializados de uso ocasional

Política flexible:

• Permite la invocación automática según la detección de patrones de tareas
• El agente principal enruta automáticamente las tareas coincidentes
• Ideal para subagentes bien definidos y de uso frecuente

Método 2: sistema de reglas

Descripción general

Los archivos de reglas son documentos Markdown que guían el comportamiento de Verdent, el formato de salida y la toma de decisiones sin necesidad de modificar el código. Tres tipos de reglas ofrecen una personalización integral:

Precedencia de las reglas

Cuando se producen conflictos:

1. AGENTS.md (más alta): las reglas del proyecto prevalecen sobre las preferencias del usuario
2. VERDENT.md (media): se aplica cuando no hay conflicto con el proyecto
3. Comportamiento predeterminado (más baja): los valores predeterminados integrados de Verdent

Ejemplo de conflicto:

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

VERDENT.md (preferencias globales)

Propósito: estilo de codificación personal y preferencias en todos los proyectos

Ejemplo:

# 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

Acceso: Configuración → Reglas → Reglas de usuario

AGENTS.md (reglas del proyecto)

Propósito: estándares de codificación para todo el equipo y convenciones específicas del proyecto

Ejemplo:

# 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

Acceso: directorio raíz del proyecto (bajo control de versiones)

plan_rules.md (personalización del plan)

Propósito: controlar el formato de salida y el nivel de detalle de Plan Mode

Ejemplo:

# 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

Acceso: Configuración → Reglas → Reglas del plan

Mejores prácticas para escribir reglas

Sé específico y directivo:

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

Organiza de forma lógica:

• Agrupa las reglas relacionadas bajo encabezados de sección
• Separa los temas (estilo, pruebas, documentación, seguridad)
• Usa una estructura coherente en todos los archivos

Prioriza las reglas críticas:

• Coloca las reglas importantes al inicio de cada sección
• Usa énfasis para los estándares no negociables: **NEVER** commit credentials
• Concéntrate en la prevención de errores y la seguridad

Comprueba la eficacia:

• Inicia una nueva conversación para verificar la aplicación de las reglas
• Refina las reglas según el comportamiento real del agente
• Actualízalas a medida que el proyecto evoluciona

Método 3: integración con MCP

Descripción general

El Model Context Protocol (MCP) amplía Verdent al conectar herramientas, fuentes de datos y servicios externos. Los servidores MCP actúan como puentes entre Verdent y los sistemas externos.

Configuración: ~/.verdent/mcp.json mediante Configuración → Servidores MCP

Capacidades de MCP

Acceso a sistemas externos:

• Herramientas de consulta de bases de datos (PostgreSQL, MySQL, MongoDB)
• APIs de servicios en la nube (AWS, Azure, GCP)
• Gestión de proyectos (Jira, Linear, Asana)
• Pipelines de CI/CD (Jenkins, GitHub Actions)
• Servicios de monitoreo (Datadog, New Relic)

Desarrollo de herramientas personalizadas: Crea servidores MCP para sistemas propietarios:

• Integraciones internas de API
• Puentes con sistemas heredados
• Fuentes de datos especializadas
• Herramientas de automatización de flujos de trabajo

MCP frente a subagentes personalizados frente a reglas

Ejemplo: combinación de los tres métodos

Escenario: equipo de desarrollo full-stack con requisitos estrictos de cumplimiento

Subagente personalizado:

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

AGENTS.md (reglas del proyecto):

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

Integración con MCP:

• Servidor MCP de base de datos de cumplimiento: verifica las operaciones frente a las reglas de cumplimiento
• Servidor MCP de registro de auditoría: registra todo el acceso a datos sensibles

Flujo de trabajo:

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

Mejores prácticas de extensibilidad

Empieza simple y escala

Adopción progresiva:

1. Fase 1: comienza con reglas básicas (VERDENT.md o AGENTS.md)
2. Fase 2: agrega subagentes personalizados para tareas especializadas repetidas
3. Fase 3: integra MCP para conexiones con sistemas externos

Combina los métodos de forma estratégica

Ejemplos de sinergia:

Reglas + subagentes:

• AGENTS.md especifica cuándo invocar subagentes personalizados
• Las reglas hacen cumplir que se sigan las recomendaciones del subagente

Reglas + MCP:

• AGENTS.md define qué servidores MCP están aprobados para su uso
• Las reglas especifican cuándo se requiere acceso a datos externos

Subagentes + MCP:

• El subagente personalizado usa herramientas MCP para acceder a sistemas externos
• El subagente interpreta los resultados de MCP con experiencia especializada

Documenta las personalizaciones

Documentación del equipo: Para subagentes personalizados y reglas del proyecto (AGENTS.md):

• Documenta la justificación de las reglas o subagentes no evidentes
• Proporciona ejemplos del uso correcto
• Incluye guías de resolución de problemas
• Mantenlos bajo control de versiones junto con el código

Documentación personal: Para VERDENT.md y subagentes personales:

• Comenta las reglas complejas explicando el razonamiento
• Mantén las reglas organizadas y actualizadas
• Elimina las reglas obsoletas con prontitud

Comprueba a fondo

Proceso de validación:

1. Crea la personalización (subagente/regla/configuración de MCP)
2. Inicia una conversación nueva para probarla
3. Verifica que el comportamiento coincida con lo esperado
4. Refina según los resultados
5. Documenta los patrones exitosos

Escenarios de prueba comunes:

• ¿El subagente se invoca automáticamente cuando se espera?
• ¿Las reglas del proyecto prevalecen correctamente sobre las del usuario?
• ¿El servidor MCP se conecta y ejecuta operaciones?
• ¿Los métodos combinados interactúan sin conflictos?

Resolución de problemas de extensibilidad

Problemas con subagentes personalizados

El subagente no se invoca:

• Verifica la política de invocación (la estricta requiere una @mención explícita)
• Comprueba que las pautas de "Cuándo usar" coincidan con tu solicitud
• Asegúrate de que el archivo esté en el directorio ~/.verdent/subagents/
• Revisa la sintaxis del frontmatter YAML

Comportamiento inesperado del subagente:

• Revisa el prompt de sistema para mayor claridad
• Refina las pautas de "Cuándo usar" y "Cuándo NO usar"
• Prueba con una @mención explícita para aislar el comportamiento
• Itera sobre el prompt de sistema según los resultados

Conflictos de reglas

La regla no se aplica:

• Verifica la precedencia de las reglas (AGENTS.md > VERDENT.md)
• Comprueba que el archivo esté en la ubicación correcta
• Inicia una nueva conversación para probar una aplicación nueva
• Haz las reglas más específicas y directivas

Comportamiento inesperado:

• Busca reglas contradictorias en el mismo archivo
• Comprueba si las reglas son demasiado vagas
• Verifica que se esté editando el archivo de reglas correcto
• Usa un lenguaje explícito ("Siempre", "Nunca", "Prefiere")

Problemas de integración con MCP

Fallos de conexión:

• Verifica la sintaxis de mcp.json
• Comprueba las credenciales de autenticación
• Asegúrate de que el servidor MCP esté en ejecución y sea accesible
• Valida la conectividad de red

Problemas de invocación de herramientas:

• Confirma que el servidor MCP exponga las herramientas esperadas
• Verifica los formatos de los parámetros de las herramientas
• Revisa los registros del servidor MCP en busca de errores
• Prueba el servidor MCP de forma independiente

Consulta también