My coding agent kept re-asking questions I'd already answered. So I made CI fail.

hematenergi — Mon, 19 Oct 2026 05:00:16 +0000

Here's the pattern, in its simplest form. On Monday you tell your agent: no email sign-up — most of your users don't have an email address, so it's phone numbers.

On Thursday a fresh session opens with: "Before I start — should sign-up use email, or a phone number?"

Nobody did anything wrong. The decision was made, and the reasoning was good. It just lived in a chat window that no longer existed. The new session read the code, saw nothing about email, and did the reasonable thing: it asked. Sometimes it didn't ask, and just built the version I'd already rejected.

If you work with coding agents every day, you've probably started typing a little speech at the top of every session. It's a small shop. Sign-up is by phone. Don't touch the price code, we fixed that bug twice. Checkout is stuck because I haven't decided what a failed payment shows. You forget a different piece each time, and the piece you forget is the one that breaks.

The fix isn't a smarter agent. It's a file.

I'm a frontend and mobile engineer. Most of my week is React and React Native apps in production, and lately a lot of side work driven by Claude Code and Codex. What I wanted was simple: the last five minutes of a session should produce a file, not a memory.

That became Fragment. It's not a tool that runs anything. It's a handful of plain files in your repo:

docs/AGENT-PROTOCOL.md   the rules. one file. every agent and human reads this one
CLAUDE.md / AGENTS.md    three lines each, pointing there. never a second copy
docs/STATE.md            the board. read first, written last
scripts/docs-check.sh    red when any of the above stops being true

STATE.md has a section called "Decisions already made — do not ask again." That's where "phone, not email, because most users don't have one" goes. The next session reads it before it speaks.

Files alone decay in a week

I've tried the "just keep a notes file" approach. It works for about five days. Then one session forgets to update it, the next one trusts a stale board, and you're back to the speech.

So the part that matters isn't the folder layout. It's the guard. docs-check.sh fails CI when:

a session changed documents and left no trace in the log,
a link stopped resolving or a document isn't indexed,
the board hasn't moved in a week,
a piece of work claims done with an unticked box and no recorded command.

It knows nothing about your code or your language. It only checks that the story stays true. Repo-specific rules go in a local file the shared guard sources, so updating the guard never touches them.

What actually happened when someone else used it

Fragment was extracted from a private repo, not designed first. Two people, two operating systems, two different agents, 25 commits in 18 hours. Two things surprised me:

The guard caught a real incident 74 minutes after it was wired into CI. A file was renamed through the GitHub web UI. Perfectly reasonable housekeeping, but the rename broke three rules at once: a dangling index link, an unlisted file, a skipped session log. CI went red within minutes. Nobody was careless; a web UI just can't see an index it doesn't know exists.

The second person adopted the ritual without being taught it. All seven of their commits had the same three-file shape: index, board, the actual work. No shared session, no reminders. They read the same protocol file and converged on the same move.

What it doesn't prove

I'd rather say this up front, because a case study that only flatters itself is marketing:

n=2. Both production repos are run by me.
Concurrency above two people is untested. Those two took turns.
Nothing here shows Fragment preventing bugs. It prevents lost context and re-argued decisions. Tests and review still decide whether the code is correct.

The full working, with commit SHAs, is in CASE-STUDY.md.

Try it

In Claude Code:

npx skills add hematenergi/fragment --skill fragment

Or paste the install prompt from the site into whatever agent you already use. The first run of the guard will fail. That's the feature: it's your adoption checklist. Work down the list until it's green.

If you try it and it breaks, I want to hear where.