和 AI 一起写代码久了，我发现最浪费时间的不是写，而是每次都要重新解释背景：这张表是什么、这个字段的单位是什么、上次那个数为什么对不上。后来我固定维护一份"项目约定文档"，每次开工前先让 AI 读一遍，协作效率明显提升。
要点速览
- AI 不缺编程能力，缺的是你脑子里的业务上下文。
- 约定文档写"事实"：术语、数据层级、常量、口径、已知差异。
- 每次开工先读，每次收工回写，让文档跟着项目长。
- 一份好文档，能把"解释背景"的时间压到接近零。
问题：每次会话都从零开始
工业现场的数据有大量"只有内行才知道"的规矩：某个字段是小时均值还是瞬时值、某类设备在统计时要剔除、两个系统的编号规则不一样……这些 AI 不可能猜到。不说清楚，它就会写出语法完美、业务错误的代码。
约定文档里写什么
- 术语表：业务名词和代码名的对应关系，避免同一个东西三种叫法。
- 数据层级：库 → 表 → 关键字段，以及它们之间怎么关联。
- 常量与单位：阈值、换算系数、时间粒度，写明出处。
- 统计口径：哪些要剔除、怎么取平均、边界日期怎么算。
- 已知差异：和人工结果对不上的地方，以及当前的判断。
- 禁止事项：比如"只读，不许写库"、"不许改动某个模板的格式"。
一个最小骨架大概是这样：
# 项目约定（每次开工前必读）
## 术语
- 指标A = 字段 xxx_avg（日均值，单位 V）
## 数据层级
- 库 → 表 → 字段；主键与关联方式……
## 口径
- 周统计：周一 00:00 至周日 23:59
- 剔除：状态为"停运"的设备
## 已知差异
- 某项计数与人工报表差一倍，疑为口径不同，待确认
## 禁止
- 只读访问数据库，任何写操作需人工确认怎么维护：读一次，写一次
- 开工：把约定文档作为第一条上下文交给 AI。
- 干活：遇到新规矩，当场讨论清楚。
- 验证：结果和人工数据比对，差异记下来。
- 收工：让 AI 把本次新确认的事实整理成几行，追加进文档。
文档只写确认过的事实，不写猜测。猜测放进"已知差异"，确认后再转正。
效果
最直接的变化是：新开一个会话，第一段回答就能直奔主题，不再反复确认"这个字段是什么意思"。更长远的好处是，这份文档本身就成了项目最有价值的资料——对新同事同样适用。