Coding agents are good at reading code. They're bad at knowing why the code is like that.
The why is usually somewhere else. A ticket where someone explained the edge case. A PR comment saying "we tried this, it broke billing". A Slack thread where the team picked Postgres over Mongo. The agent never sees any of it, so it "simplifies" the weird condition, or brings back the library you removed last month.
This isn't a hunch. Oliver Zehentleitner ran 20 fresh agent sessions on the same codebase with the same request: simplify a retry wrapper. With no recorded reason, 7 of 10 suggested the change that had already been rejected. With one written-down reason in the repo, none did. (his write-up)
CLAUDE.md and AGENTS.md help, but they're a file the model can choose to skip, and nobody keeps them current.
What I built
align-cli is a free, open-source CLI. It pulls the decisions out of where they already live (git history, ADRs, CLAUDE.md and AGENTS.md, PRs, and if you connect them, Jira, Linear, Notion, Slack and others) into a graph on your machine. Then, before your agent edits a file, it checks the change against those decisions. If the edit rewrites lines a decision wrote, it stops and asks you.
Try it in a few seconds, nothing installed, no account, no API key:
npx @aligndottech/cli demo
On your own repo:
npm install -g @aligndottech/cli
align
It plugs into Claude Code, Codex and Cursor, or runs as its own agent with your key or a local model. The graph is one SQLite file in ~/.align. Imports are read-only.
Where it falls short today
- Telling "this decision replaced that one" from "these two conflict" needs an AI key. Without one, related decisions just show up as related.
- The edit check is most battle-tested in Claude Code.
- It can't know a decision is out of date until someone makes the newer one. A lot of the devs I've talked to this week are fighting that same problem.
It's MIT and on GitHub: https://github.com/aligndottech/align-cli
Try it and tell me what breaks. I read every issue.
Top comments (0)