cavekit-methodology

Cavekit 方法论

核心原则：先明确规范，再开始构建

在告诉 Agent 如何构建之前，务必先定义你想要什么。先完成一个 cavekit 阶段——绝不要从原始需求直接跳到实现。

Cavekit 是一种利用 AI 编码 Agent 构建软件的方法论，将 kits 置于开发流程的核心——代码由 kits 派生，而不是反过来。无论是从头开始，还是对现有系统进行现代化改造，原则都相同：

• 全新项目： 参考资料 → kits → 代码
• 重写： 旧代码 → kits → 新代码

在这两种情况下，kits 都会成为一份持续演进的契约，供 Agent 使用，以便持续构建、验证和完善应用。

为什么 Kits 是一等公民

属性	优势
结构化	组织成可导航的树形结构，使 Agent 能够只加载所需内容
便于人类阅读	工程师可以从比代码更高的层次审查需求
与技术栈无关	不与任何单一框架或语言绑定
可独立演进	无需改动实现即可完善 kits
可验证	每项需求都包含 Agent 可以检查的验收标准

关键洞见： 编写完善且具有严格验证机制的 kits，能让应用可复现——任何 Agent 都可以仅凭 kits 重建应用。可以把这看作持续再生成。

---

与科学方法的类比

大模型本质上具有非确定性——就像进行实验一样，每次单独调用都可能产生不同结果。但通过正确的方法——明确假设、控制条件并重复试验——我们可以从随机过程中提取可靠、可复现的结果。

Cavekit 将科学方法应用于软件构建——提出假设、测试、观察、完善。

层次	类比	作用
大模型调用	单次实验	每次运行都可能产生不同结果；没有任何单一输出具有权威性
Kits	假设	定义你预期观察到的内容——预测的行为
验证关卡	控制条件	通过限定有效结果的判定标准，确保可复现性
收敛循环	重复试验	通过逐轮执行建立统计置信度
实现跟踪	实验记录本	记录尝试过什么、哪些有效、哪些失败
修订	修订假设	当结果与预期矛盾时，在上游更新理论

最终成果：在概率生成之上构建一套严谨、可重复的工程流程。

---

Hunt 的 5 个阶段

Hunt 是一个四阶段生命周期：Sketch、Map、Make、Check。每个阶段都有专门的提示词来推动其执行。

阶段	输入	输出	AI 角色	人类角色
Draft	源材料、领域知识、现有系统	与实现无关的 kits	提取需求、整理知识结构	验证 kits 是否准确表达意图
Architect	Kits + 框架研究	特定于框架的实现计划	设计架构、分解工作、安排步骤顺序	批准架构选择
Build	计划 + kits	可运行的代码 + 测试 + 跟踪文档	编写代码、运行测试、对照 kits 检查	留意偏差和阻碍
Inspect	验证失败项、缺漏、手动修复	通过修订更新的 kits/计划	找出根本原因，将修复向上游传递	评估结果、确定优先级
Monitor	运行中的应用、git 历史记录	问题、异常、进度报告	扫描回归问题、呈现指标	解读报告、指导后续步骤

阶段转换

每个阶段都有必须满足的门槛条件，才能进入下一阶段：

1. Draft → Architect： 所有领域都已创建套件，并附有可测试的验收标准。人工已审核其完整性。
2. Architect → Build： 计划引用套件、定义实现顺序，并包含测试策略。架构决策已通过验证。
3. Build → Inspect： 代码构建成功，测试达到当前覆盖率要求，实施跟踪信息保持最新。
4. Inspect → Monitor： 检测到收敛（迭代间的变更逐渐减少）。剩余变更都很小。
5. Monitor → Draft（循环）： 发现差距或确定了新需求。修订套件并重新启动循环。

Inspect 阶段由人工担任审核者和决策者，而非亲自编写代码。你负责监控流程、按需要求修改，并对套件和提示词进行系统性改进。

完整的 Hunt 阶段参考，请参阅 references/hunt-phases.md。

---

决策矩阵：何时使用 Cavekit

完整版 Cavekit

当项目范围较大、需求不断变化，或需要 Agent 自主执行时使用。

指标	阈值
代码库大小	50 个以上源文件
需求	不断变化，涉及多个领域
Agent 协作	多 Agent 或多提示词流水线
环境	生产环境、安全敏感环境、既有代码库
团队结构	多团队或跨团队
执行模式	长时间自主工作（隔夜、无人值守）

你将获得： 完整的 Hunt 生命周期、包含套件/计划/实施跟踪的上下文目录、提示词流水线、收敛循环、修订和验证门槛。

轻量版 Cavekit

当项目范围适中时使用——复杂度高于临时处理，但不值得采用完整流水线。

指标	阈值
代码库大小	5–50 个文件
需求	大多明确，范围集中
Agent 协作	单个 Agent，可能配有子 Agent
执行模式	交互式，偶尔进行迭代循环

操作方式：

1. 编写聚焦的 context/kits/cavekit-task.md，记录需求
2. 添加 context/plans/plan-task.md，安排实现顺序
3. 跳过完整 Hunt——仅根据计划运行迭代循环

这是“Cavekit 的基础配置”——无需完整多阶段流水线的开销，即可获得大部分收益。

跳过 Cavekit

任务非常小巧时使用。

指标	阈值
代码库大小	少于 5 个文件
任务类型	一次性工具、简单错误修复、探索性原型
实现规模	可在单次 Agent 会话中轻松完成，无需外部参考

经验法则： 如果整个任务能轻松放进一个上下文窗口，使用完整 Cavekit 带来的开销就会超过收益。

