Sistemas de regras e orientação de comportamento

Arquivos de regras são documentos Markdown que definem como o Verdent se comporta e responde durante as sessões de codificação. Eles orientam o comportamento do agente de IA, a formatação da saída, a tomada de decisões e a aderência aos padrões do projeto.

Objetivo: As regras permitem que você personalize o comportamento do Verdent sem alterar código ou configurações. Elas estabelecem convenções de codificação, padrões preferidos, estilo de comunicação e preferências de execução de tarefas que persistem entre as sessões.

Como as regras funcionam: O Verdent consulta continuamente os arquivos de regras durante as conversas, aplicando diretrizes à geração de código, análise, documentação e tomada de decisões. As regras influenciam todas as respostas do agente para garantir consistência com as preferências do usuário.

Três categorias:

• Preferências globais (VERDENT.md) - Estilo pessoal de codificação, preferências de idioma
• Padrões específicos do projeto (AGENTS.md) - Convenções da equipe, padrões arquiteturais
• Personalização de plano (Plan.md) - Formato e conteúdo da saída do Plan Mode

Precedência de regras: Quando as regras entram em conflito, o Verdent aplica a seguinte precedência: AGENTS.md (mais alta) → VERDENT.md (média) → padrões (mais baixa)

Regras do usuário (VERDENT.md)

O VERDENT.md define preferências globais que se aplicam a todos os projetos e sessões. Ele estabelece o estilo pessoal de codificação, ferramentas preferidas, preferências de comunicação e comportamentos padrão.

Localização e escopo

Localização do arquivo: ~/.verdent/VERDENT.md

Escopo: Global para todos os projetos

Acesso:

• Settings → Rules → User Rules
• Edição direta do arquivo em ~/.verdent/VERDENT.md

Quando as alterações entram em vigor: As regras se aplicam imediatamente em novas conversas e influenciam as respostas da conversa atual.

Casos de uso

Formato e sintaxe

O VERDENT.md usa o formato Markdown simples com marcadores ou listas numeradas.

Estrutura:

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

• Use linguagem clara e diretiva ("Sempre use...", "Prefira...", "Nunca...")
• Organize em seções lógicas com cabeçalhos
• Use marcadores para regras individuais
• Seja específico sobre o comportamento desejado

Exemplos por tipo de desenvolvedor

# 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

Como criar e editar

Regras do projeto (AGENTS.md)

O AGENTS.md define regras específicas do projeto que controlam o comportamento do agente para o projeto atual. Ele estabelece padrões de codificação da equipe, padrões arquiteturais, requisitos de teste e fluxos de trabalho de desenvolvimento específicos do projeto.

Localização e escopo

Localização do arquivo: Diretório raiz do projeto

Escopo: Apenas o projeto atual

Controle de versão: Pode ser commitado no git para compartilhamento com toda a equipe

Acesso:

• Settings → Rules → Project Rules
• Edição direta em <project-root>/AGENTS.md

Casos de uso

Colaboração em equipe: O AGENTS.md é armazenado na raiz do projeto e pode ser commitado no controle de versão, garantindo que todos os membros da equipe trabalhem com um comportamento de agente consistente.

Formato e sintaxe

O AGENTS.md usa o formato Markdown com seções estruturadas e marcadores, semelhante ao VERDENT.md, mas com foco em requisitos específicos do projeto.

Estrutura:

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

• Linguagem imperativa e diretiva
• Organizada por área de fluxo de trabalho (desenvolvimento, testes, deploy)
• Comandos e procedimentos específicos
• Padrões de toda a equipe, não preferências pessoais

Exemplos por tipo de projeto

# 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

Diferenças em relação ao VERDENT.md

Escopo:

• VERDENT.md: Preferências pessoais em todos os projetos
• AGENTS.md: Padrões da equipe apenas para um projeto específico

Prioridade:

• AGENTS.md: Precedência mais alta - sobrescreve user_rules para consistência do projeto
• VERDENT.md: Precedência mais baixa - aplica-se quando nenhuma regra do projeto conflita

Foco do conteúdo:

• VERDENT.md: Estilo individual de codificação, preferências de comunicação, ferramentas pessoais
• AGENTS.md: Convenções da equipe, arquitetura do projeto, fluxos de trabalho compartilhados, stack tecnológico

Controle de versão:

• VERDENT.md: Não compartilhado - permanece na máquina do indivíduo
• AGENTS.md: Commitado no git - compartilhado com toda a equipe

Armazenamento:

• VERDENT.md: ~/.verdent/VERDENT.md (global)
• AGENTS.md: Diretório raiz do projeto (específico do projeto)

Exemplo de resolução de conflito:

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

Quando usar cada um:

• VERDENT.md: Preferências pessoais que você quer em todos os projetos
• AGENTS.md: Padrões que toda a equipe deve seguir para este projeto

Regras de plano (Plan.md)

O Plan.md personaliza o conteúdo e o formato dos planos gerados no Plan Mode. Ele controla o nível de detalhe do plano, as seções incluídas, as preferências de formatação e as informações exibidas.

Localização e escopo

Localização do arquivo: ~/.verdent/plan_settings.json

