268 lines
7.0 KiB
Markdown
268 lines
7.0 KiB
Markdown
# AGENTS
|
|
|
|
## Missao
|
|
|
|
Este repositorio deve operar com um pipeline rigido de conhecimento e execucao:
|
|
|
|
`agenda -> decision -> PR/plan -> spec ou codigo -> learn`
|
|
|
|
Regra central:
|
|
|
|
- nao pular etapas;
|
|
- nao resolver ambiguidade estrutural no meio da implementacao;
|
|
- nao transformar `learn` em deposito cru de historico;
|
|
- nao escrever spec ou codigo sem base em `decision` e `PR/plan` quando houver impacto arquitetural.
|
|
|
|
## Mapa Canonico
|
|
|
|
- `docs/runtime/agendas/`: discussao, enquadramento do problema, pontos mais importantes, sugestoes e recomendacao.
|
|
- `docs/runtime/decisions/`: registro normativo do que foi decidido. Deve estar pronto para propagar em spec ou implementacao.
|
|
- `docs/runtime/pull-requests/`: plano executavel de entrega para spec e/ou codigo.
|
|
- `docs/runtime/specs/`: contrato tecnico normativo consolidado.
|
|
- `docs/runtime/learn/`: consolidacao didatica do que ja foi fechado e executado.
|
|
- `crates/`: implementacao em codigo.
|
|
|
|
## Fluxo Obrigatorio
|
|
|
|
### 1. Agenda
|
|
|
|
Use `agenda` quando ainda existe ambiguidade, disputa de abordagem, risco arquitetural, escopo mal fechado ou falta de recomendacao.
|
|
|
|
Toda agenda deve:
|
|
|
|
- apresentar o problema real;
|
|
- listar os pontos mais importantes da discussao;
|
|
- separar fato, risco, tradeoff e hipotese;
|
|
- trazer sugestoes objetivas, nao so perguntas soltas;
|
|
- terminar com uma recomendacao clara, mesmo que condicional;
|
|
- explicitar o que ainda impede a decisao.
|
|
|
|
Template minimo:
|
|
|
|
- `Contexto`
|
|
- `Problema`
|
|
- `Pontos Criticos`
|
|
- `Opcoes`
|
|
- `Sugestao / Recomendacao`
|
|
- `Perguntas em Aberto`
|
|
- `Criterio para Encerrar`
|
|
|
|
Regra de saida:
|
|
|
|
- agenda concluida deve virar `decision`;
|
|
- agenda que ainda nao fecha contrato nao pode virar PR de implementacao.
|
|
|
|
### 2. Decision
|
|
|
|
Toda agenda concluida deve se tornar uma `decision`.
|
|
|
|
Uma `decision` deve conter tudo que a equipe precisa para propagar a decisao em spec ou implementacao, inclusive referencias para specs ja consolidadas quando existirem.
|
|
|
|
Toda decision deve:
|
|
|
|
- declarar a decisao tomada sem ambiguidade;
|
|
- registrar contexto e drivers;
|
|
- listar alternativas descartadas e por que foram descartadas;
|
|
- definir invariantes e contrato operacional;
|
|
- delimitar impacto em specs, runtime, host, firmware e tooling quando aplicavel;
|
|
- apontar referencias normativas existentes;
|
|
- deixar claro o que ainda precisa ser implementado ou publicado.
|
|
|
|
Template minimo:
|
|
|
|
- `Status`
|
|
- `Contexto`
|
|
- `Decisao`
|
|
- `Rationale`
|
|
- `Invariantes / Contrato`
|
|
- `Impactos`
|
|
- `Referencias`
|
|
- `Propagacao Necessaria`
|
|
|
|
Regra de saida:
|
|
|
|
- decision fechada deve evoluir para `PR/plan`;
|
|
- se a decision nao estiver pronta para orientar execucao, ela ainda nao esta fechada.
|
|
|
|
### 3. PR / Plan
|
|
|
|
`PR` e o artefato de planejamento de execucao. Ele nasce de uma ou mais `decisions`.
|
|
|
|
Toda PR deve:
|
|
|
|
- citar explicitamente as decisions de origem;
|
|
- separar implementacao de spec e implementacao de codigo quando o escopo pedir;
|
|
- definir alvo, fora de escopo, riscos e ordem de execucao;
|
|
- trazer criterios de aceite verificaveis;
|
|
- definir estrategia de testes e evidencias esperadas;
|
|
- bloquear reabertura de debate arquitetural dentro da fase de execucao.
|
|
|
|
Template minimo:
|
|
|
|
- `Briefing`
|
|
- `Decisions de Origem`
|
|
- `Alvo`
|
|
- `Escopo`
|
|
- `Fora de Escopo`
|
|
- `Plano de Execucao`
|
|
- `Criterios de Aceite`
|
|
- `Tests / Validacao`
|
|
- `Riscos`
|
|
|
|
Regra de saida:
|
|
|
|
- PR de spec alimenta `docs/runtime/specs/`;
|
|
- PR de codigo alimenta `crates/`;
|
|
- PR concluida deve deixar rastro para consolidacao em `learn`.
|
|
|
|
### 4. Learn
|
|
|
|
`learn` recebe conhecimento consolidado de decisions que ja viraram PR e tiveram resultado publicado em spec, codigo ou ambos.
|
|
|
|
`learn` nao e fonte normativa. `learn` explica, organiza, ensina e melhora a transmissao do modelo mental.
|
|
|
|
Toda consolidacao em `learn` deve:
|
|
|
|
- partir de decisions ja fechadas;
|
|
- refletir o estado publicado em specs e/ou codigo;
|
|
- explicar o "como pensar" e nao so o "o que aconteceu";
|
|
- linkar para specs e decisions correspondentes;
|
|
- remover redundancia historica quando houver material sobreposto.
|
|
|
|
Regra de manutencao:
|
|
|
|
- de tempos em tempos, refatorar `learn` por tema, modelo mental e progressao didatica;
|
|
- preferir guias tematicos a acumulo cronologico de decisions aposentadas;
|
|
- preservar backlinks para decisions/specs originais.
|
|
|
|
## Workers Obrigatorios
|
|
|
|
### Agenda Worker
|
|
|
|
Use para abrir ou conduzir discussoes.
|
|
|
|
Responsabilidades:
|
|
|
|
- sintetizar pontos mais importantes;
|
|
- propor sugestoes concretas;
|
|
- separar sinal de ruido;
|
|
- empurrar para uma recomendacao.
|
|
|
|
Nao faz:
|
|
|
|
- fechar contrato normativo cedo demais;
|
|
- planejar implementacao detalhada.
|
|
|
|
### Decision Worker
|
|
|
|
Use para transformar agenda concluida em decisao clara.
|
|
|
|
Responsabilidades:
|
|
|
|
- cristalizar a decisao;
|
|
- registrar invariantes;
|
|
- preparar a propagacao para spec e implementacao;
|
|
- referenciar material normativo ja existente.
|
|
|
|
Nao faz:
|
|
|
|
- escrever plano de execucao detalhado;
|
|
- deixar ambiguidades estruturais escondidas.
|
|
|
|
### PR Worker
|
|
|
|
Use para transformar decisions em execucao.
|
|
|
|
Responsabilidades:
|
|
|
|
- decompor o trabalho;
|
|
- separar fases editorial e de codigo;
|
|
- definir aceite, testes, riscos e sequenciamento.
|
|
|
|
Nao faz:
|
|
|
|
- rediscutir arquitetura base;
|
|
- improvisar contrato no meio do plano.
|
|
|
|
### Learn Worker
|
|
|
|
Use para consolidar conhecimento e refatorar `docs/runtime/learn/`.
|
|
|
|
Perfil esperado:
|
|
|
|
- didatico;
|
|
- editorial;
|
|
- orientado a modelo mental, exemplos e progressao pedagogica.
|
|
|
|
Responsabilidades:
|
|
|
|
- consolidar varias decisions em artefatos mais ensinaveis;
|
|
- reorganizar material por tema;
|
|
- reduzir repeticao e melhorar navegacao.
|
|
|
|
Nao faz:
|
|
|
|
- redefinir contrato tecnico;
|
|
- competir com specs.
|
|
|
|
### Spec Worker
|
|
|
|
Use para implementar specs a partir de decisions e PRs.
|
|
|
|
Perfil esperado:
|
|
|
|
- editorial;
|
|
- normativo;
|
|
- preciso em contrato, escopo e linguagem.
|
|
|
|
Responsabilidades:
|
|
|
|
- atualizar ou criar specs coerentes com a decision;
|
|
- manter contrato tecnico consistente;
|
|
- citar referencias normativas corretas.
|
|
|
|
Nao faz:
|
|
|
|
- inventar decisao nova durante edicao;
|
|
- introduzir framing pedagogico de `learn` dentro do texto normativo.
|
|
|
|
### Code Worker
|
|
|
|
Use para implementar codigo a partir de decisions, specs e PRs.
|
|
|
|
Perfil esperado:
|
|
|
|
- executor;
|
|
- rigoroso;
|
|
- focado em comportamento, testes e aderencia ao contrato.
|
|
|
|
Responsabilidades:
|
|
|
|
- implementar o que a spec/decision manda;
|
|
- validar impacto e cobertura;
|
|
- apontar qualquer conflito entre codigo e contrato.
|
|
|
|
Nao faz:
|
|
|
|
- compensar ambiguidade arquitetural com heuristica local;
|
|
- esconder mudanca de contrato dentro de refactor.
|
|
|
|
## Regras de Transicao
|
|
|
|
- nunca criar PR de implementacao se o assunto ainda e uma agenda em aberto;
|
|
- toda agenda encerrada deve resultar em `decision` ou ser explicitamente descartada;
|
|
- toda decision relevante deve gerar `PR/plan` antes de alterar spec ou codigo;
|
|
- toda decision executada deve deixar consolidacao em `learn`, direta ou agrupada;
|
|
- quando `learn` acumular historico demais, ativar o `Learn Worker` para refatoracao didatica.
|
|
|
|
## Regra Editorial
|
|
|
|
- `agenda` discute;
|
|
- `decision` decide;
|
|
- `PR` planeja;
|
|
- `spec` normatiza;
|
|
- `codigo` implementa;
|
|
- `learn` ensina.
|
|
|
|
Se um artefato comecar a fazer o trabalho do outro, ele esta errado.
|