Devops Monk

A sub-agent is a specialized Claude instance that runs in an isolated context window with its own allowed tools, memory, and instructions. While your main Claude session handles the conversation, a sub-agent spins up to handle a specific task — investigation, code review, security audit, testing — in parallel with your work.

Sub-agents excel at tasks that require:

• Reading many files without cluttering main context
• Specialized expertise in one domain
• Fresh perspective (the agent isn’t biased by earlier conversation)
• Parallel execution (multiple agents working simultaneously)

Sub-Agents vs Skills vs Hooks

Before diving into sub-agents, understand the distinctions:

Sub-agents are for: “I need a specialist to review this code while I continue coding.” Skills are for: “I need to run a complex workflow in my current session.” Hooks are for: “I need this to happen automatically every time.”

How Sub-Agents Work

When you delegate a task to a sub-agent:

1. Spin up — Claude Code creates a new isolated session with:

   • Fresh context window (no conversation history pollution)
   • Specified allowed tools (restricted permissions)
   • Custom instructions (the agent.md frontmatter)
   • Optional: isolated git worktree (separate branch)

2. Run — The agent executes independently:

   • Reads files, runs commands, analyzes code
   • Makes changes within its scope
   • Maintains its own memory (not shared with main session)
   • Reports progress and findings

3. Return — Agent reports back:

   • Summary of what was found/done
   • Specific file:line references
   • Recommendations for the main session
   • Optional: opens a PR with proposed changes

4. Cleanup — Agent context is freed:

   • Session ends, context released
   • Any git worktree is cleaned up (unless you keep it)
   • Main session continues with the agent’s findings

Creating Sub-Agents

Sub-agents are defined in .claude/agents/ directory:

.claude/
└── agents/
    ├── code-reviewer.md
    ├── security-auditor.md
    └── test-orchestrator.md

Each agent is a markdown file with frontmatter + instructions:

---
name: code-reviewer
description: Reviews code changes for bugs, style, and best practices
tools: Read, Edit, Bash
model: claude-opus-4-7
disabled: false
isolation: none
---

You are a senior code reviewer. Your job is to:

1. Read the proposed code changes
2. Identify bugs, edge cases, and improvements
3. Check for adherence to project conventions
4. Provide specific file:line feedback

Focus on:
- Logic errors and potential runtime failures
- Security vulnerabilities
- Performance issues
- Test coverage gaps
- Style/convention violations

Provide findings in this format:

## Findings

### Critical Issues (must fix)
- [file:line] — [Issue] — [Why it matters]

### Improvements (should consider)
- [file:line] — [Suggestion] — [Benefit]

### Passing checks
- Code follows all project conventions
- Error handling is consistent
- Tests cover happy path and edge cases

Frontmatter Fields

Real Sub-Agent Examples

Agent 1: Code Reviewer (For Developers)

Developers benefit from fresh-perspective code review without blocking their own work.

---
name: code-reviewer
description: Reviews code changes for bugs, style, and best practices
tools: Read, Edit, Bash
model: claude-opus-4-7
isolation: none
---

# Code Reviewer Agent

You are a senior code reviewer conducting a thorough review of code changes.

## Your task

Read the current git diff and identify:

1. **Logic errors** — code that will fail at runtime or produce wrong results
2. **Security issues** — injection, auth bypass, data exposure
3. **Edge cases** — scenarios the code doesn't handle
4. **Style violations** — deviations from project conventions
5. **Test gaps** — scenarios not covered by tests

## How to proceed

```bash
git diff HEAD~1

For each changed file, review:

• Function/method signatures (unchanged contract?)
• Error handling (all failure paths covered?)
• Resource cleanup (memory, file handles, connections?)
• Concurrency (race conditions if async?)
• Type safety (TypeScript types sound?)

Report format

Code Review — [COMMIT_HASH]

Critical Issues (must fix before merge)

• [file:line] functionName() — [Issue] — [Why]

Improvements (should consider)

• [file:line] — [Suggestion] — [Benefit]

Passing checks

✓ No logic errors detected ✓ Error handling is comprehensive ✓ No security vulnerabilities ✓ All tests passing

### Agent 2: Test Orchestrator (For Testers)

Testers need to run parallel test suites, generate reports, and identify flaky tests.

```markdown
---
name: test-orchestrator
description: Runs parallel test suites, analyzes results, and identifies flaky tests
tools: Bash, Read, Edit
model: claude-sonnet-4-6
isolation: none
---

