My agent.md to improve LLM-assisted code quality
Developers are debating how useful dedicated “AGENTS.md” files are for steering large language models when generating code, compared with relying on linters, existing CONTRIBUTING/CODING_STANDARDS docs, and simpler, high‑level guidelines. Many complain that models overproduce low‑value comments and verbose style fixes, arguing that mechanical checks and concise, positively phrased rules work better than long, detailed agent instruction files that can dilute context or become obsolete as models improve. Others still find value in minimal agent prompts that encode workflow norms (like TDD or limiting unrelated edits) and voice/style constraints, but see per‑project, evolving configurations as more effective than one-size-fits-all rule sets.
Role and Design of AGENTS.md
- Many see AGENTS.md as useful but highly personal: different people, projects, and models have different failure modes, so a shared template is only a starting point.
- Some argue much of the article’s content is generic CS or already “known” by modern models, so extra rules may add little or even harm.
- Others feel AGENTS.md is an “ugly band-aid” that goes stale with new models, is often ignored, and can poison reasoning when rules are misinterpreted.
- Alternative: keep project rules in CONTRIBUTING/CODING_STANDARDS and have the harness or skills discover them as needed.
Linters vs Agent Instructions
- Strong theme: enforce mechanical/style rules with linters, pre-commit hooks, and CI, not via non-deterministic agents.
- Examples: braces on one-line
if, no nested ternaries, no comments, formatting, magic numbers. - Some use an LLM as CI/reviewer to detect forbidden patterns/comments, making “robots fight robots.”
Comments and Documentation
- Widespread frustration with over-commenting: agents generate verbose “what this does” comments, often longer than code.
- Many try to ban comments entirely or allow only “why/context” comments; “what” should be self-evident from code.
- Concerns: comments go stale, mislead humans and future agents, and pollute context.
- A minority defends comments as summaries for large/ugly functions or places with hidden complexity; some hide comments via editor folding.
Instruction Following and Prompt Strategy
- Users report mixed success with rules like “never add comments”; newer larger models obey better, others ignore.
- Discussion of “do” vs “don’t” phrasing: positive instructions may persist better than prohibitions, but some constraints (e.g., “no comments ever”) are hard to express without “don’t.”
- Long, dense AGENTS.md can suffer from “lost in the middle” context dilution; several prefer short core rules, or modular rule files that the agent selects per task.
Style, Architecture, and Workflow Preferences
- Strong disagreements on style mandates: short vs long function names, always-using braces vs minimalism, enums vs booleans, small extracted functions vs larger ones.
- Some emphasize architectural and “why” context in AGENTS.md over line-level rules.
- Workflows mentioned: multi-pass generation with self-review, convergence-style rules (success/progression/honest stop), TDD-centric prompting, and strict limits on agents touching unrelated code.