Standardizing AI Agent Setup Across a Development Team

The Problem with Ad-Hoc Team AI Setups

When every developer on a team configures their AI coding agent independently, you get a fragmented team: different context files, different tool choices, different habits, and AI agents making contradictory decisions for different developers working on the same codebase. One developer's Claude Code knows about the Auth0 decision; another's Cursor doesn't. One generates code that follows your error pattern; another generates code that violates it.

Standardization isn't about restricting how developers use AI — it's about ensuring the shared decisions are consistently accessible to every developer's agent, regardless of which tool they prefer.

What to Standardize (and What Not To)

Standardize:

• The shared context files (AGENTS.md content, format, update process)
• The approved AI tool list (which tools are supported and have shared context)
• Code review requirements for AI-generated code
• Security constraints (which files and systems AI agents can access)
• The update process for shared context (how decisions get from individual sessions to AGENTS.md)

Leave to individual preference:

• Which specific AI coding tool to use (Claude Code vs Cursor vs Cline)
• Personal workflow habits and session management
• Model selection (which Claude model to use within Claude Code)
• Personal shortcuts and individual CLAUDE.md extensions

The test for standardization: "If this isn't consistent across the team, does it produce inconsistent code?" Yes → standardize. No → leave personal.

The Minimum Viable Standard

For most teams, the minimum viable standard is:

1. A shared AGENTS.md committed to the repository
2. A one-page AI usage guide covering approved tools and expectations
3. A PR template addition prompting context updates when architecture changes

This three-element standard costs 2–3 hours to set up, takes minutes to maintain weekly, and eliminates the most common sources of AI-generated inconsistency.

The one-page AI usage guide covers:

• Approved tools (which AI coding tools are supported and have shared context)
• Context file location and format (where AGENTS.md is, how it's structured)
• Review requirements (what to check in AI-generated code before merging)
• What to do when the AI contradicts established patterns
• How to propose updates to shared context

Distribute this as docs/ai-usage.md — keep it short, current, and linked from the main README.

Setting Up the Shared Context Foundation

Step 1: Create and commit AGENTS.md

touch AGENTS.md

Write the shared context (see Sharing AI Context Across a Development Team for content guidance). Commit and push.

git add AGENTS.md
git commit -m "feat: add shared AI agent context (AGENTS.md)"
git push

Every developer now gets shared context on their next pull.

Step 2: Tool-specific wrappers

For Claude Code users, a thin CLAUDE.md that extends AGENTS.md:

# Claude Code Context
<!-- See AGENTS.md for shared project context -->

## Claude Code-Specific
- MCP servers: github, postgres (see .claude/settings.json)
- Pre-commit hook: runs typecheck + lint
- Use /compact before long refactoring sessions

For Cursor users, a .cursorrules that references AGENTS.md:

See AGENTS.md for project architecture and conventions.

Cursor-specific: prefer Tab for completions in boilerplate code; 
use Composer for multi-file refactors.

Step 3: PR template update

In .github/pull_request_template.md:

## AI Context (if applicable)
- [ ] Updated AGENTS.md with new architectural decisions
- [ ] No architectural changes in this PR (skip)

This single checkbox is often enough to ensure AGENTS.md stays current.

Enforcing Standards Without Bureaucracy

Heavy process requirements for AI usage create friction without proportionate value. Two enforcement mechanisms that don't require process:

CI check for AGENTS.md staleness:

A lightweight GitHub Action that checks if significant architecture-related files changed without a corresponding AGENTS.md update:

name: Check AI Context
on: [pull_request]
jobs:
  check-agents-md:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Check if AGENTS.md updated with arch changes
        run: |
          ARCH_CHANGED=$(git diff --name-only origin/main HEAD | grep -E "(auth|database|api|prisma)" | wc -l)
          AGENTS_CHANGED=$(git diff --name-only origin/main HEAD | grep "AGENTS.md" | wc -l)
          if [ $ARCH_CHANGED -gt 2 ] && [ $AGENTS_CHANGED -eq 0 ]; then
            echo "Warning: Architecture files changed but AGENTS.md was not updated."
            echo "Consider updating AGENTS.md with any new architectural decisions."
          fi

This warns (not blocks) when architecture files change without a context update. The developer can dismiss it if the change is trivial.

Shared hook configuration:

For Claude Code teams, distribute a shared .claude/settings.json that all Claude Code users start from:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "context-keeper capture" }
        ]
      }
    ]
  },
  "permissions": {
    "allow": ["Read(*)", "Edit(*)", "Write(*)", "Bash(npm run *)"],
    "deny": ["Bash(git push --force)", "Bash(rm -rf *)"]
  }
}

Commit this to the repo. New developers copy it to their ~/.claude/settings.json and get the team's standard configuration immediately.

Security Standardization

AI coding agents need access constraints — not to be restrictive, but to prevent accidental damage and limit the blast radius of mistakes.

Standard permission model (Claude Code example):

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(apps/**)",
      "Write(apps/**)",
      "Bash(npm run *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git checkout *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(rm -rf *)",
      "Bash(DROP TABLE *)",
      "Read(.env)",
      "Read(.env.local)",
      "Edit(.env*)"
    ]
  }
}

This allows the agent to read, edit, run tests, and commit — but blocks force pushes, recursive deletes, and access to environment files with secrets.

Distribute this as the team's base permission model. Individual developers can extend it locally if their specific workflow requires broader access.

Code Review Standards for AI-Generated Code

AI-generated code requires the same review standards as human-written code — but reviewers should specifically look for certain categories of AI-specific issues:

Standard AI code review checklist:

• Follows established patterns (compare against AGENTS.md patterns)
• No anti-patterns from AGENTS.md DO NOT list
• Auth checks in place for all protected routes
• No hardcoded values that should be environment variables
• Tests included (same requirement as human-written code)
• No new dependencies added without discussion

This doesn't need to be a separate process — add these checks to your existing PR review template as a reminder for AI-generated code sections.

Measuring Standard Adoption

Track whether standards are working by measuring outcomes, not compliance:

• Pattern violation rate: how often do PRs include code that violates AGENTS.md patterns?
• Context freshness: when was AGENTS.md last updated vs. when was the last architectural change?
• New developer ramp time: how long does it take a new developer to make their first productive AI-assisted contribution?
• Context re-explanation time: are developers spending less time re-establishing context at session start?

If pattern violations stay below ~10% of PRs and new developers are productive in hours rather than days, your standards are working.

Key Takeaways

• Standardize: AGENTS.md, approved tools, code review requirements, security constraints, update process
• Leave flexible: which tool to use, personal workflow, model selection
• Minimum viable standard: shared AGENTS.md + one-page AI usage guide + PR template addition
• Enforce with tooling (CI checks, shared hook config) not process bureaucracy
• Security model: standard permissions that allow productive work while blocking destructive actions
• Measure outcomes (pattern violation rate, new developer ramp time) not compliance

Related: Sharing AI Context Across a Development Team · AGENTS.md vs CLAUDE.md: The Agent Instruction File Standard · Measuring ROI of AI Coding Tools for Teams