跳转至

我的 agent.md：如何利用它提升大模型辅助编程的代码质量

文章背景与核心概要

在使用大语言模型（LLM）进行辅助编程时，尽管开发速度大幅提升，但初始生成的代码往往杂乱无章、缺乏格式化，需要进行繁琐的手动修正。为了解决这一痛点，开发者 Fabien Sanglard 引入了一种项目级的配置文件——agent.md。通过在 AI 的提示词约束（prompt harness）中直接注入代码风格指南、架构边界和编码标准，从而消除了重复的代码风格纠正，确保产出达到生产环境的可用标准。

本文探讨了 Fabien 如何通过迭代工作流演进出 agent.md 方案，详细列出了其自定义的各项严格规则，并分享了应对大模型“上下文稀释（context dilution）”问题以及自动更新配置文件的实用技巧。

摘要 (Executive Summary)

Using Large Language Models (LLMs) for coding can drastically speed up development, but the initial code quality is often messy, unformatted, and requires tedious correction. By introducing a project-level configuration file named agent.md, developers can inject style guides, architectural boundaries, and coding standards directly into the AI's prompt harness. This article explores how Fabien Sanglard evolved his workflow to eliminate repetitive code-style corrections and maintain production-ready outputs.

使用大语言模型（LLM）进行编码可以极大地加快开发速度，但初始代码质量往往杂乱无章、未格式化，并且需要进行繁琐的修正。通过引入名为 agent.md 的项目级配置文件，开发者可以将风格指南、架构边界和编码标准直接注入到 AI 的提示词框架中。本文探讨了 Fabien Sanglard 如何演进其工作流，以消除重复的代码风格修正并保持生产就绪的代码输出。

从无感到应接不暇 (From Unimpressed to Overwhelmed)

Fabien's first attempt to use LLMs for coding in mid-2025 resulted in broken, non-compiling Rust code for an mDNS implementation (libadbmdns). Returning to LLMs in January 2026 yielded much better results, including complex binary heap generation and tracking down obscure Windows IOCP bugs.

However, the generated code quality was abysmal: spaghetti code devoid of comments and structure. The time saved in writing code was quickly lost in cleaning it up to meet production standards.

Fabien 在 2025 年中期首次尝试使用 LLM 进行编码时，得到的 mDNS 实现（libadbmdns）是损坏且无法编译的 Rust 代码。2026 年 1 月重新使用 LLM 时，效果有了很大改善，包括复杂的二叉堆生成以及排查晦涩的 Windows IOCP 漏洞。

然而，生成的代码质量依然糟糕透顶：充斥着缺乏注释和结构的“面条代码”。编写代码所节省的时间，很快就在将其清理至符合生产标准的过程中消耗殆尽了。

不断迭代与重复唠叨 (Iterating and Repeating Yourself)

By March 2026, using agentic IDEs like Antigravity and VS Code's Claude Code plugin allowed for staged code iteration. While code quality improved significantly—resembling hand-written work—the process became tedious. Fabien found himself acting as an infinitely patient junior CS major's reviewer, constantly repeating instructions like: * "Don't use magic numbers." * "Add a short explanatory comment." * "Use short function names."

到 2026 年 3 月，使用诸如 Antigravity 和 VS Code 的 Claude Code 插件等智能体 IDE（agentic IDEs），使得分阶段的代码迭代成为可能。尽管代码质量显著提高——类似于人工编写的代码——但这个过程变得十分繁琐。Fabien 发现自己扮演着一个拥有无限耐心的计算机专业初级学生的审阅者，不断重复着如下指令： * “不要使用魔法数字。” * “添加简短的解释性注释。” * “使用简短的函数名。”

Agent.md 救场 (Agent.md to the Rescue)

Coding harnesses often load a file named agent.md at the start of a session, injecting it directly into the prompt. This serves as the ideal location to fine-tune coding style preferences once and for all.

Placing the following agent.md file in the root of a project enforces these standards automatically. (Alternatively, you can symlink gemini.md or claude.md to point to agent.md).

编程工具框架通常会在会话开始时加载名为 agent.md 的文件，并将其直接注入到提示词中。这是彻底微调代码风格偏好的理想场所。

