AGENTS.md

AGENTS.md — Contrato de Desenvolvimento

Este arquivo é lido pelo agente a cada sessão. ❌ O agente NUNCA deve modificar este arquivo.

---

1. CONFIGURAÇÃO DO PROJETO

Nome:         [nome do projeto]
Repositório:  [url do repositório]
Linguagem:    [ex: Python, TypeScript]
Stack:        [ex: Docker, Nuxt 4, Litestar]
Objetivo:     [descrição resumida do que o projeto faz]

Comandos do Projeto

# Instalar dependências


# Iniciar App


# Iniciar API


# Lint / Format


# Build (se aplicável)

---

2. PLANO DE DESENVOLVIMENTO

O plano de desenvolvimento está em PLAN.md na raiz do repositório. Leia esse arquivo antes de qualquer ação — ele é a fonte da verdade sobre o que deve ser construído.

• ✅ A única modificação permitida em PLAN.md é marcar uma TASK como concluída ao finalizá-la
• ❌ NUNCA alterar descrições, adicionar ou remover tasks — isso é responsabilidade humana
• Ao identificar a próxima TASK, referencie sempre pelo identificador definido em PLAN.md
• O PLAN.md define o objetivo da TASK, não a solução — use-o como direção, não como especificação rígida; se houver uma abordagem melhor, sugira antes de implementar

---

3. PADRÕES DE DESENVOLVIMENTO

3.1 Estrutura de Pastas

• Ao iniciar, analise a estrutura de pastas existente antes de criar qualquer arquivo
• Respeite e siga o padrão de organização já adotado no repositório
• Em projetos novos, proponha uma estrutura condizente com a linguagem/framework da seção 1 e aguarde aprovação antes de criá-la
• ❌ NUNCA criar arquivos em locais que contradizem a organização existente

3.2 Convenções de Código

• Analise o código existente antes de implementar — siga arquitetura, nomenclatura e estilo já adotados
• Funções pequenas, responsabilidade única, sem duplicação — lógica usada 2x ou mais vira utilitário
• Código simples primeiro: sem over-engineering, sem abstrações prematuras, sem tipos genéricos vazios (any, object)
• Camadas com responsabilidades bem definidas (entrada/saída, regras de negócio, acesso a dados) — sem vazamento entre elas
• Se existir pacote consolidado que resolva o problema, sugira-o antes de implementar manualmente

3.3 Git

• Branch: feature/TASK-XXX-descricao ou fix/TASK-XXX-descricao
• Commits: padrão Conventional Commits

  feat(escopo): descrição curta no imperativo
  fix(escopo): descrição curta no imperativo
  chore(escopo): descrição curta no imperativo
  

• ❌ NUNCA executar git commit sem solicitação explícita — commitar é responsabilidade humana

3.4 Testes

• ❌ NUNCA criar arquivos de teste, pastas de teste ou instalar dependências de teste de nenhum tipo
• Se solicitado, perguntar antes de prosseguir

3.5 Documentação e Comentários

• ❌ NUNCA criar arquivos .md — a criação de qualquer documentação em Markdown é responsabilidade humana. Exceção: MEMORY.md
• ✅ Atualizar arquivos .md já existentes quando o conteúdo implementado impactar sua documentação
• ✅ Docstrings apenas quando descrevem comportamento não-trivial, efeitos colaterais ou restrições — nunca repita o que o nome já diz
• ✅ Comentários inline apenas para lógica genuinamente não-óbvia

3.6 Regras Importantes

1. ❌ Nunca commitar segredos, tokens ou arquivos .env
2. Sempre validar inputs externos antes de processar ou persistir
3. Sem tipos genéricos vazios (any, object, interface{}) — defina o tipo correto

---

4. INSTRUÇÕES PARA O AGENTE

Ao iniciar a sessão

Sempre:

1. Ler este arquivo (AGENTS.md)

Somente se solicitado para executar uma task: 2. Ler o PLAN.md e identificar a task solicitada ou a próxima pendente 3. Ler o MEMORY.md se a task envolver refatoração ou modificação de algo já implementado

Somente se não houver task clara no PLAN.md: 4. Ler o README.md e o arquivo de dependências (pyproject.toml, package.json ou equivalente) 5. Analisar a estrutura de pastas do repositório conforme 3.1

Durante a execução

• Seguir os padrões da seção 3 sem exceções, salvo aprovação explícita
• Ao tomar qualquer decisão técnica relevante, atualizar o MEMORY.md imediatamente
• Após implementar, inicializar o App e a API conforme os comandos da seção 1 e verificar se há erros no console antes de prosseguir
• Ao concluir uma TASK, criar um smoke script em scripts/smoke/TASK-XXX.py apenas se solicitado pelo usuário — após validação, deletar o arquivo
• Ao concluir uma TASK, verificar se algum padrão novo foi descoberto no código e registrá-lo em "Padrões Descobertos" no MEMORY.md antes de atualizar "Últimas Sessões"
• Ao concluir uma TASK, marcar como concluída no PLAN.md antes de avançar

Ao finalizar a sessão

1. Atualizar o MEMORY.md seguindo as regras de manutenção definidas nele
2. Atualizar o README.md se a TASK concluída impactar o uso ou funcionamento do projeto
3. Reportar ao usuário um resumo do que foi feito antes de encerrar