aitormf/agent-skills

Contexto do projeto

Ajude a pessoa a decidir e escrever as regras estáveis do projeto, cada uma no arquivo onde pertence. A pessoa toma as decisões: você lê, propõe opções concretas e rascunha.

Substitui o constitution.md do Spec Kit. Todo o seu conteúdo tem um lar melhor:

Conteúdo	Arquivo	Lido por
Stack, camadas, regras de dependência, princípios inegociáveis, glossário	docs/ARCHITECTURE.md	Pessoas e agentes; spec-to-plan e review-spec verificam os princípios
Qualidade, branches, commits, PRs, revisão, uso de IA	CONTRIBUTING.md	Pessoas (e agentes, via link)
O porquê de cada decisão estrutural e as alternativas descartadas	docs/adr/NNNN-*.md	Ambos, sob demanda
Comandos, limites, convenções não óbvias, mapa da documentação	AGENTS.md (+ CLAUDE.md com @AGENTS.md)	Agentes, em toda sessão
Como reportar vulnerabilidades, política do agente	SECURITY.md	Pessoas

Templates em assets/en/ (Inglês) e assets/es/ (Espanhol). Use o idioma em que o projeto está documentado; pergunte se não estiver claro. Cada template explica em seu comentário de abertura como preenchê-lo.

Regras

• Não duplicar. Se algo já está em pyproject.toml, no CI ou em um linter, faça um link; não copie. Se um princípio aparecer em dois arquivos, eles acabarão se contradizendo: princípios vivem apenas em ARCHITECTURE.md.
• AGENTS.md curto: menos de 150 linhas. É um mapa que referencia; não contém. Para cada linha: "se eu remover, o agente erraria?". Se não, fora.
• O que pode ser verificado com uma ferramenta, é verificado com uma ferramenta. Para cada princípio, pergunte como é verificado (lint, import-linter, teste, CI, revisão) e anote em sua coluna.
• Nada volátil: nenhum status de sprint ou TODOs. Estes vão no gerenciador de tarefas ou em docs/plans/.
• Mostre cada arquivo na íntegra (ou o diff, se já existir) e escreva somente após a pessoa aprová-lo.

Processo

1. Leia o projeto

Antes de perguntar qualquer coisa, leia: manifestos (pyproject.toml, package.json, go.mod…), README.md, quaisquer arquivos de contexto existentes, .github/workflows/, configuração de linter e a estrutura de pastas. Use o que encontrar para propor respostas em vez de fazer perguntas abertas.

Decida o modo e informe a pessoa:

• Greenfield (sem código ou quase nenhum): ARCHITECTURE.md é prescritivo, como será.
• Brownfield: ARCHITECTURE.md é descritivo, como é hoje. O ideal vai para os ADRs e as 'catracas' das ferramentas. Se os arquivos de contexto já existirem, pergunte apenas sobre as lacunas e proponha diffs.
• Migração de um constitution.md: distribua seu conteúdo de acordo com a tabela acima e proponha deletá-lo ou reduzi-lo a um link.

2. Entrevista por rodadas

Uma categoria de cada vez. Para cada pergunta, ofereça opções concretas (A, B, "deixar em aberto", "outro"). Se os arquivos já responderem a pergunta, peça confirmação em vez de perguntar. Se uma categoria não se aplicar (ex.: não há banco de dados), pule-a e avise. Ao final de cada rodada, resuma o que foi decidido.

Rodada	O que é decidido	Destino
1. Propósito	O que o projeto é e o que está fora; tipo (app, serviço, biblioteca, CLI)	ARCHITECTURE.md §1, README.md
2. Stack e arquitetura	Linguagem, framework, persistência, infraestrutura; camadas ou módulos e o que pode importar o quê	ARCHITECTURE.md §2–4, um ADR por decisão estrutural
3. Princípios inegociáveis	5–10 regras estáveis e verificáveis: por que e como cada uma é verificada	ARCHITECTURE.md §5
4. Qualidade	Teste primeiro ou depois, cobertura mínima, tipagem, o que nunca é mockado	CONTRIBUTING.md §5; se inegociável, também um princípio
5. Segurança	Autenticação, dados sensíveis, validação de entrada, conformidade regulatória	ARCHITECTURE.md §10, SECURITY.md
6. Processo	Branches, Conventional Commits, merge ou squash, aprovações, tamanho do PR, ferramentas de IA permitidas	CONTRIBUTING.md §4, §6–7
7. Dependências	Política para adicioná-las, bibliotecas proibidas, construir ou comprar	Princípio (se inegociável) ou CONTRIBUTING.md
8. Para o agente	Comandos (o de verificação é obrigatório), convenções não óbvias, áreas críticas ou frágeis (brownfield), limites (sempre / perguntar / nunca)	AGENTS.md

Na rodada 8, o comando de verificação é o contrato com as outras skills (plan-to-tasks, implement, revisão). Se ele não existir, proponha setup-guardrails-python (ou um equivalente para a linguagem) ou deixe como uma pergunta em aberto em AGENTS.md. Se o projeto for usar review-prepush ou review-pr, ofereça também a seção opcional ## Code review (template em review-context/assets/AGENTS-code-review.md): branch base, caminhos de alto risco, idioma do relatório…

3. Rascunhe e escreva

Ordem: ARCHITECTURE.md → ADRs → CONTRIBUTING.md → SECURITY.md → AGENTS.md. AGENTS.md vai por último porque referencia todos os anteriores.

• Comece pelo template em assets/. Exclua as seções que ainda não se aplicam; não as deixe vazias.
• ADRs: copie ADR.md como docs/adr/0000-template.md (0000-plantilla.md em espanhol) e adr-README.md como docs/adr/README.md. Crie um ADR por decisão estrutural das rodadas 2–3. Brownfield: apenas 3–5 retroativos, para o que é mais questionado, com as alternativas descartadas.
• AGENTS.md deve incluir:
  • a linha "Planning": verifique o plano contra os princípios em docs/ARCHITECTURE.md antes de implementar;
  • um link para CONTRIBUTING.md para o processo.
• CLAUDE.md contém apenas @AGENTS.md, a menos que já tenha conteúdo. Nesse caso, proponha movê-lo para AGENTS.md.
• pull_request_template.md vai em .github/. Ofereça, não imponha.

4. Conclusão

Liste os arquivos criados ou alterados e as perguntas que ficaram em aberto. Lembre a pessoa:

• AGENTS.md é revisado mensalmente e podado, especialmente ao mudar de modelos.
• ARCHITECTURE.md é verificado contra o código a cada trimestre.
• Todo erro que o agente repete se torna uma regra de ferramenta ou, como último recurso, uma linha em "Armadilhas conhecidas".