AI 协作开发 Playbook（通用框架）

一份通用的、与 AI 协作开发的方法论与模板。本文档从两个真实工程复盘提炼，但主文不绑定任何具体项目——MARS 电机热流体仿真工程与 PCB 轴向磁通电机自动化仿真系统仅作为「案例来源 / 参考实现」出现在附录，供理解与对照学习。目标：在任何新项目上，与 AI 协作时能快速搭好框架、立刻开始干活，且过程可复现、可交接、可沉淀。

命名说明：本框架把「给 AI 的行为准则」统一命名为 AGENTS.md（业界通用标准文件名，Claude Code / Codex / Cursor 等主流 AI 工具默认自动读取）。

版本更新记录

本文档会持续迭代。每次改动在此追加一条：版本号 / 日期 / 改动内容 / 影响。

版本	日期	改动内容	影响
V1.0	2024（MARS 项目沉淀）	初版：三支柱文件（README/AGENTS/HANDOFF）+ 会话日志 + 规矩前置 + 接口文件化 + 验收量化 + 铁律带"为什么" + 换机接续 + 五步启动法 + 模板库	建立基础方法论，从 MARS 电机热仿真工程实战提炼
V2.0	2026-09-01	融合第二个项目（PCB 自动化仿真系统）实战经验：三支柱扩展为五支柱（+KNOWLEDGE_BASE + 留痕双件套）；新增里程碑管理、测试纪律、工程规范（禁臆测/自查清单/交付声明）、反模式自查表；新增 KNOWLEDGE_BASE / TEST_RECORDS / 里程碑三套模板	从"单项目经验"升级为"多项目通用框架"
V2.1	2026-09-01	通用化重构：主文移除所有具体项目描述（路径/参数/工具名），改为通用占位；两个真实项目降级为「案例来源」移入附录；新增本「版本更新记录」	文档成为不绑定项目的通用框架，可直接复制到任何新项目

后续迭代约定：新增一条版本记录时，写明「版本号 / 日期 / 改动内容 / 影响」四列；若改动较大，可在「改动内容」里分条说明。

0. 核心结论（30 秒读完）

AI 协作开发的效率，不取决于 AI 的能力，而取决于工程的秩序。

从真实项目复盘得出，真正让开发又快又稳的，是五件事：

五支柱文件 —— README（项目全貌）+ AGENTS.md（给所有 AI 的规矩）+ HANDOFF.md（接续指南）+ KNOWLEDGE_BASE.md（环境事实与踩坑）+ 留痕双件套（session_log + TEST_RECORDS）。AI 每次开工读一遍，就能带着全部上下文干活。
一条日志线 —— 每次对话都写 session_log，把「目标→动作→结论→踩坑→遗留」沉淀为组织记忆；每次测试写 TEST_RECORDS，把「环境→步骤→结果→问题→修复」落成可追溯记录。AI 永远不会重复踩坑。
规矩前置 + 铁律带"为什么" —— 开工前把协作约定写成显式规则；每条血泪教训配"为什么"，AI 才知道何时严格遵守、何时可以变通。
验收量化 + 独立验证 —— 每个里程碑都有可复核的数值基准，且校验方式 ≠ 产出方式；AI「看似完成」时能立刻被识别。
里程碑闭环 + 可交接 —— 用 Phase/Milestone 管理进度，每阶段完成即更新 README；HANDOFF + 接续提示词 + 环境体检脚本，让换人/换机/换会话在 10 分钟内接上。

1. 通用方法论要点（每个要点后附「案例」供对照学习）

1.1 五支柱文件：把"上下文"变成"资产"

五个文件分工，让任何新接手者（人类或 AI）能在 10 分钟内进入工作状态：

