codebase-design
借 John Ousterhout《软件设计哲学》的"深模块"思想,定义一套精确词汇:Module(任何有接口和实现的东西)、Interface(调用者需要知道的一切,不止类型签名)、Depth(每个接口单元能撬动的行为量)、Seam(测试与修改的边界位置)、Adapter(在 seam 上满足接口的具体实现)、Leverage/Locality(深模块给调用者/维护者的回报)。关键原则:"一个适配器是假想的 seam,两个才是真的"(别为不存在的变化抽象);"删除测试"(删掉这模块,复杂度是消失还是摊到 N 个调用者?);"接口即测试面"(想绕过接口测,说明模块形状不对)。可测试性三条:接受依赖别创建依赖、返回结果别产生副作用、接口面要小。还明确否决的框架(如"深度=实现行数/接口行数"),防止误用。
🔍 实测报告
★★★★☆ 4/5 进阶向
把"深模块"落地成一套可复用的精确词汇(每个术语带 Avoid 词)+ 四条可执行原则 + 可测试性三条,并明确否决错误框架;适合给 AI 一个统一的架构语言。
本报告由自动化实测生成:读取技能完整内容,按描述验证可执行性与依赖。
有这个技能,差别在哪
| 遇到的情况 | 没有这个技能 | 有这个技能 |
|---|---|---|
| 设计模块接口 | 接口又大又浅,全是透传,调用者学一堆没用的。 | AI 按深模块设计:小接口、厚实现,调用者学得少撬动得多。 |
| 要不要加一层抽象 | 随手加,为不存在的变化买单。 | "一个适配器是假想的 seam,两个才是真的"——只有真有两处变化才加。 |
| 代码难测,只能绕内部 | 测试绑死实现,一重构就碎。 | 想绕过接口测?说明模块形状不对——先改形状,再谈测试。 |
装好后,AI 会这样帮你干活
你:帮我把订单模块的接口重新设计一下
AI:先问:这个模块的调用者要学多少东西?接口几个方法?参数多简单?
AI:应用删除测试:删掉它,复杂度是消失还是摊到调用者?
AI:把复杂逻辑藏进实现,对外只露小接口。
AI:验证:接口是不是测试面?能不能不绕过接口就测全行为?
安装(超简单,一句话搞定)
不用敲任何命令。 复制下面这句话,发给你的 AI 助手(Claude Code、Reasonix、Cursor、Codex 等都行),它会自己帮你装好:
帮我安装 codebase-design 这个技能,它来自 https://github.com/mattpocock/skills ,装好告诉我是干什么的
你的 AI 助手可能还会问你放在哪、怎么用,照常回答它就行——就像平时让它干活一样,不用懂技术细节。
想自己动手?(不推荐,给懂命令行的人)
下面的命令按工具区分,均来自原仓库。普通用户请直接使用上面的一句话方式,让智能体代劳。
Claude CodeCodexCursorGemini CLIOpenCodeReasonix
/plugin marketplace add mattpocock/skills /plugin install
/plugins → 搜索 skills → Install Plugin
在 Cursor Agent 聊天中输入 /add-plugin skills
gemini extensions install https://github.com/mattpocock/skills
git clone https://github.com/mattpocock/skills.git 对应技能目录(详见原仓库 README)
用 install_source 安装 https://github.com/mattpocock/skills(Reasonix 会引导你完成)
来源与版权
- 原作者:Matt Pocock
- 原仓库:https://github.com/mattpocock/skills
- 许可证:MIT(允许复制、修改、翻译、再分发,需保留版权声明)
- 仓库路径:skills/engineering/codebase-design/SKILL.md