OpenSpec 入门：把 AI 编程需求变成可审阅的变更材料
OpenSpec 入门：把 AI 编程需求变成可审阅的变更材料
理解提案、行为规格、设计与任务各自负责什么，再让助手开始修改代码。
OpenSpec 入门：把 AI 编程需求变成可审阅的变更材料知识学习CN编辑简报更新 2026-09-23
你将学会
- 把约定留在聊天之外
- 理解助手的边界
- 完成状态需要拆开看
开始前需要
- 基本 Git 与 Node 知识
- 可独立试验的样例仓库
用合成模式解释阻塞原因，把规划状态与实现证据放在不同列中。
先看结论
- 材料让约定脱离聊天记录。
- 助手命令与终端命令不同。
- 规划完成不等于发布完成。
把约定留在聊天之外
OpenSpec 把一次变更整理为 Markdown 材料：提案解释动机，规格描述可观察行为，设计记录实现选择，任务跟踪工作。团队可以用 Git 保存并审阅这些约定。
例如增加 CSV 导出时，导出哪些行、逗号如何转义属于行为约定；使用哪个 CSV 库属于设计。把两类问题分开，换库时就不必误改用户需求。
理解助手的边界
命令行工具为选定的编程助手初始化指引，助手据此提出方案和实施变更。安装 OpenSpec 不会同时安装模型、提供模型凭据或验证应用已经正确运行。
终端命令与助手命令不能混用。不同工具的提案入口拼写不同，Codex 使用 $openspec-propose；应以初始化输出为准，不要把聊天斜杠命令粘进终端。
完成状态需要拆开看
在提交 1d35e9 中，规划材料完成后会返回查看实现进度的指令。这不代表测试通过或生产发布成功；规划、实现与发布应分别提供证据。
本系列检查固定版本源码，并对真实的纯图类执行了六项离线断言。没有运行完整命令行流程、编程助手或应用部署，后续文章不会把这些边界混为一谈。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
选择一个可观察行为。
- 2
分开需求约定和实现选择。
- 3
实施前指定审阅人。
可复制示例
text
proposal.md: 为什么需要 CSV 导出
specs/: 导出行为
design.md: 编码与库选择
tasks.md: 实现和验证常见问题
OpenSpec 会自行写代码吗？
文档中的流程依赖你的编程助手及其执行环境。
本系列运行了完整流程吗？
没有，实际执行的测试仅覆盖纯图类。
资料来源
- OpenSpec / README.md来源核查 2026-09-23
- OpenSpec / schemas/spec-driven/schema.yaml来源核查 2026-09-23
- OpenSpec / src/core/change-status-policy.ts来源核查 2026-09-23