codebase-design · diff
git:20261118.549ccf7 to git:20261118.581e4cd
21 added, 15 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: codebase-design
- description: Designs deep modules with narrow public interfaces and explicit test seams tailored to the repository's chosen architecture using Design It Twice. Use when designing new module interfaces, choosing test seam boundaries, or collapsing shallow wrappers.
+ 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 (Deep Modules, Seams & 6 Pillars)
+ # Codebase Design (Pre-Code Engineering Design & Deep Modules)
- Design module interfaces within the repository's existing (or user-approved) topology that maximize implementation depth behind narrow, stable public interfaces.
+ 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 project topology/module layout already established or explicitly defined by the user?**
- - **No** → Inspect `CONTEXT.md` and manifests first; if greenfield/undecided, call `ask_question` (putting the simplest flat layout with plain relative imports as `(Recommended)`). Never impose an unrequested monorepo or alias structure.
+ 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 capability live inside an existing module/component without bloating its public interface?**
- - **Yes** → Extend the existing module internally. Do not create a new file, pass-through wrapper, or parallel component.
+ 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 boundary (DB, HTTP, filesystem, queue, clock)?**
- - **Yes** → Define a narrow boundary seam for swappability and hermetic testing.
- - **No (pure internal domain logic)** → Export concrete functions/types directly; do not create 1:1 `IFoo` interfaces.
- 4. **Is the interface non-trivial or shared across multiple callers?**
- - **Yes** → Run **Design It Twice** below before editing.
+ 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**: Sketch **Design A** (minimal extension) vs **Design B** (deeper interface hiding policy, validation, concurrency safety, and edge cases). Compare across *Future-Proof, Scalable, Maintainable, Secure, High-Performance, Upgradeable*.
- 2. **Minimize Surface Area**: Pull defaults, invariant checks, and edge-case normalization inside the module so callers stay thin.
- 3. **Verify Blast Radius**: Check existing callers via `rg -n` (or search tool) so rule/dependency changes stay localized to one module.
+ 1. **Design It Twice**:
+ - 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).
+ - 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.