# AI 协作流程规范

> 版本: v1.0 | 更新: 2026-10-01
> 相关: [README.md](README.md) · [ai_agent_rules.md](ai_agent_rules.md) · `../ai_coding_knowledge.json`

定义 AI 在本项目中的**协作流程**：怎么规划、怎么验证、怎么收尾、怎么沉淀。目标 —— 产出可验证、经验可复利。

---

## §0 三条不可协商的原则

1. **不一次性生成大量代码** —— 任务必须可拆解（`anti_pattern:one-shot-big`）
2. **没有验收标准不开工** —— 否则无法判断何时完成（`method:acceptance-criteria`）
3. **不审查 diff 不算完成** —— AI 的自我描述可信度低于实际改动（`method:review-diff`）

## §1 主工作流：Explore → Plan → Implement → Verify

| 阶段 | 做什么 | 产出 |
|------|--------|------|
| **Explore** | 读相关源码 / 规格 / 知识图谱实体，确认现状与约束 | 现状结论 + 涉及文件清单 |
| **Plan** | 输出结构化步骤（步骤 + 依赖 + 验收标准）；复杂任务**先给计划再动手** | 计划（TodoWrite 跟踪） |
| **Implement** | 按计划分步实现，**一步一验证**，不攒到最后一起验 | 可增量验证的改动 |
| **Verify** | 跑门禁；失败回到 Implement | 门禁通过证据 |

> 复杂任务（跨 3 个以上模块 / 涉及数据模型 / 涉及部署）**必须先出计划并等确认**。

## §2 任务拆解铁律

- **窄范围 > 大而模糊**：`修 /api/tools 分页 total 字段` 优于 `改进工具模块`
- 每步定义**输入**（依赖文件/数据）与**输出**（验收标准）
- 状态机驱动：`Pending → Running → Blocked → Done / Failed`
- 单任务改动建议 ≤15 个文件；超出则重新拆解

## §3 验收标准（每个任务开工前必须明确）

| 任务类型 | 验收标准 |
|---------|---------|
| 功能开发 | `npx tsc --noEmit` 零错误 + `npx vitest run` 全绿 + 新功能可用 + 无回归 |
| Bug 修复 | 复现路径通过 + 相关测试通过 |
| 重构 | 行为不变 + 测试全绿 + 无性能回归 |
| 数据/脚本 | 输出格式正确 + 样例验证通过 + 幂等可重跑 |
| 部署/运维 | 部署后自检清单全通过（见 project_rules.md §15.3） |

本项目**双门禁**：`npx tsc --noEmit` + `npx vitest run`（缺一不可）。

## §4 代码审查：看 diff 不看对话

- 用 `git diff` 逐行审查**实际改动**
- 对照 `§3 验收标准` 核验，而不是对照 AI 的说法
- 重点排查：臆造的 API/字段、被静默删除的逻辑、异常处理缺失、硬编码密钥

## §5 失败分型（先分型，再优化）

| 失败类型 | 表现 | 优化方向 |
|---------|------|---------|
| 规划失败 | 任务拆解不合理、范围失控 | 重新拆解任务 |
| 执行失败 | 命令/环境/依赖报错 | 修工具、环境、依赖 |
| 质量失败 | 结果不满足验收标准 | 收紧验收标准或加门禁 |

> 禁止把所有失败都归因为「模型不够强」（`anti_pattern:model-is-everything`）。

## §6 完成流程：自动记录（关键，不可跳过）

开发完成并通过门禁后，**必须**运行：

```bash
npm run knowledge:update
# 等价于：node scripts/update-knowledge.mjs（可加 --dry-run 预览，不写文件）
```

脚本自动捕获三类信息并沉淀：

| 捕获内容 | 来源 | 落盘位置 |
|---------|------|---------|
| **能力特征** | 扫描 `src/app/api/**/route.ts`、`src/app/**/page.tsx`、`src/components/**`、`prisma/schema.prisma`、`scripts/**`、`crontab.txt`、`package.json`、`data/bot-characters.json` | `.trae/knowledge/capabilities.json` |
| **开发过程** | `git log`（最近提交：hash/时间/主题/改动文件数） | `.trae/knowledge/dev_process.jsonl`（按提交追加） |
| **模型成果** | 本次交付物：新增迁移、新增/变更脚本、提交统计 | `.trae/knowledge/artifacts.jsonl`（追加） |

并**增量 upsert**（按实体名，同名替换 observations，未出现的旧实体原样保留，永不删除）：

- `.trae/knowledge_graph.json`（渲染版，人类可读 + 权威）
- `.trae/knowledge_graph.jsonl`（MCP Knowledge Graph Memory 读取的源文件）

**自动化触发**：本机已装 `git post-commit` 钩子（`.git/hooks/post-commit`），每次提交后自动执行同一脚本（静默 + 后台，不阻断、不拖慢提交），无需手动记得。

> **换机 / 新克隆后重装钩子**（`.git/hooks/` 不随 git 传递）——在仓库根执行：
> ```bash
> printf '#!/bin/sh\nROOT=$(git rev-parse --show-toplevel) || exit 0\n[ -f "$ROOT/scripts/update-knowledge.mjs" ] || exit 0\ncommand -v node >/dev/null 2>&1 || exit 0\n( cd "$ROOT" && node scripts/update-knowledge.mjs --quiet >/dev/null 2>&1 & )\nexit 0\n' > .git/hooks/post-commit
> ```
> 卸载：删除 `.git/hooks/post-commit` 即可（脚本本身仍可手动运行）。

> 未运行记录脚本就结束任务，视为**流程未完成**。

## §7 反模式（禁止）

| 反模式 | 替代做法 |
|--------|---------|
| 一次性生成大量代码 | 任务拆解（§2） |
| 无验收标准 | 先定义验收标准（§3） |
| 不审查 AI 代码 | 看 diff + 双门禁（§4） |
| 一次性灌入冗余上下文 | 上下文预算，按需加载 |
| 把「模型更强」当「系统更稳」 | 模型 + 编排 + 门禁三层闭环 |
| 同一知识多份副本 | 单一事实源 + 引用 |
| 知识库只写不更新 | §6 自动记录 + 定期一致性巡检 |

## §8 版本历史

| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-10-01 | v1.0 | 初始版本：Plan-first 四阶段 + 验收标准 + 完成自动记录（§6） |