尧图网页设计 
1. 项目概述为什么我们需要“规约驱动”在软件开发的日常里我们常常陷入一种困境产品经理、设计师、开发者和测试人员围坐在一起对着一个需求反复讨论。产品经理在白板上画着原型嘴里说着“这里应该有个按钮点了之后会弹出一个浮层”开发者一边听一边在心里盘算着这个浮层是用模态框还是非模态框状态该怎么管理测试同学则在想这个按钮的边界条件是什么连续点击怎么处理。一场会议下来似乎达成了共识但散会后每个人带走的理解都像被哈哈镜扭曲过一样。最终代码写出来了UI也画好了但产品经理一看“这和我当初想的完全不一样啊”于是新一轮的扯皮、返工、加班开始了。问题的根源往往在于“需求”这个关键信息在传递和转化的过程中丢失、失真了。这就是“规约驱动开发”要解决的核心痛点。它不是一个新潮的概念其思想内核——用明确的、可执行的规约来指导开发——早已存在于测试驱动开发TDD或行为驱动开发BDD中。但传统的 Spec 文档无论是 PRD 还是需求规格说明书往往是静态的、孤立的 Word 或 Confluence 页面。它们与代码仓库、CI/CD 流水线、测试用例是割裂的。开发者在编码时需要不断切换上下文去查阅文档文档更新了也未必能及时同步到所有相关方。“规约驱动”追求的是将这份静态的文档变成整个开发流程中活的、可验证的“单一事实来源”。而 GitHub spec-kit正是 GitHub 为这一理念提供的一套“趁手工具”。它不是要取代你现有的项目管理工具而是旨在弥合从需求文字描述到可运行代码之间的巨大鸿沟。简单说它试图让需求规约Specification像代码一样可以被版本控制、被引用、被自动化验证并最终驱动开发工作流。当你听到“从需求到代码一条线”时想象的不再是断开的虚线而是一条从 Issue 或 Discussion 中萌发的想法生长为 Markdown 格式的详细规约然后这份规约自动创建出待实现的任务列表、关联的测试用例并最终在代码提交时被验证和标记完成。这条线是连贯的、可追溯的。2. 核心思路spec-kit 如何编织这条“线”GitHub spec-kit 本身并不是一个独立的全新平台它是一系列基于 GitHub 原生能力Issues, Projects, Actions, Codespaces构建的最佳实践和自动化工作流的集合。你可以把它理解为一套“乐高积木”式的方案核心思路是将规约文档化、结构化、自动化。2.1 规约即代码从文档到可操作资产传统的需求文档是给人读的而 spec-kit 倡导的规约是给人读的同时也能给机器“读”的。这并不意味着要用某种复杂的领域特定语言DSL恰恰相反它充分利用了开发者最熟悉的 Markdown 语法并通过约定俗成的格式和元数据赋予其额外的语义。例如一份用于描述“用户登录”功能的规约可能看起来像这样# 用户登录功能规约 **状态**: 草案 **负责人**: dev-alice **关联史诗**: EPIC-001 **开始日期**: 2023-10-27 **截止日期**: 2023-11-03 ## 概述 用户应能使用注册的邮箱和密码登录系统。 ## 功能需求 - **FUN-001**: 登录页面应包含邮箱输入框、密码输入框和“登录”按钮。 - **FUN-002**: 密码输入应被掩码显示。 - **FUN-003**: 应提供“忘记密码”链接。 ## 验收标准AC ### AC-001: 成功登录 **给定** 用户已注册且账号有效 **当** 用户在邮箱框输入正确邮箱在密码框输入正确密码并点击登录按钮 **那么** 系统应验证凭据跳转至用户仪表盘页面 **并且** 页面顶部应显示“欢迎回来[用户名]” ### AC-002: 密码错误 **给定** 用户已注册 **当** 用户输入正确邮箱但错误密码并点击登录 **那么** 系统应显示错误信息“邮箱或密码错误” **并且** 密码输入框应被清空并获得焦点 ## 技术任务 - [ ] 后端实现 /api/v1/auth/login POST 接口进行密码校验并返回 JWT。 - [ ] 前端创建 Login.vue 组件包含表单和状态管理。 - [ ] 前端集成 axios 拦截器将成功返回的 JWT 存储至 localStorage。 - [ ] 测试编写 Cypress E2E 测试用例覆盖 AC-001 和 AC-002。 ## 非功能需求 - 性能登录接口 P99 响应时间应 500ms。 - 安全密码传输必须 HTTPS后端存储必须加盐哈希。这份 Markdown 文档如果只是躺在 Wiki 里那它依然是静态的。但通过 spec-kit 的实践我们可以做以下事情自动创建任务利用 GitHub Actions可以解析## 技术任务下的复选框列表自动在项目的 Board 上创建对应的 Issue 或 Task并分配给指定的负责人如dev-alice。关联测试## 验收标准AC部分可以用类似 GherkinGiven-When-Then的语法编写。这些文本可以直接被转化为 Cucumber 等 BDD 测试框架的 feature 文件或者至少作为编写自动化测试用例的明确依据。状态追踪文档顶部的 YAML 前言Front Matter或特定标记如**状态**: 草案可以被机器人读取。当所有关联的技术任务 Issue 都被关闭或者所有关联的测试用例都通过后一个 GitHub Action 可以自动将规约文档的状态从进行中更新为已完成。双向链接在代码的 Pull Request 描述中可以引用具体的规约条目如实现 FUN-002或满足 AC-001。当 PR 被合并时机器人可以自动在对应的规约条目旁打上勾或添加评论实现从代码到规约的反向追溯。注意spec-kit 本身不包含一个“规约解析器”。上述自动化能力需要你团队利用 GitHub Actions、自定义脚本或集成第三方工具如用于解析任务列表的脚本来构建。spec-kit 提供的是模式和思路具体的“自动化齿轮”需要你自己组装。2.2 工作流集成在 GitHub 的生态内闭环spec-kit 的强大之处在于它深度集成在 GitHub 生态中这意味着所有活动都在同一个协作平面上进行减少了上下文切换。起源一个功能想法可能始于一个GitHub Discussion或一个Issue。经过初步讨论结论是“这个需要详细规划”。规约编写负责人通常是 Tech Lead 或资深开发者在代码仓库中一个特定的目录如/specs/下创建一个新的 Markdown 文件如user-login.md。他/她会利用模板填写如上所示的规约内容。自动化触发当这个 Markdown 文件被创建或推送到主分支或特定分支时配置好的GitHub Action被触发。这个 Action 会解析文件提取元数据状态、负责人、截止日期并更新到 Issue 或 Project 字段。解析“技术任务”列表为每个[ ]项创建一个子任务 Issue并链接到父 Issue。可能还会根据“验收标准”生成测试任务的骨架。开发与测试开发者领取分配的子任务 Issue 进行开发。他们可以在GitHub Codespaces中获得一个预配置好的开发环境立即开始编码。他们编写的单元测试、集成测试需要覆盖规约中定义的验收标准。提交与验证开发者完成代码后提交 Pull Request。PR 描述中应引用其解决的规约条目如Closes #23关闭了某个任务 Issue或Implements AC-001 from specs/user-login.md。CI 流水线会自动运行所有测试包括那些可能由规约生成的 BDD 测试。审查与合并审查者Reviewer在查看代码时可以轻松点击链接回溯到原始的规约文档理解这段代码的上下文和验收条件使代码审查更有依据。完成与归档PR 合并后关联的任务 Issue 自动关闭。当所有子任务和测试都通过后规约文档的状态被自动更新为“已完成”。这份规约成为了该功能永久的、可追溯的设计档案。这条“线”的核心价值在于可追溯性和一致性。任何时候你都可以从一行代码追溯到它要实现的需求也可以从一个需求追溯到实现它的所有代码和测试。这极大地降低了沟通成本提高了交付质量。3. 实操搭建从零开始配置你的 spec-kit 工作流理论很美好但落地需要具体的步骤。下面我将以一个典型的全栈 Web 应用项目为例演示如何搭建一个基础的 spec-kit 驱动的工作流。我们假设项目技术栈为 Node.js Vue.js使用 GitHub 进行托管。3.1 第一步规划仓库结构与规约模板首先在你的代码仓库根目录下创建规约文档的专属目录和模板。mkdir -p .github/workflows # 存放 GitHub Actions 配置文件 mkdir -p .github/ISSUE_TEMPLATE # 存放 Issue 模板可选 mkdir -p specs # 存放所有规约文档 mkdir -p .spec-templates # 存放规约模板在.spec-templates/下创建一个基础模板feature-spec-template.md--- title: “【请填写功能名称】”功能规约 status: draft # draft, in-review, active, implemented, deprecated author: “你的GitHub用户名” epic: “” # 关联的史诗 Issue 编号如 EPIC-1 start_date: YYYY-MM-DD due_date: YYYY-MM-DD --- # {{title}} ## 概述 简要描述这个功能是什么解决用户的什么痛点。 ## 背景与上下文 为什么需要这个功能相关的用户故事、业务目标或技术债是什么 ## 功能需求 以列表形式描述具体的功能点每个点最好有唯一标识如 FUN-001。 - **FUN-001**: [描述功能点一] ## 验收标准 使用 Given-When-Then 格式确保其可测试性。 ### AC-001: [场景描述] **给定** [初始状态] **当** [用户或系统执行某个操作] **那么** [预期的系统输出或状态改变] **并且** [其他相关的预期结果] (可选) ## 技术任务分解 将实现此规约所需的具体开发任务列出来。这些条目将被自动化脚本解析。 - [ ] 后端: [描述后端任务如“实现 /api/v1/xxx 接口”] - [ ] 前端: [描述前端任务如“创建 XxxComponent 组件”] - [ ] 数据库: [描述数据库变更如“新增 users 表的 last_login_at 字段”] - [ ] 测试: [描述测试任务如“编写 Cypress 测试覆盖 AC-001”] ## 非功能需求 - 性能: [例如“列表接口在 1000 条数据下加载时间 2s”] - 安全: [例如“所有敏感 API 必须进行权限校验”] - 兼容性: [例如“需支持 Chrome 最新两个版本”] ## 待决策项 - [ ] [需要团队讨论决定的问题如“采用轮询还是 WebSocket 实现实时更新”] ## 参考资料 - [链接到相关设计稿] - [链接到相关技术文档]这个模板包含了 Front Matter在---之间的部分用于存储元数据其余部分则是结构化的内容区域。团队所有成员在编写新规约时都应复制此模板保证格式统一。3.2 第二步创建规约解析与任务自动化 Action这是实现自动化的核心。我们需要编写一个 GitHub Actions 工作流当specs/目录下的 Markdown 文件被创建或修改时自动解析其中的“技术任务分解”部分并创建对应的 GitHub Issues。在.github/workflows/目录下创建process-spec.ymlname: Process Specification on: push: paths: - specs/**/*.md # 监听 specs 目录下所有 .md 文件的推送 pull_request: types: [closed] paths: - specs/**/*.md jobs: parse-and-create-tasks: if: github.event_name push contains(github.event.head_commit.message, docs(spec)) # 示例仅当提交信息包含特定前缀时运行 runs-on: ubuntu-latest permissions: issues: write # 需要写 Issues 的权限 contents: read steps: - name: Checkout code uses: actions/checkoutv4 with: fetch-depth: 0 - name: Parse Spec and Create Issues env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} SPEC_FILE: “${{ github.event.head_commit.modified }} # 简化处理实际中需要更精细地获取变更文件 run: | # 这是一个简化的 Bash 脚本示例实际应用可能需要用 Python/Node.js 编写更健壮的解析器 for file in $SPEC_FILE; do if [[ $file specs/*.md ]]; then echo “Processing spec file: $file” # 1. 提取规约标题和元数据 (例如用 yq 或 grep/sed) SPEC_TITLE$(grep -m1 ‘^# ‘ “$file” | sed ‘s/^# //’) # 2. 提取技术任务列表介于‘## 技术任务分解’和下一个二级标题之间的内容 # 这里逻辑较复杂省略细节。假设我们提取到了一个任务数组 TASKS # 3. 为每个任务创建 Issue for task in “${TASKS[]}”; do # 使用 GitHub CLI 创建 Issue gh issue create --title “$SPEC_TITLE: $task” --body “此任务来源于规约文件: $file” --label “task” echo “Created issue for task: $task” done fi done update-spec-status: if: github.event_name ‘pull_request’ github.event.action ‘closed’ github.event.pull_request.merged true runs-on: ubuntu-latest permissions: contents: write steps: - name: Checkout code uses: actions/checkoutv4 with: fetch-depth: 0 - name: Update Spec Status run: | # 当 PR 合并时检查 PR 描述或关联的 Issue找到其对应的规约文件 # 然后检查该规约关联的所有任务是否都已完成所有 Issue 已关闭 # 如果全部完成则使用 sed 或更高级的工具将规约文件 Front Matter 中的 status 从 ‘active’ 改为 ‘implemented’ # 最后提交更改 echo “Logic to update spec status would go here.” # 例如git config user.email “actiongithub.com” # git config user.name “GitHub Action” # git add specs/ # git commit -m “chore(spec): mark [spec-name] as implemented” # git push实操心得上面的 Action 示例是一个高度简化的概念验证。在实际生产中解析 Markdown 并精确提取结构化信息是一个复杂任务建议使用专门的脚本语言如 Python 的frontmatter、mistune库来编写独立的解析脚本并在 Action 中调用。此外管理 Issue 的创建、分配和状态更新逻辑也需要精心设计避免重复创建或孤儿 Issue。3.3 第三步建立开发与验收流程有了自动创建的任务接下来需要规范开发过程。开发启动开发者从分配给自己的 Issue 开始。他们可以使用GitHub Projects (Beta)的 Board 视图来管理个人任务流To Do, In Progress, Done。开发环境鼓励使用GitHub Codespaces。项目根目录下的devcontainer.json配置文件可以确保每个开发者打开项目时都拥有完全一致的、预装了所有依赖Node.js, npm, Vue CLI, 数据库等的开发环境真正做到“开箱即码”。提交关联在开发分支进行提交时强制要求在提交信息中关联任务 Issue。可以使用 Conventional Commits 格式git commit -m “feat(auth): implement login form UI - Implements FUN-001, FUN-002 from specs/user-login.md Closes #45” # 假设 #45 是“前端创建 Login.vue 组件”这个任务 Issue测试驱动在实现功能前先根据规约中的“验收标准”编写测试。对于前端可以是 Jest 单元测试或 Cypress 组件测试对于后端可以是 Jest/Mocha 接口测试。让失败的测试来驱动你编写实现代码。创建 Pull RequestPR 的标题和描述应清晰说明改动内容并务必链接到相关的规约和任务 Issue。这为审查者提供了完整的上下文。3.4 第四步配置自动化验证与状态同步这是让“线”真正连起来的关键。我们需要另一个 Action 来监听 PR 的合并事件并更新规约和项目的状态。创建.github/workflows/verify-and-update.ymlname: Verify and Update Spec Status on: pull_request: types: [closed] jobs: verify: if: github.event.pull_request.merged true runs-on: ubuntu-latest steps: - name: Check Linked Issues and Specs run: | # 1. 获取 PR 描述体 PR_BODY“${{ github.event.pull_request.body }}” # 2. 使用正则表达式从 PR_BODY 中提取所有关联的 Issue 编号 (如 #23, #45) 和规约文件引用 # 3. 检查所有提取到的 Issue 是否都已处于 ‘closed’ 状态 # 4. 如果某个规约关联的所有 Issue 都已关闭则判定该规约已实现 # 5. 调用上一个 Action 中类似的脚本去更新对应规约文件的 ‘status’ 字段 echo “Verification logic here.”此外你还可以集成更强大的工具。例如使用Cucumber或Jest-Cucumber将规约中的Given-When-Then语句直接转化为可执行的测试步骤定义。这样CI 流水线不仅能运行单元测试还能运行这些从规约衍生出来的验收测试实现真正的“规约即测试”。4. 避坑指南与进阶技巧在实际推行 spec-kit 这类规约驱动工作流时你会遇到不少挑战。下面是我从实践中总结出的常见问题和应对策略。4.1 常见问题与解决方案问题表现根本原因解决方案规约沦为形式主义开发者写完规约就丢一边编码时还是按自己想法来。规约与开发流程脱节没有强制或自动化的关联。强化自动化将任务创建、测试生成、状态更新完全自动化。让开发者不按规约走就“寸步难行”如无法创建分支、PR 检查不通过。文化引导在代码审查中首要问题就是“这段代码对应的规约是什么是否满足了所有 AC”规约编写耗时过长写一份详细的规约花了几天时间感觉拖慢了项目启动。试图一次性写出完美、面面俱到的规约。采用渐进式细化先写一个包含核心用户故事和关键 AC 的“轻量规约”创建初步任务开始 Spike 或原型开发。在开发过程中随着认知加深不断迭代和补充规约细节。使用模板模板能极大减少格式上的思考时间。规约与代码不同步功能上线后规约文档还是旧的失去了参考价值。缺乏规约更新的动力和机制。将规约文件视为源代码将其放在代码仓库中任何对功能的修改包括 Bug 修复都必须先更新规约或创建更新规约的任务否则 PR 无法合并。利用 Git 历史来追溯规约的演变。自动化脚本维护复杂自己写的解析 Markdown、管理 Issue 的脚本越来越臃肿容易出错。初期为了快速上线脚本写得不够健壮和模块化。优先使用现有工具在构建自定义流水线前先探索 GitHub Marketplace 上是否有现成的 Action如actions/github-script。脚本工程化将解析逻辑封装成独立的、有良好测试的 CLI 工具或容器镜像而不是将大段 Bash/Python 代码写在 YAML 文件里。团队抵触觉得太“重”尤其是小团队或快速迭代的项目觉得这套流程繁琐。没有根据团队规模和项目阶段进行裁剪生搬硬套。从小处试点不要一开始就在全团队推行。选择一个有代表性的新功能或一个小型子项目进行试点。灵活裁剪对于非常小的改动如修改文案可以不走完整的规约流程而是用一个简化的“变更请求”模板。核心是保证沟通效率而不是流程本身。4.2 进阶技巧提升规约驱动效能将设计稿与规约关联在规约的“参考资料”部分直接链接到 Figma 或 Sketch 的设计稿。更好的是利用一些插件或工具将设计稿的版本号或关键帧也记录下来。当设计稿更新时能快速定位到受影响的规约。使用 GitHub Discussions 进行前期探索在编写正式规约之前针对一个复杂或不确定的需求先在 GitHub Discussions 中发起技术讨论。将讨论中的关键结论、决策依据和待办事项直接整理并复制到最终的规约文档中。这保证了决策过程的透明和可追溯。为规约添加“健康度”检查在 CI 中增加一个检查步骤对specs/目录下的文件进行“lint”。例如检查是否所有规约都有负责人author、是否每个功能需求FUN-xxx都有至少一个验收标准AC-xxx对应、是否截止日期due_date格式正确等。这能保证规约的基本质量。利用 GitHub Projects 的可视化将规约、任务 Issue、PR 都关联到同一个 GitHub Project 中。利用 Project 的表格、看板视图和筛选、分组功能你可以一目了然地看到整个产品待办事项的全貌哪些规约在起草中哪些在开发中哪些卡在了代码审查环节。非功能需求的量化与监控规约中“性能接口 P99 500ms”这样的描述是好的开始但还不够。可以在 CI 流水线中集成性能测试如 k6在每次合并到主分支前都运行并将结果报告与规约中的要求进行比对。同样安全扫描SAST工具也可以集成进来自动验证“安全”需求是否被满足。5. 适用场景与团队适配思考Spec-Driven Development 和 spec-kit 这套方法论并非银弹它有最适合的土壤。最适合的场景中大型长期项目项目周期长参与人员多功能复杂对可维护性和可追溯性要求高。分布式或跨职能团队团队成员地理位置分散或者产品、设计、开发、测试角色分明需要清晰的书面沟通媒介。对质量、合规有高要求的领域如金融、医疗类应用变更需要严格的审计追踪。核心业务逻辑复杂业务规则多变且需要精确实现任何误解都可能导致严重错误。需要谨慎评估或调整的场景初创公司或探索性项目业务方向瞬息万变可能今天写的详细规约明天整个功能就被推翻了。此时更适合用轻量级的用户故事和原型来快速验证想法。微型团队如 1-3 人全栈沟通成本极低过度流程化反而会成为负担。可以只采用最核心的“将验收标准写成可测试的语句”这一实践而不必搭建完整的自动化流水线。纯粹的前端样式调整或简单 Bug 修复为修改一个按钮颜色或修复一个拼写错误而走全套规约流程显然是杀鸡用牛刀。团队适配的关键在于“渐进式”和“价值驱动”。不要试图一夜之间改变团队的工作习惯。可以从一个试点项目开始先让大家体验“写好规约后任务自动创建”的便利。然后逐步引入“PR 必须关联规约”的规则。最后再完善自动化状态同步和测试集成。让团队成员在每个阶段都感受到新流程带来的实际价值如减少会议扯皮、降低返工率、新人 onboarding 更快变革的阻力才会变小。我个人在推动这类实践时最深的体会是工具和流程只是骨架而团队对“清晰沟通”和“质量共建”的共识才是灵魂。spec-kit 提供了一套优秀的骨架但能否让它血肉丰满真正为团队提效取决于我们是否愿意花时间写出那些最初看起来有点“麻烦”的、清晰的规约。当团队养成这个习惯后你会发现前期在规约上多花的每一分钟都在后期为你节省了数小时的调试、争论和返工时间。这条从需求到代码的“线”最终编织成的是一张可靠的质量保障网。 GitHub spec-kit：规约驱动开发实践，从需求到代码的自动化工作流
1. 项目概述为什么我们需要“规约驱动”在软件开发的日常里我们常常陷入一种困境产品经理、设计师、开发者和测试人员围坐在一起对着一个需求反复讨论。产品经理在白板上画着原型嘴里说着“这里应该有个按钮点了之后会弹出一个浮层”开发者一边听一边在心里盘算着这个浮层是用模态框还是非模态框状态该怎么管理测试同学则在想这个按钮的边界条件是什么连续点击怎么处理。一场会议下来似乎达成了共识但散会后每个人带走的理解都像被哈哈镜扭曲过一样。最终代码写出来了UI也画好了但产品经理一看“这和我当初想的完全不一样啊”于是新一轮的扯皮、返工、加班开始了。问题的根源往往在于“需求”这个关键信息在传递和转化的过程中丢失、失真了。这就是“规约驱动开发”要解决的核心痛点。它不是一个新潮的概念其思想内核——用明确的、可执行的规约来指导开发——早已存在于测试驱动开发TDD或行为驱动开发BDD中。但传统的 Spec 文档无论是 PRD 还是需求规格说明书往往是静态的、孤立的 Word 或 Confluence 页面。它们与代码仓库、CI/CD 流水线、测试用例是割裂的。开发者在编码时需要不断切换上下文去查阅文档文档更新了也未必能及时同步到所有相关方。“规约驱动”追求的是将这份静态的文档变成整个开发流程中活的、可验证的“单一事实来源”。而 GitHub spec-kit正是 GitHub 为这一理念提供的一套“趁手工具”。它不是要取代你现有的项目管理工具而是旨在弥合从需求文字描述到可运行代码之间的巨大鸿沟。简单说它试图让需求规约Specification像代码一样可以被版本控制、被引用、被自动化验证并最终驱动开发工作流。当你听到“从需求到代码一条线”时想象的不再是断开的虚线而是一条从 Issue 或 Discussion 中萌发的想法生长为 Markdown 格式的详细规约然后这份规约自动创建出待实现的任务列表、关联的测试用例并最终在代码提交时被验证和标记完成。这条线是连贯的、可追溯的。2. 核心思路spec-kit 如何编织这条“线”GitHub spec-kit 本身并不是一个独立的全新平台它是一系列基于 GitHub 原生能力Issues, Projects, Actions, Codespaces构建的最佳实践和自动化工作流的集合。你可以把它理解为一套“乐高积木”式的方案核心思路是将规约文档化、结构化、自动化。2.1 规约即代码从文档到可操作资产传统的需求文档是给人读的而 spec-kit 倡导的规约是给人读的同时也能给机器“读”的。这并不意味着要用某种复杂的领域特定语言DSL恰恰相反它充分利用了开发者最熟悉的 Markdown 语法并通过约定俗成的格式和元数据赋予其额外的语义。例如一份用于描述“用户登录”功能的规约可能看起来像这样# 用户登录功能规约 **状态**: 草案 **负责人**: dev-alice **关联史诗**: EPIC-001 **开始日期**: 2023-10-27 **截止日期**: 2023-11-03 ## 概述 用户应能使用注册的邮箱和密码登录系统。 ## 功能需求 - **FUN-001**: 登录页面应包含邮箱输入框、密码输入框和“登录”按钮。 - **FUN-002**: 密码输入应被掩码显示。 - **FUN-003**: 应提供“忘记密码”链接。 ## 验收标准AC ### AC-001: 成功登录 **给定** 用户已注册且账号有效 **当** 用户在邮箱框输入正确邮箱在密码框输入正确密码并点击登录按钮 **那么** 系统应验证凭据跳转至用户仪表盘页面 **并且** 页面顶部应显示“欢迎回来[用户名]” ### AC-002: 密码错误 **给定** 用户已注册 **当** 用户输入正确邮箱但错误密码并点击登录 **那么** 系统应显示错误信息“邮箱或密码错误” **并且** 密码输入框应被清空并获得焦点 ## 技术任务 - [ ] 后端实现 /api/v1/auth/login POST 接口进行密码校验并返回 JWT。 - [ ] 前端创建 Login.vue 组件包含表单和状态管理。 - [ ] 前端集成 axios 拦截器将成功返回的 JWT 存储至 localStorage。 - [ ] 测试编写 Cypress E2E 测试用例覆盖 AC-001 和 AC-002。 ## 非功能需求 - 性能登录接口 P99 响应时间应 500ms。 - 安全密码传输必须 HTTPS后端存储必须加盐哈希。这份 Markdown 文档如果只是躺在 Wiki 里那它依然是静态的。但通过 spec-kit 的实践我们可以做以下事情自动创建任务利用 GitHub Actions可以解析## 技术任务下的复选框列表自动在项目的 Board 上创建对应的 Issue 或 Task并分配给指定的负责人如dev-alice。关联测试## 验收标准AC部分可以用类似 GherkinGiven-When-Then的语法编写。这些文本可以直接被转化为 Cucumber 等 BDD 测试框架的 feature 文件或者至少作为编写自动化测试用例的明确依据。状态追踪文档顶部的 YAML 前言Front Matter或特定标记如**状态**: 草案可以被机器人读取。当所有关联的技术任务 Issue 都被关闭或者所有关联的测试用例都通过后一个 GitHub Action 可以自动将规约文档的状态从进行中更新为已完成。双向链接在代码的 Pull Request 描述中可以引用具体的规约条目如实现 FUN-002或满足 AC-001。当 PR 被合并时机器人可以自动在对应的规约条目旁打上勾或添加评论实现从代码到规约的反向追溯。注意spec-kit 本身不包含一个“规约解析器”。上述自动化能力需要你团队利用 GitHub Actions、自定义脚本或集成第三方工具如用于解析任务列表的脚本来构建。spec-kit 提供的是模式和思路具体的“自动化齿轮”需要你自己组装。2.2 工作流集成在 GitHub 的生态内闭环spec-kit 的强大之处在于它深度集成在 GitHub 生态中这意味着所有活动都在同一个协作平面上进行减少了上下文切换。起源一个功能想法可能始于一个GitHub Discussion或一个Issue。经过初步讨论结论是“这个需要详细规划”。规约编写负责人通常是 Tech Lead 或资深开发者在代码仓库中一个特定的目录如/specs/下创建一个新的 Markdown 文件如user-login.md。他/她会利用模板填写如上所示的规约内容。自动化触发当这个 Markdown 文件被创建或推送到主分支或特定分支时配置好的GitHub Action被触发。这个 Action 会解析文件提取元数据状态、负责人、截止日期并更新到 Issue 或 Project 字段。解析“技术任务”列表为每个[ ]项创建一个子任务 Issue并链接到父 Issue。可能还会根据“验收标准”生成测试任务的骨架。开发与测试开发者领取分配的子任务 Issue 进行开发。他们可以在GitHub Codespaces中获得一个预配置好的开发环境立即开始编码。他们编写的单元测试、集成测试需要覆盖规约中定义的验收标准。提交与验证开发者完成代码后提交 Pull Request。PR 描述中应引用其解决的规约条目如Closes #23关闭了某个任务 Issue或Implements AC-001 from specs/user-login.md。CI 流水线会自动运行所有测试包括那些可能由规约生成的 BDD 测试。审查与合并审查者Reviewer在查看代码时可以轻松点击链接回溯到原始的规约文档理解这段代码的上下文和验收条件使代码审查更有依据。完成与归档PR 合并后关联的任务 Issue 自动关闭。当所有子任务和测试都通过后规约文档的状态被自动更新为“已完成”。这份规约成为了该功能永久的、可追溯的设计档案。这条“线”的核心价值在于可追溯性和一致性。任何时候你都可以从一行代码追溯到它要实现的需求也可以从一个需求追溯到实现它的所有代码和测试。这极大地降低了沟通成本提高了交付质量。3. 实操搭建从零开始配置你的 spec-kit 工作流理论很美好但落地需要具体的步骤。下面我将以一个典型的全栈 Web 应用项目为例演示如何搭建一个基础的 spec-kit 驱动的工作流。我们假设项目技术栈为 Node.js Vue.js使用 GitHub 进行托管。3.1 第一步规划仓库结构与规约模板首先在你的代码仓库根目录下创建规约文档的专属目录和模板。mkdir -p .github/workflows # 存放 GitHub Actions 配置文件 mkdir -p .github/ISSUE_TEMPLATE # 存放 Issue 模板可选 mkdir -p specs # 存放所有规约文档 mkdir -p .spec-templates # 存放规约模板在.spec-templates/下创建一个基础模板feature-spec-template.md--- title: “【请填写功能名称】”功能规约 status: draft # draft, in-review, active, implemented, deprecated author: “你的GitHub用户名” epic: “” # 关联的史诗 Issue 编号如 EPIC-1 start_date: YYYY-MM-DD due_date: YYYY-MM-DD --- # {{title}} ## 概述 简要描述这个功能是什么解决用户的什么痛点。 ## 背景与上下文 为什么需要这个功能相关的用户故事、业务目标或技术债是什么 ## 功能需求 以列表形式描述具体的功能点每个点最好有唯一标识如 FUN-001。 - **FUN-001**: [描述功能点一] ## 验收标准 使用 Given-When-Then 格式确保其可测试性。 ### AC-001: [场景描述] **给定** [初始状态] **当** [用户或系统执行某个操作] **那么** [预期的系统输出或状态改变] **并且** [其他相关的预期结果] (可选) ## 技术任务分解 将实现此规约所需的具体开发任务列出来。这些条目将被自动化脚本解析。 - [ ] 后端: [描述后端任务如“实现 /api/v1/xxx 接口”] - [ ] 前端: [描述前端任务如“创建 XxxComponent 组件”] - [ ] 数据库: [描述数据库变更如“新增 users 表的 last_login_at 字段”] - [ ] 测试: [描述测试任务如“编写 Cypress 测试覆盖 AC-001”] ## 非功能需求 - 性能: [例如“列表接口在 1000 条数据下加载时间 2s”] - 安全: [例如“所有敏感 API 必须进行权限校验”] - 兼容性: [例如“需支持 Chrome 最新两个版本”] ## 待决策项 - [ ] [需要团队讨论决定的问题如“采用轮询还是 WebSocket 实现实时更新”] ## 参考资料 - [链接到相关设计稿] - [链接到相关技术文档]这个模板包含了 Front Matter在---之间的部分用于存储元数据其余部分则是结构化的内容区域。团队所有成员在编写新规约时都应复制此模板保证格式统一。3.2 第二步创建规约解析与任务自动化 Action这是实现自动化的核心。我们需要编写一个 GitHub Actions 工作流当specs/目录下的 Markdown 文件被创建或修改时自动解析其中的“技术任务分解”部分并创建对应的 GitHub Issues。在.github/workflows/目录下创建process-spec.ymlname: Process Specification on: push: paths: - specs/**/*.md # 监听 specs 目录下所有 .md 文件的推送 pull_request: types: [closed] paths: - specs/**/*.md jobs: parse-and-create-tasks: if: github.event_name push contains(github.event.head_commit.message, docs(spec)) # 示例仅当提交信息包含特定前缀时运行 runs-on: ubuntu-latest permissions: issues: write # 需要写 Issues 的权限 contents: read steps: - name: Checkout code uses: actions/checkoutv4 with: fetch-depth: 0 - name: Parse Spec and Create Issues env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} SPEC_FILE: “${{ github.event.head_commit.modified }} # 简化处理实际中需要更精细地获取变更文件 run: | # 这是一个简化的 Bash 脚本示例实际应用可能需要用 Python/Node.js 编写更健壮的解析器 for file in $SPEC_FILE; do if [[ $file specs/*.md ]]; then echo “Processing spec file: $file” # 1. 提取规约标题和元数据 (例如用 yq 或 grep/sed) SPEC_TITLE$(grep -m1 ‘^# ‘ “$file” | sed ‘s/^# //’) # 2. 提取技术任务列表介于‘## 技术任务分解’和下一个二级标题之间的内容 # 这里逻辑较复杂省略细节。假设我们提取到了一个任务数组 TASKS # 3. 为每个任务创建 Issue for task in “${TASKS[]}”; do # 使用 GitHub CLI 创建 Issue gh issue create --title “$SPEC_TITLE: $task” --body “此任务来源于规约文件: $file” --label “task” echo “Created issue for task: $task” done fi done update-spec-status: if: github.event_name ‘pull_request’ github.event.action ‘closed’ github.event.pull_request.merged true runs-on: ubuntu-latest permissions: contents: write steps: - name: Checkout code uses: actions/checkoutv4 with: fetch-depth: 0 - name: Update Spec Status run: | # 当 PR 合并时检查 PR 描述或关联的 Issue找到其对应的规约文件 # 然后检查该规约关联的所有任务是否都已完成所有 Issue 已关闭 # 如果全部完成则使用 sed 或更高级的工具将规约文件 Front Matter 中的 status 从 ‘active’ 改为 ‘implemented’ # 最后提交更改 echo “Logic to update spec status would go here.” # 例如git config user.email “actiongithub.com” # git config user.name “GitHub Action” # git add specs/ # git commit -m “chore(spec): mark [spec-name] as implemented” # git push实操心得上面的 Action 示例是一个高度简化的概念验证。在实际生产中解析 Markdown 并精确提取结构化信息是一个复杂任务建议使用专门的脚本语言如 Python 的frontmatter、mistune库来编写独立的解析脚本并在 Action 中调用。此外管理 Issue 的创建、分配和状态更新逻辑也需要精心设计避免重复创建或孤儿 Issue。3.3 第三步建立开发与验收流程有了自动创建的任务接下来需要规范开发过程。开发启动开发者从分配给自己的 Issue 开始。他们可以使用GitHub Projects (Beta)的 Board 视图来管理个人任务流To Do, In Progress, Done。开发环境鼓励使用GitHub Codespaces。项目根目录下的devcontainer.json配置文件可以确保每个开发者打开项目时都拥有完全一致的、预装了所有依赖Node.js, npm, Vue CLI, 数据库等的开发环境真正做到“开箱即码”。提交关联在开发分支进行提交时强制要求在提交信息中关联任务 Issue。可以使用 Conventional Commits 格式git commit -m “feat(auth): implement login form UI - Implements FUN-001, FUN-002 from specs/user-login.md Closes #45” # 假设 #45 是“前端创建 Login.vue 组件”这个任务 Issue测试驱动在实现功能前先根据规约中的“验收标准”编写测试。对于前端可以是 Jest 单元测试或 Cypress 组件测试对于后端可以是 Jest/Mocha 接口测试。让失败的测试来驱动你编写实现代码。创建 Pull RequestPR 的标题和描述应清晰说明改动内容并务必链接到相关的规约和任务 Issue。这为审查者提供了完整的上下文。3.4 第四步配置自动化验证与状态同步这是让“线”真正连起来的关键。我们需要另一个 Action 来监听 PR 的合并事件并更新规约和项目的状态。创建.github/workflows/verify-and-update.ymlname: Verify and Update Spec Status on: pull_request: types: [closed] jobs: verify: if: github.event.pull_request.merged true runs-on: ubuntu-latest steps: - name: Check Linked Issues and Specs run: | # 1. 获取 PR 描述体 PR_BODY“${{ github.event.pull_request.body }}” # 2. 使用正则表达式从 PR_BODY 中提取所有关联的 Issue 编号 (如 #23, #45) 和规约文件引用 # 3. 检查所有提取到的 Issue 是否都已处于 ‘closed’ 状态 # 4. 如果某个规约关联的所有 Issue 都已关闭则判定该规约已实现 # 5. 调用上一个 Action 中类似的脚本去更新对应规约文件的 ‘status’ 字段 echo “Verification logic here.”此外你还可以集成更强大的工具。例如使用Cucumber或Jest-Cucumber将规约中的Given-When-Then语句直接转化为可执行的测试步骤定义。这样CI 流水线不仅能运行单元测试还能运行这些从规约衍生出来的验收测试实现真正的“规约即测试”。4. 避坑指南与进阶技巧在实际推行 spec-kit 这类规约驱动工作流时你会遇到不少挑战。下面是我从实践中总结出的常见问题和应对策略。4.1 常见问题与解决方案问题表现根本原因解决方案规约沦为形式主义开发者写完规约就丢一边编码时还是按自己想法来。规约与开发流程脱节没有强制或自动化的关联。强化自动化将任务创建、测试生成、状态更新完全自动化。让开发者不按规约走就“寸步难行”如无法创建分支、PR 检查不通过。文化引导在代码审查中首要问题就是“这段代码对应的规约是什么是否满足了所有 AC”规约编写耗时过长写一份详细的规约花了几天时间感觉拖慢了项目启动。试图一次性写出完美、面面俱到的规约。采用渐进式细化先写一个包含核心用户故事和关键 AC 的“轻量规约”创建初步任务开始 Spike 或原型开发。在开发过程中随着认知加深不断迭代和补充规约细节。使用模板模板能极大减少格式上的思考时间。规约与代码不同步功能上线后规约文档还是旧的失去了参考价值。缺乏规约更新的动力和机制。将规约文件视为源代码将其放在代码仓库中任何对功能的修改包括 Bug 修复都必须先更新规约或创建更新规约的任务否则 PR 无法合并。利用 Git 历史来追溯规约的演变。自动化脚本维护复杂自己写的解析 Markdown、管理 Issue 的脚本越来越臃肿容易出错。初期为了快速上线脚本写得不够健壮和模块化。优先使用现有工具在构建自定义流水线前先探索 GitHub Marketplace 上是否有现成的 Action如actions/github-script。脚本工程化将解析逻辑封装成独立的、有良好测试的 CLI 工具或容器镜像而不是将大段 Bash/Python 代码写在 YAML 文件里。团队抵触觉得太“重”尤其是小团队或快速迭代的项目觉得这套流程繁琐。没有根据团队规模和项目阶段进行裁剪生搬硬套。从小处试点不要一开始就在全团队推行。选择一个有代表性的新功能或一个小型子项目进行试点。灵活裁剪对于非常小的改动如修改文案可以不走完整的规约流程而是用一个简化的“变更请求”模板。核心是保证沟通效率而不是流程本身。4.2 进阶技巧提升规约驱动效能将设计稿与规约关联在规约的“参考资料”部分直接链接到 Figma 或 Sketch 的设计稿。更好的是利用一些插件或工具将设计稿的版本号或关键帧也记录下来。当设计稿更新时能快速定位到受影响的规约。使用 GitHub Discussions 进行前期探索在编写正式规约之前针对一个复杂或不确定的需求先在 GitHub Discussions 中发起技术讨论。将讨论中的关键结论、决策依据和待办事项直接整理并复制到最终的规约文档中。这保证了决策过程的透明和可追溯。为规约添加“健康度”检查在 CI 中增加一个检查步骤对specs/目录下的文件进行“lint”。例如检查是否所有规约都有负责人author、是否每个功能需求FUN-xxx都有至少一个验收标准AC-xxx对应、是否截止日期due_date格式正确等。这能保证规约的基本质量。利用 GitHub Projects 的可视化将规约、任务 Issue、PR 都关联到同一个 GitHub Project 中。利用 Project 的表格、看板视图和筛选、分组功能你可以一目了然地看到整个产品待办事项的全貌哪些规约在起草中哪些在开发中哪些卡在了代码审查环节。非功能需求的量化与监控规约中“性能接口 P99 500ms”这样的描述是好的开始但还不够。可以在 CI 流水线中集成性能测试如 k6在每次合并到主分支前都运行并将结果报告与规约中的要求进行比对。同样安全扫描SAST工具也可以集成进来自动验证“安全”需求是否被满足。5. 适用场景与团队适配思考Spec-Driven Development 和 spec-kit 这套方法论并非银弹它有最适合的土壤。最适合的场景中大型长期项目项目周期长参与人员多功能复杂对可维护性和可追溯性要求高。分布式或跨职能团队团队成员地理位置分散或者产品、设计、开发、测试角色分明需要清晰的书面沟通媒介。对质量、合规有高要求的领域如金融、医疗类应用变更需要严格的审计追踪。核心业务逻辑复杂业务规则多变且需要精确实现任何误解都可能导致严重错误。需要谨慎评估或调整的场景初创公司或探索性项目业务方向瞬息万变可能今天写的详细规约明天整个功能就被推翻了。此时更适合用轻量级的用户故事和原型来快速验证想法。微型团队如 1-3 人全栈沟通成本极低过度流程化反而会成为负担。可以只采用最核心的“将验收标准写成可测试的语句”这一实践而不必搭建完整的自动化流水线。纯粹的前端样式调整或简单 Bug 修复为修改一个按钮颜色或修复一个拼写错误而走全套规约流程显然是杀鸡用牛刀。团队适配的关键在于“渐进式”和“价值驱动”。不要试图一夜之间改变团队的工作习惯。可以从一个试点项目开始先让大家体验“写好规约后任务自动创建”的便利。然后逐步引入“PR 必须关联规约”的规则。最后再完善自动化状态同步和测试集成。让团队成员在每个阶段都感受到新流程带来的实际价值如减少会议扯皮、降低返工率、新人 onboarding 更快变革的阻力才会变小。我个人在推动这类实践时最深的体会是工具和流程只是骨架而团队对“清晰沟通”和“质量共建”的共识才是灵魂。spec-kit 提供了一套优秀的骨架但能否让它血肉丰满真正为团队提效取决于我们是否愿意花时间写出那些最初看起来有点“麻烦”的、清晰的规约。当团队养成这个习惯后你会发现前期在规约上多花的每一分钟都在后期为你节省了数小时的调试、争论和返工时间。这条从需求到代码的“线”最终编织成的是一张可靠的质量保障网。