AI 编程不只靠提示词：CodeStable 与 Matt Pocock Skills 使用指南
使用 Claude Code、Codex 等 AI 编程工具时，我们经常遇到三个问题：
- AI 没有真正理解需求，写到一半才发现方向错了。
- 大型任务超过单次对话的承载能力，越做越乱。
- 几个月后再回到项目，需求、设计和架构决策已经无法追溯。
Matt Pocock Skills 和 CodeStable 都在解决这些问题，但它们采用了不同的方法：
- Matt Pocock Skills 更像一套可以自由组合的软件工程工具箱。
- CodeStable 更像一套管理需求、设计、实现和历史的项目生命周期系统。
需要注意，早期的 EasySDD 已经迁移并演进为 CodeStable，旧仓库地址目前也会跳转到 CodeStable。(GitHub )
一句话理解两套 Skills
Matt Pocock Skills：教 AI 正确地做工程
Matt Pocock Skills 由多个相对独立的 Skill 组成。每个 Skill 负责一个明确问题，例如：
- 把模糊需求问清楚；
- 把讨论整理成规格；
- 把大型任务拆成工单；
- 使用 TDD 实现；
- 系统性诊断 Bug；
- 对代码进行独立审查。
这套 Skills 强调“小型、可组合、可修改”，不会强行接管项目的全部开发流程。(GitHub )
CodeStable：让项目拥有长期记忆
CodeStable 不以多个 Agent 如何协作为中心，而是围绕软件本身组织信息：
- Requirement：需求；
- Architecture Decision：架构决策；
- Feature：功能；
- Issue：问题；
- Goal：长期目标；
- Compound：可以复用的工程知识。
这些状态保存在项目的 .codestable/ 目录中，让人和 AI 都可以读取。它更适合需要长期维护、不断演进的正式项目。(GitHub )
Matt Pocock Skills：从模糊想法走向实现
Matt Skills 最容易理解的一条流水线是：
/grill-with-docs
↓
/to-spec
↓
/to-tickets
↓
/implement
它们分别解决四个问题：
需求是否真的明确？
↓
能否形成正式规格？
↓
如何拆成可以执行的任务？
↓
如何实现、测试和审查？
1. /grill-with-docs：先把需求问清楚
当你只有一个大致想法时，不要立刻让 AI 写代码。
例如：
我想升级项目的知识库功能。
这个描述缺少大量关键信息：
- 知识库的数据来源是什么？
- 是否支持版本历史？
- 全文检索还是向量检索？
- 删除文档后如何处理索引？
- Agent 可以访问哪些知识库？
- 数据是否需要兼容旧版本？
此时可以使用：
/grill-with-docs
它会围绕需求、领域术语、模块边界和架构决定持续提问，并把重要术语和决策记录到项目文档中。官方尤其强调通过 CONTEXT.md 和 ADR 建立人与 AI 共用的领域语言。(GitHub )
适合使用它的情况：
- 想法还比较模糊；
- 边界条件很多；
- 涉及多个模块；
- AI 很容易自行脑补；
- 需要先统一项目术语。
不适合的情况：
- 只是增加一个确定字段；
- 已经有完整设计文档；
- 修复原因明确的小 Bug。
2. /to-spec：把讨论固化成规格
当需求已经讨论清楚后，可以执行：
/to-spec
它会读取当前讨论和项目背景，将内容整理成正式规格，并写入已经配置好的 Issue Tracker。
需要特别注意：
/to-spec负责整理已经形成的决定，而不是代替需求讨论。
因此不要把一个非常模糊的想法直接交给 /to-spec。更合理的顺序是：
模糊想法
→ /grill-with-docs
→ 完成关键决策
→ /to-spec
Matt Skills 官方将其定义为：把当前会话整理成 Spec 并发布，而不是重新进行完整访谈。(GitHub )
3. /to-tickets：把规格拆成可交付工单
普通任务拆分经常会变成：
任务一：修改数据库
任务二：开发后端
任务三：开发前端
任务四：补充测试
这种横向拆分的问题是：前几个任务完成后，用户仍然得不到任何可验证的功能。
/to-tickets 更强调 垂直切片：
一张 Ticket
= 数据层
+ 业务逻辑
+ 接口
+ 界面
+ 测试
例如“文章置顶”可以被拆成一个完整切片：
增加置顶字段
→ 提供置顶接口
→ 后台增加操作入口
→ 前台按置顶规则排序
→ 增加排序测试
每张 Ticket 都应该尽可能独立完成、独立验证，并明确与其他 Ticket 的阻塞关系。(GitHub )
它特别适合：
- 多人或多 Agent 并行开发；
- 大型数据迁移；
- 需要 GitHub Issue 依赖关系；
- 一次对话无法完成的功能；
- 希望减少最后集中集成的风险。
4. /implement：按照规格进入实现
当 Spec 或 Tickets 已经准备好后，可以使用：
/implement
它会推动实际编码，并结合：
/tdd；- 类型检查；
- 自动化测试；
/code-review。
官方流程强调在预先约定的测试边界上使用 TDD，并在提交前完成代码审查。(GitHub )
因此，Matt Skills 并不是单纯要求 AI“多想一会儿”，而是给 AI 建立反馈循环：
先写失败测试
→ 实现最小代码
→ 测试通过
→ 重构
→ 代码审查
/wayfinder：大型工程的探路工具
有些任务不是“怎么实现”不明确，而是连“应该走哪条路线”都不知道。
例如：
- 全面重构为 DDD；
- 从 Lucene 迁移到 Elasticsearch；
- 合并另一个大型项目；
- 重做 AI Agent Runtime；
- 重新设计知识库的数据模型；
- 从本地应用演进为服务化架构。
这些任务很难由一次会话完成，此时适合：
/wayfinder
Wayfinder 会建立一张共享的决策地图，将大型问题拆成：
- Research：查资料；
- Prototype：做低成本原型；
- Grilling：与用户完成关键决策；
- Task：为决策准备必要条件。
每次只解决地图中的一个问题，直到通往最终目标的路线逐渐清晰。官方将它定位为：规划一个超过单个 Agent 会话容量的大型工作，并通过逐个解决决策 Ticket 来找到可执行路径。(GitHub )
典型流程是：
/wayfinder
↓
逐个完成研究、原型和决策
↓
/to-spec
↓
/to-tickets
↓
/implement
需要记住：
Wayfinder 负责探路，不负责直接把整个大型工程一次做完。
CodeStable：日常项目开发的主工作流
CodeStable 的最大特点是：日常使用时，不需要记住所有阶段命令。
完成项目接入后，可以直接调用：
/cs
它会先判断你是在咨询、了解体系，还是准备执行具体任务，然后路由到对应工作流。(GitHub )
首次接入项目：
/cs-onboard
执行后，项目中会出现类似目录：
.codestable/
├── requirements/
├── roadmap/
├── goals/
├── features/
├── issues/
├── refactors/
├── audits/
├── brainstorms/
├── compound/
├── tools/
└── reference/
这些目录用于保存需求、领域模型、Epic、Feature、Bug、重构记录以及可以重复利用的工程知识。(GitHub )
1. /cs-feat：开发新功能
新增功能时，最常用的入口是：
/cs-feat 支持文章置顶
CodeStable 会根据任务风险选择三种 Lane。
Quick：小而明确
适合：
- 增加字段；
- 调整局部界面；
- 标准 CRUD；
- 修改明确的排序规则；
- 已有接口上的小扩展。
流程大致是：
实现
→ 验证
→ 独立审查
→ 留下简短记录
Standard：需要设计或跨模块修改
适合：
- RSS 订阅；
- 访客地图；
- 权限功能；
- 新增第三方模型；
- 知识库增加版本历史；
- 同时影响前端、后端和数据结构。
流程大致是：
设计
→ 实现
→ Review
→ 验收
Goal：需要长程自主执行
适合：
- 完整知识库升级；
- 大型模块迁移；
- AI 对话系统重构；
- 多阶段架构改造；
- 需要多轮实现、验证和修正的任务。
流程大致是：
确定起点和终点
→ 持续实现与验证
→ 失败后继续修正
→ 独立 QA
→ 完整验收
CodeStable 的 Quick、Standard 和 Goal 是按照工程风险选择，而不是按照所使用的模型选择。(GitHub )
2. /cs-issue：处理 Bug
发现 Bug 后可以使用：
/cs-issue 修复删除文章后搜索结果仍然存在的问题
它会端到端推进：
问题记录
→ 根因分析
→ 修复
→ 验证
→ 代码审查
与直接让 AI“修一下”相比，它更重视：
- 能否稳定复现；
- 真正根因是什么；
- 修改范围是否失控；
- 是否增加回归测试；
- 修复历史是否被记录。
3. /cs-refactor：进行行为等价重构
当代码能够运行，但已经越来越难维护时，可以使用：
/cs-refactor 整理知识库索引模块
重构的前提是尽量保持外部行为不变。
它适合：
- 拆分过大的模块；
- 去除重复逻辑；
- 整理混乱依赖；
- 收紧模块接口；
- 改善内部命名和结构。
不要用它来偷偷加入新功能。需要改变产品行为时，应使用 /cs-feat。
4. /cs-epic 与 /cs-goal：管理大型需求
当需求本身已经清晰，但规模很大时，可以使用：
/cs-epic 重构整个知识库系统
Epic 负责：
- 大需求规划；
- 规划审查；
- 用户确认；
- 拆分子 Feature；
- 生成后续 Goal 执行包。
而 /cs-goal 更关注一个明确的起点和终点，让 AI 在约束范围内持续实现、验证和迭代。(GitHub )
可以这样理解：
Epic：决定大型工程由哪些部分组成
Goal：把其中一个长期目标真正推进到完成
两套 Skills 应该如何选择？
可以记住下面这张表：
| 当前情况 | 推荐工具 |
|---|---|
| 不知道该用什么 | /cs 或 /ask-matt |
| 小而明确的新功能 | /cs-feat |
| 跨模块功能 | /cs-feat Standard |
| 明确的 Bug | /cs-issue |
| 行为不变的代码整理 | /cs-refactor |
| 已经明确的大需求 | /cs-epic |
| 长程自主实现 | /cs-goal |
| 想法模糊，需要反复确认 | /grill-with-docs |
| 超大型且路线不明 | /wayfinder |
| 已有方案，需要拆 Issue | /to-tickets |
| 难以定位的 Bug 或性能问题 | /diagnosing-bugs |
| 希望严格按测试推进 | /tdd |
推荐的组合方式
两套 Skills 可以共存，但不要让它们同时控制同一个实现阶段。
我更推荐下面的组合：
CodeStable
负责项目长期记忆、日常功能、Bug、重构和验收
Matt Wayfinder
负责超大型问题的前期探索
Matt to-tickets
负责复杂任务的垂直切片和依赖拆分
Matt diagnosing-bugs / tdd
补充调试和测试纪律
例如，进行“Lucene 迁移到 Elasticsearch”时：
/wayfinder
先研究：
- 是否真的需要 Elasticsearch；
- 本地优先产品是否适合依赖独立服务；
- 中文分词如何选择；
- 旧索引如何迁移；
- 是否需要双写；
- 如何回滚。
路线明确后，再进入：
/cs-epic
由 CodeStable 管理后续 Feature、Goal、实现记录和验收。
三条最重要的使用原则
第一，越不明确的任务，越不要急着写代码
错误方式：
帮我全面重构这个项目。
正确方式：
/wayfinder
或者：
/grill-with-docs
先暴露问题，再形成决定。
第二，小功能不要强行使用大型流程
增加一个显示字段，没有必要创建十几张 Ticket，也不需要 Wayfinder。
直接使用：
/cs-feat 增加文章阅读时长显示
让 CodeStable 选择 Quick 即可。
第三，一个阶段只能有一个主驱动器
不要同时运行：
/implement
和：
/cs-feat
两者都可能尝试推进编码、测试和审查，容易造成状态冲突。
可以先使用 Matt Skills 探索和拆分，再交给 CodeStable 实现，但交接点必须明确。
安装速查
安装 Matt Pocock Skills
npx skills@latest add mattpocock/skills
安装时选择：
setup-matt-pocock-skills
grill-with-docs
wayfinder
to-spec
to-tickets
implement
tdd
diagnosing-bugs
code-review
然后在项目中执行一次：
/setup-matt-pocock-skills
它会配置 Issue Tracker、项目文档位置和相关工程约定。(GitHub )
安装 CodeStable
npx skills@latest add codestable/CodeStable/plugins/codestable
进入项目后执行：
/cs-onboard
之后日常直接使用：
/cs
CodeStable 也提供 Codex 和 Claude Code 的插件安装方式。(GitHub )
最后总结
Matt Pocock Skills 和 CodeStable 并不是两套互相排斥的框架。
它们分别擅长：
Matt Pocock Skills
= 如何把一项工程工作想清楚、拆清楚、做正确
CodeStable
= 如何让整个项目长期保持清晰、可追溯和可持续演进
最实用的选择方式是：
日常开发使用 CodeStable
方向模糊时使用 grill-with-docs
超大型工程使用 Wayfinder 探路
需要专业拆分时使用 to-tickets
测试和调试使用 TDD、diagnosing-bugs
最终需求、设计和历史沉淀回项目档案
AI 可以提高写代码的速度，但真正决定项目质量的，依然是需求是否明确、模块是否清晰、反馈是否及时，以及重要决策有没有被长期保存。
这正是这两套 Skills 最有价值的地方。