My agent.md to improve LLM-assisted code quality

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.

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.

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.

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.

**Always use ASD-STE100 Simplified Technical English

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

local llm remain more in line like that.

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.

That way everyone benefits.