--- title: Extensibilidad y personalización description: Amplía las capacidades de Verdent mediante subagentes personalizados, reglas e integración con MCP --- ### 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:** ```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 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 ```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 ``` ### Ejemplo: revisor de migraciones de base de datos ```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 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: | Tipo de regla | Alcance | Prioridad | Almacenamiento | |-----------|-------|----------|---------| | **VERDENT.md** | Global en todos los proyectos | Media | `~/.verdent/VERDENT.md` | | **AGENTS.md** | Específico del proyecto (equipo) | Más alta | Directorio raíz del proyecto | | **plan_rules.md** | Formato de Plan Mode | Independiente | `~/.verdent/plan_rules.md` | ### 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:** ```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 ``` **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:** ```markdown # AGENTS.md ## Dev environment tips - Use `pnpm dlx turbo run where ` to navigate - Run `pnpm install --filter ` for dependencies - Check package.json name field for correct package name ## Testing instructions - Run `pnpm turbo run test --filter ` - From package root: `pnpm test` - Focus on one test: `pnpm vitest run -t ""` - Fix all errors before merge ## PR instructions - Title format: [] - 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:** ```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 ``` **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 | Necesidad | Mejor método | Por qué | |------|-------------|-----| | Análisis especializado con IA | Subagente personalizado | Requiere razonamiento de IA con contexto personalizado | | Aplicación de estándares de codificación | Reglas (AGENTS.md) | Guía de comportamiento simple | | Acceso a bases de datos externas | Integración con MCP | Requiere conexión con un sistema externo | | Preferencias personales de codificación | Reglas (VERDENT.md) | Personalización global del comportamiento | | Convenciones del equipo | Reglas (AGENTS.md) | Estándares compartidos del proyecto | | Integración con API | Integración con MCP | Interacción con servicios externos | | Personalización del formato del plan | Reglas (plan_rules.md) | Control de salida de Plan Mode | | Experiencia de dominio (finanzas, salud) | Subagente personalizado | Aplicación de conocimiento especializado | ### Ejemplo: combinación de los tres métodos **Escenario:** equipo de desarrollo full-stack con requisitos estrictos de cumplimiento **Subagente personalizado:** ```markdown --- name: compliance-auditor description: Audits code for regulatory compliance (SOC2, HIPAA) --- [System prompt for compliance checking] ``` **AGENTS.md (reglas del proyecto):** ```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 ``` **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 <CardGroup cols={2}> <Card title="Gestión de subagentes" icon="users" href="/docs/verdent-for-vscode/agents-rules/subagent-management"> Guía detallada de creación de subagentes </Card> <Card title="Sistemas de reglas" icon="book" href="/docs/verdent-for-vscode/agents-rules/rule-systems"> Documentación completa de reglas </Card> <Card title="Integración con MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp"> Configuración e instalación de MCP </Card> <Card title="Referencia de herramientas" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference"> Capacidades de las herramientas integradas </Card> </CardGroup>