A bunch of these should be enforce with linting, that way people who still hand-craft code get the same kind of feedback, e.g. Always use {}, even on a one-line "if" statement. & Keep function names short. Less than 30 characters.

Then this one really is a pattern that creates a lot of churn:

- Add a small, to the point, comment to explain what the block does and why. Use examples when possible. Propose ASCII drawings to explain complete systems.

The what _is_ the code.

> - Keep function names short. Less than 30 characters.

Recently I asked GPT to port a browser game to Rust. It voluntered this gem:

draw_image_with_html_image_element_and_sw_and_sh_and_dx_and_dy_and_dw_and_dh(...)

I thought it was smoking some good stuff, but it turned out, that is actually the name of the function!

https://docs.rs/web-sys/latest/web_sys/struct.CanvasRenderin...

Great stuff. AGENTS.md is not the ideal place for most of it though. Most of what is shown in this article can go in CODING_STANDARDS.md. The skills that I use find this document when it is needed (writing and reviewing code) so it doesn't pollute context when code is being read.

I also have sub-agent reviews (both of a planning phase and the produced code) that would catch some of these problems and demand revisions. [1]

> - If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test. Observe it failing. Then write the fix. And observe the test passing.

I always use /tdd [2]. Occasionally it results in some silly tests, but it produces much lower defect code. Its not just for bugs.

[1] https://github.com/gregwebs/skills-sdlc/

[2] https://github.com/mattpocock/skills/blob/main/skills/engine...

Since we are sharing our AGENTS.md, I thought I'd share my own, because most of the time, this is pretty much all you need for LLMs to write good code, everything else can be added per project: ---- *Convergence rule* Every substantial task must end in exactly one of three states:

A. Success The intended capability works in the real path and the real motivating case materially improves.

B. Meaningful progression The capability is not complete, but one genuine blocker is removed and the next blocker is isolated with evidence.

C. Honest stop Further work would require overbroad scope expansion, excessive debt, brittle patching, or tangled logic. Stop and report the reason with concrete evidence.

Do not continue producing patches once the work stops converging.

Do not confuse activity with progress. A failed attempt is only acceptable if it leaves behind a narrower problem, stronger evidence, or a justified stop.

Any partial work must leave the codebase in a cleaner, more legible, and more diagnosable state than before. ----

A lot of the article's AGENTS.md just feel like telling the LLM agents either something they already know (for example, most of the time they know to use exhaustive switch/match statements instead of "arrow anti-pattern") or seems actively harmful ("keep function names short" seems arbitrary and may cause the LLMs to write weird abbreviations for functions that are harder to read and review.

It's interesting to read these things.

I would describe this as 13 code writing rules (interpreted to be at least 16 - Starting with reduce code indentation) plus a commit message instruction set which I chose to ignore - because it's style-specific and not interesting to me.

8 or 9 of these rules are not necessary. Basic CS is not something I have needed to ask agents, I use, to follow. eg Explaining that you need explicit interfaces is not a necessary instruction, nor is leveraging early return.

Unclear instructions are of limited utility. What "Let the reader of the code breathe" or "reduce code indentation" means is subjective and will rarely be effective. Maybe the training for the language being used has gaps, which others do not. If you want to measure, ask it to output a string when it applies a rule. You'll figure out what works, what doesn't and how often, quickly.

There's 3 or 4 style choices included.

The rest are not something I would use, but we all get burned by different things so I get it.

This is a problem that people mostly have to solve themselves. Like, I've been working with Claude for almost a year now and I have never once seen it write "Arrow Anti-Pattern" code. That, and much of the rest, would be fluff in my projects. Agent instructions are best learned from experience project-by-project.

Hm. I'm curious if this actually helps LLMs iterate on the code, or if it's human nitpicking over things that the author won't really look at? How would you measure?

Personally, I tend to do 3 passes, where I ask the agent to write, and self review; that's been enough to get things functional enough that I don't need to read the code.

A great piece.

I esp liked:

"- Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature."

The feature where you ask the LLM to fix one thing and it fixes three things.

I kept noticing this in diffs.

Just this one line in AGENTS.md has given better results to reduce if not eliminate verbosity and grandeur.

