cavekit-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cavekit Writing

Cavekit 编写指南

Core Principle: Kits Describe WHAT, Not HOW

核心原则：套件描述目标（WHAT），而非实现方式（HOW）

Kits are implementation-agnostic. They define what the system must do and how to verify it, but never prescribe a specific framework, language, or architecture.

This is the fundamental distinction in Cavekit:

Kits = WHAT must be true (framework-agnostic, durable, portable)
Plans = HOW to build it (framework-specific, derived from kits)
Code = the implementation (generated from plans, validated against kits)

套件是与实现无关的。它们定义系统必须完成的目标以及验证方式，但绝不指定具体框架、语言或架构。

这是Cavekit的核心区别：

Kits（套件） = 必须实现的目标（与框架无关、持久、可移植）
Plans（方案） = 实现目标的方式（与框架相关，基于套件推导）
Code（代码） = 具体实现（由方案生成，依据套件验证）

Why Implementation-Agnostic?

为什么要与实现无关？

When kits avoid prescribing HOW, they become:

Portable — the same kits can drive implementations in different frameworks
Durable — kits survive technology migrations
Testable — acceptance criteria are about behavior, not implementation details
Reusable — the same kits work for greenfield, rewrites, and cross-framework evaluation

Bad cavekit requirement: "Use React useState hook to manage form state" Good cavekit requirement: "Form state persists across user interactions within a session. Acceptance: entering values, navigating away, and returning preserves all entered values."

当套件不指定实现方式时，它们将具备以下特性：

可移植性 — 同一套件可驱动不同框架下的实现
持久性 — 套件可在技术迁移中保留
可测试性 — 验收标准聚焦于行为，而非实现细节
可复用性 — 同一套件适用于全新项目、系统重写以及跨框架评估

错误的Cavekit需求示例： "使用React useState钩子管理表单状态" 正确的Cavekit需求示例： "表单状态在会话内的用户交互中保持持久。验收标准：输入值后导航离开再返回，所有输入值均被保留。"

Every Requirement Needs Testable Acceptance Criteria

每项需求都需要可测试的验收标准

This is the single most important rule in Cavekit writing. If an agent cannot automatically validate a requirement, that requirement will not be met.

这是Cavekit编写中最重要的规则。如果Agent无法自动验证某项需求，该需求将无法被满足。

The Validation-First Rule

验证优先规则

Every requirement must answer: "How would an automated test verify this?"

Weak Criterion	Strong Criterion
"UI should look good"	"All interactive elements have minimum 44x44px touch targets"
"System should be fast"	"API responses return within 200ms at p95 under 100 concurrent users"
"Handle errors gracefully"	"Network failures display a retry prompt with exponential backoff (1s, 2s, 4s)"
"Support authentication"	"Valid credentials return a session token; invalid credentials return 401 with error message"

每项需求必须回答：“自动化测试如何验证这一点？”

模糊标准	明确标准
"UI应美观"	"所有交互元素的触摸目标最小尺寸为44x44px"
"系统应快速"	"在100个并发用户下，95%的API响应时间在200ms以内"
"优雅处理错误"	"网络故障时显示带指数退避（1s、2s、4s）的重试提示"
"支持身份验证"	"有效凭证返回会话令牌；无效凭证返回401错误及提示信息"

Acceptance Criteria Format

验收标准格式

Each criterion should be:

Observable — can be checked by reading output, UI state, or logs
Deterministic — same input always produces same pass/fail result
Automatable — an agent can write a test that checks this
Independent — does not depend on subjective judgment

markdown

**Acceptance Criteria:**
- [ ] {Action} results in {observable outcome}
- [ ] Given {precondition}, when {action}, then {result}
- [ ] {Metric} meets {threshold} under {conditions}

每条标准应具备以下特性：

可观测 — 可通过读取输出、UI状态或日志进行检查
确定性 — 相同输入始终产生相同的通过/失败结果
可自动化 — Agent可编写测试用例进行验证
独立性 — 不依赖主观判断

