产品 × 研发 × 测试：从单兵提效到团队协同的 Skill 搭建指南

提速卡在了哪一层

这两年最明显的变化，是写代码这件事的门槛塌了。过去需要资深工程师才能搞定的活，现在一个人配上 AI 就能推进。但奇怪的是，团队整体的交付节奏并没有跟着翻倍。

原因不难找：AI 提升的是单点速度，而一个产研团队的瓶颈从来不在单点，而在交接。产品和研发对同一个需求的理解有偏差，测试拿到的信息总是缺一块，方案评审靠开会对齐，代码风格靠 review 兜底——这些协作成本，AI 写得再快也消化不掉。

更进一步说，如果团队里每个人都各自和 AI 对话，prompt 全凭个人手感，那 AI 越多，产出的离散度反而越大。你得到的不是一支整齐的队伍，而是十个风格迥异的「人机搭档」，谁也接不上谁的活。

所以真正该解决的命题是：让 AI 之间也能协同，而不是各干各的。 而 AI 协同的前提，不是模型更聪明，是团队先有一套机器能读懂、能执行、能自检的工程约定——需求长什么样、方案评什么、代码怎么交、质量怎么验、上下文怎么更新，全都要变成固定下来的「标准动作」。

这里有个容易踩空的地方：约定如果只写在文档里，等于没写。 文档没人维护、很快和现实脱节，AI 也不会主动去翻。约定必须被「执行化」——落进 Skill、hooks、模板和检查规则，在每一次真实交付里被自动触发，才算数。否则 AI 产能越高，制造的混乱和返工只会越多。

把上面这件事换成一句话：怎么把零散的个人提速，攒成一支团队带得走、传得下去的能力。在 Agent 的语境里，承载这种「标准动作」的单元，就叫 Skill。

「快」和「带得走」是两件事

维度	个人提速（多数团队的现状）	团队协同（这篇要搭的）
怎么用 AI	各自对话，效果看 prompt 手感	全员共用同一批 Skill 和契约
知识在哪	群聊、网盘文档、某个人的记忆	收进 .claude/，跟代码一起进版本库
交接质量	字段缺了下游补，补错了返工	上游产出即下游输入，缺字段当场拦
一致性	一件事十种做法	标准动作，结果可复现
人走了之后	隐性经验随人蒸发	留在仓库，新人 clone 即继承

Skill 的本质：一个能被自动调用的标准动作

剥到最里层，一个 Skill 就是一个文件夹，里面放一个 SKILL.md。它分两半：开头的元数据负责回答「碰到什么情况该用我」，正文负责回答「用我的时候照着做什么」。在 Claude Code 里，把这个文件夹丢进 .claude/skills/，它立刻就成了一个斜杠命令；再搭配 hooks 自动跑校验、CLAUDE.md 共享项目背景，就能串成完整流程。

它之所以能在团队规模上铺开，靠三个特性，第一个最反直觉。

特性一：按需加载，所以可以海量积累。 Skill 的内容不是一次性全部塞进 AI 的脑子，而是分层亮出来的：

平时只有那句 description 常驻，正文和附属文件都躺在硬盘上不占地方。换句话说，你建几十上百个 Skill，平时的开销也几乎可以忽略——只有被命中的那个才真正展开。这是它能当「团队知识库」用的物理基础。

特性二：单一职责，可以拼装。 一个 Skill 只干一件事，复杂任务由 AI 临场把多个 Skill 组合起来完成。所以你积累的是一批小而专的零件，而不是一个臃肿的万能体。

特性三：触发权可控。 纯参考性的规范，交给 AI 自动判断要不要用；而带副作用的操作——部署、提交、回写——可以用 disable-model-invocation: true 锁住，只允许人手动点。你不会希望 AI 看代码顺眼就自己把生产环境发了。

至于起步，没必要从零造。社区里现成的脚手架不少，从官方示例库到带 rules/skills/hooks 的生产级模板都有，fork 下来就能当骨架。但要提醒一句：模板解决的是「长什么样」，解决不了「适不适合你」。 真正的功夫在于读懂机制之后，把它改造成贴合自家流程、规范和业务知识的样子——这一步没有捷径。

先别贪多：把主链路收敛成 6 个

新手最容易犯的错，是兴奋地一口气做十几个 Skill，结果一个都没打磨好。更聪明的起步方式是先锁定一条主链路，只做支撑它的最小集合。产研交付的核心环节，其实就六个：