支柱	文件	写给谁	职责	关键内容
① 全貌	README.md	人类/全局	项目是什么、怎么跑、做到哪了	目标、目录表、工具链、常用命令、约定、最近更新
② 规矩	AGENTS.md	所有 AI（自动读取）	AI 的行为准则	工作约定、关键接口、铁律、已知坑、文档索引、反模式自查
③ 接续	HANDOFF.md	接续者	换人/换机/续作入口	环境要求、恢复步骤、当前进度、阻塞点、接续提示词
④ 知识	docs/KNOWLEDGE_BASE.md	人 + AI	环境事实、参数语义、探测技术、SOP、已踩的坑	环境验证命令、常见问题表、连接/求解 SOP、踩坑清单
⑤ 留痕	docs/session_log.md + docs/TEST_RECORDS.md	组织记忆	对话留痕 + 测试留痕	目标→动作→结论→踩坑→遗留；环境→步骤→结果→问题→修复

要点：

README 是「静态全貌 + 滚动更新」，HANDOFF 是「动态状态」，AGENTS 是「行为规则」，KNOWLEDGE_BASE 是「环境与坑的事实库」，留痕双件套是「过程记录」。五者分工明确，不要混在一起，否则更新时互相打架。
session_log 与 TEST_RECORDS 必须分离：session_log 记"对话做了什么、踩了什么坑、遗留什么"；TEST_RECORDS 记"测试怎么跑的、结果如何、修了什么"。混淆会导致追溯困难。
AGENTS.md 之所以有效，是因为主流 AI 工具在项目目录里工作时会自动读取它。你要做的，是把「期望 AI 怎么干活」全部写进去。

案例对照：①—④ 出自两个真实项目的共同实践；⑤「留痕双件套」在第一个项目只做了会话日志，第二个项目补上了 TEST_RECORDS 测试记录，并验证了二者分离的价值。

1.2 会话日志 + 测试记录 = 组织记忆

会话日志（统一模板）：

## YYYY-MM-DD · 第 N 次对话 —— 一句话目标
### 用户要求（要点）
### 本次完成（动作 + 结果）
### 用户纠偏（如有）—— 纠正：为什么，如何修正
### 遗留问题 / 待确认

测试记录（每条含索引 + 详细）：

## TEST-XXX：测试主题
**日期** / **测试环境** / **测试目的** / **测试脚本** / **输出目录**
### 测试步骤与结果（表格：步骤 | 内容 | 结果 | 详情）
### 关键数据 / 发现的问题 / 修复措施

为什么有效：

对话是易失的，日志是持久的。AI 换会话、换机器后，靠日志重建上下文。
踩过的坑全部沉淀下来，成为后续 AI 的"避坑清单"。
记录本身是一种校验：写完日志，等于把这次对话"归档了"，可以安心进入下一目标。
强制约束：每次对话、每次测试都必须留痕，没有例外。

案例对照：两个项目分别沉淀了 20+ 条避坑记录（API 常量、工具特定行为、环境变量陷阱等），验证了「记录即资产」。

1.3 规矩前置：把协作摩擦降到零

开工第 1 天就立好的规矩（可裁剪、可扩充）：

每次测试前先 git commit（可回退）
每次对话写 session_log、每次测试写 TEST_RECORDS（可追溯）
文件名只用 ASCII 且有意义（不许 1111.prt 这种）
源码（.py/.ps1）只含 ASCII，中文说明写进 Markdown；脚本用英文注释、报告文档可用中文
生成 PPT/PDF 用专门的 skills
有 GUI 的程序必须前台运行；后台 Python 一律加 -u（否则看不到进度）
参考目录只读，不许改；原始模型只读（操作在内存或时间戳副本）
特定工具链必须用特定解释器
生成物不入库（output/、build/、dist/、*.log 等），关键数值转录进文档

要点：规矩要具体到「AI 能执行」，不要写"注意规范"这种空话。

1.4 接口文件化 + 单一事实源：让 AI 的修改可预期

把"关键数据接口"做成文件，把 AI 修改的边界明确框定：

<project>/data/<interface>.csv   ← 改这一个文件，重跑指定步骤，即可换输入
<project>/src/<core>/<def>.py    ← 指标/拓扑/参数等定义的唯一权威，多端消费
<project>/config/<xxx>.json      ← 可执行程序侧车配置，改配置无需重新构建

为什么有效：AI 修改的边界被明确框定——「只改这个文件，别动其他东西」。可预期的修改 = 可审查的修改 = 可回退的修改。凡是被多处消费的定义，必须收敛到单一事实源，禁止多处漂移（否则会出现"改一处漏两处"的返工）。