markdown

**验收标准：**
- [ ] {操作} 产生 {可观测结果}
- [ ] 给定 {前置条件}，当执行 {操作} 时，得到 {结果}
- [ ] {指标} 在 {条件} 下达到 {阈值}

Hierarchical Structure with Index

带索引的层级结构

Kits must be organized as a hierarchy — one index file linking to domain-specific sub-kits. This enables progressive disclosure: agents read the index first, then only the sub-kits relevant to their task.

套件必须按层级组织——一个索引文件链接到特定领域的子套件。这支持渐进式披露：Agent先读取索引，再仅加载与任务相关的子套件。

The Cavekit Index Pattern

Cavekit索引模式

Create a

cavekit-overview.md

as the entry point:

markdown

undefined

创建

cavekit-overview.md

作为入口文件：

markdown

undefined

Cavekit Overview

Cavekit 概览

Domains

领域

Domain	Cavekit File	Summary
Authentication	cavekit-auth.md	User registration, login, session management, OAuth
Data Models	cavekit-data-models.md	Core entities, relationships, validation rules
API	cavekit-api.md	REST endpoints, request/response formats, error handling
UI Components	cavekit-ui-components.md	Shared components, accessibility, responsive behavior
Notifications	cavekit-notifications.md	Email, push, in-app notification delivery

领域	Cavekit文件	摘要
身份验证	cavekit-auth.md	用户注册、登录、会话管理、OAuth
数据模型	cavekit-data-models.md	核心实体、关系、验证规则
API	cavekit-api.md	REST端点、请求/响应格式、错误处理
UI组件	cavekit-ui-components.md	共享组件、可访问性、响应式行为
通知	cavekit-notifications.md	邮件、推送、应用内通知投递

Cross-Cutting Concerns

跨领域关注点

Security requirements: see cavekit-auth.md R3, cavekit-api.md R7
Performance budgets: see cavekit-api.md R12, cavekit-ui-components.md R5
Accessibility: see cavekit-ui-components.md R8-R10

undefined

安全需求：参见cavekit-auth.md R3、cavekit-api.md R7
性能预算：参见cavekit-api.md R12、cavekit-ui-components.md R5
可访问性：参见cavekit-ui-components.md R8-R10

undefined

Why Hierarchical?

为什么采用层级结构？

Context window efficiency — agents load only the domains they need
Parallel work — different agents can own different spec domains
Review efficiency — humans can review domain-by-domain
Cross-referencing — domains link to each other explicitly

上下文窗口效率 — Agent仅加载所需领域的内容
并行工作 — 不同Agent可负责不同的规格领域
评审效率 — 人员可按领域逐一评审
交叉引用 — 领域间可明确相互链接

Cross-Referencing Between Kits

套件间的交叉引用

Related kits must link to each other. Cross-references prevent requirements from being lost at domain boundaries.

相关套件必须相互链接。交叉引用可避免需求在领域边界处丢失。

Cross-Reference Patterns

交叉引用模式

markdown

undefined

markdown

undefined

Cross-References

交叉引用

Depends on: cavekit-auth.md R1 (session tokens required for API access)
Depended on by: cavekit-notifications.md R4 (uses user preferences from this cavekit)
Related: cavekit-ui-components.md R6 (error display components used by this domain)

undefined

依赖于： cavekit-auth.md R1（API访问需会话令牌）
被依赖于： cavekit-notifications.md R4（使用本套件中的用户偏好设置）
相关： cavekit-ui-components.md R6（本领域使用的错误展示组件）

undefined

When to Cross-Reference

何时进行交叉引用

When one domain's requirement depends on another domain's output
When shared entities are defined in one cavekit but used in many
When validation criteria span multiple domains
When out-of-scope items are in-scope for another cavekit

当一个领域的需求依赖于另一个领域的输出时
当共享实体在一个套件中定义但在多个套件中使用时
当验证标准跨多个领域时
当某个套件的范围外内容属于另一个套件的范围时

Full Cavekit Format Template

