AI 编程协作治理框架：从 V1 到三层治理的实践升级

一、从 V1 说起

2025 年我接手了一个工业全栈项目——嵌入式局部放电在线监测设备。Python 算法核心、Cython 交叉编译、Streamlit 前端、E2E 测试、MATLAB 原型验证，多技术栈穿插，强合规约束，横跨 6 个月迭代 3 个大版本。

当时我建了一套 AI 协作脚手架，后来称之为 V1：

V1 帮我跑通了 170 多个开发任务，AI 的行为可预期性明显提高，重复踩坑的次数大幅减少。在设计探索阶段，这套脚手架够用——规则少、探索多、迭代快。

但项目进入实施阶段后，问题开始一个接一个地浮出水面。

二、自然发现的六个瓶颈

以下六个问题不是在纸上对比出来的，而是在真实推进中逐步感知到的：

1. 规则膨胀不可控

规则从最初的 3 个增长到 18 个。不少规则长期无人调用，却依然占据上下文预算。更糟的是，AI 开始在不重要的约束上"过度服从"，反而忽略了真正关键的规范。

2. 规则与技能耦合

9 个规则模板嵌在 scaffold 技能里。想加一个规则？得改技能代码。改完怎么保证新旧规则不冲突？没有检查机制。

3. Agent 预置反成负担

预置了三个专家——项目初期有用。但随着需求演变，预置 Agent 的领域知识逐渐过时（算法专家里写的是局部放电的陷阱参数），而创建新 Agent 没有标准化流程。

4. 工具绑定导致资产沉没

规则里写着 ln -s（Claude Code 的 symlink 命令），写着 .cursor/rules/ 路径。当团队有人换工具时，规则系统就得重写。

5. 治理没有分级

一个个人脚本和一个工业软件用同一套规则——简单项目被规则系统压垮，复杂项目被规则系统漏过。

6. 上下文没有分层加载

所有规则平等对待，AI 每次对话都加载全部 18 个规则。这相当于每次开会前先读一遍公司章程。

三、升级思路：按软件工程生命周期重构

3.1 核心洞察

设计探索阶段和实施阶段对规则的需求截然不同：

V1 在设计阶段够好，但直接拿到实施阶段就不够用了。这不是规则数量的问题，而是规则的组织方式需要随阶段变化。

3.2 按生命周期重新组织

V2 的升级遵循一条主线：按软件工程生命周期来规划规则和技能。

规则按开发阶段覆盖：

环境搭建 → 项目结构 → 编码实现 → 测试验证 → 文档同步 → Git 管理 → 原型迭代 → 并行开发

工作流技能按生命周期阶段规划：

初始化 → 看板刷新 → 任务归档 → Agent 创建 → 规则创建 → 决策记录

每个阶段有自己需要的规则上下文，不必全量加载。

四、V2 三层治理架构

4.1 核心假设

AI 协作不是"写多少规则"的问题，而是"规则在什么层级生效"的问题。我把它抽象成三层的"约束-上下文-任务"三角：

        约束层（Rules）
       ╱              ╲
      ╱   AI Agent      ╲
     ╱    执行空间       ╲
    ╱                    ╲
上下文层（Knowledge）—— 任务层（Tasks）

• 约束层回答"AI 不能做什么"：编码规范、测试标准、Git 流程。硬边界，始终生效。
• 任务层回答"AI 现在该做什么"：当前活跃任务、里程碑、阻塞项。方向指引。
• 上下文层回答"AI 需要知道什么"：模块结构、设计文档、技术债务。参考信息。

优先级法则：规则 > 知识 > AI 自主判断。

4.2 规则独立化

V2 最大的结构变化：每个规则是一个独立 Markdown 文件。V1 的规则在 scaffold 技能内部，V2 把 15 个规则拆成 15 个独立文件：

.ai-collab/rules/
├── _RULE_TEMPLATE.md
├── _PROFILE_INDEX.md          ← 三档选型矩阵
├── g-development-environment.md
├── g-taskManagement.md
├── g-designStructure.md
├── g-doc-sync.md
├── g-test-management.md
├── g-git-workflow.md
├── g-repowiki-protection.md
├── g-detailed-design-template.md
├── g-ddd-evolution.md
├── g-parallelExecution.md
├── g-frontend-prototype.md
├── g-requirements-format.md
├── g-toolsGuide.md
└── g-importCleanup.md

4.3 三级触发机制

上下文窗口不是无限的，V2 给每个规则分配触发模式：

500 行的 always_on 预算——这个数字来自 V1 的实践观察：超过 8 个规则（约 700 行）时，AI 开始出现注意力分散。预算迫使每一条 always_on 规则都必须"值得一个位置"。

4.4 三档治理

治理成本与项目风险匹配。通过 8 维问卷自动匹配：

4.5 Agent 零预设

V2 删掉了所有预置 Agent，只保留一个五要素模板（领域定位 / 工作流 / 验收标准 / 领域知识 / 禁止行为），以及一个 g-agent-creator 技能。

理由来自 V1 的教训：预置 Agent 的领域知识有"保质期"，技术栈变了、架构重构了、Agent 知识就过时了。与其维护"过期专家"，不如提供创建新专家的标准化方法论。

4.6 INDEX.md 自描述协议

