Sistemas de reglas y guía de comportamiento

Los archivos de reglas son documentos Markdown que definen cómo se comporta y responde Verdent durante las sesiones de programación. Guían el comportamiento del agente de IA, el formato de salida, la toma de decisiones y el cumplimiento de los estándares del proyecto.

Propósito: Las reglas te permiten personalizar el comportamiento de Verdent sin cambiar el código ni la configuración. Establecen convenciones de programación, patrones preferidos, estilo de comunicación y preferencias de ejecución de tareas que persisten entre sesiones.

Cómo funcionan las reglas: Verdent consulta continuamente los archivos de reglas durante las conversaciones, aplicando directrices a la generación de código, el análisis, la documentación y la toma de decisiones. Las reglas influyen en cada respuesta del agente para garantizar la coherencia con tus preferencias.

Tres categorías:

• Preferencias globales (VERDENT.md): estilo de programación personal, preferencias de idioma
• Estándares específicos del proyecto (AGENTS.md): convenciones del equipo, patrones arquitectónicos
• Personalización de planes (Plan.md): formato y contenido de salida de Plan Mode

Precedencia de reglas: Cuando las reglas entran en conflicto, Verdent aplica la siguiente precedencia: AGENTS.md (más alta) → VERDENT.md (media) → valores predeterminados (más baja)

Reglas de usuario (VERDENT.md)

VERDENT.md define las preferencias globales que se aplican a todos los proyectos y sesiones. Establece el estilo de programación personal, las herramientas preferidas, las preferencias de comunicación y los comportamientos predeterminados.

Ubicación y alcance

Ubicación del archivo: ~/.verdent/VERDENT.md

Alcance: global para todos los proyectos

Acceso:

• Settings → Rules → User Rules
• Edición directa del archivo en ~/.verdent/VERDENT.md

Cuándo surten efecto los cambios: Las reglas se aplican de inmediato en las nuevas conversaciones e influyen en las respuestas de la conversación actual.

Casos de uso

Formato y sintaxis

VERDENT.md usa formato Markdown simple con viñetas o listas numeradas.

Estructura:

# User Rules

## Code Style Preferences
- Always use TypeScript strict mode
- Prefer functional components in React
- Include JSDoc comments for exported functions

## Documentation
- Add JSDoc comments for all exported functions
- Include usage examples in component documentation

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

Estilo de escritura:

• Usa un lenguaje claro y directivo ("Usa siempre...", "Prefiere...", "Nunca...")
• Organiza el contenido en secciones lógicas con encabezados
• Usa viñetas para reglas individuales
• Sé específico sobre el comportamiento deseado

Ejemplos por tipo de desarrollador

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases for object shapes
- Include return types on all functions
- Use const assertions where appropriate

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

# User Rules

## Python Style
- Follow PEP 8 conventions
- Use type hints for function signatures
- Prefer list comprehensions over map/filter

## Data Analysis
- Use pandas for data manipulation
- Include DataFrame.head() after transformations
- Document assumptions about data

## Output Format
- Show shape and info() after operations
- Include visualization examples

# User Rules

## JavaScript Preferences
- Use ES6+ features (arrow functions, destructuring)
- Async/await over promises
- Template literals for string interpolation

## Testing
- Jest for unit tests
- Include test cases for edge conditions
- Aim for 80%+ code coverage

## Code Review
- Flag potential performance issues
- Suggest security improvements

# User Rules

## Communication
- Always respond in French
- Use technical English terms when no French equivalent exists
- Provide French variable/function names when appropriate

## Code Comments
- Write comments in French
- Documentation in both French and English

# User Rules

## Code Style
- Minimal comments - code should be self-documenting
- Short, focused functions (< 20 lines)
- Avoid unnecessary abstractions

## Output Preferences
- Brief explanations
- Show code first, explain after
- No verbose documentation unless requested

Cómo crear y editar

Reglas de proyecto (AGENTS.md)

AGENTS.md define reglas específicas del proyecto que controlan el comportamiento del agente para el proyecto actual. Establece estándares de programación del equipo, patrones arquitectónicos, requisitos de pruebas y flujos de trabajo de desarrollo específicos del proyecto.

Ubicación y alcance

