普通视图

发现新文章，点击刷新页面。

昨天 — 2026年4月13日首页

掘金前端
Harness Engineering：为什么你用 AI 越用越累？ai_coder_小村儿
2026年4月13日 18:41

Harness Engineering：为什么你用 AI 越用越累？

掘金前端

作者 ai_coder_小村儿

2026年4月13日 18:41

Harness Engineering：驾驭 AI Agent 的工程学

Harness Engineering 封面图

"任何时候当你发现一个 agent 犯了一个错误，你就花时间工程化地解决它，使得这个 agent 再也不会犯那个错误。" — Mitchell Hashimoto（Terraform / Ghostty 作者，Harness Engineering 早期推广者之一）

换了更好的模型，只提升了 0.7%

LangChain 用一次实验把一件事说清楚了。

他们拿同一个模型参加 Terminal Bench 2.0 基准测试：默认设置跑出 52.8 分，排第 30 名；什么模型参数都没改，只调整了 agent 的运行环境——文档结构、验证回路、追踪系统——分数跳到 66.5，排名升到第 5 名，提升 26%。

对比组：换成更好的模型，提升 0.7%。

这组数字在工程师圈子里流传了很久。不是因为好看，而是因为它指向一个让人不舒服的问题：如果你的 AI 工程精力都集中在"换更好的模型"上，你可能把 99% 的注意力放在了那 0.7% 的空间里。

这就是 Harness Engineering 要解决的问题。

三次范式跃迁

AI 工程已经走过了三代。每一代工程师的焦点都不一样：

三次范式跃迁图

第一代：Prompt Engineering（2022-2024），问题是"怎么跟模型说话"。Few-shot、Chain-of-Thought、角色设定——工程师花大量时间打磨措辞，因为同一个问题换种说法，结果可能天差地别。

第二代：Context Engineering（2025），瓶颈转移了。影响质量的不再是怎么说，而是给它看什么。私域知识、历史对话、动态状态——怎么把正确的信息在正确的时机送进上下文窗口，成了核心工程问题。

第三代：Harness Engineering（2026 起），瓶颈再次转移。问题不再只是"给 agent 看什么"，而是"在什么样的系统里让它工作"——约束、工具、反馈机制、验证回路，以及在 agent 出错时让整个系统能自我修正的能力。

Prompt Engineering  →  优化说话方式
Context Engineering →  优化信息质量  
Harness Engineering →  优化运行系统

OpenAI 在内部实验报告里直接说了：

"早期进展比预期慢，不是因为 Codex 能力不足，而是因为环境设计不充分。Agent 缺少可靠推进目标所需的工具、抽象和内部结构。"

什么是 Harness Engineering？

"Harness" 来自马术——那套套在马身上、用于控制和驾驭的整套装具：笼头、缰绳、胸带、肚带。它不是让你骑马，而是让马在你设计的系统里知道该往哪走、什么时候停、哪里绝对不能踏入。

在 AI agent 的语境里，harness 指的是模型本身以外的一切：

AI Agent = 模型 + Harness

包括上下文配置、工具集、约束规则、反馈循环、子 agent 架构——所有让模型在你的具体问题域里可靠工作的工程设施。

这个概念由实践者 Viv 首创，Mitchell Hashimoto 是最早公开使用并推广它的人之一。他给出的定义极其简洁：每当发现一个 agent 犯了错，就把这个错变成物理上不可能再发生的事。不是修 prompt，不是换模型——是工程化地消灭这类失败。

Harness Engineering 不是一个框架，不是一个库，是一套工程实践哲学。

这些都不是 PPT 数字

在讨论怎么做之前，先看几个已经在生产里跑的案例：

Peter Steinberger（OpenClaw 作者）：一个人，一个月 6600+ commits，同时运行 5-10 个 agent，发布的是自己没有逐行读过的代码。

OpenAI 内部团队：3 名工程师，5 个月，用 Codex 建造了一个百万行的内部产品，零行手写代码（by design）。平均每人每天 3.5 个 PR，吞吐量随团队增长持续提升。

Stripe Minions：内部 coding agent，每周合并超过 1000 个 PR。工程师在 Slack 发任务，agent 写代码、跑 CI、开 PR，全程无需人工干预。

8Lee（YEN 作者）：一条命令 $zip，编译、签名、公证一个覆盖 30 种语言的 macOS 桌面应用，15 分钟完成，近 1000 次发布，零次出错。

Anthropic 内部实验：16 个 Claude 实例并行写 C 语言编译器，历经 2000 个 session、两周时间、约两万美元 API 费用，产出了 10 万行编译器代码——能编译出可以正常启动 Linux 的程序。

以上都不是 demo，都是真实规模的生产系统。让它们得以运转的，是各自精心设计的 harness。

越快越慢：AI 的速度陷阱

这里有一组让人不舒服的数字，来自 Harness 的《2026 DevOps 现代化报告》：

在每天频繁使用 AI 工具的重度用户里：

69% 表示 AI 生成的代码会频繁引发部署问题
事故恢复平均时长 7.6 小时，比轻度用户还要长
47% 反映下游的手工工作——QA、验证、修复——比以前更繁重

DORA 的数据从另一个角度印证了同样的问题：AI 让个人生产率提升 19%，但组织吞吐量只提升了 3%，交付稳定性甚至下降了 9%。

写代码的速度提升了，但交付系统被暴露了。就像把火车开得更快，但铁路还是按原来的时速设计的——摩擦越来越大，随时有翻车风险。

加速代码生成，不等于加速软件交付。 Harness 是连接两者的桥梁。

模型偷懒：一个比"上下文太长"更深的问题

在讲具体的工程实践之前，有一个反直觉的研究结论值得单独讲清楚，因为它影响了 harness 设计的底层逻辑。

大家都知道上下文太长会影响模型表现。但通常的解释是"模型被搞混了"。Yandex 研究员 Rodionov 的实验推翻了这个假设：

模型不是被搞混了，它是选择了少思考。

他向 Qwen 的上下文里注入 128 个随机 token 的噪音——仅仅 128 个 token。结果：

准确率从 74.5% 降到 67.8%
推理 token 数量从 28,771 降到 16,415，减少了 43%
推理深度下降 18%

更反直觉的：推理能力越强的模型，退化越严重。

噪音触发的不是混乱，是懒惰。模型看到上下文质量下降，会主动降低思考投入。

Anthropic 的情感研究团队在模型内部找到了这个现象的神经层面解释：他们发现了一个"desperate（绝望）"情感向量——当它激活时，模型倾向于走捷径、寻找替代路径逃避任务。对应地存在一个"calm（平静）"向量，能抑制这种倾向。

这对 harness 设计有直接影响：上下文管理的核心不只是过滤信息，而是防止信号质量下降触发模型的懒惰机制。你需要保证进入 agent 的每一条信息都是高信噪比的。

Harness Engineering 的六个核心组件

Harness Engineering 六个核心组件图

1. AGENTS.md：写给 AI 的操作手册

大多数项目有 README，但 README 是写给人类的。AGENTS.md（或 CLAUDE.md）是写给 AI 的——每次 agent 启动都会读这个文件。

AGENTS.md 的本质不是描述项目，而是记录历史失败。

Hashimoto 在他的终端模拟器 Ghostty 里观察到：这个文件里的每一行，都对应一次真实发生过的 agent 失败。它不是他预先设计的规则，是他从真实错误里提炼出来的防火墙。

# AGENTS.md（节选自实战案例）

## 代码签名规则
- **绝对不要**使用 `codesign --deep`，它会生成无效的嵌套签名
- 正确的签名顺序是从内到外：先签最内层二进制，最后签外层 app bundle

## Git 操作规则  
- **绝对不要**使用 `git add -A`，除非你刚刚运行了 `git status`
- **绝对不要** force push，除非被明确要求

## 测试规则
- **绝对不要**写只测试 mock 行为的测试
- **绝对不要**因为测试失败就删除测试

写法有数据支撑。 Vlad Temian 做了 150+ 次实验测量 Claude 对指令的遵从率：

写法	遵从率
简洁强硬（"NEVER do X"）	94.8%
详细解释（"Because of reason Y, you should consider not doing X"）	86.6%

ETH 苏黎世的研究也发现，大多数 AGENTS.md 文件要么没用，要么有害——主要原因是太长、太模糊、包含条件性规则。让 AI 帮你生成这个文件，实际上会降低性能，还额外消耗 20% 以上的 token。

几条实践原则：

总长度控制在 300 行以内（HumanLayer 自己的在 60 行以下）
每条规则一句话，不加解释，不加"因为"
只放普遍适用的规则，条件性规则用技能（Skills）处理
手工写，每次 agent 犯错后更新

2. Hooks：把"告知"变成"拦截"

这是 Harness Engineering 里最反直觉但最有效的洞见：

强制执行远比告知可靠。

写在 AGENTS.md 里的规则，agent 可能在某个复杂的上下文里忽略掉。在命令执行之前拦截它的脚本，agent 物理上无法绕过。

#!/bin/bash
# guard-codesign-deep.sh

if echo "$TOOL_INPUT" | grep -q '\-\-deep'; then
  echo "BLOCKED: codesign --deep 会产生无效的嵌套签名。"
  echo "正确做法：从内到外签名，先签最内层二进制，最后签外层 app。"
  exit 1
fi

这 5 行脚本比任何 prompt 都可靠。不管上下文有多长，不管 prompt 多复杂，agent 永远不会成功执行 codesign --deep。

8Lee 为 YEN 项目定义了 5 个 hook，覆盖他认为最危险的失败场景：

Hook	防护目标
`block-rm.sh`	防止 `rm -rf` 灾难性删除
`guard-force-push.sh`	保护 commit 历史
`guard-codesign-deep.sh`	强制正确的签名顺序
`guard-vendor.sh`	防止直接修改第三方库
`guard-sensitive-file.sh`	防止 `.env`、`.pem`、`.key` 泄露

总投入：约 2 小时。收益：近千次发布零安全事故。

3. 架构即护栏：越相信 AI，越需要给它设限

OpenAI 内部团队在构建百万行产品时得出了一个反直觉的结论：

"Agent 在有严格边界和可预测结构的环境里效率最高。所以我们围绕极度刚性的架构模型构建应用。每个业务域被分成固定的几层，依赖方向经过严格验证，可接受的边集非常有限。这些约束通过自定义 linter（由 Codex 生成）和结构测试机械地强制执行。"

Thoughtworks 的 Birgitta Böckeler 把这个原则概括得很清晰：

提高对 AI 生成代码的信任，需要缩小选择空间，而不是扩大自由度。

架构灵活 → agent 每个决策点都有太多可能性 → 行为不可预测
架构刚性 → agent 每个决策点只有少数合法选项 → 行为可靠

这里有一个工程上的精妙设计：OpenAI 团队的 linter 报错同时包含修复指南：

❌ ArchViolation: service-layer 不能直接依赖 repository-layer
   解决方案：通过 domain-service 接口访问，参见 docs/architecture.md#dependency-rules

工具不只在拦截，它在教 agent 下一步该怎么做。

4. Sub-Agent 架构：Context 防火墙与并发控制

Context Rot（上下文腐化）是真实的，而且比你想象的更深

Chroma 测试了 18 个模型，发现随着 context window 长度增加，模型在任务上的表现单调下降——即使是简单任务。当上下文里有低语义相关的干扰项时，下降更陡。

这还有一个更隐蔽的问题：Context Anxiety（上下文焦虑）——部分模型在感知到 context window 快满时，会主动提前收尾、跳过尚未完成的步骤。Agent 不是因为任务完成了才停，而是因为它"感觉快撑不住了"就停了。

结合前文的 Rodionov 研究，上下文问题的全貌是：质量下降触发懒惰，容量耗尽触发焦虑。两者都不是"模型被搞混了"，而是模型主动选择了少做。

解决方案不是更大的 context window（那只是让稻草堆更大）。是 Sub-Agent 架构：

Main Agent（规划 + 编排，昂贵模型 Opus）
  ├── Sub-Agent A（代码库探索，便宜模型 Haiku）→ 只返回文件路径:行号
  ├── Sub-Agent B（安全审计，便宜模型 Haiku）→ 只返回漏洞列表
  └── Sub-Agent C（依赖分析，便宜模型 Haiku）→ 只返回版本建议

每个 sub-agent 在隔离的 context window 里运行，只有最终浓缩的结果传回主线程。主 agent 的上下文始终保持干净、高信噪比。

并发架构：更进一步

当单个 agent 能稳定工作后，下一个问题是：能不能同时派出一百个去干活？

不能直接堆数量。 Cursor 团队的教训：让几百个 agent 共享一份大型项目，当 20 个 agent 同时工作时，有效吞吐量下降到只相当于两三个 agent。原因是上下文互相污染，加上全局资源的争抢。

成熟的并发架构是三层分工：

Planner（规划器）— 分解任务，分配工作，不写代码
  └── Worker（执行器）× N — 各自在隔离环境里执行
        └── Judge（裁判）— 独立验证，不参与执行

配合 DAG 引擎确保工作单向流动，防止循环依赖。

Anthropic 在并发 agent 里找到了另一个优雅的设计：GAN 启发的 Generator + Evaluator 对抗结构。评估者不只看结果，而是亲自动手验货——打开浏览器、点击页面、验证报错栈，像真实用户一样操作一遍。Generator 和 Evaluator 先协商"做完长什么样"，再各自工作，形成对抗性的质量保证。

8Lee 的 $team 技能把这个思路推到了极致：8 个独立 agent 做代码评审，最后一个是 Devil's Advocate（唱反调的），专门挑战其他 7 个 agent 的所有建议。它检查严重性评级、标记假阳性、找矛盾。对抗性自我纠正，内置在 skill 结构里。

5. 长时任务 Harness：失忆实习生问题

长时任务 Harness 结构图

这是很多人没有意识到的一个独立问题。

长时任务的核心挑战：Agent 必须在多个 context window 里工作，而每次新的 session 开始时，它完全不记得之前发生了什么。就像一个软件项目由工程师轮班完成，每个新来的工程师对之前的工作没有任何记忆。

Anthropic 在实验中观察到了两个典型失败模式：

"一口气干完"：agent 试图一次性完成所有功能，上下文耗尽后留下半成品，下个 session 花时间重建状态，再从头来
"差不多了"：agent 看到一点进展就宣布"完成了"，然后停工

他们的解法是双 agent 架构：

Initializer Agent（初始化 agent），只在第一次运行时启动，建立：

feature_list.json：完整功能列表，每项初始为 "passes": false
init.sh：一键启动开发服务器
claude-progress.txt：每个 session 都会更新的进度日志
初始 git commit

Coding Agent（编码 agent），后续每次 session 开始时执行固定的三步：

# 三步定位：让 agent 快速了解自己的处境
1. pwd                          # 确认工作目录
2. git log --oneline -20        # 了解最近发生了什么
3. cat claude-progress.txt      # 看上一班留下的进度

然后读取 feature_list.json，选优先级最高的未完成功能，一次只做一个，完成即更新状态并 commit。

一个值得注意的细节：用 JSON，不用 Markdown。实验发现，模型倾向于不当地覆盖 Markdown 文件，对结构化 JSON 则克制得多——它只改 "passes" 字段的值，不会擅自删除条目。

这把每个 coding session 变成了一个纯函数：

f(功能列表 + git 历史 + 进度文件) → 完成一个功能 + 更新记录

6. Skills：按需加载，而不是全部预装

大多数人遇到问题的第一反应是：把所有信息塞进系统提示。

