AI Agent Design Guide: What Works, What Fails

What works, what doesn’t, and why — based on analysis of publications (2023-2025).

Related articles: Detailed Meta-Analysis of AI Agents | Building Blocks for AI Agents | 11 Multi-Agent Orchestration Patterns

The Fundamental Principle

THE GOLDEN RULE

An AI agent succeeds when it generates content that will be validated by an external deterministic system. It fails when it must validate its own work.

This rule explains 90% of documented successes and failures. It breaks down into 3 corollaries:

• Closed loop = Likely success: The agent generates, an external system validates (compiler, test, simulator)
• Open loop = Likely failure: The agent generates and self-evaluates without external feedback
• The locus of decision determines success: The more logic is in orchestration code, the more reliable the system

The Paradox

Why Code is Easier Than a Marketing Plan

This is deeply counterintuitive:

Code has an automatic verifier

Feedback is: binary, immediate, precise, automatic.

Marketing plan has none

Feedback is: subjective, delayed (6 months), ambiguous, human required.

The general rule

The more a task seems “creative” and “human”, the harder it is for an autonomous agent.

The more a task seems “technical” and “rigid”, the easier it is for an autonomous agent.

It’s not a question of intellectual complexity. It’s a question of automatic verifiability.

What Actually Works

The following patterns have solid empirical evidence of success in production.

1. Code Generation with Automatic Validation

Implementation: Generate → Run tests → Analyze errors → Fix → Repeat loop. Maximum 5 iterations. The agent doesn’t need to “think”, it reacts to error messages.

2. Natural Language → Structured Format Translation

3. Information Extraction to Defined Schema

4. RAG with Verifiable Sources

5. Orchestration in Code (not Prompts)

Implementation: Manager/Worker pattern. The manager (Python/YAML code) decides who does what. Workers (LLM) execute atomic tasks. Never negotiate between agents.

6. Neuro-Symbolic Hybridization

Case Study: Get-Shit-Done

Why orchestration frameworks work

Frameworks like BMAD, Get-Shit-Done (GSD), or GitHub Spec Kit show impressive results in software engineering. Let’s analyze why.

Get-Shit-Done Architecture

The GSD workflow in detail

# 1. QUESTIONS PHASE — The agent asks questions until it understands
/gsd:new-project
# → Generates: PROJECT.md, REQUIREMENTS.md

# 2. RESEARCH PHASE — Parallel agents explore the domain
# → Generates: .planning/research/

# 3. PLANNING PHASE — Roadmap creation
# → Generates: ROADMAP.md, STATE.md
# → HUMAN VALIDATION: "Approve the roadmap"

# 4. CONTEXT PHASE — Capture preferences before implementation
/gsd:context
# → Generates: CONTEXT.md
# "Visual features → Layout, density, interactions, empty states"
# "APIs/CLIs → Response format, flags, error handling"

# 5. BUILD PHASE — Execution with atomic commits
/gsd:build
# → Each task = 1 commit
# abc123f docs(08-02): complete user registration plan
# def456g feat(08-02): add email confirmation flow
# hij789k feat(08-02): implement password hashing

Why GSD works: Mapping with principles

What GSD does NOT do

❌ The agent does NOT decide when to move to the next phase
   → The orchestrator (code) decides

❌ Agents do NOT negotiate with each other
   → They follow a coded sequential workflow

❌ The agent does NOT self-correct without feedback
   → The compiler/tests provide feedback

❌ The agent does NOT "plan" autonomously
   → It generates candidates that humans validate

The lesson

GSD doesn’t prove that “agents work now”.

GSD proves that when properly structured (coded orchestration + specialization + deterministic feedback + human-in-loop), it works in domains with automatic verifiers.

Software engineering is the sweet spot for AI agents because all success conditions are naturally present:

What Doesn’t Work

The following patterns seem promising but fail structurally.

1. Self-Correction Without External Feedback

⚠️ TRAP: “The agent will re-read and correct its errors” is an illusion. Without external signal, the agent cannot distinguish an error from a correct response.

2. Autonomous Multi-Step Planning

3. Multi-Agent Debate to Improve Accuracy

4. Betting on Scaling to Solve Limitations

5. Universal / Generalist Agent

6. “Emergent” Multi-Agent Coordination

Decision Matrix

Checklist: Will Your Agent Work?

Score:

• 7/7 = Excellent
• 5-6 = Viable with precautions
• 3-4 = Prototype only
• < 3 = Rethink architecture

Quick decision tree

7 Design Principles

1. Mandatory Closed Loop

Any agent that generates content must have an external verifier. If you can’t define an automatic test, reduce scope until you can.

• Code → Compiler + Tests
• SQL → Sandbox execution + schema validation
• Structured text → JSON Schema validation
• Decisions → Simulator or coded business rules

2. Strict Specialization

An effective agent does one thing well. Versatility is the enemy of reliability.

• Maximum 3-5 tools per agent
• Restricted semantic domain (limited ontology)
• Outputs in a single, constrained format
• Ephemeral micro-specialization: agents created for 30 seconds then destroyed

3. Deterministic Orchestration

Coordination logic must be in code, not prompts.

• Manager/Worker pattern: code decides, LLMs execute
• Centralized state managed by orchestrator
• Never negotiate between agents
• Explicit timeouts and fallbacks

4. Minimal Context

The shorter the context, the more reliable the agent.

• < 10 distinct steps per task
• 1-3 files maximum in context
• Purge memory between tasks
• Avoid conversation history accumulation

5. Integrated Human Supervision

Plan for > 15% human supervision. Invest in supervision rather than model scaling.

• Human checkpoints at each irreversible step
• Human validation for out-of-distribution cases
• Confidence metrics exposed to user
• Automatic escalation if confidence < threshold

6. Fail Fast, Fail Loud

The agent must fail quickly and explicitly rather than silently produce wrong results.

• Assertions at each step
• Strict timeout (no infinite reflection loops)
• Detailed logs for debugging
• Never “silently retry”

7. Test in Real Conditions

Benchmarks lie. Only real deployment validates an agent.

• Production metrics, not contaminated benchmarks
• Tests with variations (temperature, seed, reformulations)
• Monitoring for drift over time
• A/B testing vs deterministic scripts

Summary by Use Case

✅ VIABLE — Automate

⚠️ CONDITIONAL — With precautions

❌ NOT VIABLE — Rethink architecture

Conclusion

Key Takeaways

AI agents are not “autonomous intelligences”. They are probabilistic pattern-matching systems that work remarkably well WHEN coupled with deterministic verifiers and constrained to a specialized domain.

The correct mental model

Final word

Build systems where the LLM generates and a verifier validates.

Any other architecture is, in 2025, an unkept promise.

Further Reading

• Meta-Analysis: Capabilities, Limitations and Patterns of AI Agents — Systematic analysis of publications with pattern verdict tables
• Building an Agent: The Art of Assembling the Right Building Blocks — Practical guide to languages, orchestration frameworks, models and infrastructure
• The 11 Multi-Agent Orchestration Patterns — Pipeline, Supervisor, Council, Swarm: which pattern for which use case
• Agent Skills: The Onboarding Manual That Turns AI Into an Expert — How to structure instructions for specialized agents