AI 时代的工程实践：复利工程体系

工程师的复利困境有没有想过，为什么同样的工作，有人做一次就永久受益，有人却要反复做？最常见的场景是这样的：周一花了 3 天搭建配置系统，周三又要搭建协议生成，周五还要搭建数据表创建流程。每次都是从零开始，每次都要排查同样的问题，每次都要写同样的文档。这不是懒惰，这是系统设计的问题。一次性

工程师的复利困境

有没有想过，为什么同样的工作，有人做一次就永久受益，有人却要反复做？

最常见的场景是这样的：周一花了 3 天搭建配置系统，周三又要搭建协议生成，周五还要搭建数据表创建流程。每次都是从零开始，每次都要排查同样的问题，每次都要写同样的文档。

这不是懒惰，这是系统设计的问题。

一次性工作 vs 永久资产

大多数工程师的工作模式是这样的：

完成任务 → 交付代码 → 下一个任务
知识停留在脑子里 → 离职时流失 → 新人重复踩坑

这就像每次都在重新发明轮子。经验、踩坑、最佳实践，都没有被系统化地保留下来。

但有些团队不一样。他们把每一次工作都变成了可复用的资产：

第一次搭建 Config 系统 → 流程化 → 后续只需定义即可
第一次写技术方案 → Skill 化 → 自动触发，持续演进
第一次踩坑 → 沉淀为规范 → 团队永久受益

这就是复利工程的核心思想。

这篇文章要讲什么

本文会从三个角度展开：

Skill 系统：如何把经验变成可复用的工作流
复利引擎：如何建立知识的永久积累机制
理论基础：为什么这样做有效（LLM、Agent、约束设计）

读完这篇，会理解：为什么有些团队效率高、知识积累快、新人成长快。不是因为他们更聪明，而是因为他们建立了复利工程体系。

Skill 系统：为什么 AI 需要 Skill

什么是 Skill？为什么 AI 需要 Skill？

Skill 不是一个新概念，但在 AI 时代有了新的定义和紧迫性。

简单说，Skill 就是把工作流程标准化、模板化、可复用化。但更重要的是：Skill 是为了让 AI 不会忽视规则。

人和 AI 的根本差异

人的工作方式：

做过一次"写技术方案"，下次做类似的工作时，脑子里会自动想起上次的经验
踩过一个坑，下次会自动避免
经验是"隐性知识"，存在脑子里

AI 的工作方式：

每次对话都是从零开始
没有"记忆"，只有上下文
如果不明确告诉 AI 规则，AI 就会忽视
即使告诉了，在长对话中也容易被忽视

这就是为什么需要 Skill。Skill 不是为了解决人的问题，而是为了让 AI 能够"记住"和"遵守"规则。

Skill 的三个关键要素

1. 明确的输入和输出

例子：技术方案 Skill

输入：

功能需求描述
技术约束（比如"必须用 Redis"）
时间限制

输出：

数据结构设计
API 接口定义
实现流程
风险评估

当 AI 知道"输入是什么，输出应该是什么"时，就能更准确地执行任务。

2. 已知陷阱和成功模式

这是 Skill 最关键的部分。

例子：Compounding Engineering Skill

已知陷阱：

session 模块的 save() 方法是异步的，必须 await
不要在循环中调用 API，使用批量接口

成功模式：

新增 API 端点时，参考 PR #241 的错误处理方式
代码审查时，检查是否遵循了 AppError 类的使用规范

这些陷阱和模式是什么？是人踩过的坑。但关键是：这些坑必须被明确记录下来，让 AI 能够看到和遵守。

3. 验收标准

每个 Skill 都需要明确的验收标准。什么样的输出才算"完成"？

例子：Observation Tracker Skill

验收标准：

所有发现都被记录到 .observations.md
每条记录包含：文件位置、优先级、描述、建议行动
任务完成前，所有观察都被总结并报告给用户

验收标准的作用是：让 AI 知道什么时候才算"做完了"。

Skill 的演进：从一次性文档到可持续资产

这是最关键的一点。

传统方式：

写一份技术方案文档
项目完成后，文档就成了"历史文档"
下一个类似项目时，新人不知道有这份文档，或者文档已经过时

Skill 化方式：