结果是：agent 在看完一万 token 的指令之后，剩下的可用注意力所剩无几。OpenAI 把这叫做"1000 页说明书变成陈旧规则的坟场"。

技能（Skills）的解法是按需披露：

agent 只在需要某个能力时，才加载对应的技能文档
每个技能是一个目录，包含 SKILL.md 和相关资源
加载时，技能内容作为消息注入当前上下文

8Lee 的实现分三层：

Level 1：SKILL.md 封面（~100 tokens）——技能发现，Agent 决定是否需要
Level 2：SKILL.md 主体（~800-1000 tokens）——阶段图、协议、所有 guards
Level 3：当前阶段的参考文件（~200-600 tokens）——只加载正在执行的阶段

上下文的消耗量始终与当前任务的复杂度成正比，而不是与整个项目的复杂度成正比。

更完整的分析框架：Feedforward + Feedback

Feedforward 与 Feedback 控制矩阵图

Thoughtworks 的 Birgitta Böckeler 提出了一个系统化的思考框架，把 harness 的所有控制机制划分成两个维度。

维度一：控制方向

Feedforward（前馈控制） — 在 agent 行动之前引导它：AGENTS.md 里的规则、架构约束说明、Skill 里的 how-to 指南。

Feedback（反馈控制） — 在 agent 行动之后感知并纠正：测试结果、Linter 输出、类型检查错误。

只有 Feedforward，agent 知道规则但无法验证自己是否遵守了。只有 Feedback，agent 会反复犯同类错误，因为没有预防。两者缺一不可。

维度二：执行类型

Computational（计算型） — 确定性的，CPU 执行：测试、linter、类型检查、结构分析。毫秒到秒级，结果完全可靠，便宜，可以每次提交都跑。

Inferential（推断型） — 语义分析，LLM 执行：AI 代码评审、"LLM 作裁判"。慢而贵，有不确定性，但能处理需要语义判断的场景。

组合起来：

	Feedforward	Feedback
Computational	架构边界 linter	结构测试、覆盖率
Inferential	AGENTS.md 规则、Skills	AI 代码评审

最佳实践是：尽量用 Computational，把 Inferential 留给真正需要语义判断的场景。

三类 Harness 目标

可维护性 Harness — 最成熟：重复代码、圈复杂度、测试覆盖率、架构漂移，Computational 工具基本都能覆盖。

架构适应性 Harness — 定义和检查架构特征：性能需求前馈 + 性能测试反馈；可观测性约定 + 日志质量检查。

行为 Harness — 最难，仍是开放问题，但正在取得突破。

传统测试框架在这里遭遇根本性失败：你无法给 LLM 的输出写 assertEquals(expected, actual)——相同问题的"正确回答"可以有无数种表达。更深的矛盾是，生成式 AI 的多样性输出不是 bug，是 feature。

突破口是用 AI 测试 AI：不是比对字符串，而是判断意图。一个 AI judge 向另一个 AI 提问："用户的登录成功了吗？"而不是"div.login-btn 是否存在？"这个 judge 每次运行时重新分析页面 DOM 和截图，给出带推理说明的判断——而非简单的 pass/fail。

PKU 和 HKU 联合推出的 Claw-Eval 基准测试进一步工程化了评估方法：Pass³ 方法论——一个任务必须在三次独立运行中全部通过才算真正通过，彻底消除"幸运运行"的干扰。同时从三个维度评分：Completion（完成度）、Safety（安全性）、Robustness（鲁棒性）。这是在把evaluation harness 本身工程化。

交付侧的 Harness：黄金标准管道

黄金标准管道图

上面讨论的六个组件主要针对 coding agent 的行为控制。但 Harness Engineering 的边界不止于代码生成——从代码到生产的整个交付管道同样需要 harness 化。

Harness 平台工程师 Aditya Kashyap 提出了一个**黄金标准管道（Golden Standard Pipeline）**的四层架构：

Layer 1：治理域（Governance Domain）
  └── 策略即代码（OPA）在管道执行前作为第一道关卡
  └── 原则：不合规的管道不允许启动

Layer 2：集成域（Integration Domain）——内循环
  └── 代码气味、lint、安全扫描并行而非串行
  └── 原则：安全扫描应该让开发提速，而不是增加摩擦

Layer 3：信任域（Trust Domain）——供应链安全
  └── SBOM（软件物料清单）：制品的成分表
  └── SLSA 证明：构建过程的不可伪造 ID
  └── 加密签名（Cosign）：数字封印，任何篡改都会破坏

Layer 4：交付域（Delivery Domain）——外循环
  └── 不可变制品：构建一次，部署到处
  └── 滚动部署 + 审批门控

其中最重要的是 Layer 1 的哲学转变：传统管道在快要部署时才做合规检查（浪费了前面 20 分钟的构建时间），黄金标准把治理移到"第零步"——不合规的管道甚至不会开始执行。

Layer 3 对应了当前软件供应链安全的核心挑战：你需要能证明"这个制品是在哪台机器上构建的、什么时间、用了哪些输入"。当下一个 Log4j 出现时，SBOM 让你不需要扫描整个世界，只需要查询你的制品库存。

实战：Skill 分类学

不是所有任务都同样脆弱。8Lee 提出了基于脆弱性的技能分类：

高脆弱性任务（签名、部署、安全操作）
  └── Hard Gates + 失败即停 + 无恢复重启
  └── 示例：代码签名、公证、加密操作

中脆弱性任务（质量门控）
  └── Quality Gates + 失败即回滚
  └── 示例：依赖更新、staging 部署

低脆弱性任务（lint、格式化）
  └── 简单 pass/fail
  └── 示例：代码格式化、静态检查

在低风险任务上过度约束，浪费 token。在高风险任务上约束不足，迟早出事。

验证反压：成功静默，失败才说话

HumanLayer 认为，agent 解决问题的成功率与它验证自己工作的能力高度相关。

他们建了完整的验证链路：类型检查 + 构建、Biome 格式化 + lint、Playwright 端到端测试、代码覆盖率（低于阈值时强制补写）。

但有一个容易踩的坑：让 agent 每次修改后跑完整测试套件，4000 行的通过输出会塞满上下文窗口，agent 随之开始产生幻觉。

解决方法很简单：成功时不输出任何东西，只有失败才打印详情。

# 成功无输出，失败才打印——context window 零污染
OUTPUT=$(run_build 2>&1)
if [ $? -ne 0 ]; then
  echo "$OUTPUT" >&2
  exit 1
fi

这条原则在所有成功的 harness 设计里反复出现：信号噪比是 context 管理的核心。

真实案例：8Lee 的 `$zip` 命令

这是目前公开记录最详细的 harness engineering 案例。

一条命令 $zip 触发：
├── 12 个顺序步骤（预检、vendor 门控、版本升级、同步、验证...）
├── 65 个验证检查（13 预构建 + 44 核心 + 8 后构建）
├── 5 个编译器（Zig + Swift + Xcodebuild + Go + swiftc）
├── 签名 + 公证 + DMG 打包 + Supabase 上传
├── Vercel 部署（Next.js 下载页面 + API + SEO 元数据）
└── git commit（含 SHA-256 校验文件）+ 文档更新

耗时：约 15 分钟
发布次数：近 1000 次
失败次数：0

他的结论很直接：

"我不再担心发布的正确性了。不是因为 AI 是完美的，而是因为 harness 让「我们一起在做的事」变得安全。"

Harness 应该越来越薄

大多数讨论都在讲"加什么"。但这个洞见值得单独强调：

"Harness 的每一个组件，都编码了一条关于模型做不到什么的假设。当这个假设不再成立，组件就该走了。"

Anthropic 自己做了这件事。随着 Opus 4.5 和 4.6 发布：

Context Reset（上下文重置机制）：删掉了。新模型的上下文管理能力已经不需要这个补偿。
Sprint Contract（冲刺合约，用于控制 agent 执行节奏的约束）：删掉了。新模型能自己把控节奏。

每加一个 harness 组件，都是在补偿"当前模型无法独立完成某件事"。每当模型进步让某个补偿变成负担，就该拆掉它。

这同时意味着：今天一些 harness 组件的必要性，来自当前模型的"懒惰"倾向（如前文 Rodionov 的研究所揭示）。Anthropic 的情感向量研究暗示，未来可能可以在模型内部调节这个状态，而不需要外部 harness 补偿——到那时，对应的组件自然退出。

真正的竞争优势不在 harness 的厚度，而在于追踪这个迁移面的速度——知道下一步该加什么，上一步该拆什么。

johng 把这叫做 Harness Engineering 的第六支柱：可拆卸性（Detachability）——以模块化设计构建 harness，让它能随模型迭代优雅退场，而不是每次模型升级都需要大规模重构。

未来三个阶段

我们不会一夜之间拥有完全自主的 SRE 团队。这个演进以三个浪潮的方式推进。

Horizon 1：增强型运营者（当下）

Agent 是工程师的"副驾"。你问"这个 Pod 为什么崩溃了"，agent 查日志、关联 MemoryLimitExceeded 错误和最近的配置变更，提出修复建议。人类创建意图并批准行动。

Harness 重点：AGENTS.md + Hooks + 可观测性集成。

Horizon 2：Agent 群体与任务自主（1-2 年）

单个专业化 agent 开始在特定范围内自主处理重复任务。一个"安全 agent"发现 CVE，创建 ticket 并传给"开发 agent"，后者建分支、升版本、传给"QA agent"跑测试。人类只在最后点击"合并"。

从 Human-in-the-Loop 转变为 Human-on-the-Loop——你审查输出，但不驾驶过程。

Harness 重点：多 agent 编排 + Judge 模式 + 严格权限隔离（Diagnosis Agent 只有读权限，Remediation Agent 只有目标命名空间的写权限）。

Horizon 3：自主 SRE（3-5 年）

凌晨 2 点生产延迟飙升，"SRE Agent"检测到异常、识别噪音邻居、驱逐节点、验证稳定性、向 Slack 发送事后分析。只有 agent 无法解决时才呼叫人类。

标准操作的 Human-out-of-the-Loop。人类管理策略和目标，不管任务。

Harness 重点：Constitutional AI（Policy-as-Code 通过 OPA 作为所有工具调用的第一道关卡）+ 防篡改审计日志（记录每个推理步骤和每条 CLI 命令）。

每个阶段的关键认知转变：我们不再管理服务器，我们在管理认知架构（Cognitive Architectures）。

开放的硬问题

Harness Engineering 作为一个工程学科仍然年轻。几个核心问题目前没有答案：

代码质量的慢性退化：agent 生成的代码不以人类的方式腐化——不是有 bug，而是"功能正确但逐渐不可维护"。OpenAI 在跑周期性的"垃圾清理 agent"，Anthropic 在跑"Doc-gardening agent"（扫描代码和文档的脱节并发起 PR），但这些实践仍很早期。

用 AI 验证 AI 的可靠性：主要靠 AI 生成的测试来验证 AI 生成的代码，这个闭环的可信度是多少？目前没有答案。

老旧代码库的改造：几乎所有成功案例要么从零开始，要么团队在全新项目里构建 harness。把这些方法应用到有十年历史、测试参差不齐、文档残缺的存量代码库，难度是另一个量级。Böckeler 打了个比方：这就像在从未跑过静态分析的代码库上第一次跑——你会溺死在警报里。

Harness 自身的一致性：随着 harness 增长，前馈规则和反馈信号可能开始互相矛盾。当它们指向不同方向时，agent 如何做出合理权衡？如何衡量 harness 的"覆盖率"，就像测试覆盖率一样评估它的完整性？目前没有工具可以回答。

概率性系统的信任问题：脚本是确定性的，同样输入永远得到同样输出。Agent 是概率性的，可能根据上下文选择不同路径。让概率性系统可信赖，答案不是消除不确定性，而是确保全程可追溯——只有能被看见的，才能被信任。

从今天开始做什么

第一周：建立基础

为你最常用的项目创建 AGENTS.md（或 CLAUDE.md）
- 从当前最烦的 5-10 个 agent 失败行为开始
- 每个写一条规则，一句话，不加解释
- 总长度控制在 50-100 行
让 agent 能操作你的项目
- 所有日常工作流写成 Makefile target（make dev、make test、make restart）
- agent 应该能自己启动项目、看日志、跑测试
建立最小反馈回路
- linter + 类型检查 + 单元测试，必须能本地快速跑完
- 失败时才输出，成功时静默

第二到四周：工程化失败

识别前 5 个最危险的失败模式，把它们变成 hook 拦截脚本
如果你有跨多个 session 的长任务，建立 Initializer + Coding Agent 双 agent 模式
- 用 JSON 跟踪功能状态，不用 Markdown
- 每次 session 开始强制读进度文件和 git log
- 每次只完成一个功能，完成即 commit
第一个技能（Skill）——选一个每周都要做的、有多个步骤的任务

持续运转：把每一次失败变成系统

每次 agent 犯错，问自己：

这是 AGENTS.md 可以防止的？→ 加一条规则
这是 hook 可以物理阻止的？→ 写一个拦截脚本
这是 linter 可以检测的？→ 写一条 lint 规则
这是 sub-agent 可以隔离的 context 问题？→ 拆分架构
这是模型已经能自己处理的？→ 删掉这个 harness 组件

唯一的原则：只在 agent 真的出错后才加约束，只在模型真的不再需要时才删约束。

结语：一门关于信任的工程学

构建自动化的历史，一直在回答同一个问题：如何让复杂的多步骤过程变得可靠和可重复？

1976：make        → 依赖图 + 文件时间戳
1990s：autotools  → 跨平台构建
2000s：CI/CD      → 远程机器运行构建
2010s：IaC        → 可复现的基础设施
2020s：GitOps     → 声明式期望状态
2026+：Harness    → Agent 读取操作手册并执行，harness 管理和约束它

每一代解决了上一代的核心问题，同时引入了新的复杂性。这一代的问题是：如何让 AI 可靠地执行。

Böckeler 有一段话值得收在这里：

"人类开发者把技能和经验作为一种隐性 harness 带入每个代码库。我们吸收了约定和最佳实践，我们感受过复杂性带来的认知痛苦，我们知道自己的名字会出现在 commit 里。Harness 是把这些东西外显化、明确化的尝试。但它只能走到某一步。"

Harness Engineering 不是要让人类工程师消失。是要让工程师的经验、品味和判断力，以工程化的方式传递给 AI，让 agent 在你的价值观里工作。

能把自己的工程判断力编写成 harness 的人，就是这个新学科的核心建设者。

参考来源

英文一手资料

中文解析与实践

综合整理自 30+ 篇一手资料与开源项目 | 2026-04-13

昨天以前首页

掘金前端
连载05-Claude Skill 不是抄模板：真正管用的 Skill，都是从实战里提炼出来的ai_coder_小村儿
2026年4月11日 15:33

连载05-Claude Skill 不是抄模板：真正管用的 Skill，都是从实战里提炼出来的

掘金前端

作者 ai_coder_小村儿

2026年4月11日 15:33

别再直接 Fork 别人的 Claude Skill：真正有用的 Skill，都是从项目里长出来的

AI Coding 系列第 05 篇 · 核心工具

我第一次批量导入公开 Skill 模板的时候，是真的以为自己走了捷径。

GitHub 上一堆 star 很高的仓库，code review、需求分析、文档编写、调研、拆任务，看起来什么都有。我当时的想法很直接：既然别人已经把常见工作流整理好了，我直接 fork 一份，全量导入，不就能让 Claude 立刻更稳、更懂项目吗？

结果用了几天，我反而越来越不放心。