完整Cavekit格式模板

Use this template for every domain cavekit:

markdown

undefined

为每个领域的Cavekit使用以下模板：

markdown

undefined

Cavekit: {Domain Name}

Cavekit: {领域名称}

Scope

范围

{One paragraph describing what this spec covers and its boundaries.}

{一段文字描述本规格涵盖的内容及边界。}

Requirements

需求

R1: {Requirement Name}

R1: {需求名称}

Description: {What must be true — stated in terms of behavior, not implementation.} Acceptance Criteria:

{Testable criterion 1}
{Testable criterion 2}
{Testable criterion 3} Dependencies: {Other specs/requirements this depends on, or "None"}

描述： {必须实现的目标——以行为而非实现方式表述。} 验收标准：

{可测试标准1}
{可测试标准2}
{可测试标准3} 依赖项： {本需求依赖的其他规格/需求，或“无”}

R2: {Requirement Name}

R2: {需求名称}

Description: {What must be true} Acceptance Criteria:

{Testable criterion 1}
{Testable criterion 2} Dependencies: {Dependencies}

描述： {必须实现的目标} 验收标准：

{可测试标准1}
{可测试标准2} 依赖项： {依赖项}

R3: ...

Out of Scope

范围外内容

{Explicit list of things this cavekit does NOT cover. This is critical — it prevents agents from over-building and clarifies domain boundaries.}

{Thing explicitly excluded and why}
{Another exclusion}

{明确列出本Cavekit不涵盖的内容。这一点至关重要——可防止Agent过度构建并明确领域边界。}

{明确排除的内容及原因}
{另一项排除内容}

Cross-References

交叉引用

See also: cavekit-{related-domain}.md — {why it is related}
Depends on: cavekit-{dependency}.md R{N} — {what is needed}
Depended on by: cavekit-{dependent}.md R{N} — {what depends on this}

undefined

另请参见：cavekit-{相关领域}.md — {关联原因}
依赖于：cavekit-{依赖领域}.md R{N} — {所需内容}
被依赖于：cavekit-{依赖领域}.md R{N} — {依赖本套件的内容}

undefined

Template Rules

模板规则

Number requirements sequentially (R1, R2, R3...) — agents reference them by ID
Every requirement gets acceptance criteria — no exceptions
Out of Scope is mandatory — explicit exclusions prevent scope creep
Cross-References section is mandatory — even if it says "None"
Scope section is one paragraph — concise boundary description

需求按顺序编号（R1、R2、R3...）—— Agent通过ID引用需求
每项需求都需包含验收标准 — 无例外
范围外内容为必填项 — 明确排除内容可防止范围蔓延
交叉引用部分为必填项 — 即使标注“无”
范围部分为一段文字 — 简洁描述边界

Greenfield Pattern: Reference Material → Kits

全新项目模式：参考资料 → 套件

When building from scratch, you start with reference materials and derive kits from them.

从零开始构建时，先从参考资料入手，再从中推导套件。

Flow

流程

context/refs/              context/kits/
├── prd.md          →      ├── cavekit-overview.md
├── design-doc.md   →      ├── cavekit-auth.md
├── api-draft.md    →      ├── cavekit-api.md
└── research/       →      ├── cavekit-data-models.md
    └── ...         →      └── cavekit-ui.md

context/refs/              context/kits/
├── prd.md          →      ├── cavekit-overview.md
├── design-doc.md   →      ├── cavekit-auth.md
├── api-draft.md    →      ├── cavekit-api.md
└── research/       →      ├── cavekit-data-models.md
    └── ...         →      └── cavekit-ui.md

Process

步骤

Place all reference materials in
```
context/refs/
```
Run cavekit generation — agent reads all refs, decomposes into domains
Agent produces:
- ```
cavekit-overview.md
```
  — index with domain summaries
- One
```
cavekit-{domain}.md
```
  per identified domain
- Cross-references between related domains
Human reviews kits for completeness and correctness
Iterate — refine kits based on review feedback

