/codebase-design 技能

它的作用

codebase-design 定下你设计模块时使用的词汇： module, interface, depth, seam, adapter, leverage, locality。它精确地定义每一个词汇，禁用松散的替代词（「component」「service」「API」「boundary」），并陈述由此得出的几条原则。

It is a reference, not a process. It runs no loop, produces no artifact, and never stops to ask you a question. Every other skill that touches design uses its vocabulary. On its own, it gives you the words and stops. Know this before you invoke it. If you point a 会话 at a skill with no process and no stopping rule and say "go", the agent invents a process. The questions below show what that looks like.

何时使用

输入 /codebase-design，或当设计任务合适时智能体会自动调用它。

Reach for it when you already know which code you're redesigning and you need to think about its shape: where the seam goes, how small the interface can get, whether an extraction removes complexity from its callers. Also use it to settle an argument about what a design word means.

Several skills are close to it. Pick by the problem you have:

问题	技能
The shape of one module: its interface, its seam, its depth	`codebase-design`
这个领域的词汇: "account" means three things, two people mean different things by "cancellation"	domain-modeling
你还不知道 which 要重新设计的模块	improve-codebase-architecture (the survey that finds candidates)
你想要设计被争辩，而不只是被命名	追问审视
有具体行为要构建，而且你想要经得起重构的测试	tdd

词汇表

The glossary is the skill. The skill defines every term against the others, and gives each one the word it replaces.

术语	它意味着什么	不要说
模块	Anything with an interface and an implementation. Deliberately scale-agnostic: a function, a class, a package, a slice spanning tiers.	unit、component、service
接口	调用者正确使用它必须知道的一切：类型签名，以及不变量、顺序约束、错误模式、所需配置、性能特征。	API、签名
深度	Leverage at the interface: how much behaviour a caller or a test can exercise per unit of interface they have to learn. 深：小接口背后藏着大量行为。浅：接口几乎和实现一样复杂。	none
接缝	Michael Feathers 的术语：一个你可以不在此处编辑就能改变行为的地方。它就是 location 是一个接口的，而放在哪里是它自己的决策，与背后放什么分开。	boundary
适配器	A concrete thing satisfying an interface at a seam. It names a role, not a kind of thing: an in-memory fake and a Postgres repo are both adapters.	none
杠杆	调用者从深度得到什么：每学习一单位接口，获得更多能力。	none
局部性	What maintainers get from depth: changes, bugs and verification stay in one place, so one fix covers every caller.	none

The skill does not define depth as the ratio of implementation lines to interface lines, which is Ousterhout's own definition. That metric rewards padding the implementation, so the skill uses depth-as-leverage instead.

四条原则

深度是接口的属性，不是实现的属性。 A deep module can be built internally from small swappable parts. Callers just don't see them. A module can have internal seams its own tests use, and one external seam at its interface.
删除测试。 Imagine deleting the module. If complexity disappears, the module was a pass-through. If it reappears across N callers, the module was hiding real complexity.
接口就是测试表面。 调用者和测试跨越同一个接缝。如果你想测试 past 接口，模块就是错误的形状。
一个适配器意味着假设性接缝。两个适配器意味着真实接缝。 Don't cut a seam until something varies across it. A single-adapter seam is just indirection.

两个辅助文件更进一步，技能按需读取它们，而不是预先读取。 DEEPENING.md classifies a candidate's dependencies into four categories (in-process, local-substitutable, remote-but-owned, true-external), because the category decides how you test the deepened module across its seam. DESIGN-IT-TWICE.md starts parallel sub-agents 为同一个模块产出三个或更多截然不同的接口，然后从深度、局部性和接缝位置比较它们。

常见问题

在 TypeScript 中到底怎么构建深模块？

这是关于该技能被问最多的问题，而技能没有回答它。它定义了深模块 is；它没有说明如何阻止一个游离的 import 越过接口。 Issue #458 put it plainly: "let's say we're happy with the interface, it hides the details, etc. But how do we enforce it? I think without linting or clear guardrails, humans and LLMs alike will start making it messy over time." The answer in that thread gave three options: wrap it in a class or IIFE and accept that the class gets enormous; make it a package in a monorepo and accept the monorepo tooling; or use a linter like dependency-cruiser to forbid imports that bypass the interface. Of these mechanisms, Effect is the best and dependency-cruiser the second-best. There is a setup-ts-deep-modules 仓库 in-progress/ 桶里放着一个 src/packages/<name>/index.ts convention, but it is a beta-channel skill with no docs page, and it ships no lint rule.

