How Does AI Coding Scale Across a Team? Build Standards That Survive People, Tools, and Time

Monday morning: the repository has four versions of the truth

A team uses the same repository in four different ways:

• one developer works in Cursor and keeps important rules in .cursor/rules/;
• another uses Codex and follows AGENTS.md;
• a third uses Claude Code and maintains a long CLAUDE.md;
• a mobile developer copied the build commands into a personal prompt six weeks ago.

Then the project changes its test command and introduces a new package boundary. The repository documentation is updated, but two AI instruction files and the personal prompt are not.

The next three pull requests are all plausible:

• one runs a command that no longer covers the changed package;
• one imports an internal module that the architecture no longer permits;
• one updates code correctly but leaves the project documentation describing the old behavior.

The problem is not that the team chose the wrong model. The problem is that it has no shared engineering contract. Each tool is operating from a different snapshot of the project.

This article builds that contract. By the end, you will have a practical system for:

1. keeping one source of truth while supporting several AI Coding tools;
2. giving teammates different autonomy according to evidence, not job title;
3. passing work safely between people, sessions, and tools;
4. turning important natural-language rules into executable checks;
5. making project documentation improve whenever the code or workflow changes.

The objective is not to make every developer use AI in the same way. It is to make every accepted change satisfy the same project contract.

1. The operating model: one project contract, five implementation layers

Many teams begin with one large AGENTS.md. That is useful, but it is not a team system. A sustainable system has five distinct layers.

This separation matters because each layer fails differently.

• A project document can be stale.
• An Agent can misunderstand a clear instruction.
• A task can be underspecified.
• A test can miss an important behavior.
• A review comment can disappear without improving the system.

Do not ask one file to solve all five problems.

A useful test for the design

Imagine the team replaces every AI Coding tool next month. What should survive?

• architecture and product decisions;
• build and test procedures;
• task acceptance criteria;
• security and permission boundaries;
• verification evidence;
• lessons from previous failures.

Those assets belong in the repository and delivery system, not inside one vendor’s memory.

2. Build the repository as the team’s shared memory

Start with a boring, discoverable structure. A medium-sized repository might use:

repository/
├── README.md
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
├── .cursor/
│   └── rules/
│       └── 00-project-contract.mdc
├── docs/
│   ├── project-map.md
│   ├── development.md
│   ├── testing.md
│   ├── architecture/
│   │   ├── boundaries.md
│   │   └── decisions/
│   └── ai/
│       ├── tool-compatibility.md
│       ├── task-template.md
│       ├── review-checklist.md
│       └── evals/
├── .github/
│   ├── CODEOWNERS
│   └── pull_request_template.md
└── scripts/
    └── verify-ai-contract.sh

The names can differ. The responsibilities should not.

AGENTS.md is an index, not an encyclopedia

The root instruction file should contain the information that changes an Agent’s behavior on almost every task:

# Repository working contract

## Start here
- Read `docs/project-map.md` to locate the owning module.
- Read the nearest `AGENTS.md` before editing a nested package.
- Read `docs/architecture/boundaries.md` before crossing package boundaries.

## Required workflow
1. Restate the task outcome, allowed scope, and unknowns.
2. Reproduce or characterize current behavior before changing code.
3. Make the smallest coherent change.
4. Run the focused checks, then the owning package checks.
5. Report changed files, commands, results, and remaining risk.

## Commands
- Install: `<verified-install-command>`
- Focused test: `<verified-focused-test-command>`
- Package verification: `<verified-package-command>`
- Repository checks: `<verified-repository-command>`

## Boundaries
- Do not change public contracts, stored data, permissions, dependencies, or release configuration implicitly.
- Do not use production data or credentials.
- Stop when the task conflicts with an architecture decision or requires another owner's approval.

## Definition of done
- Acceptance criteria are met.
- Required checks pass.
- Documentation changes with behavior, commands, architecture, or operator workflow.
- The handoff states what was not verified.

Detailed architecture does not belong in this file. Neither do hundreds of lint rules already enforced by tooling.

A June 2026 study of 100 popular repositories found recurring instruction-file smells including duplicated lint rules, context bloat, misplaced procedures, stale references, and conflicting instructions. It is early research, not a universal law, but it supports a practical rule: keep standing guidance concise and point to owned documents and executable checks instead of copying them (Configuration Smells in AGENTS.md Files).

Give every durable document four properties

An important document should make these visible:

Owner: @team-or-role
Applies to: apps/web, apps/mobile
Last verified: 2026-08-17
Verify with: ./scripts/check-project-docs.sh

Last verified is not a decorative timestamp. It should mean somebody checked the document against the current repository or ran the listed evidence.