**Always use ASD-STE100 Simplified Technical English

Disclaimer: I saw this listed in some other HN post that I can' locate right away.

What's the point of agents.md if you just use an LLM on a codebase?

Just say, complete this bit like how the rest is...

Even then they aren't great at it. Idk, the best case use for LLMs are extremely specific requests, for example "write an evaluator for this byte code and if you can't ask for clarification"

The ultimate specification language is code anyways so you might as well stick a to-do, a comment describing the semantics of the function and say "okay codex fill the to-do"

I feel like claude.md is like Asimov's laws of robotics. Whatever you write there ends up eventually messing up everything.

Some of these such as "Always use {}, even on a one-line "if" statement." should just be lint rules.

This approach never worked for me. Explanation here:

- https://www.minid.net/2026/7/14/how-to-automatise-with-ai

But in summary: the more bloated your AGENTS.md is, the worse the context consumption gets. The best approach I use is telling the agent to first think about what it needs to do, then choose which rules apply. I got 100% consistency across every area of my projects.

In the post there's also a replica of one of projects rules I use, feel free to provide feedback: https://github.com/meerita/monorepo-nextjs-golang-rust-pytho...

I disagree with the less than 30 characters.

Im against restricting anything related to code length this goes for function names and length, file length ect.

I rather the dots be as close as possible than trust the agent connects the dots.

I dont care if the file is 5000 lines I rather the agent reads one file and get all the context than trust it will read all the need files.

I see so many review skills that puts hard limits on these thing and it just bad.

The function name shouldn't be limited they should be as clear as possible and if for some reason it over 30 chars so be it.

I want to read the function name and the logic and it match exactly. I don't want the agent being lazy because of some limit I set.

In fact I force my agents to write long functions because I specifically tell it not to break out repeated code that doesn't actually deserve a function.

A check on a function input doesn't need to be a function. A auth guard doesn't need to be it own function.

types.go types.ts absolutely the worst file to see in any code base. Put the type next to the code that uses it.

From FAB's AGENT.MD: > - Avoid magic numbers and strings by extracting recurring or meaningful values into descriptive constants (const) or enums. ---

I've been seeing the same thing with models like GPT5.6 and Opus4.8 in GH Cop CLI. They still introduce magic numbers, and in Scala they often put an entire 10-line Spark expression inside an if condition instead of extracting it into a meaningfully named value to keep "if" readable. I wonder when common sense instructions will be baked into the models.

I could understand "prefer enums to booleans" but "use enums instead of booleans" is a weird choice.

Then again, with the LLM capacity for nuance it would be the same thing.

I think it's a bit too detailed, especially with the linting.

To me when I code by hand, I never use {} after an if statement if it's one-line, it's just faster, look cleaner to me.

I didn’t see anything in there instructing the LLM not to generate text about goblins.

I used to be big into agents.md files but read the latest SOTA doesn’t need them anymore. Have people still been getting value out of them?

I really like that you put architectural context in there, specifically the "why" behind certain decisions

Can't wait to modify my agent.md file and then forget about it until it becomes useless again

I had good results with making it add a few lines with a summary of RFC 2119/8147 keywords (SHALL/MUST...), and then using those, uppercase.

local llm remain more in line like that.

Some of these are generic software engineering advice.

I noticed modern frontier models (e.g., Fable/Opus/Sol) need less procedural coaching than earlier models.

Are they sure it improves code quality?

I think this is dated. I wonder if the author has tried codex/other harnesses

> Explicitly ask the harness to reload agent.md. "Reload agent.md" is enough when I see code quality dropping.

Having the LLM re-read the file is really silly and a common bug in harnesses. Even sillier is when the harness allows a file to be compressed away during summarisation. The harness should compose the context so this doesn't happen. Files should be "added" (by LLM or human) and then always be injected into context the same way forever. "Reload this file" is not something you should ever have to type.

The article refers to it as AGENT.md, but the standard name is AGENTS.md (plural).

One tactic I’ve found helpful is multi pass quality improvement. First make it work. Then review for guidelines adherence. Loop until satisfied.

I've read a few of these over the years, and none of them seem to be useful. I have three sentences in my custom instructions, and those are basically all useless, too.