#	环节	Skill	主责角色	一句话职责
1	需求	write-prd	产品	把沟通记录 + 知识库 → 结构化 PRD
2	方案	write-tech-design	研发	把 PRD + 架构上下文 → 技术方案与接口契约
3	拆解	breakdown-tasks	研发	把方案 → 能独立执行的任务单
4	编码	coding	研发	带着 L0+L1+L2 → 符合规范的实现
5	验证	testcase-gen / code-review	测试 / 研发	铺用例 + 对照规范做结构审查
6	回写	update-context	全员	把本轮变更 → 沉淀回知识库

下面按产品、研发、测试三个角色，把每个 Skill 拆开看。写 Skill 的功夫，全在「输入读什么、输出哪些字段必填、什么东西不许编」这三件事上。

产品侧：让需求一出生就能被下游直接消费

中小团队的浪费，很大一块发生在「需求交接」这个动作上。write-prd 要解决的不是「帮我把字凑出来」，而是逼着 AI 从既有知识库里捞领域规则，而不是顺着上下文自己脑补一套设定。

---
name: write-prd
description: 把沟通记录、需求线索和知识库整理成结构化 PRD。需求评审、新功能立项时使用。
---

## 加载上下文
- L0：领域术语、业务规则总纲（来自 CLAUDE.md / 知识库根目录）
- 本次：沟通记录、需求线索

## 输出契约（字段必填）
- 功能目标：解决谁的什么问题，成功指标是什么
- 业务规则：必须能在知识库里找到出处；找不到的，标「待确认」而不是自己定
- 异常场景：边界、失败、并发、权限
- 验收标准：用 Given/When/Then 写，每一条都要能被测试直接转成用例

## 护栏
凡是知识库里没依据的业务设定，一律标「待产品确认」，不准假设。

研发侧：方案落成契约，编码绑死规范

write-tech-design 在执行时会先把 L0 架构文档拉进来，避免方案越写越偏离系统现状：

---
name: write-tech-design
description: 基于 PRD + 架构上下文，输出技术方案与接口契约。技术评审、排期估算时使用。
---

## 加载上下文
- L0：系统架构、技术栈、编码规范、核心 ADR
- 本次：PRD

## 输出契约
- 影响面：动到哪些模块/接口/数据表（结合代码库实际结构判断，别拍脑袋）
- 接口契约：新增/改动 API 的请求与响应结构
- 数据变更：表结构、索引、迁移影响
- 风险与兼容性：会不会破坏现有功能，灰度和回滚怎么走
- 模块边界：留给下游拆任务用

拿不准的约束，明确写「待确认」，不要替别人做主。

breakdown-tasks 负责把方案切成「能直接丢给一个 Coding Agent 独立跑完」的颗粒。颗粒里必须标清输入、输出、依赖和验收，否则 Agent 干到一半就得停下来反问：

---
name: breakdown-tasks
description: 把技术方案拆成可独立执行的任务单元。
---

输入：技术方案 + 上下文。每张任务卡输出：
- 输入：依赖哪些上游产出或接口
- 输出：交付物 + 可验证的完成标志
- 依赖：前置任务及顺序
- 验收：可测试的通过条件

颗粒度标准：能独立交给一个 Coding Agent 跑完，不需要中途追问。

编码、单测、CR 这三个可以编成一组，让 Coding Agent 自己跑「写 → 测 → 审 → 修」的小循环：编码阶段把 L0/L1/L2 三层都带上；单测阶段补齐用例；CR 阶段不光看代码风格，更要对着架构约束做结构性审查。

测试侧：从「人肉补全」转向「契约驱动」

测试是这套机制里受益最直接的一环——它的大量工作本质上是把验收标准机械地铺成用例。而上游 write-prd 强制产出的「验收标准 + 异常场景」，恰好就是这一步的现成输入。这正是整条链的精髓所在：前一棒的产出，不用翻译就能当后一棒的原料。

---
name: testcase-gen
description: 从 PRD 的验收标准与异常场景生成测试用例。需求评审完成、补测试覆盖时使用。
---

输入：PRD 的验收标准 + 异常场景 + 受影响模块（L1）。要覆盖：
- 正向：每条验收标准至少配一条
- 边界：空值、极值、长度上限、并发
- 异常：非法输入、权限不足、依赖挂了、超时
- 回归：本次改动可能波及的老功能

输出表格：用例ID | 前置条件 | 步骤 | 预期结果 | 优先级。
推不出来的细节，标「需向产品确认」，不要凭空补。

