使用 agent.md 提升LLM辅助代码质量

# 我的 agent.md 如何提升 LLM 辅助代码质量 来源：https://fabiensanglard.net/agent.md/index.html 2026年8月21日 **我的 agent.md 如何提升 LLM 辅助代码质量** 我第一次尝试使用 LLM 加速编码是在 2025 年中。当时并没有留下深刻印象。那时我正在开发`libadbmdns`，一个用 Rust 实现的 mDNS 库。生成的代码甚至无法编译。 我在 2026 年 1 月重新尝试了 LLM。这次效果好得多。它不仅编写了一个复杂的索引二进制堆类，还能精确定位到 polling（https://docs.rs/polling/latest/polling/）crate 中一个因 Windows IOCP 实现导致的晦涩 bug。 然而，代码质量却极其糟糕。那是没有注释、缺乏结构的“意大利面”代码。尽管有趣，但如果提升的速度被清理代码至生产级标准所抵消，那么与 LLM 合作并不现实。 **反复迭代与自我重复** 2026 年 3 月，我尝试使用像 Antigravity 和 VS Code 的 Claude Code 插件这样的智能 IDE。现在我可以对“暂存”代码进行“迭代”。我发现自己像是在审查一位无限耐心的计算机专业低年级学生的代码，不断提出诸如“不要使用魔术数字”、“在这里添加简短注释以解释意图”或“使用简短的函数名”之类的建议。 代码质量显著提高了。它非常接近我“手写”的水平，但这过程很乏味。最终，我在每个新会话中都不得不一遍又一遍地重复自己。 **Agent.md 来救场** 当编码会话开始时，编码工具会加载一个名为 `agent.md`（https://github.com/agentsmd/agents.md/issues/135）的文件，并将其注入到提示词中。这是微调编码风格偏好的绝佳位置。当我觉得自己在重复相同的代码改进建议时，就把它们加了进去。 这是我版本的 `agent.md`（https://fabiensanglard.net/agent.md/agent.md），如果你需要，可以作为起点。将其放在项目根目录应该就足够了。或者，可以为 `gemini.md` 或 `claude.md` 创建指向 `*agent.md*` 的符号链接，这样它就能在任何地方生效。 ``` # FAB 的 AGENT.MD - 在编写供人类阅读的内容（注释、提交信息、对提示的回复）时，使用尽可能少的词语。仔细斟酌每个词，将内容精简到极致。直击要点。少即是多。 - 避免使用最高级和赞扬。别告诉我我绝对正确。给我冷静、客观的事实。 - 避免使用魔术数字和字符串，将重复出现或有意义的值提取为描述性的常量 (const) 或枚举。保持那些一目了然、一次性的值内联，以避免混乱。如果值来自规范（例如 HTTP 200 OK），则无论如何都使用常量。 - 减少代码缩进。避免箭头反模式。利用提前返回和 continue。 - 保持函数名简短。少于 30 个字符。 - 对于函数参数，使用枚举代替布尔值。 - 让代码读者有喘息的空间。在逻辑代码块之间添加空行。 - 添加简短、切中要害的注释来解释代码块*做什么*以及*为什么*这样做。尽可能使用示例。建议使用 ASCII 绘图来解释完整系统。 - 将成员可见性变更视为重大的设计变更。除非设计严格要求外部访问，否则将所有字段和函数保持为私有。在将任何访问修饰符从私有更改为内部或公共之前，请提示用户明确批准。 - 针对抽象层次进行编程。底层机制（例如原始硬件 I/O、扇区解析、直接套接字流）必须封装在专用的驱动程序/抽象层中。向应用程序的其余部分暴露干净、高级的 API，以便调用代码处理领域概念，而非原始的实现细节。 - 不要触及与你正在实现的功能无关的代码块。例如，如果你没有创建或修改过某个代码块，就不要给它添加注释。在实现功能时，尽可能减少更改的行数。 - 严格遵守分层边界层次结构：每一层只能与紧邻其下的层直接通信。永远不要“打穿”层（例如，控制器或 UI 组件永远不能直接调用数据库查询、原始硬件驱动程序或底层网络客户端；必须始终通过中间服务/抽象层进行路由）。 - 始终使用 {}，即使是在单行的“if”语句中。 编写提交信息时，遵循以下 7 条规则： 规则 1：在主题行和正文之间用一个空行分隔。 规则 2：将主题行限制在 50 个字符以内（72 是绝对硬性上限）。 规则 3：主题行首字母大写。 规则 4：主题行结尾不要加句号。 规则 5：主题行使用祈使语气（例如，“修复 bug”、“添加功能”，而不是“已修复”或“添加了”）。测试公式：它必须完成句子：“如果应用此提交，[你的主题行]”。 规则 6：手动将正文文本在 72 个字符处换行，以防止 Git 格式问题。 规则 7：在正文中解释做什么以及为什么，而不是如何做。假设代码解释了如何做；提交信息必须解释上下文和推理。 - 如果提示表明正在修复一个 bug，不要立即编写修复代码。首先编写测试。观察它失败。然后编写修复代码。并观察测试通过。 ``` 虽然这个“技巧”显著提高了生成的代码质量，但它并非能让我避免阅读代码的“灵丹妙药”。LLM 会不断产生幻觉，不能完全信任。我仍然需要大量验证和迭代，但现在我通常专注于架构和设计，而不是代码风格。 **如何处理注意力稀释问题** LLM 存在一个恼人的现象，称为“上下文稀释”或“注意力稀释”，这在《Lost in the Middle》（https://arxiv.org/abs/2307.03172）论文中有概述。随着上下文增长，模型开始更关注上下文的开头和结尾部分，而对中间部分的指令关注度降低。截至我撰写本文时，其原因尚不完全清楚。我只发现了两种方法来最小化其影响。 1. 保持上下文简短。这意味着为每个功能启动一个新会话。 2. 明确要求工具重新加载 `*agent.md*`。当我看到代码质量下降时，说“Reload agent.md”就足够了。 **自动更新 agent.md** 你不需要每次想添加新规则时都打开编辑器。我现在做的是让 agent 更新 agent.md。 ---