Imported from emilianoeloi/cowboy (.github/skills/harness/SKILL.md). Install upstream with npx skills add emilianoeloi/cowboy --skill harness. Copyright stays with the author (MIT).

Harness do Projeto (Claude Code + Codex + GitHub Copilot + ADK)

Trate o projeto como dois contextos de execução:

1. O harness de desenvolvimento governa Claude Code, Codex ou GitHub Copilot (VS Code) enquanto alteram o repositório.
2. O harness de runtime governa agentes que a aplicação executa com Google ADK.

Identifique primeiro qual contexto e qual host a solicitação afeta. Não pressuponha que um artefato documentado exista ou esteja ativo.

Inventariar antes de diagnosticar

Execute um inventário mínimo:

git status --short
rg --files -uu \
  -g 'AGENTS.md' -g 'AGENTS.override.md' -g 'CLAUDE.md' \
  -g '.agents/**' -g '.claude/**' -g '.codex/**' \
  -g '.github/copilot-instructions.md' -g '.github/instructions/**' \
  -g '.github/prompts/**' -g '.github/agents/**' -g '.github/hooks/**' \
  -g '.github/skills/**' -g '.mcp.json' -g '.pre-commit-config.yaml' \
  -g '.github/workflows/**' -g 'tests/**' -g 'harness/**'

Classifique cada item citado na documentação como:

• ativo: existe e o host o descobre;
• presente, mas não conectado: existe sem mecanismo de carregamento;
• planejado: aparece apenas em documentos;
• ausente: não existe e não está declarado como plano.

Relate essa classificação. Nunca descreva um sensor planejado ou ausente como proteção ativa.

Harness de desenvolvimento

Camada compartilhada

Mantenha regras compartilhadas em um ponto canônico sempre que possível. Se uma regra continuar em CLAUDE.md, preserve em AGENTS.md a instrução explícita para o Codex e o Copilot lerem esse arquivo. Nunca crie .github/copilot-instructions.md junto de AGENTS.md — o VS Code trata os dois como alternativos e recomenda usar apenas um.

Claude Code

Use /doctor para conferir instruções e skills e /hooks para inspecionar hooks carregados.

OpenAI Codex

Use /skills para confirmar a descoberta do skill e /hooks para revisar, confiar e depurar hooks. Reinicie a sessão se instruções antigas continuarem em contexto.

Não trate .claude/commands/, .claude/agents/ ou .claude/settings.json como configuração automática do Codex. Porte o comportamento necessário para os equivalentes do Codex.

GitHub Copilot (VS Code)

Skills e a leitura de AGENTS.md já funcionam sem trabalho extra, pois o Copilot os descobre nos mesmos caminhos usados pelo Codex. Hooks e subagentes especializados (.claude/agents/, .claude/settings.json) não são portados automaticamente — recrie-os em .github/hooks/ e .github/agents/ quando o comportamento precisar ser garantido também no Copilot.

Harness de runtime (Google ADK)

Descubra a implementação real antes de listar componentes. Procure agentes, ferramentas, callbacks, políticas e avaliações:

rg -n -uu 'google\.adk|Agent\(|BaseAgent|tool|callback|guard|eval' \
  --glob '*.py' --glob '!**/.venv/**'

Considere como sensores de runtime somente os componentes efetivamente importados ou executados pela aplicação. AGENTS.md configura o Codex; ele não configura agentes Google ADK automaticamente. Só o classifique como prompt de runtime se o código da aplicação o carregar de modo explícito.

Diagnosticar uma regra ignorada

1. Localizar a regra

rg -n -uu '<palavra-chave>' \
  AGENTS.md CLAUDE.md .agents .claude .codex tests pyproject.toml

Se a regra não estiver documentada, adicione um guia inferencial no host correto.

2. Localizar o mecanismo de aplicação

Verifique hooks, testes, pre-commit e CI existentes. Separe uma recomendação ao modelo de um bloqueio determinístico.

3. Confirmar descoberta e execução

• No Claude Code, inspecione /doctor e /hooks.
• No Codex, inspecione /skills e /hooks; confirme que o projeto está confiável para carregar .codex/.
• No GitHub Copilot, confirme que o skill aparece no seletor de barra (/) e que .github/hooks/*.json está versionado; skills em .agents/skills/ não exigem passo extra.
• Para sensores compartilhados, execute diretamente o comando configurado e observe o código de saída.
• Para runtime ADK, rastreie o ponto de importação/registro e execute o teste ou avaliação correspondente.

4. Fortalecer a camada certa

Converta falhas repetidas de instrução em sensores determinísticos quando houver uma condição objetivamente verificável. Prefira testes, análise estática, pre-commit ou CI para invariantes de código; use hooks para feedback rápido dentro do host.

Adicionar guias

Regra compartilhada

Atualize o contexto canônico do projeto e confirme que ambos os entrypoints de desenvolvimento chegam até ele. Evite copiar parágrafos longos entre CLAUDE.md e AGENTS.md.

Regra apenas do Claude Code

Use CLAUDE.md para regra global, .claude/rules/ para escopo por caminho e .claude/skills/ para fluxos reutilizáveis.

Regra apenas do Codex

Use AGENTS.md para regra global, um AGENTS.md aninhado para escopo de diretório e .agents/skills/ para fluxos reutilizáveis. Inclua apenas name e description no frontmatter de SKILL.md; mantenha metadados de interface em agents/openai.yaml.

Regra apenas do GitHub Copilot

Use .github/instructions/*.instructions.md com applyTo para escopo por caminho, .github/prompts/ para tarefas parametrizadas e .github/agents/*.agent.md para subagentes com ferramentas restritas. Skills reutilizáveis não precisam de cópia própria: reaproveite .agents/skills/.

Regra de runtime ADK

Coloque a instrução no prompt, spec ou configuração realmente consumida pelo agente. Adicione um teste ou eval que prove o comportamento.

Adicionar sensores

Priorize sensores compartilhados quando a regra independer do host:

1. teste unitário ou estrutural;
2. lint ou typecheck;
3. pre-commit;
4. CI.

Use hooks específicos para antecipar o feedback:

• Claude Code: .claude/settings.json;
• Codex: .codex/hooks.json, com scripts em .codex/hooks/;
• GitHub Copilot: .github/hooks/*.json, um arquivo por hook, sem matcher — o script recebido decide com base em tool_name.

Ao portar hooks, adapte o formato de entrada. Em hooks do Codex, apply_patch aparece como tool_name: "apply_patch" e o patch fica em tool_input.command; não conte com tool_input.file_path. Em hooks do Copilot, ferramentas de edição (create_file, replace_string_in_file) expõem tool_input.filePath diretamente, mais próximo do formato do Claude Code do que do Codex.

Teste cada script de hook diretamente com JSON representativo em stdin. Para bloqueio em PreToolUse, emita uma decisão suportada ou encerre com código 2 e uma mensagem em stderr.

Medir a saúde

Concluir a alteração

1. Valide o frontmatter do skill.
2. Valide JSON/TOML e execute scripts adicionados.
3. Execute os testes relevantes do repositório.
4. Revise git diff --check e git diff.
5. Informe separadamente o que ficou ativo, o que depende de confiança/reinício e o que continua apenas planejado.

Referências

• AGENTS.md
• CLAUDE.md
• .claude/settings.json
• .codex/hooks.json
• AGENTS.md no Codex
• Skills no Codex
• Hooks no Codex
• Custom instructions no VS Code
• Agent Skills no VS Code
• Custom Agents no VS Code
• Hooks no VS Code
• Harness Engineering for Coding Agent Users