本周我在公司内部进行了一次技术分享，介绍了一套完整的 AI 辅助编码工作流，涵盖 Chat、OpenSpec、Coding 三个核心阶段，以及通过 Agent Skills 持续沉淀团队能力的方法论。
引言：为什么需要一套工作流
你是否也遇到过这些问题
相信很多人在使用 AI 编码工具时，都踩过类似的坑：
- 改了不该改的文件：AI 在生成代码时，会修改与当前需求无关的文件，引入意外变更
- 组件组织形式不对：生成的组件结构不符合团队规范
- 单个组件代码超过 500 行：新需求实现时，一个组件承担了太多逻辑
- ......
这些问题的背后，原因可以归为三类：
| 原因 | 表现 | 结果 |
|---|---|---|
| 需求描述模糊 | 「帮我做一个用户管理功能」—— AI 不知道你要的是增删改查、权限控制还是数据统计 | AI 理解偏差，来回返工 |
| 边界条件缺失 | AI 只实现功能主流程，项目约定的处理方式它不知道 | 生成代码违背团队规范，review 时需要逐行检查 |
| AI 过度自信 | 遇到不确定的地方，AI 不会停下来确认，而是自己做决定（且不会告诉你它在猜） | 不知道接口字段名 → 自己造一个「看起来合理的」 |
工作流的本质
工作流的本质是减少 AI 猜你的次数。把该说清楚的事，在正确的阶段说清楚。
完整工作流
需求 → [Chat 阶段] 梳理&方案
→ [OpenSpec 阶段] 结构化规范
→ [Coding 阶段] 代码生成
第一阶段：Chat 阶段
这个阶段在做什么
- 拿到新需求之后，不着急写代码
- 用AI帮你「想清楚」：澄清需求盲点、讨论技术方案、暴露潜在风险
关键技巧
- 提供足够的上下文：技术栈、团队规范、已有约束、接口API
- 避免：「帮我做一个xxxx功能」这种开放式指令
这个阶段的产出物
一份双方（我和AI）对齐后的「需求理解文档」，为下一步做输入
第二阶段：OpenSpec阶段
上一阶段的产物，作为这阶段创建方案的提示词，可以让提案创建的更准确。
如何使用openspec
下面我们以官网的例子「为应用添加深色模式」，完整演示一遍工作流。
1. 发起变更（默认流程）
You: /opsx:propose add-dark-mode
AI: 已创建 openspec/changes/add-dark-mode/
✓ proposal.md — 说明做这件事的原因及变更内容
✓ specs/ — 需求与场景描述
✓ design.md — 技术方案
✓ tasks.md — 实现任务清单
准备好开始实现了！
2.生成的文件内容
proposal.md - 记录变更意图:
# Proposal: Add Dark Mode
## Intent
用户希望在夜间使用时减少眼睛疲劳，因此提出了深色模式需求。
## Scope
- 在设置中添加主题切换开关
- 支持读取系统主题偏好
- 将用户偏好持久化存储到 localStorage
## Approach
使用 CSS 自定义属性实现主题化，配合 React Context 进行状态管理。
specs/ui/spec.md - 以增量方式描述新增需求:
# UI 模块变更说明
## 新增需求
### 需求：主题选择
系统应允许用户在浅色主题和深色主题之间自由切换。
#### 场景：手动切换
- GIVEN 用户正在访问任意页面
- WHEN 用户点击主题切换开关
- THEN 主题立即切换
- AND 该偏好在会话之间持续生效
#### 场景：跟随系统偏好
- GIVEN 用户尚未保存任何主题偏好
- WHEN 应用加载时
- THEN 自动采用系统的色彩方案偏好
tasks.md - 实现任务清单:
# 任务清单
## 1. 主题基础设施
- [ ] 1.1 创建包含浅色/深色状态的 ThemeContext
- [ ] 1.2 添加颜色相关的 CSS 自定义属性
- [ ] 1.3 实现 localStorage 持久化逻辑
## 2. UI 组件
- [ ] 2.1 创建 ThemeToggle 组件
- [ ] 2.2 在设置页面添加切换开关
- [ ] 2.3 在 Header 中添加快捷切换入口
## 3. 样式
- [ ] 3.1 定义深色主题色板
- [ ] 3.2 更新各组件，改用 CSS 变量
怎么用好openspec
review 生成的提案是重点
- review的是逻辑，不是代码
- 发现问题的成本，远低于代码写完
- 修改 Spec 比重写代码要容易的多
第三阶段：Coding阶段
1. 执行实现
你： /opsx:apply
AI： 正在逐步执行任务……
✓ 1.1 已创建包含浅色/深色状态的 ThemeContext
✓ 1.2 已将 CSS 自定义属性添加到 globals.css
✓ 1.3 已实现 localStorage 持久化逻辑
✓ 2.1 已创建 ThemeToggle 组件
……
所有任务已完成！
2. Review AI生成的代码
- 对着tasks.md 确认任务完成情况
- 查看边界情况有没有被突破
- 看opespec里写的Decisions的实现。Decisions有几条，就重点检查几个地方。
3. 归档
你： /opsx:archive
AI： 正在归档 add-dark-mode……
✓ 已将变更规范合并到 openspec/specs/ui/spec.md
✓ 已移动至 openspec/changes/archive/2025-01-24-add-dark-mode/
完成！可以开始下一个功能了。
至此，本次的增量规范已并入主规范文档，完整记录了系统的演进过程。
