Put your code style in agent.md: Fabien Sanglard's 15 rules for taming Claude Code
Put your code style in agent.md: Fabien Sanglard's 15 rules for taming Claude Code
On August 23, 2026, Fabien Sanglard — the guy behind the annotated Doom source — dropped his agent.md on Hacker News. Seven hours later it was sitting at 147 points with 75 comments. Forget flashy prompt hacks; what he's really saying is blunt: the biggest problem with LLM-written code isn't that it can't compile. It's that it doesn't look like yours.
His framing: instead of telling your coding agent "no magic numbers" and "add a comment here" in every single session, write it all down once in a file and let the toolchain inject it for you.
From "would not even compile" to "abysmal code quality"
Sanglard's timeline is refreshingly honest. His first LLM attempt, mid-2025, produced Rust code that "would not even compile" — he walked away. By January 2026, the model could write a complex indexed-binary heap class and pinpoint an obscure Windows IOCP bug in the polling crate. But the cost: "spaghetti code with no comments and no structure."
In March 2026 he switched to agentic IDEs (Antigravity, VS Code's Claude Code plugin). Now he could iterate over "staged" code — but the experience became reviewing the work of an "infinitely patient junior CS major":
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".
Quality got close to hand-written. But he kept repeating himself in every new session. That's the pain agent.md exists for.
agent.md: injecting "you" into every session
The whole trick, in his own words:
When a coding session starts, the coding harness loads a file named agent.md and injects it into the prompt.
Your style preferences get "super fine-tuned" into every session. He published his full agent.md (linked below), and the rules fall into three buckets:
| Category | Example rules |
|---|---|
| Code style | No fluff comments, avoid magic numbers, function names <30 chars, enums over boolean params |
| Architecture | Strict layer boundaries, private by default, never touch unrelated blocks |
| Workflow | Write the failing test before the fix, 7 commit-message rules |
A few rules worth stealing outright:
- "Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth." — kills the AI sycophancy problem at the root.
- "Always use {}, even on a one-line 'if' statement." — the classic dangling-else trap, banned.
- "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." — TDD, baked into the system prompt.
Don't expect it to read code for you
Sanglard is careful about what agent.md is not:
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.
The real win: he spends his energy on architecture and design instead of cleaning up style. He also flags a real failure mode — context dilution (from the Lost in the Middle paper). As context grows, models pay less attention to instructions in the middle. His two countermeasures: start a new session per feature to keep context short, and when quality dips, just say:
Reload agent.md is enough when I see code quality dropping.
What you can do today
Don't write your own rules from scratch. Fork his agent.md (link below) as a starting point and drop it in your project root. If you use both Gemini and Claude CLIs, symlink gemini.md / claude.md to the same agent.md — one rule set, active everywhere.
Then run his loop for a week: every time you catch yourself saying "no magic numbers" to your agent, add it to agent.md instead. Let the model improve itself.
FAQ
What is agent.md? A config file that coding harnesses (Claude Code, Gemini CLI, etc.) auto-load and inject into the prompt at session start, encoding your code style and workflow preferences. Spec discussion lives in agents.md issue #135.
Where does agent.md go? Project root. Sanglard: "Placing it in the root of a project should be enough." For multi-tool setups, symlink your tool-specific files to the same source.
Does agent.md conflict with CLAUDE.md? No. agent.md is the general spec; tools have their own files (claude.md / gemini.md). Sanglard symlinks them all to one agent.md so there's a single source of truth.
Sources
- Fabien Sanglard, My agent.md to improve LLM-assisted code quality: https://fabiensanglard.net/agent.md/index.html
- agents.md spec discussion, issue #135: https://github.com/agentsmd/agents.md/issues/135
- Lost in the Middle (the context dilution paper): https://arxiv.org/abs/2307.03172
✨ Drafted by DeepSeek, edited by Claude.