一直在用 @mattpocockuk 的 /improve-codebase-architecture 技能，已经好几个月了，效果惊人。我在工作流中用的技能不多，但这个我几乎每个项目都会用。https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/SKILL.md

mattpocock/skills

来源：https://github.com/mattpocock/skills

面向真正工程师的技能

skills.sh (https://skills.sh/mattpocock/skills)

我自己每天使用的代理技能，用于进行真正的工程实践——而非“氛围编程”。

开发真正的应用很难。像 GSD、BMAD 和 Spec-Kit 这类方法试图通过掌控流程来提供帮助，但这样做反而剥夺了你的控制权，并且让流程中的 bug 难以解决。

这些技能的设计原则是：小巧、易于调整、可组合。它们适用于任何模型。背后是数十年的工程经验。你可以随意捣鼓，把它们变成自己的东西。享受吧。

如果你想了解这些技能的更新以及我创建的新技能，可以加入约 6 万名开发者订阅我的新闻通讯：订阅新闻通讯 (https://www.aihero.dev/s/skills-newsletter)

快速开始（30 秒设置）

1. 运行 skills.sh 安装器：bash npx skills@latest add mattpocock/skills
2. 选择你想要的技能，以及你要将它们安装到哪些编码代理上。确保你选择了 /setup-matt-pocock-skills。
3. 在代理中运行 /setup-matt-pocock-skills。它会：
   • 询问你想使用哪个问题跟踪器（GitHub、Linear 或本地文件）
   • 询问你在分类时给工单分配哪些标签（/triage 会用到标签）
   • 询问你想把创建的文档保存在哪里
4. 搞定——你已经准备好了。

为什么需要这些技能

我构建这些技能是为了解决我在使用 Claude Code、Codex 和其他编码代理时常见的一些失败模式。

#1：代理没有按我的意图执行

“没有人确切知道自己想要什么。” —— David Thomas 与 Andrew Hunt，《程序员修炼之道》(https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)

问题：软件开发中最常见的失败模式是错位。你以为开发人员理解你的需求，但当你看到他们构建的东西时，才发现他们根本没有理解你。在 AI 时代也是如此。你与代理之间存在沟通鸿沟。解决方法是进行盘问环节——让代理问你关于要构建的内容的详细问题。

解决方案：使用：

• /grill-me —— 用于非编码场景
• /grill-with-docs —— 与 /grill-me 相同，但增加了更多功能（见下文）

这些是我最受欢迎的技能。它们帮助你在开始之前与代理达成一致，并深入思考你要做的改动。每当你想要做改动时都应该使用它们。

#2：代理太啰嗦

“拥有通用语言后，开发人员之间的对话和代码的表达都源自同一个领域模型。” —— Eric Evans，《领域驱动设计》(https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)

问题：在项目初期，开发人员和为软件构建的领域专家通常使用不同的语言。我在代理上也感受到了同样的紧张。代理通常是直接丢进一个项目，然后边走边摸索术语。结果它们用 20 个词来表达本来一个词就够了的意思。

解决方案是共享语言。这是一份文档，帮助代理解码项目中使用的术语。

示例：这是我 course-video-manager 仓库中的一个 CONTEXT.md (https://github.com/mattpocock/course-video-manager/blob/076a5a7a182db0fe1e62971dd7a68bcadf010f1c/CONTEXT.md) 示例。

哪个更容易阅读？

• 之前：“当课程某个章节中的一课变得‘真实’（即在文件系统中有了一个位置）时，会出现一个问题”
• 之后：“物质化级联有问题”

这种简洁性会在每次会话中得到回报。这一理念已内置于 /grill-with-docs 中。它也是一个盘问环节，但能帮助你与 AI 建立共享语言，并将难以解释的决策记录到 ADR 中。很难解释这有多强大。它可能是这个仓库中最酷的技术。试试看吧。

共享语言除了减少啰嗦之外还有很多好处：

• 变量、函数和文件使用共享语言命名一致
• 因此，代理更容易浏览代码库
• 同时，代理在思考上花费的 token 更少，因为它可以使用更简洁的语言

#3：代码跑不通

“始终采取小而有意得的步骤。反馈的速度就是你的速度极限。永远不要接受太大的任务。” —— David Thomas 与 Andrew Hunt，《程序员修炼之道》(https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)

问题：假设你和代理在要构建什么上达成了一致。但代理仍然产出垃圾代码怎么办？这时你需要审视你的反馈循环。如果没有关于代码实际运行情况的反馈，代理就会盲飞。

解决方案：你需要通常的反馈循环：静态类型、浏览器访问和自动化测试。对于自动化测试，红-绿-重构循环至关重要。也就是代理先编写一个失败的测试，然后修复测试。这有助于给代理提供一致的反馈水平，从而产出更优质的代码。

我构建了一个 /tdd 技能，可以插入任何项目。它鼓励红-绿-重构，并为代理提供关于好测试和坏测试的大量指导。对于调试，我还构建了一个 /diagnose 技能，将最佳调试实践封装成一个简单的循环。

#4：我们构建了一个大泥球

“每天都投资于系统的设计。” —— Kent Beck，《极限编程解析》(https://www.amazon.co.uk/Extreme-Programming-Explained-Embrace-Change/dp/0321278658) “最好的模块是深的。它们允许通过一个简单的接口访问大量功能。” —— John Ousterhout，《软件设计哲学》(https://www.amazon.co.uk/Philosophy-Software-Design-2nd/dp/173210221X)

问题：大多数用代理构建的应用复杂且难以修改。由于代理可以大幅加速编码，它们也加速了软件熵。代码库以空前的速度变得复杂。

解决方案是采用一种全新的 AI 驱动开发方法：关心代码的设计。这已经内置于这些技能的每一层中：

• /to-prd 在创建 PRD 之前询问你将要触及哪些模块
• /zoom-out 指示代理在整个系统的上下文中解释代码

关键是，/improve-codebase-architecture 可以帮助你拯救一个已经变成大泥球的代码库。我建议每几天在你的代码库上运行一次。

总结

软件工程基础比以往任何时候都更重要。这些技能是我将基础浓缩成可重复实践的最佳努力，帮助你交付职业生涯中最好的应用。享受吧。

参考

工程技能

我每天用于编码工作的技能。

• diagnose —— 针对难解 bug 和性能回退的有纪律的诊断循环：复现 → 最小化 → 提出假设 → 工具测量 → 修复 → 回归测试。
• grill-with-docs —— 盘问环节，根据现有领域模型挑战你的计划，打磨术语，并内联更新 CONTEXT.md 和 ADR。
• triage —— 通过一个分类角色的状态机来分类问题。
• improve-codebase-architecture —— 在代码库中发现深度改进的机会，参考 CONTEXT.md 中的领域语言和 docs/adr/ 中的决策。
• setup-matt-pocock-skills —— 搭建每个仓库的配置（问题跟踪器、分类标签词汇、领域文档布局），供其他工程技能使用。每个仓库运行一次，之后再使用 to-issues、to-prd、triage、diagnose、tdd、improve-codebase-architecture 或 zoom-out。
• tdd —— 测试驱动开发，采用红-绿-重构循环。每次垂直切片构建功能或修复 bug。
• to-issues —— 将任何计划、规格或 PRD 拆分成独立的、可领取的 GitHub 问题，使用垂直切片。
• to-prd —— 将当前对话上下文转换为 PRD，并作为 GitHub 问题提交。无需面试——仅合成你已经讨论过的内容。
• zoom-out —— 指示代理拉远视角，提供更广泛的上下文或更高层次的视角，以便理解不熟悉的代码段。
• prototype —— 构建一个可抛弃的原型来完善设计——要么是一个可运行的终端应用（用于探索状态/业务逻辑问题），要么是多个截然不同的 UI 变体，可从一条路由切换。

生产力技能

通用工作流工具，非代码特定。

• caveman —— 超紧凑的通信模式。通过去掉填充词，减少约 75% 的 token 使用，同时保持完整的技术准确性。
• grill-me —— 持续不断地被盘问计划或设计，直到决策树的每个分支都被解决。
• handoff —— 将当前对话压缩成交接文档，以便另一个代理可以继续工作。
• write-a-skill —— 创建具有适当结构、渐进式披露和捆绑资源的新技能。

杂项工具

我保留但很少使用的工具。

• git-guardrails-claude-code —— 设置 Claude Code 钩子，在执行前阻止危险的 git 命令（push、reset –hard、clean 等）。
• migrate-to-shoehorn —— 将测试文件从 as 类型断言迁移到 @total-typescript/shoehorn。
• scaffold-exercises —— 创建带有章节、问题、解决方案和解释的练习目录结构。
• setup-pre-commit —— 使用 lint-staged、Prettier、类型检查和测试设置 Husky 预提交钩子。

Stéphane - smo (@_smontlouis): /improve-codebase-architecture

我很少见过这么棒的技能。