My agent.md to improve LLM-assisted code quality

TL;DR Highlight

Moving repeated review feedback into agent.md raised the quality of LLM-written code

Who Should Read

A developer tired of giving an AI coding agent the same code-review feedback every session

Core Mechanics

Repeated feedback went into agent.md
- The harness loads agent.md at session start and injects it into the prompt.
- Each time the author repeated a suggestion, he added it as a rule.
- Place it in the project root, or symlink gemini.md or claude.md to it.
Style rules are concrete
- Extract magic numbers into constants or enums, and cut indentation with early return and continue.
- Keep function names under 30 characters, use enums instead of boolean parameters, and always use {} on ifs.
- Don't touch unrelated code and minimize changed lines.
Structure and communication rules too
- Members stay private, and changing access needs explicit user approval.
- Each layer talks only to the layer directly below, so controllers never call DB queries or hardware drivers directly.
- No praise, and answers use as few words as possible.
Bug fixes start with a test
- Write the test first, watch it fail, then fix and watch it pass.

Community Reactions

Opinion: enforce with linters
- Commenters said rules like {} and name length belong in linters so hand-coders get the same feedback.
- Another said 'what is the code itself', so per-block explanatory comments add noise.
Experience: many rules are unnecessary
- One commenter has used Claude for almost a year and never saw Arrow Anti-Pattern code.
- Another said 8 or 9 rules are basic CS, and vague ones like 'let the code breathe' are rarely effective.
- They suggested making the model print a string when it applies a rule to measure what works.
Context cost and splitting rules
- One commenter said bloated AGENTS.md hurts context use, and having the agent pick applicable rules first gave 100% consistency.
- Another puts coding rules in CODING_STANDARDS.md, which skills load only when needed.
- One always uses /tdd and said that despite occasional silly tests it yields much lower defect code.
Opinion: phrase rules positively
- One commenter said 'don't do X' pre-seeds X, so 'do Y, for these reasons' works better.

How to Apply

Add your top 3 repeated notes to agent.md
- Pick three review comments you repeated to the agent today and add each as a line in agent.md at the project root.
- Start a new session on the same task and check the issues are gone.
Add a test-first rule for bug fixes
- Put 'For fixes, write a failing test first, confirm it fails, then fix and confirm it passes' in agent.md.
- Apply it to your next bug ticket and compare the diff.
Use a new session and reload command
- Start a new session after each feature.
- Type 'Reload agent.md' when quality drops.
Move lintable rules to the linter
- Move machine-checkable rules like braces or name length into linter config.
- Keep only design rules in agent.md that a linter can't catch.

Try It

copy & run

# Paste into agent.md (or CLAUDE.md) for Claude Code or an agentic IDE. Simplified version of the original agent.md

- 사람이 읽는 글(주석, 커밋 메시지, 답변)은 최소한의 단어로 쓴다. 칭찬과 최상급은 빼고 냉정하게 말한다.
- 매직 넘버와 문자열은 설명적인 상수나 enum으로 뺀다. 한 번 쓰는 자명한 값은 그대로 둔다.
- 들여쓰기를 줄인다. early return과 continue를 쓴다.
- 함수 이름은 30자 미만으로 짧게 쓴다.
- boolean 파라미터 대신 enum을 쓴다.
- if는 한 줄이어도 항상 {}를 쓴다.
- 구현하는 기능과 무관한 코드는 건드리지 않는다. 바뀐 줄을 최소화한다.
- 멤버는 기본 private. 접근 제어자를 넓히기 전에 승인을 요청한다.
- 버그 수정 요청이면 수정 전에 테스트를 먼저 쓰고, 실패를 확인한 뒤 수정하고, 통과를 확인한다.

# Next step: ask the agent to print [RULE:name] whenever it applies a rule, then count which rules are actually followed.

Terminology

agent.mdA config file the coding tool injects into the prompt at session start. It is like pre-loading your team's coding conventions into the AI.

HarnessThe tool wrapping the LLM that handles file reads and prompt assembly, such as Claude Code or Antigravity.

Context dilutionAs context grows, the model pays less attention to instructions in the middle. It is like remembering the start and end of a long meeting but not the middle.

Arrow Anti-PatternDeeply nested ifs that push code to the right in an arrow shape. Early returns flatten it.