OpenSpec：让当前规格与拟议变更在 Git 中收敛
OpenSpec 的核心不是多写几份 Markdown，而是把“系统当前承诺什么”和“这次准备改变什么”分开。变更被实现和验证后，delta 才合并回当前规格；未完成或被否决的提案不能悄悄改写事实源。
当前规格与 change 目录承担不同责任
当前规格描述已经成立的可观察行为，按 capability 组织。change 目录保存本次 proposal、delta spec、design 和 tasks，它是一个有生命周期的工作对象。项目初始化后先检查生成目录、命令或 agent 集成是否与锁定发行线一致，再选择一个小行为跑完整闭环。
openspec --version
openspec init
openspec list
openspec validate --all命令名和目录以项目锁定版本为准。初始化会修改仓库，应先在干净分支查看 diff，确认没有覆盖既有规则。安装来源、包版本与生成器脚本进入依赖审查，不能从非官方镜像复制未知安装脚本。
proposal 说明动机，delta 说明行为变化
proposal 解释为何改变、范围和影响；delta spec 用新增、修改或移除的 requirement/scenario 表达可观察差异；design 记录需要长期理解的技术决策；tasks 把已批准方案拆成可验证动作。四者不能互相替代，也不需要为了填模板重复同一句话。
openspec/changes/add-session-expiry/
├── proposal.md
├── design.md
├── tasks.md
└── specs/auth/spec.md好的 requirement 不描述“使用某个库”，而描述用户或系统能观察到的结果。scenario 覆盖成功与拒绝，边界条件进入同一 change。跨 capability 的改动可以包含多个 delta，但每个 requirement 仍应有明确 owner 和验证入口。
正反验证把规格与实现连接起来
OpenSpec 校验只能证明文档结构符合 schema，不能证明代码实现。实现前让 proposal、delta、design 和 tasks 互相对账；实现后从 scenario 生成或关联测试，保存实际命令、退出码和关键输出。反向实验故意违反一个 requirement，确保测试会失败。
openspec validate add-session-expiry --strict
npm test -- auth-session-expiry
git diff -- openspec src testAI 代理可以起草这些文件和补丁，但不能由同一次生成同时自证规格、实现和测试都正确。评审者分别检查行为边界、设计取舍、代码 diff 与运行证据。tasks 的勾选状态只是进度，不是验收结果。
并行 change 需要显式处理重叠
两个 change 同时修改同一 requirement 时，普通 Git 文本合并成功也可能产生语义冲突。合并或归档前比较 delta 覆盖的 capability、requirement 与 scenario；发现重叠就决定顺序、重新基于当前规格调整，或拆成互不冲突的行为。
大 change 容易让 proposal 失焦、tasks 失去可回滚边界。按独立用户结果拆分，每个 change 能单独验证、归档和撤销。临时调查若最终不实施，也保留被否决原因或按团队策略归档，不能让半成品 delta 留在开放目录长期误导代理。
归档是状态收敛，不是移动文件
归档前确认代码、测试和文档证据通过，delta 已合并到当前规格，tasks 与实际提交一致。归档后再次校验全部规格并运行受影响测试；旧 change 仍是历史证据，但当前规格成为下一次变更的事实起点。
openspec archive add-session-expiry
openspec validate --all --strict
git diff -- openspec若归档结果错误，优先回退整个归档提交，恢复 change 与当前规格的共同状态，再修正 delta 后重做。只手工移动目录会留下规格已更新、任务未完成或历史断链的混合状态。
权限、数据与代理接入要保持最小化
OpenSpec 文件会包含需求、架构、内部名称和未来计划，属于仓库敏感上下文。云端 AI 接入前按组织策略处理；secret、客户数据和生产凭据不写进 proposal。代理只在当前工作区读写，shell、网络和 Git 提交分别授权，生成文件继续经过 diff 和测试。
团队约定哪些 change 需要安全、数据、架构或产品评审，CI 运行 schema 校验、链接与未归档冲突检查。模板和 schema 升级先在固定样本 change 上比较生成差异，失败可恢复旧版本。成本不仅是工具许可，还包括规格维护、评审、代理上下文和无效文档膨胀。
退出时保留可移植的行为资产
停用 OpenSpec 前先把开放 change 分类为完成、继续、撤销或迁移，确认当前规格仍准确，再导出为普通 Markdown 与 Git 历史。删除 CLI 和 agent 集成后，构建与测试不能依赖残留命令；仓库中保留的规格要有新的 owner 和更新流程。
工作站迁移只需按仓库文件和锁定安装恢复，不复制聊天记录或本机缓存。新环境运行版本检查、全量 validate、一个正向 scenario 和一个反向 scenario，才能证明规格控制面真正可恢复。