Appearance
核心概念
概览页回答 OpenFlow 的 What 和 Why；本页回答 How：OpenFlow 如何用文档、目录、工作流和证据约束 AI 开发。
文档即约束编程
OpenFlow 的核心理念是：文档编程就是约束编程。
在普通项目里，文档经常只是给人看的说明；在 OpenFlow 里，文档会直接影响 AI 应该如何行动。AI 不只是"参考"文档，而是必须把文档当作当前项目的行为边界。
这带来一个重要变化：写文档不只是记录想法，而是在定义 AI 的可行动空间。
设计文档
设计文档（design.md）是每次需求的正式技术契约，回答"这次要改什么、怎么改、哪些不能碰"。
一份完整的设计文档通常包含以下内容：
- 问题与目标：当前状态、痛点、期望变化，以及明确的非目标（不该做的事）。
- 设计决策：每个关键技术选择及其理由。
- 约束条件：按严重程度分级（必须 / 应当 / 可以），覆盖功能、性能、安全等维度。
- 架构与任务流：涉及的组件、调用关系、数据契约和集成边界。
- 成功标准：怎样才算做完了——每条标准对应具体的验证方式和证据类型。
- 风险与缓解：已知风险和应对策略。
- 测试策略：单元、集成、端到端和手工测试的覆盖计划。
设计文档在 /openflow-feature 阶段生成，后续的计划、实施和验证都以它为依据。
行为文档
行为文档（behavior.md）描述的是用户或外部调用者能看到什么，而不是系统内部怎么实现。
OpenFlow 采用 BDD（行为驱动开发）思想来组织行为文档。每个行为场景用 Given / When / Then 结构描述：
- Given（前置条件）：开始之前系统处于什么状态。
- When（触发动作）：用户或外部系统做了什么。
- Then（可观测结果）：系统应该表现出什么行为。
markdown
### 用户提交表单后显示成功提示
Actor: 用户
Given:
- 用户已登录
- 表单所有必填项已填写
When: 用户点击提交按钮
Then:
- 页面显示"提交成功"提示
- 数据被保存到数据库
- 用户收到确认邮件行为文档的核心规则是：只描述可观测行为，不涉及函数名、变量名、代码分支或框架细节。这样无论内部实现怎么变，只要行为不变，就算满足要求。
行为文档中还包含 Must Not 行为——明确列出不该发生的事，比如"不得在未登录状态下访问数据"。这些反向约束在验证阶段会被重点检查。
目录结构
OpenFlow 用四个顶层目录表达知识的不同生命周期：
docs/
├── current/ ← 当前系统事实（AI 必须遵守）
├── decisions/ ← 架构决策记录（跨需求生效）
├── changes/ ← 活跃变更工作区（进行中）
│ └── {日期}-{需求名}/
└── archive/ ← 冻结历史（只读权威）
└── {日期}-{需求名}/| 目录 | 职责 | 生命周期 |
|---|---|---|
docs/current/ | 当前仍然有效的系统事实，AI 执行任何任务时必须遵守。 | 归档时自动更新，持续维护 |
docs/decisions/ | 跨需求的正式架构决策记录（ADR），所有需求都要遵守。 | 手动创建，长期稳定 |
docs/changes/ | 正在进行的变更工作区，每个需求一个子目录。 | 需求开始时创建，归档后移走 |
docs/archive/ | 已完成变更的冻结历史，归档后不可修改。 | 归档时写入，永久只读 |
这套划分的关键不是"把文件放整齐"，而是让 AI 明确知道：哪些是当前事实，哪些是进行中的设计，哪些是不可变历史。
docs/current/ 的分类原则
docs/current/ 借鉴了 DDD（领域驱动设计）中限界上下文的思想来划分子目录——把项目知识按主题拆成一个个独立的"知识岛"，每个岛只管自己的事，不跨界、不重复。
docs/current/ 不是随便可以改的日志目录——它只在头脑风暴确认新规则、归档提升长期事实、或人工治理清理时才会更新。这样保证 AI 读到的是稳定、可信的当前状态。
AI 反思
AI 和人一样会犯错，而且会犯同样的错。OpenFlow 的 AI 反思机制，就是让 AI 在发现自己犯了可重复的流程性错误时，主动把教训记下来，下次遇到类似场景就能避免。
反思记录保存在 docs/current/workflow/ai-reflection/ 下，按错误类别分目录存放。每个类别记录三样东西：
- 犯了什么错：具体的失败场景和上下文。
- 根因是什么：为什么会犯这个错。
- 下次怎么做：可复用的纠正规则。
反思不是每次报错都要触发——普通的代码 Bug 不算，只有当错误暴露出 AI 在工作流程或决策方式上的问题时，才值得记录。比如：未经确认就开始写代码、跳过验证就声称完成、把信息写进了错误的文档层级。
这些反思会在后续任务的约束扫描阶段被自动读取，相当于 AI 给自己立了规矩，而且是真正会遵守的规矩。
文档漂移检测
代码写着写着偏离设计，是 AI 开发中最常见的问题之一。OpenFlow 用多层漂移检测机制来发现和应对这种情况。
第一层：实时守护
在 AI 实施代码的过程中，每次文件变更都会触发实时检查。守护进程会拿着设计文档中的约定来比对：
- 这个文件在设计范围内吗？
- 导出的函数、类、常量是不是设计里预期的那几个？
- 改动有没有违反
docs/current/中标记为不可变的约束？
如果只是路径重命名这类确定性的小偏差，守护进程会自动修复并记录日志。如果改动模糊或明显违反设计，就加入待确认队列，等待人工处理。
实时守护不会打扰你——它只在后台默默检查，把发现的问题积累起来。
第二层：质量门检查
当 AI 说"做完了"，你运行 /openflow-quality-gate 时，质量门会做一次全面的最终状态检查：
- 设计漂移：改动的文件和符号是否超出了设计文档声明的范围？
- 当前约束检查：有没有触碰
docs/current/中标记为@stable、@public或locked的内容？ - 决策约束检查：有没有违反
docs/decisions/中的架构决策规则？
如果发现问题，质量门不会让你归档，而是给出明确的 未通过 或 需要人工决策 判定。
第三层：归档拦截
归档是最后一道关卡。如果前面的检查没有通过，或者仍存在未解决的漂移问题，归档会被直接拦截。
你必须要么回去修复实现、更新设计文档，要么明确确认接受已知漂移，才能完成归档。
三层配合
简单来说：实时守护在实施过程中持续监听，质量门在实施结束后做全面复查，归档拦截确保未解决的问题不会悄悄溜进历史。三层配合，既不会每次保存都打断你，也不会让漂移积累到不可控。
完成的定义
在 OpenFlow 中，"完成"必须同时满足四个条件：
- 实现符合设计和当前事实：代码没有越过本轮变更边界，也没有静默破坏
docs/current/或docs/decisions/中的约束。 - 质量门给出允许归档的判定：验证证据足够，漂移检测通过，风险被处理，或需要人工决策的问题已经解决。
- 归档冻结历史并生成
implementation-mapper.md：需求、设计、行为约束和代码位置可追溯。 - 必要的长期事实被提升到
docs/current/：完成后的系统状态不只存在于归档里，也反映到当前有效文档中。
少了其中任意一个，最多只能说"代码改完了"，不能说 OpenFlow 意义上的变更已经完成。