AI coding assistants for engineering teams: a rollout with review gates
A five-step rollout for Claude Code, Cursor, Copilot or Codex: shared conventions, permissions in configuration, review gates, secrets handling and delivery metrics.
An illustrative case. On a Thursday afternoon, a payments start-up in Amman is in the second week of a pilot of AI coding assistants for engineering teams. A developer asks a coding agent to fix a failing test. The agent makes the test pass by loosening its assertion, adds a debug line that logs full request bodies, and tidies imports in 40 other files on the way. One reviewer, facing a 1,900-line diff before the weekend, approves it.
On Sunday the logs hold customer phone numbers, and nobody can say which part of the change was asked for. The agent did what it was told. The team had no rules for what it may touch, how large a change may be, or who must read it, and those rules are the real work of rolling out AI coding assistants.
Our position: set shared conventions, permissions and review gates first, then add seats. The cost is a slower first two weeks, because agents stop to ask for approval more and pull requests get split. In return, every agent change arrives small, traceable to a task, and checked by someone who did not ask for it. The five steps below apply whether the team uses Claude Code, Cursor, GitHub Copilot or OpenAI Codex.
Step 1: Write the team's conventions once, in the repository
All four AI coding assistants read standing instructions from files in the repository, so conventions can sit in version control next to the code. We checked each vendor's documentation on 19 October 2026. Claude Code reads a project CLAUDE.md shared through version control, and can read AGENTS.md when no CLAUDE.md exists. OpenAI Codex reads AGENTS.md files before doing any work. Cursor keeps project rules in .cursor/rules and supports AGENTS.md. GitHub Copilot reads .github/copilot-instructions.md and AGENTS.md files.
We recommend one AGENTS.md as the single source, so four tools do not drift into four rulebooks. Keep any tool-specific file short and have it import AGENTS.md. In Claude Code that means a CLAUDE.md containing the line @AGENTS.md, because Claude Code skips AGENTS.md once a CLAUDE.md exists. Keep it under two pages. A short template:
- Build and test: the exact commands, and "run the tests before you report a task as done".
- Scope: "change only the files the task needs; no unrequested refactoring; one concern per pull request".
- Restricted areas: database migrations, payment logic, authentication and infrastructure files need a named reviewer.
- Tests: "never weaken or delete an assertion to make a test pass; explain every test you change".
- Data: "no real customer data in fixtures, logs or prompts; use the synthetic records in /fixtures".
- Language: where user-facing Arabic text lives, and that right-to-left layouts must be checked after any interface change.
One limit matters. Anthropic's Claude Code documentation says these files are context, not enforced configuration, so an agent can still ignore them. Anything that must never happen belongs in step 2 or step 3.
Step 2: Set permissions in configuration, not in prose
Permissions decide what an agent may do without asking. Set them centrally and commit them.
- Claude Code: the Claude Code settings documentation describes shared project settings in .claude/settings.json, which the team checks into source control. It covers allow, ask and deny rules, and its own example denies reading .env files. Managed settings, which an organisation deploys, sit above every other level.
- OpenAI Codex: the Codex agent approvals and security page says the agent runs with network access turned off by default. It recommends Auto (workspace write with on-request approvals) for version-controlled folders. Keep that default and make full access an exception that a named person approves.
- Cursor: project rules in .cursor/rules are version-controlled, and on Team and Enterprise plans admins can set team rules from the dashboard and mark them as required.
- GitHub Copilot cloud agent: GitHub's documentation says the agent can push to a single branch only: the branch of the pull request it was asked to work on, or a new copilot/ branch. Its internet access is restricted. By default, GitHub Actions workflows on its pull request do not run until a user with write access approves them. A setting can let them run automatically; keep it off.
Coding agents that also reach ticketing systems, cloud consoles or production data need controls beyond what a repository can hold. Our guide to AI agent governance guardrails covers tool permissions, budgets and approvals for that case.
Step 3: Put review gates where the agent cannot skip them
Review catches what conventions and permissions miss, so enforce it in the Git platform. On GitHub, protected branch rules can require a set number of approving reviews and approval from code owners. They can also dismiss stale approvals when new commits arrive, require someone other than the pusher to approve the most recent push, and require passing status checks. On another Git platform, look for the equivalent settings before the pilot starts.
For Copilot cloud agent, GitHub's risks and mitigations page adds a useful default: the user who asked the agent to create a pull request cannot approve it. We recommend the same rule for every tool. Whoever prompted the agent is the author of the change, not its reviewer.
| Type of agent change | Gate we recommend |
|---|---|
| Documentation, tests, small fixes | One reviewer who did not prompt the agent, plus passing CI |
| Business logic | Independent reviewer, passing CI, and a linked task that states what was asked |
| Authentication, payments, personal data, migrations | Code-owner approval, a security check in CI, and a description written by a person |
| New dependencies or infrastructure | Code-owner approval, a dependency scan, and the infrastructure plan attached |
| Agent instruction files and permission settings | Tech lead approval |
Add one team rule that no platform enforces: a pull request a reviewer cannot read in about 20 minutes goes back to be split. That rule alone would have stopped the Thursday pull request above.
Step 4: Keep secrets and real data out of the agent's reach
An agent with shell access can read what the developer's account can read. Three layers help reduce exposure:
- Block reads. Deny rules for .env files, key stores and cloud credential folders, set in each tool's settings where it offers them (Claude Code's deny rules, for example) and committed with the repository.
- Block pushes. GitHub's push protection blocks pushes that contain secrets; push protection set at repository level is off by default and requires GitHub Secret Protection to be enabled. Turn it on before the pilot, not after the first leak.
- Use synthetic data. Fixtures, seed scripts and prompts use made-up records. A health-tech team in Riyadh, for example, can keep a generated patient dataset in the repository so nobody pastes a real record into a prompt.
If a key ever reached an agent session, a commit or a log, rotate it; deleting the line does not remove it from history. For apps that colleagues outside engineering built with AI tools, our vibe coding security checklist runs the same secrets checks from the outside.
Step 5: Measure delivery, not lines of code
Lines written by an agent show how much was typed, not whether the team ships better software. We recommend a baseline from the four weeks before the pilot and delivery metrics the team already understands. DORA's guide to software delivery metrics (last updated 5 January 2026) lists five. Two matter most here. Change fail rate is the share of deployments that need immediate intervention. Deployment rework rate is the share of unplanned deployments caused by a production incident.
Track these next to them, split into agent-assisted and other pull requests:
- median pull request size and time to first review;
- pull requests reverted or reopened within 14 days;
- secrets stopped by deny rules or push protection, read as a training signal rather than a score;
- a five-question developer survey every two weeks: where the agent saved time, and where it cost time.
If change fail rate climbs while throughput climbs, pause new seats and tighten step 3 first.
Two illustrative rollouts in Jordan and the Gulf
Illustrative: a 15-developer software house in Amman. It builds client portals with mixed Arabic and English interfaces and has no separate security team. It starts Claude Code with six volunteers, one shared AGENTS.md, committed deny rules and code-owner approval on authentication code. If the week-three numbers show agent pull requests being reopened for broken right-to-left layouts, the team adds an RTL rule to AGENTS.md and a screenshot check to CI.
Illustrative: the in-house team of a retail group in Riyadh. Developers already use Copilot in the editor and some prefer Cursor. Instead of forcing one tool, the tech lead standardises the rules. Both tools read one AGENTS.md, Cursor team rules are marked as required, and Copilot cloud agent is limited to tests and documentation for the first month. Business logic opens to agents once their pull requests are reverted no more than the team's own.
How to start with AI coding assistants in one team
Pick one team, one repository and four weeks. Write AGENTS.md in week one, commit permissions and branch rules before the first agent pull request, and review the numbers with the team in week four. Our Engineering Team AI Enablement service (ET3) rolls out Cursor, Claude Code, Codex or Copilot with shared conventions, permissions, review gates and secrets handling. The coding agents page shows where it fits, and the Enablement Lab covers the rest of the organisation. Our Engineering AI Bootcamps and community events in Amman (AH5) focus on coding agents and agentic engineering. If you are unsure where to begin, the free AI Exposure Scan is a 45-minute conversation that ends in a written next step.
Frequently asked questions
Which AI coding assistant is best for an engineering team?
There is no single answer. Claude Code, Cursor, GitHub Copilot and OpenAI Codex all read instruction files from the repository and offer permission settings, so choose by where your code is hosted, the admin and data controls you need, and how your developers prefer to work. Pilot one or two tools on one repository for four weeks with the same rules and metrics, then decide on evidence.
Should a coding agent be allowed to approve or merge its own pull requests?
No. Treat the agent and the person who prompted it as the author, and require approval from someone else before merging. GitHub's Copilot cloud agent already prevents the user who asked it to create a pull request from approving it. Apply the same rule to every tool through protected branch settings, with code-owner approval for authentication, payments and personal data.
How do we stop AI coding assistants from leaking secrets?
Use three layers. Deny reads of .env files and credential folders in each tool's settings where the tool supports it, and commit those settings. Turn on secret push protection in your Git platform so commits containing keys are blocked. Use synthetic data in fixtures and prompts. If a key ever appears in a session, commit or log, rotate it, because deleting the line does not remove it from history.
How do we measure whether coding agents are helping?
Take a baseline from the four weeks before the pilot, then compare agent-assisted and other pull requests. Use delivery metrics such as DORA's change fail rate and deployment rework rate, plus pull request size, time to first review and the share of changes reverted within 14 days. Lines of code generated is not a useful measure of quality.
Do AGENTS.md or CLAUDE.md files enforce rules on the agent?
No. Anthropic's Claude Code documentation describes these files as context, not enforced configuration, so an agent can still deviate from them. Use them for conventions such as test commands, scope and naming. Anything that must never happen, such as reading secrets or merging without review, belongs in permission settings and protected branch rules that the tool and Git platform enforce.
Get new insights by email
One email when we publish something useful. No spam; leave any time.
Services in this article
Related lab: Enablement Lab ↗
