convez.ai
SkillAutomaçãoAvançado
hacxy

Agent Architect

hacxy/agent-architect

Design e orquestração de multi-agentes com harness determinístico

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-architect

1 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

Estrelas
6
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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:

StepActionOutput
1. RequirementsAnalyze task complexity, constraints, environmentRequirements spec
2. Pattern SelectionRecommend from 5 foundational patternsArchitecture diagram
3. Harness DesignDesign deterministic orchestration layerHarness spec
4. Deploy LocationConfirm where to scaffold (project/skill/standalone)Location + name check
5. ScaffoldGenerate runnable code with commentsCode files
6. Audit ChecklistVerify design decisionsChecklist report
7. Review & IterateIndependent agent reviews, auto-fixes issuesFinal 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:

LayerControlNature
HarnessOverall flow, tool permissions, error handling, state managementDeterministic (code)
AgentHow to complete a task, which tool to use, how to interpret resultsNon-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

5 Foundational Patterns

Based on Anthropic's "Building Effective Agents" (December 2024), these five patterns cover the vast majority of agent system architectures:

PatternWhen to UseKey Characteristic
Prompt ChainingFixed steps, clear boundariesSequential, most predictable
RoutingDiverse inputs need different handlingClassify → dispatch to specialists
ParallelizationIndependent subtasksSectioning (split) or Voting (consensus)
Orchestrator-WorkersSubtasks are dynamic, can't be pre-definedCentral LLM plans → workers execute
Evaluator-OptimizerQuality critical, iterative improvementGenerate → evaluate → fix loop

Harness Architecture

Harness Architecture

The harness layer has 7 core components, each addressing a specific concern:

ComponentPurposeKey Mechanisms
① Agent Loop ControlPrevent infinite executionmax_turns, timeout, interrupt, loop detection
② Permission SystemEnforce least privilegeauto/confirm/deny per tool, per agent
③ Context ManagementPrevent context explosionSubagent isolation, truncation, summarization
④ Error HandlingGraceful failure recovery4-level fallback: retry → degrade → skip → human
⑤ State & RecoverySurvive crashes, resume work3 state types + checkpoints
⑥ ObservabilityDebug and monitorLogs, cross-agent tracing, metrics
⑦ Token BudgetControl costsGlobal + per-agent budgets, model tiering

7-Step Workflow

7-Step Workflow

The skill follows a structured workflow with an automated review loop:

  1. Requirements Analysis — Collect task description, I/O format, complexity source, constraints, tech stack
  2. Pattern Selection — Recommend architecture from the 5 patterns, with rationale
  3. Harness Design — Design loop control, tool layer, context strategy, error handling, state management
  4. Deploy Location — Ask user: current project / global skill / standalone project.
  5. Generate Scaffold — Produce runnable code with comments, error handling, and sensible defaults
  6. Audit Checklist — Verify: necessity, responsibility boundaries, iteration limits, permissions, error recovery
  7. 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):

#DimensionWhat It Checks
1SimplicityIs it over-engineered? Could a single agent do this?
2Responsibility ClarityAre agent boundaries clear? Any overlap?
3Least PrivilegeDo subagents have minimum necessary tools?
4Context IsolationIs context explosion prevented?
5Error HandlingDoes every failure point have a fallback?
6ObservabilityCan you trace, debug, and monitor?
7Cost ControlIs token consumption reasonable? Model tiering?
8ExtensibilityEasy to add/modify agents? Low coupling?
9Pattern SelectionDoes the pattern match the task characteristics?
10Harness Robustness7 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 skeletons
  • references/harness-design.md — Harness layer: agent loop, permissions, context, error handling, state, observability
  • references/code-templates.md — Python, TypeScript, and Claude Code Skill templates
  • references/claude-code-integration.md — Multi-agent in Claude Code (Skill + Workflow + Agent tool)
  • references/best-practices.md — Design principles, anti-patterns, performance, cost, security
  • references/optimization.md — Diagnosis framework, optimization strategies, architecture evolution, extensibility
  • references/review-criteria.md — 10-dimension scoring, audit checklist, common problem patterns

Third-Party Resources

Anthropic Official

Research & Deep Dives

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

Ver o original no GitHub

Bom para

Relacionados