# Harness Engineering > > - **Type:** Skill - **Install:** `agentstack add skill-thaifurforo-ai-toolkit-harness-engineering` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [thaifurforo](https://agentstack.voostack.com/s/thaifurforo) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [thaifurforo](https://github.com/thaifurforo) - **Source:** https://github.com/thaifurforo/ai-toolkit/tree/main/skills/harness-engineering ## Install ```sh agentstack add skill-thaifurforo-ai-toolkit-harness-engineering ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Harness Engineering > "O gargalo nunca foi a capacidade do agente de escrever código — foi a falta de estrutura, ferramentas e mecanismos de feedback ao seu redor." > — OpenAI Engineering Blog, 2026 Pipeline de desenvolvimento com IA que transforma uma ideia em software confiável, combinando **guias (feedforward)** e **sensores (feedback)** que permitem autocorreção antes de chegar ao humano. --- ## Modelo mental: Guias + Sensores **Guias (feedforward — antes de agir):** - O agente tem o contexto certo? (PRD, arquitetura, convenções) - As restrições estão codificadas? (linters, tipos, estrutura de camadas) - A documentação existe como sistema de record? (`.catalog/`, `AGENTS.md`, tracking configurado) **Sensores (feedback — após agir):** - Computacionais: testes, linters, type check, análise estrutural (rápidos, determinísticos) - Inferenciais: code review por IA, "LLM como juiz" (mais lentos, semânticos) **Regra:** sensores computacionais rodam a cada commit. Sensores inferenciais rodam antes do PR e no pipeline. --- ## Sistema de IDs — fio de rastreabilidade ``` RF-01 (PRD) → US-01 (story) → CA-01 (critério) → T-01 (task) → teste que verifica CA-01 ``` Nunca crie tasks sem RF. Nunca feche task sem gate verificado. Nunca abra PR sem CA validados. --- ## Tracking e release são eixos separados Leia `project_tracking.tool` e `release_management.strategy` em `harness.config.yaml` antes de criar documentação, issues, milestones, changelog ou release notes. | Eixo | Campo | Valores suportados | Decide | |------|-------|--------------------|--------| | Gestão de projeto | `project_tracking.tool` | `github`, `jira`, `linear`, `azuredevops`, `local` | Onde vivem PRD, agrupamentos, user stories, tasks e status | | Versionamento de release | `release_management.strategy` | `github-auto-release`, `github-legacy`, `release-please`, `manual-changelog`, `none` | Como versionar, gerar changelog e publicar releases | Presets como `github-auto-release` e `github-legacy` são atalhos que preenchem os dois eixos quando o usuário quiser GitHub para tudo. Eles **não** impedem combinações como `project_tracking.tool: jira` + `release_management.strategy: github-auto-release`. Compatibilidade com configs antigas: - `project_tracking.mode: github-auto-release` → `project_tracking.tool: github` + `release_management.strategy: github-auto-release`. - `project_tracking.mode: github-legacy` → `project_tracking.tool: github` + `release_management.strategy: github-legacy`. - `project_tracking.mode: local-markdown` → `project_tracking.tool: local` + `release_management.strategy: manual-changelog`. - `project_tracking.tool: github|jira|linear|azuredevops|local` continua válido. Milestones **não** são números de versão por padrão. Milestone versionada é escolha de `release_management.strategy: github-legacy` ou configuração explícita em `project_tracking.github.milestone_policy: versioned`. --- ## Documentação viva ``` AGENTS.md (≤100 linhas — tabela de roteamento) ↓ aponta para: .catalog/ ← fonte de verdade técnica versionada no repositório [delivery_docs.path]/ ← docs de entrega quando `project_tracking.tool: local` ou fallback Ferramenta de rastreamento ← GitHub/Jira/Linear/Azure DevOps/markdown conforme `project_tracking.tool` GitHub Releases ou changelog ← conforme `release_management.strategy` .handoffs/ (sessão) ← handoffs inter-sessão apenas (temporário) ``` **Regra de ouro:** decisão técnica permanente → `.catalog/`. Planejamento e entregas → tracking configurado. Não duplique uma fonte ativa em markdown se o projeto declara uma ferramenta externa como fonte de verdade. **Templates canônicos** para `[delivery_docs.path]/`: `references/10-documentacao-entregas.md` **Como persistir por ferramenta:** `references/11-project-tracking.md` **Como versionar releases:** `references/13-release-management.md` --- ## Pipeline de 9 etapas Para cada etapa, invoque a skill correspondente: | # | Etapa | Skill | Triggers | |---|-------|-------|---------| | 00 | Setup do Projeto | *(referência interna)* | primeira invocação sem `harness.config.yaml` | | 01 | PRD | **`harness-prd`** | "criar PRD", "especificar", "iniciar projeto" | | 02 | Arquitetura Técnica | **`harness-architecture`** | "arquitetura", "stack", "design técnico" | | 03 | Breakdown de Tasks | **`harness-tasks`** | "quebrar em tasks", "planejar", "tasks" | | 04 | Implementação | **`harness-implementation`** | "implementar", "código", "implement T-XX" | | 05 | Code Review | **`harness-code-review`** | "revisar", "code review", "review do PR" | | 06 | Testes | **`harness-testing`** | "gerar testes", "cobertura", "testar" | | 07 | Documentação | **`harness-documentation`** | "documentar", "README", "atualizar catalog" | | 08 | CI/CD | **`harness-cicd`** | "CI/CD", "pipeline", "deploy" | | 09 | Iteração | **`harness-iteration`** | "analisar feedback", "próximo ciclo" | Cada skill é **autossuficiente**: contém a persona, o processo detalhado e o prompt template em `./prompt.md`. > **Etapa 00:** Se `harness.config.yaml` não existe → executar wizard em `references/00-setup-wizard.md` antes de prosseguir. Se existe → ler config, especialmente `project_tracking.tool` e `release_management.strategy`, e mapear variáveis antes de qualquer etapa. --- ## Skills complementares — verificar disponibilidade antes de cada etapa > **Regra:** Verificar se a skill está disponível antes de invocar (consultar `harness.config.yaml`). > Se não disponível → usar `references/12-fallback-skills.md` para o conteúdo equivalente. ### tlc-spec-driven *(se disponível — `skills.tlc_spec_driven: true`)* - **Quando usar:** etapas 01 (SPECIFY), 02 (DESIGN), 03 (TASKS), 04–06 (EXECUTE) - **Integração:** TLC fornece execução atômica com commits e critérios de verificação. Harness Engineering fornece os guias e sensores ao redor. - **Fallback:** continuar o pipeline sem TLC — cada sub-skill define seus próprios gates ### context7-mcp *(se disponível — `skills.context7: true`)* - **Quando usar:** sempre que o código usa uma biblioteca externa — antes de gerar qualquer implementação - **Cadeia:** Codebase → `.catalog/` + `AGENTS.md` → Context7 → Web search - **Fallback:** `references/12-fallback-skills.md § context7` ### Superpowers *(se disponível — `skills.superpowers: true`)* | Skill | Quando acionar | Fallback | |-------|---------------|---------| | `brainstorming` | Etapa 01/02 — escopo ainda indefinido | `12-fallback-skills.md § brainstorming` | | `writing-plans` | Etapa 03 — criar o breakdown de tasks | `12-fallback-skills.md § writing-plans` | | `executing-plans` | Etapa 04 — task por task | `12-fallback-skills.md § executing-plans` | | `test-driven-development` | Etapa 04+06 | `12-fallback-skills.md § test-driven-development` | | `requesting-code-review` | Etapa 05 — antes de abrir PR | `12-fallback-skills.md § requesting-code-review` | | `receiving-code-review` | Etapa 05 — processar feedback | `12-fallback-skills.md § receiving-code-review` | | `systematic-debugging` | Etapa 04 — quando uma task falha | `12-fallback-skills.md § systematic-debugging` | | `verification-before-completion` | Etapa 04/05/06 | `12-fallback-skills.md § verification-before-completion` | | `finishing-a-development-branch` | Após etapa 06 | `12-fallback-skills.md § finishing-a-development-branch` | | `dispatching-parallel-agents` | Etapa 03/04 — tasks independentes | `12-fallback-skills.md § dispatching-parallel-agents` | | `using-git-worktrees` | Etapa 04 — trabalho paralelo | *branches sequenciais* | --- ## Fluxos de uso ### Completo (feature nova — agrupamento com múltiplas USs) ``` 01 PRD → 02 Arq → 03 Tasks + tracking de entrega → [por US, sequencial — nunca em paralelo]: 04 Código → 05 Review → 06 Testes → 07 Docs ↓ PR aberto pelo agente ↓ humano revisa, aprova e mergea ↓ só então iniciar próxima US → 08 CI/CD → Deploy → 09 Iteração ``` ### Rápido (bug fix / quick task) ``` TLC "quick fix" → 04 Código → gate → commit ``` ### Paralelo (tasks independentes dentro de uma US) ``` 03 Tasks → dispatching-parallel-agents → [04+05+06] × N tasks → 07 Docs → PR ``` > **Paralelismo só para tasks dentro de uma US — nunca para USs entre si.** ### Sequencial por US (obrigatório para agrupamentos com várias USs) ``` Para cada US do agrupamento (em ordem de dependência): 1. 03 tracking/docs criados conforme `project_tracking.tool` 2. 04 Código → 05 Review → 06 Testes → 07 Docs 3. PR aberto pelo agente com descrição completa 4. PARAR — aguardar humano revisar, aprovar e mergear 5. Só após merge confirmado → iniciar próxima US ``` ### Release gate (PR para main) ``` 05 Review OK → 06 Testes OK → 07 Docs OK → PR aberto → checks verificados → merge (humano) ``` Com `release_management.strategy: github-auto-release`, o PR para `main` deve fechar issue com closing keyword e conter exatamente uma label `release:*`, mesmo que a gestão de projeto esteja em Jira, Linear ou Azure DevOps. > **RESTRIÇÃO ABSOLUTA:** O agente **NUNCA** faz merge de qualquer PR. Exclusivamente responsabilidade do usuário humano. Sem exceções. --- ## Princípios consolidados 1. **Harness antes de velocidade.** Defina restrições antes de liberar o agente. 2. **Computacional primeiro, inferencial sob demanda.** Testes, linters e type check rodam sempre. Code review por IA roda estrategicamente. 3. **Documentação como sistema de record.** Se não está em `.catalog/` ou no tracking configurado, não existe para o próximo agente. 4. **Linter com remediação inline.** A mensagem de erro deve ensinar como corrigir. 5. **Reset de contexto > compaction.** Acima de ~40% da janela, escreva handoff em JSON e reinicie. 6. **Steering loop contínuo.** Cada erro recorrente vira uma regra no harness. 7. **Topologia reduz variedade (Lei de Ashby).** Defina stack, padrão de camadas e estrutura de módulos antes de começar. --- ## PROJECT_CONTEXT.md — template ```markdown # Contexto — [Nome] ## Stack - Linguagem + versão: - Framework backend: - Framework frontend: - Banco de dados: - Deploy: - Repositório: ## Camadas de dependência (ordem obrigatória) Types → Config → Repository → Service → Runtime → UI ## Convenções - Commits: Conventional Commits - Linting: [ferramenta] - Testes: [framework], cobertura mínima [X]% - Branches: main / develop / feature/T-XX-descricao - Tracking: `project_tracking.tool` em `harness.config.yaml` - Release: `release_management.strategy` em `harness.config.yaml` ## Skills instaladas - [ ] tlc-spec-driven - [ ] superpowers - [ ] context7 - [ ] mermaid-studio ## Links - Config: harness.config.yaml - PRD: `.catalog/PRD.md` ou `[delivery_docs.path]/[level1-nome]/prd.md` - Arquitetura: .catalog/architecture.md - Riscos/Dívidas: .catalog/concerns.md ``` --- ## Referências | Arquivo | Conteúdo | |---------|----------| | `references/00-setup-wizard.md` | Wizard de setup: detecta config, escolhe tracking e release separadamente | | `references/10-documentacao-entregas.md` | Templates canônicos para tracking local e fallback markdown | | `references/11-project-tracking.md` | Como persistir outputs por ferramenta (`github`, `jira`, `linear`, `azuredevops`, `local`) | | `references/12-fallback-skills.md` | Conteúdo condensado de 14 skills externas — usar quando a skill não estiver instalada | | `references/13-release-management.md` | Como versionar releases e changelogs por estratégia | --- ## Fontes - [Fowler/Böckeler — Harness Engineering for Coding Agent Users](https://martinfowler.com/articles/harness-engineering.html) - [OpenAI — Harness Engineering: Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/) - [Anthropic — Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps) ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [thaifurforo](https://github.com/thaifurforo) - **Source:** [thaifurforo/ai-toolkit](https://github.com/thaifurforo/ai-toolkit) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-thaifurforo-ai-toolkit-harness-engineering - Seller: https://agentstack.voostack.com/s/thaifurforo - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.