My agent.md to improve LLM-assisted code quality

Source: Fabien Sanglard · https://fabiensanglard.net/agent.md/index.html
URL: https://fabiensanglard.net/agent.md/index.html
Original date: 2026-08-21
Captured: 2026-08-22 (AAIF daily intake, opencli web read)

摘要（AAIF）

Fabien Sanglard（Rust mDNS 实现 libadbmdns 作者）记录与 Claude Code 协作的真实迭代：agent 产出能跑但像意大利面，他在每个新 session 重复同样的风格指令。解法是把规范固化到项目根目录的 agent.md，由 harness 在 session 起始注入。文中公开全文：措辞极简、禁 superlative 与夸奖、recurring 值提取为常量、早返回防箭头反模式、函数名小于 30 字符、参数用 enum 不用 bool、访问修饰符变更需显式批准、分层不得穿层、commit message 七条规矩、修 bug 先写失败测试。针对 Lost in the Middle 的 context dilution 给出两对策：每个 feature 开新 session、发现质量下滑就让 agent Reload agent.md。作者坦承这不是 magic bullet——幻觉仍需人盯，但注意力终于能从代码风格回到架构。

为什么值得读：把和 agent 协作从口号拆成十几条可执行规则，每条背后都有真实项目场景；agent.md 全文公开，可直接当模板。

Summary (EN)

Fabien Sanglard documents his real iteration loop with Claude Code on libadbmdns (a Rust mDNS implementation): agent output compiles but reads like spaghetti, and he kept repeating the same style suggestions every session. The fix is to codify them into an agent.md that the harness injects at session start. The post publishes his full rule set: minimal wording, no superlatives or praise, extract recurring values into constants, early returns against the arrow anti-pattern, function names under 30 chars, enums over booleans for parameters, member-visibility changes require explicit approval, strict layer boundaries, seven commit-message rules, and test-first bug fixing. For context/attention dilution (Lost in the Middle) he prescribes a new session per feature and asking the agent to reload agent.md when quality drops. Not a magic bullet — hallucinations still need review — but his focus moves from code style back to architecture.

原文（full text capture）

Fabien Sanglard - WEBSITE

https://github.com/fabiensanglardmailto:fabiensanglard.net@gmail.comhttps://fabiensanglard.net/rss.xml

Aug 21, 2026

My agent.md to improve LLM-assisted code quality

The first time I tried to use an LLM to speed up coding was in mid-2025. I was not impressed. I was working on libadbmdns back then, an mDNS implementation in Rust. The code produced would not even compile.

I revisited LLMs in January 2026. This time it worked better. Not only did it write a complex indexed-binary heap class, it was able to pinpoint an obscure bug in the polling crate due to the Windows IOCP implementation.

However, the code quality was abysmal. It was spaghetti code with no comments and no structure. It was cool but not realistic to work with LLMs if the speed gain was lost to cleaning up the code until it met the production-level bar.

Iterating and repeating myself over and over again

In March 2026, I tried to use agentic IDEs like Antigravity and VS Code's Claude Code plugin. I was now able to "iterate" over the "staged" code. I found myself reviewing the code of an infinitely patient junior CS major with suggestions like "don't use magic numbers", "add a short comment here to explain yourself", or "use short function names".

The code quality improved dramatically. It was very close to what I would have produced "by hand" but it was tedious. I ended up repeating myself over and over again in each new session.

Agent.md to the rescue

When a coding session starts, the coding harness loads a file named agent.md and injects it into the prompt. This is the perfect location to super fine-tune coding style preferences. When I found myself repeating the same suggestion to improve the code, I added it in there.

Here is my version of agent.md as a starting point if you need one. Placing it in the root of a project should be enough. Alternatively, gemini.md/claude.md can be symlinked toward an _agent.md_ to have it active anywhere.

\# 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.

While this "trick" has considerably improved the code generated, this is not a magic bullet that lets me avoid reading the code. LLMs constantly hallucinate and cannot be trusted. I still have to verify and iterate a lot but now I usually focus on architecture and design instead of code style.

How to deal with dilutions

There is an annoying phenomenon with LLMs called "context dilution" or "attention dilution" that was outlined in the Lost in the Middle paper. As the context grows, a model starts paying less attention to instructions in the middle of the context in favor of what is at the beginning and the end. The reasons why this happens are not well understood at the time I am typing this. I have found only two ways to minimize the impact.

1. Keep the context short. This means starting a new session per feature. 2. Explicitly ask the harness to reload _agent.md_. "Reload agent.md" is enough when I see code quality dropping.

Auto-update agent.md

You don't need to open an editor every time you want to add a new rule. What I do now is ask the agent to update agent.md.

Source: https://fabiensanglard.net/agent.md/index.html

Captured: 2026-08-22 (AAIF daily-intake-evening)