Agent Architect
hacxy/agent-architect
Design e orquestração de multi-agentes com harness determinístico
Ver no GitHubSkill para Claude Code que guia o design, construção e otimização de sistemas multi-agentes baseado em padrões oficiais Anthropic. Fornece um workflow estruturado de 7 etapas que vai desde a análise de requisitos até a scaffolding de código executável com revisão automatizada.
Instalação
npx convez-ai hacxy/agent-architect1 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 sistemas multi-agentes complexos com orchestração clara
- Gerar código base (harness) para pipelines de agentes
- Validar e otimizar decisões de design de arquitetura de agentes
Veredito

Ferramenta sólida para arquitetos que trabalham com sistemas multi-agentes. Segue rigorosamente a filosofia Anthropic de harness determinístico + LLM não-determinístico, evitando abstrações genéricas de frameworks. Excelente para projetos que precisam de controle fino e extensibilidade.
README
A tradução para o português deste README ainda está na fila.
agent-architect
A Claude Code skill for designing multi-agent systems and harness architectures based on Anthropic's official patterns and best practices. Guides you from architecture design through code scaffolding, with automated review and iterative optimization.
Install
Via npx (Recommended)
npx skills add hacxy/agent-architect
Manual Install
git clone https://github.com/hacxy/agent-architect.git ~/.claude/skills/agent-architect
As Project Skill
# In your project root
mkdir -p .claude/skills
git clone https://github.com/hacxy/agent-architect.git .claude/skills/agent-architect
What It Does
This skill provides a structured 7-step workflow for designing, building, and optimizing multi-agent systems:
| Step | Action | Output |
|---|---|---|
| 1. Requirements | Analyze task complexity, constraints, environment | Requirements spec |
| 2. Pattern Selection | Recommend from 5 foundational patterns | Architecture diagram |
| 3. Harness Design | Design deterministic orchestration layer | Harness spec |
| 4. Deploy Location | Confirm where to scaffold (project/skill/standalone) | Location + name check |
| 5. Scaffold | Generate runnable code with comments | Code files |
| 6. Audit Checklist | Verify design decisions | Checklist report |
| 7. Review & Iterate | Independent agent reviews, auto-fixes issues | Final design + review report |
Triggers: "multi-agent", "harness", "agent architecture", "agent orchestration", "agent workflow", "subagent", "agent pipeline", "optimize agent", "extend agent", "agent system design"
Design Philosophy
Why Harness, Not Framework
Anthropic's official guidance is clear: write your own harness, don't rely on agent frameworks.
"Agents are custom systems built for your specific tasks. Don't be fooled by fancy agent frameworks. Write your own code instead of relying on framework abstractions." — Building Effective Agents, Anthropic (2024.12)
The reason is architectural:
┌─────────────────────────────────────────┐
│ Your Harness (code) │ ← Deterministic, testable, debuggable
│ ┌───────────────────────────────────┐ │
│ │ LLM + Tools │ │ ← Non-deterministic, flexible
│ └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
A harness is a thin layer of deterministic code that controls:
- When to call the LLM
- What tools the LLM can access
- How to handle LLM outputs
- What to do when errors occur
- How the overall flow proceeds
This is fundamentally different from frameworks like LangChain or CrewAI, which add abstraction layers between you and the LLM. Those abstractions:
- Become outdated as agent patterns evolve rapidly
- Add debugging complexity on top of an already hard-to-debug system
- Impose generic patterns that don't fit your specific needs
- Remove the fine-grained control you need in performance-critical paths
The Core Insight: Deterministic Orchestration + LLM Decision-Making
The most important design decision in any agent system:
| Layer | Control | Nature |
|---|---|---|
| Harness | Overall flow, tool permissions, error handling, state management | Deterministic (code) |
| Agent | How to complete a task, which tool to use, how to interpret results | Non-deterministic (LLM) |
This means:
- The overall flow is predictable — you know which steps the agent will take
- Each step is flexible — the LLM can decide how to accomplish it
- Debugging is tractable — you can pinpoint which step failed
Start Simple, Add Complexity Only When Needed
Can a single agent + tools solve this?
├─ Yes → Use a single agent. Don't over-engineer.
└─ No → Where is the complexity?
├─ Fixed, predictable steps → Prompt Chaining
├─ Diverse input types → Routing
├─ Independent subtasks → Parallelization
├─ Dynamic planning needed → Orchestrator-Workers
└─ Iterative improvement needed → Evaluator-Optimizer
Most real-world agent systems combine multiple patterns. But the starting point should always be the simplest possible architecture.
Architecture Overview
5 Foundational Patterns
Based on Anthropic's "Building Effective Agents" (December 2024), these five patterns cover the vast majority of agent system architectures:
| Pattern | When to Use | Key Characteristic |
|---|---|---|
| Prompt Chaining | Fixed steps, clear boundaries | Sequential, most predictable |
| Routing | Diverse inputs need different handling | Classify → dispatch to specialists |
| Parallelization | Independent subtasks | Sectioning (split) or Voting (consensus) |
| Orchestrator-Workers | Subtasks are dynamic, can't be pre-defined | Central LLM plans → workers execute |
| Evaluator-Optimizer | Quality critical, iterative improvement | Generate → evaluate → fix loop |
Harness Architecture
The harness layer has 7 core components, each addressing a specific concern:
| Component | Purpose | Key Mechanisms |
|---|---|---|
| ① Agent Loop Control | Prevent infinite execution | max_turns, timeout, interrupt, loop detection |
| ② Permission System | Enforce least privilege | auto/confirm/deny per tool, per agent |
| ③ Context Management | Prevent context explosion | Subagent isolation, truncation, summarization |
| ④ Error Handling | Graceful failure recovery | 4-level fallback: retry → degrade → skip → human |
| ⑤ State & Recovery | Survive crashes, resume work | 3 state types + checkpoints |
| ⑥ Observability | Debug and monitor | Logs, cross-agent tracing, metrics |
| ⑦ Token Budget | Control costs | Global + per-agent budgets, model tiering |
7-Step Workflow
The skill follows a structured workflow with an automated review loop:
- Requirements Analysis — Collect task description, I/O format, complexity source, constraints, tech stack
- Pattern Selection — Recommend architecture from the 5 patterns, with rationale
- Harness Design — Design loop control, tool layer, context strategy, error handling, state management
- Deploy Location — Ask user: current project / global skill / standalone project.
- Generate Scaffold — Produce runnable code with comments, error handling, and sensible defaults
- Audit Checklist — Verify: necessity, responsibility boundaries, iteration limits, permissions, error recovery
- Review & Iterate — Spawn independent review agent, score 10 dimensions, auto-fix issues, re-review (max 2 rounds)
10-Dimension Review System
The review agent evaluates designs across 10 dimensions (1-5 score each):
| # | Dimension | What It Checks |
|---|---|---|
| 1 | Simplicity | Is it over-engineered? Could a single agent do this? |
| 2 | Responsibility Clarity | Are agent boundaries clear? Any overlap? |
| 3 | Least Privilege | Do subagents have minimum necessary tools? |
| 4 | Context Isolation | Is context explosion prevented? |
| 5 | Error Handling | Does every failure point have a fallback? |
| 6 | Observability | Can you trace, debug, and monitor? |
| 7 | Cost Control | Is token consumption reasonable? Model tiering? |
| 8 | Extensibility | Easy to add/modify agents? Low coupling? |
| 9 | Pattern Selection | Does the pattern match the task characteristics? |
| 10 | Harness Robustness | 7 sub-items below |
Harness Robustness sub-items (corresponding to the 7 harness components):
- 10a. Loop Control — max_turns, timeout, interrupt
- 10b. Permission System — auto/confirm/deny, per-tool config
- 10c. Context Management — isolation, truncation, summarization
- 10d. Error Handling — retry, degrade, skip, human-in-the-loop
- 10e. State & Recovery — persistence, checkpoints, breakpoint resume
- 10f. Observability — logs, tracing, metrics
- 10g. Token Budget — global + per-agent limits, cost monitoring
Pass criteria: Average score ≥ 4.0. Any sub-item ≤ 2 caps the overall at 3.0.
References
references/patterns.md— 5 foundational patterns with decision tree and code skeletonsreferences/harness-design.md— Harness layer: agent loop, permissions, context, error handling, state, observabilityreferences/code-templates.md— Python, TypeScript, and Claude Code Skill templatesreferences/claude-code-integration.md— Multi-agent in Claude Code (Skill + Workflow + Agent tool)references/best-practices.md— Design principles, anti-patterns, performance, cost, securityreferences/optimization.md— Diagnosis framework, optimization strategies, architecture evolution, extensibilityreferences/review-criteria.md— 10-dimension scoring, audit checklist, common problem patterns
Third-Party Resources
Anthropic Official
- Building Effective Agents — The foundational guide. Covers all 5 patterns, harness philosophy, and when NOT to use agents.
- Anthropic Docs: Agentic Systems — Official documentation on building agent systems with Claude.
- Claude Code Documentation — Claude Code's own multi-agent architecture (Agent tool, Workflows, Skills).
- Claude Code GitHub — Reference implementation of a production harness system.
Research & Deep Dives
- Anthropic: Multi-Agent Research — Anthropic's research publications on agent systems, debate, and constitutional AI.
- LLM Agent Survey (2024) — Comprehensive academic survey of LLM-based agent architectures.
- AgentBench — Benchmark for evaluating LLM agents across multiple environments.
Related Frameworks (for reference, not recommended for production)
- LangChain — Most popular agent framework. Good for prototyping, but adds abstraction layers.
- CrewAI — Multi-agent role-playing framework. Interesting patterns but opinionated.
- AutoGen — Microsoft's multi-agent conversation framework. Research-oriented.
- Swarm — OpenAI's lightweight multi-agent experiment. Good for learning handoff patterns.
Note: Anthropic recommends writing your own harness rather than using frameworks. These links are provided for learning and comparison, not as recommendations.
Community & Patterns
- Agent Protocol — Standardized API for agent interoperability.
- Eugene Yan: Agents — Practical patterns for LLM agents from a practitioner's perspective.
- Latent Space: Agents — Podcast and blog covering the latest in agent architectures.