关于将 CONTEXT.md 重命名为 GLOSSARY.md 的讨论

随着时间的推移，CONTEXT.md 已缩减到实质上只是一个术语表，因此这样做是合理的。并且我认为，相比 DDD 中的“有界上下文”（CONTEXT.md 便源自于此）https://t.co/t0E7B95l1q，术语表要直观得多。

mattpocock/skills

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

适用于真正工程师的技能

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

我每天用于真正工程实践（而非氛围编程）的智能体技能。开发真实应用是困难的。像 GSD、BMAD 和 Spec-Kit 这样的方法试图通过接管流程来提供帮助。但这样做时，它们夺走了你的控制权，并使得流程中的错误难以解决。这些技能被设计得小巧、易于适配且可组合。它们适用于任何模型，基于数十年的工程经验。尝试使用它们，让它们成为你自己的工具。享受其中的乐趣。

如果你想跟踪这些技能的更新以及我创建的任何新技能，可以加入约 60,000 位开发者的行列，订阅我的新闻通讯： 订阅新闻通讯

安装（30 秒完成）

两种方式，两种理念。

Claude Code 插件 (https://code.claude.com/docs/en/plugins) 会将整套技能作为受管理的、只读的捆绑包安装，当我在发布时进行更新——你只需订阅，而非派生。

skills.sh (https://skills.sh/mattpocock/skills) 会将可编辑的技能文件复制到你的项目中，因此你可以修改它们，使其成为你自己的工具。

选择其一——安装两者会导致每个技能被安装两次。

1. 获取技能

Claude Code

claude plugins install mattpocock-skills

或者，在会话中：

/plugin install mattpocock-skills

它已在 Claude Code 的官方市场中，因此无需预先添加任何内容，更新也会自动到达。

Codex 及其他智能体

npx skills@latest add mattpocock/skills

选择你想要的技能，以及要将它们安装到哪个编码智能体上。

安装程序允许你选择要获取的技能——请确保 setup-matt-pocock-skills 是其中之一。

原生 Codex 插件已在计划中——请参阅 .agents/adr/0002-ship-as-a-claude-code-plugin.md。

对于喜欢折腾的人 在任何智能体（包括 Claude Code）上使用相同的安装程序：

npx skills@latest add mattpocock/skills

它会将技能以你拥有且可编辑的普通文件形式写入你的仓库。没有任何内容会在你不知情的情况下更新；当你想要获取我的最新更改时，使用 npx skills update。

2. 运行 /setup-matt-pocock-skills

在你的智能体中，每个仓库运行一次。它将：

• 询问你想使用哪个问题跟踪器（GitHub、Linear 或本地文件）
• 询问你在分类问题时为其添加什么标签（/triage 使用标签）
• 询问你希望将我们创建的文档保存在哪里

3. 搞定——你已准备就绪。

为什么存在这些技能

我构建这些技能是为了修复我在 Claude Code、Codex 和其他编码智能体中看到的常见故障模式。

#1：智能体没有执行我想要的操作

“没有人确切地知道他们想要什么”

David Thomas & Andrew Hunt，《程序员修炼之道》 (https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)

问题所在：软件开发中最常见的故障模式是错位。你认为开发者知道你想要什么。然后你看到他们构建的东西——你意识到它完全不理解你。在人工智能时代也是如此。你和智能体之间存在沟通鸿沟。

解决方法是进行 “拷问式”对话——让智能体询问你关于你正在构建内容的详细问题。

解决方案是使用：

• /grill-me - 用于非代码场景
• /grill-with-docs - 与 /grill-me 相同，但增加了更多好东西（见下文）

这是我最受欢迎的技能。它们帮助你在开始之前与智能体对齐，并深入思考你正在做的更改。每次你想做更改时都要使用它们。

#2：智能体过于冗长

通过通用语言，开发者的对话和代码的表达都源自同一个领域模型。

Eric Evans，《领域驱动设计》 (https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)

问题所在：在项目开始时，开发者和他们为之构建软件的人（领域专家）通常说着不同的语言。我在与我的智能体交互时感受到了同样的张力。智能体通常被投入一个项目，并被要求边做边弄清楚术语。因此，它们用 20 个词来表达本可以用 1 个词就能说清的内容。

解决方法是建立一种共享语言。这是一种帮助智能体解读项目中使用的术语的文档。

示例 以下是一个 CONTEXT.md 示例 (https://github.com/mattpocock/course-video-manager/blob/076a5a7a182db0fe1e62971dd7a68bcadf010f1c/CONTEXT.md)，来自我的 course-video-manager 仓库。 哪个更容易阅读？

• 修改前：“当课程章节中的一个课时被‘实体化’（即，在文件系统中获得一个位置）时出现问题”
• 修改后：“在实体化级联中存在问题”

这种简洁性在一次又一次的会话中带来回报。这已内置于 /grill-with-docs 中。它是一次拷问式对话，但帮助你与 AI 共同构建一种共享语言，并通过 ADR（架构决策记录）记录难以解释的决策。很难解释这有多强大。它可能是这个仓库中最酷的技术。尝试一下，看看效果。

共享语言除了减少冗长外，还有许多其他好处：

• 变量、函数和文件名称保持一致，使用共享语言
• 因此，代码库对智能体来说更容易导航
• 智能体在思考上花费的 token 也更少，因为它可以访问更简洁的语言

#3：代码无法工作

“总是采取小而审慎的步骤。反馈循环的频率是你的速度限制。永远不要承担过于庞大的任务。”

David Thomas & Andrew Hunt，《程序员修炼之道》 (https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)

问题所在：假设你和智能体就构建什么达成了一致。当智能体 仍然 产出垃圾代码时会发生什么？是时候审视你的反馈循环了。如果没有关于其产出代码实际如何运行的反馈，智能体将如同盲飞。

解决方案：你需要常规的反馈循环：静态类型、浏览器访问和自动化测试。对于自动化测试，红-绿-重构循环至关重要。这要求智能体先编写一个失败的测试，然后修复测试。这有助于为智能体提供一致的反馈水平，从而产生更好的代码。

我构建了一个 /tdd 技能，你可以将其插入任何项目。它鼓励红-绿-重构，并就什么构成好的和坏的测试为智能体提供大量指导。

对于调试，我还构建了一个 /diagnosing-bugs 技能，它将最佳调试实践封装在一个严谨的循环中，按阶段进行门控。

#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-spec 在创建规范之前，会询问你正在接触哪些模块。

关键的是，/improve-codebase-architecture 会扫描代码库寻找深化机会，并将候选方案呈现给你。我建议每隔几天在你的代码库上运行一次。这是一项调查，而非救援：在一个真正老旧的代码库上，它会找到真正的候选方案，但它不会为你解开泥潭。

总结

软件工程基础比以往任何时候都更重要。这些技能是我努力将这些基础浓缩为可重复实践的最佳成果，旨在帮助你发布你职业生涯中最好的应用程序。享受其中的乐趣。

参考

这些技能在一个维度上划分——谁可以调用它们。

用户调用的技能仅在你输入它们时可达（例如 /grill-me）；它们的工作是进行编排。

模型调用的技能可由你调用，或者 在任务匹配时由智能体自动调用；它们包含可重用的规范。

用户调用的技能可以调用模型调用的技能，但绝不能调用另一个用户调用的技能。

工程技能

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

用户调用

• ask-matt — 询问哪种技能或流程适合你的情况。这个仓库中用户调用技能的路由器。
• grill-with-docs — 也构建你项目领域模型的拷问式对话，精炼术语并即时更新 CONTEXT.md 和 ADR。
• triage — 通过一个分类角色的状态机移动问题。
• improve-codebase-architecture — 扫描代码库以寻找深化机会，将它们呈现为可视化 HTML 报告，然后对你选择的任何一个进行拷问。
• setup-matt-pocock-skills — 为工程技能配置此仓库（问题跟踪器、分类标签、领域文档布局）。在使用其他工程技能之前，每个仓库运行一次。
• to-spec — 将当前对话转化为规范并发布到问题跟踪器。无需面试——只需综合你已讨论的内容。
• to-tickets — 将任何计划、规范或对话分解为一组追踪子弹票，每张票声明其阻塞边——写为本地文件中的文本，或真实跟踪器上的原生阻塞链接。
• implement — 构建规范或一组票描述的工作，在预设的接缝处驱动 /tdd，并在提交前通过 /code-review 完成。
• wayfinder — 规划一大块工作，超出单个智能体会话所能承载的范围，作为问题跟踪器上的共享决策票地图——一次解决一张票，直到通往目的地的路径清晰。

模型调用

• prototype — 构建一个一次性原型来回答一个设计问题——一个用于状态/逻辑问题的可共享 HTML 文件，或几个可从一个路由切换的、根本不同的 UI 变体。
• diagnosing-bugs — 用于困难 bug 和性能回归的严谨诊断循环：构建一个在此 bug 上变红→最小化→假设→插桩→修复→回归测试的反馈循环。
• research — 针对高可信度主要来源调查一个问题，并将发现作为引用的 Markdown 文件保存在仓库中，作为后台智能体运行。
• tdd — 红-绿-重构循环的测试驱动开发。一次构建一个垂直切片的功能或修复错误。
• domain-modeling — 积极构建和打磨项目的领域模型——根据术语表挑战术语，用边界场景进行压力测试，并即时更新 CONTEXT.md 和 ADR。
• codebase-design — 用于设计深层模块的共享规范和词汇：在小接口背后提供大量功能，放置在干净的接缝处，可通过该接口进行测试。
• code-review — 对从某个固定点以来的差异进行双轴审查：规范（是否遵循仓库的编码标准，加上 Fowler 代码异味基线？）和 规范（是否忠实地实现了原始问题/规范？），作为并行子智能体运行，以免相互污染。
• resolving-merge-conflicts — 逐块处理进行中的 git merge 或 rebase 冲突，通过追溯到每一方主要来源的意图来解决，然后完成操作——绝不 --abort。
• wizard — 生成一个交互式 bash 向导，引导用户完成只有他们能执行的步骤：配置基础设施、设置凭证或 CI 密钥、浏览陌生的第三方仪表板，或运行一次性迁移或切换。

生产力

通用工作流程工具，不特定于代码。

用户调用

• grill-me — 就一个计划或设计进行无情的面试，直到设计树的每个分支都得到解决。
• handoff — 将当前对话压缩为一份交接文档，以便另一个智能体可以继续工作。
• teach — 使用当前目录作为有状态的教学工作区，通过多个会话向用户教授一项新技能或概念。
• to-questionnaire — 将你无法独自回答的决策转化为一份 Markdown 问卷，交给唯一能回答的人——异步填写，或在会议中一起填写。它拷问你的是发送方（给谁，你需要什么回来），而不是主题本身。
• wait-what — 在消息未被理解时立即触发。智能体会用你缺失的上下文，使用你的 CONTEXT.md 词汇，用清晰的语言重新阐述。

模型调用

• grilling — 就一个计划、决策或想法对用户进行无情的面试，直到设计树的每个分支都得到解决。grill-me、grill-with-docs、triage、wayfinder 和 improve-codebase-architecture 背后的可重用面试原语。
• writing-for-agents — 为智能体编写文档：技能、AGENTS.md/CLAUDE.md，以及智能体通过指针访问的任何文档。