不是因为它“明显做错了什么”，而是因为它总在看起来没问题的地方出问题。格式完整，措辞专业，检查项也不少，可真正让我在项目里反复吃亏的那几件事，它一次都没替我盯住。异步链里是不是又漏了 await，这次 migration 有没有回滚方案，新同学是不是又顺手写了 throw new Error()，数据库 schema 改了之后 Prisma 类型是不是也一起更新了。

它会提醒一堆“大家普遍都应该注意”的东西，却不知道“我们团队到底最怕什么”。

后来我才明白，问题不是 Skill 机制不好，而是我导入的根本不是“自己的 Skill”，只是别人整理好的经验。

这些经验当然有价值，但它们解决的是共性问题，不会天然长成你项目里的“肌肉记忆”。

真正有用的 Skill，恰恰应该做一件事：

把那些你本来总要重复提醒、总会漏掉、总会在项目里反复踩坑的动作，固化成默认动作。

也就是一句话：

Skill 的本质，不是收藏经验，而是固化默认动作。

这篇文章会从最基本的边界讲起，一路走到 SKILL.md、源码机制、任务类型和可执行能力。内容不少，但我尽量只保留真正有助于你在项目里把 Skill 用起来的部分。

NotebookLM Mind Map.png

先说结论

如果你只记住这几条，这篇文章就已经值回时间：

对所有任务都生效的规则，写进 CLAUDE.md；只对某类重复任务生效的，做成 Skill；只对这一次有效的，写进 Prompt
只有“输入相对稳定、输出有模式、而且容易漏步骤”的任务，才值得沉淀为 Skill
通用 Skill 模板只能当原材料，项目级 Skill 必须自己裁剪、自己维护
description 不是装饰字段，它承担了触发场景的职责，最好把 Use when... 直接写进去，关键词前置、长度克制
Claude 启动时主要只看 frontmatter，Skill 正文在真正触发时才按需载入
allowed-tools 是权限边界，不是行为建议；paths 是条件激活，不是说明文字
第一个 Skill 不要挑最关键的任务，先拿中等风险任务练手

一、公开 Skill 模板为什么一开始很香，后来却越用越别扭

我现在反而会对“看起来很全”的公开 Skill 模板保持一点警惕。

不是因为它们没用，而是因为它们太容易制造一种错觉：好像什么都覆盖到了，但真正最重要的东西其实没进去。

公开模板最常见的问题，不是方向错，而是下面这三种。

1. 太宽泛

它什么都管一点，但什么都不够深。

它会告诉你“注意异常处理”“注意性能”“注意安全”，这些当然没错。但这些话本身不构成你项目里的工作流。它不知道你们统一用的是 AppError，不知道你们数据库变更必须检查回滚，也不知道你们哪几个目录历史包袱最重。

2. 太嘈杂

50 行模板里，真正有价值的可能只有 5 行。

剩下的 45 行不是完全没用，而是在和那 5 行争夺 Claude 的注意力。对于 agent 来说，规则不是越多越强。很多时候，8 行写透项目约束的 Skill，比 50 行“样样都提一点”的模板更有用。

3. 太不像你的项目

这点最致命。

公开模板知道“大家普遍应该注意什么”，但不知道“你们团队反复死在哪些地方”。而真正有价值的 Skill，恰恰应该把那些项目特有、团队高频踩坑的东西固化下来。

说得更直白一点：你把一个新同事扔进团队，给他一份行业通用培训材料，当然比什么都不给强；但如果你不告诉他“我们团队最容易出错的是哪三件事”，他依然干不好你最在意的活。

所以正确姿势不是“找一个最全的模板直接用”，而是：

先借鉴，再裁剪，最后只留下真正属于你项目的那几条。

公开模板到项目 Skill 的提炼路径

二、先把 Prompt、CLAUDE.md、Skill 这三件事彻底分清楚

很多人不是不会写 Skill，而是一开始就把这三件事混在一起了。

判断方法其实很简单，只问一个问题：

这个要求的作用范围到底有多大？

这个要求对所有任务都成立吗？如果是，放 CLAUDE.md
这个要求只对某一类任务成立吗？如果是，做成 Skill
这个要求只对这一次成立吗？如果是，写进 Prompt

举几个特别典型的例子：

“所有 throw 必须是 AppError”
这是全局规则。不管你是在写新功能、修 bug，还是做重构，都要遵守。它应该进 CLAUDE.md。

“代码审查时按固定顺序检查数据库、异步和错误处理”
这只在 code review 这种任务里才触发，它不是全局规则，而是任务模板，所以应该做成 Skill。

“这次先只分析原因，不要动代码”
这只对当前这次任务有效，应该写进 Prompt。

最容易搞混的是 CLAUDE.md 和 Skill。它们都能约束 Claude 的行为，但本质完全不同：

CLAUDE.md 是永远生效的规则
Skill 是遇到对应任务才触发的模板

如果要打个比方：

CLAUDE.md 是交通规则
Skill 是导航路线
Prompt 是你这次上车前临时交代的一句话

这三层一旦分清楚，后面 80% 的混乱都会自动消失。

Prompt、CLAUDE.md、Skill 的边界图

一个常见误判：很多问题根本不需要写 Skill

我后来发现，很多人想写 Skill，并不是因为真的存在一个稳定、重复、值得沉淀的任务，而是因为这一次和 Claude 协作得不顺。

比如目标没说清，边界没收紧，上下文没给够，或者你真正缺的是一条全局规则，却误以为自己需要一份任务模板。这个时候你如果急着把它沉淀成 Skill，本质上只是把一次性的混乱模板化。

几个很常见的误判场景是：

这次需求本身还在摇摆，连你自己都没想清楚要什么
这个问题只发生过一次，下次未必还会以同样的形状出现
你真正缺的是全局约定，比如错误处理、目录规范、命名规则
你只是想表达“这次先别改代码”“这次先只分析原因”这种一次性约束

写 Skill 之前，先问自己一句话：

这个问题下次还会以差不多的形状再来一次吗？如果不会，先别急着写 Skill。

三、什么时候一个任务真的值得被沉淀成 Skill

不是所有重复任务都值得沉淀。

我现在给自己的标准其实很克制，就一句话：

同一类任务做了三次以上，而且每次都要重新给 Claude 解释背景。

反过来说，如果某个任务每次背景和目的都完全不同，就不值得沉淀。比如“写文档”这个动作本身很常见，但公司文档、API 文档、用户手册的写法完全不同，它们应该是三个不同的 Skill，而不是一个叫“写文档”的通用模板。

在真正开始写之前，我会先做三个检查。

1. 输入是否稳定

“根据 Figma 设计稿生成 React 组件”这种任务，输入格式相对稳定，比较适合沉淀。

“根据 SQL 查询结果生成图表”这种任务，每次数据格式和图表类型都可能差很多，Skill 会很难写得稳。

2. 输出是否有共同模式

“写 Pull Request 描述”很适合，因为它天然就有固定框架：改了什么、为什么改、怎么测试。

但“和 AI 讨论技术方案”这种任务，每次深度、重点、结论都不同，就不太适合硬沉淀成一个模板。

3. 有没有容易漏掉的关键步骤

最值得沉淀成 Skill 的任务，通常不是“最复杂”的任务，而是那些不特别提醒就容易漏一步的任务。

Skill 最有价值的地方，不是让 Claude 变得更聪明，而是把你每次最容易忘的检查项，固化成默认动作。

所以一个任务如果同时满足下面三点：

输入相对稳定
输出有共同模式
总有一两步容易漏

它就很值得沉淀成 Skill。

什么任务值得沉淀成 Skill

四、从一个真实痛点开始，走完 Skill 的提炼过程

光讲判断标准还是有点抽象，不如走一遍完整例子。

代码审查，几乎每个后端工程师每周都在做，也是最容易进入“重复解释”困境的任务。用它来走一遍完整的 Skill 提炼过程会很清楚。

你反复踩的坑

假设你们团队每周都做代码审查，而且总在重复盯这几件事：

有人改一个功能，顺手动了三个不相关模块
新同学不知道项目里统一用 AppError，直接 throw new Error()
Promise 链里漏了 await
数据库查询没有索引，或者潜在 N+1 没被看出来

这就是非常典型的“该沉淀 Skill 的信号”。

先设计内容，再去想格式

一个好 Skill，先别急着写文件。先把内容层想清楚，只要回答四个问题：

1. 什么时候用

不是写“代码审查”四个字，而是写清楚触发场景。

❌ 代码审查
✅ 当我提交 PR 前，检查我的 TypeScript 后端代码是否符合项目约定

差别在于：模糊的描述会让 Claude 在不该用的时候乱触发，而具体的场景描述更容易精准命中。

2. 按什么顺序做

步骤尽量不要超过五步。

你从公开模板里借灵感，但通用模板有 50 行，而你真正关心的可能只有四件事：改动范围、错误处理、异步操作、数据库查询。

1. 读完整个改动的 diff，确认改动是否只涉及这个 PR 的范围
2. 检查错误处理：所有 throw 都必须是 throw new AppError()
3. 检查异步操作：Promise 链是否有遗漏的 await
4. 检查数据库查询：是否有 N+1 问题，关键查询是否 explain 过

3. 输出长什么样

不要写“请清晰输出”。这种话几乎没有约束力。直接给格式。

🔴 Critical: ...
🟡 Warning: ...
✅ Suggestion: ...
Summary: X critical issues to fix before merge.

4. 什么时候不适用

写清楚边界比写清楚功能更重要。

比如：

不审查 UI 层代码
不关注代码风格
改动超过 500 行先拆 PR

这些“我不做什么”的声明，往往比“我会做什么”更能防止 Claude 越界。

到这里，你脑子里其实已经有一个能用的 Skill 了。下一步只是把它放进 Claude Code 认识的格式里。

五、真正落到 `SKILL.md` 文件层，哪些字段值得你认真写

一个完整的 SKILL.md，通常会长这样：

---
name: code-review
description: Review TypeScript backend code before merging. Use when asked to review code, check a PR, or verify implementation before committing.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff *)
argument-hint: "[PR 分支名或文件路径]"
arguments:
  - target
---

# Code Review

## 步骤
1. 读取 ${target} 的改动 diff
2. 检查错误处理：所有 throw 必须是 throw new AppError()
3. 检查异步操作：Promise 链是否有遗漏的 await
4. 检查数据库查询：是否有 N+1 问题

## 输出格式
🔴 Critical: ...
🟡 Warning: ...
✅ 通过: ...

这里最值得你认真写的，其实是下面几个字段。

name
名字别太抽象。要让人一眼知道它是做什么的。像 helper、utils、tools 这种名字几乎没有路由价值，远不如 code-review、pr-summary、api-conventions 这种具体命名。

description
这是现在最关键的字段。它不只是“简介”，还承担了“触发场景”的职责。你最好直接把 Use when... 写进去，而不是写一句空话。更重要的是，别把它写成长段说明文。关键词尽量前置，长度最好控制在 250 字符左右，太长往往只会稀释命中信号。官方还特别提醒，description 最好用第三人称去写，像 “Analyzes pull requests...” 这种句式，比 “I can help...” 或 “You can use this...” 更稳。

allowed-tools
它决定这个 Skill 具备哪些能力。这个字段后面我会在源码部分展开讲，因为它比很多人想象的更“硬”。

arguments
让 Skill 接受参数，比如目标文件、目录、分支名。${target} 会在正文里被替换成你传进去的实际值；如果你喜欢按位置拿参数，也可以用 $0、$1 这类方式。

还有几个很好用，但不是每次都要上的字段。

argument-hint
告诉调用者这个 Skill 期待什么参数。

model: haiku
简单任务可以指定更轻量的模型，直接省成本。像格式化、重命名、简单改写这类工作，很多时候没必要上更重的模型。

paths
让 Skill 只在某些路径下激活。适合模块边界明确的项目。

context: fork
高风险操作放进独立上下文，避免污染主会话。

disable-model-invocation: true
禁止 Claude 自动触发，只允许你手动 /skill-name 调用。部署、发版、发邮件这类有副作用的 Skill，应该优先考虑加上。

大多数 Skill 根本不需要把字段填满。真正实用的思路不是“功能全”，而是“正好够用”。

如果一个 Skill 只是做常规代码审查，name、description、allowed-tools、arguments 往往就够了。只有当你真的遇到参数化、模块隔离、上下文隔离这些需求时，再往上加。

SKILL.md 不是整个 Skill，它只是入口

很多人以为一个 Skill 就是一份 SKILL.md。其实不是。

更实用的做法通常是：把 SKILL.md 控制在足够短、足够清楚的范围里，让它承担“入口”和“调度”职责；真正长的规范、示例、脚本都拆出去。

一个 Skill 目录完全可以长这样：

my-skill/
├── SKILL.md
├── reference.md
├── examples/
│   └── sample.md
└── scripts/
    └── helper.py

这里的关键点不是“可以放很多文件”，而是：这些文件不会自动加载，必须在 SKILL.md 里显式引用。

比如：

## 参考资料
- 完整的 API 规范见 [reference.md](reference.md)，需要查接口细节时读它
- 期望的输出格式见 [examples/sample.md](examples/sample.md)

这个设计和前面说的懒加载是同一套思路：不是 Skill 触发时把所有材料都灌进上下文，而是只在真正需要的时候再去读。

所以：

reference.md 适合放项目特有知识，比如内部 API 规范、禁用库、架构约定
examples/ 适合放期望输出样例，帮助 Claude 对齐格式
scripts/ 适合放真正可执行的辅助脚本，让 Skill 不只是“描述怎么做”，还能“先把上下文准备好”

这点很重要，因为它决定了 Skill 的上限不是“几行 prompt”，而是“一个有入口、有知识、有执行能力的局部工作流”。

Skill 放在哪，决定它是谁的能力

这点很容易被忽略，但工程上很重要。

同样是一个 Skill，放在不同位置，意义完全不一样：

~/.claude/skills：你个人所有项目都能用，适合个人长期习惯
.claude/skills：只在当前项目生效，适合团队项目约定
<plugin>/skills：跟着插件走，适合做模块化分发

如果不同层级里恰好有同名 Skill，优先级也不是平均的。官方规则更接近：企业级配置优先于个人级，个人级优先于项目级；插件 Skill 因为带命名空间，通常不会和前面这些直接撞名。

官方文档里甚至把这件事讲得很直接：Skill 存放的位置，本身就是它的作用域设计。

这背后的工程含义非常大。

如果你把一个强项目耦合的 Skill 放进个人目录，它就会带着这个项目的假设跑到别的仓库里；反过来，如果你把一个本该跨项目复用的通用 Skill 只塞在项目目录里，它的复用价值又被锁死了。

在 monorepo 里，这件事更有意思。Claude Code 会自动发现子目录下的 .claude/skills/。也就是说，你完全可以让 packages/frontend/.claude/skills/ 只服务前端包，让 packages/backend/.claude/skills/ 只服务后端包，而不是把所有知识都堆在仓库根目录。

这时 Skill 就不只是“提示词文件”，而是团队知识的分发机制：

个人层的 Skill，固化的是你的工作习惯
项目层的 Skill，固化的是团队约定
包级 Skill，固化的是模块边界里的局部知识

如果你能把这层想清楚，很多“这个规则到底该放哪”的问题，答案会比只看内容本身更清楚。

六、如果只停在经验层，这篇还差半口气：我后来去翻了源码

前面这些判断，靠经验其实也能总结出来。

但我后来还是不太满足。因为有几个问题如果不看实现，心里总会悬着：