第一次做这个工作时，沉淀为 Skill
第二次做同样的工作时，直接用 Skill（可能需要微调）
第三次、第四次…每次都能用，每次都能改进
Skill 本身在不断演进，变得越来越好

Compounding Engineering Skill 就是这样的例子：

执行原则：

即时记录：发现可沉淀内容时立即行动，不要等
具体引用：引用具体的 PR、文件、代码位置
持续迭代：文档随项目演进而更新
最小化重复：让每个问题只需要解决一次

这不是一份静态的文档，而是一个活的系统。每次使用 Skill 时，都可能发现新的陷阱、新的模式，然后更新 Skill。

Skill 的三个层级与实例

第一层：流程型 Skill（直接执行）

这类 Skill 步骤清晰、可预测，AI 可以直接按步骤执行。

例子：Observation Tracker

核心思想：在任何复杂任务中，AI 容易因为上下文限制而遗漏重要发现。Observation Tracker 的职责是单一的：记录和保留所有发现。

工作流程：

在任务开始时创建 .observations.md
在工作过程中，发现任何问题就立即记录（BUG、REFACTOR、TEST、SECURITY、PERF、DOCS、DEBT、UNCLEAR）
在任务结束前，读取 .observations.md 并总结

关键原则：

Record First, Judge Later：先记录，后过滤
Low Friction：记录应该快速，不要成为负担
No Silent Discards：永远不忽视发现，要么处理，要么报告

这个 Skill 的每一步都很明确，AI 可以直接执行。

第二层：决策型 Skill（需要判断）

这类 Skill 需要 AI 进行判断和决策。

例子：Occam’s Razor（奥卡姆剃刀原则）

核心思想：设计和需求容易膨胀。Occam’s Razor 的职责是单一的：检查是否有不必要的复杂性。

检查清单：

必要性检查：这个功能是核心需求还是锦上添花？去掉它，用户核心目标是否仍能达成？
复杂度检查：有没有更简单的实现方式能达到相同效果？
范围检查：新需求是否偏离了原始目标？是否在一次迭代中试图解决太多问题？
成本收益检查：实现成本与带来的价值是否匹配？维护成本是否被考虑在内？

行动指南：

质疑：主动询问"这个真的需要吗？"
简化：提出更简单的替代方案
推迟：建议将非核心功能移至后续版本
删除：勇于建议移除不必要的部分

这个 Skill 不是"做什么"，而是"怎么思考"。AI 需要在每个设计决策点应用这个原则。

第三层：演进型 Skill（持续改进）

这类 Skill 本身在不断演进。

例子：Compounding Engineering（复利工程）

核心思想：每次工作都应该产生长期价值。Compounding Engineering 的职责是单一的：把一次性工作转化为系统永久知识。

执行流程：

Bug 修复的长期价值：修复 bug 时执行检查清单（Lint 规则、Skill 演进、回归测试、审查清单）
从代码审查提取模式：此反馈是否适用于未来的类似代码？是否应成为项目编码规范？
建立可复用工作流程：发现有效工作模式时进行沉淀
持续演进 Skill：完成一次"长期价值修复"后，使用 skill-evolution-manager 演进相关 Skill

演进记录（evolution.json）：

v1.0：基础的经验沉淀流程
v1.1：加入了 skill-manager 管理
v1.2：加入了 skill-evolution-manager 持续演进机制

每次使用这个 Skill 时，都可能发现新的改进点，然后更新 Skill。这样做的好处是：Skill 会越来越好，越来越适应实际工作。

Skill 职责的单一性原则

这是 Skill 设计中最容易被忽视但最关键的原则。

错误做法：

一个 Skill 试图解决"代码审查、性能优化、安全检查、文档生成"
结果：Skill 变得复杂、难以维护、容易被忽视

正确做法：

Observation Tracker：只负责记录发现
Occam’s Razor：只负责检查复杂性
Compounding Engineering：只负责沉淀经验
每个 Skill 职责单一，AI 能清晰地理解和执行

为什么职责单一很重要：

AI 在长对话中容易忽视复杂的规则
职责单一的 Skill 更容易被记住和应用
多个单一职责的 Skill 可以组合使用，比一个复杂 Skill 更灵活
单一职责的 Skill 更容易演进和维护

Skill 的核心价值

