一、基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 正式名称 | codebase-design | 合集仓库子目录名（见下方说明） |
| 所属合集仓库 | mattpocock/skills（Matt Pocock 个人维护的 Agent Skills 公开仓库） | GitHub |
| 作者/维护者 | Matt Pocock（Total TypeScript 创始人，AI 工程教育者，个人 Newsletter 约 6 万订阅者） | 仓库 README |
| 来源链接 | https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design | — |
| 许可证 | MIT | GitHub API |
| 所属仓库整体 Stars/Forks | 195,965 / 16,886（注：该数字属整个合集，不代表本技能自身热度，仅供了解仓库规模） | GitHub API |
| 该技能自身活跃度 | GitHub 全站代码搜索中，“codebase-design/SKILL.md”精确路径命中 700+ 个独立仓库；已被 AWS 官方开源项目 aws/graph-explorer、多个第三方技能聚合仓库（如 sickn33/agentic-awesome-skills）收录进各自的 .agents/skills 目录，另有独立中文翻译版仓库 |
GitHub Code Search API |
| 最新版本 | v1.1.0（2026-07-08 发布，全仓库统一发版） | GitHub Releases API |
| 安装方式 | Claude Code 插件市场一条命令，或 npx skills@latest add mattpocock/skills 按需勾选单个技能（见第十章） |
官方 README |
二、功能介绍与亮点
codebase-design 是一套给编码 agent 使用的“深模块设计”共享词汇表与设计原则，源自 John Ousterhout《A Philosophy of Software Design》的深模块理论，但做了明确的再加工与取舍。
核心能力：
- 精确词汇表：Module（模块）、Interface（接口）、Implementation（实现）、Depth（深度）、Seam（接缝）、Adapter（适配器）、Leverage（杠杆）、Locality（局部性）八个术语逐一给出定义与“避免混用”的反例（如明确不用“component/service/API/boundary”），解决 agent 在讨论架构时用词漂移、同一件事换着说法的问题
- 深浅模块判据：“小接口 + 大量行为”为深，“大接口 + 稀薄实现”为浅，并给出可操作的删除测试（deletion test）：假设删掉这个模块，复杂度是消失了还是转移到了调用方——用于快速判断一段代码是否只是无意义的转发层
- 接缝取舍原则：“一个适配器只是假设的接缝，两个适配器才是真实的接缝”，避免过度设计出不必要的抽象层
- 配套文档：
DEEPENING.md给出四类依赖（进程内/本地可替换/远程自有/真正外部）各自的加深与测试策略；DESIGN-IT-TWICE.md提供“并行多子 agent 各设计一版接口再比较”的具体操作流程 - 独立第三方评测文章将其与
domain-modeling、improve-codebase-architecture等并列，评价这组技能“推动 agent 认真思考模块边界、词汇一致性与设计质量”
三、适用场景
固定分类：工程效率与代码质量
适用于：设计或重构模块/接口时统一 agent 与团队的架构语言、判断某段代码是否该拆分或合并、决定抽象层（接缝）该不该引入、为提升可测试性重新设计接口。受益人群：独立开发者与小团队工程师、希望 AI 辅助编码时不因用词漂移而反复返工的用户、正在建立团队编码规范的技术负责人。
四、跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 官方 README 提供 Claude Code 插件市场一键安装（claude plugins install mattpocock-skills），技能按 SKILL.md 规范编写，未设置 disable-model-invocation，可被模型自动触发；技能目录内附带 agents/openai.yaml 声明跨 agent 展示元数据 |
| Codex | 原生支持 | 官方 README 明确标注 “Codex, and other agents” 一节，说明可用 npx skills@latest add mattpocock/skills 按需勾选安装到 Codex 等遵循 Agent-Skills 标准的运行时 |
| OpenClaw | 未验证 | 已抓取材料未提及 OpenClaw 专门支持 |
| Hermes Agent | 未验证 | 同上 |
五、推荐理由
AI 辅助编码最常见的返工不是代码写错，而是接口设计一开始就不对——浅薄的转发层、该拆的没拆、不该抽的抽了。codebase-design 把“深模块”这套经过验证的设计判断标准变成 agent 能直接引用的固定词汇和检验流程（删除测试、接缝取舍规则），让每次讨论架构都用同一套语言，减少来回改接口的成本。相比接管全流程的重型框架，它是一份可以单独拿走的参考词汇表，装了就能用，不改变现有工作方式。
六、评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 单个子技能维度：GitHub 代码搜索精确路径命中 700+ 独立仓库，被 AWS 官方仓库 aws/graph-explorer 等收录进自有 agent 配置，另有独立中文翻译版；≥3 个独立技术媒体（Developers Digest、byteiota、mcp.directory 等）专门撰文分析该仓库及其中的架构类技能（合集仓库整体 stars 不作为本项依据） |
| 可用性 | 9 | npx skills@latest add 支持按需只勾选这一个技能安装，纯 Markdown 无需任何配置或付费依赖；2026-07-08 刚统一发版，仓库持续活跃维护（最近提交 2026-07-29） |
| 安全性 | 9 | 见下方安全检查清单 |
| 综合评分 | 8.7 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行及权限范围 | 无——技能主体及配套文档（DEEPENING.md、DESIGN-IT-TWICE.md）均为纯自然语言指令，不含任何脚本 |
| ② 运行时联网外发数据 | 无——不发起任何网络请求 |
| ③ API Key/凭据要求及存储方式 | 无需任何凭据 |
| ④ 可疑指令/Prompt Injection 迹象 | 未发现——已逐字审阅 SKILL.md、DEEPENING.md、DESIGN-IT-TWICE.md 全文及 agents/openai.yaml（仅为展示名称/简介的元数据），均为正常设计指导内容 |
| ⑤ 作者/组织信誉 | 良好——真实身份可查（Total TypeScript 创始人，长期公开发布 TypeScript 教育内容），无刷星或自我造假迹象 |
| ⑥ License | MIT，明确 |
| ⑦ 最近维护时间 | 活跃，2026-07-29 有提交 |
七、跟同类 Skills 相比的优势
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| clean-code-guard（amElnagdy/guard-skills） | 代码写完后的事后质检工具，检测坏味道并给出修复建议 | 是“检测已发生的问题”，本技能是“写代码前先把接口设计对”，作用时机在前，目标是从源头减少返工而非事后修补 |
| refactor-module（hashicorp/agent-skills） | 把单体 Terraform 配置拆分为可复用模块，聚焦 IaC 场景 | 只解决 Terraform 模块拆分这一个具体领域问题，本技能提供的是跨语言、跨领域的通用架构词汇，适用范围更广 |
八、用户评价
该技能目前在第三方平台尚无具名用户评价。独立技术媒体 Developers Digest 在专门评测该仓库架构类技能的文章中评价：“to-prd、improve-codebase-architecture、domain-modeling 和 codebase-design 都在推动 agent 认真思考模块边界、词汇一致性与设计质量”（2026-05-13）。
九、其他补充
同仓库还提供两个可搭配使用的姊妹技能：domain-modeling（维护项目专属术语表 CONTEXT.md 与架构决策记录 ADR）与 improve-codebase-architecture（扫描代码库并生成可视化 HTML 深化建议报告），三者共享本技能定义的同一套词汇体系，可按需单独安装或组合使用。仓库提供 10 种语言的 README 翻译，含简体中文版。
十、安装使用方式
方式一（Claude Code 插件市场，安装全部技能）：
/plugin install mattpocock-skills方式二（按需只装这一个技能，支持 Codex 等其他 agent）：
npx skills@latest add mattpocock/skills运行后在交互式列表中只勾选 codebase-design（以及要安装的目标 agent），无需重启，安装完成后即可在对话中直接引用其词汇或用 /codebase-design 触发。
注意事项：官方建议首次使用前运行一次 /setup-matt-pocock-skills 完成议题跟踪工具等基础配置；该配置主要服务于同仓库的 triage、improve-codebase-architecture 等技能，仅使用 codebase-design 本身可跳过。
十一、注意事项
- 本技能是词汇表与设计原则，不含自动化脚本，效果依赖 agent 在对话中主动引用这些术语，需要使用者在初期养成“用这套词汇提问”的习惯
- 与
improve-codebase-architecture搭配使用时收益更完整（后者的 HTML 报告生成流程会直接引用本技能的词汇），单独安装本技能同样可作为架构讨论的参考标准独立使用 - OpenClaw、Hermes Agent 的兼容性未获第三方证据验证，实际使用前建议先行小范围测试