3. Decide what belongs where

Most documentation sprawl begins when every useful sentence is copied into every AI file. Use this placement rule instead.

Ask one question whenever a rule is proposed:

If a different tool or a new teammate performs the same task, must this still be true?

If yes, it belongs in the project contract or an executable control. If no, it may belong in an adapter or personal configuration.

4. Support several tools without maintaining several projects

Tools do not load instructions in the same way.

• Codex discovers layered AGENTS.md files from the project root toward the working directory and applies nearer guidance later in the chain (official Codex AGENTS.md guide).
• Claude Code uses CLAUDE.md; its current documentation explicitly recommends importing AGENTS.md when a repository already uses that shared file (Claude Code memory documentation).
• Gemini CLI uses hierarchical GEMINI.md files by default, supports imports, and can configure AGENTS.md as a context filename (Gemini CLI context documentation).
• Cursor supports project Rules and AGENTS.md, but exact behavior can differ between editor and CLI surfaces; GitHub Copilot similarly publishes a support matrix because its chat, coding Agent, code review, IDE, and CLI surfaces do not all load the same instruction types (Cursor Rules, GitHub custom-instruction support).

The conclusion is not “pick the best filename.” It is:

Maintain one canonical project contract and make every tool adapter thin, explicit, and testable.

Example: thin adapters

CLAUDE.md can import the shared contract and add only Claude-specific behavior:

@AGENTS.md

## Claude Code adapter
- Use plan mode before a change spans more than one owned package.
- Project facts and definition of done come from `AGENTS.md` and `docs/`.
- Do not store team decisions only in auto memory; propose a repository document change.

Gemini CLI can load the shared filename through project settings:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

A Cursor project rule can remain deliberately small:

---
description: Load the canonical project contract before implementation
alwaysApply: true
---

Read `AGENTS.md` and the linked project documents before editing.
Cursor-specific workflows may be defined here; project requirements may not.

Do not generate four full copies unless a tool provides no import or shared-file mechanism. If copying is unavoidable, generate the adapters from one source and fail CI when generated files drift.

Maintain a compatibility record

Create docs/ai/tool-compatibility.md:

Recheck this file when a tool version, execution surface, instruction format, or project adapter changes. “The vendor supports AGENTS.md” is not enough evidence that the exact surface your team uses loaded the expected files.

5. Give every task the same portable contract

A teammate should be able to move a task from Cursor to Codex, or hand it to another person using Claude Code, without reconstructing the goal from a chat transcript.

Use a task envelope like this:

# Change request

## Outcome
What should a user, operator, or developer observe when this is complete?

## Context to read
- `AGENTS.md`
- `<owning-module-document>`
- `<relevant-decision-or-spec>`

## In scope
- named behavior
- allowed packages or components

## Out of scope
- contracts, platforms, migrations, or cleanup not included in this task

## Acceptance evidence
- observable behavior
- focused automated check
- owning-package regression checks
- documentation that must remain accurate

## Autonomy lane
- read only / plan only / branch implementation / expert-approved implementation

## Stop conditions
- missing decision
- boundary crossing
- sensitive data or permission required
- unexpected unrelated failure

## Handoff
- base commit and resulting commit
- files changed
- commands and actual results
- decisions made
- unresolved risks and recommended next owner

The task envelope is deliberately tool-neutral. A product manager, designer, Web developer, service developer, or App developer can read the same outcome while each discipline supplies its own verification evidence.

One example: change a product term without breaking contracts

Suppose the product changes the visible term Project to Workspace.

A poor task says:

Replace Project with Workspace everywhere.

A safe task contract says:

Outcome
Web and App users see “Workspace” in navigation, empty states, and validation messages.

In scope
- user-visible copy in apps/web and apps/mobile
- snapshots or UI tests for changed states
- the product glossary and screenshots in user documentation

Out of scope
- public API fields such as project_id
- database names, analytics event names, and migration work
- unrelated internal class names

Acceptance
- no user-visible “Project” remains in the named flows
- Web and App focused checks pass
- public contracts are unchanged
- glossary and affected user docs describe “Workspace”

This contract works across disciplines because it separates the user outcome from implementation boundaries. It also makes the dangerous shortcut—global search and replace—obviously invalid.

6. Match autonomy to demonstrated capability, task risk, and tool familiarity

“Junior developers may not use Agents” is too crude. “Everyone may use every feature” is unsafe.

Treat capability as a matrix, not a permanent rank. The same person may be independent in a familiar Web package, supervised in an unfamiliar App package, and plan-only when using a new tool.

Qualify a teammate on each workflow, not each product tour

