scaling AI agent configs across your engineering team

Individual developers using AI coding tools get productivity gains. Teams using AI coding tools with consistent, shared configurations get compounding productivity gains — plus faster onboarding, more consistent code quality, and AI assistants that actually understand how the team works.

The difference is configuration management. Here’s how to do it at scale.

The problem with individual configurations

When every developer on a team configures their AI tools independently, you get fragmentation:

New hires spend days setting up their AI assistants (if they set them up at all)
Senior engineers have highly tuned configs; junior engineers have defaults
The AI suggests different patterns to different people on the same codebase
Configuration drift means the AI gives different advice in November than it did in March

The AI is supposed to help enforce consistency. When every developer has a different configuration, it does the opposite.

Starting point: shared configuration files in the repo

The simplest starting point: put your AI configuration files in version control and treat them like any other team standard.

project-root/
├── AGENTS.md                              # Universal agent context
├── CLAUDE.md                              # Claude Code specific
├── .cursor/rules/
│   ├── conventions.mdc
│   ├── testing.mdc
│   └── architecture.mdc
└── .github/
    └── copilot-instructions.md

With this structure:

Every developer who clones the repo gets the team’s AI configuration automatically
Config changes go through code review like any other change
The history of config decisions is in git, with rationale in commit messages

This is table stakes. Most teams are already here or should be.

The ownership question

Who owns the AI configuration? This matters more than you’d think.

The worst outcome: nobody owns it. It starts strong, accumulates drift, becomes outdated, and developers stop trusting it. AI suggestions stop matching team patterns. Developers turn off the configuration or ignore it.

Assign explicit ownership:

Option 1: Rotating ownership. Each quarter, a different engineer is responsible for reviewing and updating the team’s AI config. Keeps knowledge distributed, prevents single points of failure.

Option 2: Senior engineer ownership. Your most experienced engineers know the codebase patterns best. Have them maintain the config as part of their technical leadership responsibilities.

Option 3: Platform/DX team. If you have a developer experience function, AI configuration management fits naturally there.

Whichever you choose, make it explicit. Put it in the team handbook. Give the owner a quarterly reminder to review.

Layering: shared base + project overrides

For organizations with multiple repos or projects, a flat “one config per repo” approach doesn’t scale. You end up with the same base conventions duplicated across dozens of configs that drift apart independently.

The better structure is layered configuration:

Layer 1: Organization base config Common conventions that apply across all repos: code style, comment standards, security requirements, logging patterns.

Keep this in a shared repo or package that other repos can reference.

Layer 2: Project-specific config Each repo imports the base config and adds what’s specific to that project: framework choices, architectural patterns, domain-specific conventions.

Layer 3: Personal overrides (optional) Individual developers can layer personal preferences on top, but cannot override team or project standards.

In practice this looks like:

# AGENTS.md (project-level)

## From org standards
See https://github.com/org/engineering-standards for base conventions.
Key organizational requirements:
- All API endpoints require authentication
- All user-facing errors must be logged to our error tracking system
- Security-sensitive operations require code review from @security-team

## Project-specific
This is the Payments service. Additional context:
- PCI DSS compliance is required for all payment-related code
- Never log card numbers, CVVs, or full PANs anywhere
- All monetary values use integer cents, never floats

Handling per-file and per-directory rules

Cursor’s MDC format handles this natively with glob patterns:

---
description: "Payment processing conventions"
globs: ["src/payments/**/*.ts"]
alwaysApply: false
---

Payment processing code is PCI DSS sensitive.
Always mask card data in logs.
Payment amounts are always integers (cents), never floats.
Validate all card data with our internal validation library before processing.

For Claude Code, you can place CLAUDE.md files in subdirectories:

src/payments/CLAUDE.md    # additional context for payment-related work
src/api/CLAUDE.md         # API-specific conventions

Claude Code reads and merges these automatically when working in those directories.

Onboarding: from zero to productive in an hour

With shared configuration in the repo, onboarding a new developer’s AI tools becomes a checklist item, not a week-long process:

Clone the repo (configs come with it)
Install preferred AI tools
The tools read the repo’s configuration automatically
For tool-specific setup, follow the team’s setup doc (5-10 minutes)

The AI assistant already knows how your project works before the new developer writes a line of code. They can ask “how should I structure a new API endpoint?” and get an answer consistent with how the team actually does it.

Track this: measure how long new hires take to submit their first PR before and after implementing shared AI configuration. The improvement is typically significant.

Reviewing and updating your configuration

Treat your AI configuration like living documentation. Review it quarterly with these questions:

What patterns did reviewers keep correcting this quarter? If code review comments show repeated corrections of the same patterns, the AI is either not following your config or your config doesn’t cover that pattern. Add it.

What conventions changed? Your team adopted a new library. Switched from one auth approach to another. Changed your API response format. Every convention change should trigger an AI config update.

What’s become outdated? Old conventions that no longer apply add noise and can contradict current practice. Remove them.

What’s missing for new team members? Ask your most recent hire: what did your AI assistant get wrong in the first month? Those are documentation gaps.

Using spaget for team configuration management

Managing shared AI configurations manually works but has friction points — especially when you need to keep AGENTS.md, CLAUDE.md, .cursor/rules, and copilot-instructions.md all saying the same thing.

spaget team plans let you:

Build your agent configuration once in the visual builder
Export to all formats simultaneously (every file stays in sync)
Share the configuration across the team
Update once and re-export everything when conventions change

For teams using multiple AI tools (the norm at most companies now), this eliminates the maintenance burden of keeping platform-specific configs aligned. One source of truth, many export formats.

No account required to try the builder — open it here.

The compound effect

Here’s the compounding value of team AI configuration that’s easy to miss: every improvement to the shared config benefits everyone immediately.

When a senior engineer adds a convention that eliminates a class of bug, every developer on the team’s AI assistant applies that convention starting now. When a new library’s best practices are documented in the config, everyone gets good suggestions for it immediately.

This is different from traditional documentation, which requires developers to actively read and remember. AI configuration makes good patterns the path of least resistance — the AI suggests them first, every time.