Boffin Tries Per-Edit Agent Constraints

Boffin is MicSm's open-source JavaScript project for steering AI coding agents with constraints that match the file being edited. It deals with a familiar failure mode: ask for a tiny fix, get a broad refactor that still passes tests but changes too much. The useful takeaway is simple: the best way to review agent work is to make the review shape visible before the edit, not only after it. Boffin is a concrete way to implement code review habits for ai-generated code without turning every task into a repo-wide policy lecture.

Boffin is a staff-engineer control layer for coding agents: it selects relevant architectural constraints before an edit and requires verification after the edit. The project says it is not another static AGENTS.md-style rules file, not a prompt pack, and not a linter. As of July 26, 2026, the GitHub repo had 28 stars, an MIT license, mostly JavaScript code, and a README example that frames the tool around review safety rather than speed. That framing is why it landed as more than another agent wrapper.

Look at the edit before the prompt

Boffin's core idea is narrower than most agent instruction systems. Instead of giving the agent one giant block of repository guidance, it routes the constraints that apply to the exact file the agent is about to touch.

That matters because most real repositories are not governed by one rule. A storage engine file might care about allocator boundaries. A UI component might care about accessibility and event ownership. A generated file might need the opposite instruction: do not edit this by hand.

The trap is believing that more context always helps. Claude Code, Anthropic's coding agent, Claude, Anysphere's AI code editor, and OpenAI's Codex can all carry instructions, but a long universal instruction blob often becomes ambient noise. Boffin's bet is that relevance beats volume.

A small example:

Path: src/query/planner/join_order.cpp
Task: change one predicate edge case
Relevant constraints:
- Do not change join enumeration strategy.
- Keep cost-model behavior unchanged unless the test names it.
- Add or update a regression test for the failing shape.
- Verify with the smallest planner test target first, then the wider suite if touched code escapes the planner.

That is the staff-engineer move. It does not tell the agent to be careful. It names the boundary.

Why developers argued about it

The Hacker News discussion circled a fair question: is this materially different from a CONTRIBUTING.md, CONTEXT.md, or AGENTS.md file with better instructions?

The charitable answer is yes, if the routing is real. A static rules file says what the repo values. Boffin tries to choose which values matter for this edit, then pair them with verification. That makes it closer to a review preflight than a memory file.

The skeptical answer is also fair. If the project becomes only a thin prompt convention, then a disciplined repo note can get you most of the benefit. You still need accurate constraints, current tests, and reviewers who notice when the agent complied with the wrong thing.

The best objection in the thread was basically: can an AI slop plugin make AI less sloppy? My read: not by magic. But a small constraint router can reduce one specific kind of slop, where the agent expands the problem because it lacks the local architecture map.

For readers tracking the related training topic, this is the interesting part. The tool is not trying to replace review. It is trying to move part of review earlier, into the agent's working context.

Compare Boffin with rules files and CI gates

Boffin sits between repo memory and enforcement. That makes it easy to misunderstand.

Verdict: Boffin wins when the hard part is local architectural judgment before an edit. Static instructions win when the rule is durable and broad, like naming, formatting, or dependency conventions. CI wins when the rule can be made deterministic. Good repos will use all three, but they should not pretend they solve the same problem.

A useful mental model: repo memory says how we usually work, Boffin says what matters here, and CI says whether the result met a checkable bar.

Try it on one risky path, not the whole repo

The safest way to try Boffin is to pick one path where agents often over-edit. Do not start with the whole codebase. Pick the place where reviewers already say things like, please do not touch that layer, or this test passing is not enough.

For Claude Code users, a good first experiment is a local slash-command workflow around a narrow change:

/agent-small-fix path=src/billing/proration.ts issue=rounding-edge-case

Before editing:
- Load only the constraints for src/billing/proration.ts.
- State the intended edit boundary in 3 bullets.
- Name the smallest verification command.

After editing:
- Show changed files.
- Show verification run.
- Explain any line-count growth over 2x the requested change.

