A team working agreement for coding agents, clause by clause
Stefan-Iulian Tesoi · · 6 min read
Five clauses cover most of it: which work may go to an agent, how agent-authored changes are labelled, who reviews them and how closely, what an agent must never touch, and who answers for a change once it merges. Write them as the team's own rules, revisit them at each retrospective, and delete any clause nobody has needed.
A team working agreement is the page of rules a team sets for itself about how work moves: when code is reviewed, what counts as finished, how people hand work over. Coding agents add a participant that reads the rules literally, follows the ones it is shown and cannot be asked afterwards what it meant.
What is a team working agreement for coding agents?
It is the team's own answer to how agent work enters, moves through and leaves the codebase, written as checkable behaviour rather than values. "Use AI responsibly" is not a clause. "Agent pull requests carry the agent label" is.
Most working agreement examples online predate agents and assume every author can be asked a question. The agent version keeps the old clauses and adds the ones that matter when the author cannot be asked. It sets the engineering team norms AI tools work inside, and it is short enough to reread at the start of a sprint.
Five clauses most teams need
Each clause below is a behaviour someone can check, with the reason it exists.
- Intake: which work may go to an agent. Only items in Ready, with acceptance criteria a test or a reviewer can check. Anything touching authentication, billing or production data needs a person to dispatch it by name. This is the definition of done read from the other end: an item with no checkable criteria cannot be finished, so it should not be started.
- Labelling: how agent changes are marked. A co-author trailer on every commit and a label on every pull request. Claude Code adds a co-author trailer by default and a setting removes it, so the agreement decides which, not the tool's defaults. Without the label, a retrospective cannot separate agent rework from human rework.
- Review: who looks, and how closely. Code review is where an agent's change first meets a person, so name the person: paths that matter get owners in a CODEOWNERS file, and branch protection requires their approval. One detail catches teams out: GitHub's CODEOWNERS documentation states that code owners are not automatically requested on draft pull requests, and several agents open drafts. The clause has to say who marks a draft ready.
- Limits: what an agent must never touch. Secrets, deploys, the shared checkout, other people's branches. Each limit should be enforced by a permission or a hook rather than requested in a file; what an agent should never be able to do has the full list.
- Accountability: who answers once it merges. The person who started the agent session. That needs every agent to run under a person's identity, not a shared token, so the record says whose agent made the change.
How does it differ from a company AI policy?
A company AI policy decides which tools and accounts are allowed and what data may never leave; a team working agreement decides how work moves inside the team once those tools are in use. The first is written once for everyone. The second is the team's, and changes every few sprints.
| Company AI policy | Team working agreement | |
|---|---|---|
| Written by | Security, legal, IT | The team that works under it |
| Covers | Approved tools, accounts, data that may never be sent, licensing | Intake, labelling, review, limits, accountability |
| Changes | Once or twice a year | At a retrospective, when a clause stops fitting |
| Enforced by | Procurement, single sign-on, contracts | Hooks, branch protection, CODEOWNERS, the ready gate |
The two fail differently. A policy with no agreement under it leaves AI usage norms for developers to each developer, so five people adopt five habits. An agreement with no policy above it can approve a tool the company has not, which is how shadow AI coding tools end up in a codebase before anyone has reviewed them.
Which clauses get ignored, and why?
The ones that depend on someone remembering them at the moment they apply. A clause stated as a principle gets applied to the case it was written about and missed on the next one.
Our own repositories show the pattern. Their instructions say the exit code is the only proof a check passed, because pnpm run ci | tail reports the exit code of tail. In September an agent chained a worktree cleanup onto a merge piped the same way. The merge failed, the pipe reported success, and the worktree was removed. The commits survived only because git branch -d refuses to delete an unmerged branch.
The clauses that held are the ones taken out of the agreement and put into a check. Several agent sessions share each checkout here, and a checkout has one branch between them, so the rule "work in your own worktree" is enforced by a hook that refuses edits and git writes in the shared checkout. Nobody has to remember it.
A clause that a tool can enforce should not stay in the agreement as a request. The agreement keeps the decisions a tool cannot make.
Laimonade takes one clause off the page the same way. A coding agent connected to it cannot mark its own item done: it reaches In Review and no tool takes it further. Laimon, the product owner agent, can close an item, and each closure is stamped as its own, so the agreement can say who may close what and the record shows who did.
Revisiting the team working agreement at each retrospective
Read it at the sprint retrospective, one clause at a time, and ask whether anything in the sprint tested it. Most of the time the answer is no, and that is fine for a sprint or two.
Three outcomes are possible for each clause:
- Keep it if it was tested and held.
- Rewrite it if it was broken because it was ambiguous, then add the case it missed.
- Delete it if nobody needed it in three sprints, or move it into a hook, a branch rule or CODEOWNERS if a tool can now hold it.
Revisiting is also how the agreement keeps up with the tools. Agent products change monthly; a clause naming one tool's default goes stale before the team notices. Teams early in a coding agent rollout should expect most clauses to change in the first two months.
Frequently asked questions
Should agent-authored pull requests be labelled?
Yes, because the label changes how the change is reviewed and makes it countable. A co-author trailer on commits and a label on the pull request let a retrospective separate agent rework from human rework, and let anyone measure later what the agents shipped. Keep the label factual: it records which tool wrote the change, not who is to blame for it.
Who signs off on the agreement?
The team that works under it, with the tech lead or engineering manager holding the document. It is not a policy for someone outside the team to approve, though it cannot contradict the company's AI policy or security rules. Every member should agree to each clause explicitly. A clause one person wrote and nobody discussed is the first one ignored.
How long should a working agreement be?
One page, usually five to ten clauses. Each clause should name a behaviour someone can check, such as "agent pull requests carry the agent label", not a value such as "use AI responsibly". Past a page it stops being read at the start of a sprint, and anything worth enforcing belongs in a hook, a branch rule or CODEOWNERS instead.