HERO-Anti-OverDefense: a paste-in contract for coding agents that over-defend

The failure HERO names: an agent optimising for not being blamed

The README opens with a sentence that most people who have driven a coding agent will recognise: you asked for a feature, and it built a fortress around the feature and never got to the feature. The repository's own framing is that these shapes look like an agent optimising for not being blamed rather than for the work being good, and it labels that as a hypothesis that fits what the authors observed, not an established account of how these models are trained. That hedge is worth keeping in mind, because it is the difference between a diagnostic vocabulary and a claim about training objectives.

The vocabulary is the deliverable. HERO stands for Hashing, Edge cases, Rubrics, Overbuild, described as the four shapes coding agents over-defend in. Naming them, the README argues, makes it possible to say which one just happened instead of arguing about vibes. That is a smaller promise than it sounds, and a more useful one: the value is in having four words to point at during a review, not in a theory of why the model did it.

The intended audience is anyone who writes a config file for an agent and has watched output drift toward defensiveness. The repository states there is nothing to install, which is accurate in the sense that it is Markdown you copy. It is not accurate in the sense that there is no setup work at all: you still have to decide which host you are pasting into and where that host reads its instructions from.

What is actually in the repository, and what you paste

The layout is four directories plus a licence. RULES.md holds the contract in English and Chinese, and the README says it also covers the three places the line is genuinely hard to draw. cases/ is a catalogue of observed behaviours, each entry recording what was asked, what the agent did, why it is disproportionate, and what proportionate looks like. The README is explicit that you do not paste cases/ in: it is what you quote back when the agent argues. hosts/ documents where to paste the block for Claude Code, Codex, Antigravity, Copilot, Cursor, Windsurf and Gemini CLI. examples/ holds real AGENTS.md and CLAUDE.md files that contributors wrote for their own projects, with a warning that these are not HERO variants and not the short version, and that their thresholds are theirs. Borrow the approach, not the file, is the instruction.

There is also a short version of the block, referenced from RULES.md, described as half the size. That matters for anyone running a host with a tight instruction budget, though the README does not state what is cut.

The separation between the contract and the case catalogue is the most interesting design decision here. A rules file that only asserts rules invites the agent to negotiate. A rules file plus a catalogue of dated, specific incidents gives you evidence to paste back when the agent explains why this particular case really did need the extra layer. Whether that works in practice depends on the agent, and the repository does not claim to have measured it.

The nine rules, the siblings, and the press-release principle

The changelog is the best documentation of what the block currently contains, because the authors only log changes that alter what you should do. Working backwards from the entries: rule 9 bans process traces, spelling out that intermediate errors, abandoned approaches and AI-assistance markers are not content. Rule 8 covers momentum, instructing the agent that when several options are reasonable it should pick one and note the tradeoff rather than hand back a menu. Rule 7 says deliverable text is not a defense transcript, and gained the press-release principle in the 2026-09-03 entry: lead with the strongest result, explain an unfavourable number that is a tradeoff as one, state plainly one that is not, and keep it in the table either way rather than narrating it as a defeat. Rule 6 states that the contract never overrides security or migration work you actually asked for, and the entry notes eight examples were added, two marked to mean report this rather than dismiss it.

Two named siblings sit alongside the four letters: defensive prose, where caveats scattered through every paragraph make the work read as an apology, and instructions confessed into the product, where telling the agent not to mention X produces the sentence we do not address X. The changelog also names stalling as a sibling.

The press-release principle is credited to a separate project, anti-defensive-writing-Skill by Adkid-Zephyr, which the entry says works the principle out in full for papers. That is a real dependency in the intellectual sense even though there is no code dependency: if you care about the writing half of this, the upstream project is where the argument lives.

Getting it running: paste, re-paste, and the staleness problem

There is no install step. The README says the repository is a short block you paste into your agent's config, and hosts/README.md is the index of where that config lives for each supported host. The supported list is Claude Code, Codex, Antigravity, Cursor, GitHub Copilot, Windsurf and Gemini CLI, described as anything that loads a config file without being asked.

The operational catch is that the block changes, and the changelog marks those changes with a re-paste instruction. Three entries carry it. The 2026-09-02 entry adds rule 8 and extends rule 7. The 2026-08-26 entry adds rule 7 and two siblings. The 2026-08-11 entry adds rule 6 and eight examples. A fourth entry on 2026-09-03 says rule 7 gains the press-release principle and tells you to re-paste it. The repository's own warning is blunt: if you pasted the block before any of the above, yours is stale.

So the real maintenance task is not installing HERO, it is noticing that HERO moved. A pasted block is a fork the moment you paste it, with no version number in the file and no mechanism described for detecting drift. The changelog is dated and the entries are short, which makes manual checking feasible, but nothing in the material suggests an automated check exists. If you maintain this across several repositories, that is several places to re-paste by hand each time a rule changes.

The fade problem, and why the repository tells you not to set a timer