# Test Orchestrator Agent

You orchestrate test execution across multiple suites in parallel.

## Your task

Run all test suites and generate a comprehensive report:

```bash
npm test -- --coverage
npm run test:e2e
npm run test:integration

Analysis

For each test run:

1. Count passed/failed
2. Identify new failures vs previously failing
3. Check coverage trends
4. List flaky tests (tests that pass/fail inconsistently)

Report format

Test Report — [DATE]

Summary

• Total tests: XXX
• Passing: XXX (XX%)
• Failing: XXX
• Skipped: XXX

By suite

• Unit tests: XXX passed, XX% coverage
• E2E tests: XXX passed
• Integration: XXX passed

Failures

• [test name] — [reason] — [last 5 runs: pass/fail pattern]

Flaky tests detected

• [test] — fails 20% of the time — investigate: [suggestion]

Coverage gaps

• [file] — [uncovered lines] — [recommended tests]

### Agent 3: Infrastructure Auditor (For DevOps)

DevOps teams benefit from continuous infrastructure audits without blocking deployments.

```markdown
---
name: infra-auditor
description: Audits infrastructure for security, compliance, and cost optimization
tools: Bash, Read, WebFetch
model: claude-opus-4-7
isolation: none
---

# Infrastructure Auditor Agent

You audit infrastructure configurations for security, compliance, and operational health.

## Your task

Scan all infrastructure code and live resources:

```bash
# Scan Terraform
terraform plan -out=plan.json

# Scan Kubernetes
kubectl get all -A

# Check logs
kubectl logs -l app=myapp --tail=50

Security checks

• No hardcoded secrets (passwords, API keys, tokens)
• All storage encrypted at rest
• All traffic encrypted in transit (TLS 1.2+)
• IAM policies follow least-privilege
• Logging enabled on all sensitive operations
• No public-facing databases
• Backups automated and tested

Compliance checks

• Resources tagged appropriately
• Audit logging enabled
• Retention policies enforced
• Data residency compliant

Operational health

• Multi-AZ/replicas for critical services
• Resource limits configured
• Monitoring/alerting active
• Disaster recovery tested recently

Report format

Infrastructure Audit Report — [DATE]

Security Status: [✓ Secure | ⚠ Warnings | ✗ Critical]

Critical Issues (fix immediately)

• [Resource] — [Issue] — [Risk] — [Fix]

Warnings (plan fixes)

• [Resource] — [Issue] — [Recommendation]

Passing checks

✓ All secrets managed via HashiCorp Vault ✓ Multi-AZ on all critical services ✓ Encryption enabled across storage and transit ✓ Logging configured with 90-day retention

Cost optimization opportunities

• [Resource] — [Opportunity] — [Estimated savings]

---

## Invoking Sub-Agents

**Method 1: Simple delegation**

```bash
Use the code-reviewer agent to review the changes in this PR

Claude automatically creates the agent, gives it context about the PR, and runs it.

Method 2: Explicit task assignment

Run the test-orchestrator agent to execute all test suites and report results

Method 3: Programmatic via Claude Code SDK

For advanced workflows, spawn agents directly in code.

Sub-Agent Memory

Sub-agents maintain their own memory files separate from your main session:

~/.claude/projects/my-project/agents/
├── code-reviewer/
│   └── memory/
│       └── MEMORY.md
├── test-orchestrator/
│   └── memory/
│       └── MEMORY.md
└── infra-auditor/
    └── memory/
        └── MEMORY.md

Each agent learns from its own sessions:

