根据仓库事实生成 AGENTS.md
AI 总结
一篇报告介绍了一个零依赖 Python 脚本,通过扫描仓库生成 AGENTS.md,识别语言、入口候选文件、测试文件、包管理文件、顶层目录、文件总数和可能的测试命令。代码约定和禁止事项则保留在由人工维护的固定模板中。脚本还会校验五个必需章节是否齐全、是否为空,以及文件是否超过 6,000 个字符;报告展示了如何将校验接入 CI。报告还复盘了两个错误:用 match 而非 search 匹配测试文件名,以及扫描提前返回时遗漏文件计数。建议的工作流是在仓库结构或测试命令变化后重新生成并检查差异;pre-commit 钩子可以只做校验而不重新生成。
深度见解
报告称,手写的 AGENTS.md 在测试命令变更后未能同步,导致 Codex 运行错误命令并重试。根据仓库当前结构生成事实,可以使这些说明与代码库保持一致;校验和人工复核则用于保留必需章节与约定。
仓库里那份 AGENTS.md 是去年手写的,写着"测试用 pytest"。那会儿确实用 pytest。
后来前后端共用一套测试脚本,跑法换成了 npm test。AGENTS.md 里那行没人想起去改。于是 Codex 每次要跑测试都先 npm test,报错,再翻 package.json,发现路径不对,重来。一来一回两分钟,一天十几次,谁也没觉得这是个问题,只觉得"这 AI 有点笨"。
问题不在模型。手写的约定文件一定会过期,因为它是从仓库里复制出来的第二份事实。凡是第二份事实,都会漂。
我的做法是这部分别手写,让脚本去仓库里扫。
只写能扫出来的东西
AGENTS.md 里真正有用的就三类:这个仓库是什么语言写的、入口在哪、测试怎么跑。这三样全在文件系统里,不用人记。