1. 让 AI 不会忽视规则

问题：如果只在 Prompt 中写规则，AI 在长对话中容易忽视。

解决：把规则写成 Skill，让 AI 在每个关键点都能看到和应用。

2. 让知识可以传递

问题：人的经验是隐性知识，很难传递。

解决：把经验显式化为 Skill，新人和新 AI 都能快速学习。

3. 让工作可以复用

问题：每次做类似的工作都要从零开始。

解决：用 Skill 快速复用之前的经验，减少重复工作。

4. 让系统可以演进

问题：文档容易过时，规范容易被遗忘。

解决：Skill 是活的系统，每次使用都可能改进，持续演进。

核心洞察

Skill 系统的本质是把隐性知识显式化，让 AI 能够"记住"和"遵守"规则。

不是为了解决人的问题，而是为了让 AI 更可靠
不是一份静态的文档，而是一个活的系统
不是一次性的投入，而是持续的演进
职责必须单一，这样 AI 才能清晰地理解和执行

复利引擎：知识的永久积累

复利工程的核心：长期主义

复利工程的本质不是"偷懒"，而是为长期稳定性做投资。

短期 vs 长期的权衡

短期思维：

“这个功能赶紧做完，先上线再说”
不写 Skill，不建立流程，不沉淀经验
结果：功能快速上线，但后续维护成本高，新人重复踩坑

长期思维：

“这个功能怎么做才能长期稳定？”
建立 Skill、流程、规范
结果：前期投入较大，但后续维护成本低，知识永久积累

复利工程就是长期思维的体现。

复利工程的三个层级

第一层：经验沉淀

当完成一个工作时，不要只是交付代码。要问自己：

这个工作中有哪些陷阱？
有哪些最佳实践？
有哪些规范是新人需要知道的？

把这些沉淀下来，写成 Skill。

例子：

Bug 修复 → 沉淀为"已知陷阱"Skill
代码审查 → 沉淀为"代码规范"Skill
问题排查 → 沉淀为"排查清单"Skill

第二层：知识库建设

把所有沉淀的经验组织成一个可查询、可搜索的知识库。

这样做的好处是：

新人遇到问题时，能快速找到答案
不需要重复问同样的问题
团队知识不会因为某个人离职而流失

知识库的形式：

Skill 管理系统（比如 skill-manager）
版本控制（evolution.json 记录演进历史）
分类和搜索（快速定位相关 Skill）

第三层：自动化执行

最高层是让 AI 或自动化系统直接执行这些 Skill。

比如：

代码审查 Skill → AI 自动审查代码
问题排查 Skill → AI 自动诊断问题
技术方案 Skill → AI 自动生成初版方案

这样做的好处是：

人类专注于创意和决策
重复性工作由 AI 完成
效率提升 10 倍以上

复利工程的四个关键实践

1. 把规则从 Prompt 挪到 Skill

很多团队的做法是：写一份详细的 Prompt，让 AI 按照 Prompt 执行。

但这有个问题：Prompt 规则容易被忽视，尤其是在长对话中。

更好的做法是：把规则写成 Skill。

代码风格 → 用 Skill 明确规范
数据格式 → 用 Skill 定义标准
业务规则 → 用 Skill 记录陷阱和模式

这样做的好处是：

规则永远不会被忽视（Skill 是显式的）
新人不需要记住规则，Skill 会提醒
AI 也会自动遵守规则（因为 Skill 在上下文中）

2. 短对话优于长对话

LLM 在长对话中容易出现幻觉和性能衰减。所以：

不要把所有工作放在一个长对话里
把复杂任务拆分成多个短对话
每个短对话专注于一个子任务
用外部记录（Skill、配置文件、数据库）传递上下文

例子：

不要：一个对话里完成"需求分析 → 设计 → 实现 → 测试"
要：四个短对话，每个对话一个阶段，用 Skill 传递上下文

3. 建立"记忆"机制

Agent 没有持久记忆，每次对话都是从零开始。所以需要建立外部"记忆"：

Skill 文件（记录规范、陷阱、模式）
项目信息文件（记录当前进度、决策）
配置文件（记录技术选型、约束）
知识库（记录经验、最佳实践）

这样做的好处是：