将所有参考资料放入
```
context/refs/
```
运行Cavekit生成 — Agent读取所有参考资料，分解为不同领域
Agent生成：
- ```
cavekit-overview.md
```
  — 带领域摘要的索引
- 每个已识别领域对应一个
```
cavekit-{domain}.md
```
  文件
- 相关套件间的交叉引用
人员评审 套件的完整性与正确性
迭代 — 根据评审反馈优化套件

Greenfield Prompt Pattern

全新项目提示词模式

The first prompt in a greenfield pipeline (typically

001-generate-kits-from-refs.md

) should:

Read all files in
```
context/refs/
```
Decompose reference material into domains
Generate kits following the template above
Create
```
cavekit-overview.md
```
as the index
Cross-reference related kits

全新项目流程中的第一个提示词（通常为

001-generate-kits-from-refs.md

）应：

读取
```
context/refs/
```
中的所有文件
将参考资料分解为不同领域
按照上述模板生成套件
创建
```
cavekit-overview.md
```
作为索引
为相关套件添加交叉引用

Rewrite Pattern: Old Code → Reference Docs → Kits

重写模式：旧代码 → 参考文档 → 套件

When rewriting an existing system, the existing code becomes your reference material. But you never go directly from old code to new code — you always extract kits first.

重写现有系统时，现有代码即为参考资料。但绝不能直接从旧代码过渡到新代码——必须先提取套件。

Flow

流程

Existing codebase          context/refs/              context/kits/
├── src/            →      ├── ref-apis.md      →     ├── cavekit-overview.md
├── tests/          →      ├── ref-data-models.md →   ├── cavekit-auth.md
└── docs/           →      ├── ref-ui-components.md →  ├── cavekit-api.md
                           └── ref-architecture.md →   └── cavekit-data.md

现有代码库          context/refs/              context/kits/
├── src/            →      ├── ref-apis.md      →     ├── cavekit-overview.md
├── tests/          →      ├── ref-data-models.md →   ├── cavekit-auth.md
└── docs/           →      ├── ref-ui-components.md →  ├── cavekit-api.md
                           └── ref-architecture.md →   └── cavekit-data.md

Process

步骤

Agent explores the existing codebase and generates reference documents
Reference docs capture the current system's behavior, APIs, data models, and UI patterns
Agent generates kits from reference docs — implementation-agnostic requirements
Validate kits against existing code — verify acceptance criteria match current behavior
Proceed with normal Hunt — kits drive the new implementation

Agent探索现有代码库并生成参考文档
参考文档记录 当前系统的行为、API、数据模型及UI模式
Agent根据参考文档生成套件 — 与实现无关的需求
验证套件与现有代码的一致性 — 确认验收标准与当前行为匹配
按常规流程推进 — 套件驱动新实现

Rewrite Prompt Pattern

重写提示词模式

Rewrites typically use more prompts because of the reverse-engineering step:

```
001
```
: Generate reference materials from old code
```
002
```
: Generate kits from references + feature scope
```
003
```
: Validate kits against existing codebase
```
004+
```
: Plans and implementation

The key difference from greenfield: step 003 validates that your kits actually describe what the old system does, before you start building the new one.

重写通常需要更多提示词，因为包含逆向工程步骤：

```
001
```
：从旧代码生成参考资料
```
002
```
：根据参考资料和功能范围生成套件
```
003
```
：验证套件与现有代码库的一致性
```
004+
```
：生成方案与实现

与全新项目的关键区别：在开始构建新系统前，步骤003需验证套件是否准确描述了旧系统的行为。

Cavekit Compaction

Cavekit压缩

When implementation tracking or cavekit files grow beyond approximately 500 lines, they become unwieldy for agents to process efficiently. Spec compaction compresses large files while preserving active context.

当实现跟踪或Cavekit文件超过约500行时，Agent将难以高效处理。规格压缩可在保留活跃上下文的同时压缩大文件。

When to Compact

何时压缩

