AI 协作流程规范

版本: v1.0 | 更新: 2026-10-01 相关: README.md · ai_agent_rules.md · ../ai_coding_knowledge.json

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

§0 三条不可协商的原则

不一次性生成大量代码 —— 任务必须可拆解（anti_pattern:one-shot-big）
没有验收标准不开工 —— 否则无法判断何时完成（method:acceptance-criteria）
不审查 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 完成流程：自动记录（关键，不可跳过）

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

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 传递）——在仓库根执行：
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）

5.5 KiB Raw Blame History Unescape Escape