My agent.md to improve LLM-assisted code quality

The author first tried LLM-assisted coding in mid-2025 while working on libadbmdns, a Rust mDNS implementation, but was unimpressed because the generated code did not even compile. Revisiting LLMs in January 2026 worked better: the LLM produced a complex indexed-binary heap class and pinpointed an obscure bug in the polling crate caused by Windows IOCP. However, the code quality was abysmal — spaghetti code with no comments or structure — making it impractical unless the author spent significant time cleaning it up.

In March 2026, the author tried agentic IDEs like Antigravity and VS Code's Claude Code plugin, iterating over staged code as if reviewing an infinitely patient junior CS major. Telling the assistant to avoid magic numbers, add comments, and use short function names dramatically improved output, but the process was tedious because the same suggestions had to be repeated every session. The solution was an agent.md file loaded into the prompt when a coding session starts. The author placed it in the project root and suggests symlinking gemini.md/claude.md to agent.md to make it active anywhere.

The agent.md content includes rules such as: use minimum words for human-consumption text, avoid superlatives and praise, avoid magic numbers by extracting constants (especially values from specs), reduce indentation with early returns, keep function names under 30 characters, use enums instead of booleans for parameters, add blank lines between logical blocks, add concise comments explaining what and why with examples and ASCII diagrams, and treat member visibility changes as a breaking design shift — keeping fields and functions private unless needed.