Every repo has lines like these. They look wrong, or pointless, and they're there for a reason nobody wrote next to them.

That used to be a mild annoyance. With coding agents it's a real problem: the agent reads the line, sees no reason, and "fixes" it.

Here are three from my own repo, what each one is protecting, and how to get the reason back without asking around.

1. provenance: false

In our CI image builds. Read cold, it looks like someone switched off a security feature.

The reason: docker/build-push-action attaches an attestation to every image by default, and AWS ECR caps how many can point at one image. Our least-changed images rebuilt to the same digest every time, the attestations piled up on it, and pushes started failing on a commit that only touched two Python files.

Remove that line and nothing breaks today. It breaks weeks later, somewhere else.

2. A hook that refuses git push

We have a guard that refuses a push when the branch has no open pull request.

The reason: pushing to a branch whose PR already merged is completely silent. The push succeeds, no CI runs, and the commit never reaches main. It happened to us five times in one day before the guard existed.

3. A CI check that bans one shell idiom

GH_TOKEN=$(gh auth token --user X) gh ... looks like the tidy one-liner. We fail the build if anyone documents it.

The reason: if that account isn't on the machine, the substitution fails quietly, the variable comes out empty, and gh runs as whichever account happens to be active. On a public repo, the wrong account doesn't error. It answers a narrower question, and we published a wrong claim off the back of it.

Getting a reason back by hand

When you hit a line like these and nothing explains it:

# who touched it, ignoring whitespace and moved code git blame -w -C -L 40,45 .github/workflows/ci.yaml # every commit that added or removed the exact string git log -S 'provenance: false' --oneline -- .github/workflows/ # the PR that commit came from gh pr list --state merged --search <commit-sha> 

Then read the PR description and whatever ticket it links. Five minutes if you're lucky. If the reasoning happened in Slack or a call, it's gone.

What I did about it

I got tired of doing that dance, and of agents skipping it entirely, so I built a CLI that does it before the agent edits. It reads decisions out of PRs, tickets, ADRs, chat and git, and when an edit touches lines that came from one, the agent sees the decision and has to check it still holds. If the edit clashes, it stops and asks.

The same prompt to Claude Code, without Align and with it

It's free and open source, and runs locally:

npx @aligndottech/cli demo 

https://github.com/aligndottech/align-cli

It doesn't catch everything yet. When I asked it about the provenance: false line, the reason wasn't in its graph, because that one lives in a rules file it doesn't read. Which is the whole point of this post: the reason has to live somewhere a person or an agent will actually look.

What's the line in your repo nobody can explain anymore?