Improving Codebase Architecture
Find evidence-backed structural improvements that concentrate behavior and ownership behind smaller, clearer interfaces. Treat review, assessment, diagnosis, and planning requests as read-only. Improvement, refactoring, or implementation requests authorize in-scope local edits and non-destructive validation. Require confirmation before external writes, destructive actions, an incompatible public API or data migration, or material scope expansion.
Establish Scope
- Read repository instructions and the domain glossary, architecture documents, and ADRs relevant to the target. Missing optional architecture documents are not blockers.
- Use the area, pain point, or behavior named by the user. Trace only its actual callers, contracts, dependencies, data and state ownership, tests, and directly affected runtime paths.
- When no target is named, inspect recent change history and repeatedly modified paths to bias the assessment toward architecture where future work is likely. Widen the scan only when no meaningful hotspot emerges.
- If multiple incompatible directions remain equally plausible, or the work would break a public API, require a migration, or cross the requested boundary, ask one focused question before choosing.
Assess
Load the architecture assessment reference when evaluating candidates.
- Observe concrete friction: concepts split across files, callers coordinating the same policy, state with unclear ownership, wide or unstable interfaces, leaking dependencies, duplicated adaptation, or tests that must bypass the intended interface.
- Measure the interface by everything callers must know, including ordering, invariants, errors, configuration, side effects, and performance—not only method count.
- Apply the deletion test: reject a proposed module when deleting it would only move the same complexity into callers. Reject speculative seams, pass-through abstractions, style-only rearrangement, and abstractions without a demonstrated variation or ownership need.
- Compare the current and proposed ownership, interface, dependency direction, test surface, and migration path. Prefer the smallest structural change that improves locality or leverage without hiding important operational behavior.
- Keep claims tied to source, tests, history, or executable evidence. Label assumptions and unverified risks.
For an assessment-only request, return at most three candidates ordered by expected leverage, migration risk, and confidence. For each, include evidence paths, current friction, proposed seam and ownership, expected locality or leverage, migration risk, and a concrete verification method. Name the top recommendation and explain why it outranks the alternatives. Do not create a visual report unless the user asks for one.
Refactor Safely
For an authorized implementation request:
- Select one highest-confidence, bounded candidate. Do not bundle unrelated cleanup.
- Establish a behavioral baseline with existing checks and, when practical, characterization or regression coverage at the current public contract.
- Move ownership in small, reversible steps. Preserve externally observable behavior and existing contracts unless the request explicitly changes them; keep the worktree runnable between steps when practical.
- Put policy at its owning module and adapt dependencies at the narrowest justified seam. Remove superseded paths instead of leaving parallel abstractions.
- Run focused checks after each meaningful step, then affected integration tests and the repository gate. Reinspect callers, dependency direction, tests, and the final diff to confirm the candidate's claimed benefit was actually achieved.
- Stop after the selected candidate is complete. Report changed ownership and interface, behavior evidence, checks run, residual risk, and any stronger candidate deferred because it needs a product or migration decision.
Use review-code for ordinary diff or pull-request correctness review. Use harden-code-paths for confirmed edge-case and failure-mode bugs; an architecture finding may explain the root cause, but do not turn this workflow into a generic bug sweep.
1---2name: improve-codebase-architecture3description: Assess or improve an existing codebase's architecture when the user asks about module boundaries, coupling, scattered ownership, testability, change locality, deep modules, seams, or behavior-preserving structural refactoring. Use for cross-module design rather than ordinary diff review or a confirmed edge-case bug fix.4---5
6# Improving Codebase Architecture
7
8Find evidence-backed structural improvements that concentrate behavior and ownership behind smaller, clearer interfaces. Treat review, assessment, diagnosis, and planning requests as read-only. Improvement, refactoring, or implementation requests authorize in-scope local edits and non-destructive validation. Require confirmation before external writes, destructive actions, an incompatible public API or data migration, or material scope expansion.
9
10## Establish Scope
11
121. Read repository instructions and the domain glossary, architecture documents, and ADRs relevant to the target. Missing optional architecture documents are not blockers.
132. Use the area, pain point, or behavior named by the user. Trace only its actual callers, contracts, dependencies, data and state ownership, tests, and directly affected runtime paths.
143. When no target is named, inspect recent change history and repeatedly modified paths to bias the assessment toward architecture where future work is likely. Widen the scan only when no meaningful hotspot emerges.
154. If multiple incompatible directions remain equally plausible, or the work would break a public API, require a migration, or cross the requested boundary, ask one focused question before choosing.
16
17## Assess
18
19Load [the architecture assessment reference](references/architecture-assessment.md) when evaluating candidates.
20
21- Observe concrete friction: concepts split across files, callers coordinating the same policy, state with unclear ownership, wide or unstable interfaces, leaking dependencies, duplicated adaptation, or tests that must bypass the intended interface.
22- Measure the interface by everything callers must know, including ordering, invariants, errors, configuration, side effects, and performance—not only method count.
23- Apply the deletion test: reject a proposed module when deleting it would only move the same complexity into callers. Reject speculative seams, pass-through abstractions, style-only rearrangement, and abstractions without a demonstrated variation or ownership need.
24- Compare the current and proposed ownership, interface, dependency direction, test surface, and migration path. Prefer the smallest structural change that improves locality or leverage without hiding important operational behavior.
25- Keep claims tied to source, tests, history, or executable evidence. Label assumptions and unverified risks.
26
27For an assessment-only request, return at most three candidates ordered by expected leverage, migration risk, and confidence. For each, include evidence paths, current friction, proposed seam and ownership, expected locality or leverage, migration risk, and a concrete verification method. Name the top recommendation and explain why it outranks the alternatives. Do not create a visual report unless the user asks for one.
28
29## Refactor Safely
30
31For an authorized implementation request:
32
331. Select one highest-confidence, bounded candidate. Do not bundle unrelated cleanup.
342. Establish a behavioral baseline with existing checks and, when practical, characterization or regression coverage at the current public contract.
353. Move ownership in small, reversible steps. Preserve externally observable behavior and existing contracts unless the request explicitly changes them; keep the worktree runnable between steps when practical.
364. Put policy at its owning module and adapt dependencies at the narrowest justified seam. Remove superseded paths instead of leaving parallel abstractions.
375. Run focused checks after each meaningful step, then affected integration tests and the repository gate. Reinspect callers, dependency direction, tests, and the final diff to confirm the candidate's claimed benefit was actually achieved.
386. Stop after the selected candidate is complete. Report changed ownership and interface, behavior evidence, checks run, residual risk, and any stronger candidate deferred because it needs a product or migration decision.
39
40Use `review-code` for ordinary diff or pull-request correctness review. Use `harden-code-paths` for confirmed edge-case and failure-mode bugs; an architecture finding may explain the root cause, but do not turn this workflow into a generic bug sweep.
narumiruna