案例对照：第一个项目用 CSV 接口文件换输入；第二个项目把指标/拓扑/参数 Schema 各归一个权威定义（单一事实源），并因曾有三处定义漂移而返工。

1.5 验收基准 + 测试纪律：防止"看似完成"

每个里程碑都留下量化验收基准，并立下规矩：对不上就别往下走。

测试纪律（强烈推荐）：

每段交付代码必须附带可运行的测试用例，至少覆盖：正常路径 / 边界条件（极值、上下限）/ 异常输入（非法值、缺字段、类型错误）/ 空值零值场景
测试脚本统一放 scripts/test_*.py，命名与被测模块对应；python scripts/test_*.py 可独立运行，exit 0 = PASS
无法自动化的场景（真实求解、真实 AI 调用）必须给出可复现的手动测试步骤，或标注"待验证"
全量回归：每个里程碑结束跑一遍全部 test_*.py，防止回归

要点：验收要「可复核、可重跑」，且校验方式最好与产出方式不是同一条代码路径（否则不算独立验证），不是"看起来对了"。

1.6 铁律沉淀：把血泪教训变成规则

把吃过亏的地方写成「铁律」，并且每条都带"为什么"（示例，实际请按你的项目补充）：

任何几何/数据改动后核对「数量 + 总量」不变量。（曾两次在坏数据上白跑）

检查必须用精确模式，不要用快速模式。（快速模式漏掉大部分问题）

不要用某工具的某操作，改用替代方案。（会留副本、后续修复会碎裂）

先 A 后 B，顺序不能反。（顺序反了会建立依赖链，之后无法再改）

工具实例用独立实例，不连已有实例；启动后设为前台可见。（可能控制错误窗口；脚本模式默认隐藏）

参数写入必须回读校验，不一致标记失败并继续。（静默写入失败会污染整批结果）

结果逐点落盘并 flush。（崩溃不丢已算点；不能等整批）

仿真禁止跑在主线程。（GUI 会卡死，必须子线程）

非登录 shell 可能不继承机器级环境变量 → 脚本内回退。（否则工具找不到/静默退出）

要点：规则带"为什么"，AI 才知道什么时候该严格遵守、什么时候可以判断变通。

1.7 换机接续：环境差异变成可检测项

写一个 scripts/check_machine_paths.py，一条命令核对软件路径（可能散落在多个文件）、专用解释器、依赖包、仓库资产、Git 状态，并提供 --fix 一键修正（或打印精确修复命令）。

要点：把"环境假设"写成可检测的脚本，新机器第一条命令就能确认环境。

案例对照：第二个项目把工具定位、许可证、依赖包、仓库资产、Git 干净度全部纳入体检，并发现"AI shell 解释器与项目运行环境分离"这一常见陷阱。

1.8 里程碑管理：Phase/Milestone + 每阶段更新 README

用 Phase（阶段）/ Milestone（里程碑） 两级粒度推进，并立下硬纪律：

每个 Phase 或 Milestone 完成后，必须立即更新 README.md，记录：完成的功能点、新增的文件/模块、关键技术决策、已知问题和后续计划
不允许"代码提交了但 README 没更新"的情况；README 更新应与代码提交在同一 commit 中或紧随其后
每个里程碑规划时写清：计划内容 → 实际交付 → 状态 → Commit（可追溯）

为什么有效：里程碑是"可复核的最小单元"，每完成一个就闭环一次（记录→验收→提交→更新文档），避免大段工作无人可查。

1.9 工程规范：禁臆测 + 自查清单 + 交付声明

工程规范（优先级高于"完成速度"）：

