AI 协作开发规范（历史项目版）
1. 文档目标与适用范围
本规范用于历史项目 / 有技术债项目中，引导人类开发者与 AI 编程工具（如 Gemini CLI、Claude Code、Copilot 等）进行可控、可复现、可审计的协作开发。
目标不是最大化代码生成速度，而是：
- 降低 AI 输出的不确定性
- 避免对历史系统造成结构性破坏
- 提升 AI 在复杂上下文下的实现准确率
- 明确人、AI、文档三者的职责边界
适用场景包括但不限于：
- 运行多年、设计已多次演进的系统
- 架构约束强、兼容性要求高的项目
- 人员流动频繁、隐式知识较多的系统
2. 核心设计原则
2.1 AI 是“受控执行者”，不是“自主设计者”
在历史项目中，AI 的定位必须明确：
- 不能做架构决策
- 不能引入新技术路线
- 不能重构历史边界
AI 的主要职责是：
- 在既定设计与约束下完成代码实现
- 按规范补全样板代码、重复性逻辑
- 辅助定位实现遗漏与潜在风险
2.2 一切不明确，必须显式化
AI 无法可靠处理：
- 隐式约定
- 人脑记忆
- “大家都知道”的事实
因此，本规范要求：
所有希望 AI 正确理解的内容，必须以文档形式存在。
3. 文档分工模型（核心）
历史项目的 AI 协作，至少需要以下三类核心文档。
3.1 GEMINI.md —— 行为与规范约束文档
定位：AI 的“行为边界定义文件”
解决问题：
- AI 能做什么 / 不能做什么
- 优先级如何排序
- 出现冲突时如何取舍
典型内容包括：
- 技术栈与版本约束
- 架构分层与调用规则
- 禁止行为（如引入新框架、跨层调用）
- 输出要求（是否允许推测、是否必须自检）
GEMINI.md 是 Hard Constraint，其优先级高于任何自然语言指令。
3.2 PROJECT_PROFILE.md —— 项目语义压缩文档
定位：AI 的“项目世界观说明书”
解决问题：
- 项目是做什么的
- 为什么会变成现在这样
- 哪些地方是历史包袱
推荐包含内容：
- 项目背景与核心目标
- 核心业务流程
- 关键模块职责划分
- 历史演进里程碑
- 已知妥协点与不可触碰区域
PROJECT_PROFILE.md 不追求完整，但追求稳定、可信、长期有效。
3.3 DESIGN.md —— 人类主导的详细设计文档
定位：从需求到实现的“确定性翻译结果”
解决问题：
- 消除自然语言歧义
- 明确边界条件与异常路径
- 将“意图”转为“实现约束”
原则：
- 由人编写
- 面向实现，而非概念描述
- 可以被逐条验证是否被实现
4. 人与 AI 的职责边界
4.1 人类必须负责的事项
- 需求理解与澄清
- 架构与方案决策
- 详细设计与权衡说明
- 最终代码合入决策
4.2 AI 可以承担的事项
- 按设计生成代码
- 补全重复性逻辑
- 根据规范发现实现遗漏
- 按约束进行局部重构
4.3 明确禁止 AI 执行的事项
- 自行改变架构分层
- 引入新技术或第三方库
- 推翻历史兼容逻辑
- 在设计不明确时自行假设
5. 标准协作流程（推荐）
5.1 标准流程
- 人类编写 / 更新 DESIGN.md
- AI 阅读：GEMINI.md + PROJECT_PROFILE.md + DESIGN.md
- AI 输出实现方案或代码
- AI 执行自检（如有要求）
- 人类 Review 与修正
5.2 强制自检机制（推荐）
在 GEMINI.md 中可要求 AI 在输出前明确回答：
- 是否违反任何架构或规范约束
- 哪些地方存在不确定性
- 哪些逻辑依赖历史假设
6. 约束分级机制（进阶）
建议将约束分为两类：
6.1 Hard Rules（不可违反）
- 架构分层
- 数据一致性规则
- 向后兼容要求
6.2 Soft Rules（可讨论）
- 代码风格
- 性能优化策略
- 技术债处理方式
AI 在 Hard Rules 上零容忍，在 Soft Rules 上需显式说明取舍。
7. 历史包袱的结构化表达
建议在文档中显式记录：
- 已知反模式（为什么不能改）
- 已知脆弱点（动了容易出问题）
- 已知妥协方案（理想 vs 现实）
这些信息对 AI 的价值 高于抽象设计原则。
8. 风险与防控
8.1 文档与代码不一致风险
- 文档必须有维护责任人
- 重大偏差需优先更新文档
8.2 AI 稳定性风险
- 不允许“看起来合理但未经确认”的实现
- 强制暴露不确定性
9. 结语
在历史项目中使用 AI，本质上不是“是否使用 AI”的问题，而是：
是否有能力为 AI 构建一个可理解、可约束、可校验的工程环境。
本规范的核心价值在于：
- 让 AI 的能力可预测
- 让人的精力聚焦在真正需要判断的地方
- 让历史系统在演进中保持可控
本规范允许根据项目成熟度逐步引入，不要求一次到位。
总结
整体是按“工程规范级别”来写的，而不是提示词说明书，目标是可长期使用、可落地、可扩展。
你现在这份规范的特点
从结构和定位上看，它已经具备几个很重要的特征：
- 不是围绕某一个模型或工具（Gemini / Claude / Copilot），而是方法论级别
- 明确区分了 约束（GEMINI.md） / 语义背景（PROJECT_PROFILE.md） / 决策产物（DESIGN.md）
- 把“历史包袱”当成一等公民，而不是附录说明
- 默认 AI 是 受控执行器，而不是 自由创作体
这使得它非常适合你当前的使用场景： 复杂历史系统 + 高风险演进 + 人机协作而非替代。
如果你想进一步“工程化”，我建议的下一步（可选）
你可以按阶段演进，不必一次做完：
-
拆模板
-
从这份规范中，直接拆出：
GEMINI.md 模板PROJECT_PROFILE.md 模板DESIGN.md（AI 可执行版）模板
-
-
加执行约束
-
给 AI 明确规定：
- 哪些文档是 Single Source of Truth
- 冲突时的优先级裁决规则
-
-
引入 Review Checklist
-
把第 5、6、7 章转成：
- 人 Review 的 checklist
- AI 自检的 checklist
-
