Context Course documentation
Hands-On: Multi-Agent Workflow
Hands-On: Multi-Agent Workflow
This project builds a research → implement → verify pipeline. A researcher subagent maps the existing code, an implementer writes the change, and two read-only reviewers (security and performance) sign off in parallel before the change is merged.
Project Setup
Create a new project:
mkdir code-quality-pipeline
cd code-quality-pipeline
# Create files
mkdir -p .claude/agents
touch main.py
touch .claude/CLAUDE.mdStep 1: Define Custom Agents
The workflow is the same on both platforms: define a narrow researcher, a writer, and two read-only reviewers. The file format differs.
Create .claude/agents/researcher.md:
---
name: researcher
description: Explores codebase and documents architecture
tools: Read, Grep, Glob
model: sonnet
---
You are an architecture researcher. Your job is to:
1. Explore the codebase structure
2. Identify key modules, dependencies, and patterns
3. Document the architecture clearly
4. Note areas for improvement
Be thorough. Read 10+ files to build a complete picture.Create .claude/agents/implementer.md:
---
name: implementer
description: Writes code based on specifications
tools: Read, Write, Glob, Bash
model: sonnet
---
You are a skilled developer. Your job is to:
1. Read the specification and architecture docs
2. Write clean, well-tested code
3. Follow existing patterns and conventions
4. Document your changes
Focus on correctness and maintainability.Create .claude/agents/security-reviewer.md:
---
name: security-reviewer
description: Reviews code for vulnerabilities
tools: Read, Grep
model: sonnet
---
You are a security expert. Your job is to:
1. Review code for security vulnerabilities
2. Check for data leakage, injection attacks, etc.
3. Recommend fixes
4. Assess overall security posture
Be thorough. This code might be production-critical.Create .claude/agents/performance-reviewer.md:
---
name: performance-reviewer
description: Reviews code for performance issues
tools: Read, Grep
model: sonnet
---
You are a performance specialist. Your job is to:
1. Identify performance bottlenecks
2. Suggest optimizations
3. Calculate impact
4. Recommend best practices
Be specific with numbers and concrete suggestions.Step 2: Define Project Policies
Keep the preferred workflow in a repo-level instruction file so the team uses the same sequence every time.
Create .claude/CLAUDE.md:
# Code Quality Pipeline
## Architecture
This project uses a multi-agent workflow:
1. **Research** — Understand existing code
2. **Implement** — Write new features
3. **Verify** — Security and performance review
## Workflow Triggers
### Before Implementation
When the user asks for a new feature:
1. Use the researcher subagent first
2. Have it explore the codebase (15+ files)
3. Document architecture and relevant patterns
4. Pass findings to implementation stage
### During Implementation
1. Spawn the implementer subagent
2. Provide it with:
- Feature specification (from user)
- Architecture findings (from researcher)
- Existing code patterns
3. Have it write the code
### Before Merge
1. Spawn security-reviewer and performance-reviewer in parallel
2. Both are read-only (no Write access)
3. Collect findings
4. Report to user before committing
## Example: Add Payment System
User: "Add Stripe integration"
→ Researcher explores payment-related code
→ Implementer writes integration based on findings
→ Security-reviewer checks for token leakage
→ Performance-reviewer checks database queries
→ User reviews all findings and decides to mergeStep 3: Using the Pipeline
Scenario: Add Feature
Prompt your agent:
I want to add OAuth2 authentication.
1. Use the researcher subagent to explore our current auth system.
Read the auth module thoroughly (15+ files).
Document the current architecture and patterns.
2. Use the implementer subagent to write the OAuth2 integration.
Base it on the architecture findings.
Follow existing patterns.
3. Once complete, have security-reviewer and performance-reviewer
review the code in parallel.
I want to see vulnerabilities and bottlenecks before merging.Typical result:
Step 1: Spawning researcher subagent...
✓ Exploring auth/ directory
✓ Reading 18 relevant files
✓ Documenting patterns and dependencies
→ Findings: Current system uses JWT with Redis cache.
Token rotation every 1 hour.
Validates on every API call.
Step 2: Spawning implementer subagent...
✓ Writing OAuth2 provider integration
✓ Following existing JWT pattern
✓ Added tests
→ Implementation: 450 lines of new code + tests
Step 3: Spawning security-reviewer and performance-reviewer in parallel...
✓ Security review complete
Findings: HTTPS enforced? ✓ Tokens hashed? ✓ No secrets in logs? ✓
Recommendation: Add rate limiting to OAuth endpoint
✓ Performance review complete
Findings: 3 database queries per auth (expected)
Recommendation: Cache OAuth provider metadata
Ready for merge? Review findings above.Step 4: Fan-Out Example
When researching, the parent agent can fan out into parallel exploration threads:
Research codebase structure
[Research subagent 1: Explore backend/]
├─ authentication/
├─ database/
└─ api/
[Research subagent 2: Explore frontend/]
├─ components/
├─ state/
└─ pages/
[Research subagent 3: Explore infrastructure/]
├─ docker/
├─ kubernetes/
└─ monitoring/
All 3 run in parallel → Parent aggregates findingsPrompt your agent:
Use 3 subagents to research our codebase:
- Researcher 1: Backend architecture
- Researcher 2: Frontend architecture
- Researcher 3: Infrastructure setup
Each should explore 15+ files and document patterns.
Then combine findings into an architecture overview.Step 5: Pipeline Review Pattern
Classic pipeline: design → code → test → deploy
Stage 1: Architecture Design
└─ Designer subagent: Create schema, define interfaces
Stage 2: Implementation
└─ Developer subagent: Write code based on design
Stage 3: Security Review
└─ Security subagent: Review for vulnerabilities
Stage 4: Testing
└─ QA subagent: Write and run tests
Stage 5: Deployment Planning
└─ DevOps subagent: Plan deployment strategy
Parent: Aggregate findings and present to userCommand:
Use a pipeline workflow to implement a new API endpoint:
Stage 1: Design the endpoint schema and request/response formats
Stage 2: Implement the endpoint using the design
Stage 3: Security review the implementation
Stage 4: Write comprehensive tests
Stage 5: Plan the deployment
Each stage is a subagent. Run sequentially (output of stage N → input to stage N+1).Advanced: Keep Automation Separate from Delegation
Use repo instructions to define when review agents should be used. If you also want automation, use the platform’s real automation surface instead of inventing a subagent DSL.
Use .claude/CLAUDE.md for delegation guidance. If you also want automated checks, use .claude/settings.json hooks for commands such as test or lint scripts:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-checks.sh"
}
]
}
]
}
}Example Results
When the pipeline completes:
{
"researcher": {
"architecture": {
"modules": ["auth", "api", "database"],
"patterns": ["MVC", "Repository pattern", "Middleware"],
"dependencies": ["Express.js", "MongoDB", "Redis"]
}
},
"implementer": {
"files_created": ["oauth2.js", "oauth2.test.js"],
"lines_of_code": 450,
"test_coverage": 94
},
"security_reviewer": {
"vulnerabilities": 0,
"warnings": 1,
"recommendations": ["Add rate limiting"]
},
"performance_reviewer": {
"database_queries_per_request": 3,
"bottlenecks": 0,
"recommendations": ["Cache provider metadata"]
}
}Best Practices Demonstrated
This project demonstrates clear stage separation (research, implement, verify), specialized agents with specific tools and prompts, parallel execution for security and performance reviews, pipeline flow where each stage’s output feeds the next, and repo-level instructions that keep the workflow consistent for the whole team.
Key Takeaways
A researcher agent explores and documents, an implementer writes code, and security and performance reviewers sign off in parallel. Define the specialists in .claude/agents/*.md, .codex/agents/*.toml, or .pi/agents/*.md, and keep the workflow in CLAUDE.md or AGENTS.md. Hooks, extensions, and runtime settings are for automation around the workflow, not for driving subagent orchestration.
Next, the unit 4 quizzes.
Update on GitHub