TL;DR
Engineers see AI tools touch files nobody asked about, refactor working code and produce changes too large to review, and many teams still rely on judgment plus pull-request review. Set a short list of written agreements instead: scope, size, tests, an author who can explain the change, limits for unattended agents, and owned instruction files. Hold each one with a script, a named person or a record, and agree how it changes. Review then becomes the last safeguard, not the only one.
In this article
8 min read
A team needs five or six written agreements, each tied to a problem it has actually seen, and each with a stated way of being held: a check that runs on every change, a named person who judges it, or a record that shows it happened. Most teams find the same short list: keep a change to its task, keep it small enough to read, bring tests with behaviour changes, make sure the author can explain it, decide where an agent may work unattended, and treat the shared AI instruction files as code. The last agreement is about how the list itself changes.
Pull-request review was never meant to be the only safeguard
In January 2026 an engineer on Reddit’s r/EngineeringManagers forum asked managers whether they set any explicit rules for Copilot, Cursor or Claude, or relied on “use your judgment” plus pull-request review. The worry was specific: tools touching files nobody asked about, refactoring code that worked, and changing behaviour in ways that only show up later. Two months earlier, a developer asked on Hacker News how small teams use these tools, after finding that generated chunks were too big to review and collaborate on once they joined a startup.
Review struggles with exactly those cases. In Google’s study of its own code review (Sadowski et al., ICSE-SEIP 2018), the median change modified 24 lines and about 90% touched fewer than 10 files. Reviewers worked with small changes. Google’s public guidance on small changes says they are reviewed more quickly and more thoroughly, and that a reviewer may reject a change simply for being too large. DORA’s page on working in small batches (last updated 8 December 2025) adds that this discipline matters more with AI assistants, because they generate large blocks of code that are hard to review, test and integrate.
The replies on the Reddit thread show where teams start: authors must be able to explain every part of their change, refactors go in a separate pull request, and behaviour changes come with tests. Those are agreements. The gap is that most of them still live only in a reviewer’s head.
Six agreements worth writing down
Each agreement below answers one of the problems in those questions. A team should adopt only the ones it needs, word them in its own terms and set its own numbers.
Comparison
| Agreement | Problem it prevents | How it is held |
|---|---|---|
| A change does what its task asks; refactors travel separately | Unrequested edits and drive-by refactors | Reviewer judges; a check can flag files outside the expected paths |
| A change stays under an agreed size, or is split or agreed in advance | Diffs too large to read in one sitting | Check on lines and files changed, with a recorded exception |
| A behaviour change arrives with a test that fails without it | Subtle behaviour changes nobody tested | Check that tests changed; reviewer judges whether they test the right thing |
| The author can explain every part and states which tools helped | Changes their own author cannot defend | Pull-request template and trailer recorded; reviewer asks |
| Agents run unattended only in agreed areas, and a named person owns each agent pull request | Agent work nobody feels responsible for | Tool permissions and branch rules; owner named on the pull request |
| Shared AI instruction files are reviewed like code, by a named owner | Rules that drift without anyone noticing | Required review from the file’s owner |
The fourth row borrows from public projects. The Linux kernel’s guidance on AI coding assistants (documentation for 7.3.0-rc6, read 9 October 2026) says an AI agent must not add a Signed-off-by tag, that the human submitter takes full responsibility for the contribution, and that AI-assisted work should carry an Assisted-by tag in a fixed format. The format is what makes it useful to a team: a script can see whether the tag is there.
Sort every agreement into a check, a person or a record
This step turns a list into working agreements. For each one, ask whether a script can decide it from the change alone, without judgment. If it can, make it a check. If it needs judgment, name the person who makes it. If neither applies but you still need to know it happened, make it a record attached to the change.
Most agreements split across lanes. A script can count lines and files and confirm that a test file changed alongside the code, but only a person can tell whether a test exercises the behaviour that moved. A script can confirm that an Assisted-by trailer is present, but not that it is honest. Writing that split down tells reviewers what they no longer need to look for and what remains theirs. The case for turning deterministic rules into executable checks applies here; what the team adds is the decision about which of its own agreements belong in which lane.
The holders already exist in most toolchains. GitHub rulesets and protected branches can require status checks and reviews before a merge, and with a CODEOWNERS file and “Require review from Code Owners”, changes to a path need approval from the people who own it. Point that at AGENTS.md, CLAUDE.md or .github/copilot-instructions.md and the sixth agreement holds itself. Some coding tools can also act before an edit: Claude Code’s hooks include a PreToolUse event that runs before a tool call and can block it. Checks at merge apply to every author, whichever tool wrote the code; checks before an edit depend on the tool.
Unattended agents need one more line than the rest: which directories, branches and commands an agent may use without a person watching, and who answers for its pull requests. A change to a payment flow and a change to a copy string rarely deserve the same freedom, which is the argument for risk lanes rather than one rule for every change.
Decide in advance how an agreement changes
AI tools change monthly, so an agreement that cannot be changed is soon ignored. DORA’s page on a clear and communicated AI stance (last updated 12 January 2026) names both failure modes: the policy written once and never revisited, and the “whiplash” of changing it so often that teams cannot adapt.
QEMU shows a change route written into the agreement itself. Its code provenance policy declines contributions believed to include AI-generated content, and invites anyone who wants an exception to propose it on the developers’ mailing list; agreed exceptions are listed in the policy. Whatever you think of the rule, everyone knows how to challenge it.
A team version can be small. The agreements live in the repository, next to the code. A named owner, often the tech lead, approves changes through the same review as code, because, as one Hacker News question put it, adding a rule has more impact than adding a line of code. The team looks at them on a fixed rhythm, such as each retrospective, and changes one when there is evidence: a check that keeps flagging good changes, the same review comment appearing three times, or a new tool that ignores the instruction file.
The AI Delivery Programme is built around this sequence. Over five weeks on one application, the team writes down its conventions and exceptions in week 1 (Align), decides in week 2 (Prepare) which of them a script can test and which need a person, implements the testable ones as checks validated against agreed passing and failing examples, and practises the agreements on real backlog work in weeks 3 and 4 (Practise), adjusting them where the work shows they need to change. The open-source framework underneath, Paqad, runs each change through ordered stages (planning, specification, development, review, checks, documentation sync) and keeps a record per change, so the team can see whether the agreed steps ran. That record shows the method ran, not that the code is correct. Its checkpoints can block an edit on Claude Code and Codex CLI; Gemini CLI records without blocking, and on other coding tools the workflow is advisory (current as of paqad-ai 1.90.0). And which agreements help most has not yet been tested on a customer team. Sales wait for Spine, the shared team view, which is being finished; no dates or fees are published. If review is still your team’s only safeguard, fix this for your team: the first step is a fit conversation about your codebase and the tools you use.
Frequently Asked Questions
What working agreements should a team set for AI-assisted development?
Start with the problems you see and write one agreement per problem, usually five or six. A company AI policy is a different document: it says which tools and data are allowed. Team agreements say how a change is made and checked, whichever approved tool made it.
Which problems should our agreements address first?
Look at the last month of merged pull requests and their review comments, and count what recurs: oversized changes, edits outside the task, missing tests, or authors who could not answer a question about their own change. Write agreements for the two or three that recur most. A problem seen once is a review comment, not yet an agreement.
Which agreements are worth their cost, and which only slow people down?
An agreement earns its cost when the problem it prevents is expensive to find later, such as a behaviour change without a test. It costs more than it saves when it has no exception route: a size ceiling that blocks a generated migration everyone has already discussed, for example. Write the exception into the agreement, such as “larger changes are agreed with the reviewer first”, and record when it is used.
How do we keep the agreements from becoming a document nobody reads?
Keep them to one page in the repository, mirror the relevant ones in the instruction files that coding tools load, such as AGENTS.md, and repeat them as fields in the pull-request template. Instruction files guide an agent but do not enforce anything, so every agreement a script can decide should also run as a check, and stop depending on reminders.
How will we know the agreements are followed and help, and who updates them?
Checks report their own results, so track how often each one fails and how often it is overridden. For human-judged agreements, have the owner read a small sample of merged pull requests each month against the list. DORA suggests also asking the team whether the expectations are clear. The tech lead or another named owner updates the list, through review, when that evidence says it should change.
