先说说 OpenSpec 是个啥子玩意儿

先把概念甩给你，OpenSpec 本质上是一个约定好的文件结构。

它把需求、设计、测试全dou装进同一个目录。

这么一套“提案+验证”流程，AI 写代码前必须先写文档。

听起来有点儿像老妈子检查作业，哈哈，其实是帮你省事儿。

为什么要让 AI 吃规矩

说实话，我见过太多 AI 把需求搞得七零八落。

它们懂代码，却不懂项目的历史和团队的习惯。

结果生成的代码kan着hen炫，却总是跑偏。

这时候我们就需要 OpenSpec 把“想法”先写清楚。

打开 OpenSpec 的第一步——装工具

这步其实也没什么好说的，安装工具嘛，大家dou懂。

记得用 @fission-ai/openspec@ 这个版本，新版本可Neng有坑，毕竟稳定压倒一切。

目录结构长啥样

openspec/

# changes/
#   {change-name}/
#     proposal.md    # 提案描述
#     design.md      # 技术设计
#     specs/         # 规范文件
#     tasks.md       # 可执行任务清单
#   archive/        # Yi归档变geng
# specs/            # 独立规范库

每次新功Neng，就在 changes/ 里建一个文件夹。

这样Zuo，好比给每个需求开了个专属小抽屉，东西一目了然。

写提案：proposal.md 那点事儿

先写提案。提案里要交代“干啥子”“为啥子”。

别忘了加上受影响的模块、预期效果和风险点。

举个例子：

# 添加用户认证
## 背景
当前系统没有登录态，需要防止未授权访问。
## 目标
实现基于 JWT 的登录与鉴权。
## 风险
token 失效处理、跨域问题。

设计稿：design.md 的小技巧

设计稿里把技术细节摊开来聊。

比如数据库表结构、接口路径、错误码定义等。

别一次性写太多，一行一句，用 #/-/代码块分层次这样审查时geng舒服。

任务清单：tasks.md 真正动手的地方

- 创建 users 表
- 实现 /api/login 接口
- 编写 JWT 中间件
- 添加单元测试用例
- geng新 CI 检查 JWT 安全策略

每条任务Zui好配上对应的负责人或标签，这样后面执行时Ke以直接跑 /opsx:apply "add-user-auth".

验证环节：别让烂活进库

AIOps 会读取所有上下文文件，然后一步步执行 tasks.md.

Ai 生成代码后会走一套校验链：

ValidateProposalFiles: 必须有 proposal、design、tasks 三个文件；

ValidateDesign: 检查是否遗漏关键字段；

ValidateTasks: 确保每条任务dou有实现脚本或占位符；

Linter & Test Suite: Zui终跑 lint 与单元测试。

"为什么百度不收录" 的插曲

*问*: 为什么百度不收录我的技术博客？*

*答*: 大概率是缺少结构化数据和合规的 meta 信息，还有就是页面加载太慢或者 robots.txt 把它拦住了。再者，Ru果内容重复率高、标题没抓关键词，那搜索引擎会觉得价值低，自然不给收录。解决办法就是：

Add `` 并包含核心关键词；

Sitemap.xml 要及时geng新；

Avoid duplicate content by using canonical tags;

Migrate heavy JS 到异步加载，让首屏渲染快点儿。

Sprint 流程里的状态机

Init → Drafting → Openspecing → Reviewing → Executing → ExecutionCompleted → Completed → Archived

Status kan着高大上，其实就是几段文字描述当前阶段：

DRAFTING: 写 proposal 和 design；

\

PENDING REVIEW: 人工审阅并提交反馈；

\

EFFECTIVE: tasks 执行成功后进入完成状态；

\

CLOSED: 归档到 archive/ 保存记录。

\

CICD 与 OpenSpec 的完美联姻

CICD pipeline Ke以直接读取 openspec/tasks.md 来生成构建步骤。

# 在 .github/workflows/openspec.yml 中：
steps:
  - name: Checkout code
    uses: actions/checkout@v3
  - name: Apply OpenSpec Change
    run: opsx apply "$"

CICD 自动化确保每次变gengdou有完整审计痕迹——谁改了什么、什么时候通过审查，dou留在 Git log 里。这样即使以后出现 bug，也Neng快速定位是哪一次提案导致的。

AIAssist 与 OpenSpec 的配合技巧

AIAssist在你敲命令时会自动补全，但Ru果没有明确规范，它往往“发挥想象”。咱就是说让它先读 /openspec/specs/*.md, 再去写代码，这样出错概率明显下降。

实战案例：从零到上线只用了两天

A 项目原本没有登录功Neng，同事们急得直跳脚。我们立马打开终端：

opsx:new "add-user-auth" --repo "web"
# 自动生成 skeleton，包括 proposal.md、design.md、tasks.md 等。
vim openspec/changes/add-user-auth/proposal.md   # 填写需求描述。
vim openspec/changes/add-user-auth/design.md    # 写技术细节。
opsx:apply "add-user-auth"                     # 开始执行任务。
opsx:status --change "add-user-auth"           # 查kan进度。
opsx:archive "add-user-auth"                   # 完成后归档。

整个过程几乎没有手工 copy‑paste，所有产出dou在 git 上可追溯。上线后监控显示登录成功率 99.8%，团队满意度飙升——哈哈，这才叫效率！

Pitfall 小提醒

- 别忘了在 proposal 中标明 “回滚计划”，否则出错没人知道该怎么撤销；

\

- tasks 要拆得足够细，否则 CI 一卡就不知道到底卡哪一步；

\

- 定期清理 archive，防止磁盘被旧提案吃满；

\

- Ru果发现 AI 总是忽略某些约束，把这些约束搬到 design 或 specs 中强制出现。

\

Killer Tips：让 OpenSpec 成为团队文化的一部分

- 每周例会抽五分钟回顾Zui近几个提案，有人负责 “提案质量” 打分；

\

- 在新人入职手册里加入 “OpenSpec 入门指南”，让他们从第一天起就养成写文档的好习惯；

\

- 用 Slack / Teams Bot 推送 “新提案Yi创建”，提醒大家及时审阅；

\

- 给通过审查且成功部署的提案发放小徽章，提高大家参与积极性。

\ \ \ TIPS END.

Hello, future you!

说实话，我也曾经对这种“多步骤”流程嗤之以鼻。 但真的用了之后才发现，它像是一根隐形支撑杆，让整个项目站得geng稳。 所以啊，你要是不想每天跟 AI 打架，就赶紧把 OpenSpec 拉进来。 哈哈，有空记得给我点赞哦，咱们下回聊别的话题再见！ P.S. Ru果还有啥子疑问或者想交流经验，直接留言吧，我随时在线哈。 祝编码愉快~

---