Overreach

Helpers, types and wrappers nobody calls

没人调用的辅助函数、类型和包装层

The agent adds speculative helpers, unused types, one-line wrappers and commented-out "reference" code. It works, but it is more to read and maintain.

Applies to: Claude Code · Cursor · Codex · Copilot agent

Symptom

`fetchUserByEmail()` that is never called, an `interface UserSnapshot` nothing uses, `persistEntity(e) { save(e) }`, blocks of commented-out old code.

Why it happens

"Agents over-build. They speculate about what helpers will be useful and leave them in" (agent-review). It catalogs AR001 dead code, AR007 phantom type, AR031 redundant abstraction and AR003 commented-out code left behind.

Example

From the agent-review taxonomy (AR001, AR031).

js

function fetchUser(id) { return db.find(id); }
function fetchUserByEmail(email) { return db.findByEmail(email); } // never called

function persistEntity(e) { save(e); } // wrapper over a single call

Copy-paste fixes

Pick the files for the agents you use. Snippets are in English so they work in any repo.

Rules

Claude Code: add to CLAUDE.md

CLAUDE.md

## No speculative code
- Every function, type, file and parameter you add must be used by this change. Delete anything that isn't.
- Don't add wrappers or abstractions that only forward a single call.
- Don't leave commented-out code "for reference"; git history is the reference.
- Don't add debug prints, TODOs or placeholder comments to finished work.

Rules

Codex, Copilot coding agent and others: add to AGENTS.md

AGENTS.md

## No speculative code
- Every function, type, file and parameter you add must be used by this change. Delete anything that isn't.
- Don't add wrappers or abstractions that only forward a single call.
- Don't leave commented-out code "for reference"; git history is the reference.
- Don't add debug prints, TODOs or placeholder comments to finished work.

Cursor rule

Cursor: project rule

.cursor/rules/speculative-dead-code.mdc

---
description: "AgentFails: Helpers, types and wrappers nobody calls"
alwaysApply: true
---

## No speculative code
- Every function, type, file and parameter you add must be used by this change. Delete anything that isn't.
- Don't add wrappers or abstractions that only forward a single call.
- Don't leave commented-out code "for reference"; git history is the reference.
- Don't add debug prints, TODOs or placeholder comments to finished work.

CI / script

Find unused exports and files (knip, JS/TS)

package.json (scripts)

{
  "scripts": {
    "check:unused": "npx knip"
  }
}

Skill

Fresh-context review skill (subagent reviews the diff, not the chat)

Follows the habit Anthropic describes in its code-review post: verify first, then have a subagent review the diff with fresh context. Named review-diff to avoid clashing with built-in or popular /code-review skills.

.claude/skills/review-diff/SKILL.md

---
name: review-diff
description: Review the current diff with fresh context before a PR. Use after /verify passes.
---

# Review the diff

Start a subagent that has NOT seen this conversation. Give it only:
- the original request (one paragraph, verbatim),
- the output of `git diff origin/main...HEAD`,
- the names of the test/build commands.

Ask it to report, with file:line for each finding:
1. **Wrong feature**: does the diff do what the request asked? Quote the request line each change serves.
2. **Bugs**: logic errors, missing edge cases (empty, null, boundary), unhandled errors,
   unawaited promises, invented APIs or packages, swallowed exceptions.
3. **Overreach**: changes no request line needs (refactors, renames, formatting, dependency or
   config edits, public API changes, weakened tests).
4. **Evidence gaps**: claims in the PR description that no command output supports.

Then fix real findings, or list them under "Known issues" in the PR. Do not argue with the reviewer
in the PR text; either fix or explain in one line.

Sources and credit

Improve this pattern on GitHub Hit this and the fix didn't work? Tell us