HERO Anti-OverDefense: A Config Block That Keeps Coding Agents on Scope

The Four Shapes of Over-Defense

The README names four recurring behaviors that coding agents produce when optimizing against blame rather than for the actual task. Their initials form the acronym HERO.

Hashing means adding checksums or fingerprints to output that does not require them. If a hash does not replace a materially more expensive operation and its result does not change between calls, it is filler. Edge cases means handling inputs that the project does not actually produce, addressed in pre-emptive code before any evidence that the edge will occur. Rubrics means inserting evaluation matrices, scoring criteria, or audit frameworks that nobody requested and that slow the work toward the real deliverable. Overbuild means constructing infrastructure, version trees for recoverable failures, or multi-stage audit loops at a scale that is disproportionate to the task.

The README is careful to say these are observed shapes, not a model of how agents are trained. The hypothesis is that the behaviors appear when a model optimizes for not being blamed, but the README calls that a hypothesis that fits observations, not an established account. Either way, naming the shapes makes it possible to say which one just happened, rather than arguing about vibes.

The changelog adds two sibling behaviors that emerged from repair work. Stalling: instead of picking a reasonable path and naming the trade-off, the agent hands back a menu of options. Defensive prose: caveats distributed through every paragraph until the work reads as an apology, and instructions confessed into the product where the deliverable itself says it does not address something the user never asked about. These siblings are addressed in the RULES.md block as of the August 2026 updates.

The RULES.md Contract and Its Structure

RULES.md is the working document. It contains the contract block in English and Chinese, along with three places where the line between appropriate verification and over-defense is genuinely hard to draw. The contract block opens with a header line followed by numbered scope rules. The block ends with a line that tells the agent to say plainly when something is correct.

The repository also contains cases/, a catalog of observed behaviors with descriptions of what was asked, what the agent did, why it was disproportionate, and what a proportionate response looks like. The README notes that you do not paste the cases directory into your config. It exists so you can quote a specific case back when an agent argues that its behavior was appropriate. The hosts/ directory lists where to paste the block for each supported agent: Claude Code, Codex, Antigravity, Copilot, Cursor, Windsurf, and Gemini CLI.

The examples/ directory holds real AGENTS.md and CLAUDE.md files that contributors wrote for their own projects and shared. The README is explicit that these are not HERO variants and not the short version. Their scope thresholds are their own. The README says to borrow the approach, not the file.

Pasting the Block into Your Agent Config

The README shows the block to paste and a one-line command that appends it without duplicating it if it is already there:

grep -qi 'scope.limits' CLAUDE.md 2>/dev/null || { printf '\n\n'; curl -sL \
  https://raw.githubusercontent.com/wanshuiyin/HERO-Anti-OverDefense/main/RULES.md \
  | awk '/^=== SCOPE LIMITS/,/^Say plainly when something is correct/'; } >> CLAUDE.md

The grep guard prevents double-appending. The curl command fetches RULES.md and extracts the contract block between the two delimiter lines. For Codex or Antigravity, swap CLAUDE.md for AGENTS.md. For GitHub Copilot, the destination is .github/copilot-instructions.md.

The README notes an important constraint: if you pasted the block before any of the changelog updates, your copy is stale. The guard that prevents double-append also prevents replacement. You must manually delete the old block between the delimiters and run the command again.

For the Chinese-language version of the block, the README points to README_CN.md.

How the Block Fades on Long Runs

The README documents a real failure mode: on long agent runs, the block stops having its intended effect. Three causes are identified, each with a different fix.

If something more specific in the config is contradicting the HERO block, repeating the block will not help. If the block is still in the config but buried under many turns of output, re-emitting it will restore its effect. If context compaction has thinned the block, re-emitting also helps. The README advises against setting an hourly timer to re-paste, because context grows with work, not with minutes. The hosts/ directory documents a hook-based approach for automated re-emission.

The changelog also notes eight examples of the block in use, two of them marked with a checkmark to indicate report-this, do-not-dismiss-it cases. These distinguish over-defense from a legitimate security concern. Rule 6 in the contract states that the block never overrides security or migration work you actually asked for.

Limitations and What HERO Does Not Do

The block binds what the agent proposes, not what it looks for. The README states this directly in the header line of the contract itself. An agent using HERO will still report genuine problems it finds; it is instructed to do so in the first line of the contract. What changes is the scope of the fix proposed, not the scope of the search.

HERO does not fix unclear task descriptions. If the request is ambiguous, the agent may still over-defend because the scope of the actual task is not defined. The block sets a ceiling on defensive additions; it does not raise the floor on task clarity.

The block does not apply to all outputs. The most recent changelog entry adds Rule 7, which bans process traces, intermediate errors, and abandoned approaches from deliverable text, but that rule is in the RULES.md block, not something HERO enforces separately.

Rule 6 in the block addresses the security boundary explicitly: the scope limits never override security or migration work you actually asked for. If the project states it has a real adversary, that project's scope wins over the HERO defaults. This prevents the block from becoming an excuse to skip legitimate input validation or cryptographic requirements in security-focused code.

The open-source repository has no issue tracker or release history. The last push was on 2026-09-09.

Compared to Writing Your Own Scope Instructions

Many developers writing a CLAUDE.md file include a section asking the agent to stay focused on the requested task. That approach works until you encounter a specific pattern you did not think to name. Over-built version trees for recoverable failures, for example, are a specific behavior that a general stay-focused instruction often fails to catch.

The advantage HERO offers is a shared vocabulary. When the cases/ catalog labels a behavior HERO-O-005, you can point at a documented example rather than describing the behavior from scratch each time. The disadvantage is that the block is maintained externally: when the block changes, you must re-paste it. The README changelog lists several updates to the block in August and September 2026, each requiring a re-paste for existing users.

For a team with specific scope rules that differ from the default, the examples/ directory shows how other contributors adapted the approach for their own projects without forking the HERO contract itself.

Editorial conclusion

HERO is the right tool when you have already observed a coding agent padding output with checksums nobody reads, pre-emptive error-handling for cases you did not ask about, or scaffolding that consumed the session before reaching the actual feature. Paste the block from RULES.md into CLAUDE.md, AGENTS.md, or the equivalent file for your host. On long runs, re-paste if the block has been buried under many turns of output. Do not use it as a substitute for clear task descriptions: it narrows defense, not ambiguity.

Frequently asked questions

Official sources

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