Agent 能"记住"之前的决策
新 Agent 能快速接手工作
知识不会因为对话结束而丢失

4. 验收标准 + 自动化检查

每个 Skill 都需要明确的验收标准，并且这些标准要自动化。

不能是"看起来不错"
必须是"通过了所有检查"
检查包括：lint、typecheck、单测、集成测试等

这样做的好处是：

质量有保证
不需要人工审查
问题能快速发现

复利工程的数学模型

假设一个工作第一次需要 10 小时。

没有复利：

第 1 次：10 小时
第 2 次：10 小时
第 3 次：10 小时
总计：30 小时

有复利（假设每次效率提升 30%）：

第 1 次：10 小时（沉淀 Skill）
第 2 次：7 小时（用 Skill，效率提升 30%）
第 3 次：5 小时（Skill 继续优化）
总计：22 小时（节省 27%）

如果做 10 次：

没有复利：100 小时
有复利：约 50 小时（节省 50%）

这就是复利的威力。

核心洞察

复利工程的本质是把一次性工作变成永久资产。

第一次投入较大，但后续每一次都能快速复用
关键是要尽快沉淀、尽快自动化
不要等到问题积累了再改，要在第一次就建立好系统

理论基础：理解 LLM 与 Agent

LLM 的本质：自回归生成

要理解为什么复利工程对 AI 时代这么重要，首先要理解 LLM 的本质。

LLM 不是在"思考"，而是在逐个预测 token。

输入一个 prompt
LLM 预测下一个 token
把这个 token 加到输入中
再预测下一个 token
重复这个过程，直到生成完整的回答

这个过程叫自回归生成。它有一个重要的特性：LLM 无法修改已生成的内容。

如果前面生成错了，后面的内容会基于这个错误继续生成，导致错误累积（滚雪球效应）。

LLM 的三个核心限制

1. 上下文窗口有限

LLM 的"记忆"完全依赖上下文。但有效上下文远小于标称值。

实测数据：

LLM 在 15% context 以内表现最好
40%-60% context 时开始出现幻觉
超过 80% context 时性能严重衰减

这意味着什么？如果 prompt 是 100K tokens，LLM 只能有效利用前 15K tokens。后面的内容基本被忽视。

2. 注意力机制的稀疏性

LLM 的注意力机制是稀疏的，关键信息容易被稀释。

例子：

在 prompt 中间插入一个重要的约束
但这个约束被大量的背景信息淹没
LLM 可能就忽视了这个约束

这就是为什么结构化的 prompt 比冗长的 prompt 更有效。

3. 概率性生成导致的不确定性

LLM 的生成是概率性的，不是确定性的。

同样的 prompt，多次运行可能得到不同的结果
有时候生成正确，有时候生成错误
这就是为什么需要验收标准和自动化检查

Coding Agent 的工作原理

理解了 LLM 的本质，再看 Coding Agent 就清楚了。

Agent Loop：模型调用 → 工具执行 → 结果反馈

用户输入 prompt
LLM 调用工具（如读文件、执行代码）
工具返回结果
把结果加到上下文中
LLM 继续生成下一步
重复 2-5，直到完成任务

这个循环的关键是：LLM 不是直接生成代码，而是通过工具调用来完成任务。

为什么 Agent 比直接生成代码更可靠？

可验证：工具执行的结果是确定的，可以验证
可纠正：如果工具执行出错，可以立即反馈给 LLM，让它纠正
可追溯：每一步都有记录，可以追溯问题

相比之下，直接生成代码就像"一次性生成"，如果出错就很难纠正。

为什么需要 Skill？

现在回到 Skill 的本质。

问题：LLM 的三个核心限制（上下文有限、注意力稀疏、概率性生成）意味着什么？

如果在 Prompt 中写了一个重要的规则，LLM 可能会忽视
如果在长对话中写了一个约束，LLM 可能会遗忘
如果依赖 LLM 自动遵守规则，结果往往不可靠

解决方案：用 Skill 把规则显式化。

Skill 不是 Prompt 的补充，而是规则的显式表达
Skill 在每个关键点都能被 LLM 看到和应用
Skill 本身可以被版本控制、演进、优化

例子：

