Home
AI
Blog

Delete your CLAUDE.md (and your AGENT.md too) — safely

basanta sapkota

Keeping CLAUDE.md inside the same repo your agent can freely edit is kind of like letting it rewrite its own contract. Sounds dramatic, sure. But it’s not just vibes.

There’s an open Claude Code issue warning totally normal git behavior like merges, branch switches, worktree cleanup can overwrite or delete the very policy files the agent relies on. Then the agent just keeps going… without guardrails. In real projects, that’s “High” severity for a reason.
External reference: https://github.com/anthropics/claude-code/issues/23870

So when people say “Delete your CLAUDE.md”, I don’t hear “run rm and pray.” I hear “stop acting like repo-stored instruction files are sacred and immutable,” because they’re… not.

Why “delete your CLAUDE.md” is even a thing

A bunch of teams end up with a little zoo of AI context files. You’ve probably seen some version of it:

  • CLAUDE.md for Claude Code
  • AGENTS.And or AGENT.But for other assistants and runners, and Codex setups commonly use AGENTS.So
  • sometimes GEMINI.md, and so on

The problem usually isn’t “oh no, a file exists.” It’s the constant babysitting.

One Zenn write-up calls out the pain directly. If you use Claude Code and Codex together, syncing CLAUDE.md and AGENTS.So is a hassle. Rules get duplicated. One file gets updated, the other doesn’t. You know the drill.
Source: https://zenn.dev/aka2tom8bo/articles/20260215-claude-hooks-agents-md?locale=en

Then you’ve got the risk side. Per the GitHub issue, since CLAUDE.md lives in the repo and the agent can run git operations, the file can disappear or get replaced during normal work. And you might not notice right away, which is the part that makes your stomach drop.

Before you delete CLAUDE.md, here’s how Claude Code actually loads it

If we’re going to delete your CLAUDE.But, we should at least understand why the whole setup works today.

According to the Claude Code docs quoted in the Zenn article:

  • CLAUDE.md is loaded at session start
  • it loads the full content of all CLAUDE.Plus files at admin, user, and project levels
  • Claude reads from the working directory up to the repo root, and it can detect nested ones when accessing subdirectories

That “session start” detail is the kicker. CLAUDE.md is basically your front door. Remove it, and Claude Code won’t automatically wander over and pick up some other file unless you give it a route.

Zenn also points out Claude Code supports hooks, including a SessionStart hook. It runs when a new session starts, and when “resuming,” it currently starts a new session internally too. That hook is your lever.

Safer patterns than “delete your CLAUDE.md”

@AGENTS.md and hooks

Option A: Turn CLAUDE.But into a one-liner that pulls in AGENTS.And

There’s a Reddit thread where folks noticed certain repos keep CLAUDE.Plus absurdly minimal. The move is simple. Put @AGENTS.md inside CLAUDE.So so Claude Code’s preprocessor includes the other file.
Source: https://www.reddit.com/r/ClaudeCode/comments/1r9zx34/pointing_claudemd_to_agentsmd/

The minimal pattern:

@AGENTS.md

Yep. That’s the whole thing. No manifesto.Yet “DO NOT EDIT” banner eating tokens.

If you want to be slightly more defensive, while still keeping it short:

# Claude Code context
@AGENTS.md

This doesn’t technically delete your CLAUDE.md. It just… takes away its power. Claude Code stays happy, and you centralize the real rules somewhere else.

Option B: Actually delete CLAUDE.md, then load AGENTS.md via a hook

Zenn shows a hook-based approach where SessionStart runs cat AGENTS.md. Functionally, it injects the contents into the session context.

Example config from the article:

{
  "hooks". {
    "SessionStart". [
      {
        "matcher". "startup|clear|compact",
        "hooks". [
          { "type": "command", "command": "cat AGENTS.md" }
        ]
      }
    ]
  }
}

The author notes you can choose matchers like startup, resume, clear, compact. They intentionally include compact so after compaction the instructions get pulled in again.