禁止臆测：不得编造任何未实际验证的结果、数值、接口行为或"应该能跑"的结论。若无法运行或测试某段代码/场景，必须明确说明"我无法执行此测试，以下是我的推理/建议"，并给出理由与降级方案。
测试完备：见 1.5 测试纪律。
代码规范：遵循语言标准规范（Python 遵循 PEP8）；关键逻辑必须有注释；复杂函数/类必须有 docstring（函数用途、参数、返回值、异常）。
自查清单（交付前逐项确认，标注 ✅/❌）：代码已通读无语法错误和明显逻辑漏洞 / 所有测试用例已列出且能描述预期输入输出 / 已考虑边界情况（空值、极值、并发、超时、资源耗尽）/ 已考虑错误处理路径（异常捕获、回滚、降级）/ 多模块时已确认接口契约和数据流向 / 无法实际运行测试时已明确告知用户。
交付声明：只有完成上述自查并确认无误后，才能说"已完成/已通过"；否则必须使用"草案待验证"或"需要您协助测试"，并说明缺口。
迭代修正：若用户反馈测试失败，必须：复现问题 → 定位根因 → 修复 → 重新走一遍自查清单 → 再回复。不得仅口头致歉后跳过复现与修复。

1.10 反模式自查：把 AI 协作的坑写成表

反模式	后果	对策
不读文档直接开工	跑偏、重复踩坑	接续提示词强制"先读、先报告理解、再动手"
规矩只写"注意规范"	AI 无法执行	规矩写到"可执行、可检查"的颗粒度
验收凭"看起来对"	假完成	量化基准 + 独立验证
踩坑不记录	下次再踩	每次坑都追加到 AGENTS.md 铁律 / KNOWLEDGE_BASE
环境假设不检测	换机全崩	check_machine_paths.py 一键核对
上下文只留在对话里	换会话即失忆	session_log 持久化
让 AI 多任务并行	上下文混乱、互相污染	一次一个目标
只给结论不给原因	AI 无法变通	规则带"为什么"
多处定义同一概念	三处漂移、改一处漏两处	单一事实源（各归一个权威定义）
编造未验证的数值/接口	返工、误导决策	禁臆测 + 交付声明 + "待验证"标注
只跑功能不跑回归	改一处坏一片	每个里程碑结束跑全量 test_*.py
阶段完成不更新文档	文档与代码脱节、无人能接手	每 Phase/M 完成立即更新 README

2. 通用框架：五步启动法

Phase 0  探查    读懂现状/需求，不猜
Phase 1  立规矩  五支柱文件 + 会话日志 + 约定 + git init
Phase 2  搭骨架  目录结构 + 接口文件（单一事实源）+ 最小可跑通闭环 + 第一个验收基准
Phase 3  迭代    一次一个目标 → 记录 → 验收 → 提交 → 更新 README（里程碑粒度）
Phase 4  交接    写清状态/阻塞/下一步 + 接续提示词 + 环境体检脚本

Phase 0 · 探查（半天内）

把需求、参考资料、旧代码全部读完，先理解再动手。
确认：交付物各部分有来源；计划依赖的事实已拿到；没有靠"应该/大概"支撑的关键步骤。
连续两次读取都不再改变计划，就停止探查、开工。

Phase 1 · 立规矩（半天内）

建目录结构（见 3.1）；写五支柱（README / AGENTS / HANDOFF / KNOWLEDGE_BASE / session_log+TEST_RECORDS）；git init 第一次 commit。
把「工作约定」写进 AGENTS.md（提交时机/命名/注释语言/GUI 前台/参考目录只读/专用解释器/生成物不入库）。

Phase 2 · 搭骨架（1 天内）

把「关键数据接口」文件化（单一事实源）。
打通一条最小可跑通的端到端闭环（哪怕结果粗糙）。
写第一个验收基准（哪怕粗），并注明独立校验方式。

Phase 3 · 迭代（主体过程）

用 Phase/Milestone 粒度规划，每次只推进一个目标，做完立即：记录 session_log → 跑验收基准 + 全量回归（对不上就停）→ git commit → 更新 README → 下一个。
发现坑 → 立刻把「铁律」追加进 AGENTS.md / KNOWLEDGE_BASE。
每个里程碑完成即是一个"可复核、可回溯、可交付"的闭环。

Phase 4 · 交接

更新 HANDOFF.md：环境要求、恢复步骤、当前进度、阻塞点、下一步、已知坑速查。
写 scripts/check_machine_paths.py（环境体检 + --fix）。
写好给 AI 的接续提示词（见 3.6），让下一个会话/机器/人 10 分钟内接上。

3. 可直接复制的模板

3.1 目录结构模板