规则：“所有函数都要有类型注解”
传统方式：在 Prompt 中写这个规则，希望 LLM 遵守
Skill 方式：创建一个 Skill，明确定义"什么样的代码才符合规范"，让 LLM 在每个生成点都能看到这个 Skill

会话间失忆与外部记录

Agent 没有持久记忆。每次对话都是从零开始。

问题：

第一个对话中，Agent 做了一个决策（比如"使用 Redis 作为缓存"）
第二个对话中，Agent 不知道这个决策，可能做出矛盾的决策
结果就是系统设计不一致

解决方案：

用外部文件记录决策（Skill、配置文件、项目信息文件）
每个对话开始时，Agent 读取这些文件
这样 Agent 就能"记住"之前的决策

例子：

项目信息.md：

缓存方案：Redis
数据库：PostgreSQL
部署方式：Docker

Agent 开始对话时，先读取这个文件，然后所有的代码生成都会遵守这些决策。

最佳实践总结

1. 短对话优于长对话

把复杂任务拆分成多个短对话
每个对话专注于一个子任务
用外部记录传递上下文

2. 结构化 Prompt 优于冗长 Prompt

用清晰的格式组织信息
把关键信息放在前面
用 Skill 而不是文字来表达规则

3. 验收标准 + 自动化检查

定义明确的验收标准
用工具自动检查
不符合就报错，让 Agent 纠正

4. 建立"记忆"机制

用 Skill 记录规范和陷阱
用配置文件记录决策
用知识库记录经验
让 Agent 能"记住"之前的工作

核心洞察

理解 LLM 和 Agent 的本质，才能设计出更好的工程系统。

LLM 的限制决定了需要短对话、结构化 prompt、自动化检查
Agent 的特性决定了需要外部记录、可验证的标准、Skill 系统
复利工程就是在这些限制和特性的基础上，建立的一套系统

构建和演进 Skill 系统的工具

官方 Skill Creator

https://github.com/anthropics/skills/tree/main

Claude 官方发布的开源仓库，提供了 Skill 的标准化结构和最佳实践。这是构建 Skill 系统的基础框架，定义了 Skill 的组织方式、文档格式、验收标准等。

Skill Evolution 管理

https://github.com/KKKKhazix/Khazix-Skills

一个优秀的开源 Skill Evolution 实现。结合 Compounding Engineering Skill，可以让 Skill 进化得更好。

为什么这个组合很强大：

skill-creator 提供了 Skill 的标准化结构
Skill Evolution 提供了 Skill 的持续演进机制
Compounding Engineering Skill 提供了经验沉淀的方法论
三者结合，形成了一个完整的 Skill 生态系统

演进流程：

用 skill-creator 创建新 Skill
在实际工作中使用 Skill
发现改进点时，用 Skill Evolution 管理器记录演进
用 Compounding Engineering 的方法论沉淀经验
更新 Skill，形成新版本
循环往复，Skill 越来越好

这就是复利工程的完整实现：从创建、使用、演进、沉淀，形成一个闭环。

附录：核心 Skill 源码

为了让读者更好地理解 Skill 系统的实际应用，这里附上三个核心 Skill 的完整源码。

Observation Tracker Skill

---
name: observation-tracker
description: 用于在 AI 编码任务中记录和保留发现的工作流。在任何编码任务中使用此 Skill，确保次要发现（潜在 bug、重构机会、缺失测试、代码异味、安全问题、性能问题）被捕获而不是因上下文限制而丢失。此 Skill 应在复杂任务开始时激活，并在任务完成前查阅。
---

# Observation Tracker

此 Skill 确保在编码任务中做出的有价值观察被捕获和保留，防止因上下文窗口限制而导致的知识丢失。

## 核心工作流

### 1. 初始化追踪

在任何复杂任务开始时，创建观察文件：

