improve-codebase-architecture

Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Glossary

Use these terms exactly in every suggestion. Full definitions are in LANGUAGE.md.

• Module: anything with an interface and an implementation.
• Interface: everything a caller must know to use the module correctly.
• Implementation: the code inside.
• Depth: leverage at the interface. Deep means high leverage; shallow means the interface is nearly as complex as the implementation.
• Seam: where an interface lives; a place behavior can be altered without editing in place.
• Adapter: a concrete thing satisfying an interface at a seam.
• Leverage: what callers get from depth.
• Locality: what maintainers get from depth.

Key principles:

• Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across many callers, it was earning its keep.
• The interface is the test surface.
• One adapter means a hypothetical seam. Two adapters means a real seam.

Process

1. Explore

Read the project's domain glossary and any ADRs in the area first. Then inspect the codebase organically and note where understanding creates friction:

• Where does understanding one concept require bouncing between many small modules?
• Where are modules shallow?
• Where have pure functions been extracted only for testability, while real bugs hide in how they are called?
• Where do tightly-coupled modules leak across seams?
• Which parts are untested, or hard to test through their current interface?

Apply the deletion test to anything suspected of being shallow.

2. Present Candidates

Present a numbered list of deepening opportunities. For each candidate include:

• Files: which files/modules are involved.
• Problem: why current architecture causes friction.
• Solution: plain-English description of what would change.
• Benefits: explain locality, leverage, and how tests would improve.

Use CONTEXT.md vocabulary for the domain and LANGUAGE.md vocabulary for architecture. If a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting that ADR.

Do not propose interfaces yet. Ask: "Which of these would you like to explore?"

3. Grilling Loop

Once the user picks a candidate, walk the design tree: constraints, dependencies, the shape of the deepened module, what sits behind the seam, and what tests survive.

Side effects happen inline as decisions crystallize:

• If naming a deepened module after a concept not in CONTEXT.md, add the term using CONTEXT-FORMAT.md.
• If sharpening a fuzzy term, update CONTEXT.md immediately.
• If the user rejects the candidate with a load-bearing reason, offer an ADR using ADR-FORMAT.md.
• If exploring alternative interfaces, use INTERFACE-DESIGN.md.