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; 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. Most editors normalise line endings when they load the file and write back their own on save. Open a CRLF file, change one word, save: every line now ends in LF, and git shows the whole file changed. Mixed-ending files (common when text is pasted between tools) get flattened the same way. 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. AsItIs 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, AsItIs shows what changed since you last looked and lets you keep or revert it.

Check your own file

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.