absolute-spec

📋 请在首次回复时以 📋 表情符号开头。

Absolute Spec

Absolute Spec 将模糊的意图转化为一份经过评审的设计规格文档，然后停止。它是从完整生命周期中提取出来的 work 规划产物：扫描代码库，只询问代码无法回答的问题，编写规格，进行独立评分评审，然后交付一份文档，供你讨论、移交，或输入 /absolute work 来构建。

它刻意保持轻量。没有没完没了的访谈，没有任务看板，没有拆解，也不执行。只有一项交付物：一份足以让不熟悉项目的开发者据此构建的规格。

---

何时使用此命令

在以下情况下使用 spec：

• 你想要一份用于讨论、评审或移交的设计规格，而不是现在就开始构建。
• 你需要先在纸面上充分考虑某个功能，再决定是否投入实现。
• 团队成员或其他 Agent 将根据你的规格进行构建。
• 你想快速获得一份经过评审的设计文档，而无需走完整的分阶段生命周期。

以下情况下不要使用 spec：

• 你想在一个流程中完成设计和构建 → 使用 /absolute work（规格是其第 2 阶段，之后会进行拆解并安全地分批执行）。
• 你要记录的是已经存在 / 已经发布的代码 → 使用 /absolute docs（用于参考 / 说明类文档，而非前瞻性设计）。
• 只是一个无需设计、显而易见的一行修复。

与 work 的区别：**spec 生成文档后停止；work 生成文档后继续构建。**如果你不确定是否要现在就构建，可以先从 spec 开始；之后可以衔接 work，它会接续使用该规格。

---

核心原则

1. **先看代码库，再提问题。**先阅读现有内容；只询问代码无法回答的问题。
2. **有限澄清，而非没完没了。**进行一轮简短的澄清（3–5 个问题），而不是 work 那种深度追问。可以将问题批量提出。
3. **规格就是交付物。**这里的质量比其他任何环节都重要——保留独立评分评审。
4. **复用，不要另起炉灶。**模板、扩展规则和评审标准来自 absolute-work 的 references/spec-writing.md。此命令只是围绕它们构建的精简流程。
5. **评审后停止。**不写代码、不建看板、不执行。清晰地移交。
6. **绝不自动提交。**写入规格文件并报告；由用户提交。

---

流程

SCAN ─→ CLARIFY ─→ WRITE ─→ REVIEW ─→ HANDOFF

步骤之间没有硬性关卡（那是 work 的做法）。唯一的检查点是澄清环节——提问、获取答案，然后直接继续，直到产出经过评审的规格。

---

步骤 1 — 扫描

在提出任何问题之前，先根据实际情况确定规格的基础。

1. 检测约定——先读取缓存的配置：如果 .absolute.config.json 或 ~/.absolute/config.json 存在（由 /absolute init 创建），则解析生效的配置 （项目文件 → 全局 projects["<cwd>"] → 全局 defaults），并使用其中的 conventions， 只检测缺失的内容。如果没有配置 → 温和建议运行 init，并执行 work 的代码库 约定检测表（包管理器、语言 / 运行时、测试运行器、代码检查工具、构建系统、目录约定；参见 absolute-work 的 SKILL.md 中的 Codebase Convention Detection）。规格必须准确反映项目 实际使用的技术栈、脚本和路径。
2. 深入扫描上下文——阅读现有内容：docs/（先读 README）、根目录下的 README.md、 CLAUDE.md、CONTRIBUTING.md、docs/plans/（有重叠 / 相关的设计），近期 提交（最近 10–20 个）、包清单，以及功能涉及的目录。
3. 综合归纳——用 2–4 行说明你了解到的情况（技术栈、相关现有代码、 任何重叠的既有设计）。不要列出文件清单。

只需识别工作类型（功能 / 重构 / 从零构建 / 迁移），以便调整规格内容——spec 不会执行完整的分类型问题库。

---

第 2 步 — 澄清（有限提问）

只询问代码库确实无法回答的问题——关于偏好和范围的分歧。最多 3–5 个问题；可以合并提问（在可用时，一次 AskUserQuestion 调用中提出多个问题）。

