My agent.md to improve LLM-assisted code quality
A project-level agent.md is a high-leverage lever for consistent, production-grade LLM code — it moves style/architecture guidance out of the chat loop and into the system prompt.
Key Points
- Early LLM coding attempts (mid-2025) produced non-compiling Rust code for
libadbmdns; by Jan 2026 LLMs could write complex data structures and debug obscure crate bugs like the Windows IOCP issue in the polling crate. - Agentic IDEs (Antigravity, VS Code Claude Code) enabled iterative refinement but required repetitive style guidance — “don’t use magic numbers,” “add comments,” “short function names” — per session.
- Solution: place an
agent.mdin the project root (or symlinkgemini.md/claude.mdto it) so the harness injects it into every prompt, encoding preferences once. - Author’s
agent.mdenforces: concise human-facing text, no magic numbers (use constants/enums), reduced indentation via early returns, short function names (<30 chars), enums over booleans, whitespace between logical blocks, explanatory comments with ASCII diagrams, strict private-by-default visibility, layered architecture boundaries, minimal diffs, mandatory braces, and a 7-rule commit message format. - Workflow for bug fixes: write failing test first, observe failure, then implement fix, observe pass — prevents hallucinated fixes.
- Context dilution (per Lost in the Middle paper) degrades adherence to
agent.mdin long sessions; mitigations: start new session per feature, or explicitly ask the harness to “reload agent.md” when quality drops. - Meta-tip: ask the agent to update
agent.mddirectly when a new rule emerges, avoiding manual edits.