Implementation tracking file exceeds 500 lines
Cavekit file has many resolved/completed requirements mixed with active ones
Agent is spending too much context window on historical information

实现跟踪文件超过500行
Cavekit文件中混合了大量已完成/已解决的需求与活跃需求
Agent在历史信息上消耗过多上下文窗口

How to Compact

如何压缩

Identify resolved content: completed tasks, resolved issues, archived dead ends
Archive removed content to a separate file (e.g.,
```
impl/archive/impl-domain-v1.md
```
)
Preserve in the compacted file:
- All active/in-progress tasks
- All open issues
- Recent dead ends (last 2-3 sessions)
- Current test health status
- Active cross-references
Target: under 500 lines in the active file

识别已解决内容： 已完成任务、已解决问题、已归档的失败尝试
将移除的内容归档到单独文件中（例如
```
impl/archive/impl-domain-v1.md
```
）
在压缩后的文件中保留：
- 所有活跃/进行中的任务
- 所有未解决的问题
- 近期的失败尝试（最近2-3个会话）
- 当前测试健康状态
- 活跃的交叉引用
目标： 活跃文件控制在500行以内

Compaction Rule

压缩规则

Never delete information — move it to an archive. Agents can still find archived context if needed, but it will not consume context window during normal operations.

绝不删除信息——将其移至归档文件。Agent仍可在需要时查找归档上下文，但在常规操作中不会消耗上下文窗口。

Gap Analysis

差距分析

Gap analysis compares what was built against what was intended, identifying where kits, plans, or validation fell short.

差距分析对比已构建内容与预期内容，找出套件、方案或验证环节的不足。

How to Perform Gap Analysis

如何执行差距分析

Read kits (intended behavior) and implementation tracking (what was built)
For each cavekit requirement, check if acceptance criteria are satisfied
Classify each requirement:

Status	Meaning
Complete	All acceptance criteria pass
Partial	Some criteria pass, others do not
Missing	Requirement not implemented at all
Over-built	Implementation exceeds cavekit (may indicate cavekit gap)

Report gaps with: which cavekit, which criterion, what is missing
Feed gaps into revision — update kits if needed, then re-implement

读取套件（预期行为）和实现跟踪（已构建内容）
针对每个Cavekit需求，检查验收标准是否满足
对每个需求进行分类：

状态	含义
已完成	所有验收标准通过
部分完成	部分标准通过，其他未通过
缺失	需求完全未实现
过度构建	实现超出Cavekit范围（可能表明Cavekit存在漏洞）

报告差距，包含：所属Cavekit、具体标准、缺失内容
将差距反馈至修订环节 — 必要时更新套件，然后重新实现

Gap Analysis as Feedback

作为反馈机制的差距分析

Gap analysis is not a one-time activity. Run it:

After each implementation iteration
Before starting a new session (to prioritize work)
When convergence stalls (to identify what is blocking progress)

差距分析并非一次性活动。在以下场景执行：

每次实现迭代后
开始新会话前（用于优先级排序）
当收敛停滞时（用于识别阻碍因素）

Integration with Other Skills

与其他技能的集成

Collaborative Design in the Draft Phase

草稿阶段的协作设计

The Draft phase (

/ck:sketch

) now embeds brainstorming principles directly. When running in interactive mode (no arguments), the drafter follows a collaborative design process before generating any files:

Explore project context — check existing files, docs, commits before asking questions
Ask clarifying questions one at a time — understand purpose, constraints, success criteria
Propose 2-3 domain decomposition approaches — with tradeoffs and a recommendation
Present the design incrementally — section by section, get approval per domain
Generate kits only after design approval — formalize with acceptance criteria
Cavekit review loop — automated reviewer checks quality, up to 3 iterations
User review gate — explicit approval before transitioning to Architect phase

This process applies to EVERY project regardless of perceived simplicity. The design can be short for simple projects, but it must happen.

Visual companion: For projects involving visual elements (UI, architecture diagrams), the Draft phase can use a browser-based visual companion to show mockups and diagrams during the design conversation. See