将以下 agent.md 文件放在项目的根目录下，即可自动强制执行这些标准。（或者，您可以将 gemini.md 或 claude.md 符号链接指向 agent.md）。

# FAB's AGENT.MD

- When writing something intended for human consumption, (comment, commit message, reply to prompt) use as few words as possible. Pick every word meticulously to reduce the volume to a strict minimum. Be down to the point. Less is more.

- Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth.

- Avoid magic numbers and strings by extracting recurring or meaningful values into descriptive constants (const) or enums. Keep self-explanatory, one-off values inline to avoid clutter. If a value comes from a spec (e.g. HTTP 200 OK), use a constant regardless.

- Reduce code indentation. Avoid Arrow Anti-Pattern. Leverage early return and continue.

- Keep function names short. Less than 30 characters.

- Use enums instead of booleans for function parameters.

- Let the reader of the code breathe. Add empty lines between logical blocks of code.

- Add a small, to the point, comment to explain *what* the block does and *why*. Use examples when possible. Propose ASCII drawings to explain complete systems.

- Treat member visibility changes as a breaking design shift. Keep all fields and functions private unless external access is strictly required by the design. Prompt the user for explicit approval before changing any access modifier from private to internal or public.

- Program to levels of abstraction. Lower-level mechanics (e.g., raw hardware I/O, sector parsing, direct socket streams) must be encapsulated in a dedicated driver/abstraction layer. Expose clean, high-level APIs to the rest of the application so calling code works with domain concepts, not raw implementation details.

- Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature.

- Strictly adhere to the layered boundary hierarchy: each layer may only communicate with its immediate neighbor directly below it. Never "punch holes" through layers (e.g., controllers or UI components must never directly call database queries, raw hardware drivers, or low-level network clients; always route through the intermediate service/abstraction layer).

- Always use {}, even on a one-line "if" statement.

When you write a commit message, follow these 7 rules:
Rule 1: Separate the subject line from the body with a single blank line.
Rule 2: Limit the subject line to 50 characters (72 is the absolute hard limit).
Rule 3: Capitalize the first letter of the subject line.
Rule 4: Do not end the subject line with a period.
Rule 5: Use the imperative mood in the subject line (e.g., "Fix bug," "Add feature," 
        not "Fixed" or "Adds"). Test formula: It must complete the sentence: "If applied,
        this commit will [your subject line here]".
Rule 6: Wrap the body text manually at 72 characters to prevent Git formatting issues.
Rule 7: Use the body to explain what and why vs. how. Assume the code explains the how;
        the message must explain the context and reasoning. 

- If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test. Observe it failing. Then write the fix. And observe the test passing.

Note: While this approach dramatically improves code quality, it isn't a silver bullet. LLMs still hallucinate and require code review—shifting the developer's focus from micro-style edits to high-level architecture and design.

注意： 尽管这种方法极大地提高了代码质量，但它并非万灵药。LLM 仍然会产生幻觉并需要代码审查——这把开发者的工作重点从微观风格的修改转移到了高层架构和设计上。

如何应对上下文稀释 (How to Deal with Context Dilution)

As context grows, LLMs suffer from "context dilution" (or attention dilution), as explored in the "Lost in the Middle" paper. Models pay less attention to instructions buried in the middle of the context window. To minimize this issue:

  1. Keep the context short: Start a fresh session for each new feature.
  2. Explicitly reload: Prompt the harness to reload instructions when code quality dips by simply typing: "Reload agent.md."

随着上下文的增长，LLM 会遭受“上下文稀释”（或注意力稀释）的影响，正如“迷失在中部”（"Lost in the Middle"）论文中所探讨的那样。模型对埋在上下文窗口中间的指令关注度会下降。为了将此问题降到最低：

  1. 保持上下文简短： 为每个新功能开启一个全新的会话。
  2. 显式重新加载： 当代码质量下降时，只需输入 “Reload agent.md.” 即可提示框架重新加载指令。

自动更新 agent.md (Auto-Updating agent.md)

You don't need to manually open an editor every time you want to refine a rule. A quick and efficient approach is to simply ask the agent to update agent.md directly when a new preference emerges.

每当你想完善规则时，大可不必每次都手动打开编辑器。一个快捷高效的方法是：当出现新的偏好时，直接让 AI 助手去更新 agent.md 即可。