Uma arquitetura para o trabalho.
O modelo organiza responsabilidades, contexto e evidências. A IA participa da execução; a responsabilidade técnica continua explícita.
Três camadas que se conectam
- Contexto: requisitos, escopo, caminhos, contratos e decisões descrevem o sistema existente.
- Execução: tarefas pequenas, limites de módulo e regras proporcionais ao risco orientam a mudança.
- Evidência: testes, revisão, operação e aceite indicam o que foi realmente verificado.
O ciclo de uma entrega
- Delimitar o problema e seu critério de aceite.
- Ler o mapa e apenas as fontes necessárias para a tarefa.
- Inspecionar código e consumidores antes de escolher a alteração.
- Implementar o menor recorte coeso, preservando comportamento saudável.
- Validar o risco afetado e registrar resultado, divergências e limites.
- Revisar a entrega e tratar publicação e aceite como etapas próprias.
Ler por tarefa, não por volume
| Tarefa | Leitura principal | Ampliar quando |
|---|---|---|
| Orientação | PATHS.toml + PRD.md | For necessário entender arquitetura ou operação |
| Bug | BUGS.md + código + TESTES.md | Houver contrato, permissão, banco ou integração |
| UI | TELAS.md + código + TESTES.md | A mudança envolver regra ou persistência |
| Arquitetura | ESCOPO.md + QUALITY_ROADMAP.md + DECISOES.md | Houver impacto em consumidores ou deploy |
| Pacote | PRD + roadmap + governança + backlog | O fechamento exigir revisão integrada |
SOLID aplicado às fronteiras reais
Separar regra de negócio, apresentação, persistência e integração. Uma tela não deve assumir o banco; um caso de uso não deve depender de detalhes de interface. Nomes e pastas devem seguir o sistema existente, não um padrão imposto sem inspeção.
Em CRUD, separar lista/filtro, detalhe, criação e edição. Formulários podem ser compartilhados, mas não devem assumir roteamento, carregamento remoto e persistência ao mesmo tempo.
Pacote é objetivo. Lote é recorte.
Um pacote agrupa uma entrega maior; os lotes permitem evoluir em partes revisáveis. Em cada lote, execute testes focados. No fechamento do pacote, revise o conjunto, regressões, contratos, documentação e checks completos aplicáveis.
Documentação simples não deve disparar testes de aplicação sem necessidade. Em contrapartida, mudanças de regra, permissão, persistência ou integração exigem evidência mais forte.
Cobertura não é conclusão
A matriz distingue implementado e comprovado, implementado com lacuna, dependência externa, parcial, planejado, divergente e bloqueado. Um arquivo presente ou uma caixa marcada não torna uma funcionalidade pronta.
O gerador encontra e sincroniza itens do snapshot. A qualidade semântica da classificação continua dependendo de revisão humana. Nenhum check local prova, sozinho, publicação, restore, uso em dispositivo ou sucesso de negócio.
Operação é parte do projeto
RUNBOOK e GOVERNANCA mantêm procedimentos, riscos, observabilidade, retenção, smoke e rollback. Logs da aplicação não devem conter segredos ou dados pessoais desnecessários. Banco e publicação precisam de passos explícitos e reversíveis quando possível.
O kit original adota SQL por scripts e não migrations. Essa é uma convenção da base, não uma alegação de que todo projeto do mundo deva fazer o mesmo. Revise e documente adaptações antes de executar.