Designer de Harness de Codificação v1
"O que o agente não conseguiu fazer não foi por falta de habilidade, mas por falta de ambiente." — OpenAI "Não deixe o gerador avaliar seu próprio trabalho." — Anthropic "Se o agente cometer um erro, projete a engenharia para que ele nunca mais o repita." — Mitchell Hashimoto
Relação entre esta skill e o harness-designer
┌─────────────────────────────────────────────────────────────┐
│ Base Comum: 5 Pilares do Design de Harness │
│ Divulgação Progressiva / Imposição Mecânica / │
│ Ciclo de Feedback / Continuidade de Sessão / Gerenciamento de│
│ Entropia │
├──────────────────────────┬──────────────────────────────────┤
│ harness-designer (existente)│ coding-harness-designer (esta)│
│ Workspace de análise/decisão│ Workspace de codação/desenvolv.│
│ Agente = função de perspectiva│ Agente = trabalhador de codação│
│ Saída = relatórios/decisões │ Saída = código fonte/testes │
│ Validação = checklist/discussão│ Validação = CI/linters/testes │
│ "Design de sala de reunião" │ "Design de linha de fábrica" │
└──────────────────────────┴──────────────────────────────────┘
7 Pilares do Harness de Codificação
Aos 5 pilares existentes, adicionam-se 2 específicos para codação:
| Pilar | Pergunta Central | Princípio |
|---|---|---|
| Divulgação Progressiva | O agente vê apenas o necessário? | AGENTS.md ~100 linhas índice → docs/ |
| Imposição Mecânica | A arquitetura é imposta mecanicamente? | Linters, testes estruturais, CI |
| Ciclo de Feedback | Em caso de falha, o agente se autocorrige? | Mensagem de erro ensina como corrigir |
| Continuidade de Sessão | O handoff entre sessões é limpo? | progress + feature-status + git |
| Gerenciamento de Entropia | A qualidade do código se mantém com o tempo? | Varredura automática, refatoração, nota de qualidade |
| Rigidez Arquitetural ← Novo | Os limites dos módulos são impostos? | Regras de camada, verificação de direção de dependência |
| Runtime Observável ← Novo | O agente pode ver os resultados da execução? | Acesso a logs, métricas, DOM, screenshots |
Relação entre as Duas Camadas
┌─────────────────────────────────────────────────────────────┐
│ CAMADA 1: Meta (Papel desta skill) │
│ │
│ Planner ──→ Generator ──→ Evaluator │
│ ↑ (sequencial unidirecional, sem referência reversa)│
│ └──── Feedback se insuficiente ───────────────────┘ │
│ │
│ Objetivo: Projetar, criar e validar a estrutura do harness │
└─────────────────────────┬───────────────────────────────────┘
│ Após aprovação, harness concluído
▼
┌─────────────────────────────────────────────────────────────┐
│ CAMADA 2: Operacional (Papel do harness de codação concluído)│
│ │
│ ┌ Initializer (primeira execução)─→ Scaffold + config. ambiente│
│ │ │
│ └ Agente de Codação (execução repetida): │
│ 1. Ler progress → Selecionar próxima tarefa │
│ 2. Implementar (gerar código) │
│ 3. Autoverificação (testes, linters, navegador) │
│ 4. Solicitar revisão (revisão de código entre agentes) │
│ 5. Refletir feedback → Repetir │
│ 6. Commitar em estado limpo │
│ │
│ Objetivo: Escrever, testar, refatorar e implantar código │
└─────────────────────────────────────────────────────────────┘
CAMADA 1: Meta — Processo de Design do Harness de Codificação
3 Agentes L1 (Sequencial Unidirecional, Sem Referência Reversa)
Planner (Planejamento)
Analisa as necessidades do usuário e projeta a estrutura do harness de codação.
- Entrada: Requisitos do projeto (coletados por meio de perguntas)
- Saída: Design da arquitetura + estrutura de pastas + regras impostas + critérios de avaliação
Generator (Construção)
Transforma o design do Planner em arquivos e configurações reais.
- Entrada: Design aprovado pelo Planner
- Saída: AGENTS.md, docs/, regras de linter, configuração de CI, estrutura de teste
Evaluator (Validação)
Valida de forma independente a saída do Generator com base nos 7 pilares.
- Entrada: Arquivos gerados pelo Generator + critérios de avaliação do Planner
- Saída: Pontuação por pilar + validação funcional + feedback de melhoria
Fase L1 0: Correspondência de Padrões — Referência harness-100 (Novo v1.1)
"99% dos bons designs já foram feitos por alguém. Encontre e adapte."
Antes de iniciar a Descoberta, encontre o exemplar mais semelhante entre os exemplares validados do harness-100 (https://github.com/revfactory/harness-100, Apache-2.0) e use-o como referência. Para não desenvolvedores, redirecione para a skill harness-starter-coding.
Exemplares-alvo (27 domínios de codação)
- Dev&DevOps #16–30: fullstack-webapp, mobile-app-builder, api-designer, database-architect, devops-pipeline, security-audit, performance-tuning, refactoring-squad, test-automation, monitoring-setup, etc.
- Data&AI/ML #31–42: ml-experiment, data-pipeline, rag-llm-app, nlp-processor, recommendation-engine, design-system, etc.
Procedimento da Fase 0
- Extrair palavras-chave do tipo de aplicativo a partir da solicitação de 1-2 frases do usuário
- Apresentar os 3 principais candidatos dentre os 27 acima + confirmação do usuário
- Registrar o número do exemplar selecionado no campo
reference_exemplarde_workspace/00_input.md - Similaridade de correspondência < 0.5 → Fallback para modo de design livre (prosseguir para a Fase 1 existente)
Refletir o Resultado da Fase 0 nas Etapas Seguintes
- Planner: Usar a composição de 5 agentes do exemplar como base, ajustando de acordo com o Modo de Escala (Completo/Reduzido/Único)
- Generator: Usar o scaffold do esqueleto do exemplar como prioridade, impor a convenção de numeração
_workspace/NN_*.md - Evaluator: Usar os 8 itens dos Padrões de Qualidade do exemplar (Modo de Equipe de Agentes / Experiência em Domínio / Saídas Estruturadas / DAG de Dependências / Tratamento de Erros / Modos de Escala / Cenários de Teste / Limites de Gatilho) como rubrica
Fidelidade do Padrão (Avaliação Qualitativa, Apenas na Fase 0)
Não incluído na pontuação automática dos 7 pilares. Avaliado qualitativamente durante a correspondência de exemplares na Fase 0.
Verificar separadamente os 8 Padrões de Qualidade do exemplar do harness-100 selecionado na Fase 0 (Modo de Equipe de Agentes / Experiência em Domínio / Saídas Estruturadas / DAG de Dependências / Tratamento de Erros / Modos de Escala / Cenários de Teste / Limites de Gatilho) em relação à pontuação do Evaluator.
- Momento de aplicação: 1 vez na Fase 0 (seleção de exemplar) e 1 vez no relatório após PASS do Evaluator
- Sem pontuação: Não incluído na pontuação dos 23 itens dos 7 pilares
- pillar-weight: Apenas o ajuste de peso dos 7 pilares é possível. Fidelidade do Padrão não é alvo de ponderação
Limites de Gatilho (deve + NÃO)
O Planner/Generator deve incluir uma seção should-NOT trigger no skill.md do orchestrator gerado. Exemplo: "Não usar para aplicativos móveis, microsserviços empresariais, sites estáticos".
Princípios de Comportamento do Agente de Codação (Inspirado em Karpathy, Injeção Obrigatória)
O Generator deve incluir a seção abaixo ao final do .claude/CLAUDE.md gerado. Esses 4 princípios são sincronizados com a skill karpathy-guidelines (instalada independentemente) e se tornam as diretrizes básicas de comportamento para todos os agentes de codação dentro do harness.
## Princípios de Comportamento do Agente de Codação (Inspirado em Karpathy)
Todos os agentes de codação devem seguir os 4 princípios abaixo durante o trabalho.
Consulte a skill karpathy-guidelines para detalhes (gatilho automático).
1. Pense Antes de Codificar — Explicitar suposições, perguntar se ambíguo, apresentar alternativas
2. Simplicidade Primeiro — Apenas o solicitado. Sem abstrações ou funcionalidades especulativas
3. Mudanças Cirúrgicas — Alterar apenas as linhas solicitadas. Sem melhorias no código ao redor
4. Execução Orientada a Objetivos — Critérios de sucesso verificáveis → Loop → Confirmação
Adicionar o item "Existência da seção dos 4 princípios de Karpathy no CLAUDE.md" ao checklist do Evaluator.
Modos de Escala (Valor Padrão da Camada Operacional)
| Modo | Composição do Agente |
|---|---|
| Completo | architect + frontend + backend + qa + devops |
| Backend | architect + backend + qa |
| Frontend | architect + frontend + qa |
| Refatoração | architect + desenvolvedor relevante + qa |
| DevOps | devops sozinho |
Fase L1 1: Descoberta — Operação do Planner
A Descoberta é composta por 4 estágios de perguntas. Cada estágio é realizado em ordem, mas as perguntas subsequentes se ramificam de acordo com a resposta do usuário. Após receber a resposta de um estágio, passe para o próximo. Não pergunte tudo de uma vez.
1-1. Estágio 1 — Propósito e Contexto (POR QUÊ / QUEM)
Entenda a razão de existir deste projeto, não a tecnologia.
P1. Qual problema este projeto pretende resolver?
(Qual incômodo/ineficiência está tentando eliminar?)
P2. Quem o utiliza?
(Funcionários internos / Clientes / Desenvolvedores / Público em geral)
→ Seguimento: Número de usuários? Proficiência em TI?
P3. Qual é o critério de sucesso deste projeto?
(O que significa "bem feito"?)
P4. Existe um sistema semelhante existente?
(É uma substituição / Criação do zero?)
→ Seguimento [Substituição]: Maior problema do sistema existente?
→ Seguimento [Novo]: Existe algum serviço de referência?
Ramificação de perguntas subsequentes:
- P2 "Funcionários internos" → "Quantos? Existe estrutura departamental? Necessário sistema de permissões?"
- P2 "Clientes" → "Método de cadastro? Há pagamento? Tratamento de dados pessoais?"
- P3 Menção de números específicos → "Como medir esse número?"
- P3 Resposta vaga → "Especificamente, qual tela/funcionalidade funcionando seria considerado sucesso?"
1-2. Estágio 2 — Funcionalidades e Conteúdo (O QUÊ)
O que contém, quais são as funcionalidades principais.
F1. Liste as 3 principais funcionalidades em ordem de prioridade?
(Da que precisa funcionar primeiro)
F2. Qual a natureza dos dados?
(Relacional / Documentos / Séries temporais / Arquivos / Misto)
→ Seguimento: As relações entre dados são complexas? Agregações/estatísticas são importantes?
F3. Existem requisitos de autenticação/autorização?
(Nenhum / Login simples / Baseado em funções / Permissões hierárquicas de organização)
→ Seguimento [Baseado em funções ou superior]: Quantos níveis de permissão? Necessário isolamento de dados?
F4. Existe integração com sistemas externos?
(Nenhum / Integração de API / Importação/exportação de arquivos / Pagamento / Notificações)
F5. Suporte offline ou para dispositivos móveis é necessário?
Ramificação de perguntas subsequentes:
- F1 Mais de 3 funcionalidades → "Qual a complexidade de cada funcionalidade: alta/média/baixa?"
- F2 "Misto" → "Quais tipos estão misturados? É necessário separar repositórios?"
- F3 "Hierarquia organizacional" → "A adição/alteração de departamentos é frequente? Deve ser expansível sem alteração de código?"
1-3. Estágio 3 — Tecnologia e Estrutura (COMO)
Como será construído. Reflita as respostas dos Estágios 1-2 para sugerir tecnologias adequadas.
T1. Prefere alguma pilha de tecnologia?
(Especificar se houver / "Me recomende")
→ Recomendar "tecnologia chata": Agentes funcionam melhor com tecnologias
estáveis e com abundância de dados de treinamento (proposta original da OpenAI)
→ Sugerir pilha adequada com base nas respostas dos Estágios 1-2
T2. Ambiente de implantação?
(Vercel / AWS / Servidor local / Não sei)
T3. Ferramenta de agente de codação?
(Claude Code / Codex / Cursor / Outros)
→ A configuração do harness varia de acordo com a ferramenta
T4. Nível de autonomia do agente?
(Humano revisa e faz merge / Revisão entre agentes e merge automático / Totalmente autônomo)
T5. Escala e duração do projeto?
(Protótipo 1-2 semanas / Médio porte 1-3 meses / Grande porte longo prazo)
T6. Existe base de código existente?
(Novo / Aplicar harness a código existente)
→ Se código existente, projetar estratégia de aplicação gradual
Ramificação de perguntas subsequentes:
- T1 "Me recomende" → Apresentar tabela comparativa de 2-3 opções com base nas respostas dos Estágios 1-2 e solicitar escolha
- T2 "Não sei" → Recomendar com base no tamanho do usuário e funcionalidades
- T5 "Grande porte" → "Tamanho da equipe? Número de agentes trabalhando simultaneamente?"
1-3.5. Estágio 3.5 — Histórico de Alterações de Fluxo (HISTÓRICO DE FLUXO) [Opcional]
Recomendado para projetos de longo prazo ou quando houver possibilidade de evolução do harness de codação ao longo de várias sessões. Pode ser ignorado para protótipos de 1-2 semanas.
F1. "Deseja manter um histórico quando prompts, protocolos, modelos, scripts de API, comandos e CLAUDE.md forem alterados no futuro?"
Finalidade:
- Retrospectiva do histórico de melhoria do projeto (por que mudou)
- Garantir fundamentos quando for necessário reverter para versão anterior
- Referência para o design do próximo harness de codação semelhante
※ Não se destina a ser lido a cada nova sessão.
Referenciado apenas ao modificar, reverter ou transplantar o fluxo.
→ "Não" → Não incluir 05-flow-history/. Ir para o Estágio 4.
→ "Sim" → Ir para F2.
F2. "Deseja registrar automaticamente o build inicial (v1) como um registro de change 0001?"
- Valor padrão: Sim (as respostas da Descoberta do Planner são preservadas como justificativa de design)
- Não → Apenas criar CHANGELOG e registrar manualmente na primeira alteração
Princípios de gerenciamento de histórico de fluxo (com base operacional pós-criação):
Este histórico registra apenas mudanças no sistema de fluxo de trabalho (prompts, protocolos, modelos, scripts de API, comandos, CLAUDE.md).
As saídas geradas pelo sistema (código, relatórios, resultados de análise) não são alvo de registro.
Critério de distinção: "Se esta alteração não tivesse ocorrido, o resultado da próxima execução seria diferente?"
→ Diferente = mudança no sistema = registrar / Não diferente = saída = registro desnecessário
Detalhes: 00-system/protocols/flow-change-protocol.md
Adicionar à saída do Planner (relacionado a flow-history):
flow_history_enabled: true/falseflow_history_initial_record: true/false(resposta de F2)
1-4. Estágio 4 — Qualidade e Critérios de Avaliação (QUALIDADE / AVALIAR)
Entenda os valores que o usuário considera importantes e chegue a um acordo sobre os critérios de avaliação.
E1. Quais os atributos de qualidade mais importantes neste projeto? (Selecione os 3 principais)
□ Segurança (permissões, isolamento de dados, autenticação)
□ Desempenho (velocidade de resposta, acesso simultâneo)
□ Escalabilidade (expandir escala sem alteração de código)
□ Manutenibilidade (outra pessoa/agente pode modificar facilmente)
□ Experiência do Usuário (UI intuitiva, resposta rápida)
□ Testabilidade (garantia de qualidade por meio de testes automatizados)
□ Lançamento Rápido (MVP primeiro, qualidade depois)
□ Consistência de Dados (registros precisos, sem perda)
E2. Existem planos de expansão futura?
(Nenhum / Adição de funcionalidades / Integração com outros sistemas / Expansão da base de usuários)
→ Seguimento: Especificamente, que tipo de expansão? Quando?
E3. O que nunca pode ser comprometido neste projeto?
(Exemplo: "O isolamento de permissões não pode ser quebrado", "Os dados não podem ser perdidos")
E4. Por outro lado, o que pode ser deixado para depois no início?
(Exemplo: "Suporte para dispositivos móveis depois", "Painel de estatísticas na segunda fase")
Ramificação de perguntas subsequentes:
- E1 Seleção de "Segurança" → "Que tipo de segurança? Autenticação/autorização/criptografia de dados/logs de auditoria?"
- E2 "Integração com outros sistemas" → "Quais sistemas? O formato de dados é compatível?"
- Resposta de E3 → Usar como entrada principal para os pesos do Evaluator
1-5. Acordo de Pesos de Avaliação (Após Conclusão do Estágio 4)
Analisar as respostas dos Estágios 1-4 para propor pesos para os 7 pilares. Chegar a um acordo com o usuário para finalizá-los.
[PROCESSO DE PROPOSTA DE PESOS]
ETAPA 1. Extrair palavras-chave das respostas dos Estágios 1-4
- "Isolamento de permissões" → Imposição Mecânica, Rigidez Arquitetural ↑
- "Expandir sem alteração de código" → Rigidez Arquitetural ↑
- "Lançamento rápido" → Gerenciamento de Entropia ↓, Runtime Observável ↑
- "Consistência de dados" → Ciclo de Feedback ↑, Imposição Mecânica ↑
ETAPA 2. Ajustar a partir dos pesos padrão e propor
Pesos padrão (antes de refletir as características do projeto):
| Pilar | Padrão | Justificativa do Ajuste | Proposta |
|------|------|----------|------|
| Divulgação Progressiva | 15% | (Justificativa de variação) | ?% |
| Imposição Mecânica | 20% | (Justificativa de variação) | ?% |
| Ciclo de Feedback | 15% | (Justificativa de variação) | ?% |
| Continuidade de Sessão | 10% | (Justificativa de variação) | ?% |
| Gerenciamento de Entropia | 10% | (Justificativa de variação) | ?% |
| Rigidez Arquitetural | 20% | (Justificativa de variação) | ?% |
| Runtime Observável | 10% | (Justificativa de variação) | ?% |
"Considerando [justificativa] neste projeto,
o peso de [pilar] foi ajustado de [padrão]% para [proposta]%.
Por favor, compartilhe sua opinião ou correções."
ETAPA 3. Refletir o feedback do usuário
- Concordo → Finalizado
- "Aumente a segurança" → Aumentar peso dos pilares relacionados, diminuir outros e repropor
- "Este pilar não é necessário" → Definir como 0%, redistribuir os restantes e repropor
ETAPA 4. Aprovação final
"Pesos finais confirmados. O Evaluator pontuará com estes pesos."
→ Usar estes pesos acordados em vez dos pesos padrão do evaluator-protocol.md
1-6. Mapeamento Automático de Padrões de Arquitetura
→ Consulte references/architecture-patterns.md
→ Propor o padrão mais adequado com base nas respostas dos Estágios 2-3
| Tipo de Aplicativo | Estrutura de Camadas Recomendada |
|---|---|
| Aplicativo Web Full Stack | Types→Config→Repo→Service→Runtime→UI |
| Serviço de API | Types→Config→Repo→Service→Runtime |
| Ferramenta CLI | Types→Config→Core→CLI |
| Biblioteca | Types→Core→Public API |
1-7. Saídas do Planner
① Resumo do Contexto do Projeto — Propósito, usuários, critério de sucesso, restrições principais (com base nos Estágios 1-2) ② Proposta de Design de Arquitetura — Estrutura de camadas, limites de módulos, direção de dependências ③ Esboço da Estrutura de Pastas — Com base em references/coding-folder-patterns.md ④ Design de Regras Impostas — Quais regras são impostas por linters/CI/testes estruturais ⑤ Estratégia de Teste — Escopo de unidade/integração/E2E e critérios de cobertura ⑥ Design de Autonomia do Agente — Loop de revisão, portões de aprovação, critérios de escalonamento ⑦ Estratégia de Expansão — Decisões de design preparadas para expansão futura (com base no Estágio 4 E2) ⑧ Critérios de Avaliação + Pesos Acordados — Checklist dos 7 pilares + tabela de pesos
[Planner concluído — Solicitar aprovação do usuário]
Revise ①~⑧ e informe as correções.
Após aprovação, o Generator iniciará a construção.
Fase L1 2: Construção — Operação do Generator
2-1. Geração de Saídas Principais (Em Ordem)
| Sequência | Saída | Descrição |
|---|---|---|
| 2-1a | Diagrama de arquitetura | Mermaid — Camadas, módulos, direção de dependência |
| 2-1b | AGENTS.md (~100 linhas) | Função de índice, incluindo roteamento de referência |
| 2-1c | Diretório docs/ | Detalhamento abaixo |
| 2-1d | Regras de imposição de arquitetura | Regras de linter + testes estruturais |
| 2-1e | Design de pipeline CI/CD | Definição de portões de validação |
| 2-1f | Estrutura de teste | Diretório de teste + configuração básica |
| 2-1g | Saídas de handoff de sessão | progress.json + feature-status.json |
| 2-1h | Configuração do loop de revisão de código | Protocolo de revisão entre agentes |
| 2-1i | Configuração de observabilidade | Método de acesso a logs, métricas, DOM |
| 2-1j | README.md | Guia do desenvolvedor |
| 2-1k | Inicialização do projeto bkit | Executar somente após pergunta de opt-in do usuário se T3 detectar Claude Code + bkit instalado (detalhamento abaixo) |
| 2-1l | Configuração do ambiente | Ambiente virtual, variáveis de ambiente, hooks — Não forçar criação. Sugestão do LLM na Fase 3-7 e escolha do usuário |
| 2-1m | Wiki de histórico de alterações de fluxo (opcional) | Apenas se Estágio 3.5 F1=Sim. Consultar ~/.claude/skills/harness-designer-workspace/references/flow-history-template.md e criar 05-flow-history/ + 00-system/protocols/flow-change-protocol.md. Adicionar 2 linhas de roteamento ao AGENTS.md + seção "Rastreamento de alterações de fluxo (registro seletivo)". Princípio de gerenciamento: Registrar apenas mudanças no sistema (regras, procedimentos, ferramentas). Saídas (código, relatórios) não precisam de registro. Critério de distinção: "Se esta alteração não tivesse ocorrido, o resultado da próxima execução seria diferente?" |
2-1b. Regras de Criação do AGENTS.md (Mais Importante)
→ Consulte references/agents-md-template.md
Aplique diretamente as principais lições da proposta original da OpenAI:
Índice de ~100 linhas. Não é uma enciclopédia.
# [Nome do Projeto]
> [Descrição em uma linha]
## Visão Geral da Arquitetura
[Resumo da estrutura de camadas em 3 linhas]
→ Detalhes: docs/architecture.md
## Roteamento de Referência
| Situação | Arquivo para Ler |
|------|----------|
| Regras de arquitetura | → docs/architecture.md |
| Convenções de codação | → docs/conventions.md |
| Design de domínio | → docs/design/[dominio].md |
| Plano de execução | → docs/exec-plans/[plano].md |
| Nota de qualidade | → docs/quality-grades.md |
| Dívida técnica | → docs/exec-plans/tech-debt-tracker.md |
| Estado da sessão | → progress.json |
| Status da funcionalidade | → feature-status.json |
## Regras Principais (Até 5)
1. [Regra imutável 1 — Exemplo: "Validar forma dos dados em todos os limites"]
2. [Regra imutável 2 — Exemplo: "Proibir dependência reversa entre camadas"]
3. [Regra imutável 3]
## Regras de Teste
→ docs/testing-strategy.md
## Comandos
| Comando | Função |
|--------|------|
| /implementar [funcionalidade] | Implementar funcionalidade |
| /revisar | Executar revisão de código |
| /testar | Executar testes |
| /refatorar [alvo] | Refatorar |
## Última Atualização: AAAA-MM-DD
2-1c. Diretório docs/ (Sistema de Registro)
→ Consulte references/docs-structure.md
docs/
├── architecture.md ← Estrutura de camadas, limites de módulos, direção de dependências
├── conventions.md ← Convenções de codação, nomenclatura, estilos
├── testing-strategy.md ← Estratégia de teste (cobertura, ferramentas, cenários)
├── quality-grades.md ← Critérios de nota de qualidade e método de medição
├── design/ ← Documentos de design por domínio/funcionalidade
│ ├── [dominio1].md
│ └── [dominio2].md
└── exec-plans/ ← Planos de execução e rastreadores
├── [plano1].md
└── tech-debt-tracker.md
2-1d. Regras de Imposição de Arquitetura
→ Consulte references/imposition-rules.md
Regras de Linter (exemplo):
- eslint-plugin-import: Proibir imports de camadas superiores para inferiores
- Regra personalizada: Proibir importação direta de ORM nos controladores
- Regra de nomenclatura: Nomes de arquivos de teste devem terminar com .test.ts
Testes Estruturais (exemplo, com arquitetura):
- src/controllers/ não pode importar src/repositories/
- src/services/ pode importar src/repositories/ mas não src/controllers/
- src/types/ não pode importar nenhum outro diretório
Scripts de Validação:
- scripts/validate-layers.sh: Verificar regras de direção de dependência
- scripts/check-naming.sh: Verificar convenções de nomenclatura
2-1e. Design de Pipeline CI/CD
→ Consulte references/ci-pipeline.md
Portões de Validação (Em Ordem):
- Lint (ESLint + Prettier) — Falha → Bloqueio
- Testes estruturais (validação de direção de dependência) — Falha → Bloqueio
- Testes unitários (cobertura mínima: 80%) — Falha → Relatório (não bloqueia)
- Testes de integração — Falha → Bloqueio
- Testes E2E — Falha → Relatório (não bloqueia merge automático)
- Verificação de qualidade (nota 7+ / 10) — Falha → Relatório + atribuição de dívida técnica
2-1f. Estrutura de Teste
→ Consulte references/testing-patterns.md
tests/
├── unit/ ← Testes unitários (por módulo)
│ ├── controllers/
│ ├── services/
│ └── repositories/
├── integration/ ← Testes de integração (interação entre módulos)
├── e2e/ ← Testes end-to-end (fluxo do usuário)
├── structural/ ← Testes estruturais (direção de dependência, conformidade de nomenclatura)
├── fixtures/ ← Dados de teste fixos
└── setup.ts ← Configuração global de teste
2-1g. Saídas de Handoff de Sessão
→ Consulte references/session-handoff.md
progress.json
{
"current_phase": "build",
"completed_tasks": ["setup-project", "implement-auth"],
"in_progress": "implement-user-api",
"blockers": ["pending-approval-arch"]
}
feature-status.json
{
"auth": { "status": "done", "coverage": 92, "quality_grade": 8 },
"user-api": { "status": "wip", "coverage": 45, "quality_grade": 6 },
"dashboard": { "status": "pending", "coverage": 0, "quality_grade": null }
}
2-1h. Configuração do Loop de Revisão de Código
→ Consulte references/review-loop.md
Protocolo de Revisão de Código:
1. Quando um agente completa a implementação de uma funcionalidade:
→ Executar lint + testes
→ Atualizar progress.json
→ Solicitar revisão via /revisar [funcionalidade]
2. O agente revisor verifica:
- Conformidade com a arquitetura (direção de dependência adequada)
- Erros lógicos (casos extremos, tratamento de erros)
- Consistência de estilo (convenções de codação)
- Cobertura de teste (caminho feliz + casos de erro)
3. Resultado da revisão:
- Aprovado → Merge automático (se nível de autonomia permitir)
- Aprovado condicional → Corrigir itens apontados e re-revisar
- Reprovado → Retornar ao agente implementador com motivos
4. Feedback loop:
- Se o mesmo erro se repetir em 3 revisões consecutivas:
→ Adicionar regra de linter ou item ao checklist para evitar recorrência
2-1i. Configuração de Observabilidade
→ Consulte references/observability.md
Logs:
- Logs estruturados (JSON) com nível, carimbo de data/hora, módulo, ID de rastreamento
- Todos os logs de erro incluem stack trace e contexto
Métricas:
- Tempo de resposta do endpoint (p50/p95/p99)
- Taxa de erro por módulo
- Cobertura de teste por módulo
Acesso ao DOM (para aplicativos web):
- Snapshot do DOM salvo em caso de falha de teste E2E
- Comparação de capturas de tela para detecção de regressão visual
2-1k. Inicialização do Projeto bkit (Somente Opt-in)
Se:
- T3 = Claude Code
- bkit CLI detectado no ambiente
- Workspace atual não é um projeto bkit (nenhum .bkit/ diretório)
Então:
PERGUNTAR AO USUÁRIO: "Deseja inicializar este workspace como um projeto bkit?
Isso adicionará configuração de automação de fluxo de trabalho de desenvolvimento e
infraestrutura de mudança de protocolo. (Recomendado para projetos de longo prazo)"
- Sim → Executar 'bkit init' e proceder
- Não → Pular. Registrar em _workspace/config.json: "bkit_initialized": false
2-1l. Configuração do Ambiente (Somente Sugestão do LLM)
NÃO gerar .env, .venv ou arquivos de configuração do ambiente automaticamente.
Em vez disso, na Etapa de Operação (Fase 3-7), quando o LLM detectar a necessidade,
faça a sugestão:
"Parece que este projeto precisa de configuração de ambiente.
Deseja que eu configure:
1. Ambiente virtual Python (venv)
2. Variáveis de ambiente (.env + .env.example)
3. Hooks do git (pre-commit, commit-msg)
?"
Somente criar após obter opt-in do usuário.
Fase L1 3: Validação — Operação do Evaluator
3-1. Critérios de Avaliação dos 7 Pilares
| Pilar | Item de Avaliação | Descrição | Peso |
|---|---|---|---|
| Divulgação Progressiva | PD-1 | AGENTS.md existe e é um índice de ~100 linhas | ?% |
| PD-2 | Cada seção do AGENTS.md referencia docs/ adequadamente | ||
| PD-3 | O conteúdo de docs/ é detalhado o suficiente para o agente trabalhar | ||
| PD-4 | As informações não estão duplicadas (um único sistema de registro) | ||
| Imposição Mecânica | ME-1 | A direção de dependência é imposta por testes estruturais | ?% |
| ME-2 | As regras de lint são aplicadas no CI | ||
| ME-3 | Os portões de validação do CI são definidos e funcionam | ||
| ME-4 | A cobertura de teste mínima é definida e imposta | ||
| Ciclo de Feedback | FB-1 | As mensagens de erro incluem instruções de correção | ?% |
| FB-2 | Falha no teste → Rastreabilidade até o código relevante | ||
| FB-3 | Existe loop de revisão de código entre agentes | ||
| FB-4 | Erros repetidos são rastreados e evitados | ||
| Continuidade de Sessão | SC-1 | progress.json e feature-status.json existem e estão atualizados | ?% |
| SC-2 | Os commits são atômicos com mensagens de commit consistentes | ||
| SC-3 | O estado da sessão pode ser restaurado apenas com progress.json | ||
| SC-4 | Não há suposições não verificadas entre sessões | ||
| Gerenciamento de Entropia | EM-1 | Nota de qualidade é calculada e registrada automaticamente | ?% |
| EM-2 | A dívida técnica é rastreada (tech-debt-tracker.md) | ||
| EM-3 | É realizada varredura periódica automática de qualidade | ||
| EM-4 | A refatoração é priorizada com base na nota de qualidade | ||
| Rigidez Arquitetural | AR-1 | Os limites de camada são claramente definidos e documentados | ?% |
| AR-2 | As regras de dependência são validadas automaticamente | ||
| AR-3 | Os limites de módulo são impostos (cada módulo tem API pública) | ||
| AR-4 | A introdução de dependência circular é bloqueada no CI | ||
| Runtime Observável | OR-1 | Logs estruturados são configurados e acessíveis | ?% |
| OR-2 | Métricas principais podem ser consultadas | ||
| OR-3 | O agente pode ver o resultado da execução (DOM, screenshot, etc.) | ||
| OR-4 | Há uma maneira de depurar falhas (stack trace, replay) |
3-2. Pontuação
Cada item de avaliação:
- 0: Não implementado
- 1: Implementado parcialmente (base existe, mas incompleto) |
- 2: Implementado e em funcionamento
Nota do pilar = (soma das pontuações dos itens de avaliação) / (número de itens de avaliação × 2) × 100 Nota geral = Σ(nota do pilar × peso do pilar)
3-3. Limiar de Aprovação
- Mínimo: Cada pilar individual ≥ 50% OU nota geral ≥ 75%
- Se aprovado → "Harness de codação [nome do projeto] foi aprovado. Pronto para a Camada Operacional."
- Se reprovado → Feedback detalhado por pilar + itens de melhoria prioritários → Retornar ao Generator (Fase 2)
3-4. Saída do Evaluator
① Pontuação por pilar (tabela de notas por item de avaliação) ② Nota geral (calculada com pesos acordados) ③ Resultado da aprovação/reprovação ④ Itens de melhoria prioritários (em caso de reprovação, agrupados por pilar) ⑤ Observações/riscos (pontos não diretamente relacionados aos pilares, mas que precisam de atenção)
[Evaluator concluído]
Resultado: [APROVADO/REPROVADO]
Nota Geral: [XX]%
Pontuação por Pilar:
| Pilar | Peso | Nota |
|------|------|------|
| Divulgação Progressiva | XX% | XX% |
| Imposição Mecânica | XX% | XX% |
| ... | ... | ... |
[Em caso de aprovação]
"O harness de codação foi validado e atende aos critérios de qualidade.
Agora você pode iniciar o desenvolvimento na Camada Operacional."
[Em caso de reprovação]
"Foram encontrados os seguintes problemas. Após a melhoria, execute o Evaluator novamente."
- Pilar [Nome]: [Itens de melhoria]
CAMADA 2: Operacional — Desenvolvimento Usando o Harness de Codação Concluído
A Camada 2 é a etapa onde o agente de codação realmente desenvolve usando o harness de codação concluído. Esta camada é construída automaticamente pelo Generator e não requer design separado.
Diretrizes de Expressão
Use as seguintes expressões ao interagir com o usuário:
- "crie um harness de codação para mim"
- "projete um workspace de desenvolvimento"
- "configure um ambiente de codação de agente"
- "CLAUDE.md para projeto de codação"
- "projete um pipeline de CI"
- "construa um loop de revisão de código"
- "ambiente de codação autônomo"
- "ambiente de desenvolvimento de agente"
- "coding harness"
- "desenvolvimento orientado a agente"
- "build harness for coding"
- "configuração de workspace de desenvolvimento"
- "ambiente de codação autônomo"