references/visual-companion.md

YAGNI enforcement: During the design conversation and cavekit generation, actively strip requirements the user did not ask for. Smaller kits are better kits.

草稿阶段（

/ck:sketch

）现已直接嵌入头脑风暴原则。在交互模式下（无参数），起草者在生成任何文件前会遵循协作设计流程：

探索项目上下文 — 在提问前检查现有文件、文档、提交记录
逐个提出澄清问题 — 理解目标、约束、成功标准
提出2-3种领域分解方案 — 说明权衡并给出推荐
逐步展示设计 — 逐部分展示，按领域获得批准
仅在设计获批后生成套件 — 用验收标准正式规范
Cavekit评审循环 — 自动化评审器检查质量，最多迭代3次
用户评审关卡 — 在进入架构阶段前获得明确批准

无论项目看似简单与否，此流程适用于所有项目。简单项目的设计可简短，但必须执行。

可视化辅助： 对于涉及视觉元素（UI、架构图）的项目，草稿阶段可使用基于浏览器的可视化辅助工具，在设计对话中展示原型与图表。参见

references/visual-companion.md

。

YAGNI原则执行： 在设计对话和Cavekit生成过程中，主动剔除用户未要求的需求。套件越小越好。

With

ck:design-system

与

ck:design-system

集成

When DESIGN.md exists at the project root, kits for UI domains should reference design tokens in acceptance criteria. This creates a traceable chain: DESIGN.md -> cavekit acceptance criterion -> plan task -> implementation.

Acceptance Criterion Type	Design Reference
"Button has primary CTA appearance"	DESIGN.md Section 4, primary button variant
"Text follows heading hierarchy"	DESIGN.md Section 3, type scale
"Card has subtle elevation"	DESIGN.md Section 6, elevation level 1
"Layout uses 12-column grid"	DESIGN.md Section 5, grid system
"Colors adapt for dark mode"	DESIGN.md Section 2, dark mode mapping

Do NOT duplicate DESIGN.md content into kits. Reference by section/token name only. If a color changes in DESIGN.md, kits should not need updating.

When a cavekit needs a visual pattern not yet defined in DESIGN.md, note it in the acceptance criterion:

markdown

- [ ] Component uses card-like container [DESIGN.md: pattern not yet defined — flag for design update]

当项目根目录存在DESIGN.md时，UI领域的套件应在验收标准中引用设计令牌。这将创建可追溯的链路：DESIGN.md → Cavekit验收标准 → 方案任务 → 实现。

验收标准类型	设计参考
"按钮采用主CTA样式"	DESIGN.md第4节，主按钮变体
"文本遵循标题层级"	DESIGN.md第3节，字体层级
"卡片采用轻微阴影效果"	DESIGN.md第6节，阴影层级1
"布局使用12列网格"	DESIGN.md第5节，网格系统
"颜色适配深色模式"	DESIGN.md第2节，深色模式映射

请勿将DESIGN.md内容复制到套件中。 仅按章节/令牌名称引用。若DESIGN.md中的颜色更改，套件无需更新。

当Cavekit需要DESIGN.md中尚未定义的视觉模式时，在验收标准中注明：

markdown

- [ ] 组件使用类卡片容器 [DESIGN.md：模式尚未定义 — 标记为设计更新项]

With

ck:validation-first

与

ck:validation-first

集成

Every acceptance criterion in a cavekit must map to at least one validation gate. When writing kits, think about which gate will verify each requirement:

Acceptance Criterion Type	Likely Gate
"Code compiles without errors"	Gate 1: Build
"Function returns correct output for input X"	Gate 2: Unit Tests
"User can complete workflow end-to-end"	Gate 3: E2E/Integration
"Response time under N ms"	Gate 4: Performance
"Application starts and displays main screen"	Gate 5: Launch Verification
"UI matches design intent"	Gate 6: Human Review

Cavekit中的每条验收标准必须映射到至少一个验证关卡。编写套件时，需考虑哪个关卡将验证每项需求：

