1. 项目概述一个为AI开发者量身打造的SpecKit伴侣如果你和我一样每天都在和Claude Code、GitHub Copilot这类AI编程助手打交道那你肯定也遇到过类似的困扰一个功能需求从最初的构思到最终的代码实现中间要经历“写需求文档”、“做技术设计”、“拆解任务清单”好几个阶段。这些文档散落在不同的Markdown文件里状态全靠记忆进度难以追踪更别提让AI助手连贯地理解整个开发流程了。SpecKit Companion这个我最近深度使用并贡献了代码的VS Code扩展就是为了解决这个痛点而生的。简单来说它是一个专为“规范驱动开发”设计的项目看板和工作流引擎直接集成在你的VS Code侧边栏。它不是一个独立的AI工具而是你现有AI助手Claude、Copilot、Gemini等的“驾驶舱”。你可以在这里用结构化的方式定义功能规格然后驱动AI助手按阶段Specify - Plan - Tasks - Implement去执行所有产出和状态变更都会被自动追踪和可视化。这就像给你的AI编程工作流装上了进度条和导航仪让“人机协作”从零散的对话变成了一个可管理、可复现的工程项目。2. 核心设计理念与架构解析2.1 为什么是“规范驱动开发”在深入细节之前有必要先聊聊SpecKit Companion背后的哲学Spec-Driven Development。这并非一个全新的概念但在AI时代被赋予了新的生命力。传统的SDD强调“先写规范再写代码”以减少歧义和返工。而当你的“执行者”变成了AI时一份清晰、结构化的规范就显得更为关键。AI需要明确的指令和上下文才能产出可靠的代码。SpecKit Companion将这一理念工具化。它认为一个功能的开发周期应该被明确定义为几个阶段每个阶段有明确的输入如上阶段的产出、动作调用哪个AI命令和输出生成的Markdown文档。整个扩展的核心就是围绕“阶段”、“状态”和“上下文”这三个概念来构建的。2.2 核心架构状态集中管理与事件驱动SpecKit Companion的架构非常清晰其核心是一个名为.spec-context.json的文件。我称之为“单一事实来源”文件。这个文件位于每个“规格”目录下记录了关于这个功能的所有元数据当前阶段这个功能正处在specifying明确需求还是implementing实施中历史记录每个阶段是何时开始、何时结束的甚至包含了更细粒度的“子步骤”。状态流转每一次状态变更比如从“规划中”切换到“任务拆解”都会被记录包括变更时间、触发来源。工作流类型这个规格使用的是内置的speckit-companion流程还是自定义的agent-teams-lite流程重要提示所有在侧边栏看到的可视化信息——那个显示当前步骤的徽章、步骤旁边的绿色对勾或蓝色脉冲光效、甚至是底部操作按钮的文案——全部是从这个.spec-context.json文件实时读取并渲染的。扩展绝不会通过简单地检查spec.md文件是否存在来判断“需求阶段”是否完成。这种设计保证了状态判断的准确性和可扩展性。整个扩展是事件驱动的。当你在界面上点击“批准”或“重新生成”按钮时扩展会做两件事更新状态首先同步更新本地的.spec-context.json文件写入新的status和stepHistory。驱动AI然后根据配置向对应的AI CLI工具如claude命令发送相应的指令如/speckit.plan。这种“状态先行再执行动作”的模式确保了UI展示和实际后端过程的一致性即使AI命令执行失败或耗时较长前端状态也已经更新避免了歧义。2.3 多AI提供商的无缝适配作为一个深度用户我特别欣赏它对多AI环境的支持。它不绑定任何单一的AI服务。通过speckit.aiProvider配置项你可以指定当前项目使用 Claude Code、GitHub Copilot CLI、Gemini CLI 还是 Codex CLI。它的聪明之处在于能自动识别并适配不同AI提供商的“引导文件”约定。例如当你使用Claude Code时它会去查找.claude/steering/目录下的引导文件而如果切换到GitHub Copilot则会去识别.github/copilot-instructions.md。这意味着SpecKit Companion充当了一个统一的交互层你只需要通过它来管理规格和流程底层可以灵活切换不同的AI引擎而不需要改变你的操作习惯。3. 核心功能深度体验与配置详解3.1 侧边栏你的AI开发指挥中心安装扩展后VS Code活动栏会出现一个烧杯图标。点击它主界面就展现在侧边栏。这里将所有内容分门别类规格这是核心区域你所有的功能开发单元都在这里。它又分为“进行中”、“已完成”、“已归档”三个可折叠区域一目了然。引导存放给AI的“公司规范”、“项目约定”等顶层指导文件。代理技能用于定义更复杂的AI角色和可复用的能力模块如果你使用支持多代理的工作流如Agent Teams Lite。钩子配置自动化触发脚本比如在某个阶段完成后自动运行测试。一个让我效率倍增的细节规格列表的标题栏有一个“展开/折叠全部”的切换按钮。当我在评审多个规格时可以一键收起所有详情快速浏览标题需要深入时再一键展开。这个状态是内存级的不持久化但非常符合临时性浏览的需求。右键点击任意规格会出现一个实用的上下文菜单。除了标记状态我最常用的是“在文件管理器中显示”它能立刻在Finder或资源管理器中打开该规格所在的文件夹方便我直接操作原始文件。3.2 可视化工作流编辑器让进度一目了然点击任何一个“进行中”的规格主编辑区就会变成一个可视化的工作流编辑器。这不是一个简单的Markdown预览而是一个交互式视图。编辑器顶部清晰地展示了当前规格所处的阶段流。当前阶段会以一个蓝色圆点高亮显示。如果某个阶段已经完成其前面会有一个绿色对勾。而如果AI正在为某个阶段执行任务比如正在生成plan.md该阶段标签下方会显示一个实时的计时器例如3m 22s并且阶段图标会呈现绿色的脉冲光效。这种视觉反馈极其重要让我在等待AI输出的同时能确切知道它正在处理哪个环节避免了盲目的等待。编辑器主体则渲染该规格的主要Markdown文档。对于包含Mermaid图表的内容它支持内联渲染和缩放控制这对于阅读复杂的技术架构图非常友好。3.3 行内评论像Code Review一样评审需求这是促进团队协作或自我迭代的关键功能。在浏览spec.md或plan.md时你可以像在GitHub上评论代码一样对某一行需求或设计提出疑问或建议。操作心得我通常会在“规划”阶段使用这个功能。当AI生成初步的技术方案后我会通读一遍对存疑的技术选型、可能的风险点直接添加行内评论。这些评论会被保存在规格目录下的一个独立文件中。之后我可以直接要求AI“请查看并回复第X行的评论”从而实现基于上下文的精准迭代。这比在聊天窗口里大段描述“关于XXX那一点”要高效和准确得多。3.4 安全机制为“危险操作”加上双保险开发中误操作难免。SpecKit Companion为几个关键的生命周期操作设计了防误触机制体现了其深思熟虑的一面重新生成点击后会触发一个持续5秒的撤销Toast提示。在这5秒内点击“撤销”或按Esc键操作就会被取消。这给了我反悔的机会防止因手滑而覆盖掉一份已经不错的产出。归档/完成/重新激活这些更永久的操作需要二次确认。第一次点击后按钮文字会变成“确认”并持续3秒。只有在3秒内再次点击操作才会生效。否则按钮会静默恢复原状。这个设计完美避免了在快速点击时造成的灾难性状态变更。3.5 深度配置打造属于你的工作流SpecKit Companion的默认四阶段工作流很好但它的强大之处在于其可扩展性。你可以通过VS Code的settings.json定义完全自定义的工作流。配置案例接入Agent Teams Lite假设你的团队使用更复杂的“Agent Teams Lite”框架进行多代理协作开发你可以这样配置{ speckit.customWorkflows: [ { name: agent-teams-lite, displayName: Agent Teams Lite (SDD), steps: [ { name: specify, label: 需求分析, command: sdd-spec, file: spec.md }, { name: plan, label: 技术设计, command: sdd-design, file: design.md, includeRelatedDocs: true }, { name: tasks, label: 任务拆解, command: sdd-tasks, file: tasks.md }, { name: review, label: 人工评审, actionOnly: true } ] } ], speckit.customCommands: [ { name: verify, title: 验证实现, command: /sdd-verify, step: tasks, tooltip: 运行测试验证代码是否符合规格 } ], speckit.defaultWorkflow: agent-teams-lite }配置解析与技巧steps这里完全重定义了工作流阶段。label可以本地化为中文。“actionOnly: true”的步骤如review不会生成文件只在工作流中作为一个可点击的动作按钮存在适合触发一些人工流程或外部工具。includeRelatedDocs这是一个非常实用的属性。当设置为true时该步骤如plan会自动将规格目录下所有未被其他步骤声明的.md文件收纳为其“相关文档”显示在侧边栏。这很适合管理那些在规划阶段产生的辅助性文档如api-design.md、db-schema.md等。customCommands你可以为特定阶段添加自定义的按钮。比如在“任务拆解”阶段增加一个“验证实现”按钮点击后会自动执行/sdd-verify命令。defaultWorkflow设置后新建规格时会默认使用这个工作流。避坑指南在定义自定义工作流时务必确保command字段的值与你本地AI CLI工具能识别的命令完全一致。例如Claude Code可能使用/speckit.plan而你的自定义SDD工具可能使用/sdd.design。如果命令不匹配点击按钮后AI将无法响应。最佳实践是先在终端手动测试一下命令是否有效。4. 实战从零开始一个功能开发周期让我们跟随一个真实的场景——“为用户添加双因素认证(2FA)功能”来体验完整的SpecKit Companion工作流。4.1 第一阶段明确需求创建规格在SpecKit侧边栏点击按钮弹出创建对话框。填写信息标题032-add-2fa-for-users描述详细描述背景、用户故事、业务目标。例如“作为用户我希望在登录时启用双因素认证以提高我的账户安全性。系统应支持TOTP标准并允许用户在后端恢复代码...”选择工作流使用默认的speckit-companion。附加截图可以将UI设计稿拖入对话框作为附件。提交点击“提交”扩展会做两件事在项目根目录的specs/下创建文件夹032-add-2fa-for-users/。在该文件夹内初始化一个.spec-context.json文件状态为draft并生成一个初始的spec.md文件框架。同时它会向配置的AI提供者如Claude Code发送/speckit.specify命令并将你的描述作为输入。现场记录此时侧边栏该规格的状态图标是蓝色的烧杯表示“进行中”。点开规格工作流编辑器显示当前处于“Specify”阶段并且该阶段图标开始绿色脉冲下方出现计时器。AI正在后台生成详细的规格文档。4.2 第二阶段技术规划当AI完成spec.md后.spec-context.json中的currentStep会自动更新为plan状态变为specified。工作流编辑器中“Specify”阶段前出现绿色对勾“Plan”阶段高亮为蓝色圆点。触发规划在工作流编辑器的“Plan”阶段区域点击“生成规划”按钮或“批准并继续”。AI执行扩展会发送/speckit.plan命令并将已完成的spec.md作为上下文提供给AI。产出AI会生成plan.md内容可能包括技术选型使用哪个2FA库如speakeasy、otplib数据模型变更用户表需要新增totp_secret和is_2fa_enabled字段。API设计GET /api/user/2fa/setup生成二维码POST /api/user/2fa/verify验证并启用POST /api/user/2fa/disable。实施策略先实现后端逻辑再开发前端设置界面最后更新登录流程。操作技巧在这个阶段我强烈建议使用行内评论功能。如果AI提出的某个库版本过旧或某个API设计不符合项目REST规范直接在该行添加评论。之后可以命令AI“请根据第15行和第22行的评论重新评估并更新技术方案。”4.3 第三阶段任务拆解规划确认无误后进入“Tasks”阶段。点击“生成任务清单”AI将基于spec.md和plan.md输出一个可执行的tasks.md文件。一份好的任务清单应该是这样的## 任务清单实现用户2FA功能 - [ ] **后端数据层** - [ ] 在users表中添加totp_secret (VARCHAR) 和 is_2fa_enabled (BOOLEAN) 字段。 - [ ] 创建数据库迁移脚本。 - [ ] **后端服务层** - [ ] 安装并配置 otplib 库。 - [ ] 实现生成TOTP密钥和QR码的服务函数。 - [ ] 实现验证TOTP代码的服务函数。 - [ ] **后端API层** - [ ] 实现 GET /api/user/2fa/setup 端点。 - [ ] 实现 POST /api/user/2fa/verify 端点。 - [ ] 实现 POST /api/user/2fa/disable 端点。 - [ ] 更新登录逻辑在2FA启用时要求二次验证。 - [ ] **前端设置界面** - [ ] 创建“安全设置”页面组件。 - [ ] 集成QR码显示组件。 - [ ] 实现验证码输入表单。 - [ ] **测试** - [ ] 编写后端服务单元测试。 - [ ] 编写API集成测试。 - [ ] 进行端到端流程测试。核心价值这个tasks.md文件成为了你和AI后续协作的精确“工单”。你可以手动勾选完成的任务也可以直接让AI根据某个任务项来编写代码。4.4 第四阶段实施与完成“Tasks”阶段完成后状态会变为ready-to-implement。此时工作流编辑器的底部主按钮会变成“开始实施”。驱动开发点击“开始实施”这通常不会直接生成一个巨大的代码文件而是将上下文切换到“实施”模式。你可以打开终端或者直接对AI说“请实现任务清单中的第1项为用户表添加2FA字段。”迭代与勾选AI生成迁移脚本后你进行审查、运行。确认无误后回到tasks.md手动勾选第一项。然后继续指挥AI完成下一项。状态流转当所有任务被勾选tasks.md中所有复选框变为- [x]时SpecKit Companion会检测到这一变化通过文件监听并自动将规格状态更新为completed。归档功能上线后你可以右键点击该规格选择“归档”。它会被移动到侧边栏的“已归档”区域.spec-context.json中的状态变为archived。项目目录保持原样便于未来查阅。个人体会这个流程将庞大的功能开发分解成了AI擅长处理的、离散的、上下文明确的子任务。你不再是漫无目的地向AI提问而是像一个项目经理在一个可视化的看板上有条不紊地分发和验收工作。5. 高级技巧与疑难排查5.1 自定义命令的妙用除了阶段性的主命令你可以在任何阶段注入自定义命令。例如我配置了一个在“Tasks”阶段使用的代码质量检查命令{ speckit.customCommands: [ { name: lint-and-test, title: 运行Lint和测试, command: npm run lint npm test, step: tasks, tooltip: 检查代码风格并运行单元测试, requiresSpecDir: true, autoExecute: false } ] }requiresSpecDir: true意味着命令会在当前规格的目录下执行。autoExecute: false意味着点击后命令会出现在终端面板等待回车确认而不是自动执行。这对于可能具有破坏性的命令如数据库迁移是个安全特性。5.2 权限模式的选择安全与效率的权衡在设置中speckit.permissionMode控制着AI CLI执行工具调用时的行为。interactive(推荐)AI在执行任何有副作用的操作如写入文件、运行脚本前会向你请求许可。这是最安全的模式。auto-approve(YOLO模式)跳过所有权限提示自动批准。这能极大加快AI的响应和操作速度但存在风险因为你无法预先审查AI将要执行的操作。我的建议在熟悉和信任你的AI助手提示工程之前始终使用interactive模式。只有在处理重复性高、模式固定的任务如按照固定模板生成组件时才考虑切换到auto-approve模式以提升效率。5.3 常见问题与解决方案问题1AI没有响应我的/speckit.plan命令。检查1确认VS Code底部状态栏显示的AI提供商是否正确。点击状态栏的AI图标可以切换。检查2在终端手动运行claude或gh copilot看是否能正常启动交互会话。确保CLI工具已正确安装和认证。检查3打开VS Code的输出面板选择“SpecKit”频道。这里会显示扩展发送给AI的原始命令和任何错误信息是排查问题的第一现场。问题2侧边栏不显示我的规格文件夹。检查1确认规格文件夹位于speckit.specDirectories配置的路径下。默认是specs/。检查2确保规格文件夹内至少存在.spec-context.json文件。这是扩展识别一个目录为“规格”的必要条件。检查3尝试点击侧边栏顶部的刷新按钮。问题3状态不同步比如任务都勾选了但状态没变成completed。原因状态变更依赖于对.spec-context.json文件的写入和文件系统的监听。有时VS Code的文件监听可能会延迟。解决手动执行SpecKit: Refresh All Specs命令通过命令面板CtrlShiftP。或者直接右键点击该规格选择“标记为完成”。问题4自定义工作流不生效。检查1speckit.customWorkflows配置的JSON语法是否正确尤其注意括号和逗号。检查2确保工作流中的command字符串与你实际在AI CLI中使用的命令完全一致包括前缀/和命令格式。检查3新建一个规格测试。已有规格的工作流类型在创建时就被持久化在它的.spec-context.json里了修改全局配置不会影响已有规格。5.4 性能与离线考量SpecKit Companion采用了“离线优先”的UI设计。它的字体和图标都打包在扩展内部。这意味着即使你在飞机上没有网络工作流编辑器、规格查看器的渲染也完全正常不会因为无法加载外部资源而出现布局错乱。这是一个非常贴心的设计保证了核心体验的可靠性。经过数月的使用SpecKit Companion已经彻底改变了我与AI协作开发软件的方式。它把原本松散、随性的对话变成了一个严谨、可视化的工程项目管理过程。最大的收获不是自动化本身而是过程的可视化和上下文的有序传承。我再也不用在多个聊天窗口间跳跃寻找某个功能的原始需求或设计决策一切都有迹可循井然有序。如果你也在深度使用AI进行编程并且对当前“一问一答”的碎片化模式感到效率瓶颈我强烈建议你尝试将SpecKit Companion引入你的工作流。初期可能需要一点时间来适应和配置但一旦跑通它带来的清晰度和掌控感会让你觉得这一切都是值得的。
SpecKit Companion：AI编程助手工作流引擎，实现规范驱动开发
发布时间：2026/7/31 9:29:42
1. 项目概述一个为AI开发者量身打造的SpecKit伴侣如果你和我一样每天都在和Claude Code、GitHub Copilot这类AI编程助手打交道那你肯定也遇到过类似的困扰一个功能需求从最初的构思到最终的代码实现中间要经历“写需求文档”、“做技术设计”、“拆解任务清单”好几个阶段。这些文档散落在不同的Markdown文件里状态全靠记忆进度难以追踪更别提让AI助手连贯地理解整个开发流程了。SpecKit Companion这个我最近深度使用并贡献了代码的VS Code扩展就是为了解决这个痛点而生的。简单来说它是一个专为“规范驱动开发”设计的项目看板和工作流引擎直接集成在你的VS Code侧边栏。它不是一个独立的AI工具而是你现有AI助手Claude、Copilot、Gemini等的“驾驶舱”。你可以在这里用结构化的方式定义功能规格然后驱动AI助手按阶段Specify - Plan - Tasks - Implement去执行所有产出和状态变更都会被自动追踪和可视化。这就像给你的AI编程工作流装上了进度条和导航仪让“人机协作”从零散的对话变成了一个可管理、可复现的工程项目。2. 核心设计理念与架构解析2.1 为什么是“规范驱动开发”在深入细节之前有必要先聊聊SpecKit Companion背后的哲学Spec-Driven Development。这并非一个全新的概念但在AI时代被赋予了新的生命力。传统的SDD强调“先写规范再写代码”以减少歧义和返工。而当你的“执行者”变成了AI时一份清晰、结构化的规范就显得更为关键。AI需要明确的指令和上下文才能产出可靠的代码。SpecKit Companion将这一理念工具化。它认为一个功能的开发周期应该被明确定义为几个阶段每个阶段有明确的输入如上阶段的产出、动作调用哪个AI命令和输出生成的Markdown文档。整个扩展的核心就是围绕“阶段”、“状态”和“上下文”这三个概念来构建的。2.2 核心架构状态集中管理与事件驱动SpecKit Companion的架构非常清晰其核心是一个名为.spec-context.json的文件。我称之为“单一事实来源”文件。这个文件位于每个“规格”目录下记录了关于这个功能的所有元数据当前阶段这个功能正处在specifying明确需求还是implementing实施中历史记录每个阶段是何时开始、何时结束的甚至包含了更细粒度的“子步骤”。状态流转每一次状态变更比如从“规划中”切换到“任务拆解”都会被记录包括变更时间、触发来源。工作流类型这个规格使用的是内置的speckit-companion流程还是自定义的agent-teams-lite流程重要提示所有在侧边栏看到的可视化信息——那个显示当前步骤的徽章、步骤旁边的绿色对勾或蓝色脉冲光效、甚至是底部操作按钮的文案——全部是从这个.spec-context.json文件实时读取并渲染的。扩展绝不会通过简单地检查spec.md文件是否存在来判断“需求阶段”是否完成。这种设计保证了状态判断的准确性和可扩展性。整个扩展是事件驱动的。当你在界面上点击“批准”或“重新生成”按钮时扩展会做两件事更新状态首先同步更新本地的.spec-context.json文件写入新的status和stepHistory。驱动AI然后根据配置向对应的AI CLI工具如claude命令发送相应的指令如/speckit.plan。这种“状态先行再执行动作”的模式确保了UI展示和实际后端过程的一致性即使AI命令执行失败或耗时较长前端状态也已经更新避免了歧义。2.3 多AI提供商的无缝适配作为一个深度用户我特别欣赏它对多AI环境的支持。它不绑定任何单一的AI服务。通过speckit.aiProvider配置项你可以指定当前项目使用 Claude Code、GitHub Copilot CLI、Gemini CLI 还是 Codex CLI。它的聪明之处在于能自动识别并适配不同AI提供商的“引导文件”约定。例如当你使用Claude Code时它会去查找.claude/steering/目录下的引导文件而如果切换到GitHub Copilot则会去识别.github/copilot-instructions.md。这意味着SpecKit Companion充当了一个统一的交互层你只需要通过它来管理规格和流程底层可以灵活切换不同的AI引擎而不需要改变你的操作习惯。3. 核心功能深度体验与配置详解3.1 侧边栏你的AI开发指挥中心安装扩展后VS Code活动栏会出现一个烧杯图标。点击它主界面就展现在侧边栏。这里将所有内容分门别类规格这是核心区域你所有的功能开发单元都在这里。它又分为“进行中”、“已完成”、“已归档”三个可折叠区域一目了然。引导存放给AI的“公司规范”、“项目约定”等顶层指导文件。代理技能用于定义更复杂的AI角色和可复用的能力模块如果你使用支持多代理的工作流如Agent Teams Lite。钩子配置自动化触发脚本比如在某个阶段完成后自动运行测试。一个让我效率倍增的细节规格列表的标题栏有一个“展开/折叠全部”的切换按钮。当我在评审多个规格时可以一键收起所有详情快速浏览标题需要深入时再一键展开。这个状态是内存级的不持久化但非常符合临时性浏览的需求。右键点击任意规格会出现一个实用的上下文菜单。除了标记状态我最常用的是“在文件管理器中显示”它能立刻在Finder或资源管理器中打开该规格所在的文件夹方便我直接操作原始文件。3.2 可视化工作流编辑器让进度一目了然点击任何一个“进行中”的规格主编辑区就会变成一个可视化的工作流编辑器。这不是一个简单的Markdown预览而是一个交互式视图。编辑器顶部清晰地展示了当前规格所处的阶段流。当前阶段会以一个蓝色圆点高亮显示。如果某个阶段已经完成其前面会有一个绿色对勾。而如果AI正在为某个阶段执行任务比如正在生成plan.md该阶段标签下方会显示一个实时的计时器例如3m 22s并且阶段图标会呈现绿色的脉冲光效。这种视觉反馈极其重要让我在等待AI输出的同时能确切知道它正在处理哪个环节避免了盲目的等待。编辑器主体则渲染该规格的主要Markdown文档。对于包含Mermaid图表的内容它支持内联渲染和缩放控制这对于阅读复杂的技术架构图非常友好。3.3 行内评论像Code Review一样评审需求这是促进团队协作或自我迭代的关键功能。在浏览spec.md或plan.md时你可以像在GitHub上评论代码一样对某一行需求或设计提出疑问或建议。操作心得我通常会在“规划”阶段使用这个功能。当AI生成初步的技术方案后我会通读一遍对存疑的技术选型、可能的风险点直接添加行内评论。这些评论会被保存在规格目录下的一个独立文件中。之后我可以直接要求AI“请查看并回复第X行的评论”从而实现基于上下文的精准迭代。这比在聊天窗口里大段描述“关于XXX那一点”要高效和准确得多。3.4 安全机制为“危险操作”加上双保险开发中误操作难免。SpecKit Companion为几个关键的生命周期操作设计了防误触机制体现了其深思熟虑的一面重新生成点击后会触发一个持续5秒的撤销Toast提示。在这5秒内点击“撤销”或按Esc键操作就会被取消。这给了我反悔的机会防止因手滑而覆盖掉一份已经不错的产出。归档/完成/重新激活这些更永久的操作需要二次确认。第一次点击后按钮文字会变成“确认”并持续3秒。只有在3秒内再次点击操作才会生效。否则按钮会静默恢复原状。这个设计完美避免了在快速点击时造成的灾难性状态变更。3.5 深度配置打造属于你的工作流SpecKit Companion的默认四阶段工作流很好但它的强大之处在于其可扩展性。你可以通过VS Code的settings.json定义完全自定义的工作流。配置案例接入Agent Teams Lite假设你的团队使用更复杂的“Agent Teams Lite”框架进行多代理协作开发你可以这样配置{ speckit.customWorkflows: [ { name: agent-teams-lite, displayName: Agent Teams Lite (SDD), steps: [ { name: specify, label: 需求分析, command: sdd-spec, file: spec.md }, { name: plan, label: 技术设计, command: sdd-design, file: design.md, includeRelatedDocs: true }, { name: tasks, label: 任务拆解, command: sdd-tasks, file: tasks.md }, { name: review, label: 人工评审, actionOnly: true } ] } ], speckit.customCommands: [ { name: verify, title: 验证实现, command: /sdd-verify, step: tasks, tooltip: 运行测试验证代码是否符合规格 } ], speckit.defaultWorkflow: agent-teams-lite }配置解析与技巧steps这里完全重定义了工作流阶段。label可以本地化为中文。“actionOnly: true”的步骤如review不会生成文件只在工作流中作为一个可点击的动作按钮存在适合触发一些人工流程或外部工具。includeRelatedDocs这是一个非常实用的属性。当设置为true时该步骤如plan会自动将规格目录下所有未被其他步骤声明的.md文件收纳为其“相关文档”显示在侧边栏。这很适合管理那些在规划阶段产生的辅助性文档如api-design.md、db-schema.md等。customCommands你可以为特定阶段添加自定义的按钮。比如在“任务拆解”阶段增加一个“验证实现”按钮点击后会自动执行/sdd-verify命令。defaultWorkflow设置后新建规格时会默认使用这个工作流。避坑指南在定义自定义工作流时务必确保command字段的值与你本地AI CLI工具能识别的命令完全一致。例如Claude Code可能使用/speckit.plan而你的自定义SDD工具可能使用/sdd.design。如果命令不匹配点击按钮后AI将无法响应。最佳实践是先在终端手动测试一下命令是否有效。4. 实战从零开始一个功能开发周期让我们跟随一个真实的场景——“为用户添加双因素认证(2FA)功能”来体验完整的SpecKit Companion工作流。4.1 第一阶段明确需求创建规格在SpecKit侧边栏点击按钮弹出创建对话框。填写信息标题032-add-2fa-for-users描述详细描述背景、用户故事、业务目标。例如“作为用户我希望在登录时启用双因素认证以提高我的账户安全性。系统应支持TOTP标准并允许用户在后端恢复代码...”选择工作流使用默认的speckit-companion。附加截图可以将UI设计稿拖入对话框作为附件。提交点击“提交”扩展会做两件事在项目根目录的specs/下创建文件夹032-add-2fa-for-users/。在该文件夹内初始化一个.spec-context.json文件状态为draft并生成一个初始的spec.md文件框架。同时它会向配置的AI提供者如Claude Code发送/speckit.specify命令并将你的描述作为输入。现场记录此时侧边栏该规格的状态图标是蓝色的烧杯表示“进行中”。点开规格工作流编辑器显示当前处于“Specify”阶段并且该阶段图标开始绿色脉冲下方出现计时器。AI正在后台生成详细的规格文档。4.2 第二阶段技术规划当AI完成spec.md后.spec-context.json中的currentStep会自动更新为plan状态变为specified。工作流编辑器中“Specify”阶段前出现绿色对勾“Plan”阶段高亮为蓝色圆点。触发规划在工作流编辑器的“Plan”阶段区域点击“生成规划”按钮或“批准并继续”。AI执行扩展会发送/speckit.plan命令并将已完成的spec.md作为上下文提供给AI。产出AI会生成plan.md内容可能包括技术选型使用哪个2FA库如speakeasy、otplib数据模型变更用户表需要新增totp_secret和is_2fa_enabled字段。API设计GET /api/user/2fa/setup生成二维码POST /api/user/2fa/verify验证并启用POST /api/user/2fa/disable。实施策略先实现后端逻辑再开发前端设置界面最后更新登录流程。操作技巧在这个阶段我强烈建议使用行内评论功能。如果AI提出的某个库版本过旧或某个API设计不符合项目REST规范直接在该行添加评论。之后可以命令AI“请根据第15行和第22行的评论重新评估并更新技术方案。”4.3 第三阶段任务拆解规划确认无误后进入“Tasks”阶段。点击“生成任务清单”AI将基于spec.md和plan.md输出一个可执行的tasks.md文件。一份好的任务清单应该是这样的## 任务清单实现用户2FA功能 - [ ] **后端数据层** - [ ] 在users表中添加totp_secret (VARCHAR) 和 is_2fa_enabled (BOOLEAN) 字段。 - [ ] 创建数据库迁移脚本。 - [ ] **后端服务层** - [ ] 安装并配置 otplib 库。 - [ ] 实现生成TOTP密钥和QR码的服务函数。 - [ ] 实现验证TOTP代码的服务函数。 - [ ] **后端API层** - [ ] 实现 GET /api/user/2fa/setup 端点。 - [ ] 实现 POST /api/user/2fa/verify 端点。 - [ ] 实现 POST /api/user/2fa/disable 端点。 - [ ] 更新登录逻辑在2FA启用时要求二次验证。 - [ ] **前端设置界面** - [ ] 创建“安全设置”页面组件。 - [ ] 集成QR码显示组件。 - [ ] 实现验证码输入表单。 - [ ] **测试** - [ ] 编写后端服务单元测试。 - [ ] 编写API集成测试。 - [ ] 进行端到端流程测试。核心价值这个tasks.md文件成为了你和AI后续协作的精确“工单”。你可以手动勾选完成的任务也可以直接让AI根据某个任务项来编写代码。4.4 第四阶段实施与完成“Tasks”阶段完成后状态会变为ready-to-implement。此时工作流编辑器的底部主按钮会变成“开始实施”。驱动开发点击“开始实施”这通常不会直接生成一个巨大的代码文件而是将上下文切换到“实施”模式。你可以打开终端或者直接对AI说“请实现任务清单中的第1项为用户表添加2FA字段。”迭代与勾选AI生成迁移脚本后你进行审查、运行。确认无误后回到tasks.md手动勾选第一项。然后继续指挥AI完成下一项。状态流转当所有任务被勾选tasks.md中所有复选框变为- [x]时SpecKit Companion会检测到这一变化通过文件监听并自动将规格状态更新为completed。归档功能上线后你可以右键点击该规格选择“归档”。它会被移动到侧边栏的“已归档”区域.spec-context.json中的状态变为archived。项目目录保持原样便于未来查阅。个人体会这个流程将庞大的功能开发分解成了AI擅长处理的、离散的、上下文明确的子任务。你不再是漫无目的地向AI提问而是像一个项目经理在一个可视化的看板上有条不紊地分发和验收工作。5. 高级技巧与疑难排查5.1 自定义命令的妙用除了阶段性的主命令你可以在任何阶段注入自定义命令。例如我配置了一个在“Tasks”阶段使用的代码质量检查命令{ speckit.customCommands: [ { name: lint-and-test, title: 运行Lint和测试, command: npm run lint npm test, step: tasks, tooltip: 检查代码风格并运行单元测试, requiresSpecDir: true, autoExecute: false } ] }requiresSpecDir: true意味着命令会在当前规格的目录下执行。autoExecute: false意味着点击后命令会出现在终端面板等待回车确认而不是自动执行。这对于可能具有破坏性的命令如数据库迁移是个安全特性。5.2 权限模式的选择安全与效率的权衡在设置中speckit.permissionMode控制着AI CLI执行工具调用时的行为。interactive(推荐)AI在执行任何有副作用的操作如写入文件、运行脚本前会向你请求许可。这是最安全的模式。auto-approve(YOLO模式)跳过所有权限提示自动批准。这能极大加快AI的响应和操作速度但存在风险因为你无法预先审查AI将要执行的操作。我的建议在熟悉和信任你的AI助手提示工程之前始终使用interactive模式。只有在处理重复性高、模式固定的任务如按照固定模板生成组件时才考虑切换到auto-approve模式以提升效率。5.3 常见问题与解决方案问题1AI没有响应我的/speckit.plan命令。检查1确认VS Code底部状态栏显示的AI提供商是否正确。点击状态栏的AI图标可以切换。检查2在终端手动运行claude或gh copilot看是否能正常启动交互会话。确保CLI工具已正确安装和认证。检查3打开VS Code的输出面板选择“SpecKit”频道。这里会显示扩展发送给AI的原始命令和任何错误信息是排查问题的第一现场。问题2侧边栏不显示我的规格文件夹。检查1确认规格文件夹位于speckit.specDirectories配置的路径下。默认是specs/。检查2确保规格文件夹内至少存在.spec-context.json文件。这是扩展识别一个目录为“规格”的必要条件。检查3尝试点击侧边栏顶部的刷新按钮。问题3状态不同步比如任务都勾选了但状态没变成completed。原因状态变更依赖于对.spec-context.json文件的写入和文件系统的监听。有时VS Code的文件监听可能会延迟。解决手动执行SpecKit: Refresh All Specs命令通过命令面板CtrlShiftP。或者直接右键点击该规格选择“标记为完成”。问题4自定义工作流不生效。检查1speckit.customWorkflows配置的JSON语法是否正确尤其注意括号和逗号。检查2确保工作流中的command字符串与你实际在AI CLI中使用的命令完全一致包括前缀/和命令格式。检查3新建一个规格测试。已有规格的工作流类型在创建时就被持久化在它的.spec-context.json里了修改全局配置不会影响已有规格。5.4 性能与离线考量SpecKit Companion采用了“离线优先”的UI设计。它的字体和图标都打包在扩展内部。这意味着即使你在飞机上没有网络工作流编辑器、规格查看器的渲染也完全正常不会因为无法加载外部资源而出现布局错乱。这是一个非常贴心的设计保证了核心体验的可靠性。经过数月的使用SpecKit Companion已经彻底改变了我与AI协作开发软件的方式。它把原本松散、随性的对话变成了一个严谨、可视化的工程项目管理过程。最大的收获不是自动化本身而是过程的可视化和上下文的有序传承。我再也不用在多个聊天窗口间跳跃寻找某个功能的原始需求或设计决策一切都有迹可循井然有序。如果你也在深度使用AI进行编程并且对当前“一问一答”的碎片化模式感到效率瓶颈我强烈建议你尝试将SpecKit Companion引入你的工作流。初期可能需要一点时间来适应和配置但一旦跑通它带来的清晰度和掌控感会让你觉得这一切都是值得的。