演进路径

即使项目很小，也可以从轻量版 Cavekit 开始。如果范围扩大，你已经具备了扩展所需的结构。与其从一开始就建立 cavekit 目录，不如等大型代码库成形后再将套件补充进去，后者要困难得多。

---

CI 流水线类比

Cavekit 类似于一个构建流水线——每个阶段都会将输入转换为经过验证的输出，并通过反馈循环将修正向上游传递：

Traditional CI/CD:
  Code → Build → Test → Deploy

Cavekit AI Pipeline:
  Cavekit Change
    → Generate Plans (iteration loop)
    → Generate Implementation (iteration loop)
    → Validate (Tests + Review)
    → Human Audit (Monitor & Steer)
    → [Gap Found]
    → Revise
    → Cavekit Change (cycle repeats)

每个阶段都可以作为迭代循环运行——反复执行同一提示词，直到输出趋于稳定。迭代循环能将非确定性的大模型输出转化为可预测、经过验证的软件。

迭代循环

迭代循环是 Cavekit 中的基本执行单元。针对同一代码库反复执行相同的提示词，直到各轮结果之间的差异趋近于零。

机制：

1. 针对当前代码库执行提示词
2. Agent 检查 git 历史记录和跟踪文档，了解已经完成的工作
3. Agent 应用更改并提交进展
4. 返回第 1 步

收敛信号： 连续多轮修改量逐渐减少——每次 diff 都比上一次更小，直到只剩下外观上的更改。关注的是收益递减，而非绝对归零。

如果循环无法稳定下来，问题出在上游——应修复输入（规格、验证、协调），而不是增加迭代次数。

如果各轮之间的 diff 没有缩小：

• Kits 含糊不清（Agent 每次的理解都不一样）
• 验证标准过于宽松（Agent 无法确认结果是否正确）
• 多个 Agent 相互覆盖彼此的工作（所有权边界不明确）

---

与子技能的交叉引用

Cavekit 由相互协作的技术组成。此方法论技能是索引——以下每项子技能都是独立的，但会交叉引用其他技能。

基础技能

技能	用途	使用时机
ck:cavekit-writing	编写与实现无关且具有可测试验收标准的 kits	起草阶段——始终是第一步
ck:context-architecture	组织上下文以便逐步披露	项目设置和持续维护
ck:impl-tracking	跟踪实现进度、死胡同和测试健康状况	构建和检查阶段
ck:validation-first	设计 Agent 可执行的验证关卡	所有阶段——验证是持续进行的

流水线技能

技能	用途	使用时机
ck:prompt-pipeline	为 Hunt 设计带编号的提示词流水线	设置自动化
ck:revision	将 Bug 追溯到 kits 并从源头修复	检查阶段——发现缺漏之后
cavekit:brownfield-adoption	在现有代码库中采用 Cavekit	在旧项目中开始使用 Cavekit

高级技能

技能	用途	使用时机
ck:peer-review	使用第二个 Agent 审视第一个 Agent 的工作	质量关卡、架构审查
cavekit:speculative-pipeline	错开流水线阶段以实现并行处理	优化较长的流水线
ck:convergence-monitoring	检测收敛还是遇到上限	监控迭代循环
cavekit:documentation-inversion	将文档转换为 Agent 可使用的技能	库/模块文档

与现有技能的集成

Cavekit 与现有技能协同工作，而非取而代之：

现有技能	Cavekit 集成
superpowers:brainstorming	在生成 cavekit 时用于探索需求
superpowers:writing-plans	在生成计划时用于结构化规划
superpowers:test-driven-development	Cavekit 内的 TDD：cavekit 验收标准将转化为失败测试
superpowers:verification-before-completion	在每个阶段用于关卡验证
superpowers:executing-plans	在实现阶段使用
superpowers:dispatching-parallel-agents	用于协调 Agent 团队

---

快速开始

新项目（Greenfield）

1. 设置上下文目录：

   context/
   ├── refs/           # Source materials (PRDs, language specs, research)
   ├── kits/     # Implementation-agnostic kits
   ├── plans/          # Framework-specific implementation plans
   ├── impl/           # Living implementation tracking
   └── prompts/        # Hunt pipeline prompts
   

2. 根据参考材料编写 kits（参见 ck:cavekit-writing）

3. 根据 kits 生成计划（参见 ck:prompt-pipeline）

4. 使用验证关卡进行实现（参见 ck:validation-first）

5. 在实现文档中跟踪进度（参见 ck:impl-tracking）

6. 迭代——发现缺漏时，修订 kits（参见 ck:revision）

对于现有项目（存量项目）

1. 设置上下文目录（结构同上）
2. 将现有代码库指定为参考资料
3. 从代码生成套件（参见 cavekit:brownfield-adoption）
4. 验证套件是否符合实际行为——针对生成的套件运行测试
5. 按常规流程开展 Hunt——后续变更先经过套件

---

总结

Cavekit 不是工具，而是一套方法论。核心循环很简单：

1. 描述你想要什么（包含可测试标准的套件）
2. 让 Agent 来构建（计划 → 实现 → 验证）
3. 修改套件，而不是代码（修订）
4. 重复，直到收敛（迭代循环）

你对 Agent 的约束越精确，它们就越有能力——清晰的套件、自动化验证和结构化迭代循环，让它们能够以越来越高的自主性运行。这些都无法取代软件工程师。你的架构判断力、编写精确套件的能力，以及对“完成”的直觉，都是让整个系统运转起来的关键输入。Cavekit 是一种力量倍增器：将一位工程师清晰的思路，扩展到整个实现流程中。