improve-codebase-architecture

Improve codebase architecture

Reveal architectural friction and proposedeepening opportunities— refactorings that turn shallow modules into deep modules. The goal is testability and AI-navigability.

Glossary

Use these terms precisely in every suggestion. Consistent language is the point — do not drift into "component", "service", "API", or "boundary". Full definitions are in LANGUAGE.md .

• Module— anything with an interface and an implementation (function, class, package, slice).
• Interface— everything a caller must know to use the module: types, invariants, error modes, ordering, configuration. Not just the type signature.
• Implementation— the code inside.
• Depth— leverage at the interface: a lot of behavior behind a small interface.Deep = high leverage.Shallow = the interface is almost as complex as the implementation.
• Seam— where an interface lives; a place where behavior can be changed without editing the location. (Use this, not "boundary".)
• Adapter— a concrete thing that satisfies an interface at a seam.
• Leverage— what callers get from depth.
• Locality— what maintainers get from depth: changes, bugs, knowledge concentrated in one place.

Key principles (for the full list see LANGUAGE.md）：

• Deletion test: imagine deleting the module. If the complexity disappears, it is pass-through. If the complexity reappears across N callers, it is doing work.
• The interface is the test surface.
• One adapter = hypothetical seam. Two adapters = real seam.

This skill_references_the project's domain model. Domain language names good seams; ADRs record decisions the skill should not re-litigate.

Process

1. Explore

First read the project's domain glossary and any ADRs in the area you are touching.

Then traverse the codebase using the Agent tool with subagent_type=Explore . Do not follow rigid heuristics — explore organically and note where you encounter friction:

• Where does understanding one concept require jumping between many small modules?
• Which modules areshallow— the interface almost as complex as the implementation?
• Are pure functions extracted only for testability, while the real bugs hide in how they are called (nolocality）？
• Where do tightly coupled modules leak across their seams?
• Which parts of the codebase are untested, or hard to test through their current interfaces?

Apply thedeletion testto anything you suspect is shallow: does deleting it concentrate the complexity, or just move it? "Yes, concentrate" is the signal you want.

2. Present candidates

Show a numbered list of deepening opportunities. For each candidate:

• Files—which files/modules are involved
• Problem—why the current architecture causes friction
• Solution—describe in plain English what would change
• Benefits—explain in terms of locality and leverage, and how tests will improve

Use CONTEXT.md vocabulary for the domain, and LANGUAGE.md vocabulary for the architecture. If CONTEXT.md defines "Order", talk about the "Order receiving module"—not "FooBarHandler", and not "Order service".

ADR conflict: if a candidate contradicts an existing ADR, only raise it if the friction is real enough to be worth revisiting the ADR. Flag it clearly (e.g._"contradicts ADR-0007—but worth reopening because..."_). Do not list every theoretical refactor that an ADR prohibits.

Do not propose interfaces. Ask the user: "Which one of these do you want to explore?"

3. Grilling loop

Once the user selects a candidate, enter the grilling conversation. Walk the design tree with them—constraints, dependencies, the shape of the deepening module, what is behind the seam, which tests survive.

Side effects happen inline as decisions crystallize:

• Naming a deepening module with a concept not in CONTEXT.md ? Add that term to CONTEXT.md—the same discipline as /grill-with-docs (see CONTEXT-FORMAT.md). Create the file lazily if it does not exist.
• Sharpening a vague term during the conversation? Update CONTEXT.md。
• User rejects a candidate for a load-bearing reason? Offer an ADR, framed as:"Want me to record this as an ADR so future architecture reviews do not re-suggest it?" Only offer it if the reason is genuinely needed by future explorers to avoid re-suggesting the same thing—skip transient reasons ("not worth it right now") and self-evident reasons. See ADR-FORMAT.md。
• Want to explore an alternative interface for the deepening module? See INTERFACE-DESIGN.md。