- 提交信息不带任何 AI 署名，不写
Co-Authored-By，不写Generated with。 - 提交信息用英文，散文体，少用分号。把「为什么」写清楚，「改了什么」git 自己看得见。
- 一个提交一件事。同一个文件承载两批改动时，用
git show HEAD:<path>取出旧内容、只叠加其中一批、提交、再放回完整版本——不要图省事整文件暂存。 - 每个提交自身必须能构建、能通过测试，拆分出来的中间状态也一样。
- 在默认分支上时先开分支。
- 用 Doxygen 命令：
\c标识符、\a参数、\note、\warning、<tt>多词片段。不要用反引号或引号。 - 不写考古式注释。解释「为什么现在必须这么写」的留下；叙述「以前是什么样、后来修了」的删掉——那是 git 的职责。
- 不擅自重命名既有标签或措辞。
- Markdown 段落不要硬折行。一段就是一行，让编辑器去换行——这里不是邮件列表。代码块和表格不受此限。
- Markdown 文件结尾不留多余换行。
- 看到测试通过之前，先确认 build 的退出码是 0。构建失败时 ctest 跑的是上一轮的旧二进制，会给出虚假的绿色。
- 批量改动后核对「改了几处」，而不是「能不能编译」。语法合法不等于语义正确：
grep -o <pattern> | wc -l数的是实际次数，grep -c数的是行数。 - 新增测试后确认断言真的执行了，空 suite 也会「通过」。用
--report_level=short看断言数。 - 分清断言的是当前行为还是设计意图。测试可能只是把缺陷固化了下来。
sed -i会把 CRLF 拍平成 LF，而仓库里行尾是混的。动手前grep -qU $'\r'判断，CRLF 文件改用编辑工具。sed的替换表达式必须带行号地址，否则是全局替换，且后续表达式会匹配前面已改过的文本、层层嵌套。- 改完跑
clang-format（仓库有.clang-format，ColumnLimit 100），只对自己动过的文件跑。 - 不要
sed -i扫全目录。
- 断言之前先验证。「公开 API 长这样」不等于「它真的能这么用」。
- 用户的质疑基本都是对的，先重新验证，不要辩护。
- 发现自己错了就直接更正，并把结论写回问题清单的对应条目，注明原判断错在哪。
- 不确定就说不确定，不要用推测填补。
| 内容 | 位置 |
|---|---|
| 值得长期保留的经验、设计记录 | docs/claude/（codex 写 docs/codex/） |
| 问题清单、交接、临时分析 | .cache/claude/（已 gitignore） |
| 面向用户的说明 | README.md、docs/ |
| 项目状态与 TODO | docs/Status.md |
docs/claude/ISSUES.md 是问题总账，分 A/B/C/D/E/F 组，另有 🔒 保留项。🔒 的条目不要顺手改，需先确认作者意图。