Escopo: Global para todos os projetos

Aplicação: Aplicado apenas durante o Plan Mode ao gerar planos

Acesso:

• Settings → Rules → Plan Rules
• Edição direta do arquivo em ~/.verdent/plan_settings.json

Casos de uso

Formato e sintaxe

O Plan.md usa o formato Markdown com seções que descrevem a estrutura e o conteúdo desejados do plano.

Estrutura:

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

Exemplos por estilo de planejamento

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

Quando as regras de plano são aplicadas?

Aplicação das regras de plano:

• Momento: Aplicado apenas durante o Plan Mode ao gerar planos
• Escopo: Controla o formato e o conteúdo do plano, não a geração de código
• Independência: Não conflita com o VERDENT.md ou o AGENTS.md

Aplicação dos outros tipos de regra:

• VERDENT.md: Aplicado continuamente em todos os modos (Agent, Plan, Chat)
• AGENTS.md: Aplicado continuamente em todos os modos para comportamento específico do projeto

Exemplo de interação:

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

Comportamento específico de cada modo:

• Agent Mode: VERDENT.md + AGENTS.md aplicados (sem plan_rules.md)
• Plan Mode: VERDENT.md + AGENTS.md + Plan.md todos aplicados
• Chat Mode: VERDENT.md + AGENTS.md aplicados (sem Plan.md)

Precedência de regras e resolução de conflitos

Quando as regras entram em conflito, o Verdent aplica a precedência para garantir um comportamento consistente.

Ordem de precedência

1. Regras do projeto (AGENTS.md) - Prioridade mais alta As regras específicas do projeto sobrescrevem as preferências globais. Os padrões da equipe têm precedência sobre as preferências individuais para garantir consistência.

2. Regras do usuário (VERDENT.md) - Prioridade média As preferências globais se aplicam quando nenhuma regra específica do projeto conflita.

3. Comportamento padrão - Prioridade mais baixa Os padrões internos do Verdent se aplicam quando nenhuma regra é especificada.

Exemplo de resolução de conflito:

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

Regras de plano: O Plan.md se aplica de forma independente durante o Plan Mode e não conflita com as regras de usuário/projeto. Ele controla o formato do plano, enquanto o VERDENT.md e o AGENTS.md controlam o estilo de código dentro do plano.

Solução de problemas de conflitos de regras

Quando você observar um comportamento inesperado que contradiz uma regra, siga esta estratégia de depuração:

Etapa 1: Identifique o conflito

1. Observe o comportamento inesperado que contradiz uma regra
2. Verifique quais regras podem se aplicar à situação
3. Procure por contradições entre os arquivos de regras

Etapa 2: Verifique a precedência de regras

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

As regras do projeto sobrescrevem as preferências pessoais.

Etapa 3: Teste isoladamente

Desabilite o VERDENT.md: Renomeie ou limpe temporariamente o arquivo, teste se o conflito é resolvido

Teste sem o AGENTS.md: Trabalhe no projeto sem o AGENTS.md para isolar o comportamento de user_rules

Nova conversa: Inicie uma sessão do zero para eliminar a influência do contexto da conversa

Cenários comuns de conflito

Cenário 1: Conflito de formatação

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

Cenário 2: Regras contraditórias no mesmo arquivo

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

Exemplo de correção:

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

Cenário 3: Regra muito vaga

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

Estratégia de depuração

1. Teste explícito: Pergunte ao Verdent "Qual regra você está seguindo para [comportamento específico]?"

Exemplo:

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. Refinamento incremental: Adicione especificidade a regras ambíguas

Antes:

- Use appropriate error handling

Depois:

- 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 prioridade: Use "CRITICAL:" ou "REQUIRED:" para regras não negociáveis

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

Boas práticas para escrever regras

Seja específico e diretivo:

• Use linguagem clara e imperativa ("Sempre use...", "Nunca...", "Prefira...")
• Evite frases ambíguas ("Tente..." → "Sempre...")
• Diga exatamente o que você quer, não o que você não quer

Bom:

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

Evite:

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

Organize logicamente:

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

Mantenha as regras gerenciáveis:

• Escreva regras concisas (um conceito por marcador)
• Revise e atualize as regras conforme o projeto evolui
• Remova regras obsoletas prontamente

Priorize regras importantes:

• Coloque as regras críticas primeiro em cada seção
• Use ênfase para padrões não negociáveis ("NUNCA faça commit de credenciais")
• Concentre-se em regras que previnem bugs ou problemas de segurança

Teste a eficácia das regras:

• Verifique se o Verdent segue as regras na prática
• Inicie uma nova conversa para testar a aplicação das regras
• Refine as regras com base no comportamento real do agente

Equilibre detalhe e flexibilidade:

• Específico demais → Comportamento rígido que não se adapta
• Vago demais → Comportamento inconsistente
• Busque uma orientação clara com espaço para decisões adequadas ao contexto

Considerações de equipe (AGENTS.md):

• Envolva a equipe na criação de regras
• Documente a justificativa para regras não óbvias
• Mantenha as regras da equipe focadas em padrões compartilhados, não em preferências pessoais

Veja também