# Codebase Design > Use when designing deep modules, finding refactoring or deepening opportunities, or making a codebase more testable and AI-navigable. Presents deepening opportunities and works through the one you pick. Triggers on "deep modules", "refactor architecture", "deepening", "深化模块", "重构架构", "代码库设计". Not for executing the change (use refactoring), single-file clarity (use simplify), or greenfield architecture (use architecture) — this skill designs and audits, it does not edit code. - Skill: `int2t05/codebase-design` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add int2t05/codebase-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/int2t05/codebase-design/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: int2t05 (https://skillmd.com/u/int2t05) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/int2t05/codebase-design --- # Codebase Design Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Leverage for callers, locality for maintainers, testability for everyone. This skill merges the deep-module vocabulary with a scan-and-grill workflow: surface architectural friction as deepening opportunities, present them as a visual HTML report, then grill through the one the user picks. ## When to use - Designing a new module or restructuring an existing one — deciding where a seam goes, what hides behind it - Finding refactoring or deepening opportunities across a codebase - Making a codebase more testable or AI-navigable - Consolidating tightly-coupled shallow modules into one deep module - Triggers on "deep module", "seam", "refactoring opportunity", "架构改进", "模块设计", "deepening", "深化模块", "重构架构", "代码库设计" **Not for:** executing the structural change once the design is settled (use `refactoring`); single-file clarity cleanup — naming, nesting, dead code (use `simplify`); greenfield system architecture (use `architecture`); feature-level API contracts (use `api-design`). This skill designs and audits; it does not edit code. ## Steps ### 1. Scan for deepening opportunities Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first — the domain language names good seams; ADRs record decisions not to re-litigate. Scope before you scan — put weight on parts of the codebase that have recently changed. If the user named a direction, take it. Otherwise walk the commit history (`git log --oneline`) to find hot spots, then explore those paths first. Spawn an `Explore` sub-agent to walk the codebase and note friction (if sub-agents are unavailable in this environment, walk it yourself with Glob/Grep/Read, focusing on recently-changed files via `git log --oneline -20`). Note where understanding one concept requires bouncing between many small modules; where modules are **shallow** (interface nearly as complex as the implementation); where pure functions were extracted just for testability but bugs hide in how they're called; where tightly-coupled modules leak across seams; where code is untested or hard to test through its current interface. Apply the **deletion test** to anything suspect: would deleting it concentrate complexity, or just move it? "Concentrates" is the signal. - Load [references/language.md](references/language.md) for the glossary (module, interface, depth, seam, adapter, leverage, locality) and principles - Load [references/deepening.md](references/deepening.md) for dependency categories and the replace-don't-layer testing strategy ### 2. Present candidates as an HTML report Write a self-contained HTML file to the OS temp directory (resolve from `$TMPDIR`, fall back to `/tmp` or `%TEMP%`), at `/architecture-review-.html`. Open it for the user (`xdg-open` / `open` / `start`) and tell them the absolute path. Each candidate is a card: Files, Problem, Solution, Benefits (in terms of locality and leverage), a before/after visualisation, and a recommendation-strength badge (`Strong` / `Worth exploring` / `Speculative`). End with a Top Recommendation section. Use CONTEXT.md vocabulary for the domain and the glossary for the architecture — if CONTEXT.md defines "Order," say "the Order intake module," not "the FooBarHandler." If a candidate contradicts an existing ADR, only surface it when the friction warrants reopening the ADR; mark it clearly in the card. - Load [references/html-report.md](references/html-report.md) for the full HTML scaffold, diagram patterns, and styling guidance Do NOT propose interfaces yet. After the file is written, ask: "Which of these would you like to explore?" ### 3. Grill through the chosen candidate Once the user picks a candidate, walk the design tree: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. Side effects happen inline as decisions crystallize: - Naming a deepened module after a concept not in `CONTEXT.md`? Add the term to `CONTEXT.md` (create it lazily if needed). - Sharpening a fuzzy term? Update `CONTEXT.md` right there. - User rejects the candidate with a load-bearing reason? Offer an ADR so future reviews don't re-suggest it. - Want to explore alternative interfaces? Run the design-it-twice parallel sub-agent pattern. - Load [references/interface-design.md](references/interface-design.md) for interface design criteria: depth, testability rules, seam placement - Load [references/design-it-twice.md](references/design-it-twice.md) for the parallel sub-agent pattern when exploring alternative interfaces **Output:** `docs/design/codebase-audit.md` — the deepening opportunities found (candidates with problem/solution/benefit/strength), the one chosen, and the grilled result (defined interface, seam placement, testing strategy). The HTML report (Step 2) is the visual presentation; this md is the durable record that survives the temp file. ## Verify - [ ] HTML report written to temp dir and opened for the user; absolute path communicated - [ ] Every candidate card has Files, Problem, Solution, Benefits, before/after diagram, strength badge - [ ] Glossary terms used exactly (module, interface, depth, seam, adapter) — no drift to "component," "service," "API," "boundary" - [ ] Domain vocabulary from CONTEXT.md used for module names, not raw type names - [ ] ADR conflicts flagged only when the friction warrants reopening - [ ] After grilling: the chosen candidate has a defined interface, a seam placement, and a testing strategy **Red flags:** proposing interfaces during the scan; listing every theoretical refactor an ADR forbids; drifting to "component"/"service"/"API"/"boundary"; skipping the deletion test. ## References - [${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md](${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md) — shared discipline (surface assumptions, push back, verify don't assume) - [references/language.md](references/language.md) — glossary: module, interface, implementation, depth, seam, adapter, leverage, locality + principles (deletion test, interface is the test surface, one vs two adapters) - [references/deepening.md](references/deepening.md) — dependency categories (in-process, local-substitutable, ports & adapters, mock), seam discipline, replace-don't-layer testing - [references/html-report.md](references/html-report.md) — HTML scaffold, Tailwind/Mermaid via CDN, diagram patterns (mass, cross-section, call-graph collapse), tone and glossary usage - [references/interface-design.md](references/interface-design.md) — interface design criteria: what an interface includes, depth, testability rules, comparing alternatives - [references/design-it-twice.md](references/design-it-twice.md) — parallel sub-agent pattern for exploring alternative interfaces (Ousterhout's "Design It Twice")