菜单
Use when PRD has passed a valid human or independent artifact-review Gate and technical spec is needed, or when user says 写Spec, 技术方案, tech spec, technical design, 架构设计. Defines the 12-section technical specification with mandatory architecture diagrams and API contracts.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Ezio0/agent-engineering-workflow --skill spec-authoring命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Automate a Manifest-bound delivery across Positioning, PRD, Spec, Impact, Plan, Test Plan, implementation, verification, and Candidate review by coordinating independent author/reviewer loops inside a human-approved Authority Envelope. Use when a user asks to execute a feature end to end, reduce repeated document confirmations, automate workflow gates, use graph engineering for delivery, or continue automatically while escalating only scope choices, authority expansion, non-convergence, and irreversible actions.
Write implementation plans for features that have passed a human or independent artifact-review Spec Gate. Defines Phase breakdown, task sizing (XS/S/M), dependency graph, and estimated vs actual time tracking. Trigger: after a valid Spec Gate, before Test Plan.
Use when writing a PRD, starting a new feature that needs requirements, or when user says 写PRD, 产品需求, feature requirements, 需求文档. Defines the 13-section PRD structure with mandatory observability requirements.
基于 SOC 职业分类
正在显示 SKILL.md
| name | spec-authoring |
| description | Use when PRD has passed a valid human or independent artifact-review Gate and technical spec is needed, or when user says 写Spec, 技术方案, tech spec, technical design, 架构设计. Defines the 12-section technical specification with mandatory architecture diagrams and API contracts. |
| version | 1.0.0 |
| author | human owner Agent Workflow |
| license | MIT |
| metadata | {"hermes":{"tags":["spec","technical","architecture","documentation","workflow"],"related_skills":["global-launch-review","prd-authoring","review-gate"]}} |
这是 Stage 02。它把 PRD 的"做什么"翻译成"怎么做"。
PRD 用产品语言（用户、故事、验收），Spec 用工程语言（组件、接口、错误契约、性能预算）。同一个特性，PRD 写"用户能保存草稿"，Spec 写"POST /api/drafts 返回 201，p99 < 200ms，鉴权要求 draft:write scope"。
Spec 是派生文档。它实现 PRD，不与 PRD 矛盾。如果发现 Spec 要偏离 PRD，先更新 PRD（升到 v1.1），再更新 Spec —— 否则两份文档会漂移，未来读者无法判断哪个为真。
强制 12 个章节，顺序固定。其中 §4 Architecture 必须有真图（ASCII 或 mermaid），纯文字"架构"不是架构；§6 API Surface 不能有 TBD endpoint；§11 Open Questions 每项必须有决策截止日。
启动本 skill 的典型场景：
不要使用的场景：
PRD 未通过人工签字或 Authority Envelope 内有效的独立 artifact-review PASS 就写 Spec，等于在不存在的需求上设计系统。
规则：Spec 引用 PRD，不重写 PRD。
| PRD 里 | Spec 里 |
|---|---|
| §4 功能需求 | §2 Goals —— 派生自 PRD FR |
| §10 非目标 | §3 Non-Goals —— link，别重写 |
| §3 用户故事 | §6 API Surface —— 每个 US 都对应可调用的 API |
| §5 非功能需求 | §10 Security & Privacy + §9 Performance Budget |
如果发现 Spec 要做的非目标不在 PRD §10，先去 PRD 加上 —— 否则 PRD 和 Spec 在 scope 上漂移。
一段话 + 系统上下文。
为什么需要图？因为文字描述允许读者脑补不同的架构，图把读者的脑补钉死。一旦钉死，讨论才能聚焦在"这个设计对不对"而不是"你以为的设计是什么"。
3-5 条目标，描述什么是成功。
为什么必须可量化？因为"系统应该快"是愿望，"p99 < 200ms"是承诺。前者无法验证、无法 fail、无法优化；后者都能。"快"、"准确"、"可靠"这些词必须翻译成数字才能进 §2。
本 Spec 显式不做什么。至少 3 个，每个带理由。
跟 PRD §10 一样的逻辑：scope creep 的预答辩。多一层文档不冗余 —— 工程师读 Spec 比 PRD 多，多一道防线。
组件、数据流、部署拓扑。
纯文字"架构"不是架构。 你写得再清楚，读者脑子里也会构造自己的版本。图强制所有人看到同一组 boxes 和 arrows。
部署拓扑是 §4.4 容易被忽略的部分。一个组件跑在 Lambda vs 长驻进程 vs 容器里，决定了它的失败语义、冷启动、计费方式 —— 这些都影响 §8 Failure Modes 和 §9 Performance Budget。
关键 entity、schema、状态机。
存储位置不是细节，是核心决策。同一个 entity 放 Postgres、Redis、S3、本地文件，意味着完全不同的延迟、一致性、成本 —— 这条决策必须显式。
外部可见接口（HTTP / CLI / library / 消息队列）。
§6 不能有 TBD endpoint。 PRD 里的每个用户故事都要能追到 §6 的一个 API。某个接口真不确定，加到 §11 Open Questions 并给截止日 —— 不许留在 §6 当占位符。
为什么这么严？因为下游 Plan、Test Plan、Implementation 全部依赖 §6 的契约。TBD 的接口意味着下游无法并行开工。
错误如何产生、表达、传播。
E_NOT_FOUND、E_RATE_LIMIT）错误是契约的一部分，不是事后补的。一个接口"成功返回什么"是契约，"失败返回什么"也是契约 —— 缺了失败契约，调用方不知道哪些错能重试、哪些不能。
什么会出错，如何检测，如何恢复。
| 场景 | 检测 | 恢复 |
|---|---|---|
| <失败 1> | <信号> | <动作> |
至少 3 个失败场景，每个写清检测信号和恢复动作。
Failure Mode 必须真实，不是人造的。 "数据库宕"是真的，"火星人入侵"不是。判断标准：这条失败在过去发生过吗？在合理的时间窗内可能发生吗？两个都"不"，删掉，留位置给真实风险。
关键路径必须列出多个失败模式 —— 关键路径就是"错了影响大"的路径，多列几个。
量化目标，不是愿望。
测不出就预算不了，预算不了就强制不了。 预算必须在当前可观测栈里可测 —— 如果你写 p99 < 200ms 但没有埋延迟监控，这个预算只是装饰，没人会发现它被违反。
谁能做什么，哪些数据敏感。
§10 是 Spec 里最容易被跳过的章节。原因：它难，而且常常暴露你没想清楚的事。但跳过它意味着把 PII 暴露在日志里、把 admin 接口开放给所有用户 —— 这些都是真实的事故。
至少要识别所有 PII 字段。识别了，保护就有了起点；不识别，连起点都没有。
尚未决定、影响下游（Plan、Implementation）的问题。
§11 不是"以后再想"。 说不出截止日，这个问题就没准备好进 §11 —— 它是 wishlist 项，应该删掉或先做研究。
截止日是干什么的？是逼决策的机制。没有截止日的 open question 会永远 open，直到下游 Plan / Implementation 阶段被迫替你做决策 —— 那时决策成本已经翻了 10 倍。
外部标准尤其重要 —— 如果你的 API 设计参考了 RFC 7235 或 Stripe API 规范，必须 link。这让未来读者知道哪些是约定俗成，哪些是你自创的。
本手册推荐 v1.0 项目用 Single Spec（一个文件，12 章节）。以下情况切换到 ADR-style（每条架构决策一个 ADR 文件）：
多数新项目：Single Spec + 内联"决定段落" 就够。ADR 是后期工具，不是早期工具。
症状：§4 是几段散文，没有图。
真实原因：你还没定下设计 —— 加图。文字允许模糊，图强制精确。如果你画不出图，说明你脑里的设计还没收敛。
症状：某些 endpoint 写"TBD"。
真实原因：PRD 里的 US 实现不了，或者你没想清楚接口。两个都是上游问题 —— 回 PRD。要么去掉对应 US，要么把它具体化。TBD 的接口到了 Implementation 阶段会卡死整个团队。
症状：§11 是个 wishlist，没有决策截止日。
真实原因：你没排优先级 —— 这是 Plan 阶段的事。每个 open question 都必须有截止日，否则它不是 open question，是 wishlist 项。删掉，或先做研究。
症状：Spec §3 写了 PRD §10 没有的非目标；或 Spec §2 的 Goal 跟 PRD §4 的 FR 对不上。
真实原因：你绕过 PRD 改了需求。先更新 PRD（升版本），再更新 Spec。否则两份文档漂移，未来读者无法判断哪个为真，决策历史也丢了。
症状：§10 写"暂无安全考量"或一句话带过。
真实原因：你跳过了难的部分。至少列 PII 字段 —— 这一动作就会逼你审视"系统里到底有什么数据"。识别是保护的第一步。
症状：§9 写"低延迟"、"高吞吐"、"性价比高"。
真实原因：你写的是愿望，不是预算。每个数字必须在当前可观测栈里可测 —— 不可测的预算是装饰，没人会发现它被违反。翻译成 p50/p95/p99、req/s、$/千次。
症状：§8 列了"网络分区"、"宇宙射线"这种教科书场景。
真实原因：你在凑数。Failure Mode 必须真实——过去发生过、或合理时间窗内会发生。删掉凑数的，留位置给真实风险（数据库锁、磁盘满、上游 API 限流、缓存击穿）。
进入 Stage 3（Plan）前，逐项过：
Gate 类型：人工签字 / independent artifact-review Review record 或签字：___________________ 日期：___________________
Gate PASS 后进入 Stage 3（Plan）；delivery graph reducer 可在 Authority Envelope 内自动推进。