我让一个会话指向它，它烧掉了 10 万 tokens 重新设计我从未要求过的东西。

This is a known problem, filed as issue #449. The skill is model-invoked and describes itself as vocabulary, but nothing in it hard-stops an agent from treating it as a runnable process. Told to "resume in /codebase-design and drive the open decisions", an agent picked the part of the skill closest to a process: the parallel sub-agents in DESIGN-IT-TWICE.md. It re-explored code a previous session had already mapped, and worked for a long time before it asked anything. This skill has none of the guardrails a driver skill has (checkpoints, one question at a time, no auto-advance), because it is a reference. The workaround is to invoke a driver skill (/grill-with-docs, /improve-codebase-architecture or /tdd) and use codebase-design as its vocabulary. The issue is open.

原来的 design-an-interface 去哪了？有没有 /interface-design 技能？

This skill replaced design-an-interface and took over its content. Nothing is missing. Its "design it twice" technique (parallel sub-agents generating radically different designs, from Ousterhout) ships here as DESIGN-IT-TWICE.md。另外，有几个人要求提供一个专门的 /interface-design skill for the deep-module/thin-interface philosophy; this skill already covers that philosophy, and no separate skill is planned. If you came looking for either name, this is the page.

Isn't this a file-structure convention, such as folders, barrel files, feature slices?

No. People have pushed back on this many times, and the skill has not changed. Issue #95 proposed a formalised fractal-tree file structure as the concrete implementation of deep modules; the reply was that the two are independent: "deep modules are about the design of the interface and accessing through a strict interface, no matter what the file system looks like. It seems perfectly possible that you could have shallow modules with this approach." The same came up in #458: "I think you might be tying the concept of modules too closely to the file system. The file system can certainly be a useful hint to the shape of modules, but there's no need to use the file system in the construction of deep modules." The glossary defines module 刻意与规模无关。

是否 tdd 真的会使用这套词汇吗？

It does now, but for a long time it did not. v1.0 removed the inline deep-module notes from tdd in favour of this shared skill, but nobody added a pointer to replace them, so tdd defined "seam" for itself and referenced nothing. The pointer is now in tdd, and the agent follows it when the open question is the shape of the interface, not the tests. tdd 仍然拥有「接缝」一词，作为你 test 处；这个技能拥有它背后的模块形状。

「设计两次」模式在 Claude Code 之外有效吗？

不能干净地做到。 DESIGN-IT-TWICE.md says "spawn 3+ sub-agents in parallel using the Agent tool", and "Agent" is the name of a Claude Code tool. The repo ships metadata for other harnesses, including Codex, and those may have no tool with that name. So the parallel-design phase is less portable than the skill's metadata suggests. Issue #564 tracks this, and it is open.

Can I add my own concepts to the glossary, such as connascence, module secrets, 渐进披露?

People have proposed those. Issue #180 把 Parnas 的模块秘密和 Page-Jones 的连接性作为命名层加进来，用于 what 正跨越接缝泄漏，并附有可用的 diff； issue #303 proposes 渐进披露 inside the implementation, so a module that is deep at its public interface also has structure inside it. Both are open and unmerged. The shipped glossary is small on purpose, and the skill itself gives the reason: consistent language is the whole point, and a term nobody uses consistently is worse than no term.

做到以下就算成功

设计对话不再产出「component」「service」「boundary」这些词，开始产出「module」「interface」「seam」。
任何人都能指着提议的抽取，毫不含糊地说它是否通过删除测试。
提议的接缝会附带命名第二个适配器，而不只是第一个。
Discussion of an interface covers invariants, ordering and error modes, not only the type signature.
Invoking it does not start a session. If the agent begins reading files and proposing refactors from /codebase-design 单独使用时，它把参考误当成了驱动者。

在流程中的位置

codebase-design 是一个 随时可调用的独立技能，是工程技能之下的词汇层，而不是任何链上的一步。它最近的邻居是 domain-modeling，与 问题领域's words rather than the module's shape. The two are usually wanted together, since naming a deep module well needs both. improve-codebase-architecture is the other: it surveys a codebase for deepening candidates and writes every one of them in this glossary, so it finds the module and you design it in this skill's words. When you're unsure which skill or flow fits, ask-matt 为你指路。