OpenSpec 深度指南从原理到实战让 AI 编程告别返工AI 辅助编程的痛点不是AI 不够聪明而是需求没有对齐。OpenSpec 通过一套轻量级的规范驱动工作流让开发者在写代码之前先与 AI 达成共识将 AI 编码从一次性对话升级为可追溯、可复盘、可协作的工程化实践。一、OpenSpec 是什么OpenSpec是由 Fission-AI 团队开源的一款规范驱动开发框架Spec-Driven Development Framework专门为解决 AI 编程中的核心痛点——需求对齐而设计。在传统的 AI 辅助开发中开发者直接把模糊的需求丢给 AIAI 生成代码后往往遗漏关键功能、添加冗余逻辑、与现有架构不兼容——更糟糕的是每次对话结束需求历史就消失了下一次又要从零开始。OpenSpec 的设计哲学可以用五个关键词概括流动而非僵化、迭代而非瀑布、简单而非复杂、为存量项目而生、从个人项目到企业级扩展。它的核心理念非常简单在写代码之前先把需求、设计、任务全部落地成文件让规范和代码一样纳入版本管理。核心设计哲学原则含义流动而非僵化传统规范系统将你锁定在阶段中先规划再实现然后完成。OpenSpec 允许你按任何有意义的顺序创建产物随时更新任何文档。迭代而非瀑布需求会变化理解会加深。最初看起来不错的方案在看到代码库后可能无法成立。OpenSpec 拥抱这种现实。简单而非复杂几秒钟初始化立即开始工作。不挡你的路不要求大量设置、严格格式或繁重流程。存量项目优先大多数软件工作不是从零开始而是在已有系统上迭代改造。OpenSpec 基于 Delta 的方法让描述改了什么变得自然而直观。二、OpenSpec 能解决什么问题传统 AI 编程的三大痛点痛点传统方式OpenSpec 方案上下文膨胀长对话后 AI 开始遗忘早期指令输出质量断崖式下降每一次 apply / verify / archive 都建议重新开一个会话上下文从零开始始终保持高质量AI 容易偷懒任务多时 AI 跳过步骤、敷衍实现、“假装完成”任务拆成 tasks.md 清单verify 命令逐项检查是否完成AI 无法跳过无法复盘对话结束就没了没有文档沉淀换人接手无从查起每次变更都在 openspec/ 目录下留下 proposal、design、tasks、spec形成活文档与同类工具对比工具特点OpenSpec 的优势Spec Kit (GitHub)功能全面但重量级Python 依赖严格阶段门控更轻量流程灵活自由迭代Kiro (AWS)IDE 深度集成仅限 Claude 模型不锁定工具支持 25 AI 助手无规范开发自由但混乱结果不可预测低门槛引入规范不增加繁文缛节核心收益OpenSpec 带来的价值可以浓缩为四点减少返工——在编码前对齐需求避免方向性偏差持久上下文——规范即文档不随会话结束而消失团队协作——基于 Git 的规范审查和共享新人快速上手工具无关——一套规范可以在 Cursor、Claude Code、Copilot 等任意工具间复用。三、基于什么原理Delta Specs 机制OpenSpec 最核心的机制是Delta Specs增量规范。这是让它能适用于已有项目改造的关键设计。什么是对比增量规范传统规范系统要求你描述整个系统的行为而 OpenSpec 的对比增量规范只记录本次变更涉及的部分。假设系统有 100 个 API本次只新增 1 个——Delta Spec 只描述这 1 个新 API 的行为不会把已有的 100 个再写一遍。每次/opsx:propose在changes/name/specs/下生成增量 spec包含三部分Delta 节含义归档时操作ADDED Requirements新增的行为追加到主规范MODIFIED Requirements修改的已有行为替换主规范中现有需求REMOVED Requirements废弃的行为从主规范中删除整体架构OpenSpec 将工作组织为两个主要区域specs/是权威基准描述系统当前行为归档时合并changes/是提议中的修改每个变更一个独立文件夹。openspec/ ├── specs/ # 主规范单一事实来源 │ └── domain/ │ └── spec.md ├── changes/ # 提议中的变更 │ └── change-name/ │ ├── proposal.md # 做什么、为什么 │ ├── design.md # 技术方案 │ ├── tasks.md # 执行任务清单 │ └── specs/ # 增量规范正在变化的内容 │ └── domain/ │ └── spec.md └── config.yaml这种分离的精妙之处在于多个变更可以并行存在而不冲突在变更影响主规范之前先进行审查归档时 Delta 会干净地合并回主规范。四个核心产物文件定位受众何时生成proposal.md需求变更说明做什么、为什么、影响范围所有人/opsx:proposedesign.md技术实现方案架构、接口、数据模型开发/opsx:proposetasks.md任务拆分清单可执行的 step-by-step开发 AI/opsx:proposespec.md增量规格本次变更的行为描述产品 测试/opsx:propose产物之间存在依赖关系proposal根节点→ specs 和 design可并行→ tasks需 specs 和 design 都完成。这种设计让每个产物都有明确的上下文AI 不会凭空发挥。四、怎么干从安装到归档的完整流程4.1 环境安装前置条件Node.js 20.19.0 或更高版本。OpenSpec 支持 npm、pnpm、yarn、bun 和 nix 多种安装方式# npm 全局安装npminstall-gfission-ai/openspeclatest# 验证安装openspec--version4.2 项目初始化进入你的项目目录执行初始化命令cdyour-project openspec init初始化过程中OpenSpec 会询问你使用的 AI 工具Claude Code、Cursor、Windsurf 等 25 选项按空格键勾选你需要的工具回车确认后会自动生成对应的配置文件。如果你使用 trae 插件注意 trae 只生成 skills 文件不会生成 commands 文件。4.3 核心工作流OpenSpec 的推荐工作流是/opsx:explore → /opsx:propose → 人工审核 → /opsx:apply → /opsx:verify → 人工审核代码 → /opsx:archive。两个关键原则原则一重新开一个会话。Propose提案、Apply实施、Verify验收、Archive归档各自使用独立的会话“该省省该花花”。每次从零开始的上下文才能保证 AI 输出质量不会逐轮下降。原则二不要手动改文件。所有 .md 文件的修改都通过 AI 完成。手动修改 proposal.md 会导致 tasks.md 与 proposal.md/design.md 不一致。如果 AI 理解不对在同一个会话中告诉它让它自己改同时更新所有相关的 .md 文件。完整工作流七步探索需求—/opsx:explore 描述提交提案—/opsx:propose 描述人工审核— 审查 proposal / design / specAI 实施—/opsx:apply spec-idAI 验收—/opsx:verify spec-id人工验收— 审查代码质量归档变更—/opsx:archive spec-id4.4 常用命令速查命令用途备注openspec init初始化项目仅首次/opsx:explore 描述需求探索 / 头脑风暴可在空项目使用不产生文件/opsx:propose 描述创建变更提案生成 proposal/design/tasks/spec/opsx:apply spec-idAI 实施代码重新开会话/opsx:verify spec-idAI 验收代码重新开会话逐项检查 tasks/opsx:archive spec-id归档变更重新开会话合并到主规范openspec config profile配置 AI Agent / 工作流切换简洁模式或扩展模式openspec update刷新项目中的 AI 指引和斜杠命令升级后需要运行4.5 两种工作流模式OpenSpec 提供两种模式简洁工作流推荐新手只需三个命令propose → apply → archive扩展工作流适合复杂项目提供更多控制包括/opsx:new、/opsx:continue、/opsx:ff、/opsx:bulk-archive等。通过openspec config profile切换。五、实战案例案例一新增一个物流数据推送接口以下是来自飞书文档的真实案例——在分拣机系统中需要从推送简版落格数据升级为推送完整分拣明细数据DropChuteEventListener 落格事件触发后仅推送了简版的 DropChuteOrderBO批次号、运单号、格口号、组织、分拣序号到 Order 的 /order/api/sortBag/scan 接口。Order 系统需要一份更完整的分拣明细数据包含重量、体积、分拣时间、格口备注、是否签出等以支撑后续的业务分析和状态追踪。需要额外推送一条完整的 sorter_order 数据到新接口 /order/api/sorterApi/receiveChuteData。步骤一提交提案在 Claude Code 中执行/opsx:propose DropChuteEventListener 落格事件触发后仅推送了简版的 DropChuteOrderBO……需要额外推送一条完整的 sorter_order 数据到新接口 /order/api/sorterApi/receiveChuteDataAI 会在openspec/changes/下自动创建order-chute-receive-push/目录包含 proposal.md、spec.md、design.md、tasks.md 四个文件。步骤二人工审核开发人员需要仔细阅读 spec.md纯业务描述可与产品、测试一起看、proposal.md需求目的和影响范围、design.md技术方案。如果发现 AI 理解有误在同一个会话中直接告诉它让它修改相应的 .md 文件。步骤三AI 实施重新开一个会话执行/opsx:apply order-chute-receive-pushAI 会按照 tasks.md 中的清单逐项实现代码。如果发现 bug一定要让 AI 改不要手动改并且要求 AI 将变更同步回 spec 文档。步骤四AI 验收再次重新开一个会话执行/opsx:verify order-chute-receive-pushAI 会逐项检查 tasks.md 中每个任务是否完成。如果任务非常多AI 大概率会偷懒这一步能让它自己发现遗漏项。步骤五人工验收 归档人工审查代码质量后重新开一个会话执行归档/opsx:archive order-chute-receive-push归档操作会将整个变更目录移到 archive/ 下同时将增量 spec 合并到主规范 specs/ 中。案例二为项目添加深色模式一个更简单的例子——为 Web 应用添加深色模式支持/opsx:propose add-dark-modeAI 生成 proposal.md描述变更范围添加主题切换组件、实现 CSS 变量系统、支持 localStorage 记忆用户偏好、默认跟随系统设置。design.md 明确技术方案使用 React Context 管理主题状态CSS 自定义属性支持运行时切换。tasks.md 拆分为具体步骤## 1. 主题基础设施 - [ ] 1.1 创建带有亮/暗状态的 ThemeContext - [ ] 1.2 为颜色添加 CSS 自定义属性 - [ ] 1.3 实现 localStorage 持久化 - [ ] 1.4 添加系统偏好检测 ## 2. UI 组件 - [ ] 2.1 创建 ThemeToggle 组件 - [ ] 2.2 在设置页面添加切换 - [ ] 2.3 更新 Header 包含快速切换 ## 3. 样式 - [ ] 3.1 定义暗色主题调色板 - [ ] 3.2 更新组件使用 CSS 变量确认无误后执行/opsx:apply开始实现完成后/opsx:archive归档。六、常见问题与解决方案Q1需求不明确怎么办使用/opsx:explore与 AI 进行头脑风暴让 AI 帮你理清需求边界和实现路径。注意头脑风暴时上下文很容易膨胀更好的做法是将头脑风暴的结论输出为文档或记住核心要点然后重新开一个会话用/opsx:propose创建正式提案。Q2生成的提案不符合要求怎么办切记不要手动改提案文件手动修改会导致 tasks.md 与 proposal.md/design.md 不一致。正确的做法是在同一个会话中告诉 AI 哪里不符合要求让 AI 修改 proposal.md、design.md同时更新 tasks.md。确认所有 .md 文件一致后再进行 apply。Q3生成的代码有 Bug 怎么办让 AI 自己修不要手动改。在同一个会话中告诉 AI bug 在哪、预期行为是什么。AI 修完代码后必须要求 AI 把变更同步回 spec 文档design.md、spec.md。如果 bug 是需求理解偏差导致的回溯修改 proposal.md。修完后重新执行/opsx:verify确保所有任务仍然通过。核心理念如果你手动改了代码但 spec 没更新下次别人或你自己用 OpenSpec 时会基于过时的 spec 重新生成bug 就会回来。Q4简单需求怎么办人改还是 AI 改如果人改起来比较快可以直接人改。但改完之后要让 AI 把当前变更同步回对应的 spec 中。Prompt 可以这样写“整理当前未提交代码逻辑变更同步回对应的 spec”。AI 会自己读 openspec 目录下的文件自己找对应的 spec完成同步。Q5AI 写的代码不符合规范怎么办这就是Harness Engineering的核心。当 AI 写出的代码不符合要求我们就要约束 AI遇到不规范代码 → 创建rule如字符串判空优先使用 StringUtils为这条规则生成一个 rule并在编写 Java 代码时生效遇到重复性人工操作 → 创建skill封装常用操作流程遇到上下文丢失 → 创建memory项目偏好、个人习惯Q6多人协作时归档会不会产生大量冲突理论上冲突概率很低只要你们修改的不是同一个功能点。OpenSpec 会扫描 specs 目录自动判断增量是修改已有规格还是创建新规格。如果多人修改了同一个文件的同一区域才可能产生冲突否则自动合并。这就是为什么不要手动改 spec——手动修改绕过了 OpenSpec 的合并逻辑会导致下次归档时出现真正的冲突。Q7OpenSpec 和 AI 工具的 Plan Mode 有什么区别Plan Mode 适合单次对话内的规划。OpenSpec 专注于跨会话、可共享、可迭代的规划贯穿整个开发生命周期。规划产物以文件形式存在 Git 仓库中不随对话结束而消失。Q8切换 AI 工具后规范还能用吗OpenSpec 的定位是通用规划层与具体 AI 工具解耦。你的规范可以在 Cursor、Claude Code、Copilot 等任意工具间复用。目前 OpenSpec 已支持 25 款 AI 工具。Q9AI 验证之后发现任务没完成怎么办AI 写完代码后如果任务非常多AI 大概率会偷懒。/opsx:verify会逐项检查 tasks.md 中每个任务是否完成。如果发现有未完成的或者完成的结果不符合预期AI 都会检查出来。只需要再次执行/opsx:apply spec-id命令即可。Q10最佳实践总结四个核心原则重新开一个会话—— 提案、实施、验收、归档各自独立不要手动改文件—— 所有 .md 文件的修改都通过 AI 完成规范先行—— 如果 AI 代码不符合项目规范立即创建 rule/skill/memory 约束它Bug 溯源—— 修完 bug 必须同步更新 spec否则下次 AI 会重新引入七、总结OpenSpec 为 AI 辅助编程带来了一种全新的工作方式规范先行代码随后。它不是要取代你与 AI 的对话而是将对话中产生的共识沉淀为可追溯、可共享、可迭代的文档。如果你正在使用 AI 辅助编程不妨花 10 分钟尝试一下 OpenSpec。这 10 分钟的规划可能会为你省下数小时的返工时间。AI 编码的瓶颈从来不是AI 不够聪明而是**“需求没有对齐”**——OpenSpec 解决的正是这个问题。参考资源资源链接OpenSpec 中文官方文档https://radebit.github.io/OpenSpec-Docs-zh/#overviewOpenSpec 中文文档 - 概览https://radebit.github.io/OpenSpec-Docs-zh/#overviewCSDNOpenSpec 安装与使用详解https://blog.csdn.net/qq_18948359/article/details/162639656GitHub 仓库https://github.com/Fission-AI/OpenSpec官方网站https://openspec.dev/npm 包https://www.npmjs.com/package/fission-ai/openspecDiscord 社区https://discord.gg/YctCnvvshC
OpenSpec 深度指南从原理到实战让 AI 编程告别返工AI 辅助编程的痛点不是AI 不够聪明而是需求没有对齐。OpenSpec 通过一套轻量级的规范驱动工作流让开发者在写代码之前先与 AI 达成共识将 AI 编码从一次性对话升级为可追溯、可复盘、可协作的工程化实践。一、OpenSpec 是什么OpenSpec是由 Fission-AI 团队开源的一款规范驱动开发框架Spec-Driven Development Framework专门为解决 AI 编程中的核心痛点——需求对齐而设计。在传统的 AI 辅助开发中开发者直接把模糊的需求丢给 AIAI 生成代码后往往遗漏关键功能、添加冗余逻辑、与现有架构不兼容——更糟糕的是每次对话结束需求历史就消失了下一次又要从零开始。OpenSpec 的设计哲学可以用五个关键词概括流动而非僵化、迭代而非瀑布、简单而非复杂、为存量项目而生、从个人项目到企业级扩展。它的核心理念非常简单在写代码之前先把需求、设计、任务全部落地成文件让规范和代码一样纳入版本管理。核心设计哲学原则含义流动而非僵化传统规范系统将你锁定在阶段中先规划再实现然后完成。OpenSpec 允许你按任何有意义的顺序创建产物随时更新任何文档。迭代而非瀑布需求会变化理解会加深。最初看起来不错的方案在看到代码库后可能无法成立。OpenSpec 拥抱这种现实。简单而非复杂几秒钟初始化立即开始工作。不挡你的路不要求大量设置、严格格式或繁重流程。存量项目优先大多数软件工作不是从零开始而是在已有系统上迭代改造。OpenSpec 基于 Delta 的方法让描述改了什么变得自然而直观。二、OpenSpec 能解决什么问题传统 AI 编程的三大痛点痛点传统方式OpenSpec 方案上下文膨胀长对话后 AI 开始遗忘早期指令输出质量断崖式下降每一次 apply / verify / archive 都建议重新开一个会话上下文从零开始始终保持高质量AI 容易偷懒任务多时 AI 跳过步骤、敷衍实现、“假装完成”任务拆成 tasks.md 清单verify 命令逐项检查是否完成AI 无法跳过无法复盘对话结束就没了没有文档沉淀换人接手无从查起每次变更都在 openspec/ 目录下留下 proposal、design、tasks、spec形成活文档与同类工具对比工具特点OpenSpec 的优势Spec Kit (GitHub)功能全面但重量级Python 依赖严格阶段门控更轻量流程灵活自由迭代Kiro (AWS)IDE 深度集成仅限 Claude 模型不锁定工具支持 25 AI 助手无规范开发自由但混乱结果不可预测低门槛引入规范不增加繁文缛节核心收益OpenSpec 带来的价值可以浓缩为四点减少返工——在编码前对齐需求避免方向性偏差持久上下文——规范即文档不随会话结束而消失团队协作——基于 Git 的规范审查和共享新人快速上手工具无关——一套规范可以在 Cursor、Claude Code、Copilot 等任意工具间复用。三、基于什么原理Delta Specs 机制OpenSpec 最核心的机制是Delta Specs增量规范。这是让它能适用于已有项目改造的关键设计。什么是对比增量规范传统规范系统要求你描述整个系统的行为而 OpenSpec 的对比增量规范只记录本次变更涉及的部分。假设系统有 100 个 API本次只新增 1 个——Delta Spec 只描述这 1 个新 API 的行为不会把已有的 100 个再写一遍。每次/opsx:propose在changes/name/specs/下生成增量 spec包含三部分Delta 节含义归档时操作ADDED Requirements新增的行为追加到主规范MODIFIED Requirements修改的已有行为替换主规范中现有需求REMOVED Requirements废弃的行为从主规范中删除整体架构OpenSpec 将工作组织为两个主要区域specs/是权威基准描述系统当前行为归档时合并changes/是提议中的修改每个变更一个独立文件夹。openspec/ ├── specs/ # 主规范单一事实来源 │ └── domain/ │ └── spec.md ├── changes/ # 提议中的变更 │ └── change-name/ │ ├── proposal.md # 做什么、为什么 │ ├── design.md # 技术方案 │ ├── tasks.md # 执行任务清单 │ └── specs/ # 增量规范正在变化的内容 │ └── domain/ │ └── spec.md └── config.yaml这种分离的精妙之处在于多个变更可以并行存在而不冲突在变更影响主规范之前先进行审查归档时 Delta 会干净地合并回主规范。四个核心产物文件定位受众何时生成proposal.md需求变更说明做什么、为什么、影响范围所有人/opsx:proposedesign.md技术实现方案架构、接口、数据模型开发/opsx:proposetasks.md任务拆分清单可执行的 step-by-step开发 AI/opsx:proposespec.md增量规格本次变更的行为描述产品 测试/opsx:propose产物之间存在依赖关系proposal根节点→ specs 和 design可并行→ tasks需 specs 和 design 都完成。这种设计让每个产物都有明确的上下文AI 不会凭空发挥。四、怎么干从安装到归档的完整流程4.1 环境安装前置条件Node.js 20.19.0 或更高版本。OpenSpec 支持 npm、pnpm、yarn、bun 和 nix 多种安装方式# npm 全局安装npminstall-gfission-ai/openspeclatest# 验证安装openspec--version4.2 项目初始化进入你的项目目录执行初始化命令cdyour-project openspec init初始化过程中OpenSpec 会询问你使用的 AI 工具Claude Code、Cursor、Windsurf 等 25 选项按空格键勾选你需要的工具回车确认后会自动生成对应的配置文件。如果你使用 trae 插件注意 trae 只生成 skills 文件不会生成 commands 文件。4.3 核心工作流OpenSpec 的推荐工作流是/opsx:explore → /opsx:propose → 人工审核 → /opsx:apply → /opsx:verify → 人工审核代码 → /opsx:archive。两个关键原则原则一重新开一个会话。Propose提案、Apply实施、Verify验收、Archive归档各自使用独立的会话“该省省该花花”。每次从零开始的上下文才能保证 AI 输出质量不会逐轮下降。原则二不要手动改文件。所有 .md 文件的修改都通过 AI 完成。手动修改 proposal.md 会导致 tasks.md 与 proposal.md/design.md 不一致。如果 AI 理解不对在同一个会话中告诉它让它自己改同时更新所有相关的 .md 文件。完整工作流七步探索需求—/opsx:explore 描述提交提案—/opsx:propose 描述人工审核— 审查 proposal / design / specAI 实施—/opsx:apply spec-idAI 验收—/opsx:verify spec-id人工验收— 审查代码质量归档变更—/opsx:archive spec-id4.4 常用命令速查命令用途备注openspec init初始化项目仅首次/opsx:explore 描述需求探索 / 头脑风暴可在空项目使用不产生文件/opsx:propose 描述创建变更提案生成 proposal/design/tasks/spec/opsx:apply spec-idAI 实施代码重新开会话/opsx:verify spec-idAI 验收代码重新开会话逐项检查 tasks/opsx:archive spec-id归档变更重新开会话合并到主规范openspec config profile配置 AI Agent / 工作流切换简洁模式或扩展模式openspec update刷新项目中的 AI 指引和斜杠命令升级后需要运行4.5 两种工作流模式OpenSpec 提供两种模式简洁工作流推荐新手只需三个命令propose → apply → archive扩展工作流适合复杂项目提供更多控制包括/opsx:new、/opsx:continue、/opsx:ff、/opsx:bulk-archive等。通过openspec config profile切换。五、实战案例案例一新增一个物流数据推送接口以下是来自飞书文档的真实案例——在分拣机系统中需要从推送简版落格数据升级为推送完整分拣明细数据DropChuteEventListener 落格事件触发后仅推送了简版的 DropChuteOrderBO批次号、运单号、格口号、组织、分拣序号到 Order 的 /order/api/sortBag/scan 接口。Order 系统需要一份更完整的分拣明细数据包含重量、体积、分拣时间、格口备注、是否签出等以支撑后续的业务分析和状态追踪。需要额外推送一条完整的 sorter_order 数据到新接口 /order/api/sorterApi/receiveChuteData。步骤一提交提案在 Claude Code 中执行/opsx:propose DropChuteEventListener 落格事件触发后仅推送了简版的 DropChuteOrderBO……需要额外推送一条完整的 sorter_order 数据到新接口 /order/api/sorterApi/receiveChuteDataAI 会在openspec/changes/下自动创建order-chute-receive-push/目录包含 proposal.md、spec.md、design.md、tasks.md 四个文件。步骤二人工审核开发人员需要仔细阅读 spec.md纯业务描述可与产品、测试一起看、proposal.md需求目的和影响范围、design.md技术方案。如果发现 AI 理解有误在同一个会话中直接告诉它让它修改相应的 .md 文件。步骤三AI 实施重新开一个会话执行/opsx:apply order-chute-receive-pushAI 会按照 tasks.md 中的清单逐项实现代码。如果发现 bug一定要让 AI 改不要手动改并且要求 AI 将变更同步回 spec 文档。步骤四AI 验收再次重新开一个会话执行/opsx:verify order-chute-receive-pushAI 会逐项检查 tasks.md 中每个任务是否完成。如果任务非常多AI 大概率会偷懒这一步能让它自己发现遗漏项。步骤五人工验收 归档人工审查代码质量后重新开一个会话执行归档/opsx:archive order-chute-receive-push归档操作会将整个变更目录移到 archive/ 下同时将增量 spec 合并到主规范 specs/ 中。案例二为项目添加深色模式一个更简单的例子——为 Web 应用添加深色模式支持/opsx:propose add-dark-modeAI 生成 proposal.md描述变更范围添加主题切换组件、实现 CSS 变量系统、支持 localStorage 记忆用户偏好、默认跟随系统设置。design.md 明确技术方案使用 React Context 管理主题状态CSS 自定义属性支持运行时切换。tasks.md 拆分为具体步骤## 1. 主题基础设施 - [ ] 1.1 创建带有亮/暗状态的 ThemeContext - [ ] 1.2 为颜色添加 CSS 自定义属性 - [ ] 1.3 实现 localStorage 持久化 - [ ] 1.4 添加系统偏好检测 ## 2. UI 组件 - [ ] 2.1 创建 ThemeToggle 组件 - [ ] 2.2 在设置页面添加切换 - [ ] 2.3 更新 Header 包含快速切换 ## 3. 样式 - [ ] 3.1 定义暗色主题调色板 - [ ] 3.2 更新组件使用 CSS 变量确认无误后执行/opsx:apply开始实现完成后/opsx:archive归档。六、常见问题与解决方案Q1需求不明确怎么办使用/opsx:explore与 AI 进行头脑风暴让 AI 帮你理清需求边界和实现路径。注意头脑风暴时上下文很容易膨胀更好的做法是将头脑风暴的结论输出为文档或记住核心要点然后重新开一个会话用/opsx:propose创建正式提案。Q2生成的提案不符合要求怎么办切记不要手动改提案文件手动修改会导致 tasks.md 与 proposal.md/design.md 不一致。正确的做法是在同一个会话中告诉 AI 哪里不符合要求让 AI 修改 proposal.md、design.md同时更新 tasks.md。确认所有 .md 文件一致后再进行 apply。Q3生成的代码有 Bug 怎么办让 AI 自己修不要手动改。在同一个会话中告诉 AI bug 在哪、预期行为是什么。AI 修完代码后必须要求 AI 把变更同步回 spec 文档design.md、spec.md。如果 bug 是需求理解偏差导致的回溯修改 proposal.md。修完后重新执行/opsx:verify确保所有任务仍然通过。核心理念如果你手动改了代码但 spec 没更新下次别人或你自己用 OpenSpec 时会基于过时的 spec 重新生成bug 就会回来。Q4简单需求怎么办人改还是 AI 改如果人改起来比较快可以直接人改。但改完之后要让 AI 把当前变更同步回对应的 spec 中。Prompt 可以这样写“整理当前未提交代码逻辑变更同步回对应的 spec”。AI 会自己读 openspec 目录下的文件自己找对应的 spec完成同步。Q5AI 写的代码不符合规范怎么办这就是Harness Engineering的核心。当 AI 写出的代码不符合要求我们就要约束 AI遇到不规范代码 → 创建rule如字符串判空优先使用 StringUtils为这条规则生成一个 rule并在编写 Java 代码时生效遇到重复性人工操作 → 创建skill封装常用操作流程遇到上下文丢失 → 创建memory项目偏好、个人习惯Q6多人协作时归档会不会产生大量冲突理论上冲突概率很低只要你们修改的不是同一个功能点。OpenSpec 会扫描 specs 目录自动判断增量是修改已有规格还是创建新规格。如果多人修改了同一个文件的同一区域才可能产生冲突否则自动合并。这就是为什么不要手动改 spec——手动修改绕过了 OpenSpec 的合并逻辑会导致下次归档时出现真正的冲突。Q7OpenSpec 和 AI 工具的 Plan Mode 有什么区别Plan Mode 适合单次对话内的规划。OpenSpec 专注于跨会话、可共享、可迭代的规划贯穿整个开发生命周期。规划产物以文件形式存在 Git 仓库中不随对话结束而消失。Q8切换 AI 工具后规范还能用吗OpenSpec 的定位是通用规划层与具体 AI 工具解耦。你的规范可以在 Cursor、Claude Code、Copilot 等任意工具间复用。目前 OpenSpec 已支持 25 款 AI 工具。Q9AI 验证之后发现任务没完成怎么办AI 写完代码后如果任务非常多AI 大概率会偷懒。/opsx:verify会逐项检查 tasks.md 中每个任务是否完成。如果发现有未完成的或者完成的结果不符合预期AI 都会检查出来。只需要再次执行/opsx:apply spec-id命令即可。Q10最佳实践总结四个核心原则重新开一个会话—— 提案、实施、验收、归档各自独立不要手动改文件—— 所有 .md 文件的修改都通过 AI 完成规范先行—— 如果 AI 代码不符合项目规范立即创建 rule/skill/memory 约束它Bug 溯源—— 修完 bug 必须同步更新 spec否则下次 AI 会重新引入七、总结OpenSpec 为 AI 辅助编程带来了一种全新的工作方式规范先行代码随后。它不是要取代你与 AI 的对话而是将对话中产生的共识沉淀为可追溯、可共享、可迭代的文档。如果你正在使用 AI 辅助编程不妨花 10 分钟尝试一下 OpenSpec。这 10 分钟的规划可能会为你省下数小时的返工时间。AI 编码的瓶颈从来不是AI 不够聪明而是**“需求没有对齐”**——OpenSpec 解决的正是这个问题。参考资源资源链接OpenSpec 中文官方文档https://radebit.github.io/OpenSpec-Docs-zh/#overviewOpenSpec 中文文档 - 概览https://radebit.github.io/OpenSpec-Docs-zh/#overviewCSDNOpenSpec 安装与使用详解https://blog.csdn.net/qq_18948359/article/details/162639656GitHub 仓库https://github.com/Fission-AI/OpenSpec官方网站https://openspec.dev/npm 包https://www.npmjs.com/package/fission-ai/openspecDiscord 社区https://discord.gg/YctCnvvshC
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