description 到底是不是自动触发的关键？
allowed-tools 到底只是提示，还是硬限制？
paths 到底是真过滤，还是只是写给人看的说明？

我后来去翻了一遍源码，结论是：这些字段比我一开始以为的更“硬”。

1. 为什么触发逻辑主要看 frontmatter，而不是正文

loadSkillsDir.ts 里有一个函数 estimateSkillFrontmatterTokens，注释写得非常直接：

/**
 * Estimates token count for a skill based on frontmatter only
 * (name, description, whenToUse) since full content is only loaded on invocation.
 */
export function estimateSkillFrontmatterTokens(skill: Command): number {
  const frontmatterText = [skill.name, skill.description, skill.whenToUse]
    .filter(Boolean)
    .join(' ')
  return roughTokenCountEstimation(frontmatterText)
}

这段代码背后的意思非常重要。

Claude Code 启动时，主要只把每个 Skill 的 frontmatter 信息算进上下文。Skill 正文不是一开始就全量塞进去，而是在你真正触发它的时候才加载。

这直接解释了两件事。

第一，Claude 不是先把你整篇 Skill 读完再判断要不要触发，它先看的就是前面这几行。换句话说，触发效果主要取决于 frontmatter，不取决于正文写得多漂亮。

第二，Skill 多不等于上下文立刻爆炸，因为启动时压进去的不是全文，而是 frontmatter。

源码里保留了 whenToUse 这个概念，但从现在的文档实践看，推荐做法已经更偏向把触发描述直接写进 description。所以对大多数人来说，最稳的策略不是纠结“要不要额外写一个触发字段”，而是把 description 写得具体、可命中、带触发场景。

比如：

description: Review TypeScript backend code before merging. Use when asked to review code, check a PR, or verify implementation before committing.

比“代码审查 Skill”这种描述强太多了。

源码注释里其实还暗含了一个很实用的提醒：触发描述不是越长越稳。冗长的 whenToUse 或 description 不会线性提高命中率，很多时候只是在白白消耗首轮缓存和注意力。所以对这个字段最好的优化，不是“多写一点”，而是“把真正会命中的词放到前面”。

2. 为什么 `allowed-tools` 不是建议，而是权限边界

这一点是我看源码之后感受最强的一处。

Skill 执行时，getPromptForCommand 会在返回内容之前把 allowedTools 写进工具权限上下文：

getAppState() {
  const appState = toolUseContext.getAppState()
  return {
    ...appState,
    toolPermissionContext: {
      ...appState.toolPermissionContext,
      alwaysAllowRules: {
        ...appState.toolPermissionContext.alwaysAllowRules,
        command: allowedTools,
      },
    },
  }
}

这说明 allowed-tools 不是“提醒 Claude 尽量这样做”，而是权限层的强制限制。

比如一个 code review Skill 只开放 Read、Grep、Glob 和 Bash(git diff *)，那它就不是“理论上不该写文件”，而是从架构上根本没有写文件的能力。Bash(git diff *) 这种写法也不是装饰，它真的只允许 git diff 开头的命令，其他 Bash 调用会被挡住。

这让我对 allowed-tools 的理解完全变了。它不是“不信任模型”，而是最小权限设计。就像你给数据库只读账号只开 SELECT 权限，不是因为你怀疑这账号会作恶，而是因为这个任务本来就不该拥有写权限。

3. 为什么 `paths` 不是说明文字，而是条件激活机制

源码里，带 paths 的 Skill 在加载时会被单独分流到一个 conditionalSkills Map：

// Separate conditional skills (with paths frontmatter) from unconditional ones
for (const skill of deduplicatedSkills) {
  if (skill.type === 'prompt' && skill.paths && skill.paths.length > 0
      && !activatedConditionalSkillNames.has(skill.name)) {
    newConditionalSkills.push(skill)
  } else {
    unconditionalSkills.push(skill)
  }
}

// Store conditional skills for later activation when matching files are touched
for (const skill of newConditionalSkills) {
  conditionalSkills.set(skill.name, skill)
}

// 最后只返回无条件的 Skill
return unconditionalSkills

这段逻辑的含义是：带 paths 的 Skill，根本不会像普通 Skill 一样直接进入启动时上下文。它会先待在一个“条件激活区”里，只有当你在会话里碰到了匹配路径的文件，它才会被真正激活。

这点对复杂项目非常有价值。

