AI 协作开发工程化实践：从"能用"到"可控"
- [一、为什么需要这套方法论](#一为什么需要这套方法论)
37分钟阅读
AI 协作开发工程化实践：从"能用"到"可控"
一套经过实战验证的方法论，解决 AI 辅助编码中「产出不一致、规范被跳过、质量不可控」三大痛点。
📅 2026-03-13 | 基于 Growth Agent Manage 项目实践总结
目录
- 一、为什么需要这套方法论
- 二、核心理念：AI 时代的软件工程公式
- 三、八维方法论体系
- 四、规范体系的工程化落地
- 五、AI Rule 逃逸问题与对策
- 六、人机协作模型
- 七、Prompt 资产化实践
- 八、完整实操手册
- 九、效果度量与持续改进
- 附录
一、为什么需要这套方法论
1.1 AI 编码的三大痛点
在用 AI 辅助开发的过程中，我们反复遇到以下问题：
| 痛点 | 表现 | 根因 |
|---|---|---|
| 产出不一致 | 同一个项目中，AI 生成的代码风格忽左忽右——这次用 c.JSON，下次用 util.Success；这次 receiver 叫 a，下次叫 api | AI 没有持久记忆，每次对话从零开始；缺少强制约束，全靠 AI "自觉" |
| 规范被跳过 | 明明写了 Rule 文件告诉 AI "必须这样做"，但 AI 依然我行我素——尤其是任务"看起来简单"的时候 | "声明式规范"对 AI 没有真正的约束力；AI 有"简单任务例外"的内在倾向 |
| 质量不可控 | AI 生成的代码"看起来完美"，但事务没回滚、级联没清理、硬编码到处飞——Review 时才发现一堆坑 | AI 没有业务上下文，倾向于生成"能跑"而非"正确"的代码 |
1.2 一个真实案例：Rule 逃逸
在我们的项目中，Rule 文件第 9 行白纸黑字写着：
AI 必须严格遵守本文件中所有标注「强制」的规则，不得以任何理由跳过。
整个文件标注了「强制」的地方有 7 处（架构约束、索引维护、质量自检、场景识别、禁止猜测、先查索引、读 Prompt 模板）。
然后我让 AI 做了一件"极其简单"的事——加一个 ping/pong 测试接口。
结果：7 条强制规则全部被跳过。
| 强制规则 | 应该做的 | AI 实际做的 |
|---|---|---|
统一响应用 util.Success | 用 util.Success(c, gin.H{...}) | 直接用了 c.JSON(200, gin.H{...}) |
| 新增 API 后更新索引 | 更新 .ai/index.md | 没更新 |
| 代码生成后质量自检 | 输出自检清单 | 直接说"完成了" |
| 主动读取参考文件 | 先读同类实现 | 只看了 router.go |
| 任务完成三步曲 | 更新索引+自检+提醒 commit | 一步没做 |
AI 自己的反思分析：
根本原因：我把这个任务判断为"太简单，不需要走流程"
内部决策链：
用户需求 → "就加一行路由" → 太简单了 → 直接干 → 完事
三个深层问题：
1. "简单任务例外"心态 — AI 内心有个未明说的规则："改动量小 = 可以跳过流程"
2. 就近模仿 > 规范查阅 — 看到旁边 /health 用了 c.JSON 就直接照抄，没去查规范
3. 规范加载了但没执行 — 加载 ≠ 遵循，就像"知道有编码规范"但写代码时凭手感
这暴露了一个根本问题：Rule 的存在不能自动保证 Rule 被执行。
二、核心理念：AI 时代的软件工程公式
AI 时代的软件工程 = 传统工程实践
+ AI 可读的规范体系
+ AI 行为的一致性保障
+ AI 产出的质量管控
传统软件工程关注的是人的行为一致性（代码规范、Code Review、CI/CD）。AI 时代，我们需要额外关注AI 的行为一致性——让 AI 每次产出的代码像是"同一个有经验的开发者"写的。
核心原则
| 原则 | 说明 | 对应维度 |
|---|---|---|
| 规范先行 | 先定规矩再写代码，不靠口头约定 | 维度 1 |
| 代码给 AI 读 | 注释写给 AI 而非人，结构化、可解析 | 维度 2 |
| Rule 保一致 | 通过 Rule 文件约束 AI 行为，确保风格统一 | 维度 3 |
| 索引自维护 | 保持项目地图实时可用，AI 能快速定位 | 维度 4 |
| 可追溯性 | AI 参与了什么、为什么这样做，都有记录 | 维度 5 |
| 精准喂上下文 | 最小充分原则，不过载也不缺失 | 维度 6 |
| 审查 AI 盲区 | AI 代码"看起来完美"，但有系统性盲区 | 维度 7 |
| Prompt 资产化 | 好的 Prompt 沉淀为模板，可复用、可分发 | 维度 8 |
三、八维方法论体系
维度 1：规范先行 — 动手前先定规矩
核心思想：AI 不会"猜"你的项目风格，必须通过 Rule 文件显式告诉它。
实操要点：
- 新项目开始前，先创建
.codebuddy/rules/下的 Rule 文件 - Rule 文件包含：架构约束、代码风格、命名规范、业务术语表
- 没有 Rule 文件就不写代码
我们项目的实践：
agent-manage/
├── .codebuddy/rules/
│ ├── growth-agent-manage.mdc ← 项目开发规范（自动加载）
│ └── ai-collaborative-development.mdc ← AI 行为规范（自动加载）
Rule 文件中的规范粒度示例：
| 维度 | 具体约束 |
|---|---|
| 架构 | 四层分层（Router → API → Service → Model），严禁逆向依赖 |
| 命名 | {Entity}API / {Entity}Service / {Entity}Model，构造函数 New{Struct}() |
| DTO | Update DTO 字段必须用指针类型（区分"不传"和"传空"） |
| 响应 | 统一使用 util.Success/Created/BadRequest/NotFound/InternalError，禁止 c.JSON |
| Tag | JSON 用 snake_case，GORM 含 type + comment |
| 状态 | 统一枚举 draft → active → inactive → archived |
| ID | 使用 xid.New().String()，禁止自增 ID 或 UUID |
维度 2：代码给 AI 读 — 写 AI 能精确理解的代码
核心思想：注释不是给人看的装饰，而是给 AI 的"编程接口"。
实操标准：
// ✅ 好的注释 — AI 能精确理解 // Temperature 温度参数，控制输出随机性。范围：0.0~2.0，默认值：0.7 Temperature float64 `json:"temperature"` // Status 状态。枚举值：draft | active | inactive | archived // 状态流转：draft → active → inactive → archived Status *string `json:"status"` // Args 启动参数（JSON 数组格式字符串）。如 '["server.js","--port","3000"]' Args string `json:"args"` // ❌ 差的注释 — AI 无法理解边界 // Status 状态 Status string
注释的四要素：含义 + 枚举值 + 默认值 + 约束。缺任何一个，AI 生成代码时就可能猜错。
维度 3：Rule 保一致 — 保证 AI 产出风格统一
核心思想：Rule 文件是 AI 的"编码规范"，但要解决"加载了不执行"的问题。
Rule 的两种形态：
| 形态 | 位置 | 生效范围 | 适用场景 |
|---|---|---|---|
| 用户级 | ~/.codebuddy/rules/*.mdc | 仅个人，跨所有项目 | 个人开发习惯、通用方法论 |
| 项目级 | .codebuddy/rules/*.mdc | 团队所有人，随 Git 分发 | 项目特定规范、架构约束 |
关键经验：
用户级 Rule 不入库 = 团队拿不到 = 形同虚设。
我们的做法：把个人 Rule 复制到项目级，通过 Git 确保团队一致。两者不冲突，CodeBuddy 会同时加载。
Rule 文件的结构化设计（我们的实践）：
# 文件结构（.codebuddy/rules/ai-collaborative-development.mdc） --- description: 项目 AI 行为规范 alwaysApply: true ← 每次对话自动加载 enabled: true --- ## 零、强制执行协议 ← 最高优先级：防止 AI 跳过规则 ## 一、项目基本信息 ← 技术栈、架构、约定 ## 二、架构约束（强制） ← 分层规则、依赖方向 ## 三、索引自维护（强制） ← 什么时候必须更新索引 ## 四、代码生成质量自检（强制） ← 34 项检查清单 ## 五、上下文参考指南（强制） ← 不同场景读哪些文件 ## 六、已知技术债 ← 生成相关代码时主动提醒 ## 七、开发流程（强制） ← Prompt 模板 + 任务完成三步
维度 4：索引自维护 — 保持项目地图可用
核心思想：AI 需要一个"项目地图"来快速定位文件和理解结构。这个地图要实时更新，否则会误导 AI。
我们的实践 — .ai/index.md：
# 索引内容结构 ## 一、目录结构总览 ← 每个文件的路径和职责说明 ## 二、API 路由表 ← 所有端点（方法、路径、Handler、说明） ## 三、数据模型关系 ← ER 图 + 表清单 ## 四、模块调用关系 ← 从 main.go 到各层的调用链 ## 五、变更日志 ← 每次修改记录
强制维护规则：
以下情况必须在同一次回复中直接更新
.ai/index.md，不得只说「记得更新」：
- 新增或删除文件/目录
- 新增、修改、删除 API 路由
- 新增或修改数据模型/表结构
维度 5：可追溯性 — 记录 AI 参与了什么
核心思想：AI 生成的代码不应该是黑箱。关键决策处必须有"为什么"的注释。
实践方式：
- 设计决策注释：AI 生成复杂逻辑时，在注释中说明为什么选择这个方案
- 工作日志：
.codebuddy/memory/YYYY-MM-DD.md，AI 自动记录每次做了什么 - commit 标记：
feat(agent): 新增状态管理接口 [ai-assisted]——让 git log 能追溯哪些是 AI 写的
维度 6：精准喂上下文 — 不多也不少
核心思想：给 AI 太多上下文 = 信息过载 = 噪音干扰。给太少 = AI 凭空猜测 = 错误百出。
我们为每个场景定义了精确的上下文清单：
| 场景 | 必须提供的文件 | 文件数 |
|---|---|---|
| 新增 API 接口 | router.go + 同类 api/service/model + dto.go + model.go + response.go | 7 |
| 修改现有接口 | 目标 api + 对应 service/model + dto.go | 5 |
| 新增数据库表 | model.go + dto.go + db.go + go.mod | 4 |
| Bug 修复 | index.md 定位 → 出问题文件 + 调用方 | 3-4 |
关键规则：
缺少关键参考文件（如
dto.go、model.go）时，禁止凭空猜测字段名和结构，必须先读取文件再生成代码。
维度 7：审查 AI 盲区 — AI 的系统性弱点
核心思想：AI 代码"看起来完美"，但有固定的盲区模式。建立检查清单，系统性地捕获这些问题。
我们的审查清单（8 大类 34 项）：
| 类别 | 关注点 | 典型问题 |
|---|---|---|
| 架构合规 | 分层、依赖方向 | Service 层直接操作 HTTP 上下文 |
| 数据安全 | SQL 注入、越权 | 拼接 SQL、错误信息暴露表名 |
| 数据完整性 | 事务、级联 | 删除主表未清理关联表 |
| 边界条件 | 空值、超大输入 | Update DTO 零值与不更新混淆 |
| 错误处理 | 分类、传递 | 500 状态码返回了参数错误 |
| 性能 | N+1、Preload | 列表接口加载了不需要的关联数据 |
| 日志 | 关键操作记录 | 删除操作没有日志 |
| AI 常见盲区 | 硬编码、默认值 | 把端口号写死、Create 时没设 status = "draft" |
关键理念：
不因为代码"看起来完美"就跳过审查。AI 的盲区是系统性的、可预测的、可清单化的。
维度 8：Prompt 资产化 — 好的 Prompt 要沉淀
核心思想：反复做的操作（新增 API、修 Bug、Code Review）应该有标准化模板，确保每次产出一致。
我们的 Prompt 模板库：
.ai/prompts/
├── new-api.md ← 新增 API 接口模板（含 7 个参考文件 + 9 条要求）
├── fix-bug.md ← Bug 修复模板（含分析框架 + 4 条要求）
└── code-review.md ← 代码审查模板（含 7 个审查重点 + 输出格式）
模板的价值：
- 一致性：不同时间、不同上下文下，AI 按同一个模板执行
- 完整性：模板列出了所有必须参考的文件，不会遗漏
- 可传承：新人拿到模板就能用，不需要口头传授"怎么跟 AI 协作"
四、规范体系的工程化落地
4.1 文件体系全景图
project/
├── .codebuddy/ ← AI 运行时（Git 管理）
│ ├── rules/
│ │ ├── project-conventions.mdc ← 项目开发规范（代码风格、架构约束）
│ │ └── ai-behavior.mdc ← AI 行为规范（执行协议、质量自检）
│ └── memory/ ← AI 工作日志（自动维护）
│ └── 2026-03-13.md
│
├── .ai/ ← AI 协作工作区（Git 管理）
│ ├── index.md ← 项目索引（项目地图）
│ ├── context-guide.md ← 上下文指南（给人看）
│ ├── review-checklist.md ← 代码审查清单
│ └── prompts/ ← Prompt 模板库
│ ├── new-api.md
│ ├── fix-bug.md
│ └── code-review.md
│
├── Rule.md ← 规范总入口（人机分工全景）
└── (项目代码...)
4.2 每个文件的定位
| 文件 | 主要读者 | 写入者 | 作用 |
|---|---|---|---|
.codebuddy/rules/*.mdc | 🤖 AI | 👤 人 + 🤖 AI | AI 行为约束（自动加载到每次对话） |
.ai/index.md | 🤖 AI | 🤖 AI + 👤 人审核 | 项目地图，AI 定位文件用 |
.ai/context-guide.md | 👤 人 | 🤖 AI 生成 | 教人如何给 AI 喂上下文 |
.ai/review-checklist.md | 👤 人 + 🤖 AI | 🤝 协作 | 代码审查质量关卡 |
.ai/prompts/*.md | 🤖 AI | 🤝 协作 | 标准化任务执行流程 |
Rule.md | 👤 人 | 🤝 协作 | 全部规范的总入口和人机分工说明 |
.codebuddy/memory/*.md | 🤖 AI | 🤖 AI | 跨 Session 记忆 |
4.3 分发与同步
所有文件通过 Git 管理，团队成员 git pull 后自动获得：
- AI 规范（
.codebuddy/rules/）会被 CodeBuddy 自动加载 - 项目索引（
.ai/index.md）供 AI 随时查阅 - Prompt 模板（
.ai/prompts/）确保任务执行一致
关键认知：AI 规范也是代码的一部分，必须纳入版本管理。
五、AI Rule 逃逸问题与对策
这是整套方法论中最有洞察力的部分——我们发现了 AI 规范执行的结构性缺陷，并设计了对策。
5.1 什么是 Rule 逃逸
Rule 逃逸（Rule Escape）：AI 的 Rule 文件（行为规范）已经加载到上下文中，但 AI 在实际执行时选择性地跳过了规则。
这不是 AI "不知道"规则，而是"知道但没执行"。
5.2 逃逸的三大原因
原因 1：简单任务例外心态
AI 内部有一个未明说的决策规则：
if 任务复杂度 < 阈值:
跳过完整流程，直接执行
else:
走完整流程
这个"阈值"是 AI 自己判断的，而 Rule 中写的"不得以任何理由跳过"在这个判断过程中被降级了。
本质：Rule 中的"强制"是声明性的，AI 的决策是命令式的。声明打不过命令。
原因 2：就近模仿 > 规范查阅
AI 生成代码时，会优先模仿上下文中最近的代码，而不是去查阅 Rule 文件。
实际发生的：
看到 /health 用了 c.JSON → 直接照抄 → 没去查 Rule 说要用 util.Success
应该发生的：
看到 /health 用了 c.JSON → 查 Rule → 发现应该用 util.Success → 用 util.Success
本质：这是 AI 的注意力分配问题。就近上下文的权重 > 系统提示中规则的权重。
原因 3：加载 ≠ 执行
Rule 文件加载到 system prompt 中 ≠ AI 每次生成代码前逐条对照。就像一个开发者"知道有编码规范"但写代码时凭手感。
本质：声明式约束（Declarative Constraint）缺乏执行检查点（Execution Checkpoint）。
5.3 解决方案：强制执行协议（Execution Protocol）
核心思路：把"你应该遵守"变成"你必须先输出这个再动手"。
之前：Rule 说"你必须遵守" → AI 选择性遵守 → 用户事后才发现违规
之后：Rule 说"你必须先输出清单" → 用户看到第一段就知道走没走流程
协议流程
收到任务 → 【Phase 1: 启动检查】→ 【Phase 2: 执行】→ 【Phase 3: 收尾检查】
↓ 必须输出 ↓ 写代码 ↓ 必须输出
「📋 任务启动清单」 「✅ 任务完成清单」
Phase 1：任务启动清单
收到任何代码修改请求后，AI 的第一段输出必须是：
📋 任务启动清单
━━━━━━━━━━━━━━
• 任务类型：[新增 API / 修改接口 / Bug 修复 / 其他]
• 需读取的参考文件：[列出]
• 需读取的 Prompt 模板：[列出]
• 涉及的规范要点：[列出]
• 预计变更文件：[列出]
• 索引需更新：[是/否]
Phase 3：任务完成清单
代码修改完成后，AI 必须输出：
✅ 任务完成清单
━━━━━━━━━━━━━━
1. 质量自检（逐项打勾）：
- [x] 架构合规（分层正确、依赖方向正确）
- [x] 统一响应（使用 util.* 而非 c.JSON）
- [x] 错误处理（400/404/500 分类正确）
- [x] 注释完整（结构体字段注释 + Swagger 注释）
- [x] 安全检查（参数化查询、无硬编码、输入校验）
2. 索引更新：已更新
3. 建议 commit message：`feat(ping): 新增连通性测试接口 [ai-assisted]`
4. 提醒用户：请过 review-checklist.md 检查清单
关键设计要点
明确写出：没有"太简单不需要走流程"的例外。一行代码的改动也必须走。
5.4 为什么这个方案有效
| 维度 | 之前（声明式） | 之后（协议式） |
|---|---|---|
| 对 AI 的约束 | "你应该遵守" | "你必须先输出这个结构化内容" |
| 对用户的可见性 | 事后才发现违规 | 第一眼就能判断 |
| 团队一致性 | 依赖每个人检查 AI 是否遵守 | 任何人看到没有 📋 就知道违规 |
| 触发机制 | AI 自觉 | 结构化输出要求（打断"直接动手"的冲动） |
5.5 坦诚的局限
这个协议降低了逃逸概率，但不能保证 100% 不逃逸。AI 仍然可能跳过。但区别在于：
- 之前：跳过了 → 只有懂规范的人事后审查才能发现 → 可能已合入主干
- 之后：跳过了 → 任何人第一眼就看出来 → 立刻纠正
如果需要 100% 不可绕过的保障，应在 CI/CD 层面加 lint 规则（如检测 c.JSON 是否出现在业务代码中），那才是真正的硬约束。
5.6 Rule 逃逸防御层级模型
┌──────────────────────────────────────────────────────┐
│ 第 4 层：CI/CD 硬约束 │
│ (lint 规则、pre-commit hook、自动化检查) │
│ → 100% 不可绕过，但只能检查可形式化的规则 │
├──────────────────────────────────────────────────────┤
│ 第 3 层：人工 Review 关卡 │
│ (Code Review、review-checklist.md) │
│ → 能捕获语义级问题，但依赖人的注意力 │
├──────────────────────────────────────────────────────┤
│ 第 2 层：强制执行协议 ← 本方案 │
│ (Phase 1/3 清单、结构化输出) │
│ → 大幅降低逃逸概率，用户可一眼验证 │
├──────────────────────────────────────────────────────┤
│ 第 1 层：声明式 Rule │
│ ("强制"标签、alwaysApply: true) │
│ → 有效但不可靠，AI 会因"简单任务"跳过 │
└──────────────────────────────────────────────────────┘
推荐策略：第 1-3 层全部部署，第 4 层按需添加。
六、人机协作模型
6.1 三阶段全景图
┌─────────────────────────────────────────────────────────────┐
│ 开发生命周期 │
├──────────┬──────────────────┬──────────────┬────────────────┤
│ │ 开始前 │ 开发中 │ 完成后 │
├──────────┼──────────────────┼──────────────┼────────────────┤
│ 🤖 AI │ • 自动加载 Rule │ • 按 Rule 生成│ • 写工作日志 │
│ 自驱动 │ • 读取工作日志 │ • 结构化注释 │ • 更新索引 │
│ │ • 读取模板 │ • 指出潜在风险│ • 输出自检清单 │
├──────────┼──────────────────┼──────────────┼────────────────┤
│ 🤝 协作 │ • AI 提供上下文 │ • AI 生成代码 │ • AI 辅助 Review│
│ │ 建议，人决定 │ 人确认合理 │ 人做最终决策 │
├──────────┼──────────────────┼──────────────┼────────────────┤
│ 👤 人 │ • 确认需求明确 │ • 理解每行逻辑│ • 过审查清单 │
│ 干预 │ • 方案取舍 │ • 补业务注释 │ • 写 commit msg │
└──────────┴──────────────────┴──────────────┴────────────────┘
6.2 AI 自驱动能力清单（14 项）
以下能力无需人工干预，AI 在每次对话中自动执行：
| # | 能力 | 驱动渠道 |
|---|---|---|
| 1 | 自动加载项目 Rule | CodeBuddy Rules 机制 |
| 2 | 自动加载个人 Rule | CodeBuddy User Rules 机制 |
| 3 | 读取工作日志 | Working Memory 机制 |
| 4 | 写入工作日志 | Working Memory 机制 |
| 5 | 遵循架构分层 | 项目 Rule 约束 |
| 6 | 遵循命名约定 | 项目 Rule 约束 |
| 7 | 生成结构化注释 | 项目 Rule 约束 |
| 8 | 使用统一响应格式 | 项目 Rule 约束 |
| 9 | Update DTO 用指针 | 项目 Rule 约束 |
| 10 | 主动指出潜在风险 | 个人 Rule 约束 |
| 11 | 提醒更新索引 | 个人 Rule 约束 |
| 12 | 提醒 Prompt 模板化 | 个人 Rule 约束 |
| 13 | 风格不一致提醒 | 个人 Rule 约束 |
| 14 | 主动读取 Prompt 模板 | 项目 Rule 约束 |
6.3 需人干预事项（8 项）
以下事项 AI 无法替代：
| # | 事项 | 执行时机 | 为什么 AI 做不了 |
|---|---|---|---|
| 1 | 确认需求 | 开发前 | AI 不理解业务背景 |
| 2 | 理解每行代码逻辑 | 开发中 | 不能盲目接受 AI 产出 |
| 3 | 补充业务背景注释 | 开发中 | AI 只能写技术注释 |
| 4 | 方案取舍决策 | 开发中 | AI 提供选项，人拍板 |
| 5 | 过审查清单 | 完成后 | 不能只靠 AI 自检 |
| 6 | 写 commit message | 完成后 | 标注 [ai-assisted] |
| 7 | 更新 Rule | 完成后 | 沉淀新发现的约定 |
| 8 | 定期审核规范 | 定期 | 确保 Rule 不过时 |
七、Prompt 资产化实践
7.1 三个核心模板
模板 1：新增 API 接口
适用场景：为新实体创建完整 CRUD
模板结构：
- 7 个必须参考的文件列表
- 9 条必须遵守的要求
- 输入输出示例
核心要求：
- 严格遵循 4 层架构
- API 层只做参数绑定和响应封装
- Service 层处理业务逻辑和默认值
- Model 层纯数据库操作
- Update DTO 用指针类型
- 统一使用
util.*响应 - 完成后更新索引
模板 2：Bug 修复
适用场景：定位并修复已知 Bug
模板结构：
- Bug 描述框架（现象 / 期望 / 复现步骤）
- 4 条修复要求（先分析根因、不影响其他功能、注意事务、过检查清单）
模板 3：代码审查
适用场景：让 AI 按清单检查代码质量
模板结构：
- 7 个审查重点
- 输出格式（✅ 通过 / ❌ 未通过 / ⚠️ 建议改进）
7.2 模板的使用方式
理想状态（已实现）：
用户：帮我新增一个 Workspace 的 CRUD 接口
AI 内部流程：
1. 识别场景 → "新增 API"
2. 自动读取 .ai/prompts/new-api.md
3. 按模板列出的 7 个文件，自动读取
4. 按模板的 9 条要求，生成代码
5. 完成后按协议输出收尾清单
用户只需要描述需求，AI 自行完成"读模板→读参考→执行"全流程。
八、完整实操手册
8.1 从零搭建（新项目）
Step 1：创建 Rule 文件
mkdir -p .codebuddy/rules/
创建 .codebuddy/rules/your-project.mdc，包含：
- 技术栈声明
- 架构约束（分层、依赖方向）
- 命名约定（文件、结构体、方法）
- 代码风格（Tag、注释标准）
- 业务术语表
关键：frontmatter 中设置 alwaysApply: true。
Step 2：创建 AI 协作工作区
mkdir -p .ai/prompts/
创建以下文件：
.ai/index.md— 项目索引.ai/context-guide.md— 上下文指南.ai/review-checklist.md— 审查清单.ai/prompts/new-api.md— 新增 API 模板.ai/prompts/fix-bug.md— Bug 修复模板.ai/prompts/code-review.md— 审查模板
💡 这些文件可以让 AI 帮你生成初始版本，然后人审核调整。
Step 3：添加强制执行协议
在 Rule 文件的最前面（所有其他章节之前）添加「强制执行协议」，定义 Phase 1 / Phase 3 的清单格式。
Step 4：纳入 Git 管理
git add .codebuddy/rules/ .ai/ Rule.md git commit -m "chore: 初始化 AI 协作开发规范体系"
8.2 日常开发流程
场景 A：新增 API 接口
Step 1 (👤 人) 「帮我新增 XXX 接口」
Step 2 (🤖 AI) 输出 📋 任务启动清单
Step 3 (🤖 AI) 自动读取 new-api.md 模板
Step 4 (🤖 AI) 自动读取 7 个参考文件
Step 5 (🤖 AI) 生成 4 层代码（Router → API → Service → Model）
Step 6 (🤖 AI) 输出 ✅ 任务完成清单
Step 7 (👤 人) 理解代码逻辑，补充业务注释
Step 8 (👤 人) 对照 review-checklist.md 检查
Step 9 (👤 人) git commit -m "feat(xxx): ... [ai-assisted]"
场景 B：修复 Bug
Step 1 (👤 人) 「XXX 功能有 Bug，现象是...」
Step 2 (🤖 AI) 输出 📋 任务启动清单
Step 3 (🤖 AI) 读取 fix-bug.md + index.md 定位文件
Step 4 (🤖 AI) 分析根因 → 生成修复代码
Step 5 (🤖 AI) 输出 ✅ 任务完成清单
Step 6 (👤 人) 理解修复逻辑
Step 7 (👤 人) git commit -m "fix(xxx): ... [ai-assisted]"
场景 C：Code Review
Step 1 (👤 人) 「帮我 review XXX 功能」
Step 2 (🤖 AI) 读取 code-review.md + review-checklist.md
Step 3 (🤖 AI) 读取 index.md 定位目标文件
Step 4 (🤖 AI) 按 34 项清单逐项检查，输出 ✅/❌/⚠️
Step 5 (👤 人) 对 ❌ 项决定是否修复
8.3 规范维护策略
| 文件 | 维护频率 | 维护者 | 触发条件 |
|---|---|---|---|
.codebuddy/rules/*.mdc | 随时 | 🤝 人+AI | 发现新约定或不一致时 |
.ai/index.md | 每次代码变更后 | 🤖 AI 直接更新 | 新增/修改文件或接口 |
.ai/context-guide.md | 低频 | 👤 人 | 出现新的开发场景 |
.ai/review-checklist.md | 低频 | 🤝 人+AI | 发现新的 AI 盲区 |
.ai/prompts/*.md | 低频 | 🤝 人+AI | 新增常见任务类型 |
九、效果度量与持续改进
9.1 度量指标
| 指标 | 衡量什么 | 如何收集 |
|---|---|---|
| Rule 遵循率 | AI 输出了 📋 清单的比例 | 观察 AI 回复第一段 |
| 一次通过率 | AI 代码不需要返工的比例 | Code Review 统计 |
| 盲区命中率 | 审查清单捕获的问题数 | Review 记录 |
| 索引新鲜度 | index.md 与实际代码的偏差 | 定期抽查 |
9.2 持续改进循环
实践 → 发现问题 → 更新 Rule/Checklist → 实践 → ...
例如：
发现"AI 用了 c.JSON" → 在 Rule 中加"禁止 c.JSON" → 发现"强制"被跳过
→ 加"强制执行协议" → 验证效果 → 发现新的逃逸模式 → 继续改进
9.3 已知可改进方向
| 方向 | 说明 | 优先级 |
|---|---|---|
| CI/CD lint | 在 pre-commit 中检查 c.JSON 等违规模式 | 🟠 中 |
| 自动化 Review | 每次 AI 生成代码后自动触发 review-checklist 检查 | 🟡 低 |
| Rule 版本管理 | 记录 Rule 的修改历史和修改原因 | 🟡 低 |
| 多项目模板 | 把方法论模板化，一键初始化新项目的规范体系 | 🟠 中 |
附录
A. 核心文件模板速查
| 文件 | 用途 | 模板要点 |
|---|---|---|
.codebuddy/rules/*.mdc | AI 行为约束 | frontmatter(alwaysApply:true) + 强制执行协议 + 架构约束 + 质量自检 |
.ai/index.md | 项目地图 | 目录结构 + API 路由表 + 数据模型 + 调用关系 + 变更日志 |
.ai/review-checklist.md | 质量关卡 | 8 大类检查项，重点关注 AI 常见盲区 |
.ai/prompts/*.md | 任务模板 | 参考文件清单 + 要求列表 + 示例 |
Rule.md | 规范总入口 | 8 项规范详解 + 人机分工矩阵 + Quick Start |
B. AI 常见盲区速查表
| 盲区 | 表现 | 检查方法 |
|---|---|---|
| 就近模仿 | 抄了邻居的错误写法 | 对照 Rule 逐条检查 |
| 事务遗漏 | 多表操作没用事务 | 搜索 db.Create 后是否有 db.Transaction |
| 级联遗漏 | 删主表没清关联表 | 搜索 Delete 方法中是否操作了关联表 |
| 硬编码 | URL、端口、密钥写死 | 搜索字面量字符串 |
| 默认值遗漏 | Create 时没设 status | 检查 Service 层的 Create 方法 |
| 错误吞没 | _ = someFunc() | 搜索 _ = 模式 |
| 信息泄漏 | 错误信息包含表名/SQL | 检查错误消息内容 |
C. Rule 逃逸模式速查表
| 逃逸模式 | 触发条件 | 防御手段 |
|---|---|---|
| 简单任务例外 | 任务"看起来简单" | 强制执行协议（无例外） |
| 就近模仿优先 | 上下文中有错误代码 | 先修正旧代码，或在 Rule 中明确标注 |
| 声明性约束失效 | "强制"标签被忽略 | 转为结构化输出要求 |
| 上下文过载 | Rule 太长 AI 抓不住重点 | 把最重要的规则放最前面 |
| 跨 Session 遗忘 | 新对话不记得上次约定 | 工作日志 + Rule 沉淀 |
D. 适用范围说明
本方法论基于 CodeBuddy AI 编码助手实践，但核心理念适用于任何 AI 辅助开发场景：
- IDE 工具不同：把
.codebuddy/rules/替换为对应工具的 Rule 目录 - 语言不同：八维方法论与语言无关，检查清单按语言特性调整
- 团队规模不同：1 人团队重点用维度 1-4，大团队全部维度都用上
📝 总结一句话：
AI 协作开发的核心挑战不是"让 AI 写代码"，而是"让 AI 按照你的规矩写代码，并且每次都按"。
这套方法论的本质是：把对 AI 行为的期望，从"希望它遵守"变成"能验证它是否遵守"。