Before granting branch-writing autonomy with a new tool, ask the teammate to complete four observable checks:

1. show which project instructions the tool loaded;
2. locate the correct owner and verification command for a sample task;
3. complete one bounded change without crossing scope;
4. produce a handoff that another person can reproduce.

If any step fails, improve the repository or adapter as well as coaching the person. An onboarding failure often reveals a documentation failure.

Personal settings cannot weaken the project contract

Allow personal preferences for explanation depth, keyboard workflow, local aliases, or preferred planning style. Do not allow a local file to silently override:

• required tests;
• architecture boundaries;
• data and permission rules;
• review requirements;
• definition of done.

When a tool merges global, project, and local instructions, verify the effective result. Do not assume “project rules win” unless the product documents and your test confirm it.

7. Convert important prose into executable guardrails

Instruction files are context. They are not enforcement. Claude Code’s official documentation says this explicitly, and GitHub warns that custom instructions may not be followed identically every time. Current research describes the same gap as “passive instructions” that need executable controls (Claude Code memory, GitHub response customization, ContextCov, 2026).

For every important sentence in AGENTS.md, ask whether it needs an executable twin.

GitHub protected branches can require successful status checks and approving reviews, while CODEOWNERS can request and require the responsible team’s review for matching paths (protected branches, CODEOWNERS). Other hosting systems offer equivalent controls.

Use action lanes, not one global permission switch

The OWASP Top 10 for Agentic Applications 2026 highlights tool misuse, identity and privilege abuse, unexpected execution, and supply-chain risks. The practical response is narrower tools, narrower identities, isolated execution, and human checkpoints for high-impact actions—not a longer prompt saying “be careful.”

8. Make documentation change with the project

“Please keep the docs updated” is not an operating process. Define update triggers.

Add these questions to the pull-request template:

## Project contract impact
- [ ] Behavior or acceptance changed; affected docs are updated.
- [ ] Commands, package boundaries, or ownership changed; project guidance is updated.
- [ ] AI instruction files or adapters changed; supported tools were rechecked.
- [ ] No durable decision exists only in a chat transcript or personal memory.

Give AI documents owners

For example:

/AGENTS.md                       @platform-team @repo-maintainers
/CLAUDE.md                       @platform-team
/GEMINI.md                       @platform-team
/.cursor/rules/                  @platform-team
/docs/ai/                        @ai-practice-stewards
/docs/architecture/              @architecture-owners

The owner is responsible for correctness, not for writing every sentence. AI may draft an update, but the owner accepts the resulting project contract.

Let failures improve one durable asset

Use this review rule:

First occurrence  → fix the task and record the evidence
Repeated pattern  → identify the missing or weak system asset
System change     → update one canonical source or executable control
Verification      → rerun the smallest relevant historical case

Do not add every review comment to AGENTS.md. Choose the right asset:

• missing project fact → project documentation;
• unclear task boundary → task template;
• deterministic violation → test or CI check;
• tool-only behavior → adapter;
• recurring procedure → Skill or script;
• model/tool regression → evaluation case.

OpenAI’s current evaluation best-practices guide recommends task-specific, continuous evaluation with logs and human calibration. For this team system, the evaluation unit should include the repository snapshot, task contract, instruction version, tool surface, permissions, commands, and review result—not only the model name.

9. How people and tools collaborate on one change

Return to the Project → Workspace change.

Step 1: one owner publishes the task contract

The issue contains the outcome, named Web and App flows, protected public contracts, required docs, and verification commands. It references a base commit.

Step 2: a less-experienced teammate performs impact mapping

Using Cursor in plan-only mode, the teammate produces:

Affected Web paths
Affected App paths
Relevant glossary and screenshots
Potential public-contract matches that must not change
Unknown owners or missing tests

No implementation begins until a maintainer confirms the map and splits the work.

Step 3: two contributors work in isolated scopes

• The Web contributor uses Codex on a Web worktree.
• The App contributor uses Claude Code on a separate branch.
• Both receive the same task contract and base commit.
• Neither edits the public API or the other’s package.

Different tools are acceptable because the contract, boundaries, and evidence are shared.

Step 4: every handoff is durable

Each contributor reports:

Task and base commit
Selected scope
Files changed
Focused and package checks with actual results
Docs updated
Decisions made
Unverified behavior and remaining risk
Resulting commit or pull request

A chat summary without a commit, diff, or reproducible command is not a handoff.

Step 5: CI and owners integrate the result

CI checks text matches in the named flows, Web and App tests, public-contract snapshots, documentation links, and adapter drift. CODEOWNERS routes Web, App, and glossary changes to the right reviewers.

Step 6: the review updates the system when necessary