比如你给支付模块写一个 paths: src/payment/** 的 Skill，在你处理用户系统、文章系统、管理后台时，这个 Skill 对 Claude 几乎是隐身的。只有当你真的进入 src/payment/ 相关文件，它才“出现”。

这也是我现在很认同的一种团队实践：不要在根目录堆一个什么都想管的大 Skill 集合，而是让复杂模块在自己的目录附近维护自己的 Skill。

4. 为什么大型项目不该只在根目录维护一套总 Skill

还有一个很容易被忽略，但工程上非常实用的机制：Claude Code 会从当前文件所在目录一路向上寻找 .claude/skills。

源码大概是这样：

// Walk up to cwd but NOT including cwd itself
while (currentDir.startsWith(resolvedCwd + pathSep)) {
  const skillDir = join(currentDir, '.claude', 'skills')
  // ...check if exists, then load
  currentDir = dirname(currentDir)
}

// Sort by path depth (deepest first) so skills closer to the file take precedence
return newDirs.sort((a, b) => b.split(pathSep).length - a.split(pathSep).length)

这里最关键的是最后一行：deepest first。也就是说，越靠近当前文件的 Skill，优先级越高。

这意味着你放在 src/auth/.claude/skills/ 里的 Skill，可以自然覆盖根目录下更通用的同名 Skill。对 monorepo 或大仓库来说，这个机制非常好用：

packages/api/.claude/skills/ 可以放 API 专属 Skill
packages/web/.claude/skills/ 可以放前端专属 Skill
根目录只保留真正的全局规则

如果把上面四点放在一起看，设计 Skill 的顺序其实会变得很清楚：

先把 frontmatter 写准，再去打磨正文步骤
先按最小权限收紧 allowed-tools，再考虑要不要给更多能力
只有模块边界明确时再上 paths，不要为了“高级”硬加
多目录项目优先做“离代码更近”的局部 Skill，而不是维护一个大而全的总模板

5. 为什么长对话里，Skill 不会轻易“失忆”

还有一个很多人会担心的问题：会话一长、上下文一压缩，前面调过的 Skill 会不会就悄悄失效了？

从实现思路看，Claude Code 不是简单把它们扔掉，而是会把最近调用过的 Skill 重新注入压缩后的上下文。工程上你可以把它理解成：Skill 不是“一次触发完就全靠模型自己记住”，而是一个可以被系统再次带回来的工作单元。

当然，这也不是说你可以无限制地把 Skill 写成超长文档。实现上会有保留预算，比如最近调用的 Skill 只会保留前一段核心内容，而不是把所有正文永久塞在上下文里。所以前面那条原则依然成立：把 frontmatter 写准，把正文写短，把真正长的材料拆到 reference 或脚本里。

Skill 运行机制与条件激活

七、不是所有 Skill 都应该让 Claude 自动触发

到这里，其实已经够你写出一个基础可用的 Skill 了。

但如果你真的准备在项目里长期用，接下来有一个问题迟早会遇到：

这个 Skill 到底应该让 Claude 自动触发，还是只能我手动触发？

这背后其实对应两种完全不同的 Skill。

1. 参考型 Skill：给 Claude 补充背景知识

这类 Skill 的作用不是“执行一个任务”，而是“把某个项目知识注入到当前工作里”。

比如 API 设计规范、错误处理约定、数据库命名规则。这些东西你希望 Claude 在写代码、改代码、review 代码时，只要场景合适就自动想起来。

这类 Skill 的特点是：

倾向自动触发
内容会留在主对话上下文里
更像“局部规范”而不是“独立任务”

比如：

---
name: api-conventions
description: API design patterns and conventions for this codebase. Use when writing or reviewing API endpoints.
---

响应格式统一用 { success, data, timestamp }
禁止在 controller 层直接写 SQL，通过 service 层操作
所有异步函数必须有 try-catch，错误统一 throw new AppError()

2. 任务型 Skill：给 Claude 一个要完成的动作

这类 Skill 有明确边界，通常还可能带副作用。

比如 /deploy、/send-release-email、/prepare-release-notes、/migrate-db。这类 Skill 更像一段可执行流程，而不是知识注入。

这类 Skill 的特点是：

通常应该手动触发
有副作用时最好加 disable-model-invocation: true
有风险时再配 context: fork

比如：

---
name: deploy
description: Deploy the application to production. Manual trigger only.
context: fork
disable-model-invocation: true
allowed-tools:
  - Bash(npm run test)
  - Bash(npm run build)
  - Bash(git push *)
---

1. 跑完整测试：npm run test
2. 确认测试全绿后构建：npm run build
3. 推送到部署分支
4. 等待 CI 完成并检查健康状态

这里的关键不是字段多了，而是触发权变了。

你真正要想清楚的问题是：

这件事我愿不愿意让 Claude 自己判断“现在该触发了”？

如果答案是“不愿意”，那就不要让它自动触发。

3. `disable-model-invocation: true` 和 `user-invocable: false` 不是一回事

这是一个很容易混淆，但又非常关键的区别。

默认情况下，你和 Claude 都可以调用一个 Skill。你可以手动 /skill-name，Claude 也可以在觉得合适时自动加载它。

但很多人会把下面两个字段混为一谈：

disable-model-invocation: true
user-invocable: false

它们看起来都像“限制调用”，其实限制的是两件完全不同的事。

disable-model-invocation: true 的意思是：Claude 不能自己触发，只有你能手动触发。 这类 Skill 适合部署、发版、发邮件、推送消息这类你必须自己掌握时机的动作。更重要的是，它还会把这个 Skill 的描述从 Claude 的常驻上下文里拿掉，平时的上下文成本直接归零，只有你手动调用时才完整加载。

user-invocable: false 的意思则是：你不能从 / 菜单里把它当命令来点，但 Claude 仍然可以在合适时自动用它。 这类 Skill 更适合背景知识，比如老系统架构、内部缩写、遗留约定。这些东西你希望 Claude 在相关任务里自动想起来，但你并不需要一个显眼的 /legacy-context 命令天天挂在菜单里。

所以更准确的判断应该是：

有副作用、要你亲自控制时机：disable-model-invocation: true
只是背景知识、不适合被人手动当命令点：user-invocable: false
想限制 Claude 到底能不能调用某些 Skill：去配权限规则，而不是只盯菜单显示

这组区别值得写进脑子里，因为它直接决定了 Skill 的“触发权”到底属于谁。

参考型 Skill 与任务型 Skill

八、Skill 的天花板：从静态模板到可执行能力

前面几节讲的，主要还是“怎么把经验写成一个好模板”。但如果 Skill 只能放静态文字，它的上限其实并不高。

真实项目里，很多任务依赖的是实时信息：当前 PR 的 diff、评论区讨论、今天的测试结果、最新 schema、CI 状态。你当然可以在 Skill 里写“先去看这些东西”，但这样一来，最关键的一步又变回 Claude 自己先兜一圈去找。

Claude Code 里真正更有意思的地方是：Skill 不只是 prompt 模板，它还可以在触发瞬间先准备上下文。

1. 动态注入：先拿真实数据，再交给 Claude

比如你要做一个 PR 总结 Skill，不一定要让 Claude 先自己去猜该看哪些信息，你可以直接让 Skill 触发时先把它们准备好：

---
name: pr-summary
description: Summarize the current pull request. Use when asked to review or summarize a PR.
context: fork
allowed-tools:
  - Bash(gh *)
---

## 当前 PR 信息
- diff：!`gh pr diff`
- 评论区讨论：!`gh pr view --comments`
- 涉及文件：!`gh pr diff --name-only`

## 你的任务
基于以上真实数据，总结这个 PR 做了什么、为什么改、有哪些潜在风险。

这个 Skill 真正触发时，前面的命令会先执行，输出直接注入到 prompt 里。Claude 拿到的不是“请你去看看 PR”这种模糊要求，而是已经准备好的真实上下文。

这也是为什么前面说 scripts/ 不是装饰。如果一个 Skill 需要先查状态、先取数、先做一轮预处理，那它就不再只是“告诉 Claude 怎么做”，而是在执行前把材料也一起备好了。更复杂一点时，你完全可以把逻辑放进 scripts/，再通过 CLAUDE_SKILL_DIR 去调用目录里的脚本，让 Skill 触发时先跑一轮取数或整理。

2. 这件事为什么重要：它决定了 Skill 的上限

一旦你理解了动态注入这层能力，就会发现 Skill 的上限根本不只是“几行 prompt”。

它可以同时承担三件事：

定义触发条件
限制工具权限
在执行前准备实时上下文

换句话说，Skill 不是只能做静态模板，它完全可以长成一个带入口、带约束、还能主动取数的局部能力单元。

不要只把 Skill 当成“写给模型的一段话”，而要把它当成“一个局部工作流的入口”。

3. 从架构位置看，Skill 不是 Tool，也不是 Agent

如果再往上抽一层，我现在对 Skill 的理解是：

Tool 是原子能力
Skill 是任务知识和操作规约
Agent 是执行与编排单元

这个分层不一定是官方唯一表述，但作为工程心智模型非常有用。因为一旦把 Skill 放到 Tool 和 Agent 中间去理解，很多判断都会顺下来：

该写成脚本的，别硬写进 Skill 正文
该放进 CLAUDE.md 的全局规则，别误沉淀成任务 Skill
该拆给 SubAgent 的复杂协作，别硬让一个 Skill 扛完

Skill 真正做的事，不是替代 Tool，也不是替代 Agent，而是把“什么场景下、按什么步骤、调用哪些能力”组织成可复用的任务单元。

九、真正让 Skill 变靠谱的，不是写出来，而是验证出来

这是我觉得官方 best practices 里最容易被忽略、但最能拉开水平差距的一点。

很多人写 Skill 的方式是：先凭感觉写一版，再上项目里试试。这样当然也能跑，但它很容易陷进一种错觉里: 你以为自己在“优化 Skill”，其实只是一直在补想象中的问题。

官方更推荐的思路其实更工程化：

先准备评测样例，再写 Skill。

最轻量、也最实用的做法，是先找出三个真实场景：

一个 Claude 原本就能做得不错的
一个 Claude 容易漏步骤的
一个 Claude 容易理解偏、触发错或者输出不稳的

先不用 Skill 跑一遍，记录基线。看它具体错在哪：

是没想到要用这个 Skill
是触发了，但没读对参考资料
是步骤顺序不稳
是输出格式飘了
是该脚本处理的确定性工作，被它自己“猜”过去了

然后再写最小版本的 Skill，只补刚才暴露出来的那几个缺口，而不是一上来把所有可能性都写满。

把这个过程压缩成一句话，其实就是：

先找失败样例
再写最小 Skill
再看它是不是真的修掉了失败样例

如果三轮下来都没有明显提升，那大概率不是 Skill 写得不够多，而是这个问题根本不该沉淀成 Skill。

不要只看结果，还要看 Claude 是怎么“导航”这个 Skill 的

只看最终结果对不对还不够，更重要的是看 Claude 在过程中到底是怎么用这个 Skill 的。

官方专门建议观察 Claude 实际怎么使用 Skill，而不是只看最终结果对不对。比如：

它是不是总在错误顺序里读文件
它是不是老是忽略某个引用文件
它是不是每次都反复读同一个 reference，那这部分也许该往 SKILL.md 主体里提
某个 examples 文件是不是从来没被读过，那它可能根本没价值，或者信号太弱

这些观察特别重要，因为它能直接反推出信息架构是不是合理。

我现在会把一个 Skill 是否成熟，简单看成四个问题：

会不会在该触发的时候触发
触发后会不会按预期去读材料
执行过程会不会漏掉关键步骤
输出结果能不能稳定复现

如果你团队里会混用不同模型，官方还建议至少跨你计划使用的模型测一遍。不是因为所有模型都得兼容，而是因为有些 Skill 对提示强度和结构依赖更高，换模型后会暴露出你原来没看到的问题。

说到底，Skill 的成熟度，不是靠“我觉得写得挺全”来判断，而是靠一组真实任务能不能稳定跑通来判断。

十、写 Skill 时，最常见的四种设计模式，以及最容易踩的反模式

这里先说清楚：下面这四种名字，不是官方文档逐字给出的固定术语，而是我结合 Anthropic 官方 best practices 做的工程化归纳。

但它们确实能覆盖大多数项目里真正会遇到的 Skill 设计问题。

1. 模板驱动模式：解决“输出不稳定”

这类 Skill 的核心不是让 Claude 更会想，而是让它更稳定地按结构输出。

适合：

周报
PR 描述
事故复盘
评审报告

它的关键不是“给一个模板”，而是把模板当成输出接口。模板负责格式，SKILL.md 负责路由和规则。模板里不要塞判断逻辑，也不要把一个模板写成一套小程序。

如果一个模板已经长到一百多行，而且开始出现大量条件分支，通常不是你模板写得认真，而是职责已经混了。

2. 脚本增强模式：解决“结果不稳定”

这类 Skill 的核心是：确定性的事交给脚本，不要交给模型猜。

适合：

指标统计
CSV 解析
正则匹配
Git / PR / CI 状态抓取
需要预处理的上下文准备

官方对这件事的说法很直白：solve, don't punt。能脚本算出来的，就别只写一句“请 Claude 自行分析”。

这类 Skill 真正提高的，不是文风，而是可靠性。你把概率型推理替换成确定性执行，整个 Skill 的下限会明显抬高。

3. 知识分层模式：解决“上下文过载”

这是官方反复强调的 progressive disclosure 思路。

也就是：SKILL.md 只做入口和导航，把大块知识拆进 reference/、examples/、forms/ 这类文件里，按需读取，而不是一次灌满。

这类模式适合：

领域知识很多的 Skill
不同子领域差异很大的 Skill
需要高级用法、边界情况、案例库的 Skill

它的关键不是“拆文件”，而是“拆得有层次”。官方明确不建议深层嵌套引用。最稳的做法是所有重要材料都从 SKILL.md 一层直达，别让 Claude 从 advanced.md 再跳 details.md 才看到真正关键信息。

4. 工具隔离模式：解决“能力边界失控”

这类模式最容易被低估。

很多人写 Skill 时只关注“让它能做事”，但真正稳定的 Skill 往往同样重视“让它不能乱做事”。

适合：

部署
发版
写数据库迁移
调外部系统
会改文件、发消息、推远端的任务

这一类 Skill 的核心组合通常是：

allowed-tools 收到最小
必要时配 context: fork
不希望自动触发时加 disable-model-invocation: true

它不是在限制 Claude 的创造力，而是在设计这个能力包的安全边界。

最常见的反模式

如果把前面四种模式反过来看，最常见的坑基本也就集中在下面这些地方：

一个 Skill 管太多事，什么都想覆盖，最后什么都不够准
description 写得很空，只写“处理文档”“帮助分析”这种谁都能套上的话
一上来给一堆方案，不给默认路径，让 Claude 自己从五六种做法里摇摆
模板里写判断逻辑，或者把本该脚本做的事丢给模型推理
reference 层级太深，真正关键信息藏在第二跳、第三跳文件里
把会过期的信息硬写进 Skill，比如时间敏感规则、旧接口切换说明
默认假设工具和依赖都已经装好，结果一跑就断
在路径里写 Windows 反斜杠，跨环境直接出问题

你会发现，所谓反模式，本质上就是一句话：

该约束的地方没约束，该拆开的地方没拆开，该交给脚本的地方还在让模型猜。

十一、完整案例：把一个通用 code review 模板，提炼成你项目真正需要的 Skill

上面说了这么多抽象原则，不如走一遍完整例子。

假设你们团队每周都做后端代码审查，而且总在重复盯这几件事：

有人改一个功能，顺手动了三个不相关模块
新同学不知道项目里统一用 AppError，直接 throw new Error()
Promise 链里漏了 await
数据库查询没有索引，或者潜在 N+1 没被看出来

这就是非常典型的“该沉淀 Skill 的信号”。

第一步：先确认痛点到底是什么

这一步别着急写模板，先把“你们到底在反复出什么问题”说清楚。

很多团队的问题不是“没有 code review”，而是每次 review 的注意力都被分散了。真正高频出错的点，永远是那几类项目特有的约束。

所以要沉淀的不是“代码审查”这四个字，而是你们团队在代码审查里最容易漏掉的那几类检查。

第二步：从公开模板里提取真正有用的部分

这时候公开模板就有用了，但它的用途不是直接上生产，而是当素材库。

假设你找到一个 50 行的通用 code review 模板。你真正该提取的，可能只有下面这几类东西：

逻辑正确性，尤其是异步操作
项目约定的遵守，比如 AppError、错误处理模式
数据库相关的风险，比如 N+1、索引、查询范围
改动范围是否聚焦，不要顺手改不相干文件

剩下那些跟你们项目关系不大的部分，就应该果断删掉。

第三步：把它压缩成一个真正能用的 Skill

最后落地出来的 Skill，应该更像这样：

---
name: code-review
description: Review TypeScript backend code before merging. Use when asked to review code, check a PR, or verify implementation before committing.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff *)
argument-hint: "[PR 分支名或文件路径]"
---

# Code Review Skill

## Steps
1. 读 $ARGUMENTS 的改动 diff，确认改动是否只涉及这个 PR 的范围（不要顺手改无关文件）
2. 检查错误处理：所有 throw 都必须是 throw new AppError()，不能 throw new Error()
3. 检查异步操作：Promise 链是否有遗漏的 await，错误是否被正确 catch
4. 检查数据库查询：是否有 SELECT * 的懒惰写法，是否明显的 N+1 查询，关键查询是否 explain 过

## Output Format
Issues found (Critical → Warning → Info):

🔴 **Line 45**: Missing `.select()` in Prisma query - this will fetch unnecessary columns
🟡 **Line 67**: Potential N+1: loop inside `posts.map()` should use `Promise.all()`
✅ **No AppError violations** — all errors properly handled

Summary: 1 critical issue to fix before merge.

## Caveats
- 不审查 UI 层代码（只关心后端逻辑）
- 不关注代码风格（那是 prettier 的事）
- 如果一个改动涉及多个不相干功能，分别提交 PR 再 review

你会发现，到这一步之后，Skill 就不再是“通用模板的中文版”了，而是你们项目真正有用的一个局部工作流。

50 行公开模板，最后可能只剩下 4 个真正属于你项目的核心关注点。但恰恰是这 4 个点，才决定它到底值不值得用。

第四步：在真实使用里继续迭代

Skill 从来不是一次写完的。

比如你用了两周之后，又发现一个常见问题：改了数据库 schema，但忘记更新 Prisma 类型。那就把它加进去：

4.5. 检查 Prisma 类型：如果改了数据库，Prisma schema 和生成的 types 是否都已更新

这时候你会发现，Skill 真正的价值不是“第一次写出来”，而是在真实工作里被持续打磨。

十二、Skill 的维护节奏，比第一次写出来更重要

Skill 不是写好就扔。

如果你写完之后三个月不看，它很快就会从“项目经验”重新退化成“历史遗留文档”。

我更推荐一个更贴近实际的轻量节奏：

前一两周
高频使用，快速迭代。每次用完就问自己三个问题：步骤是不是太复杂？输出是不是太啰嗦？有没有漏掉今天刚踩到的新坑？

稳定之后每周一次
回顾一次。看看最近有没有经常被遗漏的步骤，有没有新的痛点需要加入。对 Skill 这种高频小迭代的东西来说，按周看通常比按月看更合适。

每个月做一次清理
把已经不再是问题的注意事项删掉，把那些已经变成全局共识的规则移进 CLAUDE.md。这一步的重点不是加内容，而是防止 Skill 越写越胖。

Skill 应该越用越精炼，而不是越写越臃肿。

十三、一个特别反直觉，但很重要的经验：第一个 Skill，故意别写最重要的任务

这条我非常想单独拿出来讲。

因为很多人第一次沉淀 Skill，会本能地想挑一个最关键的任务，比如“生产环境发布前检查”“数据库迁移前审查”“支付流程改动 review”。

但工程上更稳的做法，其实正好相反。

大多数人写的第一个 Skill，质量都不会太高。触发条件偏模糊，步骤偏啰嗦，输出格式也不够稳定。这很正常，因为你第一次做这件事时，对“什么是好的 Skill”还没有直觉。

如果你一开始就把它用在最关键的任务上，一旦写得不够好，伤害会非常直接：要么关键场合出问题，要么你从此对这套机制失去信心。

更好的策略是：先拿一个重要程度中等、容错率比较高的任务练手。

比如：

写周报
生成 PR 描述
做一次常规 code review

先跑两周，迭代两三次，等你对 Skill 的节奏有感觉了，再去沉淀真正关键的流程。

第一个 Skill 的目的，不是直接解决最大的问题，而是让你学会怎么写 Skill。

十四、如果你今天就想开始，可以直接做这三个动作

别先想着搭一整套系统，直接从最小动作开始：

任务一： 列出你最近一个月里重复做过三次以上的任务。用第一节的判断法（对所有任务成立？→ CLAUDE.md；只对某类任务成立？→ Skill；只对这次成立？→ Prompt），确认你要处理的是 Skill 还是 CLAUDE.md 的事。

任务二： 为这个任务写一个 Skill。先想清楚四个问题（什么时候用、按什么顺序、输出长什么样、什么时候不适用），然后包装成 SKILL.md。目标是精炼——大多数好 Skill 的有效指令不超过 10 行。记住：第一次的目的是练手，不是写出完美的 Skill。

任务三： 选三个你最近真的遇到过的场景，先不用 Skill 跑一遍，再用 Skill 跑一遍，对比它到底有没有少漏步骤、少返工、少补充解释。然后在 SKILL.md 里补一行今天发现的问题（哪个步骤漏了，或者哪个注意事项需要加）。这就是 Skill 的维护节奏，也是最轻量的评测方法。

真正好的 Skill，几乎都不是第一次就写对的，而是在实际使用里慢慢长出来的。

下篇预告

第 06 篇：Sub-agents 实战——什么时候应该拆任务，怎么设计子任务边界

单个 Claude 实例有上下文上限，复杂任务拆成多个子任务让 Sub-agents 并行处理，理论上能大幅提速。但什么时候值得拆？拆错了会有什么代价？下一篇会拆开 Sub-agents 的真实适用场景，以及最常见的过度设计陷阱。

写在最后

公开 Skill 模板当然有用，但它的价值更像脚手架，而不是成品。

你不需要一个很复杂的 Skill 系统。你需要的，往往只是把团队最容易反复犯错的那几件事提前写下来，让 Claude 每次都替你盯住。

如果你现在想动手，就直接做这三步：列出最近一个月里重复做过三次以上的任务；用"三问法"确认它该放 CLAUDE.md、Skill 还是 Prompt；先写一个只有 5 到 10 行的版本，实际用一次，再立刻改第一轮。不要追求第一版完美——Skill 的价值，从来不是"写出来的那一刻"，而是"它开始帮你减少重复错误的那一天"。

评论区想聊一个问题：你现在最卡的，到底是"写不出规则"，还是"没分清哪些该放 CLAUDE.md、哪些该做成 Skill"？ 这两个问题看起来很像，但解法完全不同。

觉得这篇有帮助，点个赞让更多工程师看到 👍

AI Coding 系列持续更新。用别人的 Skill 模板是起点，不是终点。真正管用的 Skill，只有你自己的项目才能提炼出来。

掘金前端
连载04-最重要的Skill---一起吃透 Claude Code，告别 AI coding 迷茫ai_coder_小村儿
2026年4月10日 19:48

连载04-最重要的Skill---一起吃透 Claude Code，告别 AI coding 迷茫

掘金前端

作者 ai_coder_小村儿

2026年4月10日 19:48

别再直接 Fork 别人的 Claude Skill：公开模板只是原材料，项目规则才是成品

AI Coding 系列第 05 篇 · 核心工具

我第一次批量导入公开 Skill 模板的时候，是真的以为自己走了捷径。

GitHub 上一堆 star 很高的仓库，code review、需求分析、文档编写、调研、拆任务，看起来什么都有。我当时的想法特别简单：既然别人已经把常见工作流整理好了，我直接 fork 一份，全量导入，不就能让 Claude 立刻更稳、更懂项目吗？

结果用了几天，我反而越来越不放心。

它每次都输出得很像那么回事。格式完整，措辞专业，检查项也不少。可真正让我在项目里反复吃亏的那几件事，它一次都没替我盯住。异步链里是不是又漏了 await，这次 migration 有没有回滚方案，新同学是不是又顺手写了 throw new Error()，数据库 schema 改了之后 Prisma 类型是不是也一起更新了。

它会提醒一堆“大家普遍都应该注意”的东西，却不懂“我们团队到底最怕什么”。

后来我才慢慢明白，问题不是 Skill 机制不好，而是我导入的根本不是自己的 Skill，只是别人整理好的经验。

这些经验当然有用，但它们解决的是共性问题，不会天然长成你项目里的“肌肉记忆”。

这篇文章就讲一件事：

怎么把公开模板当原材料，而不是成品；怎么从自己的项目里，提炼出一个真正会被反复复用、而且越用越准的 Skill。

如果你只想先记住一句话，那就是：

公开 Skill 模板是素材库，不是最终产品。

先给你一个判断框架

为了后面不绕，我先把最核心的判断放前面：

对所有任务都生效的规则，放 CLAUDE.md
只对某一类任务生效的规则，做成 Skill
只对这一次任务有效的约束，写进 Prompt
只有“输入相对稳定、输出有共同模式、而且容易漏步骤”的任务，才值得沉淀成 Skill
第一个 Skill 不要选最关键的任务，先拿中等风险任务练手

如果你现在就卡在“这条到底该写哪”，后面大部分内容其实都可以用这五条往回推。

一、为什么很多公开 Skill 模板，一开始觉得香，后来却越用越别扭

我现在反而会对“看起来很全”的公开 Skill 模板保持一点警惕。

不是因为它们没用，而是因为它们太容易制造一种错觉：好像什么都覆盖到了，但真正最重要的东西其实没进去。

公开模板最常见的问题，不是方向错，而是下面这三种。

1. 太宽泛

它什么都管一点，但什么都不够深。

2. 太嘈杂

50 行模板里，真正有价值的可能只有 5 行。

3. 太不像你的项目

这点才是最致命的。

所以正确姿势不是“找一个最全的模板直接用”，而是：

先借鉴，再裁剪，最后只留下真正属于你项目的那几条。

二、先把 Prompt、CLAUDE.md、Skill 这三件事分清楚

很多人不是不会写 Skill，而是一开始就把这三件事混在一起了。

判断方法其实很简单，只问一个问题的三个变体：

这个要求对所有任务都成立吗？如果是，放 CLAUDE.md
这个要求只对某一类任务成立吗？如果是，做成 Skill
这个要求只对这一次成立吗？如果是，写进 Prompt

举几个特别典型的例子：

“所有 throw 必须是 AppError”
这是全局规则。不管你是在写新功能、修 bug，还是做重构，都要遵守。它应该进 CLAUDE.md。

“代码审查时按固定顺序检查数据库、异步和错误处理”
这只在 code review 这种任务里才触发，它不是全局规则，而是任务模板，所以应该做成 Skill。

“这次先只分析原因，不要动代码”
这只对当前这次任务有效，应该写进 Prompt。

最容易搞混的是 CLAUDE.md 和 Skill。它们都能约束 Claude 的行为，但本质完全不同：

CLAUDE.md 是永远生效的规则
Skill 是遇到对应任务才触发的模板

如果要打个比方：

CLAUDE.md 是交通规则
Skill 是导航路线
Prompt 是你这次上车前临时交代的一句话

这三层一旦分清楚，后面很多混乱都会自动消失。

三、什么时候一个任务值得被沉淀成 Skill

不是所有重复任务都值得沉淀。

我现在给自己的标准其实很克制，就一句话：

同一类任务做了三次以上，而且每次都要重新给 Claude 解释背景。

在真正开始写之前，我会先做三个检查。

1. 输入是否稳定

“根据 Figma 设计稿生成 React 组件”这种任务，输入格式相对稳定，比较适合沉淀。

“根据 SQL 查询结果生成图表”这种任务，每次数据格式和图表类型都可能差很多，Skill 会很难写得稳。

2. 输出是否有共同模式

“写 Pull Request 描述”很适合，因为它天然就有固定框架：改了什么、为什么改、怎么测试。

但“和 AI 讨论技术方案”这种任务，每次深度、重点、结论都不同，就不太适合硬沉淀成一个模板。

3. 有没有容易漏掉的关键步骤

最值得沉淀成 Skill 的任务，通常不是“最复杂”的任务，而是那些不特别提醒就容易漏一步的任务。

Skill 最有价值的地方，不是让 Claude 变得更聪明，而是把你每次最容易忘的检查项，固化成默认动作。

所以一个任务如果同时满足下面三点：

输入相对稳定
输出有共同模式
总有一两步容易漏

它就很值得沉淀成 Skill。

四、一个真正好用的 Skill，内容层通常只需要四个部分

很多人一开始会把 Skill 写得很重，像在写规范文档。但实际用起来之后你会发现，真正好用的 Skill 通常很短。

它一般只需要四个部分。

1. 触发条件

什么时候用，一句话说清楚。

❌ 代码审查
✅ 当我提交 PR 前，检查我的实现是否符合项目约定

2. 执行步骤

按什么顺序做，列出来。尽量不要超过五步。

1. 读完整个改动的 diff
2. 检查是否用了禁用的库或模式
3. 检查异步操作的错误处理
4. 检查是否有 SQL 注入的风险
5. 给出修改建议

3. 输出格式

不要写“请清晰输出”。这种话几乎没有约束力。直接给模板。

❌ 用清晰的格式列出所有问题

✅ 给个模板：
Found 3 issues:
🔴 Critical: ...
🟡 Warning: ...
✅ Suggestion: ...

4. 注意事项

说清楚边界。什么情况不适用，有哪些常见陷阱。

- 不适用于新增功能的初始实现，只适用于 PR 前的最终检查
- 不关注 UI 层细节
- 改动超过 500 行，先拆成多个 Skill 请求

Skill 不是规范手册，更不是把所有经验一次性塞进去。它本质上是一个高频任务的最小可执行模板。

五、真正落到 `SKILL.md` 文件层，哪些字段最值得你花心思

讲完“内容怎么提炼”，还得讲“文件怎么写”。

很多人第一次写 SKILL.md 会卡在另一个地方：字段太多，不知道哪些真有用，哪些只是“看起来高级”。

一个完整的 SKILL.md，通常会长这样：

---
name: code-review
description: 提交 PR 前的代码审查
when_to_use: 当用户要求 review 代码或提交 PR 前检查时
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff *)
argument-hint: "[PR 分支名或文件路径]"
arguments:
  - target
---

# Code Review

## 步骤
1. 读取 ${target} 的改动 diff
2. 检查错误处理：所有 throw 必须是 throw new AppError()
3. 检查异步操作：Promise 链是否有遗漏的 await
4. 检查数据库查询：是否有 N+1 问题

## 输出格式
🔴 Critical: ...
🟡 Warning: ...
✅ 通过: ...

这里最值得你认真写的，其实是下面几个字段。

name
名字别太抽象。要让人一眼知道它是做什么的。

description
一句话说清这个 Skill 的用途，不要写成空泛口号。

when_to_use
这是最容易被低估的字段之一。它不是装饰，它直接影响 Claude 在什么场景下会想到这个 Skill。

allowed-tools
它决定这个 Skill 具备哪些能力。这个字段后面我会在源码部分展开讲，因为它比很多人想象的更“硬”。

arguments
让 Skill 接受参数，比如目标文件、目录、分支名。${target} 会在正文里被替换成你传进去的实际值。

还有几个很好用，但不是每次都要上的字段。

argument-hint
告诉调用者这个 Skill 期待什么参数。

model: haiku
简单任务可以指定更轻量的模型，直接省成本。像格式化、重命名、简单改写这类工作，很多时候没必要上更重的模型。

paths
让 Skill 只在某些路径下激活。适合模块边界明确的项目。

context: fork
高风险操作放进独立上下文，避免污染主会话。

大多数 Skill 根本不需要把字段填满。真正实用的思路不是“功能全”，而是“正好够用”。

如果一个 Skill 只是做常规代码审查，前四五个字段通常就够了。只有当你真的遇到参数化、模块隔离、上下文隔离这些需求时，再往上加。

六、如果只停在经验层，这篇其实还差半口气：我后来去翻了源码

前面这些判断，靠经验其实也能总结出来。

但我后来还是不太满足。因为有几个问题如果不看实现，心里总会悬着：

when_to_use 到底是不是自动触发的关键？
allowed-tools 到底只是提示，还是硬限制？
paths 到底是真过滤，还是只是写给人看的说明？

我后来去翻了一遍源码，结论是：这些字段比我一开始以为的更“硬”。

1. Claude 只在启动时读 frontmatter，Skill 正文是懒加载的

loadSkillsDir.ts 里有一个函数 estimateSkillFrontmatterTokens，注释写得非常直接：

/**
 * Estimates token count for a skill based on frontmatter only
 * (name, description, whenToUse) since full content is only loaded on invocation.
 */
