My agent.md to improve LLM-assisted code quality
This article introduces the concept of an agent.md file, a custom markdown document containing coding style guidelines and best practices, that is injected into an LLM's prompt context. The author shares their evolving journey to improve AI-generated code quality, demonstrating how this method helps guide LLMs to produce production-ready code. The Hacker News community discusses the effectiveness of such explicit instructions, debating their necessity versus alternative methods like linters or multi-pass refinement.
The Lowdown
The author recounts their initial struggles with LLMs producing poor-quality code in 2025-2026, despite improvements in basic functionality. They found themselves constantly repeating style and structural feedback to the LLM, a tedious process that negated the speed benefits of AI assistance. This led to the development of agent.md.
agent.mdis a markdown file containing explicit coding standards and preferences (e.g., commit message rules, avoiding magic numbers, short function names, early returns, commenting guidelines).- This file is injected into the LLM's prompt at the start of a coding session, acting as a dynamic style guide for the AI.
- The author provides a sample
agent.md, emphasizing principles like conciseness in human-facing text, structured commenting, and layered architecture. - It addresses "context dilution," where LLMs lose focus on instructions in the middle of a long prompt, by suggesting short sessions and explicit reloads of
agent.md. - The system allows the LLM itself to update the
agent.mdfile, streamlining the refinement process.
While agent.md significantly improved code quality by shifting the focus from stylistic cleanup to architectural concerns, the author stresses it's not a panacea; human review and iteration remain crucial due to LLM hallucination.
The Gossip
Instructional Inconsistencies
Commenters debate the effectiveness and necessity of the specific rules presented in the author's `agent.md`. Some argue that many style guidelines should be enforced by static analysis tools (linters) rather than LLM instructions, or that LLMs already understand many best practices. Others suggest that certain rules, like 'keep function names short,' could be counterproductive, leading to ambiguous abbreviations. There's also skepticism about LLMs consistently following such detailed instructions, with some users reporting models often ignore their custom guidelines.
Alternative Agent Architectures
The discussion branches into alternative approaches for guiding LLMs or managing code quality. Some suggest a multi-pass strategy, where the LLM first creates functional code, and then a second pass refines it for quality and adherence to guidelines. Another commenter proposes using established simplified technical English standards like ASD-STE100 to ensure clarity and conciseness. There's also debate on the `agent.md` concept itself, with some arguing that standard contributing documentation is more appropriate, while others value the convenience of auto-included context.
AI's Laws of Coding
A thematic undercurrent compares `agent.md` to "Asimov's laws of robotics," hinting at the potential for unintended consequences or unexpected interpretations by the AI. This reflects a broader concern about the unpredictable nature of LLM behavior, even with explicit instructions, and the ongoing challenge of truly aligning AI output with human intent, particularly in the nuanced domain of code quality and style.