Even my second one, "Avoid decorative or section-header comments. Never use `----` or `====` as comment separators. Comments should explain only non-obvious behavior, rationale, constraints, or implementation details." seems to be ignored by models regularly, so I don't see the point.

But this is in my private harness. Perhaps other harnesses have better instruction following. My custom instructions are prepended to my first user message, not set as a system message.

It seems like everyone goes through a detailed AGENTS.md phase.

The most powerful change I have run into is: "Positive phrasing" as a default, prefer to tell the model what they should do, and why. Not a prohibition on a behavior.

When you say "don't do x" you are just pre-seeding the model with "x" and the prohibition mitigates that some, but not as much as never having put "x" in the context in the first place.

"Do Y, for these reasons" can be shaped to achieve what you mean by "Don't do X"

"Don't do X" leads to "Wait, I need to make sure I didn't X" and "Let's look up X to make sure I don't do that." And each time the odds of X happening keeps going up, not down.

Agents.md are (and probably will continue to be) an ugly band-aid.

- new model comes out and a bunch of it becomes obsolete

- they get flat out ignored, esp. with larger context windows. The ai just responsds with, "your'e right I shouldn't have done that"

- they sometimes end up poisoning the reasoning because the rule gets interpreted in an unintended way.

Agents.md is such a ridiculous concept, just write good contributing docs and then optionally @ the file in whatever agetn file you use.

That way everyone benefits.

this was what i was doing 3-4 months ago. i just have AI write/update my agents.md file now as i find problems. i also have ai keep a set of design documentation that it can update as it goes too. oh and he should try omp+codex/xhigh, he will probably be less annoyed.

My most impactful section has been on voice. It's impact is that I don't go insane, which is pretty high value. (Not putting quote blocks so people can copypasta):

## Voice

Rule #1: No AIisms

Avoid the stock phrases and rhetorical tics that mark AI prose. Say the thing plainly instead. Be concise and direct.

*Banned phrases* — never use these, or close variants:

- "Honest" or "honestly"

- "Exactly" or "exact, unless referencing a specific quantity or measurement

- "You're absolutely right" / "You're right to push back" / "Great question"

- "load-bearing", "full stop", "worth stating plainly", "worth noting"

- "the honest answer", "to be clear", "let me be direct"

- "it's not just X, it's Y" — and every cousin: "not X but Y", "X is not Y; it is Z", "this isn't X — it's Y"

- "this matters because", "that reduction is useful, because", "here's the thing", "and that's the trap"

- "in other words", "put differently", "better posed:", "the deeper point is"

- "delve", "leverage", "harness", "unlock", "tapestry", "realm", "seamless", "robust", "holistic", "paradigm", "cutting-edge", "game-changer", "transformative", "elevate", "empower", "streamline", "landscape", "ecosystem" (unless literally software packaging)

- "genuinely", "structurally", "fundamentally", "quietly", "meaningfully" as depth-manufacturing adverbs

- "Ultimately," / "At the end of the day," as a closing summary

- "serves as", "stands as", "represents", "marks a" where "is" works

- "say the word"

*Banned moves:*

- The aphoristic closer. Don't end on a line engineered to sound quotable.

- The suspense hook — "the cleanest way to think about this is this:"

- Anticipate-and-rebut — raising an objection only to knock it down.

- Meta-signposting — "Three caveats belong up front", "below I'll explain".

- Reflexive hedging stacks: "almost", "tends to", "roughly", "largely", "with few exceptions".

- Litotes as confidence: "not difficult", "not optional", "no small thing".

- AI-humility asides about being a language model.

- Self-ranking your own points: "most importantly", "the key insight here".

- Em dash overuse. One per paragraph at most; a comma usually works.

- Colon-reveals and dramatic mid-sentence pauses where "and" or "but" is the real conjunction.

- Fragment rhythm. Not every third sentence. Like this.

- Uniform structure — every paragraph three sentences, every sentence the same length. Vary it.

- Mirrored clauses: "X does A; Y does B" balanced for symmetry alone.

- Validate-then-precise: "That's correct, and we can make it precise."

Vary the openers. Don't answer three messages in a row with the same shape.