```bash
touch .observations.md

2. 立即记录发现

在工作期间注意到以下任何情况时，立即追加到 .observations.md：

与当前任务无关的潜在 bug
需要重构的代码
缺失的测试覆盖
安全问题
性能问题
文档缺口
技术债务
不清晰或令人困惑的代码

记录格式：

## [TIMESTAMP] [CATEGORY]
**File**: path/to/file.ext:line
**Priority**: HIGH | MEDIUM | LOW
**Description**: Brief description of the issue
**Suggested Action**: What should be done

3. 分类

使用这些标准分类：

BUG - 潜在 bug 或缺陷
REFACTOR - 代码改进机会
TEST - 缺失或不充分的测试
SECURITY - 安全问题
PERF - 性能问题
DOCS - 需要文档
DEBT - 技术债务
UNCLEAR - 需要澄清的令人困惑的代码

4. 任务结束审查

在完成任何任务之前：

读取 .observations.md
向用户总结所有未处理的观察
询问是否应立即处理或添加到待办事项

5. 输出格式

在任务结束时报告观察：

📋 观察总结
========================

在此任务期间，我注意到以下未处理的问题：

[高优先级]
• [文件:行] 描述 - 建议行动

[中优先级]
• [文件:行] 描述 - 建议行动

[低优先级]
• [文件:行] 描述 - 建议行动

是否希望：
1. 现在处理其中任何一个？
2. 为它们创建问题/工单？
3. 将它们添加到技术债务待办事项？

关键原则

先记录，后判断 - 捕获一切；过滤发生在审查时
低摩擦 - 记录应该只需几秒钟，而不是几分钟
上下文保留 - 包含足够的细节，以便稍后在没有原始上下文的情况下理解
不要静默丢弃 - 永远不要忽视发现；总是记录或报告
明确交接 - 用户决定如何处理观察，而不是 Agent

示例会话

用户：修复 auth.py 中的登录 bug

Agent：[创建 .observations.md]
Agent：[在修复登录 bug 时，注意到：]
  - 无关的 SQL 注入漏洞
  - 缺少登出的单元测试
  - 硬编码的超时值
Agent：[将所有三个记录到 .observations.md]
Agent：[修复登录 bug]
Agent：[在完成前报告观察总结]


### Compounding Engineering Skill

```markdown
---
name: compounding-engineering
description: 复利工程实践方法论。将每次工作（bug修复、代码审查、问题解决）转化为系统永久知识，使团队和AI代理能够持续受益。当需要：(1)将经验沉淀为 Skill 并纳入 skill-manager 管理，(2)让bug修复产生长期预防价值，(3)从代码审查中提取可复用模式，(4)建立标准化工作流程时使用此skill。
---

# Compounding Engineering 复利工程

核心理念：让每次工作都产生长期复利价值，而非一次性消耗。

## 1. 经验沉淀到 Skill 体系

将重复出现的问题、有效解决方案沉淀为 Skill，形成可管理、可演进的知识闭环：

### 创建 Skill
使用 `skill-creator` 创建领域专属 Skill：

.claude`/<skill-name>/`
├── SKILL.md           # 核心指导文档
├── evolution.json     # 演进记录（由 skill-evolution-manager 维护）
└── references/        # 补充参考资料

Skill 内容结构示例：

## 代码风格
- 使用 async/await 而非 Promise.then()
- 错误处理必须包含具体的错误类型

## 已知陷阱
- session 模块的 save() 方法是异步的，必须 await
- 不要在循环中调用 API，使用批量接口

## 成功模式
- 新增 API 端点时，参考 PR #241 的错误处理方式

纳入 skill-manager 管理

创建后 Skill 自动被 skill-manager 管理：

/skill-manager list - 查看所有 skills
/skill-manager check - 检查更新状态

持续演进 Skill

完成一次「长期价值修复」或「模式提取」后，使用 skill-evolution-manager 演进相关 Skill：

触发: /evolve 或 “把这个经验保存到 Skill 里”
流程: 经验复盘 → JSON 持久化(evolution.json) → 文档缝合(SKILL.md)
优势: 经验不会因 Skill 升级而丢失，跨版本保持

2. Bug 修复的长期价值

修复 bug 时执行以下检查清单：

Lint 规则：此类问题能否通过添加 lint 规则预防？
Skill 演进：是否应创建/演进相关 Skill 来记录此陷阱？（触发 /evolve）
回归测试：能否编写测试防止回归？
审查清单：代码审查清单是否需要更新？

真正的 bug 修复 = 让同类问题再也不会发生

3. 从代码审查提取模式

每次审查中指出问题或提出建议时考虑：

此反馈是否适用于未来的类似代码？
是否应成为项目编码规范？
Agent 能否在下次自动应用此改进？

