Agent Harness — Design Estruturado para Agentes LLM
qinghaoliqaq/Agent-Harness
Design sistemático de agentes LLM confiáveis com cobertura de 15 modos de falha
Ver no GitHubUma skill para Claude Code que guia o design completo de agentes LLM em 10 fases sequenciais: análise de requisitos, seleção de paradigma, gerenciamento de estado, sistema de ferramentas, memória, engenharia de contexto, guardrails, observabilidade e recuperação de falhas. Força decisões conscientes sobre modos de falha antes de escrever código.
Instalação
npx convez-ai qinghaoliqaq/Agent-Harness1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Arquitetar agentes de atendimento ao cliente com escalação humana
- Projetar sistemas de agentes para processamento de pedidos e reembolsos
- Migrar agentes de protótipo para produção com garantias de confiabilidade
- Escolher entre paradigmas de execução (ReAct, Plan-Execute, State Machine, DAG)
- Avaliar e mitigar modos de falha em sistemas de agentes
Veredito

Skill rigoroso e bem-estruturado que eleva o padrão de design de agentes além de prompt engineering. A metodologia de 10 fases com cobertura explícita de modos de falha é robusta; recomendado para quem precisa entregar agentes confiáveis em produção, não protótipos.
README
A tradução para o português deste README ainda está na fila.
agent-harness
A Claude Code skill for designing LLM agent projects as complete harnesses — not prompt-engineered toys. When someone brings an agent requirement, this skill walks Claude through a 10-phase sequential design track, ensuring every critical decision is made with awareness of failure modes, before a line of code is written.
Agent = Model + Harness. The model is the engine; the harness is the reins, the brakes, the steering, the dashboard, and the seatbelt. A reliable agent is not a better prompt — it's eight integrated pillars.
The 10 phases
00. Requirement analysis (T1/T2/T3/T4 failure tier, I/O shape, scope)
01. Paradigm selection (ReAct / Plan-Execute / State Machine / DAG / Hierarchical)
02. State management (storage, checkpointing, recovery semantics)
03. Tool system (schemas, permissions, idempotency, failure)
04. Memory architecture (short / working / long-term / entity)
05. Context engineering (prompt structure, compaction, caching, budget)
06. Guardrails (preventive + detective layers, HITL)
07. Observability (tracing, eval, cost tracking)
08. Failure recovery (retry, circuit breakers, degradation, rollback)
09. Synthesis (complete harness design document + FM coverage matrix)
Each phase has gating preconditions, failure-mode coverage, and forced routing to the next phase. The skill is designed so Claude cannot skim or skip — every phase produces a concrete artifact that feeds the next.
Core principles (internalized in every phase)
- Agent = Model + Harness. The harness owns reliability. Every agent failure is a harness bug, not a model bug.
- Design for failure, not for success. Every phase enumerates failure modes before solutions. 15 common failure modes are tracked end-to-end.
- Model-agnostic by default. You should be able to swap the underlying model without rewriting the system.
When this skill triggers
Claude will automatically invoke this skill when you:
- Describe an agent requirement and ask for architecture help
- Ask about paradigm choice (ReAct vs Plan vs state machine)
- Ask about memory / tools / guardrails design for an agent
- Say your agent is "unreliable in production" or keeps failing in specific ways
- Mention migrating from a prototype to production
Install
In Claude Code, run:
/plugin marketplace add qinghaoliqaq/Agent-Harness
/plugin install agent-harness@agent-harness-marketplace
(Repo: https://github.com/qinghaoliqaq/Agent-Harness — replace the owner/repo if you forked it.)
After installation, the skill loads automatically when you describe an agent design problem.
Verify
/plugin list
You should see agent-harness in the list.
Try it
Restart your Claude Code session and try this prompt:
"I want to build a customer service agent that can look up orders, process refunds, and escalate to a human. Help me design it."
If the skill is working, Claude will:
- Ask you 5 scoping questions (job-to-be-done, I/O shape, scope, failure cost tier, constraints)
- Select an execution paradigm with explicit rationale
- Walk through state / tools / memory / context / guardrails / observability / failure recovery
- Produce a complete architecture document with a 15-failure-mode coverage matrix
A shortcut: say "design an agent for X" — Claude should enter phase 0 and begin questioning.
Structure
agent-harness-marketplace/
├── .claude-plugin/
│ └── marketplace.json # marketplace manifest
├── plugins/
│ └── agent-harness/
│ ├── .claude-plugin/
│ │ └── plugin.json # plugin manifest
│ └── skills/
│ └── agent-harness/
│ ├── SKILL.md # entry — stays minimal by design
│ ├── core/ # philosophy, architecture, failure-modes
│ ├── phases/ # 00–09, the sequential track
│ └── patterns/ # paradigms, memory, guardrails, context
│ # (pulled on demand, not all read every time)
└── README.md
The skill uses a progressive-disclosure design: SKILL.md is small; the track forces sequential reading; pattern files are only read when relevant to the current phase. This prevents Claude from skimming a large file and jumping to output.
Update
/plugin marketplace update agent-harness-marketplace
Uninstall
/plugin uninstall agent-harness@agent-harness-marketplace
Grounding
The harness concept and the patterns in this skill track the primary literature:
- Anthropic — Effective harnesses for long-running agents
- Anthropic — Harness design for long-running application development
- Anthropic — Effective context engineering for AI agents
- Anthropic — Building effective agents
- OpenAI — Harness engineering: leveraging Codex in an agent-first world
- OpenAI — Unlocking the Codex harness: how we built the App Server
- Hugging Face — Harness, Scaffold, and the AI Agent Terms Worth Getting Right
License
MIT.