用途
Sus Spec 关注的是一类特定工作:当意图或具后果的开放行为需要变成需求与验收标准时,用来编写、修订或对可验证的 Suspec 规格做结构检查。它给出的定义是——规格是在测试之下的已决定意图,除此之外的内容都不属于规格。
进入方式为显式请求,或在人类为未解决意图选定 Suspec 规格工作流之后进入。直接实现不因此获得规格资格。当琐碎工作不会因书面契约改变执行或评审时,保持一句内联意图句即可,不写文件。
主要能力
- 提问与选择:通过原生 picker,或带编号选项加 Other 的方式提出必需问题;推荐项放第一位;提供三个真实选项(二选一时为两个),每项给出直白理由和代价。
- 写前准备:阅读项目规则、当前代码、持久决策、相关产物与开放问题;锁定目标、受众、成功、边界与来源。
- 消灭事实缺口:当决策缺少证据时,持续研究直到证据足以支撑该决策。解决可逆约定。
- 处理开放行为:当具后果的行为仍开放时,呈现彼此不同且可行的方案,并按依赖顺序解决相关选择。
- 转为需求:把选定行为转成意图与可执行需求,在实质行为、公开契约、安全、高代价取舍、权威冲突与不可逆动作上冻结。
- 状态管理:每个未解决的选项保持 status: draft,并阻塞依赖工作。
- 结构校验:检查 frontmatter 有效性、ID 唯一、Intent 非空、每条需求只有一个义务;要求精确的三项块、Then 中恰好一个强度词、以及真实的验证方法。
- 拒绝项:占位符、处于 status: ready 的阻塞性问题、损坏的来源、以及同一行没有可观察标准的模糊需求。
- 删减:删掉任何对清晰度、范围、执行、验证、评审或持久记忆都无改善的段落。
使用方式
产物位置
将 ~/.agents/artifacts/<workspace>/ 解析为绝对路径;<workspace> 由仓库或工作目录的 basename 推导。在该处写入,并在旁边放置链接的 sidecar。发生冲突或工作区不明确时,给出人类可读的名称选项。遇到写入被阻止时,提供授予并重试、换一个 agent 中立的用户目录、或取消三个选择。绝不覆盖,也绝不回退到仓库、vendor 目录或临时路径。
本地来源引用相对产物书写;只有在运行时交接时才使用绝对路径。
frontmatter 形状
使用这一最小 frontmatter 形状:
type: spec id: SPEC-{{slug}} title: {{title}} status: draft owner: {{owner}} sources:
- ISSUE-123
- ../../path/to/source.md
sources 保持为列表。本地路径相对该规格书写;跟踪器与决策 ID 保持裸写。SPEC- ID 必须唯一。
正文结构
要求非空的 ## Intent 与 ## Requirements。只为由独特载荷需要的部分添加可选段落。
每条需求包含:
- 一个稳定的 ### AC-NNN ID;
- 一个非空的 - When: 条件,仅对无条件不变式使用 always;
- 一个非空的 - Then: 可观察义务,其中恰好一个刻意的 MUST、MUST NOT、SHOULD、SHOULD NOT 或 MAY;
- 一个具体的 - Verify with: 方法。
这三项按该顺序各使用一次,需求正文中不再添加其他行。独立失败的义务要拆分。后果放前面。只有当兼容性或公开契约使其可观察时才指明机制,并说明原因。
验证与模式
进行结构检查。仅在请求时修订。事实核验是独立的。
- check-only 模式:报告确切错误,不做编辑。
- write/revise 模式:修复错误并重新运行。
输出与收尾
交接前,削减重复、软化、仪式感与结构性膨胀,但不改变契约、标识符、逐字来源文本、证据或行为。重新运行适用的检查。只返回规格与每个 sidecar 的可点击 Markdown 链接,使用紧凑的 ~/.agents/... 标签与完全展开的绝对目标。只解释阻塞项、创建失败、未完成的验证,或不可逆动作确认。
一旦完全处理完毕且没有下游步骤需要它,就要求人类对该产物及其 sidecar 给出一个处置:Delete、Leave 或 Promote。Promote 会把临时材料移入项目拥有的永久位置。删除每个选定路径并验证其不存在;存留物会阻塞收尾。
适用场景
当意图或具后果的开放行为必须成为需求与验收标准时;当团队需要在实现前锁定目标、受众、成功、边界与来源时;当需要可执行、可验证、可评审的规格契约时。
限制
- 资料未提供价格与收费信息。
- 资料未提供支持的平台列表。
- 资料未提供具体效果数据或安装命令。
- 它不代替事实核验,事实核验是独立的。
- 只有在显式请求或人类选定该工作流后才进入;直接实现不获得规格资格。
- 未解决的选项会保持 draft 并阻塞依赖工作。
分类为通用与其它(general)。