codebase-design · git:20261118.4ed259f · 2026-11-18 · sha256 220a0718b5f02c58
codebase-design git:20261118.4ed259fA
Immutable. This exact content never changes and is served at /api/v1/blob/220a0718b5f02c58.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_uvxn7lzvfefrczbl/220a0718b5f02c582dd344f57459e17fa4f347a9b8d706c7276523a27e61982f.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 modular, maintainable, scalable, and performance-optimized module interfaces across any language (TS, Dart/Flutter, Go, Python, Rust) using Design It Twice before coding. Use when designing new modules, refactoring shallow wrappers, choosing DI seams, or optimizing scaling and upgradeability. --- # Codebase Design (Pre-Code Engineering Design & Deep Modules) Think through **modularity, maintainability, scaling, upgradeability, configurability, security, and performance** *before* writing code. Consult [references/architecture-checklist.md](references/architecture-checklist.md) and [examples/design-it-twice-example.md](examples/design-it-twice-example.md) for concrete multi-stack patterns. ## Decision tree 1. **Is the repository layout / module boundary already established or confirmed by the user?** - **No** → Read `CONTEXT.md` and manifests first; if undecided, call `ask_question` (recommending the simplest layout). Never invent unrequested monorepos or aliases. - **Yes** → Proceed to step 2. 2. **Can this behavior live cleanly inside an existing module/feature without widening its public interface?** - **Yes** → Extend the existing module internally instead of creating a new file or parallel wrapper. - **No** → Proceed to step 3. 3. **Does the module cross an external I/O, storage, network, or device boundary?** - **Yes** → Define a narrow dependency-inversion seam (`interface` / `abstract interface class` / function type) so drivers can be upgraded/swapped and tested hermetically without mocking internal logic. - **No (pure domain logic)** → Export pure functions/classes/types directly; never create 1:1 `IFoo` boilerplate. 4. **Is the module non-trivial, performance-sensitive, or shared across multiple callers?** - **Yes** → Run the 4-step **Pre-Code Design & Optimization** workflow below before editing. ## Design workflow 1. **Design It Twice & Diagram Boundaries**: - Sketch **Design A** (minimal extension) vs **Design B** (deeper module hiding validation, config defaults, retry/timeout policy, concurrency guards, and state transitions behind a narrow interface). - For non-trivial multi-module or external I/O flows, produce a Mermaid `C4Container` (explicit technology + trust boundaries) and/or `sequenceDiagram` before coding. - Compare across all 6 Pillars: *Maintainability, Scalability, Modularity/Future-Proofing, Security/Secret Hygiene, Performance Optimization, Upgradeability*. 2. **Pre-Code Performance & Resource Audit**: - Verify O(n) / O(1) data structures, zero N+1 queries, bounded pagination/virtualization (`ListView.builder` / cursor pagination), non-blocking UI/event threads (Isolates / workers), explicit timeouts, and deterministic resource disposal (`dispose()`, `close()`, `defer`). 3. **Configurability & Logging Seam**: - Inject typed startup-validated config (zero hardcoded URLs, limits, or secrets) and structured logger calls at boundary/error transitions with secret redaction (`<REDACTED>`). 4. **Blast-Radius & Upgradeability Check**: - Search existing callers (`rg -n`) and confirm future changes to rules or external SDKs stay isolated inside one module.