• Code Reviewer learns project conventions, common mistakes
• Test Orchestrator learns test infrastructure, flaky patterns
• Infrastructure Auditor learns infrastructure decisions, compliance requirements

This specialization means agents improve at their tasks over time without cluttering main session memory.

Worktree Isolation

For agents that make code changes, use worktree isolation:

---
name: automated-fixer
isolation: worktree
---

This causes the agent to:

1. Create a git worktree (separate branch + folder)
2. Run in that isolated environment
3. Make changes without affecting your main branch
4. Open a PR when done
5. Clean up the worktree

Great for: automated fixes, refactoring, migrations.

Parallel Execution Patterns

Pattern 1: Review While You Code

# Main session: implementing a feature
You: "implement OAuth2 authentication"
Claude: [your session writes code]

# Meanwhile, delegate review
You: "have the code-reviewer agent review my changes as I go"
Agent: [runs in background, reports findings when done]

Pattern 2: Multi-Agent Audit

# Run security and compliance audits in parallel
You: "run security-auditor and compliance-auditor agents on infrastructure"

Agent 1 (Security): scans for vulnerabilities
Agent 2 (Compliance): checks regulatory requirements
Both: report findings simultaneously

Pattern 3: Test Orchestration

# Run different test suites in parallel
You: "run test-orchestrator to execute unit, e2e, and integration tests"

Agent: 
  - Spins up 3 parallel test runners
  - Aggregates results
  - Identifies flaky tests
  - Generates report

When to Use Sub-Agents

Use a sub-agent when:

• Task requires reading many files (would pollute main context)
• You want a fresh perspective (not biased by main conversation)
• Task can run in parallel with your work
• Task needs specialized expertise (security audit, performance analysis)
• Task needs to make changes in isolation (use worktree)

Don’t use a sub-agent when:

• The task is simple and fits in main context
• You need immediate feedback (agent spin-up adds latency)
• Task must read your real-time conversation context
• Task is one-time-only and not worth specialization

Tips for Effective Sub-Agents

1. Make agent scope clear and bounded

Good: “Review code for security vulnerabilities” Bad: “Do a general code review”

2. Specify exactly what tools they need

tools: Read, Bash(npm test), Bash(terraform plan)

Don’t give Bash without restrictions unless necessary.

3. Use the right model for the task

• claude-haiku-4-5 — quick checks, simple analysis
• claude-sonnet-4-6 — standard tasks, good balance
• claude-opus-4-7 — complex reasoning, security, architecture

4. Include output format in instructions

Agents should produce output you can easily parse and act on. Structured format (markdown tables, JSON) beats prose.

5. Test the agent profile first

Use the code-reviewer agent to review src/auth.ts

Verify it produces useful output before relying on it.

Common Mistakes

1. Over-scoping agent responsibility

Agent becomes “do everything” instead of “do one thing well.”

2. Not specifying allowed tools

Agent gets too much access. Always restrict to necessary tools.

3. Agents with very different models

Don’t mix Haiku and Opus for the same type of task unless there’s a reason. Keep consistency.

4. Ignoring agent memory

Agents improve over time. Check their memory files to see what they’ve learned about your project.

5. Not using worktree isolation for changes

Agent makes code changes in your branch. Use isolation: worktree to prevent conflicts.

Sub-Agents in Teams

For team-wide specialists:

# Store agents in version control
.claude/agents/
├── security-reviewer.md     # team standard
├── performance-analyzer.md  # team standard
└── compliance-checker.md    # team standard

All team members get the same agent definitions. Agents learn individually but apply team standards.

Monitoring Agent Progress

When an agent is running, Claude Code shows:

[Sub-agent: code-reviewer] — Reading files...
[Sub-agent: code-reviewer] — Analyzing patterns...
[Sub-agent: code-reviewer] — Generating report...
[Sub-agent: code-reviewer] — Complete

Check /agents to see active and completed agents in current session.

Sub-agents unlock parallel work, fresh perspective, and specialization. Invest in well-defined agents and your team’s quality and speed both improve significantly.