2025-09-23
How I Went From Dev Team to Engineering VP with Claude Code
I had a bug that only appeared during parallel processing. It was intermittent, timing-dependent, and the kind that makes you question your life choices.
My issue-diagnosis agent found worthwhile improvements that would stave off issues like this, but couldn’t nail the root cause. After a few attempts I took a crack at it, and then thought: wait a minute. I had just recently created a team of specialists and seeded the project with context and domain knowledge. Is this really what I’m supposed to be using my time for?
Me → Claude → Diagnoser → Fix → Test
↑ ↓
└── Still Broken ←┘
(repeat 3x)
↓
Debug manually
↓
"Wait, why am I doing this?"
So I made the sub-agents huddle and figure it out.
claude> Work on issue #234. Use issue-diagnoser, analyst, test-writer, and
implementer. Collaborate by orchestrating communication between them.
You will have to make them aware of each other's findings so they can problem
solve more effectively.
Ultrathink about possible causes. Tell each agent to ultrathink
when analyzing. The previous attempts found real issues but not root cause.
Once you identify the problem, implement minimal fix to verify. Then have
the team collaborate on various other optimal solutions. Present me with the
quick fix, and multiple best-practice approaches so I can decide.
The Agents Worked It Out, Orchestration Can Work On-the-fly
The app involves a multi-tenant architecture with complete data isolation between tenants. There was a very minor issue with a shard-switching resource that manifested when the number of processors was increased. Something not realistic on my laptop.
The solution was simple: a MUTEX. But that’s beside the point.
The sub-agents did all of the heavy lifting and found an obscure problem pretty quickly. Based on what I saw, the orchestration that it cooked up looked something like this:
Issue #234
↓
Claude reads issue
↓
→ Diagnoser: "shard switching"
↓
→ Analyst: "multi-tenant issue"
↓
→ Test-Writer: "can't reproduce"
↓
┌─────────┐
│ Retry? │
│ ↓ │
└──→ Yes ─┘
↓ No
"Reproduced! High CPU count"
↓
→ Implementer: "MUTEX fix"
↓
Multiple solutions presented
↓
I decide
I did have to ask for a refinement on the solution I thought best, but that wasn’t particularly time consuming.
Why This Actually Worked
Three things made this ad-hoc orchestration effective:
1. You have to rally the troops
Claude will automatically delegate to subagents when it makes sense. But if you want specific agents involved at a specific moment, you need to call them out by name. Include phrases like use subagent [name] to be explicit.
Although now I can see the case for a /dev-team-huddle command that would kick off this type of workflow automatically.
2. Subagent definitions need good metadata
The description field is critical. It tells the primary agent what the subagent does, when to use it, and what information needs to be passed to it.
Subagents share NO session information with the primary agent. All the prompting you do, everything in the conversation you see (and don’t see) is not shared with the subagent. That initial prompt the primary agent sends them is all they have to work with.
3. Domain knowledge makes isolated agents effective
My projects are rich with domain knowledge. There are CLAUDE.md files with patterns and anti-patterns in strategic locations. The code has casual documentation in it. More intricate areas have more substantial comments (# AIDEV-NOTE: …). Then for fundamental concepts there are stand-alone meta-docs that summarize these topics. These help the primary agent (Claude Code in this case) and the subagents it delegates to. They can navigate and reason about the project much more effectively.
So the sub-agents are set up pretty well even though they’re cut off from the larger conversation. They have the context they need baked into the project.
What These Agents Actually Look Like
The metadata and domain knowledge I mentioned? Here’s what that looks like in practice. These are shortened versions. The production ones have more detail, but you get the idea:
Analyst Agent
---
name: analyst
description: Requirements and architecture analyst who finds patterns and recommends implementation approaches. Pass the complete requirement OR diagnosis from issue-diagnosis. Returns patterns found and architectural guidance. Invoke at start of feature work, planning, or when evaluating bug fix approaches.
tools: Read, Grep, Glob
model: inherit
---
You are a requirements and architecture analyst responsible for understanding features and recommending implementation approaches.
## Core Philosophy
**IMPORTANT: Prioritize correctness and comprehensive solutions over implementation speed.**
- AI can implement quickly regardless of approach
- Test runtime differences are negligible
- **ULTRATHINK**: Think deeply about the best long-term solution
- Consider multiple layers of testing when gaps exist
- Strategic decisions matter more than tactical optimizations
## Scope
**I analyze and recommend:**
- Requirements and GitHub issues
- Bug fix approaches (when given diagnosis from issue-diagnosis)
- Existing patterns in codebase
- Implementation approaches (both for existing patterns and new capabilities)
- Which files need modification
- System architecture decisions
- Comprehensive test strategies across all layers (unit/integration/system)
**I don't:**
- Write code (I'm read-only)
- Run tests or review code
- Implement the decisions (I recommend, others implement)
- Diagnose bugs (that's issue-diagnosis's job)
_[Full production version includes detailed output formats, examples, and comprehensive workflow details]_
Issue Diagnosis Agent
---
name: issue-diagnosis
description: Analyzes bug reports to identify root cause and test gaps. Pass "issue #XXX" or a bug description with affected UI and symptoms. Returns diagnosis only - does not prescribe solutions.
tools: Grep, Read, Bash, Glob
---
## Purpose
Read-only diagnostic specialist. Find root causes and identify test gaps. Do NOT prescribe solutions - only diagnose problems.
## Input
Accept either:
- `issue #XXX` - fetch with `gh issue view XXX`
- Bug description with UI location and symptoms
## Workflow
1. **Find the bug** - Locate where it manifests in code
2. **Trace root cause** - Follow data/logic flow to actual problem
3. **Check ALL test coverage** - Use Glob to find test files at every layer
4. **Identify ALL gaps** - Report missing tests at each affected layer
## Critical Thinking About Test Placement
**Think carefully:** Where does this bug ACTUALLY manifest? Match the test to the bug's location:
- **UI/Visual bug** (wrong text shown, button doesn't work) → **System test gap**
- **Business logic bug** (calculation wrong, validation missing) → **Model/Command test gap**
- **Authorization bug** (user can access forbidden resource) → **Policy test gap**
- **HTTP bug** (wrong status code, missing redirect) → **Controller test gap**
**Key principle:** Match tests to where problems exist. A single bug might expose gaps at multiple layers - report them all if they're legitimate gaps.
_[Full production version includes detailed output templates, pattern recognition rules, and comprehensive diagnostic procedures]_
Test Writer Agent
---
name: test-writer
description: TDD specialist who writes and refines tests. Pass the full requirement, target test files, patterns found, and any validator errors. Invoke when needing tests written or fixed.
tools: Read, Write, Edit, MultiEdit, Grep, Glob
model: inherit
---
You are a TDD specialist responsible for creating and modifying tests ONLY.
## Specialization
This agent creates all test types:
- **Model tests** - validations, scopes, methods
- **Controller tests** - HTTP responses, redirects
- **Job tests** - background job behavior
- **Command tests** - business logic testing
- **Query tests** - database query logic
- **System tests** - UI interactions, browser workflows
## Scope
**I write:**
- New test files (all types)
- Failing tests for TDD (Red phase)
- Test modifications based on validator feedback
- Test syntax fixes
**I don't:**
- Write production code
- Run tests
- Make implementation decisions
## Critical Rule: Test the Actual Bug Scenario
When creating tests for bug fixes, choose the right approach:
**Missing Coverage Tests (Preferred)**
Test what SHOULD happen - the intended behavior that would have prevented the bug.
**Bug Reproduction Tests (When Needed)**
Test the exact failure when you need to prove the bug exists.
_[Full production version includes detailed troubleshooting guides, output formats, and comprehensive testing patterns]_
Implementer Agent
---
name: implementer
description: Implementation specialist who writes production code to pass tests. Pass failing test output, all files to modify, patterns to follow, and current state. Invoke when test is failing correctly.
tools: Read, Write, Edit, MultiEdit, Grep, Glob
model: inherit
---
You are an implementation specialist responsible for writing production code to make tests pass.
## Scope
**I implement:**
- Production code to pass failing tests
- Minimal code for TDD (Green phase)
- Following existing patterns
**I don't:**
- Write tests
- Run tests
- Add extra features beyond test requirements
- Refactor unless needed to pass test
- Create database migrations (return NEEDS_MIGRATION status)
## Process
1. **Understand failing test**
- What behavior does it expect?
- What assertion is failing?
- What's the minimal fix?
2. **Find patterns** (unless trivial fix)
- Check CLAUDE.md in relevant directories
- Find 2-3 similar implementations
- Look for # AI: comments in existing code
3. **Write minimal code**
- Just what's needed to pass test
- Follow patterns from existing code closely
- Use THIS project's patterns, not generic Rails patterns
_[Full production version includes detailed output formats, delegation patterns, and comprehensive implementation guidelines]_
The Transformation
Remember that moment: “Wait, why am I doing this?”
That’s when I realized I’d already built the team. Now I needed to actually use it like one. Instead of jumping back into debug mode myself, I could orchestrate specialists who were setup for these specific problems.
The bug got fixed. But more importantly, I stopped being the bottleneck. When the next complex issue appeared, I knew exactly what to do: rally the team, give them context, let them work.
Your pre-built orchestrators handle routine work. But when something weird comes up, you’re not stuck. You have a team of specialists ready to dive deep while you stay focused on the bigger picture.
You’re not just coding anymore. You’re running an engineering organization where each specialist is made of intentional instructions.
#AICodingAssistants #ClaudeCode #Automation #Productivity #SoftwareEngineering #DigitalTransformation