<project>/
├── README.md              # 项目全貌 + 最近更新（人类读）
├── AGENTS.md              # AI 行为准则（AI 自动读）
├── HANDOFF.md             # 接续指南（换人/换机/AI 续作）
├── docs/
│   ├── KNOWLEDGE_BASE.md  # 环境事实 + 参数语义 + 探测技术 + SOP + 已踩的坑
│   ├── session_log.md     # 会话日志（组织记忆：目标→动作→结论→踩坑→遗留）
│   ├── TEST_RECORDS.md    # 测试记录（环境→步骤→结果→问题→修复）
│   └── figures/           # 图表
├── data/                  # 机器可读数据 + ★接口文件（改这里即可改输入）
├── scripts/               # 自动化脚本（英文注释）+ test_*.py 测试
├── src/ 或 work/          # 实际工作产物（含单一事实源定义层）
├── reference/             # 参考材料（只读，不许改）
├── package.json           # 如有 JS 依赖
└── .gitignore             # 生成物不入库

3.2 README.md 模板

# <项目名> —— <一句话定位>

<两句话：这个项目做什么、目标链路是什么>

| 项目 | 内容 |
|---|---|
| 文档版本 | V<X>（<最新完成阶段>） |
| 当前状态 | P1 ✅ / P2 进行中 / ... |

## 目录
| 路径 | 说明 |
|---|---|
| `src/` | ... |
| `scripts/` | ... |
| `data/` | ... |

## 工具链
| 工具 | 版本 | 路径 | 备注 |
|---|---|---|---|
| ... | ... | ... | ... |

## 约定
- 每次测试前先 git commit
- 每次对话记录到 docs/session_log.md；每次测试记录到 docs/TEST_RECORDS.md
- 文件名只用 ASCII 且有意义；源码 ASCII，脚本英文注释，报告可用中文
- <参考目录只读等约束>

## 最近更新（YYYY-MM-DD）
### <Px-My>：<主题>
**背景** / **改动内容** / **涉及文件** / **验证**（含 TEST 编号）/ **已知问题**

## 常用命令
python scripts/<入口>.py

3.3 AGENTS.md（给所有 AI 的规矩）模板

# <项目名> AI 协作规矩

**接续请先读 HANDOFF.md。**

## 开始工作前必须阅读（按顺序）
1. docs/KNOWLEDGE_BASE.md —— 核心知识库（环境事实、参数语义、SOP、已踩的坑）
2. docs/HANDOFF.md —— 当前进度与接续指南
3. README.md —— 项目全貌与最近更新

## 工作约定
- 每次测试前先 git commit
- 每次对话记录到 docs/session_log.md；每次测试记录到 docs/TEST_RECORDS.md
- 文件名只用 ASCII 且有意义；源码 ASCII，脚本用英文注释；报告文档可用中文
- 生成 PPT/PDF 用 skills
- 有 GUI 的程序必须前台运行；后台 Python 一律加 -u
- 不要修改 <reference>/ 下任何内容（只读）；原始模型只读
- <特定工具>必须用 <特定解释器> 运行
- 生成物不入库

## 关键接口（单一事实源）
- `data/<interface>.csv` 或 `src/<core>.py` —— 改这一个文件即可换输入，然后重跑 <步骤A> + <步骤B>
- 凡被多处消费的定义，必须收敛到单一事实源，禁止多处漂移

## 铁律（每条带"为什么"）
1. <规则>（<原因>）
2. ...

## 已知坑
- <坑> → 表现 → 对策（详见 KNOWLEDGE_BASE.md / session_log.md）

## 反模式自查（交付前对照）
- <反模式1> → <对策1>；<反模式2> → <对策2>；...

## 工程规范
- 禁止臆测；测试完备（正常/边界/异常/空值）；交付前自查清单 ✅/❌；未过自查只能说"草案待验证"

## 当前状态
- 已完成：... / 进行中：... / 阻塞：...

## 文档索引
| 文档 | 内容 |
|---|---|
| HANDOFF.md | 接续指南 |
| docs/KNOWLEDGE_BASE.md | 环境事实与踩坑 |
| docs/session_log.md | 会话记录 |
| docs/TEST_RECORDS.md | 测试记录 |

