Editing a CLAUDE.md or AGENTS.md without losing track of changes

Checked November 2026 against Anthropic's Claude Code documentation, agents.md, Cursor's documentation and Git's manual, all linked below. Coffee isn't affiliated with any of them.

Keep the file in Git, commit changes to it on their own with a message saying why, and read the diff whenever a tool has edited it. These files are ordinary Markdown, so git diff and git log -p tell you what changed and when. The other half of keeping track is knowing which file each tool actually loads, because a change to the wrong one does nothing.

Which file gets read

AGENTS.md is an open format, described as a README for coding agents, stewarded by the Agentic AI Foundation under the Linux Foundation. It's plain Markdown with no required fields. CLAUDE.md is Claude Code's own equivalent, and Anthropic's documentation sets out how the two interact:

Reading AGENTS.md directly needs Claude Code v2.1.277 or later. Note the second row: adding a small CLAUDE.local.md for your own preferences stops Claude reading AGENTS.md for you, unless you change the Project instructions setting. That's an easy one to miss.

If you use several tools, the tidy arrangement is one shared file. Put everything in AGENTS.md, and if you also need Claude-specific instructions, make CLAUDE.md start with an import:

@AGENTS.md

## Claude Code

Anything only Claude needs goes here.

Now there's one place to edit, and one history to read.

Nested files behave differently across tools, so check before relying on them. The AGENTS.md site says the closest file to the one being edited wins. Cursor combines nested files with their parents, with the more specific taking precedence. Claude Code joins all the CLAUDE.md files it finds rather than letting one override another, and if two contradict each other, Claude may pick either.

Put it in Git and commit it alone

Project instruction files are meant to be shared through source control, and that's also what gives you the record. When you change one, commit only that:

git add AGENTS.md
git commit -m "Tell agents to run the linter before committing"

A change to an instruction can alter how a tool behaves from then on, so you'll want to find it later. Mixed in with fifty other files, you won't.

These commands answer the questions you'll actually have:

git diff --word-diff CLAUDE.md
git log -p -- CLAUDE.md
git blame CLAUDE.md

The first shows what's changed since your last commit. The second, git log -p, shows every past change to the file. And git blame shows which commit last changed each line, though it says nothing about lines that were removed. For those, use git log -p.

Private instructions need the opposite treatment. CLAUDE.local.md is for preferences that are only yours, and Anthropic's docs say to add it to .gitignore. ~/.claude/CLAUDE.md applies to all your projects and lives outside any repository, so nothing tracks its changes unless you make it so.

Know what the tool writes for itself

This is where most lost changes actually go. When you tell Claude to remember something, Claude Code saves it to auto memory, which is separate from CLAUDE.md. By default those notes live under ~/.claude/projects/, outside your repository, so they won't show in its Git history. To get an instruction into the file, say so ("add this to CLAUDE.md") or edit it yourself. Running /memory lists your instruction files and opens the one you choose, and it also leads to the auto memory folder, so you can see what's been saved.

Other commands to know:

• /init creates a starting CLAUDE.md. If one already exists, it suggests improvements instead of overwriting it.
• /doctor prompt-audit looks for outdated instructions, references to things that don't exist, and files that contradict each other. It reports proposed edits and changes nothing until you ask. It needs v2.1.283 or later.

Commit before you run anything that might write to these files. If you do let a tool edit one, review it the same way you'd review a note, and if one change is wrong, undo only that one.

Keep it short enough to read

A file you can read in a minute is a file whose changes you'll notice. Anthropic suggests under 200 lines per CLAUDE.md, since longer files use more context and reduce how well they're followed. It also suggests:

• Concrete, checkable instructions, such as "Run npm test before committing" rather than "test your changes".
• Headers and bullets instead of dense paragraphs.
• Moving what applies to only part of a project into rules scoped to those paths, in .claude/rules/.
• Imports for tidiness, keeping in mind that imported files still load and still use context.

To leave a note for people without spending context on it, use a block-level HTML comment. Claude Code strips those before the file reaches Claude:

<!-- Kept for a reason: ask before removing. -->
Always run migrations on a copy first.

Remember what these files are, too. Anthropic's docs describe CLAUDE.md as context, not enforced configuration. If something must always happen or must never happen, use a permission rule or a hook. Editing the file carefully won't turn a request into a rule.

Editing these files in Coffee

Any text editor works, and Git does the tracking either way. Coffee is one option on a Mac, with one trap worth knowing about first.

Open the file from Finder, or with Open…, and keep your project out of Coffee's library. Inside the library, a note's title is its file name, and editing the title heading renames the file. A CLAUDE.md whose top heading you change would be renamed to match, and Claude Code would stop finding it. A file opened from outside the library keeps its name, whatever its heading says. A file in a hidden folder such as .claude/ doesn't show in the library's list in any case.

Opened that way, Coffee watches the file's folder, so an edit by a tool shows up as changes since you last read it, each with Keep and Undo. As ever, it needs a first read to compare with, and it compares whole lines. It keeps no shared record, which is what Git is for. If you'd like to send one changed file as a pull request without the command line, Propose change does that.

Questions

Should I use CLAUDE.md or AGENTS.md?

If you use more than one tool, keep the content in AGENTS.md. Add a CLAUDE.md with @AGENTS.md only if you need Claude-specific instructions. If you only use Claude Code, CLAUDE.md alone is fine.

Why did Claude ignore what I added?

Check it loaded: run /context all and look under Memory files. Also look for a contradicting instruction elsewhere, and make the wording more specific. Anthropic's docs say there's no guarantee of strict compliance.

Where did the thing I told Claude to remember go?

Probably to auto memory, not CLAUDE.md. Run /memory to see both. To put it in the file, ask for that directly or edit the file yourself.

Does AGENTS.md need any special format?

No. Its site says it's standard Markdown, with no required fields, and agents read whatever text you give them.

How do I see who changed a line?

Use git blame on the file, once it's in Git. It names the commit, author and date for each line. An AI tool's edit shows as whoever committed it, so make commit messages say where a change came from.