Overreach

Ignored the conventions in CLAUDE.md

无视 CLAUDE.md 里写好的约定

The code works, but it doesn't follow the conventions written in the project's rules files or visible in the surrounding code, and steps the rules require (like running certain tests) get skipped as "unnecessary".

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

Symptom

New code uses a different structure, naming or layering than its neighbours; boundaries the team set are crossed; a rule in CLAUDE.md or AGENTS.md is visibly not applied. The agent may cite the rules back to you while not following them.

Why it happens

Asked why he still uses PRs, @alexitcdev said it's to review what agents write, as they are typically "ignoring my CLAUDE.md conventions" or skipping certain tests as unnecessary. @gibbostudio finds Opus and Fable code that doesn't align with the team's fences and code style. @_maulik13 caught Opus drifting from the patterns the project follows; when questioned, it found its own hypothesis was wrong and simplified the code. @WinterSoldier92 describes extra markdown files as more instructions for the agent to "cherry pick from and ignore". Long rules files compete with the task for attention, and nothing enforces them unless a check does. In the same thread, @Spanky4thewin suggests short rules with the must-dos at the top plus a Stop hook so skipping isn't possible.

Example

Illustrative.

text

CLAUDE.md:  "Data access goes through src/repo/*. Run `npm run test:integration` for DB changes."
Agent diff: src/routes/orders.ts  -> raw SQL query inline in the route handler
Agent:      "Integration tests aren't necessary for this small change. Done ✅"

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

## Follow the project's rules files
- Before editing, read CLAUDE.md / AGENTS.md / .cursor/rules and at least one neighbouring file that
  does something similar. Follow their structure, naming and layering.
- In your summary, list which project rules applied to this change and how you followed each one.
- Required commands in the rules files are not optional. If you think one is unnecessary, ask;
  don't skip it.
- If following a rule is impossible, say so explicitly instead of quietly deviating.

Rules

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

AGENTS.md

## Follow the project's rules files
- Before editing, read CLAUDE.md / AGENTS.md / .cursor/rules and at least one neighbouring file that
  does something similar. Follow their structure, naming and layering.
- In your summary, list which project rules applied to this change and how you followed each one.
- Required commands in the rules files are not optional. If you think one is unnecessary, ask;
  don't skip it.
- If following a rule is impossible, say so explicitly instead of quietly deviating.

Cursor rule

Cursor: project rule

.cursor/rules/ignored-project-conventions.mdc

---
description: "AgentFails: Ignored the conventions in CLAUDE.md"
alwaysApply: true
---

## Follow the project's rules files
- Before editing, read CLAUDE.md / AGENTS.md / .cursor/rules and at least one neighbouring file that
  does something similar. Follow their structure, naming and layering.
- In your summary, list which project rules applied to this change and how you followed each one.
- Required commands in the rules files are not optional. If you think one is unnecessary, ask;
  don't skip it.
- If following a rule is impossible, say so explicitly instead of quietly deviating.

Hook

Claude Code Stop hook: don't let the agent finish while tests fail

A Stop hook that exits with code 2 keeps Claude working and shows it stderr. The stop_hook_active check stops it from looping forever. Swap `npm test` for your test command.

.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json,sys,subprocess; d=json.load(sys.stdin); sys.exit(0) if d.get('stop_hook_active') else None; r=subprocess.run('npm test --silent', shell=True, capture_output=True, text=True); sys.stderr.write('Tests are failing. Fix them (without weakening them) before stopping:\\n'+r.stdout[-3000:]+r.stderr[-2000:]) if r.returncode else None; sys.exit(2 if r.returncode else 0)\""
          }
        ]
      }
    ]
  }
}

Skill

Shared /verify skill for Claude Code

Commit it to the repo so the whole team (and every agent session) runs the same checks. Replace the commands with your project's real ones.

.claude/skills/verify/SKILL.md

---
name: verify
description: Verify the current change before calling it done. Use before every commit, PR, or "done" message.
---

# Verify

Run every step and paste the real output. Never summarize a step you did not run.

1. **Scope**: run `git diff --stat` and `git status --short`. For every changed file, say which part
   of the request needs it. Any file you cannot justify gets reverted, or listed under
   "Unrequested changes" for the user to decide.
2. **Build and types**: `npm run build` (or the project's build command).
3. **Tests**: `npm test`. Report pass/fail counts. If a test was edited, skipped or deleted,
   say so explicitly with the reason.
4. **Behavior**: exercise the changed behavior once for real (a curl, a CLI run, a screenshot)
   and show what happened.
5. **Report** in this format:
   - Requested: <one line>
   - Changed files: <list, each with its reason>
   - Checks run: <command -> result>
   - Not done / unsure: <list, or "none">

Sources and credit

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