export function estimateSkillFrontmatterTokens(skill: Command): number {
  const frontmatterText = [skill.name, skill.description, skill.whenToUse]
    .filter(Boolean)
    .join(' ')
  return roughTokenCountEstimation(frontmatterText)
}

这段代码背后的意思非常重要。

Claude Code 启动时，主要只把每个 Skill 的 name、description、when_to_use 这些 frontmatter 信息算进上下文。Skill 正文不是一开始就全量塞进去，而是在你真正触发它的时候才加载。

这直接解释了两件事。

第一，when_to_use 写得越具体，自动命中的效果就越稳定。Claude 不是先把你整篇 Skill 读完再判断要不要触发，它先看的就是前面这几行。

第二，你有十个 Skill 还是三个 Skill，对启动时上下文的占用差距没你想的那么大。真正的成本在触发时才发生。

所以 when_to_use 不能写成“代码相关任务时使用”这种空话。它要写成“当用户要求 review TypeScript 后端代码或提交 PR 前做最终检查时”这种具体到能命中的描述。

这也是为什么我现在越来越重视 frontmatter。以前我会把心思都放在正文步骤上，后来才发现，前面几行写虚了，后面写得再好都不一定有机会被用上。

2. `allowed-tools` 是系统层权限，不是给 Claude 的礼貌性建议

这一点是我看源码之后感受最强的一处。

Skill 执行时，getPromptForCommand 会在返回内容之前把 allowedTools 写进工具权限上下文：

getAppState() {
  const appState = toolUseContext.getAppState()
  return {
    ...appState,
    toolPermissionContext: {
      ...appState.toolPermissionContext,
      alwaysAllowRules: {
        ...appState.toolPermissionContext.alwaysAllowRules,
        command: allowedTools,
      },
    },
  }
}

这说明 allowed-tools 不是“提醒 Claude 尽量这样做”，而是权限层的强制限制。

3. `paths` 不是文档字段，它会把 Skill 放进条件激活区

这一点也比表面上看起来更硬。

源码里，带 paths 的 Skill 在加载时会被单独分流到一个 conditionalSkills Map：

// Separate conditional skills (with paths frontmatter) from unconditional ones
for (const skill of deduplicatedSkills) {
  if (skill.type === 'prompt' && skill.paths && skill.paths.length > 0
      && !activatedConditionalSkillNames.has(skill.name)) {
    newConditionalSkills.push(skill)
  } else {
    unconditionalSkills.push(skill)
  }
}

// Store conditional skills for later activation when matching files are touched
for (const skill of newConditionalSkills) {
  conditionalSkills.set(skill.name, skill)
}

// 最后只返回无条件的 Skill
return unconditionalSkills

这点对复杂项目非常有价值。

这也是我现在很认同的一种团队实践：不要在根目录堆一个什么都想管的大 Skill 集合，而是让复杂模块在自己的目录附近维护自己的 Skill。

4. Skill 发现是沿目录向上找的，而且离文件越近优先级越高

还有一个很容易被忽略，但工程上非常实用的机制：Claude Code 会从当前文件所在目录一路向上寻找 .claude/skills。

源码大概是这样：

// Walk up to cwd but NOT including cwd itself
while (currentDir.startsWith(resolvedCwd + pathSep)) {
  const skillDir = join(currentDir, '.claude', 'skills')
  // ...check if exists, then load
  currentDir = dirname(currentDir)
}

// Sort by path depth (deepest first) so skills closer to the file take precedence
return newDirs.sort((a, b) => b.split(pathSep).length - a.split(pathSep).length)

这里最关键的是最后一行：deepest first。也就是说，越靠近当前文件的 Skill，优先级越高。

这意味着你放在 src/auth/.claude/skills/ 里的 Skill，可以自然覆盖根目录下更通用的同名 Skill。对 monorepo 或大仓库来说，这个机制非常好用：

packages/api/.claude/skills/ 可以放 API 专属 Skill
packages/web/.claude/skills/ 可以放前端专属 Skill
根目录只保留真正的全局规则

如果把上面四点放在一起看，设计 Skill 的顺序其实会变得很清楚：

先把 frontmatter 写准，再去打磨正文步骤
先按最小权限收紧 allowed-tools，再考虑要不要给更多能力
只有模块边界明确时再上 paths，不要为了“高级”硬加
多目录项目优先做“离代码更近”的局部 Skill，而不是维护一个大而全的总模板

七、完整案例：把一个通用 code review 模板，提炼成你项目真正需要的 Skill

上面说了这么多抽象原则，不如走一遍完整例子。

假设你们团队每周都做后端代码审查，而且总在重复盯这几件事：

有人改一个功能，顺手动了三个不相关模块
新同学不知道项目里统一用 AppError，直接 throw new Error()
Promise 链里漏了 await
数据库查询没有索引，或者潜在 N+1 没被看出来

这就是非常典型的“该沉淀 Skill 的信号”。

第一步：先确认痛点到底是什么

这一步别着急写模板，先把“你们到底在反复出什么问题”说清楚。

很多团队的问题不是“没有 code review”，而是每次 review 的注意力都被分散了。真正高频出错的点，永远是那几类项目特有的约束。

所以要沉淀的不是“代码审查”这四个字，而是你们团队在代码审查里最容易漏掉的那几类检查。

第二步：从公开模板里提取真正有用的部分

这时候公开模板就有用了，但它的用途不是直接上生产，而是当素材库。

假设你找到一个 50 行的通用 code review 模板。你真正该提取的，可能只有下面这几类东西：

逻辑正确性，尤其是异步操作
项目约定的遵守，比如 AppError、错误处理模式
数据库相关的风险，比如 N+1、索引、查询范围
改动范围是否聚焦，不要顺手改不相干文件

剩下那些跟你们项目关系不大的部分，就应该果断删掉。

第三步：把它压缩成一个真正能用的 Skill

最后落地出来的 Skill，应该更像这样：

# Code Review Skill

## When to use
在提交 PR 前，请 Claude 做最后的 code review。只用于 TypeScript 后端代码。

## Steps
1. 读 diff，确认改动是否只涉及这个 PR 的范围（不要顺手改无关文件）
2. 检查错误处理：所有 throw 都必须是 throw new AppError()，不能 throw new Error()
3. 检查异步操作：Promise 链是否有遗漏的 await，错误是否被正确 catch
4. 检查数据库查询：是否有 SELECT * 的懒惰写法，是否明显的 N+1 查询，关键查询是否 explain 过

## Output Format
Issues found (Critical → Warning → Info):

🔴 **Line 45**: Missing `.select()` in Prisma query - this will fetch unnecessary columns
🟡 **Line 67**: Potential N+1: loop inside `posts.map()` should use `Promise.all()`
✅ **No AppError violations** — all errors properly handled

Summary: 1 critical issue to fix before merge.

## Caveats
- 不审查 UI 层代码（只关心后端逻辑）
- 不关注代码风格（那是 prettier 的事）
- 如果一个改动涉及多个不相关功能，分别提交 PR 再 review

你会发现，到这一步之后，Skill 就不再是“通用模板的中文版”了，而是你们项目真正有用的一个局部工作流。

50 行公开模板，最后可能只剩下 4 个真正属于你项目的核心关注点。但恰恰是这 4 个点，才决定它到底值不值得用。

第四步：在真实使用里继续迭代

Skill 从来不是一次写完的。

比如你用了两周之后，又发现一个常见问题：改了数据库 schema，但忘记更新 Prisma 类型。那就把它加进去：

4.5. 检查 Prisma 类型：如果改了数据库，Prisma schema 和生成的 types 是否都已更新

这时候你会发现，Skill 真正的价值不是“第一次写出来”，而是在真实工作里被持续打磨。

八、Skill 的维护节奏，比第一次写出来更重要

Skill 不是写好就扔。

如果你写完之后三个月不看，它很快就会从“项目经验”重新退化成“历史遗留文档”。

我更推荐一个很轻的维护节奏：

第一个月
高频使用，快速迭代。每次用完就问自己三个问题：步骤是不是太复杂？输出是不是太啰嗦？有没有漏掉今天刚踩到的新坑？

之后每个月
回顾一次。看看最近有没有经常被遗漏的步骤，有没有新的痛点需要加入。

每个季度
系统清理一次。把已经不再是问题的注意事项删掉，把那些已经变成全局共识的规则移进 CLAUDE.md。

Skill 应该越用越精炼，而不是越写越臃肿。

九、一个特别反直觉，但很重要的经验：第一个 Skill，故意别写最重要的任务

这条我非常想单独拿出来讲。

因为很多人第一次沉淀 Skill，会本能地想挑一个最关键的任务，比如“生产环境发布前检查”“数据库迁移前审查”“支付流程改动 review”。

但工程上更稳的做法，其实正好相反。

如果你一开始就把它用在最关键的任务上，一旦写得不够好，伤害会非常直接：要么关键场合出问题，要么你从此对这套机制失去信心。

更好的策略是：先拿一个重要程度中等、容错率比较高的任务练手。

比如：

写周报
生成 PR 描述
做一次常规 code review

先跑两周，迭代两三次，等你对 Skill 的节奏有感觉了，再去沉淀真正关键的流程。