验收标准类型	对应关卡
"代码编译无错误"	关卡1：构建
"函数对输入X返回正确输出"	关卡2：单元测试
"用户可完成端到端工作流"	关卡3：端到端/集成测试
"响应时间低于N ms"	关卡4：性能测试
"应用启动并显示主屏幕"	关卡5：启动验证
"UI与设计意图匹配"	关卡6：人工评审

With

ck:context-architecture

与

ck:context-architecture

集成

Kits live in the

context/kits/

directory. See

ck:context-architecture

for the full context directory structure, CLAUDE.md conventions, and multi-repo strategies.

套件存储在

context/kits/

目录中。有关完整的上下文目录结构、CLAUDE.md约定以及多仓库策略，请参见

ck:context-architecture

。

With

ck:impl-tracking

与

ck:impl-tracking

集成

As kits are implemented, progress is tracked in

context/impl/

documents. Dead ends discovered during implementation should be recorded to prevent future agents from retrying failed approaches.

随着套件的实现，进度将记录在

context/impl/

文档中。实现过程中发现的失败尝试应被记录，以防止未来Agent重复尝试已失败的方法。

Common Mistakes

常见错误

1. Writing Implementation-Specific Kits

1. 编写与实现相关的套件

Wrong: "Use PostgreSQL with a users table containing columns: id (UUID), email (VARCHAR), ..." Right: "User accounts have a unique identifier and email. Email must be unique across all accounts. Acceptance: creating two accounts with the same email fails with a duplicate error."

错误示例： "使用PostgreSQL创建users表，包含列：id（UUID）、email（VARCHAR）..." 正确示例： "用户账户拥有唯一标识符和邮箱。邮箱在所有账户中必须唯一。验收标准：创建两个邮箱相同的账户时，返回重复错误。"

2. Vague Acceptance Criteria

2. 模糊的验收标准

Wrong: "System handles errors properly" Right: "When a network request fails, the UI displays an error message within 2 seconds and offers a retry action. Acceptance: simulating network failure shows error banner with retry button."

错误示例： "系统应正确处理错误" 正确示例： "当网络请求失败时，UI在2秒内显示错误信息并提供重试操作。验收标准：模拟网络故障时显示带重试按钮的错误横幅。"

3. Missing Out of Scope

3. 缺失范围外内容

Every cavekit needs explicit exclusions. Without them, agents will over-build or make assumptions.

每个Cavekit都需要明确的排除项。否则，Agent会过度构建或做出假设。

4. No Cross-References

4. 无交叉引用

Domains do not exist in isolation. If cavekit-auth defines session tokens that cavekit-api uses, both kits must cross-reference each other.

领域并非孤立存在。若cavekit-auth定义了cavekit-api使用的会话令牌，两个套件必须相互交叉引用。

5. Monolithic Kits

5. 单体套件

A single 1000-line cavekit file defeats progressive disclosure. Decompose into domains with a clear index.

单个1000行的Cavekit文件违背了渐进式披露原则。应分解为带清晰索引的多个领域套件。

Summary

总结

Writing kits for AI agents follows these rules:

WHAT, not HOW — describe behavior, not implementation
Every requirement gets testable acceptance criteria — if agents cannot validate it, it will not be met
Hierarchical with an index — progressive disclosure for context efficiency
Cross-referenced — related domains link to each other
Explicitly scoped — out-of-scope section prevents over-building
Compact when large — archive resolved content, keep active files under 500 lines
Living documents — kits evolve through revision as gaps are discovered

为AI Agent编写套件需遵循以下规则：

目标优先，而非实现方式 — 描述行为，而非实现细节
每项需求都需可测试的验收标准 — 若Agent无法验证，需求将无法满足
带索引的层级结构 — 渐进式披露提升上下文效率
交叉引用 — 相关领域相互链接
明确范围 — 范围外内容防止过度构建
大文件压缩 — 归档已解决内容，保持活跃文件在500行以内
动态文档 — 套件通过差距发现后的修订不断演进