codebase-design · git:20261028.6945601 · 2026-10-28 · sha256 3bd8dfe1478e0d4e
codebase-design git:20261028.6945601A
Immutable. This exact content never changes and is served at /api/v1/blob/3bd8dfe1478e0d4e.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_uvxn7lzvfefrczbl/3bd8dfe1478e0d4e005d5cfabab3a361be4a2a8c3a4747ba23fd26cf79ac75fd.json
Then /plugin install codebase-design@markdownregistry-uvxn7lzvfefrczbl in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: codebase-design description: Designs deep modules with narrow public interfaces and explicit test seams tailored to the user's chosen architecture using the Design-It-Twice method. Use when designing module interfaces, choosing where to place test seams, or refactoring shallow modules. --- # Codebase Design (Deep Modules, Seams & 6 Pillars) Design module interfaces within the **user's chosen architecture** that maximize **depth** (high internal capability behind a small, stable interface), place **seams** only at genuine boundaries, and uphold the **6 Engineering Pillars** (*Future-Proof, Scalable, Maintainable, Secure, High-Performance, Upgradeable*). ## Decision tree 1. **Has the user defined their preferred project architecture and module layout yet?** - **No** → Do not impose a static folder hierarchy! Interview the user first via `ask_question` or `/grill-me` to agree on the project's module topology. - **Yes** → Proceed to step 2. 2. **Can the new capability live inside an existing module without widening its public interface?** - **Yes** → Extend the existing module internally. Do not create a new file, wrapper class, or pass-through layer. - **No** → Proceed to step 3. 3. **Does the module cross an external I/O or third-party boundary (database, external API, queue, filesystem, clock)?** - **Yes** → Define a narrow **seam** at the boundary so callers stay **Upgradeable** (easy to swap providers) and deterministically testable without live infrastructure. - **No (internal logic)** → Expose concrete functions or types directly; do not create 1:1 `IFoo` interfaces for single-implementation internal code. 4. **Is the interface non-trivial?** - **Yes** → Run **Design It Twice** below before writing implementation code. ## Design workflow 1. **Design It Twice**: - Sketch **Design A** (minimal evolutionary extension) and **Design B** (a deeper module hiding more policy, concurrency safety, and edge cases behind fewer exported functions). - Compare both across the **6 Engineering Pillars**: *Future-Proof, Scalable, Maintainable, Secure, High-Performance, Upgradeable*. 2. **Minimize the interface**: - Ask for every exported function/method: *Can I reduce the number of methods? Can I simplify the parameters? Can I pull configuration defaults or edge-case handling inside the module?* 3. **Verify locality & upgradeability**: - Ensure a single business rule change or dependency upgrade requires editing only this module rather than scattering edits across callers.