Skip to content

Working with AI as a team

An individual builds a good AI setup by tuning their own memory files, skills, and habits. A team can't work that way — if every member tunes their own, you get N slightly different setups, N versions of "how we do things," and an AI that behaves differently depending on whose machine it runs on. Working with AI as a team means building one shared foundation that every member, and every agent, starts from.

Why this matters — Limitation #2 (No real thinking / no persistent learning). A model doesn't compound learning across sessions — and without deliberate effort, a team doesn't either. Lessons stay trapped in one person's chat history or one person's head. The fix is the same at team scale as at individual scale, just with higher stakes: externalize the knowledge into shared, reviewed, version-controlled files. Do it once, well, and every member and every agent inherits it. That shared foundation is what turns individual AI fluency into a team capability.

The shared AI foundation: one source of truth, reviewed like code, with an owner — 2 min 16 s.

One shared foundation, not N personal ones

The mechanics of project memory — the thin root that points to focused files — are covered in Memory and project rules. This page is about treating that structure as a team artifact: something the team owns, reviews, and versions together, not a file each person edits for themselves.

The distinction that matters here is already drawn in that page: team-shared memory is committed and reviewed; personal working memory is git-ignored. The shared foundation is the committed half. It's the team's contract with its tools — the single place that answers "how do we build here?" — and it earns the same care as production code.

AuditAgent in practice. The AuditAgent repo is a concrete instance of a team foundation: a one-line CLAUDE.md (@AGENTS.md), an AGENTS.md holding the project overview and shared commands, an agents/ folder with the domain detail (BACKEND.md, FRONTEND.md, UI_STYLES.md), and a design_decisions/ folder capturing the why behind big choices. None of it lives in anyone's private notes — it's in the repo, so it's the same for everyone who clones it.

Give every tool the same footing

Teams rarely use just one AI tool. Some people drive Claude Code, others use a different editor-integrated agent or a second CLI. The risk is that each tool operates on a different foundation — one reads a rich AGENTS.md, another gets nothing and improvises.

The move is to point every tool at the same source of truth. The convention that makes this work:

  • Keep one canonical file — AGENTS.md — as the real foundation.
  • Have each tool-specific file simply point to it. A CLAUDE.md whose entire contents are @AGENTS.md means Claude Code and any AGENTS.md-aware tool read the same thing. No drift, no second copy to keep in sync.

The goal is that no agent operates on a weaker foundation than any other. Whatever tool a teammate reaches for, it starts from the team's full, current understanding of the codebase — the same commands, the same architecture boundaries, the same known failure modes. The tool is interchangeable; the foundation is not.

Note — "agent teams" is a different thing. MCP and config mentions "agent teams" (the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS setting). That's about one operator orchestrating multiple sub-agents on a task — not about a team of humans. This page is about the humans. See the glossary entries for agent teams and subagent if the terms blur.

Keep the foundation alive

A shared foundation that isn't maintained rots into a shared liability — a wrong rule misleads everyone's agent, silently. Keeping it alive is ongoing team work:

  • Review foundation changes like code. An edit to shared memory or a shared skill affects every future session for every member. Review AI-generated memory edits before committing applies doubly at team scale — the bar for committed, inherited rules is high.
  • Improve skills as the team learns. When the team finds a better way to do something, fold it back into a project skill so the improvement propagates automatically — see Reusable skills and automation. The claude-md-management plugin can audit the memory files for bloat and staleness.
  • Capture the why, not just the what. Big decisions belong in a design_decisions/ folder so the reasoning survives the person who made it — this is the team-scale version of Plan and design first. Six months later, "why is auth done this way?" has a written answer instead of a shrug.

Ownership: who guards the foundation

Shared files with no owner drift toward nobody's-responsibility. Make ownership explicit:

  • Put the AI foundation under CODEOWNERS so changes to AGENTS.md, agents/, and project skills get a required reviewer — the same as any other critical part of the repo.
  • Say in CONTRIBUTING.md how to propose a change to the foundation: how to add a new focused file, when to write a new skill versus a one-off prompt, and who signs off.

The point isn't bureaucracy — it's that the foundation is high-leverage in both directions, so a small amount of stewardship keeps it an asset rather than a source of confusion.

Quick checklist

  • The AI foundation (AGENTS.md, agents/, project skills) is committed and reviewed, not personal
  • One canonical source of truth; each tool's file points to it (CLAUDE.md → @AGENTS.md)
  • Every AI tool the team uses starts from the same foundation
  • Changes to shared memory and skills are reviewed like code
  • Team lessons get folded back into skills and memory, not lost in chat history
  • Big decisions are captured in design_decisions/ with their reasoning
  • The foundation has an explicit owner via CODEOWNERS / CONTRIBUTING.md