Ubicación del archivo: directorio raíz del proyecto

Alcance: solo el proyecto actual

Control de versiones: se puede subir a git para compartirlo con todo el equipo

Acceso:

• Settings → Rules → Project Rules
• Edición directa en <project-root>/AGENTS.md

Casos de uso

Colaboración en equipo: AGENTS.md se almacena en la raíz del proyecto y se puede subir al control de versiones, lo que garantiza que todos los miembros del equipo trabajen con un comportamiento coherente del agente.

Formato y sintaxis

AGENTS.md usa formato Markdown con secciones estructuradas y viñetas, similar a VERDENT.md pero centrado en los requisitos específicos del proyecto.

Estructura:

# AGENTS.md

## Dev environment tips
- Command for navigating workspace
- Installation commands
- Environment setup instructions

## Testing instructions
- Test execution commands
- Coverage requirements
- CI/CD integration details

## PR instructions
- Title format requirements
- Pre-commit checklist
- Review guidelines

Estilo de escritura:

• Lenguaje imperativo y directivo
• Organizado por área de flujo de trabajo (desarrollo, pruebas, despliegue)
• Comandos y procedimientos específicos
• Estándares de todo el equipo, no preferencias personales

Ejemplos por tipo de proyecto

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add package to workspace
- Check the name field in package.json to confirm the right name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>` for all checks
- 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

# AGENTS.md

## Code Standards
- Use functional components with hooks
- TypeScript strict mode required
- Named exports only (no default exports)
- PropTypes or TypeScript interfaces for all components

## File Organization
- One component per file
- Components in `src/components/`
- Hooks in `src/hooks/`
- Utils in `src/utils/`

## Testing
- Jest + React Testing Library
- Test all user interactions
- 80%+ coverage required

# AGENTS.md

## API Standards
- All endpoints include input validation
- Use async/await for asynchronous operations
- Consistent error format: { error: string, code: number }
- Rate limiting on public endpoints

## Security
- Never log sensitive data (passwords, tokens, PII)
- Parameterized queries only (prevent SQL injection)
- Validate and sanitize all inputs

## Testing
- Unit tests for all business logic
- Integration tests for API endpoints
- Test success and error cases

# AGENTS.md

## Platform Support
- iOS 14+ and Android API 26+
- React Native 0.72+
- Test on both platforms before PR

## State Management
- Use Redux Toolkit
- Async operations with Redux Thunk
- Normalize state shape

## Performance
- Images: WebP format, max 500KB
- Bundle size: monitor with bundle analyzer
- FlatList for long lists (>20 items)

# AGENTS.md

## Django Conventions
- Follow Django best practices and PEP 8
- Class-based views preferred
- Django ORM for database operations
- Migrations: never edit generated files

## Testing
- pytest-django for all tests
- Factory Boy for test fixtures
- Coverage must be 90%+

## Deployment
- Docker compose for local development
- Environment variables in .env (never committed)
- Run migrations before deployment

Diferencias respecto a VERDENT.md

Alcance:

• VERDENT.md: preferencias personales en todos los proyectos
• AGENTS.md: estándares del equipo solo para un proyecto específico

Prioridad:

• AGENTS.md: mayor precedencia: anula las reglas de usuario para mantener la coherencia del proyecto
• VERDENT.md: menor precedencia: se aplica cuando no hay conflicto con una regla del proyecto

Enfoque del contenido:

• VERDENT.md: estilo de programación individual, preferencias de comunicación, herramientas personales
• AGENTS.md: convenciones del equipo, arquitectura del proyecto, flujos de trabajo compartidos, pila tecnológica

Control de versiones:

• VERDENT.md: no se comparte: permanece en el equipo de cada persona
• AGENTS.md: se sube a git: se comparte con todo el equipo

Almacenamiento:

• VERDENT.md: ~/.verdent/VERDENT.md (global)
• AGENTS.md: directorio raíz del proyecto (específico del proyecto)

Ejemplo de resolución de conflictos:

VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)

Cuándo usar cada uno:

• VERDENT.md: preferencias personales que quieres en todos los proyectos
• AGENTS.md: estándares que todo el equipo debe seguir para este proyecto

Reglas de plan (Plan.md)

Plan.md personaliza el contenido y el formato de los planes generados en Plan Mode. Controla el nivel de detalle del plan, las secciones incluidas, las preferencias de formato y la información mostrada.

Ubicación y alcance

Ubicación del archivo: ~/.verdent/plan_settings.json

Alcance: global para todos los proyectos

Aplicación: solo se aplica durante Plan Mode al generar planes

Acceso:

• Settings → Rules → Plan Rules
• Edición directa del archivo en ~/.verdent/plan_settings.json

Casos de uso

Formato y sintaxis

Plan.md usa formato Markdown con secciones que describen la estructura y el contenido deseados del plan.

Estructura:

---
name: Plan Rules
version: 1.0.0
last_updated: 2025-11-26
---

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

Ejemplos por estilo de planificación

---
name: Detailed Technical
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Executive summary (2-3 sentences)
- Prerequisites and dependencies
- Numbered implementation steps
- Testing and verification strategy
- Rollback procedures

## Level of Detail
- Break into 20-30 minute tasks
- Specific file paths for all modifications
- Function signatures for new code
- Database schema changes with migration steps

## Format
- Numbered lists for sequence
- Code blocks for complex logic
- Diagrams for architecture changes (describe verbally)

---
name: High-Level Strategic
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Brief overview (1 paragraph)
- Major phases only (3-5 high-level steps)
- Key decisions and trade-offs
- Success criteria

## Level of Detail
- High-level phases (1-2 hours each)
- Avoid implementation specifics
- Focus on approach and strategy

## Format
- Bullet points for flexibility
- Minimal code examples
- Emphasize "why" over "how"

---
name: Time-Conscious
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Time estimates for each step
- Total project duration estimate
- Parallel tasks identified
- Critical path highlighted

## Level of Detail
- Tasks sized to 30-minute increments
- Dependencies clearly marked
- Blocking operations identified

## Format
- Include time estimates inline
- Mark parallel tasks
- Highlight critical path with bold

---
name: Risk-Focused
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Risk assessment for each phase
- Mitigation strategies included
- Rollback procedures defined
- Testing requirements emphasized

## Level of Detail
- Identify potential failure points
- Document error handling approach
- Include recovery procedures

## Format
- Risk levels: low, medium, high
- Separate "Risks" section for each phase
- Mitigation steps in sub-bullets

---
name: Team Collaboration
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Role assignments for each task
- Coordination points identified
- Review checkpoints included
- Communication requirements

## Level of Detail
- Specify who handles each component
- List integration points between team members
- Include pair programming opportunities

## Format
- Use mentions for role assignments
- Mark collaboration points
- Include "Review required" markers

¿Cuándo se aplican las reglas de plan?

Aplicación de las reglas de plan:

• Momento: solo se aplican durante Plan Mode al generar planes
• Alcance: controla el formato y el contenido del plan, no la generación de código
• Independencia: no entra en conflicto con VERDENT.md ni AGENTS.md

Aplicación de otros tipos de reglas:

• VERDENT.md: se aplica continuamente en todos los modos (Agent, Plan, Chat)
• AGENTS.md: se aplica continuamente en todos los modos para el comportamiento específico del proyecto

Ejemplo de interacción:

Plan Mode activated:
1. VERDENT.md: "Use TypeScript" → Applied to code in plan
2. AGENTS.md: "Follow project conventions" → Applied to approach
3. plan_rules.md: "Include time estimates" → Applied to plan format
→ Result: Plan shows TypeScript code following project conventions with time estimates

Comportamiento específico de cada modo:

• Agent Mode: se aplican VERDENT.md + AGENTS.md (sin plan_rules.md)
• Plan Mode: se aplican VERDENT.md + AGENTS.md + Plan.md
• Chat Mode: se aplican VERDENT.md + AGENTS.md (sin Plan.md)

Precedencia de reglas y resolución de conflictos

Cuando las reglas entran en conflicto, Verdent aplica una precedencia para garantizar un comportamiento coherente.

Orden de precedencia

1. Reglas de proyecto (AGENTS.md): máxima prioridad Las reglas específicas del proyecto anulan las preferencias globales. Los estándares del equipo tienen prioridad sobre las preferencias individuales para mantener la coherencia.

2. Reglas de usuario (VERDENT.md): prioridad media Las preferencias globales se aplican cuando no hay conflicto con una regla específica del proyecto.

3. Comportamiento predeterminado: prioridad más baja Los valores predeterminados integrados de Verdent se aplican cuando no se especifica ninguna regla.

Ejemplo de resolución de conflictos:

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

Reglas de plan: Plan.md se aplica de forma independiente durante Plan Mode y no entra en conflicto con las reglas de usuario o proyecto. Controla el formato del plan, mientras que VERDENT.md y AGENTS.md controlan el estilo de código dentro del plan.

Solución de conflictos de reglas

Cuando observes un comportamiento inesperado que contradice una regla, sigue esta estrategia de depuración:

Paso 1: Identifica el conflicto

1. Observa el comportamiento inesperado que contradice una regla
2. Verifica qué reglas podrían aplicarse a la situación
3. Busca contradicciones entre los archivos de reglas

Paso 2: Verifica la precedencia de reglas

AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)

Las reglas de proyecto anulan las preferencias personales.

Paso 3: Prueba de forma aislada

Desactiva VERDENT.md: Renombra o vacía temporalmente el archivo y prueba si se resuelve el conflicto.

Prueba sin AGENTS.md: Trabaja en el proyecto sin AGENTS.md para aislar el comportamiento de las reglas de usuario.

Nueva conversación: Inicia una sesión nueva para eliminar la influencia del contexto de la conversación.

Escenarios de conflicto comunes

Escenario 1: conflicto de formato

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation"
→ Resolution: AGENTS.md wins (project standard)
→ Fix: Accept project standard or discuss with team

Escenario 2: reglas contradictorias en el mismo archivo

AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies

Ejemplo de corrección:

- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance

Escenario 3: regla demasiado vaga

"Write good tests"
→ Problem: What is "good"?
→ Fix: "Generate unit tests with 80%+ coverage, include edge cases"

Estrategia de depuración

1. Prueba explícita: Pregúntale a Verdent "¿Qué regla estás siguiendo para [comportamiento específico]?"

Ejemplo:

You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your VERDENT.md preference for 2-space indentation."

2. Refinamiento incremental: Agrega especificidad a las reglas ambiguas.

Antes:

- Use appropriate error handling

Después:

- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)

3. Marcadores de prioridad: Usa "CRITICAL:" o "REQUIRED:" para reglas no negociables.

## Security Rules
- **CRITICAL:** Never log passwords, API keys, or tokens
- **REQUIRED:** All user inputs must be validated and sanitized
- Preferred: Use parameterized queries for database operations

Mejores prácticas para escribir reglas

Sé específico y directivo:

• Usa un lenguaje claro e imperativo ("Usa siempre...", "Nunca...", "Prefiere...")
• Evita formulaciones ambiguas ("Intenta..." → "Siempre...")
• Indica exactamente lo que quieres, no lo que no quieres

Bien:

- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions

Evita:

- Try to use modern JavaScript features
- Add comments when necessary

Organiza de forma lógica:

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

Mantén las reglas fáciles de mantener:

• Escribe reglas concisas (un concepto por viñeta)
• Revisa y actualiza las reglas a medida que el proyecto evoluciona
• Elimina las reglas obsoletas con prontitud

Prioriza las reglas importantes:

• Coloca las reglas críticas primero en cada sección
• Usa énfasis para los estándares no negociables ("NUNCA subas credenciales")
• Céntrate en las reglas que previenen errores o problemas de seguridad

Prueba la eficacia de las reglas:

• Verifica que Verdent siga las reglas en la práctica
• Inicia una nueva conversación para probar la aplicación de las reglas
• Refina las reglas según el comportamiento real del agente

Equilibra el detalle y la flexibilidad:

• Demasiado específico → comportamiento rígido que no se adapta
• Demasiado vago → comportamiento inconsistente
• Apunta a una orientación clara con margen para decisiones adecuadas al contexto

Consideraciones para el equipo (AGENTS.md):

• Involucra al equipo en la creación de reglas
• Documenta la justificación de las reglas no obvias
• Mantén las reglas del equipo centradas en los estándares compartidos, no en las preferencias personales

Consulta también