codebase-design

This skill is a shared-vocabulary and design-principles reference (a Chinese-language translation of Matt Pocock's skills) for designing "deep modules": putting a large amount of behavior behind a small interface, placing that interface on a clean seam, and testing through it. It solves the problem of imprecise architecture conversations by fixing a glossary (module, interface, implementation, depth, seam, adapter, leverage, locality) and insisting on consistent terminology instead of loose words like component, service, API, or boundary.

Its main content is conceptual guidance: the deep-versus-shallow module distinction, principles such as the deletion test and "interface is the test surface," the rule that one adapter is a hypothetical seam while two make it real, and concrete testability heuristics (accept dependencies rather than create them, return results rather than cause side effects, keep surface area small). Two bundled references go deeper: DEEPENING.md categorizes dependencies (in-process, local-substitutable, remote-but-owned via ports and adapters, and true-external requiring mocks) and prescribes a replace-don't-layer testing strategy, while DESIGN-IT-TWICE.md describes a parallel sub-agent pattern that generates several radically different interface designs under different constraints and then compares them by depth, locality, and seam placement.

Target users are engineers and AI agents designing or refactoring module interfaces, looking for deepening opportunities, deciding where seams belong, or making code more testable and easier to navigate. It is a pure concept/reference skill with no executable code.