We Have Code Review. We Need Intent Review.

Last month I watched Claude Code confidently rebuild a Redis queue that my team had abandoned three weeks earlier.

The repo had redis.go, TODOs scattered around, and redis configured in docker-compose.yml. Claude saw all of this and reasonably wanted to finish what looked like a half-built feature.

The problem: we'd already decided not to use Redis. Replication lag had been causing duplicate billing events, and the team made the call to rip it out. That decision lived in a Slack thread, a couple of PR comments, and the heads of three engineers.

Code search saw the Redis files. It couldn't see the decision.

This is a specific failure mode I keep running into, and the more I look at it, the more I think we're missing an entire layer of review in our AI-assisted workflows.

We have code review. We need intent review.

The Problem Isn't What the AI Wrote

Most discussions about AI coding focus on the output: did it produce good code? Was the architecture sound? Are the tests passing?

But the failure mode I'm describing is different. The agent isn't writing bad code. It's writing reasonable code based on the wrong historical premise.

Think about how a senior engineer behaves when they touch unfamiliar code. They don't just read the function signature and start typing. They:

• Check the commit history to understand why it was written
• Look for related PRs that touched this area
• Ask the team in Slack: "anyone know why we did it this way?"
• Pause before changing patterns that look intentional but unfamiliar

This isn't because senior engineers are smarter than AI agents. It's because they have humility toward unfamiliar code. They've been burned enough times to know that what looks like dead weight is sometimes load-bearing, and what looks like a half-built feature is sometimes an explicitly abandoned approach.

AI agents don't have this humility. They're optimized for agreement, not interrogation. If the code looks half-built, the agreeable thing to do is finish it. If a TODO looks reasonable, the agreeable thing is to address it. The agent extends rather than questions.

This works fine for greenfield code. It breaks badly in any codebase older than a few weeks.

Why Existing Solutions Don't Solve This

When I describe this problem, people usually point to existing tools. Each of these has a real role, but none of them fully addresses what I'm calling intent review.

AGENTS.md / CLAUDE.md — These work for the not-todos you can anticipate. You can write "don't use Redis" once you know Redis is dead. But what about the decision you'll make next week? Or the one your colleague made yesterday? AGENTS.md only covers the past you've already documented. New decisions don't write themselves into the file.

ADRs / RFCs — Heavy enough that most teams stop maintaining them after the first quarter. Even when maintained, they're written for human readers, not for agents querying contextually before a code change.

Wiki / Notion / Confluence — Documentation drifts from code. The wiki page from six months ago still says "we use Redis." Agents don't naturally query wikis the way they query code, and even if they did, they'd find a free-form page that doesn't structure decisions vs. risks vs. rejected alternatives.

PR descriptions — Buried in GitHub. Searchable in theory, ignored in practice. Agents don't proactively pull PR descriptions for related code regions.

Agent harnesses with built-in memory — Tools like jcode capture session memory automatically and inject it into future sessions. This works within the harness. But the moment you switch agents, change tools, or have a teammate who uses a different setup, the memory is gone. You're locked into the harness.

Each of these is a partial answer to a real problem. None of them gives an agent reliable, structured access to your team's actual historical decisions before it touches unfamiliar code.

Code Review vs. Intent Review

Code review answers: "Is this change well-implemented?"

Reviewers look at the diff. They check correctness, style, test coverage. They might catch a bug or suggest a better pattern. This is essential, and it works.

But code review is a poor place to ask: "Is this change well-conceived in light of what the team already decided?"

That question requires the reviewer to know the entire decision history of the codebase. To remember why a particular pattern exists. To recall that Redis was abandoned three weeks ago for replication reasons. Most reviewers don't have this context. Even the original author often doesn't, six months later.

Intent review is a different kind of review. It happens before code is written, not after. It asks:

• What does the team already know about this area?
• What decisions were made, and why?
• What was considered and rejected, and for what reasons?
• What risks were identified that haven't been mitigated yet?
• What architectural claims are load-bearing?

For a human engineer, this kind of review happens informally—a quick Slack message, a glance at the commit log, a 30-second conversation with the person who wrote the original code.

For an AI agent, it doesn't happen at all. There's no equivalent to "let me ask the team." The agent reads the current state of the code and infers from there. The historical signal isn't accessible.

What Intent Review Looks Like

Intent review needs three properties to actually work:

1. Decisions need to be structured, not free-form.

A wiki page that says "we decided to use JWT" is fine for human reading. An agent needs to know: what was decided, what was rejected, why, what risks were identified, what files this touches, what subsystems it affects, what claims about the architecture were load-bearing.

Free-form prose hides this structure. An agent has to re-parse the entire document every time. Structured records let agents query specifically: "show me decisions affecting auth that mention session handling."

2. Decisions need to live near the code, not in a separate system.

Wiki pages drift from code. Notion pages get forgotten. Slack threads get buried. The only thing that reliably stays connected to code is git itself.

If decisions live in git, they survive everything that affects code: clones, forks, branches, time. Six months from now when the agent is touching this area, the decision is right there—same place as the code, fetched together, queryable in the same workflow.

3. The query must happen automatically, before the change.

If the agent has to be reminded "check the wiki first," it won't. If decisions live in a sidebar that requires explicit lookup, agents skip it. The query has to be part of the agent's normal workflow—the same way it grep's for symbol definitions before refactoring.

This is the hard part. An agent that already runs grep and read_file before editing should also run something like intent_context before editing. The friction of looking up decisions has to be lower than the friction of guessing.

What I'm Building