如果答案是肯定的，立即记录。让审查意见成为系统永久知识。

4. 建立可复用工作流程

发现有效工作模式时进行沉淀：

## 工作流程：添加新的 API endpoint

1. 先编写接口测试（参考 tests/api/example.test.ts）
2. 实现端点，遵循 src/api/users.ts 的模式
3. 添加错误处理，使用 AppError 类
4. 更新 API 文档
5. 运行完整测试套件验证

下次执行类似任务时直接引用：“按照添加新 API endpoint 的工作流程来做”。

执行原则

即时记录：发现可沉淀内容时立即行动，不要等
具体引用：引用具体的 PR、文件、代码位置
持续迭代：文档随项目演进而更新
最小化重复：让每个问题只需要解决一次

Premature Completion Guard Skill

---
name: premature-completion-guard
description: 防止 Agent 在长对话或多次 compaction 后过早宣告任务完成。当执行复杂多阶段任务时触发，确保 Agent 对照原始计划检查进度，而非依赖可能被压缩的记忆。适用于：(1) 多阶段开发任务 (2) 长时间运行的会话 (3) 需要结构化进度追踪的复杂工作流
---

# 过早宣告完成防护

## 问题背景

Agent 在经历多次上下文压缩（compaction）后，可能错误地认为任务已完成，因为：
- 早期任务阶段的详细信息被压缩或丢失
- 记忆中只保留了"进展顺利"的模糊印象
- 缺乏对原始计划的结构化对照

## 核心机制

### 1. 计划外置存储

将完整计划保存在上下文之外的固定位置：

.claude/plans/
├── {project-name}-plan.md    # 原始完整计划
├── {project-name}-progress.md # 实时进度记录

计划文件必须包含：

所有阶段的明确定义
每个阶段的完成标准
依赖关系说明

2. 进度检查协议

在宣布任何阶段完成前，执行以下检查：

重读原始计划 - 从外置文件加载，不依赖记忆
逐项核对 - 对照完成标准逐条验证
更新进度文件 - 记录已完成项和未完成项
明确剩余工作 - 列出下一步具体任务

3. 完成声明规范

禁止使用模糊的完成声明：

❌ “任务完成了！”
❌ “基本完成，可以测试了”

必须使用结构化声明：

✅ “阶段 2/5 完成：用户认证模块。剩余：支付、通知、部署”
✅ “所有 5 个阶段已完成，对照 .claude/plans/project-plan.md 核实”

实施步骤

任务开始时

创建或确认计划文件存在于 .claude/plans/
初始化进度文件，所有项标记为未完成
在响应中明确当前处于哪个阶段

每个阶段结束时

检查清单：
□ 重读 .claude/plans/{project}-plan.md
□ 核对当前阶段的所有完成标准
□ 更新 .claude/plans/{project}-progress.md
□ 确认下一阶段的开始条件

宣布最终完成前

完整重读原始计划文件
逐阶段核对进度文件
验证所有完成标准都已满足
列出任何偏离原计划的变更

进度文件模板

# 项目进度追踪

原始计划: .claude/plans/{project}-plan.md
最后更新: {timestamp}

## 阶段状态

- [x] 阶段 1: {名称} - 完成于 {date}
- [ ] 阶段 2: {名称} - 进行中
- [ ] 阶段 3: {名称} - 未开始

## 当前阻塞

{任何阻塞项}

## 偏离记录

{与原计划的任何偏离}

自检触发条件

当出现以下信号时，强制执行完整进度检查：

准备说"完成"、“done”、“finished”
建议用户进行手动测试
对话超过 20 轮
感觉对早期工作记忆模糊

结语

复利工程不是一个技术，而是一种思维方式。

关键在于：把每一次工作都当作投资，而不是消耗。

第一次做某件事时，多花 20% 的时间沉淀经验
第二次做同样的事时，节省 30% 的时间
第三次、第四次…效率持续提升
最终，这件事可以自动化，完全不需要人工介入

这就是复利的威力。

在 AI 时代，这种思维方式变得更加重要。因为 AI 没有记忆，每次对话都是从零开始。只有通过 Skill 系统，才能让 AI "记住"经验，让知识永久积累。

开始建立复利工程体系吧。从第一个 Skill 开始，从第一次沉淀开始。