适合提问的问题（代码无法回答时）：

• 范围边界 — v1 包含什么，明确推迟什么。
• 行为分歧 — 实时还是批处理、同步还是异步，以及真正需要决定“选哪种”的问题。
• 数据／契约形态 — 仅在设计取决于此且代码没有线索时提问。
• 非目标 — 明确不会做什么。

不要询问：配置、清单、测试文件或现有模式已经说明的内容。 如果代码已经给出答案，就在规范中说明，而不是提问。

如果用户说了“不要提问，直接起草”——跳到编写，并在 ## Open Questions／假设章节中记录每一项推测。

---

第 3 步 — 编写

将规范写入 <specDir>/YYYY-MM-DD-<topic>-design.md（<topic> = 简短的 kebab-case 标题）。 如果配置中存在 preferences.specDir，则 <specDir> 使用该值；否则使用 docs/plans。

使用 absolute-work 的 references/spec-writing.md 中的模板、章节缩放规则、写作风格和决策日志格式——该文件是唯一事实来源；请加载它，不要在此处复述。具体来说：

• 使用复杂度启发式表选择复杂度级别（Simple / Medium / Complex），并按相应要求调整章节。删除只会写“N/A”的章节。
• 内容要具体：使用真实文件路径、真实端点、代码块中的真实架构——绝不要写“用于 X 的端点”之类的内容。
• 在决策日志中记录澄清阶段解决的分歧，以及你提出的任何建议；每项都附上一句理由。

---

第 4 步 — 审查（独立评分）

分派一个单独的审查子 Agent——编写规范的 Agent 不得给自己打分（生成者 ≠ 评估者）。逐字使用 absolute-work 的 references/spec-writing.md 中的评分标准和审查者提示模板（评分式规范审查协议）：按完整性、一致性、清晰度、范围、可测试性评分（各 1–5 分，按权重计算）。

加权分数	结论	操作
4.0 – 5.0	通过	继续交接
3.0 – 3.9	需要修改	修复标出的问题并重新分派（最多 3 轮）
< 3.0	存在重大缺漏	立即告知用户；不要悄悄迭代

审查者通过是必要条件，但并非终点——交接阶段仍由用户最终决定。

---

第 5 步 — 交接

1. 展示 — 规范路径、复杂度级别，以及审查者的加权分数和结论。用 2–4 行概述关键决策。
2. 提出构建选项 — 接续使用 /absolute work，它会从分解阶段接手该规范，而不是重新进行需求收集。明确说明这是可选的后续步骤。
3. 停止。 不写代码，不创建看板。绝不要运行 git commit——如果用户提出要求，可以建议提交消息；由用户提交。

---

注意事项

1. 偏离到 work。 如果开始分解任务或编写代码，就已经偏离 spec 流程。请停在已审查的文档上。
2. 询问代码已经回答的问题。 有限提问仅用于了解偏好和分歧——先扫描，再提问。
3. 为了“简化流程”而跳过审查。 审查是低成本的质量关卡，能让独立规范值得信赖。不要省略。
4. 复述 spec-writing.md。 请加载它；不要复制模板／评分标准，否则两份内容会逐渐不一致。
5. 提问过多。 超过约 5 个问题，就变成了 work 的访谈流程。请精简。

输出 / 响应风格

像聪明的穴居人一样简洁作答。保留所有技术内容。只去掉废话。省略冠词、填充词、客套话和含糊措辞。可用片段句。技术术语保持准确。代码块和引用的错误信息保持不变。安全警告、不可逆操作确认，以及任何可能因片段顺序而被误解的多步骤流程，不要用穴居人风格；之后恢复。

---

配套命令

此技能链中的同级命令可围绕 spec 自然衔接：

• /absolute work — 实现规范描述的内容（从分解阶段接手规范）。
• /absolute ui — 为规范定义的功能设计界面。
• /absolute docs — 完成构建并发布后，为读者编写文档。

在相关情况下推荐这些命令；它们始终可用（属于同一技能，无需额外安装）。