doc-or-not

文档该不该写

文档只保留代码 / SQL / 配置无法表达的知识。

黄金判据

删掉这段，AI 读代码能不能推断出来？能 → 不该写；不能 → 该写。

每动笔一段就过一遍这句话。

清理 vs 保留

该清理（代码可推断）	该保留（代码读不出）
字段类型 / 约束 / 默认值 / 索引	业务规则、状态机决策点
接口参数 / 响应字段清单	枚举的业务语义、审批链
纯实现步骤、调用顺序	跨模块联动、设计取舍及原因
和 schema / 接口定义 / DTO 重复的内容	待确认项、证据强度、为什么这么定

"为什么这么写"这种代码里看不出的细节，放代码注释，不一定要进文档。

写新文档 / 改文档的 3 条边界

1. 字段表只写：字段名 + 业务语义 + 分组（必）；状态/枚举字段写完整可选值（必，因为代码里枚举散落）。类型/约束/默认值不重复（看 schema）。纯存储字段（电话、地址、备注等无业务规则的）一句话带过，别逐字段铺开。
2. 文档 vs 代码注释：业务规则 / 状态机 / 枚举语义 / 审批链 / 设计取舍 → 文档；代码里看不出的"为什么"细节 → 代码注释。判断标准同黄金判据。
3. 证据强度别升级：来源是用户口述 / 补丁、未实操确认的写操作（保存/修改/删除/审批/导入），文档要标"来源未实操确认"，禁止擅自写成"已确认闭环"。

检查文档漂移时的 6 类

逐篇过这 6 类：

类型	例
旧概念残留	已迁移的配置键、已删的字段、已废弃的写法
代码可推断的内容	字段类型、参数清单、调用顺序
过时的引用	旧包路径、删除的类名、改名的方法、重排的迁移编号
遗漏的规则	代码已有但文档没写的硬约束（新决策、新守门）
失效的链接	指向不存在的文档 / 已删文件
证据强度漂移	"未实操确认"被悄悄改成"已确认"

工作流

增量（编辑期顺手查）：改文档前先搜重复段落；读目标文档 + 相关代码，报告疑似漂移（位置、原因、对应代码处）；先报告不直接改，等用户确认范围；拿不准标 [需确认]，不猜不删。

批量审计（用户说"对照代码全审一遍"）：先列文档清单 + 拟修方向给用户过目；逐篇读完整文件、抽样验证关键概念是否还在代码里、修漂移不扩写无关内容；每篇单独 commit；拿不准的留 [需确认]。

雷区

• 不要扩写：用户说"修漂移"≠"重写文档"。
• 不要改 ADR 的决策内容：只更 Status，被取代就新建一篇替代。
• 不要把项目特定细节写进通用规范，也别把通用常识写进项目文档。