在实际工作流中验证了四个月并可跨 project 复用的 AGENTS.md

来源: 知乎
收录时间: 2026-04-09
标签: #Agent #代码规范 #项目管理

文档写作原则：Self-Contained（自解释）

所有文档（PROGRESS.md、STATES.md、EXPERIMENTS.md、TODO.md）必须做到只读文档就能完全理解，不依赖对话上下文或任何脑内默认知识。

每个方法首次出现时必须解释它是什么、怎么做的。不能只写"方法 A 效果好"，必须写"方法 A（用因果卷积在 MLP 打分前丰富 token 特征，让 gate 感知邻居信息）效果好"
不要假设读者知道任何缩写。首次使用缩写时必须给出全称和一句话解释。例如不要写"STE"，要写"STE（Straight-Through Estimator，前向用 hard 0/1 掩码，反向用 sigmoid 梯度近似）"
实验结论必须包含足够上下文。不要写"差距缩小到 0.001"，要写"TopK 自适应选择与 Fixed 周期掩码的质量差距从 0.005 缩小到 0.001（提高 gate 学习率从 0.001 到 0.1）"
数字必须有参照物。不要写"val_bpb=0.8605"，要写"val_bpb=0.8605（对比：无加速 baseline=0.840，Fixed 周期掩码=0.8605）"
因果链要完整。不要只记录结论，要记录为什么。"TopK 不如 Fixed"不够，要写"TopK 不如 Fixed，因为 TopK 的 think token 48% 紧挨着聚集（间距=1），导致部分 skip token 的信息供给不足（信息瓶颈），而 Fixed 均匀间隔保证每个 think token 只需支撑 2 个 skip token"
docs/STATES.md 顶部维护一个术语表，所有关键术语集中定义。其他文档开头引用该术语表即可

"TopKConvGate 实验（在 MLP 打分前用 768 通道因果深度卷积让每个 token 看到前 7 个邻居的特征，帮助 gate 感知局部上下文以减少 think token 聚集）：E4T4D4 架构下 5k 步 val_bpb=0.8610，仍略差于 Fixed 周期掩码(0.8605)，差距 0.0005"

docs/PROGRESS.md: 只记录"已经完成"的工作/实验/结论（附关键脚本/日志/ckpt 路径），不要写待办计划。

docs/TODO.md: 只记录"未完成/进行中/下一步"的待办与计划（尽量可一键复现）；完成后从 docs/TODO.md 移除对应项，并把结果写入 docs/PROGRESS.md（避免重复记录）。

docs/STATES.md: 只维护已经完成的成果，录入真正长期有用的东西而非临时的噪音。

docs/EXPERIMENTS.md: 实验相关内容的特殊STATE，专注于处理实验和数据。

当完成一个完整功能或要进行破坏性改动时：

git add .
git commit -m "描述"