3.4 会话日志模板（`docs/session_log.md`）

# 会话记录 / Session Log

## YYYY-MM-DD · 第 N 次对话 —— <一句话目标>
### 用户要求（要点）
- <要点>
### 本次完成
1. <动作> → <结果>
### 用户纠偏（如有）
- <纠正>：<为什么>，<如何修正>
### 遗留问题 / 待确认
- <问题>

3.5 HANDOFF.md 接续指南模板

# 接续指南 · <项目名>

面向<换人/换机/新会话>后继续工作的场景。

## 1. 环境要求
| 软件 | 版本 | 用途 | 必需性 |
|---|---|---|---|
| ... | ... | ... | ... |

## 2. 恢复步骤（第一条命令）
python scripts/check_machine_paths.py   # 核对环境

## 3. 当前进度
### 已完成 | 当前阻塞点 | 待办

## 4. 给 AI 的接续提示词（整段粘贴，见 3.6）

3.6 给 AI 的「接续提示词」模板

这是 <项目名> 项目，<一句话定位>。

【先做这几件事，做完再动任何东西】
1. 读 HANDOFF.md、docs/KNOWLEDGE_BASE.md、docs/session_log.md、AGENTS.md。
   KNOWLEDGE_BASE 和 session_log 里记录了大量踩过的坑，请重点看，不要重复踩。
2. 核对环境：python scripts/check_machine_paths.py
3. 恢复工作目录/依赖：<具体命令>

【工作约定（必须遵守）】
- 每次测试前先 git commit；每次对话记录到 docs/session_log.md；每次测试记录到 docs/TEST_RECORDS.md
- 文件名只用 ASCII 且有意义；源码 ASCII，脚本用英文注释
- 有 GUI 的程序必须前台运行；后台 Python 加 -u
- 不要修改 reference/ 目录；<特定工具用特定解释器>；生成物不入库

【铁律（血泪教训）】
- <规则1> / <规则2> / ...

【当前状态】
- 已完成：... / 阻塞：... / 待办：...

【接下来做什么】
- <目标1> / <目标2>

先读文档、恢复环境、跑 check_machine_paths.py，然后告诉我你的理解
和建议的下一步，不要直接开始改东西。

最后一句「先理解、别直接改」很重要——让 AI 先对齐认知，而不是闷头干活跑偏。

3.7 验收基准表模板

| 验收项 | 基准 | 校验方式 | 独立于产出路径？ |
|---|---|---|---|
| <关键输出1> | <数值/逐位一致> | <命令/脚本> | 是/否 |
| <关键输出2> | 误差 ≤ X | <独立验证路径> | 是 |

对不上就别往下走。

要点：校验方式最好与产出方式不是同一条代码路径（否则不算独立验证）。

3.8 环境检查脚本思路（`scripts/check_machine_paths.py`）

纯只读、不修改任何东西的脚本，检查清单：

软件安装根目录（可能散落在多个文件里，必须一致）
环境变量（工具定位、许可证——非登录 shell 可能不继承）
专用解释器/二进制是否存在
Python（或其他运行时）依赖包是否齐全
仓库内资产（几何/数据/依赖）是否齐全
Git 仓库干净 + HEAD 有效
工作目录是否已恢复对每个缺失项给出"改法"，并提供 --fix 一键修正（或打印精确修复命令）。建议探测项目内 venv，提示用其解释器复检（避免"当前 shell 与项目环境分离"误报）。

3.9 KNOWLEDGE_BASE 模板（`docs/KNOWLEDGE_BASE.md`）

# 知识库 — <项目名>

> 本文件是项目的核心知识沉淀，供人和任何 AI 工具阅读使用。
> 全部结论基于 <参考案例/实测> 的验证。

## 1. 环境事实
| 项 | 值 |
|---|---|
| <工具> | <版本> |
| 定位方式 | <环境变量/路径> |
| 许可证 | <服务/端口> |
| 非登录 shell 陷阱 | ... |

### 1.1 环境验证命令
### 1.2 常见环境问题（现象 | 原因 | 解决）

## 2. <工具> 自动化核心方法
### 2.1 连接与实例管理
### 2.2 模型加载与保存
### 2.3 参数写入（含回读校验）
### 2.4 结果导出与解析

