让 AI 先想清楚再写代码：Spec Kit 实战指南

让 AI 先想清楚再写代码：Spec Kit 实战指南 让 AI 先想清楚再写代码：Spec Kit 实战指南 Modified June 26 13.4 在 Codex 里为什么使用美元符号命令？ Spec Kit 的 Codex 集成采用 skills 形式，命令名称是 $speckit constitution、$speckit specify 等。部分其他 agent 会使用斜杠命令，例如 /speckit.specify。 13.5 安装后看不到 skills 怎么办？ 确认当前会话位于已初始化目录。如果仍看不到，重新打开 Codex 会话或刷新工作区，让 Codex 重新加载 .agents/skills。 14. 推荐实践模板 ✅ 每次开始一个重要功能前，建议先创建 feature spec，再进入 plan 和 tasks。实现过程中如果发现需求变化，先更新 spec，再调整 plan 和 tasks。 为当前项目补全 .specify/memory/constitution.md，写入飞书 CLI 的安全、权限和文档交付规则。 选择一个真实功能，用 $speckit specify 创建第一份 feature spec。 运行 $speckit clarify，记录澄清问题和答案。 运行 $speckit plan，明确技术栈、API、数据结构和测试策略。 运行 $speckit tasks 和 $speckit analyze，再开始实现。 15. 资料来源 • Spec Kit 官方文档 • Spec Kit Quick Start Guide • Spec Kit Installation Guide • GitHub Spec Kit 开源仓库 • GitHub 官方博客：Spec driven development with AI 16. 测试案例库：用 Spec Kit 练手 以下案例用于验证 Spec Kit 的完整工作流。每个案例都可以从 $speckit specify 开始，按需加入 $speckit clarify、$speckit plan、$speckit tasks 和 $speckit analyze。 案例 1：飞书知识库发布助手 目标：用户输入主题、目标知识库和素材来源后，系统自动创建一篇飞书文档，并放入指定知识库。 测试价值：覆盖文档创建、知识库节点管理、权限身份、长文档写入、结果链接返回，适合验证 Spec Kit 对真实工作流的拆解能力。 Spec 输入示例 Plain Text Copy $speckit specify 为飞书 CLI 增加一个知识库发布助手。用户可以输入主题、目标知识库名称、资料来源和文档风格，系统自动生成结构化飞书文档，并放入目标知识库。完成后返回文档链接、wiki 链接、space id、node token 和 doc token。若权限不足，需要给出可执行的授权步骤。 建议澄清问题： • 目标知识库只允许精确匹配，还是允许模糊匹配后由用户确认？ • 用户身份固定使用 as user，还是允许 bot 身份创建？ • 长文档是一次写入，还是先建骨架再分段写入？ • 写入失败后是否需要自动清理半成品节点？ 推荐命令链： 1. $speckit specify：写清楚用户故事、目标知识库、输入输出和异常场景。 2. $speckit clarify：确认权限、匹配策略、失败回滚和输出字段。 3. $speckit plan：选择 lark cli wiki +space list、wiki +node create、docs +update、docs +fetch 作为核心实现路径。 4. $speckit tasks：拆成知识库查找、节点创建、正文写入、结果验证、错误处理五组任务。 5. $speckit analyze：检查 spec 中的验收标准是否都出现在 tasks 中。 验收标准： • 给定知识库名称，系统能找到唯一目标或要求用户确认候选。 • 成功创建文档后返回可打开的 wiki 链接。 • 文档目录至少包含摘要、背景、正文、结论和来源。 • 权限不足时输出最小授权命令，不泄露密钥或 token。 • 失败时记录失败阶段，并给出可重试步骤。 案例 2：飞书权限不足的恢复流程 目标：当用户身份缺少飞书 scope 时，系统能识别错误、提取缺失权限、生成授权指引，并在用户授权完成后继续原任务。 测试价值：检验 Spec Kit 是否会把安全规则、身份选择和异常分支写进规格，避免只描述成功路径。 Spec 输入示例 Plain Text Copy $speckit specify 为 lark cli 包装一个权限恢复流程。当 docs、wiki、drive 等命令返回 permission violations 时，系统识别当前身份是 user 还是 bot。user 身份输出 lark cli auth login 的最小 scope 授权命令；bot 身份输出开发者后台 console url。系统不能缓存授权链接，不能对 bot 执行 auth login。 建议澄清问题： • 授权链接是否需要生成二维码？ • 用户完成授权后，由谁执行 device code 轮询？ • 是否需要把原始失败命令保存为可重试任务？ • 多 scope 缺失时，优先逐个授权还是按域授权？ 验收标准： • 识别 permission violations 并提取缺失 scope。 • user 身份只输出 lark cli auth login scope 或 domain 路径。 • bot 身份只输出后台权限配置链接和说明。 • 授权 split flow 中不在同一轮阻塞等待用户扫码。 • 日志中不出现 appSecret、accessToken 等敏感字段。 案例 3：长文档分段生成与验证 目标：输入一个复杂主题后，系统先创建文档骨架，再按章节分段写入正文，最后读取目录确认所有章节存在。 测试价值：检验 Spec Kit 对长任务拆解的处理能力，也能避免一次性写入超长内容导致命令参数超限。 Spec 输入示例 Plain Text Copy $speckit specify 实现一个长文档生成器。用户输入主题、目标读者、章节数量和资料来源，系统先创建飞书文档骨架，再按章节分段写入。写入后必须使用 docs +fetch scope outline 验证目录，确保每个章节都存在。 建议澄清问题： • 每篇文档最多写多少章节？ • 章节写入失败时，是否继续写后续章节？ • 是否需要给每节生成摘要和检查清单？ • 验证只看目录，还是还要抽查正文内容？ 验收标准： • 首次创建只写标题和章节骨架。 • 每次写入只处理一个章节或一组相邻章节。 • 最终 fetch outline 能看到完整章节目录。 • 写入失败时返回失败章节名和可重试命令。 • 不会覆盖已经写好的章节内容。 案例 4：会议纪要整理成行动清单 目标：把一段会议纪要整理为决策、待办、负责人、截止时间和后续风险，并发布为飞书文档。 测试价值：检验 Spec Kit 对结构化输出、字段完整性和验收规则的支持，适合内容型 agent 工作流。 Spec 输入示例 Plain Text Copy $speckit specify 创建一个会议纪要整理器。用户输入会议原文或要点，系统输出一篇飞书文档，包含会议摘要、关键决策、行动项、负责人、截止时间、风险和待确认问题。缺少负责人或截止时间时，需要标记为待确认。 建议澄清问题： • 负责人只有姓名时，是否需要查询 open id 并写成 @人？ • 截止时间缺失时使用“待确认”，还是向用户追问？ • 行动项是否需要同步创建飞书任务？ • 是否需要保留原始纪要全文？ 验收标准： • 每个行动项至少包含事项、负责人、截止时间、状态四个字段。 • 缺失字段被标记为待确认。 • 会议决策和行动项分开呈现。 • 最终文档可被用户直接用于会后跟进。 • 原始纪要中的敏感内容按用户要求处理。 案例 5：Spec Kit 安装检查与环境诊断 目标：为新成员提供一键检查脚本，确认本机是否已安装 uv、specify、Codex CLI，以及当前项目是否完成 Spec Kit 初始化。 测试价值：这个案例小而完整，适合第一次试跑 Spec Kit。它覆盖命令执行、环境判断、友好错误提示和修复建议。 Spec 输入示例 Plain Text Copy $speckit specify 创建一个本地环境诊断命令。它检查 uv、specify、Codex CLI、.specify 目录、.agents/skills 目录和 AGENTS.md 中的 SPECKIT 块。输出分为通过、警告、失败三类，并给出修复命令。 建议澄清问题： • 诊断脚本使用 Bash、Node.js 还是 Python？ • 是否允许自动修复，还是只输出建议？ • 版本检查需要固定到指定 tag，还是接受任意可用版本？ • 是否要支持 macOS、Linux 和 Windows？ 验收标准： • 缺少 uv 时给出安装建议。 • 缺少 specify 时给出官方 GitHub 源安装命令。 • 当前目录未初始化时提示运行 specify init here integration codex。 • 输出包含当前版本和检查时间。 • 脚本退出码能区分通过和失败。 案例 6：旧功能重构与回归保护 目标：选择一个已有 CLI 功能进行重构，在不改变用户可见行为的前提下提升结构、错误处理和测试覆盖。 测试价值：检验 Spec Kit 对老代码的适配能力。重构场景需要先描述现有行为，再制定测试和迁移计划，适合训练 agent 的工程纪律。 Spec 输入示例 Plain Text Copy $speckit specify 重构飞书文档更新流程。保持现有命令参数和输出字段兼容，内部改为更清晰的解析、校验、执行、验证四层结构。重构必须保留资源块 token，不得破坏图片、画板、表格和 @人引用。需要补充回归测试。 建议澄清问题： • 哪些命令参数需要严格兼容？ • 哪些错误消息属于用户可见契约？ • 测试是否可以使用 mock API 响应？ • 需要覆盖哪些资源块类型？ 验收标准： • 旧命令的关键用法仍可运行。 • 已有文档中的 img、source、whiteboard、sheet、cite 等资源块保持原样。 • 新增测试覆盖成功路径、权限错误、参数错误、资源块保留和部分失败。 • 重构后的模块职责清晰，单个函数只处理一个主要责任。 • 实现完成后运行回归测试，并把结果写回任务记录。 建议试跑顺序 1. 先跑案例 5，验证本地环境和 Spec Kit 集成。 2. 再跑案例 1，覆盖飞书文档和知识库的核心工作流。 3. 随后跑案例 2，补齐权限异常处理。 4. 最后选择案例 3 或案例 6，测试长任务拆解和工程化实现。 Spec Kit 官方文档 Spec Kit Quick Start Guide Spec Kit Installation Guide GitHub Spec Kit 开源仓库 GitHub 官方博客：Spec driven development with AI 13.4 在 Codex 里为什么使用美元符号命令？ Spec Kit 的 Codex 集成采用 skills 形式，命令名称是 $speckit constitution、$speckit specify 等。部分其他 agent 会使用斜杠命令，例如 /speckit.specify。 13.5 安装后看不到 skills 怎么办？ 确认当前会话位于已初始化目录。如果仍看不到，重新打开 Codex 会话或刷新工作区，让 Codex 重新加载 .agents/skills。 14. 推荐实践模板 ✅ 每次开始一个重要功能前，建议先创建 feature spec，再进入 plan 和 tasks。实现过程中如果发现需求变化，先更新 spec，再调整 plan 和 tasks。 每次开始一个重要功能前，建议先创建 feature spec，再进入 plan 和 tasks。实现过程中如果发现需求变化，先更新 spec，再调整 plan 和 tasks。 为当前项目补全 .specify/memory/constitution.md，写入飞书 CLI 的安全、权限和文档交付规则。 选择一个真实功能，用 $speckit specify 创建第一份 feature spec。 运行 $speckit clarify，记录澄清问题和答案。 运行 $speckit plan，明确技术栈、API、数据结构和测试策略。 运行 $speckit tasks 和 $speckit analyze，再开始实现。 15. 资料来源 • Spec Kit 官方文档 Spec Kit 官方文档 • Spec Kit Quick Start Guide Spec Kit Quick Start Guide • Spec Kit Installation Guide Spec Kit Installation Guide • GitHub Spec Kit 开源仓库 GitHub Spec Kit 开源仓库 • GitHub 官方博客：Spec driven development with AI GitHub 官方博客：Spec driven development with AI 16. 测试案例库：用 Spec Kit 练手 以下案例用于验证 Spec Kit 的完整工作流。每个案例都可以从 $speckit specify 开始，按需加入 $speckit clarify、$speckit plan、$speckit tasks 和 $speckit analyze。 案例 1：飞书知识库发布助手 目标：用户输入主题、目标知识库和素材来源后，系统自动创建一篇飞书文档，并放入指定知识库。 测试价值：覆盖文档创建、知识库节点管理、权限身份、长文档写入、结果链接返回，适合验证 Spec Kit 对真实工作流的拆解能力。 建议澄清问题： • 目标知识库只允许精确匹配，还是允许模糊匹配后由用户确认？ • 用户身份固定使用 as user，还是允许 bot 身份创建？ • 长文档是一次写入，还是先建骨架再分段写入？ • 写入失败后是否需要自动清理半成品节点？ 推荐命令链： 1. $speckit specify：写清楚用户故事、目标知识库、输入输出和异常场景。 2. $speckit clarify：确认权限、匹配策略、失败回滚和输出字段。 3. $speckit plan：选择 lark cli wiki +space list、wiki +node create、docs +update、docs +fetch 作为核心实现路径。 4. $speckit tasks：拆成知识库查找、节点创建、正文写入、结果验证、错误处理五组任务。 5. $speckit analyze：检查 spec 中的验收标准是否都出现在 tasks 中。 验收标准： • 给定知识库名称，系统能找到唯一目标或要求用户确认候选。 • 成功创建文档后返回可打开的 wiki 链接。 • 文档目录至少包含摘要、背景、正文、结论和来源。 • 权限不足时输出最小授权命令，不泄露密钥或 token。 • 失败时记录失败阶段，并给出可重试步骤。 案例 2：飞书权限不足的恢复流程 目标：当用户身份缺少飞书 scope 时，系统能识别错误、提取缺失权限、生成授权指引，并在用户授权完成后继续原任务。 测试价值：检验 Spec Kit 是否会把安全规则、身份选择和异常分支写进规格，避免只描述成功路径。 建议澄清问题： • 授权链接是否需要生成二维码？ • 用户完成授权后，由谁执行 device code 轮询？ • 是否需要把原始失败命令保存为可重试任务？ • 多 scope 缺失时，优先逐个授权还是按域授权？ 验收标准： • 识别 permission violations 并提取缺失 scope。 • user 身份只输出 lark cli auth login scope 或 domain 路径。 • bot 身份只输出后台权限配置链接和说明。 • 授权 split flow 中不在同一轮阻塞等待用户扫码。 • 日志中不出现 appSecret、accessToken 等敏感字段。 案例 3：长文档分段生成与验证 目标：输入一个复杂主题后，系统先创建文档骨架，再按章节分段写入正文，最后读取目录确认所有章节存在。 测试价值：检验 Spec Kit 对长任务拆解的处理能力，也能避免一次性写入超长内容导致命令参数超限。 建议澄清问题： • 每篇文档最多写多少章节？ • 章节写入失败时，是否继续写后续章节？ • 是否需要给每节生成摘要和检查清单？ • 验证只看目录，还是还要抽查正文内容？ 验收标准： • 首次创建只写标题和章节骨架。 • 每次写入只处理一个章节或一组相邻章节。 • 最终 fetch outline 能看到完整章节目录。 • 写入失败时返回失败章节名和可重试命令。 • 不会覆盖已经写好的章节内容。 案例 4：会议纪要整理成行动清单 目标：把一段会议纪要整理为决策、待办、负责人、截止时间和后续风险，并发布为飞书文档。 测试价值：检验 Spec Kit 对结构化输出、字段完整性和验收规则的支持，适合内容型 agent 工作流。 建议澄清问题： • 负责人只有姓名时，是否需要查询 open id 并写成 @人？ • 截止时间缺失时使用“待确认”，还是向用户追问？ • 行动项是否需要同步创建飞书任务？ • 是否需要保留原始纪要全文？ 验收标准： • 每个行动项至少包含事项、负责人、截止时间、状态四个字段。 • 缺失字段被标记为待确认。 • 会议决策和行动项分开呈现。 • 最终文档可被用户直接用于会后跟进。 • 原始纪要中的敏感内容按用户要求处理。 案例 5：Spec Kit 安装检查与环境诊断 目标：为新成员提供一键检查脚本，确认本机是否已安装 uv、specify、Codex CLI，以及当前项目是否完成 Spec Kit 初始化。 测试价值：这个案例小而完整，适合第一次试跑 Spec Kit。它覆盖命令执行、环境判断、友好错误提示和修复建议。 建议澄清问题： • 诊断脚本使用 Bash、Node.js 还是 Python？ • 是否允许自动修复，还是只输出建议？ • 版本检查需要固定到指定 tag，还是接受任意可用版本？ • 是否要支持 macOS、Linux 和 Windows？ 验收标准： • 缺少 uv 时给出安装建议。 • 缺少 specify 时给出官方 GitHub 源安装命令。 • 当前目录未初始化时提示运行 specify init here integration codex。 • 输出包含当前版本和检查时间。 • 脚本退出码能区分通过和失败。 案例 6：旧功能重构与回归保护 目标：选择一个已有 CLI 功能进行重构，在不改变用户可见行为的前提下提升结构、错误处理和测试覆盖。 测试价值：检验 Spec Kit 对老代码的适配能力。重构场景需要先描述现有行为，再制定测试和迁移计划，适合训练 agent 的工程纪律。 建议澄清问题： • 哪些命令参数需要严格兼容？ • 哪些错误消息属于用户可见契约？ • 测试是否可以使用 mock API 响应？ • 需要覆盖哪些资源块类型？ 验收标准： • 旧命令的关键用法仍可运行。 • 已有文档中的 img、source、whiteboard、sheet、cite 等资源块保持原样。 • 新增测试覆盖成功路径、权限错误、参数错误、资源块保留和部分失败。 • 重构后的模块职责清晰，单个函数只处理一个主要责任。 • 实现完成后运行回归测试，并把结果写回任务记录。 建议试跑顺序 1. 先跑案例 5，验证本地环境和 Spec Kit 集成。 2. 再跑案例 1，覆盖飞书文档和知识库的核心工作流。 3. 随后跑案例 2，补齐权限异常处理。 4. 最后选择案例 3 或案例 6，测试长任务拆解和工程化实现。 📌 本文是一份面向 WaytoAGI 学习者和共建者的 Spec Kit 完整说明文档，整理时间为 2026年6月25日。内容基于 GitHub Spec Kit 官方文档、GitHub 开源仓库、GitHub 官方博客，以及当前工作区的实际安装结果。 https://github.com/github/spec kit 本文是一份面向 WaytoAGI 学习者和共建者的 Spec Kit 完整说明文档，整理时间为 2026年6月25日。内容基于 GitHub Spec Kit 官方文档、GitHub 开源仓库、GitHub 官方博客，以及当前工作区的实际安装结果。 https://github.com/github/spec kit 1. 一句话理解 Spec Kit Spec Kit https://github.com/github/spec kit 是 GitHub 开源的规格驱动开发工具包，用于把 AI 编码从一句模糊提示词，调整为一套可检查、可迭代、可复用的工程流程。它的核心思想是：先定义要做什么、为什么做、验收标准是什么，再让 AI 编码 agent 根据规格、技术计划和任务清单逐步实现。 在传统 AI 编码中，用户经常直接要求 agent 写代码。这个方式适合快速原型，但在真实项目中容易出现需求偏移、架构不一致、测试缺失、上下文遗漏等问题。Spec Kit 通过结构化文档和命令，把产品意图、技术约束和实现任务拆开处理，让 AI 每一步都有明确依据。 官方文档：https://github.github.com/spec kit/ 安装指南：https://github.github.com/spec kit/installation.html 2. Spec Kit 包含什么 Spec Kit 主要由两部分组成：Specify CLI 和一组面向不同编码 agent 的模板、脚本、命令或 skills。 • Specify CLI：命令名是 specify，负责初始化项目、安装模板、设置集成、管理扩展和工作流。 • 项目脚手架：初始化后生成 .specify 目录，里面包含模板、脚本、项目原则和工作流配置。 • Agent 集成：针对 Codex、Claude Code、GitHub Copilot、Gemini CLI、Cursor、Windsurf、Zed 等工具生成对应命令或 skills。 • Markdown 产物：每个阶段都会生成文档，例如 spec.md、plan.md、tasks.md、checklist 等。 • 扩展与预设：官方文档显示 Spec Kit 支持社区扩展、预设和工作流，可用于质量门禁、架构检查、组织标准化等场景。 3. 核心工作流 阶段 Codex 命令 主要目标 关键产物 Constitution $speckit constitution 定义项目原则、质量要求、测试约束、架构边界 .specify/memory/constitution.md Specify $speckit specify 描述用户目标、业务规则、用户故事、验收标准 specs/xxx/spec.md Clarify $speckit clarify 提出澄清问题，减少需求模糊点 规格中的 Clarifications 记录 Plan $speckit plan 说明技术栈、架构方案、数据模型、接口和约束 plan.md 等设计产物 Checklist $speckit checklist 检查规格完整性、一致性和可验收性 质量检查清单 Tasks $speckit tasks 拆成可单独实现、测试和 review 的任务 tasks.md Analyze $speckit analyze 检查 spec、plan、tasks 之间是否一致 一致性分析结果 Implement $speckit implement 按任务逐项实现、测试和验证 代码变更与测试结果 阶段 阶段 Codex 命令 Codex 命令 主要目标 主要目标 关键产物 关键产物 Constitution Constitution $speckit constitution $speckit constitution 定义项目原则、质量要求、测试约束、架构边界 定义项目原则、质量要求、测试约束、架构边界 .specify/memory/constitution.md .specify/memory/constitution.md Specify Specify $speckit specify $speckit specify 描述用户目标、业务规则、用户故事、验收标准 描述用户目标、业务规则、用户故事、验收标准 specs/xxx/spec.md specs/xxx/spec.md Clarify Clarify $speckit clarify $speckit clarify 提出澄清问题，减少需求模糊点 提出澄清问题，减少需求模糊点 规格中的 Clarifications 记录 规格中的 Clarifications 记录 Plan Plan $speckit plan $speckit plan 说明技术栈、架构方案、数据模型、接口和约束 说明技术栈、架构方案、数据模型、接口和约束 plan.md 等设计产物 plan.md 等设计产物 Checklist Checklist $speckit checklist $speckit checklist 检查规格完整性、一致性和可验收性 检查规格完整性、一致性和可验收性 质量检查清单 质量检查清单 Tasks Tasks $speckit tasks $speckit tasks 拆成可单独实现、测试和 review 的任务 拆成可单独实现、测试和 review 的任务 tasks.md tasks.md Analyze Analyze $speckit analyze $speckit analyze 检查 spec、plan、tasks 之间是否一致 检查 spec、plan、tasks 之间是否一致 一致性分析结果 一致性分析结果 Implement Implement $speckit implement $speckit implement 按任务逐项实现、测试和验证 按任务逐项实现、测试和验证 代码变更与测试结果 代码变更与测试结果 4. 两条推荐路径 4.1 快速实验路径 适合小功能、原型、一次性工具。流程较短，重点是尽快得到可运行结果。 4.2 生产级路径 适合真实产品、团队协作、复杂系统、需要长期维护的功能。建议把澄清、检查和一致性分析作为常规质量门禁。 5. 当前工作区安装状态 当前机器已在目录 /Users/ajtoy/Documents/海报和活动记录/2026年/飞书CLI 中完成 Spec Kit 安装和初始化。 项目 状态 Specify CLI 已安装，版本 0.11.8 Python 3.13.3 包管理工具 uv 0.11.0 Agent 集成 Codex，使用 $speckit <command 形式调用 脚本类型 Bash，目录为 .specify/scripts/bash 核心配置 .specify 已生成 Codex skills .agents/skills 已生成 项目规则 AGENTS.md 已追加 Spec Kit 上下文块，原有规则保留 项目 项目 状态 状态 Specify CLI Specify CLI 已安装，版本 0.11.8 已安装，版本 0.11.8 Python Python 3.13.3 3.13.3 包管理工具 包管理工具 uv 0.11.0 uv 0.11.0 Agent 集成 Agent 集成 Codex，使用 $speckit <command 形式调用 Codex，使用 $speckit <command 形式调用 脚本类型 脚本类型 Bash，目录为 .specify/scripts/bash Bash，目录为 .specify/scripts/bash 核心配置 核心配置 .specify 已生成 .specify 已生成 Codex skills Codex skills .agents/skills 已生成 .agents/skills 已生成 项目规则 项目规则 AGENTS.md 已追加 Spec Kit 上下文块，原有规则保留 AGENTS.md 已追加 Spec Kit 上下文块，原有规则保留 6. 安装方式 官方推荐从 GitHub 源安装。官方安装文档提醒，PyPI 上同名或近似名称的包可能和 GitHub Spec Kit 无关，正常安装应使用 GitHub 仓库地址。 7. 初始化后目录结构 在当前工作区，Spec Kit 生成的关键文件如下： • .specify/memory/constitution.md：项目原则和治理规则。 • .specify/templates/spec template.md：功能规格模板。 • .specify/templates/plan template.md：技术计划模板。 • .specify/templates/tasks template.md：任务拆解模板。 • .specify/scripts/bash/create new feature.sh：创建新 feature 的脚本。 • .specify/scripts/bash/setup plan.sh：生成计划相关产物的脚本。 • .specify/workflows/speckit/workflow.yml：内置工作流定义。 • .agents/skills/speckit .md：Codex 可用的 Spec Kit skills。 8. 如何写好规格 规格阶段应聚焦产品意图和用户行为，技术栈留到 plan 阶段再处理。一个好规格通常回答这些问题： • 谁会使用这个功能？他们的当前痛点是什么？ • 用户完成任务的关键路径是什么？ • 哪些行为必须支持？哪些边界条件必须明确？ • 成功标准是什么？如何验收？ • 异常场景如何处理？权限、隐私、安全是否有要求？ • 哪些内容暂时不做，避免 agent 扩展范围？ 9. 示例提示词 9.1 建立项目原则 9.2 创建功能规格 9.3 生成技术计划 10. 适合的场景 • 新项目从 0 到 1：先沉淀清晰规格，再生成技术方案和任务清单。 • 复杂项目加功能：在动代码前明确边界、接口、数据影响和验收条件。 • 遗留系统现代化：先把旧系统的业务规则整理为规格，再设计新实现。 • 团队协作：让产品、工程、测试共享同一份规格和任务依据。 • AI 编码治理：通过 constitution、checklist、analyze 降低随意改动和架构漂移。 11. 谨慎使用的场景 • 只有几行脚本或一次性命令时，完整流程可能显得过重。 • 需求还处在开放探索阶段，建议先用轻量草稿收敛问题，再进入 Spec Kit。 • 团队没有共同维护规格的习惯时，容易出现文档和实现脱节，需要指定负责人维护。 • 大型历史代码库中，如果 agent 无法读取足够上下文，仍需人工提供架构说明和关键文件路径。 12. 团队落地建议 1. 先写 constitution：把团队不可妥协的规则写进去，例如安全、权限、测试、日志、性能和代码风格。 2. 把 clarify 作为习惯：复杂需求先让 agent 问问题，回答后再进入 plan。 3. 小任务优先：tasks 应拆到可以单独实现、单独测试、单独 review 的粒度。 4. 实现前先 analyze：在编码前检查 spec、plan、tasks 的一致性，节省返工。 5. 保留产物：把 spec、plan、tasks 和最终代码一起保留，方便回溯决策。 6. 定期更新规格：当实现改变业务规则时，同步更新对应规格，避免后续 agent 读取旧上下文。 13. 常见问题 13.1 Spec Kit 会替代产品文档吗？ Spec Kit 更适合作为面向实现的工程规格。产品方案仍可以保留更丰富的背景、市场分析和用户研究；Spec Kit 负责把其中可执行的部分整理为 agent 可以使用的规格、计划和任务。 13.2 Spec Kit 会自动保证代码质量吗？ 它能显著改善输入质量和执行纪律，但代码质量仍取决于规格清晰度、测试覆盖、agent 能获取的上下文，以及人工 review。建议结合单元测试、集成测试、CI 和代码评审使用。 13.3 为什么 spec 阶段不写技术栈？ spec 阶段的重点是用户目标和行为契约。技术栈放在 plan 阶段，可以让“要实现什么”和“怎么实现”保持分层，后续更容易比较不同技术方案。