缺陷同样要进契约链路。bug-report 把问题整理成标准单子，并且反向挂回 PRD 的验收标准，让回归测试和后续回写都有据可查——凡是暴露出的新规则或新边界，标「建议回写知识库」，进入下一步的输入。

回写侧：update-context 决定这套机制能活多久

有个现象很普遍：很多团队刚上 Skill 时效果惊艳，但用上一两个月就慢慢失灵了。根子几乎都一样——知识库没跟上代码的演进，AI 还在拿着过时的事实干活。update-context 就是来堵这个漏的：每轮开发收尾时，它读 diff、PRD、方案和测试结果，把新冒出来的业务规则、变动的接口、挪过的模块边界，原路写回知识库。

它的作用还不止「让知识库追上新代码」。更值钱的是它能反向开采旧代码里的隐性知识——那些从没写进文档、只活在某个分支或某次线上事故里的规则、藏在代码里的隐式状态流转、零散的边界判断，都可以借 AI 之手梳理出来，归档进 CLAUDE.md、rules 或 references。

所以这个动作有两层意义：对新功能，它是闭环的最后一棒；对老系统，它是一点点把欠下的文档债还回来的过程。少了它，链路跑得越久，知识库和真实代码反而岔得越远。

决定成败的不是 Prompt，是工程上下文

这些 Skill 能不能稳定出活，关键不在正文措辞多讲究，而在三件偏「工程」的事。

一、上下文要分层：L0 / L1 / L2

把所有资料一股脑塞进一个 CLAUDE.md，用不了多久就成了一锅谁也理不清的粥。正确的切法是分三层，让每个 Skill 只取它真正需要的那几层：

层级	装什么	放哪
L0 项目级	系统架构、技术栈、编码规范、核心 ADR、领域术语	CLAUDE.md、.claude/rules/
L1 模块级	模块职责、接口契约、数据模型、状态流转	对应模块的 references/
L2 任务级	本次 PRD、技术方案、任务卡、diff、测试结果	由具体 Skill 在执行时临时加载

哪个 Skill 该端哪几层，下面这张表说清了。这一步出错，正文写得再漂亮，输出也会整体跑偏——因为它压根在拿错的事实推理：

Skill	加载的上下文层
write-prd	L0
write-tech-design	L0 + 本次 PRD
coding	L0 + L1 + L2
code-review	L0 + diff（L2）
testcase-gen	L1 + PRD 验收标准（L2）

二、每个 Skill 都得有输入输出契约

别只交代「帮我生成一份文档」这种话。要把四件事钉死：读哪些料、产出哪些块、哪些字段不能空、哪些内容不许编。 整条链的契约可以列成一张表：

Skill	读什么	必须产出
write-prd	沟通记录 + 需求线索 + 知识库	目标、业务规则、异常场景、验收标准
write-tech-design	PRD + 架构文档	方案、接口契约、数据变更、风险点
breakdown-tasks	技术方案	任务单（每张含输入/输出/依赖/验收）
testcase-gen	PRD 验收标准 + 异常场景	正向/边界/异常/回归用例表
update-context	本轮代码变更	模块文档、接口变更、规则补充、ADR 建议

衡量一个 Skill 好不好，不看它能不能「吐出一段通顺的文字」，而看它吐出来的东西，下一棒能不能拿来即用、不用返工翻译。

三、update-context 要被流程钉死，不能靠自觉

它绝不能是「想起来才跑一次」的可选项，得变成流程里跑不掉的一环。在 Claude Code 里，这件事交给 hooks 来强制。下面是一份可以直接抄的 .claude/settings.json 片段：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run lint --silent && npm test --silent" }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "echo '本轮结束：记得跑 /update-context 回写知识库'" }
        ]
      }
    ]
  }
}

逻辑是：一改代码就自动跑 lint 和 test；一轮收尾或 PR 合并后，提醒（或直接触发）update-context，把变更摘要先写进一份「待人工确认的上下文更新稿」。让 AI 先归拢、人再拍板，这个分工对大多数团队来说，风险和收益是平衡的。

价值闭环：让产出顺着契约自己流下去

这些 Skill 单独拎出来都只是命令，真正的威力在于按一次需求的完整生命周期把它们串起来跑。整条链是这样闭合的：

落到目录上，大致是这个样子：

.claude/
  skills/
    write-prd/         SKILL.md  references/prd-template.md
    write-tech-design/ SKILL.md  references/tech-design-template.md
    breakdown-tasks/   SKILL.md
    testcase-gen/      SKILL.md
    bug-report/        SKILL.md
    code-review/       SKILL.md
    update-context/    SKILL.md  references/context-update-checklist.md
  rules/
    coding-style.md
    architecture.md
  settings.json        # hooks 配置
