codebase-design
用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航,或其他技能需要深模块词汇时。
Install / Use
npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-designInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of codebase-design
codebase-design scores 86/100 on our quality scale, 2336th of 4,698 Development & Engineering skills we index (top 50%).
Its SKILL.md is 4.3 KB long, well organised into 8 sections with 2 code examples: a solid amount of guidance for an agent.
With 4,427 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so codebase-design is actively maintained.
- Our last check on 2026-11-03 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-27. Automated pattern scan on 2026-09-27. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
codebase-design compared with similar skills
All 4 of these similar skills score higher than codebase-design; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| codebase-design (this skill)by vinvcn | 86 | 4.4k | 56d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install codebase-design?
- Run
npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design. The install tabs above show the steps for each supported agent. - Which AI agents does codebase-design work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is codebase-design safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is codebase-design still maintained?
- The repository was last updated about 2 months ago, so codebase-design is actively maintained.
Skill content
View source on GitHubname: codebase-design description: 用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航,或其他技能需要深模块词汇时。
Codebase Design
设计 deep modules:把大量行为放在小 interface 之后,把 interface 放在清晰 seam 上,并通过该 interface 测试。凡是在设计或重构代码时,都使用这套语言和原则。目标是给 callers 带来 leverage,给 maintainers 带来 locality,并让每个人都更容易测试。
Glossary
准确使用这些术语,不要替换成 "component"、"service"、"API" 或 "boundary"。一致语言就是重点。
Module - 任何拥有 interface 和 implementation 的东西。它故意不限定尺度:function、class、package,或跨层 slice 都可以。Avoid: unit, component, service.
Interface - caller 为了正确使用 module 必须知道的一切:type signature,以及 invariants、ordering constraints、error modes、required configuration 和 performance characteristics。Avoid: API, signature(太窄,只指 type-level surface)。
Implementation - module 内部的代码体。它不同于 Adapter:一个东西可以是小 adapter 但有大 implementation(Postgres repo),也可以是大 adapter 但 implementation 很小(in-memory fake)。讨论 seam 时说 adapter;其他时候说 implementation。
Depth - interface 上的 leverage:caller(或 test)每学习一单位 interface,就能触达多少行为。大量行为藏在小 interface 后面时,module 是 deep;interface 几乎和 implementation 一样复杂时,module 是 shallow。
Seam(Michael Feathers)- 你可以在不编辑当前位置的情况下改变行为的地方;也就是 module 的 interface 所在的 location。seam 放在哪里是独立设计决策,不同于 seam 后面放什么。Avoid: boundary(它和 DDD bounded context 过载)。
Adapter - 在 seam 上满足某个 interface 的具体东西。描述的是 role(填哪个槽位),不是 substance(内部是什么)。
Leverage - callers 从 depth 获得的收益:每学习一单位 interface,就得到更多能力。一个 implementation 会在 N 个 call sites 和 M 个 tests 中回本。
Locality - maintainers 从 depth 获得的收益:change、bugs、knowledge 和 verification 集中在一个地方,而不是散到 callers 里。修一次,到处都修好。
Deep vs shallow
Deep module = small interface + lots of implementation:
+------------------+
| Small Interface | -> few methods, simple params
+------------------+
| |
| Deep | -> complex logic hidden
| Implementation |
| |
+------------------+
Shallow module = large interface + little implementation(避免):
+-------------------------------+
| Large Interface | -> many methods, complex params
+-------------------------------+
| Thin Implementation | -> mostly pass-through
+-------------------------------+
设计 interface 时问:
- 我能减少 methods 数量吗?
- 我能简化 parameters 吗?
- 我能把更多复杂度藏到内部吗?
Principles
- Depth 是 interface 的属性,不是 implementation 的属性。 Deep module 内部可以由小的、mockable、swappable parts 组成,只是它们不属于 interface。一个 module 可以同时拥有 internal seams(implementation 私有,供自身 tests 使用)和位于 interface 的 external seam。
- Deletion test。 想象删除这个 module。如果复杂度消失了,它只是 pass-through。如果复杂度重新散落到 N 个 callers 里,它就在发挥价值。
- Interface is the test surface。 Callers 和 tests 穿过同一个 seam。若你想测试 interface 之后的内部细节,这个 module 形状可能不对。
- One adapter means a hypothetical seam. Two adapters means a real one. 除非确实有东西会跨 seam 变化,否则不要引入 seam。
Designing for testability
好的 interfaces 让测试自然发生:
-
Accept dependencies, don't create them.
// Testable function processOrder(order, paymentGateway) {} // Hard to test function processOrder(order) { const gateway = new StripeGateway(); } -
Return results, don't produce side effects.
// Testable function calculateDiscount(cart): Discount {} // Hard to test function applyDiscount(cart): void { cart.total -= discount; } -
Small surface area. 更少 methods = 需要更少 tests。更少 params = 更简单的 test setup。
Relationships
- 一个 Module 恰好有一个 Interface(它呈现给 callers 和 tests 的 surface)。
- Depth 是 Module 的属性,并以其 Interface 衡量。
- Seam 是 Module 的 Interface 所在的位置。
- Adapter 位于 Seam 上,并满足 Interface。
- Depth 为 callers 产生 Leverage,为 maintainers 产生 Locality。
Rejected framings
- 把 depth 当作 implementation-lines 与 interface-lines 的比例(Ousterhout):这会奖励 padding implementation。这里使用 depth-as-leverage。
- 把 "Interface" 理解为 TypeScript
interfacekeyword 或 class public methods:太窄;这里的 interface 包括 caller 必须知道的所有事实。 - "Boundary":与 DDD bounded context 过载。说 seam 或 interface。
Going deeper
- Deepening a cluster given its dependencies - 见 DEEPENING.md:dependency categories、seam discipline 和 replace-don't-layer testing。
- Exploring alternative interfaces - 见 DESIGN-IT-TWICE.md:启动并行 sub-agents,用几种截然不同的方式设计 interface,再按 depth、locality 和 seam placement 比较。
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