## 3. 参数语义
## 4. 已踩的坑（铁律来源）
## 5. SOP（标准操作流程）

3.10 TEST_RECORDS 模板（`docs/TEST_RECORDS.md`）

# 测试记录与结果总结

> 每次测试必须记录在此文档中（工作留痕）。
> 最后更新：YYYY-MM-DD

## 测试记录索引
| 编号 | 日期 | 测试类型 | 结果 | 关键发现 |
|---|---|---|---|---|
| TEST-001 | ... | ... | ... | ... |

## TEST-001：<主题>
**日期**：...
**测试环境**：...
**测试目的**：...
**测试脚本**：`scripts/test_xxx.py`
**输出目录**：`output/.../`
### 测试步骤与结果
| 步骤 | 内容 | 结果 | 详情 |
|---|---|---|---|
### 关键数据 / 发现的问题 / 修复措施

3.11 里程碑管理模板（README 或独立里程碑计划文档）

## Px-My：<主题>
**背景**：<为什么做>
**改动内容**：<做了什么>
**涉及文件**：<新增/修改的文件>
**验证**：<测试脚本 + 结果 + TEST 编号>
**技术决策**：<关键取舍及理由>
**已知问题/后续**：<遗留项>

4. 日常迭代的铁律清单（随项目增长不断追加）

在 AGENTS.md 里维护一份「铁律」，每条格式：规则 + 为什么。以下为通用示例，请替换为你的项目的真实血泪教训。

#	规则	为什么
1	任何数据/几何改动后核对「数量 + 总量」不变量	曾两次在坏数据上白跑，只报"操作成功"会漏掉损坏
2	关键输入的体积/数值必须保持不变	输入按件映射，改了映射就失效
3	检查必须用精确模式，不要用快速模式	快速模式漏掉大部分问题
4	不要用<某工具>的<某操作>，改用<替代方案>	会留副本、后续修复会碎裂
5	先后，顺序不能反	顺序反了会建立依赖链，之后无法再改
6	量关键尺寸不要用包围盒接口	对薄壁件虚报数值，要用独立解析
7	同类错误再次出现时查共同成因	warning 即使伴随成功也必须处理
8	工具实例用独立实例，不连已有实例；启动后设为前台可见	可能控制错误窗口；脚本模式默认隐藏
9	参数写入必须回读校验，不一致标记失败并继续	静默写入失败会污染整批结果
10	结果逐点落盘并 flush	崩溃不丢已算点；不能等整批
11	仿真/长任务禁止跑在主线程	GUI 会卡死，必须子线程
12	非登录 shell 要回退设置环境变量	环境变量不继承会导致工具找不到/静默退出

5. 与 AI 协作的沟通技巧（实战心得）

5.1 纠正要具体、要给"为什么"

❌ "这个不对，重新做"
✅ "xxx 用错了：原因是 <技术事实>，请改用 <方案>。依据：<文档/实测>"

5.2 验收必须量化、可独立复核

给 AI 明确基准：逐位一致、误差 ≤ X、收敛阈值。
要求「校验方式 ≠ 产出方式」（独立验证）。

5.3 让 AI 区分事实与推测

要求 AI 标注：已查证 / 估算 / 待确认 / 一方称。
关键数字必须来自输入、具体信源或可复现计算，否则标为待补充并写明口径。

5.4 一次只推一个目标

每个会话/阶段聚焦一件事：做完 → 记录 → 验收 → 提交 → 下一个。

5.5 信息不足就反问，不猜

有歧义时让 AI 用「我的理解是 X，但缺少 Y，请确认 A/B」反问。

5.6 受阻时换通道，不降级交付

同一动作失败两次就换命令/目录/依赖/实现路径。换的是执行通道，不是交付标准。

5.7 异议强制机制

当需求存在技术矛盾、逻辑漏洞、安全隐患或实现风险时，AI 必须打断并指出："【风险提示】<具体问题>。建议方案：<替代方案>，依据：<技术事实>。"禁止为迎合而执行明显错误的指令。

6. 常见反模式（AI 协作中的坑）