That is not a Boffin command. It is the shape of a safe experiment you can run around Boffin's idea in Claude Code or another agent surface.

This is also where the phrase implement code review habits for ai-generated code becomes practical. The habit is not just review the diff. It is ask the agent to declare the boundary, make the smallest change, and return evidence that matches the risk of the touched file.

When is Boffin overkill? A small script repo with ten files probably does not need a constraint router. A mature C++, data, or payments codebase with sharp subsystem boundaries might.

Copy this Boffin-style review checklist

Use this as a light review receipt for one agent edit. It is intentionally short. If it gets long, the agent will skim it too.

## Agent edit review receipt

Change request:
- Requested fix:
- Target path:
- Expected size of change:

Before edit:
- Relevant constraints loaded for this path:
- Boundary the agent agreed not to cross:
- Smallest useful verification command:

After edit:
- Files changed:
- Lines added / removed:
- Verification run and result:
- Any behavior intentionally unchanged:
- Any larger refactor deferred:

Reviewer check:
- Does the diff match the requested scope?
- Did the agent follow the path-specific constraints?
- Is the verification proportional to the risk?
- Would this pass review if a human wrote it without the chat transcript?

A hook boundary can make this harder to skip without making the hook too clever. For example, a Claude Code hook can require the receipt file to exist before a branch is marked ready, but it should not rewrite code or bless the diff. Keep humans responsible for judgment.

If you already use concise repository memory, keep it concise. A root CLAUDE.md can hold durable rules, while a Boffin-style layer can hold path-sensitive constraints. The failure mode is duplicating the same stale rule in three places and trusting none of them.

Common questions

• What are the best ways to implement code review habits for ai-generated code?

  Start by making the expected boundary explicit before the agent edits, then require verification evidence after it edits. A four-part receipt works well: requested scope, relevant constraints, changed files, and commands run. Boffin is interesting because it routes the constraint part per edit instead of relying only on a broad repo note.

• Is Boffin a replacement for AGENTS.md or CLAUDE.md?

  No, Boffin is not a direct replacement for durable repo instructions. The README explicitly positions it against one static block for everything, but broad memory still helps with rules that are always true. Use static memory for stable conventions and per-edit routing for files where architecture changes by path.

• Does this count as ai coding training for teams?

  Only in the narrow sense that it teaches a better review reflex. Boffin itself is a tool experiment, not a curriculum. The training value is the pattern: require the agent to name the local constraints, keep the diff small, and prove the result with verification proportional to the change.

• Could a linter or CI job do the same thing?

  No, not fully. Linters and CI are excellent when the rule is deterministic, but they usually act after the edit and cannot capture all design intent. Boffin's useful claim is earlier intervention: put architectural constraints into the agent's context before it chooses the shape of the change.

• When should I skip Boffin?

  Skip it when your repo is small, your conventions are simple, or your agents are mostly writing isolated tests and scripts. The overhead pays off when wrong edits are subtle: subsystem boundaries, performance-sensitive paths, generated code, compatibility layers, or files where passing tests can still hide a bad architectural move.

Best ways to use this research

• Best for: Engineers evaluating agentic coding tools in repos where small fixes often become broad rewrites.
• Best first artifact: A one-page review receipt tied to one risky path, not a repo-wide process.
• Best comparison angle: Compare Boffin against static instructions and CI by timing: before edit, during context selection, and after verification.
• Best Claude Code experiment: Wrap one narrow slash command around path constraints, expected diff size, and the smallest verification command.
• Best caution: Do not treat routed constraints as proof. They are inputs to review, not review itself.

For an adjacent read on the same project, see Boffin Routes Constraints for Coding Agents.

Further reading

• boffin — source
• Claude Code — overview
• Claude — Agent
• Model Context Protocol — specification

Try one constrained edit

Pick one file where agents tend to wander, write five constraints for that path, and run one small fix through the receipt above. If the resulting diff is smaller and easier to review, Boffin's idea earned another experiment.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.