通过 agent.md 提升 LLM 辅助编程质量：Fabien Sanglard 的实战经验分享

核心要点

• LLM 编程的演进历程：作者经历了从 2025 年代码无法编译，到 2026 年能够处理复杂逻辑但质量低劣的阶段。
• 核心痛点：尽管 AI 能够编写复杂算法，但生成的代码往往缺乏结构、注释，且存在大量“魔法数字”，导致开发者需花费大量时间进行后期清理。
• agent.md 的引入：通过在项目根目录放置 agent.md 文件，开发者可以将特定的编程风格偏好（如命名规范、注释要求）自动注入 AI 提示词。
• 效率提升：该方法消除了在每个新会话中重复向 AI 下达风格指令的必要，使 AI 生成的代码更接近生产环境标准。
• 灵活部署：支持项目级配置，也可通过软链接（如 gemini.md 或 claude.md）实现全局应用。

详细分析

从“不可用”到“面条代码”的转变

Fabien Sanglard 在记录中回顾了其使用大语言模型（LLM）辅助编程的三个阶段。2025 年中期，他在开发 Rust 语言的 mDNS 实现（libadbmdns）时首次尝试 LLM，但结果令人失望，生成的代码甚至无法通过编译。然而，到了 2026 年 1 月，技术发生了质变。LLM 不仅能编写复杂的索引二进制堆类，甚至能精准定位 Windows IOCP 实现中 polling crate 的隐蔽漏洞。尽管功能性得到了验证，但代码质量却极其糟糕——缺乏注释、结构混乱的“面条代码”成为了新的障碍。如果节省的开发时间全部被耗费在代码重构和清理上，LLM 的实用价值将大打折扣。

代理式 IDE 与重复指令的困境

2026 年 3 月，随着 Antigravity 和 VS Code 的 Claude Code 插件等代理式（Agentic）IDE 的出现，开发者开始能够对 AI 生成的代码进行“阶段性迭代”。作者发现自己扮演了一个“极其耐心的资深开发者”角色，不断向 AI 这个“初级实习生”重复相同的建议：不要使用魔法数字、添加简短注释、使用简短的函数名等。虽然代码质量因此得到了显著提升，达到了接近手写代码的水平，但这种在每个新会话中不断重复相同指令的过程极其乏味且低效。

agent.md：提示词工程的持久化方案

为了解决重复劳动的痛点，作者提出了 agent.md 的解决方案。其核心逻辑是在编码会话开始时，由开发工具自动加载该文件并将其内容注入到系统提示词中。这为开发者提供了一个微调 AI 编码风格的完美入口。通过将“禁止魔法数字”、“规范注释格式”等偏好写入 agent.md 并放置在项目根目录，AI 能够从一开始就遵循开发者的特定标准。此外，通过将 gemini.md 或 claude.md 软链接至 agent.md，开发者可以轻松地在不同模型和项目中保持一致的编码规范，实现了从“手动纠偏”到“自动约束”的跨越。

行业影响

该实践对 AI 辅助软件工程领域具有重要的参考意义。首先，它标志着开发者与 AI 的协作模式正在从简单的“对话式编程”转向“配置驱动型编程”。通过 agent.md 这样的标准化配置文件，团队可以统一 AI 生成代码的风格，降低代码审查的成本。其次，这反映了当前 AI 工具链的一个趋势：即如何通过更精细的上下文管理（Context Management）来弥补通用模型在特定工程规范上的不足。对于 AI 插件开发者而言，支持此类自动加载的配置文件可能成为未来 IDE 插件的标准功能。

常见问题

问题 1：agent.md 应该放在什么位置才能生效？

根据作者的经验，将 agent.md 文件放置在项目的根目录下即可。对于希望在所有项目中通用的配置，可以通过创建软链接（如将 gemini.md 或 claude.md 指向 agent.md）的方式，使其在任何地方都能被编程工具识别并激活。

问题 2：agent.md 主要包含哪些内容？

agent.md 主要用于存储开发者的编程风格偏好。例如，可以包含关于如何编写注释、如何撰写提交信息（commit message）、函数命名规范、以及避免使用魔法数字等具体要求。它本质上是一个针对 AI 的“个性化编码规范手册”。

问题 3：这种方法能完全替代人工代码审查吗？

虽然 agent.md 显著提升了代码的初始质量，使其更接近生产标准，但它并不能完全替代人工审查。作者提到，该方法的作用是减少重复性的风格纠正，让开发者能更专注于逻辑层面的审核，而不是浪费时间在基础的格式和命名问题上。