反模式	后果	对策
不读文档直接开工	跑偏、重复踩坑	接续提示词强制"先读、先报告理解、再动手"
规矩只写"注意规范"	AI 无法执行	规矩写到"可执行、可检查"的颗粒度
验收凭"看起来对"	假完成	量化基准 + 独立验证
踩坑不记录	下次再踩	每次坑都追加到 AGENTS.md 铁律
环境假设不检测	换机全崩	check_machine_paths.py 一键核对
上下文只留在对话里	换会话即失忆	session_log 持久化
让 AI 多任务并行	上下文混乱、互相污染	一次一个目标
只给结论不给原因	AI 无法变通	规则带"为什么"
多处定义同一概念	改一处漏两处	单一事实源
编造未验证的数值	误导决策	禁臆测 + 交付声明
不跑回归就收工	改一处坏一片	里程碑结束跑全量 test_*.py
阶段完成不更新文档	无人能接手	每 Phase/M 完成更新 README

7. 快速上手 Checklist（新项目第一天）

Phase 0 读完所有参考资料/旧代码，确认关键事实有来源
Phase 1 建目录结构（README / AGENTS.md / HANDOFF / docs/KNOWLEDGE_BASE / docs/session_log / docs/TEST_RECORDS / data / scripts / reference）
Phase 1 git init + 第一次 commit
Phase 1 把「工作约定」写进 AGENTS.md（提交时机/命名/注释语言/GUI 前台/参考目录只读/专用解释器/生成物不入库）
Phase 2 把「关键输入」做成一个接口文件（单一事实源），写清"改这一个文件 + 重跑哪几步"
Phase 2 打通最小可跑通的端到端闭环
Phase 2 写下第一个验收基准（量化、可独立复核）
Phase 2 写第一个 test_*.py（含正常/边界/异常/空值）
Phase 3 开始迭代：一次一个目标 → 记录 session_log → 验收 + 全量回归 → commit → 更新 README
Phase 3 每踩一个坑，立即追加到 AGENTS.md 铁律 / KNOWLEDGE_BASE（规则 + 为什么）
Phase 4 阶段末更新 HANDOFF.md（进度/阻塞/待办 + 接续提示词）
Phase 4 写 scripts/check_machine_paths.py（环境体检 + --fix）

附录：案例来源与参考实现

本框架从以下两个真实工程提炼。主文为通用方法论，此附录仅用于说明「每条方法论是从哪种场景验证得来的」，供对照学习。

案例 A：MARS 电机热流体仿真工程（框架 V1 来源）

场景：电机热流体仿真，多软件工具链（电磁损耗 → 热仿真 → 交叉校核），50+ 自动化脚本，跨机器迁移，AI 全程参与。
沉淀贡献：三支柱文件、会话日志、规矩前置、接口文件化、验收量化、铁律带"为什么"、换机接续脚本、五步启动法、接续提示词。
参考实现：CLAUDE.md（AGENTS.md 原名）、HANDOFF.md、docs/session_log.md、scripts/check_machine_paths.py、data/heat_loads.csv。

案例 B：PCB 轴向磁通电机自动化仿真系统（框架 V2 来源）

场景：双系统解耦的电机自动化仿真平台（Web 方案生成 + 本地 EXE 仿真执行），Motor-CAD 自动化，P1~P6 六个 Phase 迭代，AI 全程参与。
沉淀贡献：五支柱扩展（KNOWLEDGEBASE + 留痕双件套）、里程碑管理、测试纪律（test*.py 全量回归）、工程规范（禁臆测/自查清单/交付声明）、单一事实源、反模式自查表、环境变量陷阱文档化。
参考实现：AGENTS.md、docs/KNOWLEDGE_BASE.md、docs/TEST_RECORDS.md、docs/HANDOFF.md、scripts/check_machine_paths.py、scripts/test_*.py。

如何使用本框架

新项目：直接复制本文档，按第 7 节「快速上手 Checklist」初始化。
遇到不确定的方法论细节，可回看附录两个案例的参考实现文件。
本框架随你持续迭代——每次改动在「版本更新记录」追加一条。

ai-collab-dev-playbook-v2.md 32 KB История Исходник