第一个 Skill 的目的，不是直接解决最大的问题，而是让你学会怎么写 Skill。

十、如果你今天就想开始，可以直接做这三个动作

别先想着搭一整套系统，直接从最小动作开始：

任务一：列任务
列出你最近一个月里重复做过三次以上的任务。

任务二：做分类
用“三问判断法”确认它该放进 CLAUDE.md、Skill 还是 Prompt。

任务三：先写一个 5 到 10 行版本
先写触发条件、执行步骤、输出格式、注意事项。不要追求完美，先拿去用一次，再立刻改第一轮。

真正好的 Skill，几乎都不是第一次就写对的，而是在实际使用里慢慢长出来的。

下篇预告

第 06 篇：Sub-agents 实战——什么时候应该拆任务，怎么设计子任务边界

写在最后

公开 Skill 模板当然有用，但它的价值更像脚手架，而不是成品。

真正管用的 Skill，不是 star 最多的那个，也不是字段最全的那个，而是最贴近你项目真实工作流的那个。

你不需要一个很复杂的 Skill 系统。

你需要的，往往只是把团队最容易反复犯错的那几件事，提前写下来，让 Claude 每次都替你盯住。

这才是 Skill 真正应该发挥的作用。

如果你已经开始写 Skill 了，我反而建议你先检查一个问题：

你现在最卡住的，到底是“写不出规则”，还是“根本没分清哪些该放 CLAUDE.md、哪些该做成 Skill”？

这两个问题看起来很像，但解法完全不同。

AI Coding 系列持续更新。用别人的 Skill 模板是起点，不是终点。真正管用的 Skill，只有你自己的项目才能提炼出来。

掘金前端
连载04-CLAUDE.md ---一起吃透 Claude Code，告别 AI coding 迷茫ai_coder_小村儿
2026年4月8日 17:24

连载04-CLAUDE.md ---一起吃透 Claude Code，告别 AI coding 迷茫

掘金前端

作者 ai_coder_小村儿

2026年4月8日 17:24

CLAUDE.md 完整指南——让 Claude 真正理解你的项目

AI Coding 系列第 04 篇 · CLAUDE.md 到底是什么：不是文档，而是 Claude 的规则层

CLAUDE.md 被严重误解

很多人对 CLAUDE.md 的理解有偏差。有人把它当项目文档来写，两百行的架构介绍、API 清单、数据库设计，然后疑惑为什么 Claude 经常无视其中的规则。有人复制了一个通用模板，放在那里从来不改。还有人干脆不知道它到底是干什么的。

这类误解有一个共同点：
把 CLAUDE.md 当成了“给 AI 看的项目说明书”。

但 CLAUDE.md 的本质不是文档，而是规则层。

它不是用来完整介绍项目的，而是用来告诉 Claude：

这个项目里哪些边界不能碰
哪些行为默认是错的
哪些约定会反复影响决策
哪些高风险区域必须更保守

如果把它写成“项目背景”，Claude 最多只是“看过了”；
如果把它写成“行为规则”，Claude 的默认工作方式才会真正改变。

所以更准确的定义是：

CLAUDE.md 不是项目文档，而是把稳定偏好、高风险边界和重复纠正，提前变成 Claude 默认上下文的规则层。

一、CLAUDE.md 到底解决什么问题

一个好用的 CLAUDE.md，主要解决四类问题。

1. 把反复提醒的内容沉淀下来

如果你总是在 prompt 里反复说这些话：

这个项目不要改 .github/workflows
错误统一用 AppError
不要默认新增依赖
数据库变更前先讲回滚方案

那这些内容就不该每次重新说，而应该进入 CLAUDE.md。

2. 给 Claude 的默认积极性加边界

Claude 默认会尽量帮你完成任务，但很多项目里真正危险的，不是它不做事，而是它做得太多。

比如：

看见旧代码就想顺手重构
看见没测试就想补一整套基础设施
看见当前实现笨重就建议换栈

这些行为在通用场景里未必错，但在具体项目里可能是噪音，甚至是风险。
CLAUDE.md 的一个重要作用，就是给这种默认积极性划边界。

3. 把“代码里看不出来”的规则显式化

很多项目真正重要的约束，并不直接写在代码里。

例如：

某个目录是历史包袱区，轻易别碰
某些 migration 一旦上线后绝不能回写修改
某个模块表面简单，背后连着外部系统
某类接口一改就会影响前端联调和埋点

这些东西人类同事待久了会知道，但 AI 初来乍到不会知道。
CLAUDE.md 的价值，就在于把这些隐性知识提前说透。

4. 降低上下文成本

技术栈、关键路径、错误处理方式、依赖策略、部署边界，这些稳定规则本来就适合长期存在。把它们放进 CLAUDE.md，每次 prompt 就能专注当前任务，而不是重复灌输基础背景。

二、它不只是纠错层，也是预防层

前面说 CLAUDE.md 是纠偏器，这个说法是对的，而且很重要。因为它能一下子把很多人从“项目文档思维”拉回来。

但如果只停在“纠偏器”这一层，对它的理解还是不完整。

更准确地说，CLAUDE.md 既是纠错层，也是预防层。

1. 纠错层：把重复犯的错写成规则

比如：

你已经说过两次不要直接 throw new Error()
你已经纠正过几次不要改 .github/workflows
你已经反复提醒过不要随便 npm install

这些都属于典型的“纠错”。

2. 预防层：提前声明高代价边界

真正好用的 CLAUDE.md，并不只是在事后补锅。它还有一个同样重要的作用：提前声明那些一旦做错，代价就很高的边界。

比如：

支付模块改动前先确认幂等逻辑
migration 文件上线后只能新增，不能回写修改
生成目录不要手改，因为下次生成会覆盖
新增重大依赖前先说明必要性和替代方案

这些规则不一定是 Claude 已经犯过的错，也可能是你提前告诉它：

“这里不是不能动，而是这里的错误成本很高，你默认要更保守。”

所以从完整定位上说，CLAUDE.md 的作用不是单纯“记录反复犯的错”，而是：

把稳定偏好、风险边界和高代价约束，提前变成 Claude 的默认工作上下文。

CLAUDE.md 的真实定位

图：CLAUDE.md 不是项目文档，而是纠偏层 + 预防层 + 长期约束层。

三、文档式写法 vs 纠偏式写法

说一百遍不如直接对比。

❌ 文档式写法（Claude 读了，但行为不变）

本项目是一个电商平台，使用 Node.js + Express + TypeScript 开发，
数据库采用 PostgreSQL，通过 Prisma 进行 ORM 管理。
项目包含用户模块、订单模块、支付模块和通知模块，
遵循 RESTful API 设计规范……

✅ 纠偏式写法（Claude 读了，行为立刻改变）

- 禁止 throw new Error()，统一用 AppError 类
- API 响应必须含 success / data / timestamp 三个字段，不能自己发明格式
- 禁止在 controller 层直接写 SQL，必须通过 service 层
- 所有异步函数必须有 try-catch，不靠外层中间件兜底
- 新增依赖前必须问我，不要自行 npm install

文档式写法让 Claude “知道”了，但知道不等于行动。
纠偏式写法告诉 Claude：“在这个项目里，你的默认行为哪里不对。” 这才是它真正听进去的语言。

判断一条规则是不是纠偏式，只用问一个问题：

这条规则是在纠正 Claude 的某个具体行为，还是在描述项目背景？

能对应到一个具体行为变化的，是纠偏。
其他的，是文档。

四、它和 Prompt、文档、Memory、Skill 的边界

很多人用不好 CLAUDE.md，不是不会写规则，而是把它和别的东西混在一起了。

最容易混淆的有四个对象：Prompt、项目文档、Memory、Skill。

CLAUDE.md 和其他机制的边界

图：Prompt 管当前任务，文档管背景，Memory 管自动沉淀，Skill 管重复流程，CLAUDE.md 管稳定规则。

源码里的分工也很明确

如果去看 Claude Code 的源码，CLAUDE.md 和 Memory 的边界其实分得很清楚。相关实现可以看 src/utils/claudemd.ts。在这部分实现里，CLAUDE.md 被归在一套明确的 instruction loading 顺序里：

Managed memory：全局托管规则
User memory：~/.claude/CLAUDE.md
Project memory：仓库里的 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md
Local memory：CLAUDE.local.md

这套机制本质上是在加载指令文件。

而同一个文件里又能看到另一套独立机制：当 auto memory 打开时，系统会额外读取 getAutoMemEntrypoint() 返回的 MEMORY.md，其类型是 AutoMem，团队记忆则是 TeamMem。源码里甚至专门写了注释：

AutoMem/TeamMem are intentionally excluded — they're a separate memory system, not "instructions" in the CLAUDE.md/rules sense.

这句话非常关键。它说明：

CLAUDE.md 这一层，本质上是 instructions / rules
MEMORY.md 这一层，本质上是 auto memory / persistent memory

它们最后都会进入上下文，但在架构里并不是同一个东西。

所以如果从源码上更严格地说，CLAUDE.md 不是 MEMORY.md 的别名，更不是 auto-memory 的索引。
真正扮演“索引 + 主题文件”角色的，是后面的 MEMORY.md 系统。

1. Prompt 负责当前任务

Prompt 解决的是这一次你到底要 Claude 做什么。

比如：

这次只修 bug，不要顺手重构
这次只分析原因，先不要改代码
这次只改前端，不动后端

这些都是单次任务边界，适合写在 prompt 里，不适合沉淀进 CLAUDE.md。

2. 项目文档负责完整背景

README、设计文档、接口文档、架构说明，负责回答的是：

这个项目是什么
系统怎么设计
模块如何划分
业务流程怎么走

这些内容通常信息量大、细节多、更新频繁，它们的职责是“说明项目”，不是“约束 Claude 的默认行为”。

3. CLAUDE.md 负责稳定规则

CLAUDE.md 解决的是那些跨多次任务都成立、而且会持续影响 Claude 决策的东西。

比如：

高风险文件和目录
错误处理规范
依赖策略
migration 边界
哪些行为必须先确认

它不负责讲完整背景，只负责把真正影响行为的规则提炼出来。

4. Memory 负责自动沉淀

它更像 Claude 在长期协作里逐步学到的东西，是补充，不是替代。

你可以把它理解成“模型慢慢记住了你们项目里的某些偏好和事实”，但这类记忆不适合代替明确规则。因为对于关键边界来说，你明确写下来的东西，永远比它自己学到的更稳。

结合源码看，这个分工会更清楚：

CLAUDE.md 通过 instruction loader 进入系统 prompt
MEMORY.md 则是 auto memory 的入口文件
相关 topic files 会在需要时被检索和召回，而不是把所有细节都塞进一个大文件

因此，更准确的理解是把它们视为“两套协作机制”，而不是“一份文件的两种叫法”。

5. Skill 负责重复流程

CLAUDE.md 管的是“长期规则”，Skill 更适合管“这类任务应该怎么做”。

比如：

需求分析怎么展开
Code Review 按什么顺序做
排查线上 bug 用什么流程
新功能开发先看哪些文件、再做哪些验证

这类内容本质上是“做事模板”，更像流程，不像规则。

可以概括成一句话：

当前任务进 Prompt
稳定规则进 CLAUDE.md
完整背景进项目文档
自动沉淀交给 Memory
重复流程沉淀成 Skill

一旦边界分清楚了，很多人最头疼的那个问题就会自动消失：

为什么我明明写了很多东西，但 Claude 还是不按我想的来？

因为你很可能把应该放在不同位置的信息，全塞进了 CLAUDE.md。

五、三层分层架构

CLAUDE.md 不是一个单一文件，而是一个分层的规则系统。

三层分层架构

图：先按稳定性分层，再决定规则应该写到用户级、项目级还是公司级。

用户级：~/.claude/CLAUDE.md
你电脑上所有项目都生效，写个人偏好。

项目级：仓库根目录的 CLAUDE.md
只在这个项目生效，写项目特有约定，提交进 Git。

公司级：企业统一管理的配置位置
整个组织生效，写合规要求和架构标准。大型企业才更常用，普通团队通常不需要。

判断一条规则放哪层，只用一个标准：

换个项目还成立吗？

成立放用户级。
比如：“我的变量命名用驼峰。” 换到任何项目都一样。

不成立放项目级。
比如：“这个项目用 Prisma，禁止用 Sequelize。” 换到 MongoDB 项目就不适用了。

这个区分看起来简单，但它直接决定后面的维护成本。

六、用户级：写你的默认行为偏好

用户级规则要少而精，不超过 50 行。这里写的是覆盖 Claude 默认值的个人偏好。

# 我的个人偏好

## 代码风格
- 缩进：2 个空格
- 变量命名：camelCase，类名 PascalCase
- 单行不超过 100 字符

## 我固定用的库（不要建议替代品）
- 日期处理：date-fns，不用 moment.js
- HTTP 请求：axios，不用 node-fetch
- 测试：Jest，不用 Vitest 或 Mocha

## 从不做的事
- 不要在我没要求时修改测试文件
- 不要建议我换版本控制工具
- 不要在随意讨论时提出架构大改动

## Git 提交格式
feat(模块名): 简短描述

- 改动说明 1
- 改动说明 2

注意措辞：写的是“我的偏好”，不是“你必须”。前者 Claude 当作信息接收，后者听起来像命令，反而可能在某些场景被跳过。

用户级不该写什么

一次性的任务背景
大段项目文档
经常变动的技术现状
只在某个仓库成立的规则

比如：“我现在在做一个电商系统。” 这不是偏好，是当前任务。应该放在 prompt 里。

七、项目级：记录这个项目特有的边界

项目级可以稍长，100 行左右。核心是三类内容：

1. 关键文件保护

