Use parallel subagents to maintain code quality across compaction events

Problem

When running long Claude Code sessions, context compaction degrades output quality. The main agent loses track of code standards, review findings, and test results as the context window fills up. Running tests inline dumps verbose logs into context, accelerating compaction and causing what some call "concussion events" where the agent forgets prior decisions.

[compaction] Context compressed from 180k to 45k tokens
# Agent now forgets: review findings, test failures, architectural decisions

Solution

Split the workflow into parallel subagents that each own a focused task and write structured findings to a shared NOTES.md file. Each agent starts with a clean context and reads only what it needs.

<!-- CLAUDE.md -->
## Workflow: Implementation -> Review -> Triage

### Step 1: Implementation Agent (subagent)
- Read PLAN.md and implement the next feature
- Run `make build` to verify compilation
- Write summary of changes to NOTES.md

### Step 2: Review Agent (subagent)
- Read NOTES.md for change summary
- Run `make test` and capture results
- Review changed files against coding standards
- Append findings to NOTES.md under ## Review

### Step 3: Triage Agent (subagent)
- Read NOTES.md ## Review section
- Fix any issues found
- Run `make test` to verify fixes
- Update NOTES.md with resolution status

Use the Task tool to spawn subagents with focused context:

# In Claude Code, use /task for each phase
# Each subagent gets a clean 200k context window

# Implementation subagent
/task "Read PLAN.md phase 3. Implement the changes. Write a summary of what you changed to NOTES.md"

# Review subagent (after implementation completes)
/task "Read NOTES.md. Run make test. Review all changed files for code quality. Append findings to NOTES.md under ## Review"

# Triage subagent (after review completes)
/task "Read NOTES.md ## Review. Fix each issue. Run make test. Update NOTES.md with resolutions"

For deterministic quality gates, use stop hooks:

# .claude/hooks/stop.sh
#!/bin/bash
make lint && make test
# Non-zero exit code triggers agent to fix issues

Why It Works

Each subagent starts with a fresh context window, avoiding compaction-induced quality loss. The NOTES.md file acts as a structured handoff document -- only the relevant findings transfer between phases, not verbose test logs or full file contents. Stop hooks add deterministic quality checks that survive compaction because they run outside the context window. This mirrors the "implementation, review, triage" cycle that human teams use, but each agent can focus without context pressure.

Context

• Inspired by Josh Peak's stop hook patterns for deterministic QA checks that survive compaction events
• Works with Claude Code's /task command or the Task tool in agent SDK
• The NOTES.md handoff pattern works for any multi-phase workflow, not just code quality
• Consider using make targets for deterministic checks -- they run the same regardless of context state
• For Ralph-style loops, the stop hook approach is more reliable than in-context instructions
• Subagents on Claude Max plans each consume their own context window but share the same rate limits