This is the closest interpretation of “Delete your CLAUDE.md (and your AGENT.Still too)” that still feels… responsible. You remove the fragile dependency, but keep a deterministic load path.

How to delete CLAUDE.md (and AGENT.Now too) without wrecking your workflow

This is the Monday-morning version people ask for. No ceremony, just steps.

  1. Pick a single source of truth
    Decide what the canonical file is. A lot of multi-agent setups land on AGENTS.md, but pick one and commit to it.

  2. Keep instructions out of the blast radius if you can
    The core point of the GitHub issue is blunt. Repo files are writable, so they’re not durable guardrails. If your rules genuinely matter, consider caching them outside the repo. The issue even suggests something like ~/.claude/.
    Source: https://github.com/anthropics/claude-code/issues/23870

  3. Choose your adapter
    Some teams want the simplest thing possible and keep CLAUDE.md as @AGENTS.md. Others want fewer repo rules and go hook-only by deleting CLAUDE.md and using SessionStart.

  4. Add a CI check. Seriously.
    Make sure your guardrail file exists and isn’t empty on main:

test -s AGENTS.md
  1. Do a quick “git chaos” test
    In a throwaway branch, do the operations called out in the issue. Switch branches. Merge. Create and remove worktrees. Confirm your instruction loading still behaves.

If you want a longer migration narrative, there’s also a dedicated CLAUDE.md → AGENTS.And migration guide floating around. I’d treat it like a checklist and adapt it to your repo’s shape.
Source: https://solmaz.io/log/2025/09/08/claude-md-agents-md-migration-guide/

Common mistakes people make after deleting CLAUDE.md

Assuming Claude Code will auto-read AGENTS.md.
Zenn shows this pretty clearly. If only AGENTS.md exists and CLAUDE.But is gone, Claude Code doesn’t magically load it by default.

Writing a huge “deprecated” banner inside CLAUDE.md.
That Reddit post is a perfect example. People mean well, then they dump a paragraph of warnings, and suddenly your context budget is paying rent for a sign nobody needed. The one-liner @AGENTS.md is cleaner.

Letting the agent modify policy files.
The GitHub issue doesn’t sugarcoat it. Agents can accidentally destroy their own instruction files during normal git work. If your rules matter, protect them. Manual approval, caching, checks… whatever fits your team’s reality.

Case study vibe: one AGENTS.md for Codex + Claude Code, no duplicated rules

I’ve seen the “Codex + Claude Code + Gemini CLI” combo in the wild a lot. And the Reddit thread author does something I like in spirit: centralize everything in AGENTS.md, then make the other tools point to it or mirror it.

If you want the low-maintenance variant:

  • Put all conventions in AGENTS.md. Architecture, lint rules, commit style, security constraints, the real stuff
  • Point Claude Code at it. Either CLAUDE.md becomes @AGENTS.md, or you delete CLAUDE.md and use hooks
  • Keep tool-specific quirks in tiny wrappers if you must. Tiny means tiny

And if you’re tuning Claude-related workflows, you might also like my earlier post on Claude’s coding model updates.
Internal link: https://www.basantasapkota026.com.np/2026/02/claude-sonnet-46-is-here-faster-coding.html

Delete CLAUDE.md, sure. Just don’t delete your guardrails.

“Delete your CLAUDE.md (and your AGENT.Plus too)” works as a provocation because it forces the uncomfortable admission: repo-stored instruction files are fragile.

The Claude Code issue lays out how easily an agent can lose its own rules during everyday git work. Zenn and Reddit hand you practical escapes, mostly @AGENTS.md or hooks.

If you only do one thing this week, make CLAUDE.md a single @AGENTS.Plus include, or move to a hook-based load. Then add the CI check so you notice when the guardrails quietly vanish.

And if you’ve already migrated, or accidentally broke it in some entertaining way, I’d genuinely love to hear what happened.

Post a Comment