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.

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 precisely in every suggestion. Consistent language is key — do not drift to "component", "service", "API", or "boundary". Full definitions in LANGUAGE.md。

Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in LANGUAGE.md.

• Module — anything with an interface and an implementation (function, class, package, slice).

  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.

  Everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.

• Implementation — the code inside.

  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.

  Leverage at the interface: a lot of behaviour behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation.

• Seam — where an interface lives; a place where behavior can be changed without editing in place. (Use this, not "boundary".)

  Where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")

• Adapter — a concrete thing at a seam that satisfies an interface.

  A concrete thing satisfying an interface at a seam.

• Leverage — what callers get from depth.

  What callers get from depth.

• Locality — what maintainers get from depth: changes, bugs, and knowledge concentrated in one place.

  What maintainers get from depth: change, bugs, knowledge concentrated in one place.

Key principles (full list in LANGUAGE.md）：

Key principles (see LANGUAGE.md for the full list):

• Deletion test: imagine deleting the module. If the complexity disappears, it is a pass-through. If the complexity reappears across N callers, it is doing work.

  Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.

• The interface is the test surface.

  The interface is the test surface.

• One adapter = a hypothetical seam. Two adapters = a real seam.

  One adapter = hypothetical seam. Two adapters = real seam.

This skillis inspired bythe project's domain model. The domain language names good seams; ADRs record decisions the skill should not re-litigate.

This skill is informed by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.

Process

1. Explore

First read the project's domain glossary and any ADRs for the area you are modifying.

Read the project's domain glossary and any ADRs in the area you're touching first.

Then use the Agent tool and subagent_type=Explore to traverse the codebase. Do not follow rigid heuristics — explore organically, and notice where you experience friction:

Then use the Agent tool with subagent_type=Explore to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:

• How many small modules must you jump between to understand one concept?

  Where does understanding one concept require bouncing between many small modules?

• Which modules areshallow— where the interface is almost as complex as the implementation?

  Where are modules shallow — interface nearly as complex as the implementation?

• Where are pure functions extracted solely for testability, but the real bugs hide in how they are called (nolocality）？

  Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?

• Where do tightly coupled modules leak at the seam?

  Where do tightly-coupled modules leak across their seams?

• Which parts of the codebase have no tests, or are hard to test through the current interface?

  Which parts of the codebase are untested, or hard to test through their current interface?

Apply to any module you suspect is shallowDelete test: Does deleting it concentrate complexity, or just move it? "Yes, it concentrated it" is the signal you want.

Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

2. Present candidates

Present a numbered list of deepening opportunities. Each candidate includes:

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

• Files — which files/modules are involved

  Which files/modules are involved

• Problem — why the current architecture causes friction

  Why the current architecture is causing friction

• Solution — describe in plain English what would change

  Plain English description of what would change

• Benefits — explain in terms of locality and leverage, and how tests would improve

  Explained in terms of locality and leverage, and also in how tests would improve

Use the CONTEXT.md glossary to describe the domain, use the LANGUAGE.md glossary to describe the architecture. If CONTEXT.md defines "order", say "order intake module"—not "FooBarHandler", and not "order service".

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

ADR conflict: if a candidate contradicts an existing ADR, only point it out when the friction is large enough to be worth revisiting the ADR. Mark it clearly (e.g. "contradicts ADR-0007—but worth reopening because..."). Do not list every theoretical refactoring that an ADR forbids.

ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. "contradicts ADR-0007 — but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.

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

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

3. Grilling loop

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

Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.

When a decision takes shape, side effects happen in sync:

Side effects happen inline as decisions crystallize:

• Naming a deepened module with a concept not in CONTEXT.md ? Add the term to CONTEXT.md—the same discipline as /grill-with-docs (see CONTEXT-FORMAT.md). Create it lazily if the file does not exist.

  Naming a deepened module after a concept not in CONTEXT.md? Add the term to CONTEXT.md — same discipline as /grill-with-docs (see CONTEXT-FORMAT.md). Create the file lazily if it doesn't exist.

• Refining a vague term during the conversation? Update CONTEXT.md。

  Sharpening a fuzzy term during the conversation? Update CONTEXT.md right there.

• User rejects a candidate with a substantive reason? Offer an ADR, phrased as:"Want me to record this as an ADR so that future architecture reviews won't raise it again?" Only offer it when the reason would genuinely be needed by future explorers to avoid raising the same thing again—skip temporary reasons ("not worth it right now") and self-evident reasons. See ADR-FORMAT.md。

  User rejects the candidate with a load-bearing reason? Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See ADR-FORMAT.md.

• Want to explore alternative interfaces for the deepened module? See INTERFACE-DESIGN.md。

  Want to explore alternative interfaces for the deepened module? See INTERFACE-DESIGN.md.