golem-sdd
AGENTS.md0 starsChanged 3 days agoMITView on GitHub
Este arquivo é lido pelo agente em toda sessão. As regras numeradas são método: valem para toda tarefa, em qualquer conversa. Os trechos entre << >> são do projeto: preencha antes de usar. Quem é quem. O usuário decide produto, prioridade, stack, gasto e tudo que sai para fora, e faz os merges que a lista de nível 3 reserva a ele ("Convenções", abaixo). O agente decide o detalhe de implementação dentro de uma spec aprovada. Leia só o que…
- Reads credentials
- Installs packages
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adrSkill
- auditar-specsSkill
- changelogSkill
- configurarSkill
- constituicaoSkill
- diagnosticoSkill
- implementar-faseSkill
- iniciar-conversaSkill
- iniciar-sddSkill
- licaoSkill
- replanejar-roadmapSkill
- sessao-gerenteSkill
- spec-de-faseSkill
- validar-faseSkill
The file
Files
AGENTS.md — regras permanentes do projeto
Este arquivo é lido pelo agente em toda sessão. As regras numeradas são método: valem para toda
tarefa, em qualquer conversa. Os trechos entre << >> são do projeto: preencha antes de usar.
O projeto
<< Uma frase: o que o projeto é e para quem. Ex.: "API de agendamento para clínicas pequenas." >>
| O quê | Onde |
| Código | << ex.: src/ >> |
| Specs | specs/ (a constituição e uma pasta por fase) |
| Decisões técnicas | docs/adr/ |
| Lições | docs/licoes/ |
| Como as conversas trabalham | docs/operacao-das-conversas.md |
| Ferramental do agente | .claude/ (skills, agentes, ganchos, régua): a fonte |
| Cópias para o Codex | .agents/skills/ e .codex/ (agentes e gancho), geradas por .claude/instalar_codex.py, nunca à mão |
Quem é quem. O usuário decide produto, prioridade, stack, gasto e tudo que sai para fora, e faz os merges que a lista de nível 3 reserva a ele ("Convenções", abaixo). O agente decide o detalhe de implementação dentro de uma spec aprovada.
Ordem de leitura
- Este arquivo.
docs/operacao-das-conversas.md: os papéis e o que cada conversa faz sozinha.specs/mission.md,specs/tech-stack.md,specs/roadmap.md: a constituição.specs/AAAA-MM-DD-<fase>/: a spec da fase em andamento.docs/adr/: as decisões registradas, com o gatilho de revisão de cada uma.
Leia só o que a tarefa de hoje exige. O resto se abre quando for preciso.
Comandos reais
<< Preencha com os comandos que funcionam hoje, copiados de quem roda. Sem eles, as regras 4 e 8 ficam no ar. >>
# setup
<< ex.: python -m venv .venv && .venv/bin/pip install -r requirements.txt >>
# testes (a linha de resumo tem de aparecer na saída)
<< ex.: .venv/bin/python -m pytest -q >>
# lint e formatação
<< ex.: ruff check . && ruff format --check . — ou "não instalado" >>
# subir local
<< ex.: docker compose up -d >>Stack: << linguagem e versão, framework, banco. O detalhe vive em specs/tech-stack.md. >>
Contagem esperada de testes: << onde ela vive: um índice gerado ou o validation.md da fase.
Nunca um número escrito à mão em prosa, que envelhece sem avisar. >>
<!-- golem:inicio -->Como o Golem trabalha aqui
<!-- Gerado pelo `.claude/golem.py aplicar`. Não edite à mão: peça "configurar o Golem". -->Receita economico; o guia é docs/guia-configuracao.md.
- Revisor: sempre, uma vez por fase, antes da verificação: o
revisorlê o diff da fase inteira. Modelosonnet. - Validador: nunca.
- Guardião: nunca.
- Os comandos do
validation.md: sempre, pela própria conversa, com a linha de resumo lida. - Parar a cada parte: sempre: ao fim de cada grupo, mostre o diff e uma linha do que mudou, e espere o ok.
- Conversas: uma; os papéis de
docs/operacao-das-conversas.mdsão opcionais. - Gancho das lições: ligado, até 2 lições novas por ação.
<!-- golem:fim -->Convenções
- Commits e PRs em << português >>. Merge por << squash | merge commit >>.
Quem libera o merge. Por padrão, o merge no repositório do projeto é nível 2: a conversa gerente (GER) libera pelo par PEDIDO → LIBERADO, depois de conferir o head, a base e a prova. Sem gerente (uma conversa só), o usuário faz esse papel. É nível 3, só com a palavra do usuário na conversa que executa:
- o merge em repositório de terceiros (de outra equipe, de um cliente, um projeto aberto);
- o merge que vai a produção (uma branch com deploy automático, uma branch de release);
- o merge local, num projeto sem remoto (não há PR nem GER que confira: quem mergeia é o usuário);
- << o que mais o projeto listar >>.
A mesma lista está em
docs/operacao-das-conversas.md, "Níveis de autonomia": mudou aqui, muda lá no mesmo commit.- Merge em duas chamadas: primeiro a conferência do head e da base; depois, noutra chamada e
com o LIBERADO (mais a palavra do usuário, no nível 3), o merge com o sha lido na saída. Ver
docs/operacao-das-conversas.md, "Merge". - Quem muda, varre. Mudou um caminho, um comando, uma contagem ou o nome de uma variável? Busque
o nome antigo nos documentos e nos agentes (
.claude/agents/) e corrija no mesmo commit. Caminho errado num agente não dá erro: ele lê nada e responde com a mesma confiança. - O que é gerado (o índice da régua) se refaz com
python3 .claude/regua.py --gerar, nunca à mão. O bloco "Como o Golem trabalha aqui" e omodel:dos agentes saem dogolem.tomlpelopython3 .claude/golem.py aplicar(ou pela skillconfigurar). No Windows,pythonoupy -3no lugar depython3, aqui e em todo o kit. As cópias para o Codex (.agents/skills/,.codex/) também são geradas: mudou uma skill ou um agente em.claude/, rodepython3 .claude/instalar_codex.pye faça o commit das cópias junto (--conferiracusa a divergência). - << convenções do projeto: estrutura de pastas, nomes, tratamento de erro >>
Regras
Onde uma regra mora. Regra que vale para toda tarefa fica aqui, curta e imperativa. A evidência que a justifica fica na lição citada (
docs/licoes/). A regra manda; a lição explica.
- Spec antes do código. Nenhuma implementação começa sem
requirements.md,plan.mdevalidation.mdda fase escritos e aprovados pelo usuário.- Formato curto, para fase pequena: a fase sem borda externa (API pública, outro sistema),
sem deploy e que cabe num dia usa só o
requirements.mde ovalidation.md, os dois numa página, com o plano numa seção "Como fazer" dentro dorequirements.md. O que não encolhe: os critérios continuam sendo comando ou passo a passo (regra 4), e a spec é aprovada antes do código. Fora desse formato, ninguém improvisa "spec enxuta". Por quê: o que não está escrito some na próxima conversa, e o agente preenche o vazio com suposição.
- Formato curto, para fase pequena: a fase sem borda externa (API pública, outro sistema),
sem deploy e que cabe num dia usa só o
- Uma fase por branch, mergeável sozinha. Se o escopo não couber, divida o roadmap em vez de
inchar a fase.
Por quê: fase grande não se revisa de uma vez, e abandonada no meio deixa a
mainquebrada. - Nenhuma dependência nova sem aprovação do usuário. Algo fora de
specs/tech-stack.md, inclusive dependência transitiva relevante: pare e proponha. Por quê: dependência é mudança de stack, não detalhe de implementação, e sai caro de tirar. - Critério de validação é comando ou passo a passo. Cada item do
validation.mddiz o comando e o resultado esperado, ou os passos que uma pessoa executa e o que ela deve ver. "Funciona corretamente" não é critério. Por quê: o agente diz "pronto" com a mesma confiança quando está errado; só a execução separa. - Nada de credencial, token ou dado sensível no repositório. Segredo vive fora do Git
(<< ex.:
.env, no.gitignore>>). Não leia nem imprima segredo para "conferir". Por quê: o que entra no histórico do Git não sai mais de verdade. - Não commitar sem o usuário pedir. Aprovar o plano pode incluir "um commit por grupo na branch da fase"; fora disso, o trabalho fica pronto para commit, e quem pede é o usuário. Por quê: o commit é o ponto em que o usuário assume o que entrou.
- Armadilha descoberta vira lição versionada. Quando uma hipótese for refutada por
evidência, uma premissa do projeto se revelar falsa, um defeito custar mais de uma
rodada para diagnosticar, ou o usuário corrigir um entendimento seu: registre em
docs/licoes/pela skilllicao, no formato dedocs/licoes/README.md, faça ogit adddela e rodepython3 .claude/regua.py --gerar. Só esses quatro motivos: se não dá para escrever "o que se achava", não é lição. Quando a lição implicar ação obrigatória, acrescente aqui uma regra curta que a cite. Preferência do usuário e estado do projeto não são lição: vão para a memória. Por quê: a conversa seguinte não sabe o que esta aprendeu, e o gancho só entrega o que está escrito. - Suíte verde só vale com a linha de resumo lida. Leia o total de testes, as falhas e as
puladas na saída, e compare com a contagem esperada. Pulado a mais é falha até prova em
contrário. Opção que esconde o resumo (como
-qem dobro no pytest) não se usa. Por quê: "passou" sem o resumo pode ser zero testes coletados ou metade deles pulada. - Fato que sustenta spec ou decisão se confere na fonte, na hora. Todo fato que sustenta uma
spec, uma opção levada ao usuário ou um texto a terceiros (código, config, versão, contagem,
quem tem acesso a quê) se cita com
arquivo:linha(e o commit, quando o código muda) ou com a saída do comando. Memória, resumo de contexto, mensagem de outra conversa e a spec anterior são hipótese até serem conferidos.- Resposta do usuário que implica fato técnico ("tenho acesso a X", "isso já existe"): confirme o sentido exato e ache o caminho no código ou na config antes de escrever na spec.
- Decisão do usuário entra com as palavras dele e a data; o que ela implica tecnicamente fica "a conferir" até ser verificado.
- Na fronteira de cada grupo e depois de toda compactação de contexto, releia do disco o
plan.mde a spec, e reconfira os fatos-chave. - Na dúvida, escreva "a conferir" e o que falta, em vez de afirmar. Por quê: o resumo carrega a conclusão e perde a ressalva, e a spec escrita de memória vira a referência que todo mundo cita depois.
- Simplicidade: o menor que resolve o problema de hoje.
- Nada "por precaução" ou "para o futuro": nem peça nova, nem validação extra, nem camada de defesa sem uma falha vista que a justifique.
- Reuse o que existe antes de criar. Arquivo, módulo, flag, config ou tabela nova pedem um caso real, com exemplo concreto na spec ou no PR.
- Nada de abstração antes do terceiro uso real: duas cópias parecidas são melhores que uma abstração errada.
- Prefira a mudança que se desfaz sem migração. Teste proporcional ao que mudou.
- "Não mudar nada" é resposta válida.
- Produto e arquitetura são do usuário; o detalhe de implementação é do agente. Dentro de uma spec aprovada, o agente segue grupo a grupo sem pedir licença, salvo com o "parar a cada parte" do bloco "Como o Golem trabalha aqui": aí ele para ao fim de cada grupo, mostra o diff e espera o ok. Ele pergunta quando a escolha muda o que o usuário ou o cliente vê e a spec não traz, ou sai do escopo; aí propõe até duas opções simples, mais "não mudar nada".
- Antes de entregar: "o que eu posso tirar e ainda resolver o problema?". O que puder sair, sai. Por quê: agente escreve código barato e mantém código caro; cada peça a mais é peça que alguém vai ter de entender, mudar e apagar.
- Revisor e validador independentes, conforme a configuração. O bloco "Como o Golem trabalha
aqui" diz se cada um roda (
sempre,perguntaroununca), se por grupo ou uma vez por fase, e o guardião; sem o bloco, rode oaplicar, e sem Python vale aeconomico. Delegue a eles: no Claude Code, são os de.claude/agents/, e o modelo já está no frontmatter (não passe outro na chamada, salvo se a spec da fase pedir outro modelo); no Codex, os de.codex/agents/(gerados pelo instalador). Os dois só leem. O revisor dá "sem bloqueio" ou "com bloqueio"; o validador dá "valida" ou "não valida". Bloqueio se corrige e volta à revisão.- Os comandos do
validation.mdrodam sempre, pela própria conversa, com a linha de resumo lida (regras 4 e 8), qualquer que seja a configuração. - Com
perguntar, a etapa vira uma pergunta com botões na hora em que chega, com o custo ("abre 1 conversa extra"); em texto numerado onde não houver botões. Só roda com o sim. - Caminho rápido: quando o validador rodaria, o grupo ou o PR só de documentação (os
.md, inclusive skills, agentes e lições) ou só de testes leva só o revisor, se ele roda. O revisor confere fato por fato contra a fonte, e não só a forma. Se ganhar código (inclusive script em.claude/), ou se o revisor apontar algo importante, volta ao caminho completo. Não se fatia uma mudança grande para caber no caminho rápido. - O guardião, quando roda: antes do merge do PR com código, o agente
revisorsobre o diff inteiro do PR, numa conversa nova (ou num subagente novo, sem o contexto de quem escreveu). Ele vê o que a revisão grupo a grupo não vê: o efeito somado. - Quem revisa trata como achado: afirmação sem fonte, peça sem caso real, abstração prematura e escopo além do pedido. Por quê: quem escreveu lê o que quis escrever; um leitor sem esse viés acha o que o autor não vê, e a execução acha o que a leitura não acha.
- Os comandos do
- Nada vai a terceiros sem o usuário. Comentário em issue ou PR, mensagem a outra pessoa ou equipe, texto a cliente, publicação: o agente redige, o usuário lê e dá o ok na conversa que executa, e só então sai. Agentes não combinam decisões com pessoas ou agentes de fora. Por quê: o que sai fala em nome do usuário e não se desfaz.
<< Regras do projeto: acrescente a partir da 13, cada uma curta, imperativa e citando a lição que a justifica. >>
Skills e agentes
Versionados em .claude/skills/ e .claude/agents/, e as cópias do Codex em .agents/skills/ e
.codex/agents/: clonar o repositório reproduz o ambiente nos dois agentes.
O fluxo normal é spec-de-fase → implementar-fase → validar-fase, com licao sempre que a
regra 7 disparar e replanejar-roadmap quando o plano envelhecer. Os agentes revisor e
validador servem à regra 11. O fluxo inteiro está em WORKFLOW.md.
Skill nova só aparece em sessão nova: reinicie o agente (Claude Code ou Codex) depois de adicionar
uma. No Codex, rode antes python3 .claude/instalar_codex.py.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