Suppose both tools attempt to rename project_id. The task was clear, so the repeated mistake indicates a weak executable boundary. The team adds a contract snapshot or forbidden-diff check and saves this task as an evaluation case.

That is sustainable collaboration: a failure becomes cheaper the next time it appears.

10. Common designs that look organized but fail

11. Build the minimum useful system this week

Day 1: inventory the current truth

• list project docs and every AI instruction file;
• list supported tools and surfaces, not only vendor names;
• find duplicated, conflicting, personal-only, and stale rules;
• identify the actual commands and owners for major project areas.

Day 2: establish the canonical contract

• create or repair the project map, development guide, testing guide, and architecture boundaries;
• reduce AGENTS.md to navigation, required workflow, commands, boundaries, and definition of done;
• move task-only instructions out of permanent files.

Day 3: make tool adapters thin

• import or reference the canonical contract;
• record the exact tool surface and version;
• verify the effective instructions in each supported tool;
• remove copies that no longer have a reason to exist.

Day 4: enforce the expensive rules

• protect the default branch;
• require focused and package-level checks;
• add owners for architecture, public contracts, AI guidance, and docs;
• restrict external writes and production actions;
• turn the most costly repeated review comment into a check.

Day 5: rehearse collaboration

• let an observer map a task;
• let a bounded contributor implement one scope;
• hand the task between two different tools using the durable handoff format;
• record every missing fact, ambiguous boundary, and irreproducible command;
• improve the system before expanding autonomy.

After that, review the system when evidence triggers it—not because a quarterly “AI policy meeting” appears on the calendar.

12. Team acceptance checklist

A team AI Coding system is ready for wider use when you can answer yes to these questions.

Project truth

• A new teammate can locate owners, architecture boundaries, development commands, and verification commands.
• AGENTS.md points to canonical documents instead of copying the repository wiki.
• Durable decisions do not exist only in chat history or personal memory.

Multiple tools

• Every supported tool surface has a thin adapter or verified native path to the shared contract.
• Tool versions, instruction files, and verification dates are recorded.
• Replacing one tool would not require rewriting the project’s definition of done.

Different capability levels

• Autonomy depends on demonstrated evidence, task risk, repository familiarity, and tool familiarity.
• Stop conditions and escalation owners are explicit.
• A teammate can move between levels for different domains without stigma.

Stability

• High-impact rules have executable controls.
• Default branches, sensitive paths, external writes, and production actions are protected.
• Handoffs include a diff or commit, commands, actual results, and remaining risk.

Continuous documentation

• Pull requests ask whether behavior, commands, architecture, ownership, or tool support changed.
• AI guidance, adapters, architecture, and documentation have named owners.
• Repeated failures update the correct durable asset and rerun a relevant case.

Conclusion: standardize the contract, not the developer

A sustainable AI Coding team does not force everyone into one editor, one model, or one interaction style.

It standardizes what matters:

one project truth
+ portable task contracts
+ thin tool adapters
+ capability-appropriate autonomy
+ executable engineering controls
+ a documentation and evaluation feedback loop

This gives beginners a safe path to learn, experienced developers room to move quickly, and maintainers evidence they can review. The same person can change tools without changing the project’s definition of done. Project knowledge improves through normal engineering work instead of decaying in private prompts.

The real sign of team adoption is not that everybody uses an Agent. It is that people and Agents can change while the project remains understandable, reviewable, stable, and maintainable.

Authoritative references

The live product documentation below was rechecked on August 17, 2026. Research items are explicitly marked with their 2026 publication date.

• OpenAI Codex: Custom instructions with AGENTS.md — current layered discovery and precedence for Codex project instructions.
• Claude Code: How Claude remembers your project — CLAUDE.md, scoped rules, project versus personal memory, and importing AGENTS.md.
• Cursor: Rules — current project Rules and AGENTS.md customization surfaces.
• Gemini CLI: Provide context with GEMINI.md files — hierarchical context, imports, inspection, and configurable filenames.
• GitHub: Custom-instruction support matrix — differences among Copilot products, IDEs, review, cloud Agent, and CLI surfaces.
• GitHub: Protected branches and CODEOWNERS — enforceable checks, reviews, and ownership.
• OWASP Top 10 for Agentic Applications 2026 — current agentic risks around tools, identity, execution, and supply chains.
• OpenAI: Evaluation best practices — current guidance for task-specific, continuous evaluation with automated and human evidence.
• Configuration Smells in AGENTS.md Files, June 2026 — empirical catalog of duplicated, bloated, misplaced, stale, and conflicting repository guidance.
• ContextCov, February 2026 — research on converting passive Agent instructions into executable constraints.