AI Coding 实践心得
在上篇文章我介绍了openspec，这篇文章我想再向大家分享一下我的一些心得和小技巧
今天我向大家介绍的是mattpocock/skills 技能库
一、前言：AI 编程的痛点不在代码，在流程
Claude Code、Codex、Cursor 这些工具越来越强，能写能改能重构。但用久了你会发现：
- 需求还没对齐，AI 已经噼里啪啦把代码写完了（我们可以用openspec）
- 业务术语前后不一致，最后改得一地鸡毛
- 修 Bug 全靠猜，改完也不知道根因是什么
- 项目越写越乱，架构熵增肉眼可见
Matt Pocock 开源的这套 Skills For Real Engineers，本质上是一组给 AI Agent 使用的工程工作流说明书。它不是”神奇提示词合集”，而是把”追问需求 → 沉淀术语 → 编写 PRD → 垂直切片 → TDD 实现 → 诊断循环 → 架构审视”这套工程师日常纪律，翻译成 AI 能听懂并执行的指令。
二、Skill 到底是什么？
普通提示词和 Skill 化提示词的区别，可以用一个例子说明：
| 类型 | 示例 |
|---|---|
| 普通提示词 | “帮我修一下这个 bug” |
| Skill 化提示词 | “使用 /diagnose。先建立可重复运行的反馈回路，再复现，提出可证伪假设，用 instrument 验证，最后修复并补回归测试。不要在没有证据的情况下直接改代码。” |
差别很明显：前者只说目标，后者规定过程。而 AI 编程最容易翻车的地方，往往不是不知道目标，而是过程太随意。
三种使用方式
| 用法 | 适合工具 | 示例 |
|---|---|---|
| 安装成 slash command | Claude Code、Codex | /tdd、/diagnose、/grill-with-docs |
| 改写成项目规则 | Cursor | .cursor/rules/diagnose.mdc |
| 当作对话流程手动提示 | 任意 LLM | “请按 grill-me 的方式先追问我，不要直接给方案” |
所以，即使你不用 Claude Code，也能学这套方法。关键不是斜杠命令，而是把这些流程融入你和 LLM 的对话。
三、核心工程技能详解（Engineering Skills）
这是最值得认真学的一组，覆盖真实项目中的日常代码工作。推荐按以下顺序掌握：
plain
setup-matt-pocock-skills
-> grill-with-docs
-> to-prd
-> to-issues
-> tdd
-> diagnose
-> zoom-out
-> improve-codebase-architecture1. setup-matt-pocock-skills：项目初始化
含义：初始化当前仓库的 agent 技能配置。
用途：告诉其他 Skill 这个项目怎么管理 issue、有哪些 triage label、领域文档和 ADR 放在哪里。
产出：AGENTS.md 或 CLAUDE.md 里的 ## Agent skills 块，以及 docs/agents/ 下的配置说明。
对话示例：”使用
/setup-matt-pocock-skills初始化这个仓库。请先检查 AGENTS.md、CLAUDE.md、CONTEXT.md、docs/adr 和 docs/agents 是否存在，然后告诉我你准备写入哪些配置，确认后再修改文件。”
2. grill-with-docs：需求追问与术语对齐
含义：带文档沉淀能力的需求追问。官方定位与 /grill-me 同源，额外会把术语和架构决策写进项目文档。
用途：在动手前，让 agent 先”拷问”你的方案，找出含糊概念、边界条件、命名不一致和架构决策。
适合场景：
- 需求还没讲清楚
- 业务术语容易混乱
- 准备改一个已有系统
- 改动会影响模块边界或长期维护
产出：明确的需求边界、统一术语、可能更新的 CONTEXT.md 和 ADR。
对话示例：”使用
/grill-with-docs。我想给博客增加一个 AI 文章专题页。请先阅读现有内容结构和路由，再追问我需求边界。不要马上写代码。需要沉淀的术语和架构决策，请建议写入 CONTEXT.md 或 ADR。”
3. to-prd：从讨论到产品需求文档
含义：把已经讨论清楚的上下文整理成 PRD，并发布到项目配置的 issue tracker。
用途：综合口头讨论、聊天记录和代码库理解，写成正式 PRD。它会先探索仓库、梳理测试切入点，并与你确认后再按模板输出。
PRD 模板包含：
- Problem Statement
- Solution
- User Stories
- Implementation/Testing Decisions
- Out of Scope
对话示例：”使用
/to-prd。基于刚才已经确认的需求，生成一份 PRD。请包括 Problem Statement、Solution、User Stories、Implementation/Testing Decisions、Out of Scope。发布到 issue tracker 时打上ready-for-agent标签，不要再重新发散需求。”
4. to-issues：垂直切片拆分
含义：把 PRD 拆成可独立领取的垂直切片 issue。
核心原则：不要按技术层拆分（”先写数据库、再写接口、再写页面”），而要按用户可验证的结果拆分。
每个 issue 应包含：
- 背景
- 实现范围
- 非范围（Out of Scope）
- 验收标准
- 建议测试
对话示例：”使用
/to-issues。请把这份 PRD 拆成 5 个以内的垂直切片任务。每个 issue 都要包含背景、实现范围、非范围、验收标准和建议测试。不要按技术层拆，要按用户可验证的结果拆。”
5. tdd：测试驱动开发
含义：按 Red → Green → Refactor 的节奏工作。
流程：
- 先写失败测试
- 写最小实现让测试通过
- 只做必要重构
- 说明跑了哪些测试
适合场景：修 bug、加功能、改核心逻辑、项目已有测试体系时。
对话示例：”使用
/tdd实现这个 issue。请先找现有测试风格，然后写一个失败测试。测试失败后再写最小实现。通过后只做必要重构，并说明跑了哪些测试。”
6. diagnose：结构化诊断
含义：结构化诊断 bug 或性能问题，避免”看到报错就乱改”。
官方诊断循环：
plain
建立反馈回路 → 复现 → 提出可证伪假设 → instrument 验证 → 修复并写回归测试 → 清理与复盘其中「建立反馈回路」是核心——没有可重复、可自动化的 pass/fail 信号，后面几步都很难可靠。
适合场景：bug 难复现、性能退化、测试偶发失败、线上接口偶发 500。
对话示例：”使用
/diagnose。这个接口偶发返回 500。请先建立可重复运行的反馈回路（失败测试、curl 脚本、最小 harness 等），再复现。提出 3–5 个可证伪假设，每次 instrument 只改一个变量。修复前先写回归测试，最后清理调试日志并说明根因。”
7. triage：工单分拣
含义：按固定状态机处理 issue tracker 上的工单。
五个 canonical 状态角色：
needs-triage：待分拣needs-info：信息不足ready-for-agent：可分配给 agentready-for-human：需人工处理wontfix：拒绝/不修复
对话示例：”使用
/triage，列出需要我关注的未分拣和 needs-triage 工单。对 #42 给出 bug/enhancement 分类和状态建议；若信息不足先 needs-info，不要直接实现。”
8. zoom-out：系统视角审视
含义：让 agent 从局部代码跳出来，用系统视角解释当前模块。
适合场景：
- 接手陌生代码
- 开始重构前
- agent 对局部代码理解太机械
- 想知道某个模块为什么这样写
对话示例：”使用
/zoom-out。请从整个系统角度解释src/lib/posts.ts的作用。说明它和内容目录、路由生成、Markdown 渲染之间的关系。不要先给修改建议，先讲清楚上下文。”
9. improve-codebase-architecture：架构体检
含义：从架构角度寻找代码库的”加深”机会。
识别的问题类型：
- 浅模块（Shallow Modules）
- 重复概念
- 边界混乱
- 接口不清晰
对话示例：”使用
/improve-codebase-architecture。请阅读 CONTEXT.md、docs/adr 和主要模块。找出 3 个最值得改进的架构问题。每个问题都要说明症状、原因、风险、建议的小步改法和验证方式。不要直接大规模重构。”
10. prototype：快速原型
含义：做一次性原型，不以生产质量为目标，强调”扔掉原型”。
适合场景：
- 状态机还没想清楚
- UI 方向有多个版本
- 需要快速比较交互方案
对话示例：”使用
/prototype。我想探索博客首页的 AI 专题入口。请做 3 个明显不同的 UI 方向，放在一个临时 route 中切换预览。这不是生产代码，目标是帮助我比较设计方向。”
四、效率技能（Productivity Skills）
表格
| 技能 | 含义 | 适用场景 |
|---|---|---|
| grill-me | 纯追问，不绑定代码库 | 写文章前梳理观点、做产品方案、准备技术分享 |
| caveman | 极度压缩表达，只保留技术准确性 | Review diff、长上下文快满了、只想看结论 |
| handoff | 把当前对话整理成可交接文档 | 长任务中途暂停、换工具继续、让另一个 agent 接手 |
| write-a-skill | 帮助你把自己的经验写成 Skill | 某类任务反复出现，把流程沉淀成 SKILL.md |
五、实战：如何串成完整工作流
真实项目不要让 agent 从想法直接跳到代码。推荐的工作流：
plain
/grill-with-docs → 先问清楚
↓
/to-prd → 写成需求
↓
/to-issues → 拆小任务
↓
/tdd → 小步实现
↓
/diagnose → 出问题就诊断
↓
/handoff → 最后交接案例 1：实现一个新功能（给博客加”AI 专题”页）
Markdown
复制
代码预览
Step 1: 使用 /grill-with-docs
"我想给博客增加一个 AI 专题页。请先阅读当前路由、内容目录和首页结构。
然后追问我页面目标、筛选规则、展示字段、移动端表现和 SEO 要求。
不要马上写代码。"
Step 2: 使用 /to-prd
"把刚才确认的内容整理成 PRD。"
Step 3: 使用 /to-issues
"把 PRD 拆成 3 个垂直切片：
1. 内容筛选和数据结构
2. 页面路由和列表展示
3. SEO、空状态和构建验证"
Step 4: 使用 /tdd
"实现第一个 issue。先补数据筛选测试，再写实现。"案例 2：排查线上 Bug（接口偶发 500）
Markdown
复制
代码预览
使用 /diagnose。
问题：/api/report 偶发 500。
请按以下顺序：
1. 先建立反馈回路（失败测试或 curl 脚本），不要先改代码；
2. 复现并确认症状；
3. 提出 3–5 个可证伪假设，列出预测；
4. 用 instrument 验证，一次只改一个变量；
5. 有正确测试接缝时，先写失败回归测试再修复；
6. 清理 [DEBUG-...] 日志，说明根因。重要：如果 agent 急着改代码，立刻打断：
“停止实现。你还没有证明根因。请回到 diagnose 流程，先给出证据。”
六、我的使用建议
1. 不要把 Skill 当成万能插件
它本质上是流程说明，执行质量仍然取决于模型、上下文、工具权限和你的监督。
2. 优先学主流程，不要收藏所有 Skill
对大多数工程师来说，先掌握这 6 个就够了：
表格
| 优先级 | 技能 | 解决什么问题 |
|---|---|---|
| P0 | grill-with-docs | 开工前没想清楚 |
| P0 | diagnose | 出问题后乱猜 |
| P1 | to-prd | 想法无法沉淀 |
| P1 | to-issues | 任务太大一口吞 |
| P1 | tdd | 写代码没测试 |
| P2 | handoff | 会话结束无法交接 |
3. 把团队自己的经验写成 Skill
Matt Pocock 的仓库最好当模板，不要原样照搬。比如你的项目可以沉淀：
blog-research-writeup：博客写作流程cpp-code-review-checklist：C++ 代码审查规范api-gateway-deploy-verify：网关发布验证流程
4. 对第三方 Skill 保持安全意识
安装前读一下 SKILL.md，看它是否会要求执行命令、修改 Git、访问外部服务或写入敏感文件。Skill 是给 agent 的指令，指令本身也需要 review。
七、总结
Matt Pocock 这套 skills 最值得学的地方，是它把 AI 编程重新拉回工程纪律：
- 不清楚就先追问
- 有共识就写文档
- 任务太大就拆小
- 写代码要有测试
- 修 bug 要有证据
- 架构变差要定期回头看
- 会话结束要能交接
我会把它总结成一句话：
Skill 不是让 LLM 更像魔法师，而是让 LLM 更像守流程的工程师。
当你和 LLM 对话时，不要只说”帮我做”。更好的说法是：
“请按某个工程流程帮我做，并且在流程没完成前不要跳步。”
这才是 Skills For Real Engineers 真正值得借鉴的地方。