The 2026-08-12 entry is marked as a limitation and is the most useful thing in the changelog. It states that the block fades on long runs, and separates three causes with different answers. If something more specific is contradicting it, repeating will not help. If it is still there but buried under hours of output, repeating helps. If compaction thinned it, re-emitting helps. The entry then warns against setting an hourly timer, on the grounds that context grows with work, not with minutes.

That distinction is the kind of thing most prompt-engineering repositories never write down, and it is the reason to read RULES.md#what-this-does-not-do before pasting rather than after. The failure mode is not that the contract is wrong, it is that a contract expressed as text competes for attention with everything else in the window, and loses differently depending on why it lost.

A hook route is mentioned in hosts/README.md as the alternative to re-pasting. The material does not describe what the hook does or which hosts support it, so treat that as something to verify in the host documentation rather than something HERO guarantees. If your runs are short, this whole section is probably irrelevant to you. If your runs are long enough that compaction fires, it is the first thing to think about, and the three-cause split is worth reading in full before you decide whether re-pasting or a hook is the right answer for your setup.

Where HERO is the wrong tool, and what it is not

The clearest boundary is rule 6: the contract never overrides security or migration work you actually asked for. If your agents spend most of their time on exactly those tasks, the block is mostly inert at best, and at worst it gives a reviewer a reason to wave away a legitimate concern. The eight examples added alongside rule 6, two of them marked to mean report this rather than dismiss it, exist precisely because the line is easy to get wrong.

The second boundary is the examples directory. The README states plainly that those AGENTS.md and CLAUDE.md files are not HERO variants, not the short version, and that their thresholds belong to their authors. Copying one wholesale means adopting someone else's calibration for your codebase, which is the opposite of what the repository is arguing for.

The third is that HERO has no enforcement. It is Markdown in a config file. An agent that ignores it produces exactly the behaviour the cases catalogue describes, and the repository's answer is to quote a case back. That is a social remedy inside a conversation, not a technical control, and it only works with an agent that will accept the correction. The README's own framing, that the shapes are real and naming them lets you say which one just happened, is honest about this: HERO gives you language, not a guarantee.

The alternative: a hook or a lint, rather than an instruction

The obvious alternative approach is to enforce the same intent mechanically rather than by asking. Instead of telling the agent not to add a hash nobody reads, you put a check in the path that fails the change. A pre-commit hook, a CI step, or a repository lint can reject the specific artefacts HERO complains about, and unlike a pasted paragraph it does not fade when the context fills up.

The difference in approach is stark. HERO intervenes before generation, shaping what the agent considers proportionate, and works on any host that loads a config file with no code to write. A hook intervenes after generation, on the artefact, and requires you to know in advance which patterns to reject. HERO can catch a shape you had not thought to write a rule for, because it is a general instruction. A hook cannot, but it also cannot be argued with, thinned by compaction, or contradicted by a more specific instruction elsewhere in the prompt.

The two are complementary rather than competing, and the repository gestures at this by mentioning a hook route in hosts/README.md. The honest reading is that HERO is the cheaper half: it costs one paste, it covers seven hosts, and it addresses the class of problem that is hardest to write a lint for, which is an agent deciding on its own that more defence is better. Where you can name the pattern precisely enough to lint it, the lint is the stronger tool.

Licence, maintenance, and who should paste this in

HERO is MIT licensed, which permits reuse and modification with the usual attribution and warranty conditions. The repository contains no code, so the licence mostly governs the text of RULES.md and the case catalogue if you copy them into your own repository. Nothing here constitutes legal advice, and if you are redistributing the block inside a commercial product, read the LICENSE file rather than this paragraph.

The maintenance cost is real but bounded. Rules changed four times between 2026-08-11 and 2026-09-03, each time with a re-paste instruction, and the last push to the repository is dated 2026-09-09. No releases have been published, so there are no version tags to pin against; the changelog dates are the only versioning signal. The examples directory is explicitly a set of third-party adaptations rather than maintained variants, so it will drift from the main block over time.

Adopt HERO if you run one of the seven listed hosts with a config file and you can point at a specific incident where the agent over-defended. Do not adopt it if you have no config file to paste into, or if rule 6 describes most of your workload. Verify three things first: that your host appears in hosts/README.md, that the hook route described there is available to you if your runs are long enough for compaction, and that the current RULES.md still contains the rules the changelog says it does, since the block has changed four times since publication and a stale paste is the default state.

Editorial conclusion

Adopt HERO if you already run Claude Code, Codex, Cursor, Copilot, Windsurf or Gemini CLI with a config file and you can point at a specific incident where the agent built the fortress instead of the feature. Do not adopt it if you have no config file to paste into, or if your agents are mostly doing the security and migration work rule 6 was written to protect. Before pasting, read RULES.md#what-this-does-not-do and the 2026-08-12 changelog entry on fade, then check whether your host is covered in hosts/README.md, because the hook route mentioned there is the only answer to compaction thinning the block.

Official sources

1. Issues
2. License: MIT
3. README
4. wanshuiyin/HERO-Anti-OverDefense on GitHub