Transform your development workflow with AI-powered Product Manager, UX Designer, and Claude Code working in perfect harmony. Build production-ready multi-agent systems in hours, not months.
📖 Read the blog post | 🎥 Watch the video | 🚀 See it in action
- Overview
- Repository Structure
- Quick Start
- Complete Setup Guide
- Health Insight System Demo
- Creating Your Own Use Case
- Technical Architecture
- Resources
The 3 AI Amigos revolutionizes how we build multi-agent systems by orchestrating three specialized AI agents that mirror traditional software development roles:
- Product Manager Agent - Creates PRDs, user stories, and technical architecture
- UX Designer Agent - Designs interfaces, creates prototypes, and defines experiences
- Claude Code Agent - Implements the complete system following specifications
This pattern is based on Anthropic's research showing 90.2% performance improvement with multi-agent systems over single agents.
The 3 AI Amigos orchestrates these specialized AI agents in a continuous development cycle:
- Define & Plan - Product Owner collaborates with PM Agent to create requirements and architecture
- Design & Iterate - Requirements flow to UX Designer Agent for design specs and prototypes
- Build & Test - UX artifacts guide Claude Code to implement the complete system
This creates a seamless flow where human vision is amplified by AI expertise at every stage.
- ⚡ 10x Faster Development - From idea to working system in hours
- 🔄 Reusable Patterns - Technical guides work for any domain
- 🎨 Professional UX - AI-designed interfaces that users love
- 🏗️ Production Ready - Following Anthropic's best practices
- 🔧 Domain Agnostic - Works for health, finance, legal, education, etc.
3-AMIGO-AGENTS/
│
├── 🤖 agents/ # Reusable agent configurations
│ ├── pm-agent/ # Product Manager Agent
│ │ ├── config/ # Agent instructions
│ │ ├── example/ # Example outputs and prompts
│ │ │ ├── prompts/ # What to submit to PM
│ │ │ └── generated-pm-artifacts/ # Example PM outputs
│ ├── ux-agent/ # UX Designer Agent
│ │ ├── config/ # Agent instructions
│ │ ├── example/ # Example outputs and prompts
│ │ │ ├── prompts/ # What to submit to UX
│ │ │ └── generated-ux-artifacts/ # Example UX outputs
│ └── code-agent/ # Claude Code configuration
│ └── config/ # CLAUDE.md template
│
├── 📚 technical-patterns/ # Domain-agnostic patterns
│ ├── implementation-guide.md # Multi-agent implementation
│ ├── multi-agent-patterns.md # Orchestrator-worker patterns
│ ├── streaming-patterns.md # Real-time SSE updates
│ ├── dependency-management-guide.md # Critical version requirements
│ ├── sse-implementation-guide.md # SSE best practices
│ ├── multi-agent-implementation-architecture.md # Backend service structure
│ ├── visualization-agent-pattern.md # Visualization agent implementation
│ ├── technology-requirements.md # Stack and version requirements
│ └── anthropic-blog.md # Anthropic's research patterns
│
├── 🏥 use-cases/ # Domain-specific examples
│ └── multi-agent-health-insight-system/
│ ├── health-domain-requirements.md
│ ├── health-system-architecture-guide.md # Combined architecture doc
│ ├── health-mcp-tool-interface.md # Health MCP tools
│ ├── health-user-stories.pdf # User stories & mockups
│ ├── health-design-requirements.md
│ └── Anthropic-Blog-[...].txt
│
├── 📖 docs/ # Setup guides
│ ├── demo/ # Demo-specific guides
│ │ ├── demo-setup-guide.md
│ │ └── po-document-checklist.md
│ ├── requirements-directory-structure.md
│ ├── production-quality-checklist.md
│ └── images/
│ └── ai-amigos-diagram.png
│
└── README.md # You are here!
- Claude Desktop or Claude.ai account (for PM and UX agents)
- Claude Code installed (Get it here)
- VSCode or preferred editor
- Python 3.11+ for backend
- Node.js 18+ for frontend
- Basic understanding of multi-agent systems (Read Anthropic's blog)
- Create Agents → Set up PM and UX agents in Claude Desktop
- Run PM Agent → Upload domain requirements, get product specs
- Run UX Agent → Upload PM outputs, get designs
- Setup Workspace → Organize all outputs for Claude Code
- Run Claude Code → Get working system!
In Claude Desktop:
- Click "Create New Project"
- Name: "Product Manager Agent"
- Description: Copy from
agents/pm-agent/config/pm-agent-description.md - Copy instructions from:
agents/pm-agent/config/pm-agent-instructions.md - Paste into project instructions
- Save project
In Claude Desktop:
- Click "Create New Project"
- Name: "UX Designer Agent"
- Description: Copy from
agents/ux-agent/config/ux-agent-description.md - Copy instructions from:
agents/ux-agent/config/ux-designer-agent-instructions.md - Paste into project instructions
- Save project
Use provided documents in use-cases/multi-agent-health-insight-system/:
- ✅ All documents ready to use
- ✅ Skip to Phase 3
Create these documents (use health examples as templates):
- [domain]-requirements.md - Your domain expertise
- [domain]-system-architecture-guide.md - Combined architecture document with multi-agent patterns
- [domain]-mcp-tool-interface.md - If you have pre-built MCP tools
- Visual references - Screenshots/PDF showing desired UI/UX (optional but recommended)
- [domain]-design-requirements.md - Design requirements for UX Agent
- Anthropic blog - Link
- Open PM Agent project in Claude Desktop
- Start new conversation
- Copy prompt from:
agents/pm-agent/example/prompts/po-prompt-for-pm-agent.md - Customize for your domain
- Attach your documents (8 files) to the message
- Submit and wait for outputs
PM Agent will create:
- 📄 PRD.md
- 📝 user-stories.md
- 🏗️ system-architecture.md
- 🔌 api-specification.md
- 📊 data-models.md
- 🧩 component-architecture.md
- 🛠️ tool-interface.md
- 📋 feature-priority.md
- Open UX Agent project
- Start new conversation
- Copy prompt from:
agents/ux-agent/example/prompts/po-prompt-for-ux-agent.md - Attach all PM outputs + visual references (PDF/screenshots) to the message
- Submit and wait for designs
UX Agent will create:
- 🎨 design-system.md
- 🧩 component-specs.md
- 📱 welcome-prototype.html
- 📱 main-app-prototype.html
- 📐 layout-guidelines.md
- 📊 visualization-specs.md
- ♿ accessibility-guidelines.md
- 🎬 animation-specs.md
mkdir my-awesome-system
cd my-awesome-system
# Create directory structure
mkdir -p backend/tools
mkdir -p frontend
mkdir -p requirements/{technical-patterns,pm-outputs/architecture,ux-outputs/prototypes,po-inputs}# Copy from this repo's technical-patterns/
cp path/to/3-AMIGO-AGENTS/technical-patterns/* requirements/technical-patterns/Critical: Include these new guides:
dependency-management-guide.md- Exact versions to prevent conflictssse-implementation-guide.md- Correct SSE patterns
Place in requirements/pm-outputs/:
- PRD.md, user-stories.md, feature-priority.md (root level)
- architecture/ → PM's technical documents (api-specification.md, data-models.md, system-architecture.md, component-architecture.md, tool-interface.md)
Important: Check api-specification.md for correct SSE endpoint (should be GET, not POST)
Place in requirements/ux-outputs/:
- All design documents
- prototypes/ folder (containing HTML prototypes)
Place in requirements/po-inputs/:
- Your original domain requirements
- Tool documentation (if any)
- Anthropic blog
Copy the template from agents/code-agent/config/minimal-claude-md-template.md to your workspace root:
cp path/to/3-AMIGO-AGENTS/agents/code-agent/config/minimal-claude-md-template.md CLAUDE.mdThen edit CLAUDE.md to replace:
[PROJECT_NAME]with your system name[ONE_LINE_DESCRIPTION]with a brief description
This template ensures Claude Code will:
- Review all requirements before implementing
- Create a comprehensive plan and get your approval
- Avoid duplicate todo entries
- Follow a structured implementation process
- Open terminal in your workspace
- Run:
claude-code - Claude Code will:
- Read CLAUDE.md and analyze all requirements
- Create a comprehensive implementation plan
- Present the plan for your review and approval
- Only proceed with implementation after you confirm
- Provide running instructions when complete
To run the complete health insight system demo:
A sophisticated multi-agent health analysis system featuring:
- 🧠 Chief Medical Officer (CMO) orchestrator agent
- 👥 8 Medical Specialists (Cardiology, Endocrinology, etc.)
- 📊 Real-time Analysis with SSE streaming
- 📈 Dynamic Visualizations generated by AI
- 🎨 Beautiful Medical UI with glassmorphism effects
-
Use Provided Health Documents
use-cases/multi-agent-health-insight-system/ ├── health-domain-requirements.md ├── health-system-architecture-guide.md ├── health-mcp-tool-interface.md ├── health-user-stories.pdf ├── health-design-requirements.md └── Anthropic-Blog-[...].txt -
Copy Technical Patterns (CRITICAL)
cp technical-patterns/* your-workspace/requirements/technical-patterns/Especially: dependency-management-guide.md, sse-implementation-guide.md
-
Follow Phases 1-5 above with health documents
-
Expected Output Structure
health-insight-system/ ├── backend/ │ ├── main.py # FastAPI server │ ├── services/ # Multi-agent orchestration │ ├── agents/ # CMO + specialists │ └── tools/ # Pre-built health tools ├── frontend/ │ ├── src/ │ │ ├── components/ # React components │ │ └── services/ # API integration │ └── package.json └── requirements/ # All specifications -
Run the System
# Backend cd backend pip install -r requirements.txt python main.py # or uvicorn main:app --reload # Frontend (new terminal) cd frontend npm install npm run dev
-
Access at http://localhost:5173 (Vite default)
-
Common Issues:
- If Tailwind CSS errors: Ensure v3.3.0, not v4
- If SSE not streaming: Check for GET endpoint and headers
- If TypeScript errors: Use
import typefor type imports
-
Create Domain Documents
# finance-domain-requirements.md - Asset classes: stocks, bonds, crypto - Analysis types: risk, performance, allocation - User queries: "Optimize my portfolio", "Tax implications"
Plus: Dashboard screenshots showing portfolio views
-
Run Through AI Amigos
- PM creates: Chief Investment Officer + specialists
- UX creates: Financial dashboards matching your visual references
- Claude Code: Implements complete system
-
Create Domain Documents
# legal-domain-requirements.md - Document types: contracts, patents, compliance - Analysis needs: risk assessment, clause extraction - Specialists: Contract Lawyer, IP Expert, Compliance Officer
-
Same pattern, different domain!
# The pattern works like this:
Orchestrator (CMO/CIO/Senior Counsel)
├── Analyzes request complexity
├── Creates specialist tasks
├── Executes specialists in parallel
├── Synthesizes results
└── Generates visualizations// SSE provides live updates:
- Specialist activation
- Progress indicators
- Partial results
- Final synthesis- Backend: FastAPI 0.104.1, Anthropic SDK 0.39.0, SSE (sse-starlette 1.8.2)
- Frontend: React 18.2.0, TypeScript 5.2.2, Tailwind CSS 3.3.0 (NOT v4)
- Patterns: Orchestrator-Worker, Progressive Disclosure
- Streaming: GET endpoints with EventSource, X-Accel-Buffering headers
- Based on: Anthropic's Research
- 📖 Blog: The 3 Amigo Agents - The Claude Code Development Pattern
- 🎥 Video: 3 Amigo Agents Pattern Walkthrough
- 📄 Anthropic's Multi-Agent Research
- 🚀 Live Demo: Multi-Agent Health Insight System
🌟 If this helps you build something amazing, please star the repo and share your story!
Made with ❤️ by George Vetticaden and the 3 AI Amigos Community