让 AI 参与开发，
但不让流程失控。
这是一套面向多团队协作的软件研发框架：把项目资料、AI 协作、模块开发、验收归档和风险管理放入同一条可追溯的交付链路。
它解决的不是“如何让 AI 写代码”，而是“如何让团队稳定交付”。
AI 可以加快分析、编码和检查；项目负责人仍然掌握范围、授权、风险和最终验收。框架的目标是让每一次交付都有明确边界、证据和责任人。
信息不散落
项目总控入口、模块进度、规格、报告和归档均有固定位置。聊天结论不是正式状态。
AI 不越权
角色卡定义读取范围、可写路径、停止条件与交付格式。AI 不能替负责人作业务或上线裁定。
验收可复核
开发者先自检，管理方再在集成基线独立复核；通过后才允许归档。
五个目录层，覆盖从输入到归档的完整链路。
项目管理、旧系统分析、UI 标准、功能模块、验收报告、问题、归档与记录。
协作总则、Agent 角色卡、Skill 执行卡、Prompt、文档模板、工具适配。
经授权的旧版源码、设计、接口、业务资料、测试信息和环境配置；默认只读。
实际业务代码；仅在当前模块被授权范围内修改。
规格变更、任务、增量规格和归档；若项目不用 OpenSpec，需在总控入口指定替代机制。
先初始化并分析项目输入，再领取第一个模块。
框架不是复制后立即编码。登记资料不等于理解资料；完成以下八项，才能具备可控开发条件。
确定项目事实
在项目总控入口填写项目名称、仓库根目录、源码位置、主开发分支和负责人。
登记资料与授权
明确需求、设计、接口、存量代码、测试账号和环境的来源、版本、授权及敏感等级；输入资料默认只读。
冻结分析与开发基线
记录当前可工作的分支/提交/构建号、输入版本与适用范围。后续规格、报告和验收只引用已登记基线。
分析旧输入与存量能力
由分析 Agent 逐项梳理旧页面/路由、字段按钮、接口参数、登录权限、缓存、异常、固定内容和高风险操作；区分事实、推断与待确认。
形成 UI 与技术基线
从设计和存量实现提取项目级 UI、组件、状态、适配、技术约束和兼容规则；缺失项进入决策/风险，不凭猜测编码。
建立模块与上下文包
基于分析结论分配不可复用的功能编码，形成规格、AC、依赖、专项矩阵和 12 件套上下文包，再建立总进度表。
配置质量门禁
确定适用的 build、lint、typecheck、test、视觉检查、真实联调和发布/回滚要求。
明确高风险边界
对写入、支付、授权、数据迁移、生产变更等定义环境、白名单、审批人、禁测范围与回滚方式。
唯一启动入口：01-项目文档_docs/00-项目管理/项目总控入口.md
从输入分析到归档，七个阶段、五道硬门。
开发前门禁
- 输入分析、存量覆盖、模块范围、验收、依赖与风险清晰
- 基线、分支、OpenSpec change 完整
- 接口/权限/高风险边界明确
- 允许与禁止修改范围已写明
待验收门禁
- 自检报告、问题、任务和证据齐全
- 规格、change 与严格校验通过
- 状态四件套同步
- 真实接口、视觉与专项矩阵已核验
管理复核门禁
- 代码已在 develop 集成基线独立检查
- 无公共能力污染、依赖冲突或阻塞问题
- 文档、代码、change、进度一致
- 高风险能力与授权可追溯
归档门禁
- 管理复核通过，问题闭环或已裁定
- active change、formal spec 与总结齐全
- 严格校验/全量校验通过
- 状态和索引更新，流程缺口已回灌
角色负责“做什么”，权限定义“不能做什么”。
每次任务必须说明目标、输入、允许写入、禁止范围、交付物、验收人和停止条件。
项目负责人
- 决定范围、优先级、资源、授权与上线
- 接受或拒绝风险
- 作最终验收裁定
主 Agent
- 拆解、派发、维护总控和进度
- 协调依赖与串行集成
- 汇报风险，不替业务裁定
开发 Agent
- 只改当前模块授权范围
- 维护上下文包/change/自检材料
- 不能自行合主线或归档
验收与 OpenSpec Agent
- 自检与管理复核只审查、写报告
- OpenSpec Agent 仅在通过后归档
- 任何角色都不能伪造通过
develop。待集成是集成队列标签，不是模块正式状态。让每个角色清楚：什么时候行动、和谁对齐、交付什么。
角色不是称谓，而是一组可检查的工作动作。项目管理 Agent 负责组织与核对，开发者负责实现与留证，验收角色负责独立验证。
项目管理 / 主 Agent 的固定动作
模块启动前：把“能不能开发”讲清楚
与规格 Agent 对齐上下文包、AC、接口、UI、状态异常、依赖、允许/禁止范围与专项矩阵；缺项即登记阻塞。
开发中：做口径与风险巡检
定期检查状态四件套、任务真实性、问题/报告落盘、跨模块依赖、共享文件、未验接口和高风险授权。
集成前后：组织而不越权
收集子 Agent 的分支、commit、change、strict、自检、冲突与裁定事项；按依赖串行集成，并触发独立管理复核。
阶段结束：汇报、归档、回灌
汇总完成/阻塞/风险/需决策；通过后协调归档，发现流程漏洞则更新规则、Skill、Prompt 或模板。
派发给 Agent 的任务合同
| 必须明确 | 目标、任务范围、当前基线、输入资料和责任人。 |
|---|---|
| 允许与禁止 | 可读资料、可写路径、不可修改内容、是否可以调用外部环境。 |
| 交付格式 | 结论、依据路径、修改清单、检查结果、不确定项、风险、下一步。 |
| 验收与停止 | 由谁验收；资料、依赖、授权或证据不足时应停止并报告什么。 |
开发者只需要沿着一条清晰的工作路径前进。
① 领取前：先读，不先写
读取项目总控、当前模块上下文包、开发流程、状态/分支规范、UI 标准、直接依赖和当前 change。资料不全先报阻塞。
② 创建隔离环境
从 develop 登记基线创建 feature/<功能编码>-<短名>；并行时创建独立 worktree。
③ 按规格实现
按执行计划完成页面、交互、接口、权限、状态和 UI；持续更新 tasks 与功能点/专项矩阵。
④ 处理不确定性
没有接口、授权、设计或依赖时，不猜、不造、不模拟成功；记录影响并提供安全禁用/待开放方案。
⑤ 人工触发后自检
完成开发并不代表自动进入自检。开发人员明确确认后，才执行自检 Prompt、生成报告和问题单。
⑥ 交付待验收材料
提交代码、tasks、change、报告、命令和视觉证据；同步模块目录、README、规格 YAML、总进度表。
开发者必须避免的行为
- 修改项目输入、其他模块、总控规则或正式归档
- 用 mock、假接口或硬编码业务成功伪造能力
- 绕过公共请求、认证、权限、路由或共享组件
- 未经授权使用真实写接口、生产数据或高风险动作
- 未获人工触发就自检、合并、发布或归档
最小交接包
模块/分支/worktree、基线与最终 commit、change、变更文件、已完成/未完成任务、检查结果、视觉证据、问题与风险、共享文件、未验接口、需裁定事项和状态同步结果。
每个模块都有一份“可以交给新人或 AI 直接接手”的最小完整上下文。
上下文包不是需求文档的复制；它把开发边界、依赖、验收和证据放在一起。
子模板位置：02-AI协作_ai-workflow/04-文档模板_templates/模块上下文包-01 至 模块上下文包-12
“自检通过”不等于“项目验收通过”。
| 层级 | 执行位置 | 重点 | 产物与状态 |
|---|---|---|---|
| 开发者自检 | 模块分支 | AC、矩阵、真实接口、设计/存量双基线、状态异常、命令与视觉证据。 | 自检报告 + 问题；满足后进入“待验收”。 |
| 管理复核 | develop 集成基线 | 独立检查污染、公共能力、change/文档/状态一致性、依赖、风险和证据。 | 复核报告；通过后为“已验收”，否则“整改中”。 |
| OpenSpec 归档 | 通过后的正式材料 | active change、formal spec、严格校验、归档总结、状态索引与历史引用。 | 归档记录；状态为“已归档”。 |
| 全量验收 | 冻结的 develop 基线 | 跨模块链路和真实联调；L1 只读 → L2 受控写入 → L3 高风险，逐级准入。 | 仅更新治理追踪中的全量验收轴，不篡改历史归档。 |
状态代表事实，问题代表待处理的事实。
模块开发归档轴
待分析 → 待评审 → 待开发 → 开发中 → 待验收 → 已验收 → 已归档
不通过时：待验收 → 整改中 → 待验收。暂停与废弃独立记录。
每次开发状态变更同步：目录前缀、模块 README、规格 YAML、功能模块总进度表。
全量验收轴（可选）
待全量验收 → 静态回归通过 → 人工联调待验证 → 缺陷整改中 → 不通过/全量验收通过
它记录当前冻结基线，不等同于模块归档状态。归档后缺陷以 corrective change 和回归证据处理。
问题按 BUG-<功能编码>-NNN 编号，需有等级、复现、期望/实际、影响、整改与关闭依据。
用一周把框架从“文档”变成团队习惯。
第 1 天
负责人完成项目初始化，冻结基线，导入资料，确认质量与高风险门禁。
第 2 天
用一个真实小模块演示：分析 → 规格 → 12 件套 → change → 分支。
第 3–4 天
由开发者按流程完成一次开发、自检、待集成交接和管理复核。
第 5 天
完成首次归档与复盘；将实际发现的缺口回灌到规则、模板或 Prompt。
团队只需要记住四件事。
总控入口唯一
阶段、基线、范围和阻塞只认一处。
模块边界清晰
领取前有上下文包，开发中不越界。
证据先于结论
没有命令、视觉、人工或联调证据，就不说通过。
问题必须闭环
不通过就整改、回归、再复核；归档后也不改写历史。