I've been working on this with a tool called Mainline. It records team intents and decisions as structured records in git itself, where any agent can query them before making changes.

Architecturally:

refs/heads/_mainline/actor/<id>   # per-developer append-only log
refs/notes/mainline/intents       # links between commits and intents

Each sealed intent contains:

• summary.what and summary.why
• decisions[] with rationale and rejected alternatives
• risks[] with mitigations
• fingerprint covering touched files, subsystems, and architectural claims

Before an agent changes code, it runs something like mainline context auth and pulls structured records about past decisions affecting the auth area. After completing work, it seals a new intent with what was decided, what was considered, and what risks remain.

A few design choices that took me a while to settle on:

Process-based CLI, not a daemon. I considered a background daemon that would auto-capture activity. I looked at how that played out in similar tools (git-ai's daemon hits issues with macOS sleep, socket handling, zombie processes). Git itself is already a battle-tested protocol for this kind of thing. I didn't need to reinvent it.

Intent-level, not line-level. Line-level attribution (which file, which line, by whom) sounds appealing but is fragile. A formatter run, a git mv, a copy-paste, an --amend—any of these can break line-level tracking. Intent is task-level. Text transformations don't change the semantic meaning of "we decided X for reason Y."

Explicit seal, not automatic capture. Auto-capture sounds magical, but it produces a lot of noise: every keystroke and tool call gets recorded, and querying that later is harder than it looks. Explicit sealing has friction—the agent has to actively summarize what happened—but the resulting record is high-signal.

Append-only and immutable. Sealed intents can't be edited, only superseded. The original "what we thought at the time" stays intact. If we changed our minds, we add a new intent that supersedes the old one. The history of how thinking evolved is preserved, not overwritten.

The tool is open source (Apache 2.0) and currently in private beta. It's at mainline.sh if you want to look. I'm not pitching here—the point of this post is the idea, not the tool. If you build a different implementation of intent review that works better, I'd be genuinely interested in seeing it.

Where This Fits

There's a lot of energy right now in what people are calling compound engineering—the idea that each completed task should make the next one easier through accumulated learning. Tools like learning loops in Claude Code, the work Every is doing, the Ralph Loop pattern, all gesture at the same insight: AI coding workflows should accumulate knowledge instead of resetting every session.

I think compound engineering is heading the right direction, but it's missing a foundational layer. Most current implementations of "compound" rely on:

• .claude/ files that humans maintain manually
• Plain-text plans committed to the repo
• Vector memory inside an agent harness
• Retrospectives that update config files

These work, but they share a property: the knowledge is captured somewhere adjacent to git, not inside it. Switch tools, switch agents, switch teammates, and the compounding stops.

Intent review—done right—is the git-native foundation that compound engineering needs. If decisions live in git refs and notes, then any agent, any tool, any teammate can participate in the compounding. The knowledge isn't trapped in one harness.

What I'm Still Figuring Out

I've been dogfooding Mainline for about a month with a small team. Some things have surprised me.

The friction isn't where I expected. I thought engineers would resist writing structured seal records. They mostly didn't—it turns out the agent does the writing, and engineers just review and adjust. The actual friction is teaching agents when to seal. Too eager and you get a flood of trivial intents. Too conservative and important decisions go unrecorded.

The benefit shows up later than I expected. The first week, mainline feels like overhead. By week three, you start hitting moments where you ask "why did we do this?" and the answer is right there in the intent log. By week six, agents start using past intents as context without being asked. The compounding is real, but it's not immediate.

Cross-actor coordination is harder than single-user. When it's just me, sealed intents are mostly notes-to-self. When two engineers work in the same codebase, intents become a coordination protocol. We had to add explicit conflict detection (when two intents claim incompatible architectural changes) because otherwise we'd discover the conflict at PR review time, which is too late.

I don't think I've solved intent review. I think I've built one specific implementation of an idea that the field needs to develop further. Different teams will need different implementations. The structured-records-in-git approach is one path; others will work too.

What This Means for AI Coding

Code review is fundamental to software engineering. We don't ship code without review, even when the author is excellent. We don't trust raw output, even from senior engineers. We have a layer of structured human attention applied to every change.

AI agents are now writing significant fractions of new code in many teams. They're not getting reviewed less—if anything, the review burden is going up, because reviewing AI-generated code is often more cognitively demanding than reviewing human code. The reviewer can't ask the AI "why did you do it this way?" the same way they'd ask a colleague. The intent isn't legible.

Intent review isn't a replacement for code review. It's a complementary layer. Code review catches bugs in implementation. Intent review catches bugs in framing—the agent solving the wrong problem, finishing abandoned work, contradicting recent decisions, ignoring identified risks.

Without intent review, every code review has to do double duty: check the implementation and verify the framing. Most of the time, framing checks fail silently. The reviewer doesn't know that Redis was abandoned three weeks ago, or that this auth pattern was deliberately avoided, or that this risk was already identified and mitigated elsewhere. They approve the code, and the broken framing ships.

I don't think this is a problem we can solve with better prompts or larger context windows or more capable models. It's a structural problem about where institutional knowledge lives. Right now it lives in heads, Slack, and PR comments—places agents don't reliably look. We need it to live somewhere agents do reliably look. For most teams, that means git itself.

We have code review. We need intent review.

If you're seeing this same failure mode in your team, I'd be curious to hear how you're handling it—or whether you've decided it's not a real problem. Either is useful to know.

Mainline is at mainline.sh. Source on GitHub. Apache 2.0. Currently in private beta with a small group. If you have a 5+ person team using AI coding heavily and want to try it, reach out.