别再让 AI 自由发挥：我用 HInsight 迁移总结出的 5 张表
一、为什么今天直接讲这 5 张表？
前几天我讲了 HInsight 的背景：它基于 Grafana 开源能力体系迁移和改造，其中一个核心工作，是借助以 Codex 为代表的 AI 辅助编码工具，将复杂前端体系从 React 迁移到 Vue，并适配 Go 后端、packages 分包体系和工业现场需求。
但如果只讲“我做成了”，读者很难真正理解这件事的价值。真正有复用价值的，不是某个工具有多强，而是我后来逐渐沉淀出的工程方法。
今天直接放干货：我用 AI 辅助迁移复杂系统时，最终离不开这 5 张表。
- 任务卡：把模糊需求变成边界清晰的任务。
- 差异表：让 AI 先理解“原实现”和“目标实现”的差距。
- 验收清单：定义什么叫真正完成。
- 交接书：解决任务中断、换会话、换工具后的接续问题。
- 本地记忆：把关键上下文沉淀为可恢复、可共享的项目资产。
这几张表看起来像流程和文档，但它们不是形式主义。它们是我在 AI 频繁跑偏、失忆、返工之后，被迫总结出来的工程护栏。
二、为什么要用闭环框住 AI？
以 Codex、Claude Code、Cursor、Copilot 为代表的 AI 辅助编码工具，天然擅长“在给定上下文中生成下一步”。它们可以很快读代码、改代码、补类型、修报错，但它们并不天然知道你的长期目标、项目边界、历史约定、生产风险和验收标准。
尤其是大型迁移工程里，真正的难点往往不是“写出一段能编译的代码”，而是“不能破坏原有系统的行为”。Dashboard 要能打开，DataSource 要能查，Panel 要能渲染，Explore 要能排查问题，权限、日志、插件、Go 后端链路和 packages 分包体系都不能被随意改坏。
所以我后来不再把 AI 当成自动驾驶，而是把它放进一个闭环：
目标定义 → 验收标准 → 计划 → 差异表 → 执行 → 自检与测试 → 人工验收 → 交接书 → 本地记忆 → 复盘沉淀
这个闭环的意义是：先限定问题，再限定完成标准；先让 AI 说明理解，再让它执行；执行后先测试，再人工验收；最后把结果写入交接书和本地记忆，作为下一次任务的起点。
【图 1：AI 工程闭环图占位】
建议放流程图：目标定义 → 验收标准 → 计划 → 差异表 → 执行 → 自检与测试 → 人工验收 → 交接书 → 本地记忆 → 复盘沉淀
三、第一张表：任务卡
最开始我会直接对 Codex 说：“帮我迁移这个模块。”后来发现这是最容易出问题的方式。因为 AI 会主动补全它认为合理的上下文，也会选择它觉得最快的路径。如果任务边界不清，它可能会改动不该改的文件，简化不该简化的逻辑，甚至用短平快的方式掩盖真正的问题。
任务卡的意义，是在 AI 动手之前，把任务目标、边界、禁止事项、输入材料、输出要求和验收标准都写清楚。它不是为了好看，而是为了把 AI 从“自由发挥”变成“按任务盒执行”。
任务卡模板
# 任务卡：<任务名称>
## 任务背景
【说明为什么要做这个任务】
## 任务目标
1. 【目标 1】
2. 【目标 2】
3. 【目标 3】
## 任务边界
允许修改：
- 【路径 1】
- 【路径 2】
禁止修改：
- 【禁止修改的路径 / 配置 / API / 协议】
## 输入材料
- 【原实现文件】
- 【目标文件】
- 【类型定义】
- 【测试文件】
## 输出要求
- 修改文件清单
- 差异表
- 测试结果
- 交接书
## 验收标准
- [ ] 构建通过
- [ ] 类型检查通过
- [ ] 核心路径可用
- [ ] 未扩大修改范围
## 风险提示
- 【风险点 1】
- 【风险点 2】
任务卡示例
# 将示例面板配置组件迁移为 Vue/SFC
## 任务名称
将 `ExamplePanelConfig.tsx` 迁移为 `ExamplePanelConfig.vue`，保持配置项、交互、样式、i18n 和测试行为 1:1 对齐。
## 任务背景
当前示例面板配置仍由 React/TSX 实现。迁移目标是让 Vue Host 默认入口可以直接使用 Vue/SFC 版本，同时保留原 React 文件作为只读对照基线。该任务仅使用 mock/example 语义，不涉及真实生产接口、真实控制策略或客户数据。
## 任务目标
- 在目标 mirror 路径补齐 `ExamplePanelConfig.vue`。
- 对齐原 React 组件的 props、事件回调、默认值、禁用态和错误态。
- 对齐样式、主题 token、i18n key、aria/role 和测试选择器。
- 补齐必要的单测或 smoke 验证记录。
## 任务边界
### 允许修改
- `webrs/app/plugins/panel/example/ExamplePanelConfig.vue`
- `webrs/app/plugins/panel/example/ExamplePanelConfig.contract.ts`
- `webrs/app/plugins/panel/example/__tests__/ExamplePanelConfig.test.ts`
- `docs/examples/ai-engineering-loop/**`
### 只读参考
- `public/app/plugins/panel/example/ExamplePanelConfig.tsx`
- `packages/example-ui/src/components/**`
- 既有测试和 story 中的 selector、aria、文案和样式行为
### 明确不做什么
- 不修改 `public/app/**` 运行时代码。
- 不引入 React runtime 或在 Vue 中挂载 React。
- 不新增 `*.d.ts`、stub、假类型或占位组件。
- 不接入真实生产数据源，不写真实域名、IP、账号或 token。
## 输入材料
- 原实现路径：`public/app/plugins/panel/example/ExamplePanelConfig.tsx`
- 目标实现路径：`webrs/app/plugins/panel/example/ExamplePanelConfig.vue`
- 相关样式：原 React `getStyles` / theme token
- 相关测试：`ExamplePanelConfig.test.tsx`、面板 smoke spec
- 相关文档：迁移规则、UI parity 矩阵、验收清单
## 输出要求
- Vue/SFC 实现与 contract 文件。
- 差异表，说明每项 React/Vue 差距和处理方式。
- 验收清单，包含构建、类型、单测、smoke/e2e 和人工验证项。
- 交接书，记录完成内容、测试结果、风险和下一步建议。
- 本地记忆更新，记录关键决策和已知坑点。
## 验收标准
- [ ] `yarn x:guard:dsc:hard` 通过。
- [ ] `yarn x:app-vue:build` 通过。
- [ ] 示例组件单测通过。
- [ ] Dashboard / Panel 编辑态可以打开示例配置项。
- [ ] DataSource 和 Explore 相关入口不受影响。
- [ ] Vue 组件没有 React runtime、`<style scoped>`、硬编码颜色、未解释 `any` 或 `ts-ignore`。
- [ ] 修改范围未越过任务边界。
## 风险提示
- 原组件如果通过 React hook 读取主题或上下文，Vue 侧需要替换为对应 composable。
- 原测试 selector 可能被多个组件复用，改动前要确认不会影响下游 e2e。
- 组件默认值和保存回调顺序容易造成配置回写差异，需要在差异表中逐项确认。
## 给 AI 的执行要求
- 先读任务卡，再扫描原 React 文件、目标 Vue 路径、测试和样式依赖。
- 先输出计划和差异表，等待人工确认后再执行。
- 缺组件时迁移真实组件，不得写空壳或 mock。
- 每轮只修一个 root failure，优先处理 pageerror、console.error 和 5xx。
- 完成后运行验收命令，写交接书并更新本地记忆。
四、第二张表：差异表
差异表是我认为最关键的一张表。因为 AI 写计划时往往会说得很顺，但它是否真的理解了原系统，只有通过差异表才能看出来。
差异表解决的问题是：原实现是什么、目标实现是什么、差距在哪里、准备怎么处理、风险等级如何。大型迁移最怕的不是进度慢，而是一开始方向理解错了，后面越改越远。
差异表模板
| 项目 | 原实现 | 目标实现 | 当前差异 | 处理方式 | 风险等级 | 备注 |
|---|---|---|---|---|---|---|
| 组件入口 | 【原文件 / 原组件】 | 【目标 Vue/SFC】 | 【差异说明】 | 【处理策略】 | 高/中/低 | 【补充】 |
| props / 事件 | 【React props / 回调】 | 【Vue props / emits 或回调】 | 【差异说明】 | 【保持语义 / 适配】 | 高/中/低 | 【补充】 |
| 状态与副作用 | 【useState/useEffect 等】 | 【ref/computed/watch 等】 | 【生命周期差异】 | 【验证路径】 | 高/中/低 | 【补充】 |
| 样式与主题 | 【原样式方案】 | 【目标样式方案】 | 【主题变量差异】 | 【迁移方式】 | 高/中/低 | 【补充】 |
| 测试 | 【原测试】 | 【目标测试 / e2e】 | 【覆盖差异】 | 【补测方案】 | 高/中/低 | 【补充】 |
差异表示例：
示例面板配置组件 React → Vue
使用场景:
本示例用于在迁移 ExamplePanelConfig.tsx 前，把 React 基线、Vue 目标和当前差距逐项对齐。所有路径和业务对象均为脱敏 example/mock 语义。
| 项目 | 原实现 | 目标实现 | 当前差异 | 处理方式 | 风险等级 | 备注 |
|---|---|---|---|---|---|---|
| 组件入口 | public/app/plugins/panel/example/ExamplePanelConfig.tsx 由 React panel editor 引入 |
webrs/app/plugins/panel/example/ExamplePanelConfig.vue 由 Vue panel editor 引入 |
Vue 入口尚未接入 registry | 新增 Vue SFC 与 contract，并在 example plugin module 中指向 Vue 入口 | P0 | 不修改 React 基线 |
| props | React 接收 options、data、onOptionsChange、disabled |
Vue props 保持同名语义，emits 使用 update:options 或 options-change |
disabled 默认值和 data 空态未定义 |
contract 中声明默认值，空态按 React 渲染 | P1 | props 名称必须可追踪 |
| 事件回调 | onOptionsChange(nextOptions) 立即回写 |
Vue emit options-change，payload 为完整 options |
当前计划只 emit 局部字段，可能丢配置 | 统一 emit 完整 options，保持调用顺序 | P0 | 防止保存后配置丢失 |
| 状态管理 | React useState 管理展开项和本地输入 |
Vue ref / computed 管理展开项和本地输入 |
展开项默认值未对齐 | 从 options 计算初始值，watch 外部 options 更新 | P1 | 避免编辑器重开状态错误 |
| 生命周期 / 副作用 | useEffect 订阅 demo registry，并在卸载 cleanup |
Vue onMounted / onBeforeUnmount |
cleanup 缺失会重复订阅 | 迁移订阅与 cleanup，补单测覆盖 | P0 | pageerror 优先处理 |
| 样式和主题 | React getStyles(theme)，使用 theme token |
Vue useStyles2Vue / theme token |
旧草稿使用硬编码颜色 | 删除硬编码颜色，迁移 getStyles 逻辑 | P1 | 禁止 <style scoped> |
| i18n | 使用 t('example.panel-config.title') |
使用同 key | 部分新增文案没有 key | 原 key 复用；无原 key 的 demo 文案使用中文 | P1 | 禁止英文占位 |
| 权限 | canEdit 控制保存按钮和高级配置 |
Vue 使用相同权限输入或 store selector | 当前只做按钮 disabled，未隐藏高级动作 | 对齐 React 的显示、禁用和 tooltip 行为 | P0 | 防止权限绕过 |
| 测试 | React unit + panel smoke | Vue unit + panel smoke/e2e | Vue 单测缺少事件顺序断言 | 增加 props、emit、禁用态、i18n、样式类 smoke | P1 | e2e 或 smoke 至少覆盖打开配置 |
| 上下游引用 | Dashboard / Panel / DataSource / Explore 共享配置 schema | Vue 侧继续复用纯 TS schema | schema import 可能拉入 TSX | 只引用纯 TS；若链路拉入 React，拆出纯逻辑 | P0 | 不引入 React runtime |
五、第三张表：验收清单
AI 的“已完成”不等于工程上的完成。复杂系统里，完成至少意味着能构建、能运行、能交互、能验证、没有破坏边界。
验收清单的意义，是把“完成”变成可检查的条件。没有验收清单，AI 很容易把“代码写完”当成“任务完成”。
验收清单模板
# 验收清单：<任务名称>
## 1. 构建与类型
- [ ] build 通过
- [ ] typecheck 通过
- [ ] 无新增无解释 any
- [ ] 无新增无解释 ts-ignore
## 2. 功能行为
- [ ] 页面能正常打开
- [ ] 核心交互路径可用
- [ ] loading / error / empty 状态正常
- [ ] 事件回调语义保持一致
## 3. UI 与主题
- [ ] light / dark 主题表现正常
- [ ] 布局没有明显错位
- [ ] 浮层 / Tooltip / Modal 行为正常
## 4. 数据链路
- [ ] Dashboard 路径正常
- [ ] DataSource 查询正常
- [ ] Panel 渲染正常
- [ ] Explore 路径正常
## 5. 修改范围
- [ ] 未修改边界外文件
- [ ] 未改变后端 API / 协议
- [ ] 未破坏权限、日志、配置链路
## 6. 交接
- [ ] 写明测试结果
- [ ] 写明风险和未完成事项
- [ ] 更新必要本地记忆
验收清单示例
# 示例面板配置组件迁移
## 使用场景
本示例用于验收一个脱敏的 React/TSX 面板配置组件迁移到 Vue/SFC 的任务。示例命令和路径均使用 demo/example 语义。
## 构建与类型
- [ ] `yarn x:guard:dsc:hard` 通过。
- [ ] `yarn x:app-vue:build` 通过。
- [ ] `yarn x:test:app-vue:file webrs/app/plugins/panel/example/__tests__/ExamplePanelConfig.test.ts` 通过。
- [ ] 无新增未解释 `any`。
- [ ] 无新增未解释 `ts-ignore` / `ts-expect-error`。
## 功能行为
- [ ] Dashboard 中打开 demo 面板编辑态，配置区域正常渲染。
- [ ] Panel 配置项修改后能触发完整 options 回写。
- [ ] 保存、取消、刷新、返回 dashboard 行为与 React 基线一致。
- [ ] 空数据、加载中、错误态和禁用态均可见且文案正确。
## UI 与主题
- [ ] 样式来自 theme token 或 `useStyles2Vue`。
- [ ] 没有硬编码颜色。
- [ ] 没有 `<style scoped>`。
- [ ] 响应式布局在窄屏和桌面宽度下不重叠。
- [ ] `role`、`aria-label`、焦点顺序和键盘操作与基线一致。
- [ ] i18n key 与 React 基线一致；新增无 key 文案使用中文。
## 数据链路
- [ ] 配置 schema 只引用纯 TS 逻辑，不拉入 React/TSX。
- [ ] 保存 payload 不丢失未编辑字段。
- [ ] 没有 mock 冒充真实数据链路。
- [ ] 没有真实客户数据、账号、token、IP 或域名。
## 权限与安全
- [ ] `canEdit=false` 时保存按钮禁用或隐藏方式与基线一致。
- [ ] 高级配置入口的显示、禁用和 tooltip 与基线一致。
- [ ] DataSource 权限不足时错误态正确展示。
- [ ] 文档和测试中只出现 demo/example 数据。
## 自动化测试
- [ ] 单测覆盖 props 默认值、emit 顺序、禁用态、i18n 和空态。
- [ ] smoke 覆盖 Dashboard / Panel 编辑态入口。
- [ ] e2e 或 smoke 覆盖 DataSource 与 Explore 不受该迁移影响。
- [ ] e2e 若未运行，交接书说明原因和后续命令。
## 人工验收
- [ ] Dashboard：打开 demo dashboard，面板渲染不白屏。
- [ ] Panel：进入编辑态，切换配置项后保存成功。
- [ ] DataSource：进入 demo datasource 页面，列表和详情仍正常。
- [ ] Explore：打开 demo explore 页面，查询编辑器不受影响。
- [ ] 人工截图或录屏已保存到脱敏 evidence 目录。
## 修改范围检查
- [ ] 仅修改 `webrs/app/plugins/panel/example/**` 和相关 docs。
- [ ] 未修改边界外源码、构建配置、测试配置或 package 配置。
- [ ] 未修改 `public/app/**` 运行时代码。
- [ ] `git diff --name-only` 已检查。
## 文档与交接
- [ ] 差异表已更新。
- [ ] 交接书已更新。
- [ ] 本地记忆已更新。
- [ ] 未完成事项和风险已明确。
六、第四张表：交接书
交接书解决的是连续性问题。AI 会话会中断，上下文会压缩，任务会切换，worktree 可能并行，甚至工具也可能从 Codex 换成 Claude Code 或 Cursor。没有交接书，下一次继续时往往要重新解释一遍。
交接书不是项目总结，而是给“下一个继续工作的人或 AI”看的读档说明。它应该短、清楚、事实化。
交接书模板
# 交接书：<任务名称>
## 1. 本次目标
【本次任务要解决什么】
## 2. 已完成内容
- 【完成项 1】
- 【完成项 2】
## 3. 修改文件清单
| 文件 | 修改内容 | 风险等级 |
|---|---|---|
| 【路径】 | 【说明】 | 【高/中/低】 |
## 4. 测试结果
- build: 【通过 / 未运行 / 失败】
- typecheck: 【通过 / 未运行 / 失败】
- unit: 【通过 / 未运行 / 失败】
- e2e/smoke: 【通过 / 未运行 / 失败】
## 5. 当前风险
- 【风险 1】
- 【风险 2】
## 6. 未完成事项
- 【待办 1】
- 【待办 2】
## 7. 下一步建议
【下一步从哪里继续，先读哪些文件】
## 8. 给下一个 AI / 人的提示
【必须注意的上下文、边界、坑点】
交接书示例
# 示例面板配置组件迁移
## 使用场景
本示例展示一次脱敏迁移任务完成后的交接写法。文件路径均为 example/mock，不对应真实客户或生产链路。
## 本次任务目标
将示例面板配置组件从 React/TSX 迁移到 Vue/SFC，并完成构建、单测、smoke 和人工验收记录。
## 已完成内容
- 新增 `packages/example-ui/src/ExamplePanel.vue`，对齐配置项布局、禁用态和空态。
- 新增 `public/app/features/example/ExamplePage.vue`，用于 demo 页面验证。
- 新增 `docs/examples/ai-engineering-loop/02-diff-table.example.md`，记录迁移差异。
- 补齐 demo 单测，覆盖 props 默认值、emit 顺序和 i18n 文案。
## 修改文件清单
| 文件 | 类型 | 说明 |
| ---------------------------------------------------------------------- | ---- | -------------------- |
| `packages/example-ui/src/ExamplePanel.vue` | 新增 | Vue/SFC 示例面板组件 |
| `packages/example-ui/src/ExamplePanel.contract.ts` | 新增 | props/emits contract |
| `public/app/features/example/ExamplePage.vue` | 新增 | 脱敏 demo 页面入口 |
| `docs/examples/ai-engineering-loop/02-diff-table.example.md` | 修改 | 记录迁移差异 |
| `docs/examples/ai-engineering-loop/03-acceptance-checklist.example.md` | 修改 | 记录验收结果 |
## 测试结果
| 命令 | 结果 | 备注 |
| ------------------------------------------------------------------------------------------------- | ------ | -------------------------------------- |
| `yarn x:guard:dsc:hard` | PASS | 硬门禁通过 |
| `yarn x:app-vue:build` | PASS | Vue build 通过 |
| `yarn x:test:app-vue:file packages/example-ui/src/ExamplePanel.test.ts` | PASS | 单测通过 |
| `yarn playwright test e2e-playwright/example/example-panel-smoke.spec.ts --workers=1 --retries=0` | 未运行 | 本轮无本地前端 watch，交给下一轮 smoke |
## 当前风险
- e2e smoke 尚未运行，需要在前端 watch 和后端 demo 服务可用时补跑。
- 示例页面只覆盖 demo 数据，未覆盖大型 options payload。
- 仍需人工对比窄屏布局截图。
## 未完成事项
- 补跑 example panel smoke。
- 补一组宽屏和窄屏人工截图。
- 若后续接入真实模块，需要重新审查权限和数据链路，不得复用 demo 假数据。
## 下一步建议
1. 启动 demo 前端 watch 和本地后端。
2. 跑 `example-panel-smoke.spec.ts`，优先处理 pageerror、console.error 和 5xx。
3. 将 smoke 结果更新到验收清单和本地记忆。
## 给下一个 AI / 人类维护者的提示
- 先读：任务卡、差异表、验收清单。
- 只读基线：React `ExamplePanelConfig.tsx` 和原测试。
- 不要做：不要改 `public/app/**` 运行时代码，不要新增 `*.d.ts`，不要用 mock 冒充真实链路。
- 优先检查：事件回写是否 emit 完整 options，权限禁用态是否与基线一致。
七、第五张表：本地记忆
本地记忆是这套流程里最值得单独强调的部分。它不是普通文档，而是一种“读档机制”。它解决的是 AI 会话不稳定、上下文不连续、跨工具无法共享背景的问题。
我的实际体验是：即便到了 5.4 / 5.5 时代，长会话仍然可能因为上下文压缩失败而中断；奇怪的是，我在 5.3 时反而较少遇到这种断裂。但无论模型怎么演进，只要任务足够长，本地记忆都非常必要。
本地记忆解决的三个问题
- 会话中断后的读档：新起会话后，不需要从头重新加载所有背景，而是先读 current-status、project-rules、known-pitfalls 等文件恢复状态。
- 跨工具使用：Codex、Claude Code、Cursor、Copilot 都可以读取同一套项目记忆，不再把上下文锁死在某一次对话里。
- 多线程共享背景：在 5.4 / 5.5 时代，可以让多个并行任务或 worktree 共用一套稳定背景，减少重复培训。
本地记忆建议结构
.ai-memory/
current-status.md # 当前项目状态，日常优先读取
project-rules.md # 长期有效的项目规则
known-pitfalls.short.md # 已知坑点短表
validation-checklist.md # 通用验收要求
decisions/ # 关键决策记录
handoff/ # 任务交接记录
archive/ # 历史归档，默认不读
这套“记忆”机制类似于游戏的存档机制，内容比较多，需要另起一章总结。
八、AGENTS.md 应该写什么，不应该写什么？
很多 AI coding agent 会读取 AGENTS.md 这类项目指导文件。它适合放稳定、短小、全局有效的规则，但不适合放所有任务细节。
适合放入 AGENTS.md 的内容
- 项目的长期原则，例如：公开内容必须脱敏，禁止泄露客户、现场、账号、token、真实接口。
- 技术栈和通用约束，例如：前端迁移目标是 Vue，禁止新增 React 依赖。
- 构建、测试、lint、e2e 的常用命令。
- 日常开发默认读取哪些轻量文档，例如 docs/ai-agent/LOOP.md、TOKEN-RULES.md。
- 通用输出要求，例如：不要复述模板全文，完成后输出修改文件、测试结果和风险。
不适合放入 AGENTS.md 的内容
- 某个具体任务的详细任务卡、差异表、交接书。
- 很长的完整模板全文，尤其是每次任务都不一定需要的内容。
- 历史任务长记录和 archive。
- 生产数据、真实接口、客户信息、控制策略、账号 token。
- 频繁变化的状态，例如今天某个模块迁移到一半。
- 过长的复盘文章和对外传播稿。
简单说，AGENTS.md 应该像“项目级交通规则”，而不是“每次任务的完整档案库”。我们也需要另起一章来分享AGENTS.md的具体使用。
九、怎么在日常开发里使用这套模板，才不会费 token？
相信大家在看完以上的模板后，会觉得“不是吧，这得费多少token",担心费 token 是对的。如果每次都把任务卡、差异表、验收清单、交接书、本地记忆模板全文贴给 AI，token 一定会暴涨。
只给路径也不自动省 token。如果 AI 读取了完整文件，内容仍然会进入上下文。真正省 token 的关键是：短模板优先、按需读取、不复述全文、历史归档不默认加载。
推荐文档分层
docs/ai-agent/ # 日常低 token 运行版
LOOP.md
TOKEN-RULES.md
TASK-CARD.short.md
DIFF-TABLE.short.md
ACCEPTANCE.short.md
HANDOFF.short.md
DAILY-PROMPT.template.md
docs/examples/ai-engineering-loop/ # 完整模板与示例
01-task-card.template.md
02-diff-table.template.md
03-acceptance-checklist.template.md
04-handoff-report.template.md
05-local-memory.template.md
.ai-memory/ # 项目状态与记忆
current-status.md
project-rules.md
known-pitfalls.short.md
handoff/
archive/
日常低 token Prompt 模板
请执行 docs/tasks/<TASK_FILE>.md。
默认只读取：
- docs/tasks/<TASK_FILE>.md
- docs/ai-agent/LOOP.md
- docs/ai-agent/TOKEN-RULES.md
- .ai-memory/current-status.md
- .ai-memory/project-rules.md
- .ai-memory/known-pitfalls.short.md
不要读取完整模板全集。
不要复述模板全文。
如果需要额外上下文，请先列出：
- 需要读取的文件路径
- 读取原因
等待我确认后再读取。
先输出：
- 不超过 20 行的计划
- 风险点
- 需要确认的问题
等我确认后再修改代码。
完成后输出：
- 修改文件清单
- 测试命令和结果
- 未完成事项
- 交接摘要
- 是否更新本地记忆
这个 prompt 的核心不是“不给 AI 看模板”，而是“只让它看当前任务需要的最小上下文”。
十、对“费 token”顾虑的解释
模板化并不必然省 token。模板如果使用不当，反而会增加 token。
| 做法 | 结果 |
|---|---|
| 每次把 5 张表全文贴进 prompt | 必然费 token，且容易让 AI 复述模板。 |
| 每次让 AI 读取 docs/examples 全部文件 | 仍然费 token，只是从粘贴变成读取文件。 |
| 只读短版 LOOP、当前任务卡、当前状态 | 相对省 token，适合日常开发。 |
| 需要差异表时才读差异表模板 | 按需消耗，避免无关上下文。 |
| 历史交接放 archive，不默认读取 | 避免长历史污染当前上下文。 |
| 输出时禁止复述模板全文 | 减少回复侧 token 浪费。 |
所以我建议：完整模板用于沉淀方法，轻量模板用于日常执行，本地记忆用于恢复上下文，archive 用于保存历史但不默认加载。
十一、结论
HInsight 迁移让我最大的体会是：AI coding agent 很强，但它不应该被当成自动驾驶。
你不给目标，它会自己理解目标；你不给边界，它会自己扩大边界；你不给验收，它会自称完成；你不给交接，它下一轮可能失忆；你不给本地记忆，它换会话就要重新培训。
复杂工程里，真正有效的不是“神奇提示词”，而是任务卡、差异表、验收清单、交接书、本地记忆共同组成的工程闭环。
几个常见疑虑
我知道，大家看到这些模板之后，可能会有几个疑虑。
第一个疑虑是：这样做会不会很费 token？
这个问题前面已经解释过。真正费 token 的，不是模板存在，而是每次把模板全文复制进提示词、每次让 AI 重复读取所有文档、每次让它在回复里复述模板。正确做法是：完整模板放在仓库里，日常任务只读取轻量版；只读当前任务需要的最小上下文；需要详细模板时再按需读取；输出时只写本次任务内容，不复述模板全文。这样反而会减少反复解释背景、反复纠偏、反复重开任务造成的 token 浪费。
第二个疑虑是：有必要弄得这么复杂吗？是不是流程太重了？
这个问题本质上又回到了软件工程里一个老问题：流程和效率的矛盾。
如果只是写一个小脚本、修一个小样式、改一个简单页面，当然没必要上这么多流程。直接让 AI 改，人工看一眼，可能就够了。
但 HInsight 这种项目不是这样。它涉及大型系统迁移、前后端链路、packages 分包、UI 组件体系、数据源、面板、权限、日志、构建、测试和生产使用。一旦方向错了，AI 并不会自动停下来，它往往会沿着错误方向继续努力，越改越多，越走越远。最后你省掉的“流程时间”，会在返工、排错、回滚和重新培训 AI 的过程中成倍还回去。
所以这些模板不是为了增加仪式感，而是为了在复杂工程里降低失控成本。流程的目的不是变慢，而是让每一步都能积累、能验收、能交接、能回滚。对小任务可以轻量使用；对高风险任务必须严格执行。真正的效率，不是少写几行文档，而是少走几天弯路。
第三个疑虑是：AI 这么强，为什么还要这么多约束？
这恰恰是 AI 辅助开发时代最需要重新认识的地方。
AI 的代码能力很强，甚至在局部任务上，它的速度和覆盖面都超过普通开发者。但它强在“执行”和“生成”，不等于它天然具备项目负责人的判断力。它不知道哪些历史包袱不能动，不知道哪些接口背后有生产依赖，不知道哪些 seemingly clean 的重构会破坏上下游，也不一定能稳定记住几天前的约定。
所以，AI 更像一个代码能力极强、执行速度极快、但需要明确目标、边界和验收标准的协作者。你不能只给它一句“帮我迁一下”，然后期待它自动理解整个系统的历史、风险和取舍。必须有一种方式把它驾驭好：用任务卡定义目标，用差异表防止跑偏，用验收清单确认结果，用交接书承接上下文，用本地记忆沉淀经验。
换句话说，AI 时代不是不需要软件工程了，而是更需要软件工程。因为 AI 把执行速度放大了，如果没有工程约束，错误也会被同样放大。真正重要的能力，不只是会使用 AI，而是能把 AI 放进一套可控、可验证、可持续推进的工程体系里。
这里是「码客问剑」。
不只讲 AI 工具，更讲真实复杂系统里 AI 怎么落地。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
10
0- 0
已为社区贡献3条内容
所有评论(0)