V2 不写"在 Claude Code 里执行 ln -s"，也不写"复制到 .cursor/rules/"。取而代之的是 .ai-collab/INDEX.md——一个纯 Markdown 的自描述协议：

## 自配置步骤
1. 读取 _PROFILE_INDEX.md → 确定当前治理档位
2. 加载 always_on 规则
3. 注册 manual 规则
4. 注册技能
5. 发现 Agent
6. 读取任务看板

任何 AI 工具进入项目后，读取 project.md → 进入 INDEX.md → 按步骤完成自适配。今天用 Cursor、明天换 Claude Code、后天用 Copilot，规则系统不需要改动。

4.7 目录双轨制

项目根/
├── .design/          ← 人类产出（设计文档、任务看板、决策记录）
└── .ai-collab/       ← 机器消费（规则、技能、Agent 定义）

.design/ 的消费者是人，.ai-collab/ 的消费者是 AI。物理隔离，职责清晰。

4.8 生命周期适配（初级阶段）

V2 的生命周期适配当前处于初级阶段——主要依赖人工主动感知和优化。开发者在项目进入新阶段时，手动调整规则档位、审视 always_on 列表、判断是否需要增减规则。框架提供了三档选型矩阵和规则增减模板来辅助这个过程，但尚未实现自动识别阶段并切换配置。

这是 V2 明确的后续优化方向。

五、关键设计决策

决策 1：为什么删掉领域技能？

V1 有 fullstack-dev、wire-dsl 等技能。V2 全部移除。理由：领域技能绑定特定技术栈，一个"Streamlit 前端开发"技能在 React 项目里毫无用处。V2 只保留纯工作流方法论技能——这些是任何技术栈都用得上的。

决策 2：为什么规则从 18 个降到 15 个？

合并语义重叠的规则：3 个测试相关规则合并为 g-test-management，2 个环境配置合并为 g-development-environment。删除 2 个 V1 特有的项目专用规则。合并后的 15 个规则覆盖了通用软件开发的完整生命周期。

决策 3：为什么 Agent 从交付变为赋能？

V1 给三个 Agent，V2 不给 Agent，但给了"教你怎么建 Agent"的方法。因为 Agent 的领域知识天然有保质期，V2 的策略是提供标准化的创建模板和流程，让 AI 根据项目的实际技术栈现场创建 Agent。

决策 4：为什么引入预算机制？

always_on 规则合计 ≤ 500 行。当 always_on 规则超过 8 个时，AI 开始出现注意力分散和 token 争抢。预算迫使每一条 always_on 规则都必须"值得一个位置"。

六、V1 与 V2 量化对比

七、与开源治理框架的横向对比

以下五个是 2026 年最具代表性的开源 AI 开发框架，均面向全栈开发场景。

各框架的设计哲学

五维度对比

殊途同归的共识

有意思的是，五个框架独立发展，却不约而同地指向了几个相同的结论：

1. 无序的 Vibe Coding 不可持续——全都在向结构化方法论走
2. 上下文管理是核心瓶颈——GSD 用进程隔离，Superpowers 用子 Agent 隔离，我用三级加载 + 行数预算，解法不同但问题同一
3. 规约与执行分离——Brainstorming→Doing、Discovery→Delivery、Spec→Code、Persona→Dev，本质上都在做同一种分离
4. 模块化可组合——技能/规则/角色/Persona 都追求独立、可复用、可替换
5. 工具无关化——没有框架绑定特定 IDE，说明这是行业共识而非工具特性

这些共识表明，当前的演化方向不是个人偏好，而是 AI 编程协作发展到一定阶段的必然产物。V2 在生命周期感知和三档分级上有自己的探索，但底层问题和解决方向和业界主流一致。

八、迁移路径

从零开始

1. 创建 project.md → 指向 .ai-collab/INDEX.md
2. 回答 8 维问卷 → 确定治理档位
3. 按 _PROFILE_INDEX.md 加载对应档位的规则
4. 按需创建 Agent（通过 g-agent-creator 技能）

从 V1 迁移

• 删掉预置 Agent 文件，用五要素模板重新创建
• 回答 8 维问卷，确定治理档位
• 按 _PROFILE_INDEX.md 清理不需要的规则
• 将硬编码的工具路径替换为通用描述

验证清单

• always_on 规则合计 ≤ 500 行？
• project.md 指向正确？
• AI 工具能正确读取 INDEX.md？
• task_registry.md 已按新格式更新？

九、结语

V1 回答了"怎么让 AI 听话"的问题——写足够多的规则。

V2 回答的是一个更好的问题：“让 AI 听话的治理成本，应该由谁来承担？” 不是开发者。应该是框架本身。

通过与五个主流框架的横向对比可以看到，这个方向不是孤例——行业正在形成共识：无序的探索终究要向结构化的方法论收敛，区别只是收敛的方式和路径。

V2 通过三层架构、三档治理、预算限制、自描述协议，把治理成本从"每次对话手动交代"转移到了"框架自动加载"。

核心理念：规则不是越多越好，治理不是越重越好。合适的约束 + 正确的层级 + 随阶段调整的灵活性 = AI 知道边界在哪，你也知道 AI 走到哪了。

V2 框架源码及完整文档见

https://gitcode.com/lez1021/AI-Tasks-Dashboard