AI coding assistants are excellent at refactoring. They're also excellent at deleting the comment that explains why you chose 37 instead of 60. Here are four inline markers that protect institutional knowledge from well-meaning automation.
When an AI agent refactors your code, it optimizes for what it can see: structure, naming, duplication. But some of the most important information in a codebase is why things are the way they are, and where else needs to change when this changes.
That information lives in comments. And comments are the first thing a tidy-up pass deletes.
We need a small vocabulary—scannable by humans, parseable by tools—that says: this comment has semantic weight. Don't touch it.
Protects a comment from cleanup passes—whether by a human refactoring, a linter, or an AI agent tidying up. It says: this exists for a reason, leave it.
Use it for empirically-tuned constants, non-obvious import orderings, workarounds for upstream bugs, or anything where the comment is load-bearing.
# keep — explains the retry count, not obvious from code RETRY_COUNT = 3 BATCH_SIZE = 50 #keep empirically tuned for rate limit
Works as a standalone comment (# keep — reason) or as an inline suffix (#keep). The reason is optional but recommended.
Marks a non-obvious decision. The code looks wrong—or at least suspicious—but it's intentional. Without the marker, the next person (or agent) will "fix" it and introduce a bug.
Named after G.K. Chesterton's principle: don't remove a fence until you understand why it was built.
# why — ALB idle timeout is 60s, 37s leaves headroom for slow responses TIMEOUT = 37 # why — append+join is 3x faster than string concat for >100 items results = [] sleep(0.2) #why drain pending escape sequences after tmux exit
Every # why is implicitly a # keep—you'd never delete a fence-explanation.
Marks a consumer—a list, mapping, or configuration that mirrors a source of truth defined elsewhere. When the source changes, this location needs to be updated too.
The format is always: # sync — <what> syncs with <source>.
# sync — handler list syncs with jobs/handlers/*.py HANDLERS = ["earnings", "filings", "news", "social"] <!-- sync — CLI tools table syncs with ~/.local/bin/ --> | Tool | Command | Description |
This is the most novel marker in the set. It creates a lightweight, grep-able dependency graph between code locations that no type system or import mechanism captures. A tool can scan for all # sync markers, check if their sources have changed, and flag drift.
The complement of # sync. Marks the authoritative definition—the one place where a value, list, or configuration is canonically defined. When you change this, you need to update its consumers.
# ssot — port assignments; consumers: servers.md, CLAUDE.md, registry.py PORTS = { "watch": 7800, "draft": 7810, "helm": 8130, }
The # ssot tag lists known consumers. The # sync tags in those consumers point back to the source. Together, they form a bidirectional link that both humans and tools can follow.
The four markers form two pairs:
| Pair | Purpose | Relationship |
|---|---|---|
#keep + #why |
Protect knowledge | #why is a specialized #keep with Chesterton's fence semantics |
#ssot + #sync |
Track dependencies | #ssot marks the source, #sync marks each consumer |
A codebase with these markers can be audited: scan for all # sync markers, check each against its source, report drift. This turns a class of subtle bugs—stale copies, forgotten consumers, config mismatch—into a scannable, automatable check.
These markers don't duplicate existing conventions. Here's how they compare to what the ecosystem already has:
The gap is clear: no convention exists for protecting inline knowledge from automated cleanup, or for creating a grep-able dependency graph between arbitrary code locations.
Add to your project's AI instructions (CLAUDE.md, .cursorrules, AGENTS.md, etc.):
## Comment Markers - `# keep` — Do not delete this comment during refactoring - `# why` — Explains a non-obvious decision. Never remove. - `# sync — X syncs with Y` — This location mirrors a source. Check for drift. - `# ssot — X; consumers: A, B` — Canonical definition. Update consumers when changed.
A simple grep finds all markers and their relationships:
# Find all sources of truth rg "# ssot" --glob '!node_modules' # Find all consumer locations rg "# sync" --glob '!node_modules' # Find Chesterton's fences rg "#\s*why" --glob '!node_modules'
| Language | Example |
|---|---|
| Python | # keep — reason or #keep |
| JS / TS | // keep — reason or //keep |
| Go / Rust / C | // keep — reason |
| HTML / Markdown | <!-- keep — reason --> |
| YAML / TOML | # keep — reason |
| CSS | /* keep — reason */ |
The keyword (keep, why, sync, ssot) appears immediately after the comment delimiter. That's the only rule.
These markers aren't about AI specifically. They're about any refactoring agent—human or machine—that operates on structure without full context. But AI agents make the problem acute because they refactor at scale, across entire codebases, in minutes.
A human might hesitate at a suspicious constant. An AI agent will normalize it to a "better" value and move on. A human might notice that two files have suspiciously similar lists. An AI agent will happily update one and leave the other stale.
The markers are cheap: four words. The protection is real: your institutional knowledge survives the next cleanup pass.
We mined 60 days of git history in one medium-sized codebase (mixed Python/Go/JS, ~200k lines, heavy AI-assisted development) and cross-referenced with the project's learning database. We looked for reverted cleanups, "fix cleanup" commits, and recorded instances where code was removed then had to be restored.
Four cases stood out—each verified against the actual git commits and each mapping cleanly to a specific marker.
#ssot — API signature cascade (17 files, immediate revert)A function call_llm was refactored to return a string instead of a result object. The change touched one file. The breakage touched seventeen—every downstream consumer that expected metadata fields on the result. Required an immediate revert across 17 files, plus creation of a parallel call_llm_rich function to safely migrate callers.
If the return type had # ssot — return type; consumers: recap.py, search.py, eval.py, ..., the refactorer would have seen the blast radius before changing anything. This is the strongest case in the set: the damage was proportional to the number of unknown consumers.
#sync — 42 TODO items silently dropped (full restoration commit)A documentation reorganization moved vision content from Markdown to HTML. The conversion silently dropped 42 TODO items, 5 status paragraphs, 15 deliverables, and cross-references to related work. Nobody noticed until a manual audit. Required a full restoration commit adding 103 lines back.
If the HTML had <!-- sync — use cases syncs with VISION.md -->, a drift check would have caught the missing content before the commit shipped.
#keep — CSS "simplification" reverts (two reverts in one week)CSS cleanup removed a border from a markdown wrapper. Reverted 2 days later. A separate CSS "simplification" commit was reverted 4 hours later—13 lines restored from a 4-line deletion. Both removed styling that looked redundant but served a visual purpose.
An inline /* keep — prevents content jump on hover */ would have made the intent visible.
#why — "dead" constant that wasn't dead (recorded in learning DB)A constant called _ITERM2_PROFILE was removed as dead code—nothing referenced it in the current codebase. It was actually scaffolding for a planned feature; the design doc referenced it, but no code did yet. This wasn't a revert (the removal stuck), but it was logged as a mistake in the project's learning database: "Prematurely removed unused constant assuming it was dead code."
A # why — reserved for profile switching (see design/iterm.md) would have stopped the deletion. This case is weaker than the others—it required knowing the planned intent, not just reading existing code—but it's the exact scenario #why is designed for.
Evidence was gathered by searching git history for revert/restore/fix patterns (git log --grep="revert" --grep="restore" --grep="fix.*cleanup"), then cross-referencing with the project's learning database for recorded instances of premature deletions. Each claim above was verified against the actual commit diff. We discarded several initially promising leads that didn't hold up to scrutiny—including a file "restore" that was actually just a type annotation fix, and a database path learning that was about proposing the wrong location, not deleting an existing file.
The evidence above comes from a single codebase. The strongest validation would be a study across public repositories, mining for patterns like:
revert.*cleanup, fix.*refactor, restore.*removedProjects with high revert-after-cleanup rates would be natural candidates for adoption. The # sync / # ssot pair could be validated by measuring how often two locations drift apart in real codebases—e.g., a README table and the code it documents.
A CI check or pre-commit hook that parses # sync markers and verifies their sources haven't changed since the consumer was last updated. This turns a convention into an enforced invariant.
Syntax highlighting for marker keywords. "Go to source" from a # sync to its # ssot. A sidebar showing all Chesterton's fences in the current file.