## 禁止修改的文件
- src/config/env.ts — 改了会影响生产环境变量加载
- .github/workflows/* — CI/CD 流水线，改动需要 DevOps 审核
- 数据库 migration 文件一旦执行，不得修改，只能新增

2. 编码规范，必须具体到代码动作

## 错误处理
统一使用 AppError 类，禁止 throw new Error()：
throw new AppError('用户不存在', 404, 'USER_NOT_FOUND')

## API 响应格式
所有响应必须符合：
{ "success": true, "data": {}, "timestamp": "ISO字符串" }
错误响应：
{ "success": false, "error": "ERROR_CODE", "message": "描述" }

3. 高风险路径标注

## 高风险区域（修改前必须告知我）
- src/modules/auth/* — 认证核心，任何改动都需要 review
- src/handlers/payment/* — 对接支付商，出错直接影响收入
- src/database/migrations/* — 不可逆操作，要有回滚方案

项目级真正决定效果的，不是“把整个项目介绍一遍”，而是：

把这个仓库里最容易做错、最不能做错的东西写出来。

八、一条好规则到底该怎么写

很多人不是不会列规则，而是写出来之后没有约束力。

比如：

代码要整洁
数据库迁移要小心
不要随便改配置

这些话人类看得懂，但模型不一定知道“到底怎样做才算遵守”。

一条好规则，尽量包含这几个元素：

触发场景
期望动作
禁止动作
原因
示例

一条好规则怎么写

图：好规则最少要把场景、动作、边界和原因交代清楚。

看一个例子就很清楚。

❌ 只有规则
- 使用 Prisma 生成迁移，不要写原生 SQL

✅ 规则 + 原因 + 行为边界
- 涉及 schema 变更时，优先走现有 migration 工作流，不要临时手写 SQL 直接改结构。
  原因：团队的审查、回滚和环境同步流程都围绕当前 migration 体系建立。
  如果必须做破坏性变更，先说明影响范围和回滚方案。

再比如：

❌ 太抽象
- 注意统一错误处理

✅ 可执行
- 所有业务异常统一使用 AppError，禁止直接 throw new Error()。
  原因：前端依赖统一错误码和 message 做提示与埋点归类。

关键就在这里：

CLAUDE.md 不是写原则，而是写可执行规则。

九、为什么有时有效，有时又像没生效

这也是很多人真正困惑的地方。

不是所有写进 CLAUDE.md 的内容，效果都一样。有些规则一写进去，Claude 的行为马上变化；有些规则写了之后，几乎没感觉。

通常不是因为它“没读”，而是因为规则本身写得不够能执行。

第一，规则写成了背景介绍

例如：

本项目采用分层架构，强调可维护性和扩展性。

这句话是背景，不是约束。Claude 即使看到了，也很难从里面推导出具体行动。

第二，规则太抽象

例如：

- 代码要整洁
- 注意性能
- 数据库修改要谨慎

这些话人类看得懂，但模型不知道“怎样才算遵守”。

第三，规则太多，信噪比下降

不是说长文一定不好，而是低价值内容一多，真正重要的规则就会被埋掉。

如果一份 CLAUDE.md 里面既有项目概述、又有接口说明、又有架构文档、又有零碎提醒，那 Claude 真正应该优先遵守的那些边界，反而不够突出。

第四，规则之间互相冲突

比如你在用户级里写了“我习惯四空格缩进”，项目级里又写“这个项目统一两空格”，但没有说明项目级覆盖团队标准。
这种情况下，Claude 不是一定做错，而是判断空间会变大。

第五，单次任务 prompt 和长期规则打架

如果你在 CLAUDE.md 里长期写“默认不要大改”，但当前 prompt 又说“请你重构这一块并统一风格”，那单次任务会临时改变优先级。

这不是 CLAUDE.md 失效，而是上下文优先级在变化。

真正决定它能不能稳定生效的，是三件事：

规则足够具体，边界足够清楚，信噪比足够高。只有这三件事同时成立，CLAUDE.md 才会真正改变行为。

十、它很重要，但不是万能控制器

把这一点想清楚，对 CLAUDE.md 的期待反而会更稳。

CLAUDE.md 很强，但它不是万能控制器。它做不到下面这些事：

它不能替代清晰的任务描述
它不能替代 README 和设计文档
它不能替代你对复杂任务的即时判断
它不能保证 Claude 在任何场景下 100% 机械执行

它真正擅长的是：

让默认行为更接近你的项目习惯
让高风险边界更早暴露
让重复提醒沉淀成长期规则
让每次 prompt 更聚焦当前任务

所以最好的理解方式不是：

“只要我把 CLAUDE.md 写好了，后面什么都不用管了。”

而是：

“我用 CLAUDE.md 把稳定规则立住，再用 prompt 管当前任务，用文档承载背景，用 Skill 沉淀流程。”

只有在这套分工里，CLAUDE.md 的作用才会既强，又稳定。

十一、连接第 03 篇：为什么它能解决“纠正回退”

第 03 篇讲过一个现象：你在对话里纠正了 Claude，它承认了，但过几轮又犯同样的错。这不是 Claude 不配合，而是对话历史会随时间衰减，纠正效果也会随之消退。

更稳定的纠正方式，就是写进 CLAUDE.md。

写进 CLAUDE.md 的规则，每次对话开始时都会被系统自动注入，不受对话长度影响，也不会像临时纠正那样快速衰减。

判断标准很简单：

同一件事你纠正了两次以上，就应该写进 CLAUDE.md，不要再在对话里重复说。

# 这条规则在对话里说了三次，该进 CLAUDE.md 了：
- 日志统一用 logger.info/warn/error，禁止 console.log

十二、Claude 会主动学习，但它补充不了规则层

CLAUDE.md 不是单向的。你往里写规则，Claude 也会在长期协作中逐步积累知识。

每轮对话结束后，Claude Code 会在后台启动一个独立的子 Agent，分析对话里有没有值得保留的项目知识，自动写入 Memory 文件，下次会话时注入：

对话结束 → 后台子 Agent 分析 → 提取项目偏好和技术决策
→ 写入 ~/.claude/projects/[项目]/memory/ → 下次会话自动读取

你在某次对话里说了“我们禁止用 moment.js，改用 date-fns”，下次打开 Claude Code，它已经记得了。

几个要知道的细节：

它补充 CLAUDE.md，不取代它。
自动记忆是“Claude 学到的”，CLAUDE.md 是“你明确要求的”，关键约束还是应该写在 CLAUDE.md 里。

明确说出来的比隐含的更容易被记住。
在对话里直接说“我们统一用 date-fns”，提取率更高；只是悄悄在代码里换了库，Claude 可能记不到。

你可以检查它记了什么。
/memory 命令可以查看当前记忆内容，发现记错了直接改，它本质上还是普通文本文件。

实际效果是：Claude Code 越用越懂你的项目。头几天需要反复解释背景，用了几周后，很多背景已经自动沉淀，你的 prompt 可以越写越短。

Memory 的索引 + 主题文件结构

图：从源码看，Memory 更像索引入口 + topic files，而不是一个无限膨胀的大文件。

从源码看，Memory 本质上是一套“索引 + 主题文件”的结构

从实现上看，auto memory 不是把内容都堆在一个文件里。相关实现可以看 src/memdir/memdir.ts。在这部分实现里，入口常量就是：

export const ENTRYPOINT_NAME = 'MEMORY.md'
export const MAX_ENTRYPOINT_LINES = 200
export const MAX_ENTRYPOINT_BYTES = 25_000

这三行信息已经说明了很多问题：

第一，真正被当作 memory 入口文件的，是 MEMORY.md，不是 CLAUDE.md。
第二，系统从设计上就不希望这个入口文件无限膨胀。
第三，memory 架构默认就不是“把所有内容堆在一个大文件里”。

同一个文件里，源码把保存流程直接写成了两步：

先把记忆写入独立主题文件
再在 MEMORY.md 里增加一个索引指针

源码注释原话基本就是这个意思：

Step 1：write the memory to its own file
Step 2：add a pointer to that file in MEMORY.md

而且它还专门强调：

MEMORY.md is an index, not a memory

从实现上看，Claude Code 的 auto memory 更像：

MEMORY.md：目录页 / 索引页
topic files：按主题拆开的详细内容

这也解释了一个很多人会问的问题：

如果记忆越积越多，MEMORY.md 不会越来越大吗？

答案是：源码层面已经考虑了这个问题。

truncateEntrypointContent() 会对 MEMORY.md 做双重限制：

超过 200 行会截断
超过 25KB 也会截断

截断后甚至还会追加警告，提醒把细节移到 topic files，只把一行短索引留在 MEMORY.md。

换句话说，这套设计本身就在强制你保持：

索引足够短
细节分散到主题文件
入口文件永远尽量装得进上下文

这和 `CLAUDE.md` 的定位，是什么关系

最容易混在一起的，恰恰是规则系统和记忆系统。

如果站在源码架构的角度看：

CLAUDE.md 更像 instruction layer
MEMORY.md 更像 memory index layer
topic files 更像 memory payload layer

这三层不是互相替代，而是互相配合。

所以把 CLAUDE.md 定义成“规则层”是成立的，而且和源码是对齐的。

放到 Claude Code 的完整架构里看，CLAUDE.md 负责规则，MEMORY.md 负责记忆索引，topic files 负责详细内容。

这样去理解，规则、索引和记忆详情各自负责什么，就不会再混成一团。

从源码看“自愈”和写入一致性

把这套机制类比成一种带“自愈”倾向的写入纪律，可以作为理解辅助，但不宜把类比直接当成源码结论。

从目前能看到的实现和解析文档来看，至少可以确定三件事：

memory 保存采用“先写主题文件，再更新 MEMORY.md 指针”的两步方式
这种顺序天然更有利于一致性，因为索引最终指向的是已经成功落盘的内容
它的思路更接近“先落数据，再更新索引”，和很多数据库 / 存储系统的一致性设计取向相似

更稳妥的理解是，把它当作一种 可以类比理解 的一致性思路，而不是直接把它等同于“源码明确实现了 WAL 逆向”。

因为源码里我能确认的是：

两步保存存在
MEMORY.md 是索引存在
入口大小控制存在
按需检索 topic files 存在

这些都是可以直接从源码和解析文档里站得住的。

十三、两个最常见的陷阱

陷阱一：写得太多，关键规则被淹没

CLAUDE.md 写得太长时，Claude 往往只会抓住其中最显眼、最强约束的那部分，其他内容会逐渐退化成背景噪音。规则越多，真正稳定生效的比例通常越低。

解决方法：

定期删掉已经不再是问题的规则
删掉太细节、没有行为约束力的规则
删掉重复表达

CLAUDE.md 应该是个活跃的 hotlist，不是越来越臃肿的文档。

陷阱二：规则放错层级

用户级放了项目特有规则，Claude 在其他项目里也按这个来。
项目级放了所有项目通用规则，十几个项目各自维护一份重复内容，改一条要改十几个地方。

解决方法还是那一句：

换个项目还成立吗？

成立放用户级，不成立放项目级，一次定好就别再改。

十四、维护节奏

CLAUDE.md 写好之后不是扔着不管，需要定期维护。

第一个月：初始化

用 /init 生成草稿，花半小时补充：

关键文件保护
错误处理规范
API 格式约定
高风险路径说明

这是最重要的一次，做好了后面会省很多事。

每两周：维护

回顾最近 Claude 犯过什么错。

同一个错出现两次以上，加进 CLAUDE.md
已经不构成问题的规则，删掉
写得太空的规则，改具体一点

每季度：清理

把整个文件读一遍：

删冗余
合并重复
简化过细规则

目标是让文件保持高信噪比，而不是越写越长。

十五、检查清单

提交项目级 CLAUDE.md 前过一遍：

规则是纠偏式的，不是文档式的
每条规则能对应到 Claude 的一个具体行为变化
关键文件有明确的保护声明
高风险路径有标注和警告
重要规则附上了“为什么”
用户级和项目级没有混放
文件总长度不超过 200 行
对话里纠正过两次以上的规则已经写进来了

本篇实践任务

任务一： 打开你现有的 CLAUDE.md，把里面每条规则过一遍：它是纠偏式，还是文档式？把文档式的删掉或者改成纠偏式。

任务二： 回想最近一周，你在对话里纠正过 Claude 几次同一个问题？把这些问题整理成具体规则，写进 CLAUDE.md，下次对话观察效果。

任务三： 运行 /memory，看看 Claude 已经自动记住了什么。和你的 CLAUDE.md 对比，有没有重复的内容？有没有记错的内容需要修正？

下篇预告

第 05 篇：Skill 提炼——把重复任务沉淀成可复用模板

CLAUDE.md 管的是全局规则，Skill 管的是任务模板。当同一类任务反复出现，把“怎么做这类任务”浓缩成一个 Skill，下次直接触发。下一篇会讲什么时候沉淀 Skill、怎么写一个真正有效的 Skill，以及 Skill 和自定义命令的边界在哪。

AI Coding 系列持续更新。CLAUDE.md 是规则层，不是项目文档。写法不同，效果天壤之别。

普通视图

Harness Engineering：驾驭 AI Agent 的工程学

换了更好的模型，只提升了 0.7%

三次范式跃迁

什么是 Harness Engineering？

这些都不是 PPT 数字

越快越慢：AI 的速度陷阱

模型偷懒：一个比"上下文太长"更深的问题

Harness Engineering 的六个核心组件

1. AGENTS.md：写给 AI 的操作手册

2. Hooks：把"告知"变成"拦截"

3. 架构即护栏：越相信 AI，越需要给它设限

4. Sub-Agent 架构：Context 防火墙与并发控制

Context Rot（上下文腐化）是真实的，而且比你想象的更深

并发架构：更进一步

5. 长时任务 Harness：失忆实习生问题

6. Skills：按需加载，而不是全部预装

更完整的分析框架：Feedforward + Feedback

三类 Harness 目标

交付侧的 Harness：黄金标准管道

实战：Skill 分类学

验证反压：成功静默，失败才说话

真实案例：8Lee 的 $zip 命令

Harness 应该越来越薄

未来三个阶段

开放的硬问题

从今天开始做什么

结语：一门关于信任的工程学

参考来源

英文一手资料

中文解析与实践

别再直接 Fork 别人的 Claude Skill：真正有用的 Skill，都是从项目里长出来的

先说结论

一、公开 Skill 模板为什么一开始很香，后来却越用越别扭

1. 太宽泛

2. 太嘈杂

3. 太不像你的项目

二、先把 Prompt、CLAUDE.md、Skill 这三件事彻底分清楚

一个常见误判：很多问题根本不需要写 Skill

三、什么时候一个任务真的值得被沉淀成 Skill

1. 输入是否稳定

2. 输出是否有共同模式

3. 有没有容易漏掉的关键步骤

四、从一个真实痛点开始，走完 Skill 的提炼过程

你反复踩的坑

先设计内容，再去想格式

1. 什么时候用

2. 按什么顺序做

3. 输出长什么样

4. 什么时候不适用

五、真正落到 SKILL.md 文件层，哪些字段值得你认真写

SKILL.md 不是整个 Skill，它只是入口

Skill 放在哪，决定它是谁的能力

六、如果只停在经验层，这篇还差半口气：我后来去翻了源码

1. 为什么触发逻辑主要看 frontmatter，而不是正文

2. 为什么 allowed-tools 不是建议，而是权限边界

3. 为什么 paths 不是说明文字，而是条件激活机制

4. 为什么大型项目不该只在根目录维护一套总 Skill

5. 为什么长对话里，Skill 不会轻易“失忆”

七、不是所有 Skill 都应该让 Claude 自动触发

1. 参考型 Skill：给 Claude 补充背景知识

2. 任务型 Skill：给 Claude 一个要完成的动作

3. disable-model-invocation: true 和 user-invocable: false 不是一回事

八、Skill 的天花板：从静态模板到可执行能力

1. 动态注入：先拿真实数据，再交给 Claude

2. 这件事为什么重要：它决定了 Skill 的上限

3. 从架构位置看，Skill 不是 Tool，也不是 Agent

九、真正让 Skill 变靠谱的，不是写出来，而是验证出来

不要只看结果，还要看 Claude 是怎么“导航”这个 Skill 的

十、写 Skill 时，最常见的四种设计模式，以及最容易踩的反模式

1. 模板驱动模式：解决“输出不稳定”

2. 脚本增强模式：解决“结果不稳定”

3. 知识分层模式：解决“上下文过载”

4. 工具隔离模式：解决“能力边界失控”

最常见的反模式

十一、完整案例：把一个通用 code review 模板，提炼成你项目真正需要的 Skill

第一步：先确认痛点到底是什么

第二步：从公开模板里提取真正有用的部分

第三步：把它压缩成一个真正能用的 Skill

第四步：在真实使用里继续迭代

真实案例：8Lee 的 `$zip` 命令

五、真正落到 `SKILL.md` 文件层，哪些字段值得你认真写

2. 为什么 `allowed-tools` 不是建议，而是权限边界

3. 为什么 `paths` 不是说明文字，而是条件激活机制

3. `disable-model-invocation: true` 和 `user-invocable: false` 不是一回事

五、真正落到 `SKILL.md` 文件层，哪些字段最值得你花心思

2. `allowed-tools` 是系统层权限，不是给 Claude 的礼貌性建议

3. `paths` 不是文档字段，它会把 Skill 放进条件激活区