收录两篇Agent相关文章到待看笔记

InBox/AGENTS.md_待看.md

@@ -0,0 +1,81 @@
+# 在实际工作流中验证了四个月并可跨 project 复用的 AGENTS.md
+
+**来源**: [知乎](https://zhuanlan.zhihu.com/p/2009629370684306095)  
+**收录时间**: 2026-04-09  
+**标签**: #Agent #代码规范 #项目管理
+
+---
+
+## 文档写作原则：Self-Contained（自解释）
+
+所有文档（PROGRESS.md、STATES.md、EXPERIMENTS.md、TODO.md）必须做到**只读文档就能完全理解**，不依赖对话上下文或任何脑内默认知识。
+
+### 核心要求
+
+1. **每个方法首次出现时必须解释它是什么、怎么做的**。不能只写"方法 A 效果好"，必须写"方法 A（用因果卷积在 MLP 打分前丰富 token 特征，让 gate 感知邻居信息）效果好"
+
+2. **不要假设读者知道任何缩写**。首次使用缩写时必须给出全称和一句话解释。例如不要写"STE"，要写"STE（Straight-Through Estimator，前向用 hard 0/1 掩码，反向用 sigmoid 梯度近似）"
+
+3. **实验结论必须包含足够上下文**。不要写"差距缩小到 0.001"，要写"TopK 自适应选择与 Fixed 周期掩码的质量差距从 0.005 缩小到 0.001（提高 gate 学习率从 0.001 到 0.1）"
+
+4. **数字必须有参照物**。不要写"val_bpb=0.8605"，要写"val_bpb=0.8605（对比：无加速 baseline=0.840，Fixed 周期掩码=0.8605）"
+
+5. **因果链要完整**。不要只记录结论，要记录**为什么**。"TopK 不如 Fixed"不够，要写"TopK 不如 Fixed，因为 TopK 的 think token 48% 紧挨着聚集（间距=1），导致部分 skip token 的信息供给不足（信息瓶颈），而 Fixed 均匀间隔保证每个 think token 只需支撑 2 个 skip token"
+
+6. **docs/STATES.md 顶部维护一个术语表**，所有关键术语集中定义。其他文档开头引用该术语表即可
+
+### 反面例子（禁止）
+- "V11 实验效果不错" → 什么是 V11？做了什么？效果不错是多少？
+- "提高了 gate LR" → 从多少到多少？为什么要提高？效果改善了多少？
+- "信息瓶颈是核心问题" → 什么信息？什么瓶颈？为什么是核心？
+
+### 正面例子（要求）
+- "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，专注于处理实验和数据。
+
+### 关键原则
+
+- 能用小数据集/短实验快速 debug 就不要用大数据集/长实验；优先最快迭代
+- 每次准备做实验前必须先高层质疑与方向审视确认当前未知/最小实验/失败后下一步
+- 两个文档都必须按时间升序记录（越早在前、越晚在后），新增内容只能追加到文件末尾
+- 训练评测时只要是正式实验，一定要在正规文件里弄好脚本然后一键几乎无传参地跑
+- 跑训练或评测必须在 tmux 里启动，避免中途断开导致任务退出
+- 时刻注意删掉没用的 checkpoint 等大文件，维护空间不爆炸
+- 有多个相同功能文件的时候，请把错误的冗余的全部都扔进 archive，只保留一个
+
+### Git 提交规范
+
+当完成一个完整功能或要进行破坏性改动时：
+```bash
+git add .
+git commit -m "描述"
+```
+
+- 发现任何文档或代码有错误时，更新不要保留任何错误痕迹
+- 写了一个新版本的正确文件，请删掉错误版本的文件
+- 兼容性不要搞得那么好，不要 fallback
+- 同样的功能禁止有错误实现，并且只能有一个位置正确实现，禁止冗余
+
+---
+
+## 其他要点
+
+- 跟我沟通请使用中文。任何的临时测试都请在 tmp 文件夹
+- 我们现在是在一个Docker环境里边，使用公共服务器的电脑。千万不要跟别的程序抢占GPU，这是绝对禁令
+- 想用 GPU 的时候用 nvidia-smi 查看空闲 GPU 然后精确加载空闲的
+- 你只要遇到问题就处理，遇到问题就处理，直到没有问题。不要问我顺序什么的
+- 有不清楚的先记下来跳过，所有探究实现路径全部卡住了再都通知我
+- 没用的东西放 archive/