用途:为项目或功能领域创建或更新概念胶囊,作为持久的语义权威,让后续工作锚定到同一套术语与约束。胶囊只承载持久的概念性事实,初始建立后应缓慢变化。
主要能力:胶囊文档固定包含四节。一、术语表(通用语言):5-15 个领域术语及在本项目中的确切含义,格式为“- 术语:定义(一句话)”,易混淆的术语需说明边界,每个术语最终应有代码归属(类型、模块、函数或测试套件)。二、不变量/定律:3-10 条必须始终成立的陈述,是约束而非功能,每条应可测试,并决定放在类型系统、构造函数/校验器还是测试中。三、快乐路径(一个场景):单一具体的输入→输出故事,格式为 Given/When/Then,要足够具体以成为第一个集成测试。四、非目标(恰好两条):明确不做的事及其原因,用于防止范围蔓延。文档控制在一屏(约 250-500 词),每条项目一句话。
使用方式:输入为项目或功能领域($ARGUMENTS)。若用户对领域描述不够清楚,需通过提问补齐:这是什么(一句话)、关键概念/名词/实体、必须始终成立的规则、最简单应做什么、明确不应做什么。文件位置:项目级放 docs/capsule.md,功能级放 docs/capsule-<feature>.md;若已存在胶囊则更新,不要另建第二份。
更新策略:仅在术语歧义/冲突/缺失、不变量被证明有误或不完整或不可验证、快乐路径不再反映首个集成场景、非目标不再是持久排除项时更新。不要在胶囊内追加变更日志、进度日志、里程碑状态或决策日志。当假设稳定为持久定律时,将其从 docs/assumptions.md 提升为胶囊不变量,并通过 /pragma:contract 跟踪执行。
验证:写完后检查每个术语能否映射到代码构造、每条不变量能否被测试、快乐路径是否具体到可作为集成测试、非目标是否明确排除了智能体可能构建的东西、文档是否避免了里程碑状态/假设置信度/历史决策日志;任一不通过则先修订。
生命周期尾部(必需):State: foundation;Next: /pragma:skeleton;Loop: /pragma:consult(默认,除非用户明确直接继续)。
限制:胶囊不用于阶段状态、候选排序或临时推迟(归里程碑)、置信度跟踪或不确定假设(归假设台账)、带理由/证据时序的决策历史(归路线图/决策)。若某不变量无法清晰陈述,说明概念尚未理解,应停下澄清。若术语超过约 15 个,应拆分为项目胶囊与功能胶囊。未提供的收费、平台等信息暂未提供。