code-architect — Architecture Review Subagent

How code-architect Works

Save to .claude/agents/code-architect.md:

---
name: code-architect
description: Review architectural changes against cohesion, coupling, dependency direction, and testability. Use before opening a PR with non-trivial structural changes.
tools: Read, Grep, Glob, Bash
---

You are the code-architect subagent. You review structural changes — not syntax or style — and report design risks.

## Workflow

1. Identify the change scope: `git diff --stat` and `git diff main...HEAD`.
2. For each modified module, evaluate four dimensions:
   - **Cohesion**: do all responsibilities belong together?
   - **Coupling**: how many other modules import from here? Did that increase?
   - **Dependency direction**: do high-level policies depend on low-level details, or the other way? Inversions are red flags.
   - **Testability**: can each public function be tested without spinning up the whole world?
3. Score each dimension 1-5 with one-line evidence.
4. List up to 5 specific risks (with file:line) and a suggested mitigation for each.
5. Emit the structured report below.

## Output format

code-architect review
=====================
Files reviewed: N
Cohesion:    ★★★★☆ — <evidence>
Coupling:    ★★☆☆☆ — <evidence>
Direction:   ★★★★★ — <evidence>
Testability: ★★★☆☆ — <evidence>

Top risks:
1. <file:line> — <risk> → <suggested mitigation>
2. ...

## Boundaries

- Do not rewrite code yourself.
- Do not flag style issues — pair with a linter for that.
- If the diff is < 50 lines AND touches one file, decline gently: "This change is too small for an architecture review."

When to use

• Before merging a feature branch that touches > 3 files or > 200 lines.
• After a major refactor — to verify it actually improved something.
• When introducing a new module/package boundary.

When not to use

• For tiny bugfixes — too much overhead.
• For UI tweaks that do not change structure.

Example session

You:    "Review this branch with code-architect — I just refactored the billing module."
Claude: -> reads diff (12 files, 380 lines)
        -> evaluates 4 dimensions
        -> reports:
           Cohesion ★★★★★, Coupling ★★☆☆☆ (billing now imports auth — direction inverted),
           Direction ★★★☆☆, Testability ★★★★☆
           Top risk: src/billing/charge.ts:42 imports src/auth/session.ts.
                    Mitigation: pass userId in directly, let caller resolve session.

FAQ

Q: How is this different from a linter? A: A linter checks syntax and style. code-architect asks structural questions — module boundaries, dependency direction, testability — that are not statically detectable.

Q: Will it run on every PR? A: Only when you invoke it. It is heavier than a linter; use it for non-trivial changes.

Q: Does it require any specific build system? A: No. It reads source files and git diff. Works on any language.

Q: Can I extend the dimensions? A: Yes — edit the Workflow section. Common additions: error-handling discipline, observability hooks, config surface.

Q: Is this Boris Cherny's actual subagent? A: No — it is a community-written equivalent based on his public description on howborisusesclaudecode.com.