Round-tripping: parse, then print

A rendered markdown editor does not keep your text. It parses the file into a document tree (headings, paragraphs, lists, tables), shows you that tree, and on save prints the tree back out as markdown. The printer has its own opinions: which list marker to use, how wide table columns should be, whether to escape a bracket, what a line ending is. Anything the parser did not keep, the printer cannot restore.

This is called round-tripping, and it is lossy by design. Markdown has many spellings for the same structure; a tree stores one meaning, so the printer picks one spelling. Yours was not the one it picked.

What gets rewritten

What you wrote	What comes back	Why it matters in a steering file
`- item` and `+ item`	`* item`	Diff noise on every list in the file
`1. 1. 1.` or `7)`	`1. 2. 3.`	Rules that reference step numbers drift
Table cells padded by hand	Every column re-padded	Whole table shows as changed; the one edited cell is buried
`> [!CAUTION]`	`> \[!CAUTION]`	The alert stops rendering; a warning to the agent becomes a plain quote
`[^note]`, `@docs/file.md`	`\[^note]`, `\@docs/file.md`	An escaped import is no longer an import
`<!-- reviewer: check RPO -->`	Deleted	Comments are how humans talk to each other inside agent files
`<finding severity="high">`	Stripped or escaped	Structured tags that tools parse are gone
CRLF line endings, UTF-8 BOM	LF, BOM removed	Every line changed in git when the repository stores CRLF; Windows tooling that expects the BOM breaks
Frontmatter `---`	A horizontal rule, or a heading named `title:`	The file is no longer a valid skill or rule

We measured this on six report files. Every serialising engine changed 7 to 100% of lines on a save with no edits, and several deleted content. The numbers are on the benchmark page.

Source editors do it too, more quietly

A plain-text editor keeps your text, so it is mostly safe. Mostly. Editors that detect the file's line ending (VS Code and most code editors) keep a uniformly CRLF file and write nothing when you have not edited. The damage shows up elsewhere: mixed-ending files (common when text is pasted between tools) are normalised to one ending on save, so every line in the minority region changes; and editor components left at default settings do worse (CodeMirror 6 with defaults turns a CRLF file into LF on save, every line changed in a repository that stores CRLF). Some editors also add a final newline, strip trailing spaces (which are hard line breaks in markdown), or convert tabs.

Agents are editors too. When Claude Code, Cursor or Codex writes a file, it writes what it holds in memory: LF endings, no BOM, its own list markers. A steering file that an agent "improved" often comes back with the same forty-line diff.

Why it matters more for steering files

Review is the whole point. CLAUDE.md, AGENTS.md and SKILL.md are instructions. A reviewer needs to see the two lines that changed the behaviour, not the two hundred that changed spelling.
Machines read them. An escaped @import, a broken frontmatter fence or a stripped tag changes what the agent does, silently.
They are edited in turns. You, a colleague, the agent. Each rewrite by a different tool compounds the noise until nobody reads the diffs.

How to stop it

Use an editor that saves byte-clean. This is what the AsItIs desktop app, now in development, is built to do: it computes the edits you made as byte ranges and splices only those into the original bytes. Untouched bytes are never decoded and re-encoded, so line endings, BOM, padding, escapes and comments survive exactly. A save with no edits is byte-identical, every time, and CI enforces it.
Pin line endings in the repository. A .gitattributes line such as *.md text eol=lf (or eol=crlf) makes git normalise on checkout, so at least the noise is consistent. It does not stop reformatting.
Put a guard in front of the agent. The AsItIs plugin adds an optional hook that warns before, or in deny mode blocks, a write that would change a markdown file's line endings or BOM, and tells the agent to retry with the file's conventions.
Diff what the agent did, not what it printed. When an agent rewrites a file you have open, the AsItIs app shows what changed since you last looked and lets you keep or revert it.

Test your editor

Two commands tell you whether a save was clean:

# Before editing
shasum -a 256 CLAUDE.md
# After a save with no edits: the hash must be identical.

# After a real edit
git diff --stat CLAUDE.md
# The line count should match the lines you touched.

If the hash changes on a no-edit save, the editor is rewriting the file. That is the behaviour to fix.

Check your file

To see a file's line endings, byte order mark, final newline and any invalid bytes, before and after a save, drop it into the steering file checker. A dropped file is read byte for byte; nothing is uploaded.

Open the steering file checker

To check every steering file in a project from inside Claude Code, including links, @imports and what loads every session, install the free AsItIs plugin. It is read-only and makes no network calls.

claude plugin marketplace add Katta041/asitis-agent-tools
claude plugin install asitis@asitis

About the plugin Source on GitHub

MIT licensed. A star on GitHub helps other people find it.

If the rewrite came from Claude Code rather than your editor, see why did Claude Code rewrite my whole file. Related: CLAUDE.md best practices, is my SKILL.md valid.

Why did my editor change my CLAUDE.md?