用途
Cavekit Writing 是一套编写「Cavekit 规格（kit）」的方法论，目标是让 AI 智能体能够有效消费这些规格。它规定了 kit 应当如何组织、如何表述需求、如何定义验收标准，以便智能体据此生成计划、实现代码并自动验证。
核心原则：描述 WHAT，而非 HOW
Kit 与实现无关，只定义系统必须做什么以及如何验证，绝不规定具体的框架、语言或架构。Cavekit 中的基本区分是：
- Kit = 必须为真的事实（与框架无关、持久、可移植）
- Plan = 如何构建（与框架相关，由 kit 派生）
- Code = 实现（由 plan 生成，依据 kit 验证）
实现无关带来的好处：可移植（同一 kit 可驱动不同框架的实现）、持久（可跨越技术迁移）、可测试（验收标准针对行为而非实现细节）、可复用（适用于绿地、重写和跨框架评估）。
示例：
- 不好的需求：「使用 React useState hook 管理表单状态」
- 好的需求：「表单状态在会话内的用户交互中保持。验收：输入值、离开页面再返回后，所有已输入值仍保留。」
每条需求都需要可测试的验收标准
这是 Cavekit 写作中最重要的规则。如果智能体无法自动验证某条需求，该需求就不会被满足。验证优先规则要求每条需求都回答：「自动化测试将如何验证这一点？」
弱标准与强标准对比：
- 「UI 应该好看」→「所有交互元素具有最小 44x44px 的触摸目标」
- 「系统应该快」→「在 100 并发用户下，API 响应 p95 在 200ms 内返回」
- 「优雅处理错误」→「网络失败时显示重试提示，采用指数退避（1s、2s、4s）」
- 「支持认证」→「有效凭据返回会话令牌；无效凭据返回 401 及错误消息」
验收标准应满足：可观察、确定性、可自动化、独立（不依赖主观判断）。格式示例：
**Acceptance Criteria:**
- [ ] {Action} results in {observable outcome}
- [ ] Given {precondition}, when {action}, then {result}
- [ ] {Metric} meets {threshold} under {conditions}
带索引的层级结构
Kit 必须组织为层级结构：一个索引文件链接到各领域子 kit。这实现了渐进式披露——智能体先读索引，再只加载与任务相关的子 kit。
索引模式：创建 cavekit-overview.md 作为入口，包含领域表格（领域、kit 文件、摘要）以及跨领域关注点（安全、性能预算、可访问性等）。层级化的理由：上下文窗口效率、并行工作、审查效率、显式交叉引用。
Kit 之间的交叉引用
相关 kit 必须相互链接，防止需求在领域边界处丢失。交叉引用模式包括：Depends on、Depended on by、Related。当某领域需求依赖另一领域输出、共享实体被多处使用、验证标准跨多个领域、或超出范围项属于另一 kit 范围时，应当交叉引用。
完整 Kit 格式模板
每个领域 kit 使用如下模板：
# Cavekit: {Domain Name}
## Scope
{一段话描述本规格覆盖的内容及其边界。}
## Requirements
### R1: {Requirement Name}
**Description:** {必须为真的事实——以行为而非实现表述。}
**Acceptance Criteria:**
- [ ] {可测试标准 1}
- [ ] {可测试标准 2}
- [ ] {可测试标准 3}
**Dependencies:** {依赖的其他规格/需求，或 "None"}
### R2: ...
## Out of Scope
{明确列出本 kit 不覆盖的内容。}
- {明确排除的内容及原因}
## Cross-References
- See also: cavekit-{related-domain}.md — {关联原因}
- Depends on: cavekit-{dependency}.md R{N} — {所需内容}
- Depended on by: cavekit-{dependent}.md R{N} — {依赖本 kit 的内容}
模板规则：需求按 R1、R2、R3 顺序编号（智能体按 ID 引用）；每条需求都要有验收标准，无例外；Out of Scope 为必填；Cross-References 为必填（即使写 None）；Scope 为一段话。
绿地模式：参考资料 → Kit
从零构建时，先有参考资料，再从中派生 kit。流程：将参考资料放入 context/refs/；运行 kit 生成，智能体读取所有 refs 并分解为领域；产出 cavekit-overview.md 索引及各领域 cavekit-{domain}.md 及交叉引用；人工审查完整性与正确性；迭代完善。绿地流水线的首个提示（通常为 001-generate-kits-from-refs.md）应读取 refs、分解领域、按模板生成 kit、创建索引、交叉引用。
重写模式：旧代码 → 参考文档 → Kit
重写现有系统时，现有代码成为参考资料，但绝不直接从旧代码到新代码——始终先提取 kit。流程：智能体探索现有代码库并生成参考文档（捕获当前行为、API、数据模型、UI 模式）；从参考文档生成 kit（实现无关需求）；依据现有代码验证 kit（确认验收标准匹配当前行为）；再进入正常流程，由 kit 驱动新实现。重写通常需要更多提示：001 从旧代码生成参考资料；002 从参考 + 功能范围生成 kit；003 依据现有代码库验证 kit；004+ 计划与实现。与绿地的关键区别是第 003 步在开始构建前验证 kit 确实描述了旧系统的行为。
Cavekit 压缩
当实现跟踪或 kit 文件超过约 500 行时，智能体处理效率下降。压缩时机：实现跟踪文件超过 500 行；kit 文件混杂大量已解决/已完成需求与活跃需求；智能体在历史信息上耗费过多上下文。压缩方法：识别已解决内容（已完成任务、已解决问题、归档的死胡同）；将移除内容归档到单独文件（如 impl/archive/impl-domain-v1.md）；在压缩文件中保留所有活跃/进行中任务、所有未解决问题、近期死胡同（最近 2-3 次会话）、当前测试健康状态、活跃交叉引用；目标为活跃文件低于 500 行。压缩规则：绝不删除信息——移动到归档。
差距分析
差距分析比较已构建内容与预期内容，识别 kit、计划或验证的不足。方法：读取 kit（预期行为）与实现跟踪（已构建内容）；对每条 kit 需求检查验收标准是否满足；分类为 Complete（全部通过）、Partial（部分通过）、Missing（完全未实现）、Over-built（实现超出 kit，可能表明 kit 有缺口）；报告差距（哪个 kit、哪条标准、缺什么）；将差距反馈到修订——必要时更新 kit，再重新实现。差距分析应持续进行：每次实现迭代后、开始新会话前、收敛停滞时。
与其他技能的集成
- 草稿阶段的协作设计：/ck:sketch 在交互模式下嵌入头脑风暴原则，先探索项目上下文、逐一提问、提出 2-3 种领域分解方案、逐节呈现设计、设计获批后再生成 kit，并经过自动审查循环（最多 3 次迭代）与用户审查门。视觉项目可使用基于浏览器的视觉伴侣。YAGNI 执行：主动剥离用户未要求的需求。
- 与 ck:design-system：当项目根存在 DESIGN.md 时，UI 领域 kit 的验收标准应引用设计令牌，形成可追溯链：DESIGN.md → kit 验收标准 → 计划任务 → 实现。不要将 DESIGN.md 内容复制进 kit，只按章节/令牌名引用。
- 与 ck:validation-first：每条验收标准必须映射到至少一个验证门（构建、单元测试、E2E/集成、性能、启动验证、人工审查）。
- 与 ck:context-architecture：kit 位于 context/kits/ 目录。
- 与 ck:impl-tracking：实现进度记录在 context/impl/ 文档中，死胡同应记录以防未来智能体重试失败方法。
常见错误
- 编写实现特定的 kit（如指定 PostgreSQL 表结构）。
- 验收标准含糊（如「系统正确处理错误」）。
- 缺少 Out of Scope——智能体会过度构建或做假设。
- 没有交叉引用——领域并非孤立存在。
- 单体 kit——单个 1000 行文件破坏渐进式披露。
总结
为 AI 智能体编写 kit 遵循以下规则：WHAT 而非 HOW；每条需求都有可测试验收标准；带索引的层级结构；交叉引用；显式范围（Out of Scope 防止过度构建）；过大时压缩（归档已解决内容，活跃文件低于 500 行）；活文档——kit 通过修订随差距发现而演进。