# 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 的能力，而取决于工程的秩序**。

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

1. **五支柱文件** —— README（项目全貌）+ AGENTS.md（给所有 AI 的规矩）+ HANDOFF.md（接续指南）+ KNOWLEDGE_BASE.md（环境事实与踩坑）+ 留痕双件套（session_log + TEST_RECORDS）。AI 每次开工读一遍，就能带着全部上下文干活。
2. **一条日志线** —— 每次对话都写 session_log，把「目标→动作→结论→踩坑→遗留」沉淀为组织记忆；每次测试写 TEST_RECORDS，把「环境→步骤→结果→问题→修复」落成可追溯记录。AI 永远不会重复踩坑。
3. **规矩前置 + 铁律带"为什么"** —— 开工前把协作约定写成显式规则；每条血泪教训配"为什么"，AI 才知道何时严格遵守、何时可以变通。
4. **验收量化 + 独立验证** —— 每个里程碑都有可复核的数值基准，且**校验方式 ≠ 产出方式**；AI「看似完成」时能立刻被识别。
5. **里程碑闭环 + 可交接** —— 用 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 铁律沉淀：把血泪教训变成规则

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

> 1. 任何几何/数据改动后核对「数量 + 总量」不变量。（曾两次在坏数据上白跑）
> 2. 检查必须用精确模式，不要用快速模式。（快速模式漏掉大部分问题）
> 3. 不要用某工具的某操作，改用替代方案。（会留副本、后续修复会碎裂）
> 4. 先 A 后 B，顺序不能反。（顺序反了会建立依赖链，之后无法再改）
> 5. 工具实例用独立实例，不连已有实例；启动后设为前台可见。（可能控制错误窗口；脚本模式默认隐藏）
> 6. 参数写入必须回读校验，不一致标记失败并继续。（静默写入失败会污染整批结果）
> 7. 结果逐点落盘并 flush。（崩溃不丢已算点；不能等整批）
> 8. 仿真禁止跑在主线程。（GUI 会卡死，必须子线程）
> 9. 非登录 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. **禁止臆测**：不得编造任何未实际验证的结果、数值、接口行为或"应该能跑"的结论。若无法运行或测试某段代码/场景，必须明确说明"我无法执行此测试，以下是我的推理/建议"，并给出理由与降级方案。
2. **测试完备**：见 1.5 测试纪律。
3. **代码规范**：遵循语言标准规范（Python 遵循 PEP8）；关键逻辑必须有注释；复杂函数/类必须有 docstring（函数用途、参数、返回值、异常）。
4. **自查清单（交付前逐项确认，标注 ✅/❌）**：代码已通读无语法错误和明显逻辑漏洞 / 所有测试用例已列出且能描述预期输入输出 / 已考虑边界情况（空值、极值、并发、超时、资源耗尽）/ 已考虑错误处理路径（异常捕获、回滚、降级）/ 多模块时已确认接口契约和数据流向 / 无法实际运行测试时已明确告知用户。
5. **交付声明**：只有完成上述自查并确认无误后，才能说"已完成/已通过"；否则必须使用"草案待验证"或"需要您协助测试"，并说明缺口。
6. **迭代修正**：若用户反馈测试失败，必须：复现问题 → 定位根因 → 修复 → 重新走一遍自查清单 → 再回复。不得仅口头致歉后跳过复现与修复。

### 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 模板

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

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

| 项目 | 内容 |
|---|---|
| 文档版本 | 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 的规矩）模板

```markdown
# <项目名> 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`）

```markdown
# 会话记录 / Session Log

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

### 3.5 HANDOFF.md 接续指南模板

```markdown
# 接续指南 · <项目名>

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

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

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

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

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

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

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

【先做这几件事，做完再动任何东西】
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 验收基准表模板

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

对不上就别往下走。
```

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

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

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

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

```markdown
# 知识库 — <项目名>

> 本文件是项目的核心知识沉淀，供人和任何 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`）

```markdown
# 测试记录与结果总结

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

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

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

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

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

---

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

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

| # | 规则 | 为什么 |
|---|---|---|
| 1 | 任何数据/几何改动后核对「数量 + 总量」不变量 | 曾两次在坏数据上白跑，只报"操作成功"会漏掉损坏 |
| 2 | 关键输入的体积/数值必须保持不变 | 输入按件映射，改了映射就失效 |
| 3 | 检查必须用精确模式，不要用快速模式 | 快速模式漏掉大部分问题 |
| 4 | 不要用<某工具>的<某操作>，改用<替代方案> | 会留副本、后续修复会碎裂 |
| 5 | 先<A>后<B>，顺序不能反 | 顺序反了会建立依赖链，之后无法再改 |
| 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 全程参与。
- **沉淀贡献**：五支柱扩展（KNOWLEDGE_BASE + 留痕双件套）、里程碑管理、测试纪律（test_*.py 全量回归）、工程规范（禁臆测/自查清单/交付声明）、单一事实源、反模式自查表、环境变量陷阱文档化。
- **参考实现**：`AGENTS.md`、`docs/KNOWLEDGE_BASE.md`、`docs/TEST_RECORDS.md`、`docs/HANDOFF.md`、`scripts/check_machine_paths.py`、`scripts/test_*.py`。

### 如何使用本框架

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