我的 agent.md：提升 LLM 辅助的代码质量
开发者们正在讨论，在生成代码时，专门的“AGENTS.md”文件相比依赖 linters、现有的 CONTRIBUTING/CODING_STANDARDS 文档以及更简单的高层指南，到底有多大价值。很多人抱怨模型会过度生成低价值注释和冗长的风格修正，认为机械检查和简洁、正向措辞的规则，比那些可能稀释上下文、或随着模型进步而过时的长篇代理指令文件更有效。另一些人仍然认为，最小化的 agent 提示在编码工作流规范（如 TDD 或限制无关改动）和语气/风格约束上有价值，但他们更看重按项目演进的配置，而不是一刀切的规则集。
AGENTS.md 的角色与设计
- 许多人认为 AGENTS.md 有用，但也非常个人化：不同的人、项目和模型有不同的失效模式，因此共享模板只能作为起点。
- 有人认为文章中的很多内容都是通用 CS 或现代模型已经“知道”的东西，所以额外规则可能作用不大，甚至有害。
- 另一些人觉得 AGENTS.md 是一种“丑陋的创可贴”，会随着新模型而过时，经常被忽略，而且当规则被误解时还会毒化推理。
- 替代方案：把项目规则放在 CONTRIBUTING/CODING_STANDARDS 中，并让 harness 或 skills 在需要时去发现它们。
Linters 与 Agent 指令
- 一个强烈的主题是：用 linters、pre-commit hooks 和 CI 强制执行机械/风格规则，而不是依赖非确定性的 agents。
- 例子：单行
if也要加花括号、不要嵌套三元表达式、不要注释、格式化、magic numbers。 - 有些人用 LLM 作为 CI/reviewer 来检测被禁止的模式/注释，让“机器人对机器人”。
注释与文档
- 普遍对过度注释感到沮丧：agents 会生成冗长的“这段代码做什么”注释，往往比代码还长。
- 许多人尝试彻底禁止注释，或只允许“why/context”注释；“what” 应该从代码本身就显而易见。
- 担忧包括：注释会过时、误导人类和未来的 agents，并污染上下文。
- 少数人为注释辩护，认为它们适合用于大型/丑陋函数的摘要，或存在隐藏复杂性的地方；有些人还会通过编辑器折叠隐藏注释。
指令遵循与提示策略
- 用户报告像“never add comments”这样的规则效果参差不齐；更新、更大的模型遵守得更好，其他模型则会忽略。
- 讨论了“do”与“don’t”措辞：正向指令可能更容易保留，但某些约束（例如“永远不要注释”）很难不用 “don’t” 来表达。
- 冗长、密集的 AGENTS.md 会遭遇“lost in the middle”的上下文稀释；几个人更喜欢简短的核心规则，或者让 agent 按任务选择模块化的规则文件。
风格、架构与工作流偏好
- 在风格要求上分歧很大：短函数名还是长函数名、总是使用花括号还是极简主义、枚举还是布尔值、提取小函数还是保留较大的函数。
- 有些人强调在 AGENTS.md 中写架构和“why”上下文，而不是逐行规则。
- 提到的工作流包括：带自我审查的多轮生成、收敛式规则（success/progression/honest stop）、以 TDD 为中心的提示，以及对 agents 触碰无关代码的严格限制。