CLAUDE.md

这条链能跑顺，靠两根支柱：

• 每一棒的产出，要能不加工就接到下一棒。 PRD 里有业务规则和验收标准，方案才落得下接口契约；方案里有模块边界和风险，拆出来的任务才不是一堆空泛的 TODO；任务卡写清了输入输出和依赖，Coding Agent 才能独立开跑；PRD 的验收标准齐了，测试用例才能自动铺开。任何一棒缺字段，下游要么停下来问，要么靠猜——协同就断在这里。
• 末尾一定要回写。 没有 update-context，前面所有产出的有效期就只有「这一轮对话」；有了它，新规则、接口变化、边界调整都进了知识库，下一轮才用得上最新的事实。

把整个 .claude/skills/ 提交进 Git 之后，团队规范第一次有了和代码一样的待遇——能 diff、能 review、能回滚、能强制。每个人 clone 仓库、每次开 AI 会话，都自动站在了同一套约定上。

走一遍真实需求：「导出报表」从想法到回写

抽象的链路不如一个具体例子来得实在。假设产品提了个需求：「用户能把列表导出成 Excel」。看它怎么顺着契约淌过三个角色：

留意一点：全程没有一次「等下游来追问」。产品写需求时验收标准就齐了，测试不必反复确认边界；研发的接口契约直接沉进了知识库，下回再有需求碰到导出，AI 已经知道「过一万行得走异步」。这就是协同的实质——信息在交接的那一刻被补全，而不是积到下游变成扯皮和返工。

最容易栽的三个坑

• 上下文不分层。 全堆进一个 CLAUDE.md，迟早乱成一团。把稳定的规则放 L0、模块知识放 L1、本次任务材料放 L2，让每个 Skill 各取所需，输出会稳定得多。
• 输出没契约。 write-prd 要是不强制吐出业务规则、异常场景和验收标准，下游的方案就只能靠猜；breakdown-tasks 要是不写依赖和验收，Coding Agent 就只能边做边问。一个 Skill 值不值钱，看的不是它能不能写出话，而是它的产出能不能被下一棒直接吃下。
• 只顾建新档，不还旧账。 存量系统里最要命的规则，往往压根不在文档里——它藏在某条分支、某个旧 PR、某次线上事故的复盘，或者干脆只在某人嘴里。update-context 得分一部分精力去做这种逆向打捞，把隐性规则一点点拉回知识库。否则新链路跑得越欢，知识库和真实代码就背离得越厉害。

中小团队的起步路线

别想着一步到位，按这个顺序走最稳：

• 先拿一个模块开刀。 挑一个交付频繁、又有代表性的工程，用现成的代码库梳理类 Skill 先自动生成架构图、关键路径、模块说明和一份 CLAUDE.md 初稿，再让熟悉业务的人逐条校准，把错的、漏的、没说出口的规则补进去。
• 跑通一条最短的闭环。 建议从「方案 → 拆解 → 编码/单测/CR → 回写」这段开始——它离研发最近、反馈最快，也最容易看出「首稿可用率」有没有真的往上走。需求那一棒可以先用人工输入顶着，等技术链路稳了再补 write-prd。
• 用结果倒推 Skill 的质量。 别盯着「生成得快不快」，那是表象。真正该盯的是下面这几项。

指标	看什么	健康的信号
首稿可用率	PRD / 方案被人工改动的比例	一轮比一轮少
任务可托管度	任务能不能直接丢给 Coding Agent 跑通	「边做边问」越来越少
审查有效性	CR 揪出来的问题是不是真问题	真问题占比上升，噪音下降
上下文新鲜度	回写之后，下一轮还要不要重讲背景	重复解释越来越少

写在最后

社区的现成示例，最适合拿来搭骨架；但骨架之外那些真正分胜负的东西——你自家的 L0/L1/L2 怎么分、契约怎么定、回写有没有纪律——是抄不来的。能复制的是结构，复制不了的是团队自己的知识沉淀。

对人手紧、又养不起专职流程岗的中小团队来说，这反而是性价比最高的一笔投入：你组建不了一个「流程委员会」天天盯规范，但你可以让每一条被验证有效的实践，在它被发现的那一刻就固化成 Skill，从此自动作用在每个人、每一次协作里。

到那一步，这批打磨成熟、用得顺手的 Skill，就成了团队真正带得走、传得下去的工程资产。