Agentic Coding Tools on Small Engineering Teams

Executive summary

The prescriptive playbook for teams of 5–20 engineers adopting Claude Code, Codex, and similar agentic coding tools inverts the order most teams build in. Anthropic's rollout guidance describes five layers assembled in a fixed sequence — context files, hooks, skills, plugins, then MCP servers and LSP integrations — and states that "the order in which teams build them matters, as each layer builds on what came before" [1]. Vercel's January 2026 evaluation supplies the mechanism. Built around Next.js 16 APIs deliberately absent from model training data — connection(), the 'use cache' directive, cacheLife(), forbidden(), async cookies() and headers() — it compared four configurations: a no-documentation baseline passed 53%, a skill with default behavior also passed 53%, a skill the agent was explicitly told to use reached 79%, and an 8 KB documentation index embedded directly in AGENTS.md reached 100% [2]. The reason is a single reported number: "In 56% of eval cases, the skill was never invoked" [2]. A team that opens with a skills library has built the layer with the weaker expected value first.

The configuration surface has converged across tools, which makes the shared-versus-personal boundary portable. Claude Code publishes four scopes: managed settings deployed by IT, user scope in ~/.claude/, project scope in .claude/ affecting "all collaborators on this repository", and local scope in .claude/settings.local.json affecting "you, in this repository only" and gitignored automatically [4]. Codex gives the committed .codex/config.toml precedence over a developer's personal config [16] but loads project .codex/ layers "only when you trust the project" [17]. Cursor merges Team Rules, then Project Rules, then User Rules [20]. Anthropic states the negative form directly: "Never put personal preferences in shared project CLAUDE.md files" [3]. One documented behavior runs against the prescription — Claude Code resolves skill name conflicts so that "enterprise overrides personal, and personal overrides project" [5], meaning a developer's personal ~/.claude/skills/deploy/ silently shadows the team's committed version.

Hooks are the deterministic complement to advisory instructions. Anthropic's rule is explicit: when something "absolutely must not happen, use hooks or managed settings, not instructions," because "the model can fail to follow a prompted rule" [3]. The recommended starter set is three hooks — git safety, context injection, post-edit quality gate — with additions in response to incidents rather than anticipation [30].

Mixed-tool teams are the common case, and the coordination pattern is one source of truth plus symlinks. AGENTS.md is "now stewarded by the Agentic AI Foundation under the Linux Foundation" and reports use by "over 60k open-source projects" [19], with tool support spanning "20+ platforms" [18]. The published commands are ln -s AGENTS.md CLAUDE.md and ln -s ../.agents/skills .claude/skills, on the rationale that separate files "drift apart and your team gets inconsistent AI behavior depending on which tool they use" [22].

Adoption is carried by costed rituals rather than announcements. Anthropic's champion playbook budgets roughly 40 minutes a week for the entire role — 15 minutes posting wins and prompts, 20 answering questions in a shared channel, 5 hosting a weekly show-and-tell thread — and defines success as "questions in the channel are being answered by people other than you" [12]. AutoScout24 names the failure mode from the other side: tools enabled, announcement sent, demos shared, and "then the day-to-day work barely changes" [37].

The evidence base has one serious hole, stated up front. Almost no rigorous case study exists at 5–20 engineers. The strongest first-hand account in the target range covers a single five-person team, self-reported and without metrics [36], and the most widely circulated "30-dev shop" case study carries a publisher disclaimer that it is an "illustrative anonymised composite" whose numbers are constructed rather than measured [44].

Introduction

This snapshot reports what works for small software engineering teams — roughly 5 to 20 engineers — adopting agentic coding tools in practice. The lens is prescriptive: what teams set up, how they share it, how they ramp, and which rituals make adoption durable. Failure modes, security threats, industry-level adoption rates, data-team workflows, and pricing are covered by companion topics and appear here only where a positive recommendation cannot be stated without them.

The category is extensible coding agents — tools that let a team specify skills, agents, hooks, and comparable primitives. Claude Code and Codex are the canonical examples; Cursor's agent modes, Amp, Aider, and Gemini CLI enter where the evidence supports them. Two features of the subject shape everything below. First, mixed-tool teams are the common case rather than the exception, so cross-tool patterns are preferred over tool-specific ones. Second, every configuration mechanism described here changed materially during the twelve months preceding August 2026 — Claude Code merged custom slash commands into skills [5], AGENTS.md moved to Linux Foundation stewardship [19], and Codex added repository-scoped .codex/ layers gated on project trust [17] — so guidance written before late 2025 is presumed stale unless re-verified.

The recurring framing is layer ordering: a five-layer harness in which each layer presupposes the one before it [1]. The report covers layer ordering and the primacy of context files, the three-tier configuration shape now common to Claude Code, Codex, and Cursor, context-file authoring constraints, hooks as the deterministic layer, skills and their governance, distribution through committed directories and plugins, cross-tool coordination through AGENTS.md, monorepo layouts and the settings-inheritance gotcha, champion-led adoption and sustaining rituals, ownership and light instrumentation, permission posture, a synthesized 90-day sequence, and the limits of the evidence base.

Layer ordering and the primacy of context files

The layer ordering is the load-bearing prescription in this evidence set, and it is supported from two directions: a vendor assertion about sequence and an independent evaluation of the mechanism underneath it.

Anthropic names the five layers — CLAUDE.md files, then hooks, then skills, then plugins, then MCP servers and LSP integrations — and asserts that the ordering matters because "each layer builds on what came before" [1]. Vercel's eval supplies the reason it holds. Against Next.js 16 APIs absent from training data, the always-on AGENTS.md documentation index passed 100% while a skill carrying the same material passed 53% by default and 79% when the agent was explicitly told to use it, against a 53% no-documentation baseline [2]. The differentiator is not content but retrieval: the skill went uninvoked in 56% of cases [2]. Always-on context has no decision point the agent can get wrong; on-demand retrieval has one, and in this eval it failed often enough to erase the benefit.

Vercel's own caveat travels with the number: "Skills work better for vertical, action-specific workflows that users explicitly trigger" [2]. Skills are not the wrong primitive; they are the wrong first primitive for encoding general repository knowledge. Anthropic's primitive-selection guidance draws the same line from the other side — skills exist for "instructions that are procedural, like deploy workflows, release checklists, or review processes" [3], and a skill is warranted "when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact" [5]. Facts about the repository stay in the context file; procedures a human deliberately triggers become skills.

Hooks sit second for a different reason: they are the only layer that enforces rather than suggests. Hooks give "deterministic control: certain actions always happen rather than relying on the LLM to choose to run them" [6]. The five-person team documented at Dataworkz reached the same conclusion independently: "The agents could vary; the guardrails could not" [36].

The opening move the evidence supports is therefore narrow: write the context file first, add two or three hooks encoding the non-negotiables, and postpone the skills library until repeated manual pasting identifies which procedures deserve one.

The three-tier configuration shape across tools

The first concrete decision a small team makes is what lives in the repository and what lives on each developer's machine. Every major agentic tool now exposes the same configuration shape, which is what makes a single shared-versus-personal rule portable.

Claude Code's four scopes run managed, user, project, and local, with precedence ordered managed, then command-line arguments, then local, then project, then user [4]. Project scope in .claude/ affects "all collaborators on this repository" and is committed; local scope in .claude/settings.local.json affects "you, in this repository only" and is gitignored automatically [4]. Hooks follow the same table, with an additional shareable location inside a plugin's hooks/hooks.json [6]. When the same array-valued setting appears in multiple scopes, Claude Code concatenates and deduplicates rather than overrides, so a personal .claude/settings.local.json can allow npm test for one developer without silently weakening the team's Bash:rm -rf block [8].

Codex's shape matches with one addition. The committed .codex/config.toml carries team defaults — model, sandbox mode, approval policy, MCP servers — alongside .codex/rules/ and shared skills in .agents/skills/, while personal skills live in ~/.agents/skills/, and the committed project config outranks a developer's personal config [16]. The addition is a security gate: "Codex loads project .codex/ layers only when you trust the project" [17]. A team standardizing on Codex has to make trusting the repository an explicit onboarding step, or new joiners run on personal defaults while believing they are on team defaults. Cursor uses different names for the same tiers: "Rules are applied in this order: Team Rules → Project Rules → User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts," with project rules "version-controlled and scoped to your codebase" and user rules "global to your Cursor environment" [20]. Committing .cursor/rules/ is what stops the divergence where "one person's Cursor uses camelCase while another uses snake_case, one writes tests with Jest while another uses Vitest" [21].

For a 5–20 engineer team the concrete list is short. Committed: the root context file (AGENTS.md, with CLAUDE.md symlinked to it), .claude/skills/ or .agents/skills/, .claude/agents/ for subagent definitions [11], .claude/settings.json for permission rules and hooks, .mcp.json at the project root for uniform MCP configuration [33][35], and .cursor/rules/ if anyone uses Cursor [20]. Personal and gitignored: ~/.claude/ and ~/.agents/ for cross-project preferences, .claude/settings.local.json for per-repository personal overrides [4], and auto-memory and session history.

The uniformity supports one rule across all three tools: anything another engineer needs in order to reproduce a result goes in the repository, and anything reflecting personal working preference stays on the machine. Anthropic states the negative form directly — "Never put personal preferences in shared project CLAUDE.md files" [3] — and the reason is governance rather than aesthetics: a shared context file "grows the way any unowned config file does: every team appends its own instructions" [3]. At 5–20 people this arrives faster than the ownership structures that would catch it. The discipline that holds the split together is treating changes to the shared folder as code. Any change to the shared configuration "affects everyone, so any change to this should go through pull requests and code review" [32], with domain owners maintaining their own rules — the team that owns the auth code also owns the auth-related skills [32].

One precedence rule resolves backwards from what most teams would guess, and it is specific to Claude Code. Skill name conflicts resolve so that "across levels, enterprise overrides personal, and personal overrides project" [5]. A developer with a personal ~/.claude/skills/deploy/ silently shadows the team's committed .claude/skills/deploy/ — /deploy runs their version, not the reviewed one, with no warning. Two defenses exist: namespace team skills distinctly, or ship them as a plugin, since "plugin skills use a plugin-name:skill-name namespace, so they never collide with per-directory skills" [7].

Context-file authoring: length, phrasing, and ownership

The context file loads at the start of every session, so it is also the file teams most consistently bloat past usefulness. The evidence on what belongs inside it converges on three properties: bounded length, imperative phrasing, and a named owner.

On length, Anthropic's guidance is to "keep CLAUDE.md under 200 lines, give it an owner, and review changes to it like code" [3]; practitioner guidance targets 150–200 lines at the repository root and cites the same ceiling [26]. The underlying reason is stated in the best-practices documentation: "Keep it concise. For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions" [8]. Codex enforces a harder version mechanically: combined AGENTS.md content is capped at 32 KiB by default via project_doc_max_bytes, and "Codex stops adding files once this threshold is reached" [15]. Sprawl produces silent truncation of whatever sorted last rather than a warning.

The same documentation reinforces the boundary against skills: "CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use skills instead. Claude loads them on demand without bloating every conversation" [8]. Anthropic's /init command generates a starter context file from the current project structure [8], and the Champion Kit names the workflow as something a champion can share publicly [12] — but the generated output is a first draft measured against the 200-line ceiling, not a steady-state file.

On phrasing, the practitioner guidance is more specific than the vendor guidance. Instructions should be imperative rather than descriptive — "Run pnpm test before committing" rather than "We value testing" — with "be careful," "where appropriate," and "try to" treated as banned phrases because "they map to no decision" [26]. The complementary exclusion rule: "If the linter catches it, don't restate it. If a violation would block a merge in CI, the rule belongs in CI" [26]. That is the enforcement-versus-guidance boundary governing hooks [3], applied to prose.

On ownership, both source types prescribe treating the file as code. Anthropic recommends reviewing context-file edits "in pull requests… like any other documentation change so conventions track the code," and adds a domain-specific maintenance trigger — "revisit after major model releases," because "instructions that worked around an older model's limitation may become overhead once a newer model handles the case on its own" [7]. Practitioner guidance adds a concrete mechanism: a pull-request template checkbox reading "Updated AGENTS.md if build/test/deployment commands changed," plus quarterly pruning [26]. A complementary rotation keeps the file from ossifying: "Rotate CLAUDE.md ownership — assign monthly review responsibility to ensure instructions evolve with the codebase" [33]. The stated reason to bother is that "a stale or bloated AGENTS.md can actively hurt agent performance" [26] — a claim about direction with no magnitude attached, and single-sourced.

A freshness caveat applies to the headline number behind this section. The Vercel result [2] is dated 27 January 2026, roughly seven months before this snapshot, and discloses neither the model tested nor the task count. It is reported here as evidence about early-2026 agent behavior on undocumented framework APIs, which is the strongest form the evidence supports; no current-generation replication was located. The directional recommendation is additionally supported by the mechanism argument and by vendor guidance [3][1], so it does not rest on the eval alone.

Hooks as the deterministic layer

Anthropic frames hooks as a layered control mechanism alongside the context file: "Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens" [8]. The decision rule is stated plainly — when something "absolutely must not happen, use hooks or managed settings, not instructions," because "the model can fail to follow a prompted rule" [3]. One practitioner estimate puts the gap at roughly 25–40% compliance from advisory guidance versus around 95% from hook-enforced rules [31]; the figure is single-sourced and should be read as an order-of-magnitude claim rather than a measurement.

The most-quoted prescription on starting hook count comes from Blake Crosley, who maintains 95 hooks and notes that "almost all of them exist because something went wrong first" [30]. The recommended starter set is three: a PreToolUse:Bash hook for git safety, which blocks force-pushes to protected branches and destructive commands — "the git-safety-guardian exists because Claude force-pushed to main" [30]; a UserPromptSubmit hook for context injection (date, branch, project state); and a Stop hook as a quality gate running lint, tests, and format before session completion [30]. Additions come from incidents, not anticipation: "Start with 3 hooks, not 25" [30].

The cross-source taxonomy is stable. Hooks divide into prevention (PreToolUse, blocking the action before it runs) and validation (PostToolUse, running after a tool succeeds and able to inject feedback) [8]. Recurring concrete patterns include destructive-command detection and protected-path blocks on migrations/ and .env at PreToolUse; linter and formatter on every file edit plus targeted tests on edits to test or source files at PostToolUse; desktop notifications on long-task completion as a Stop hook [12]; and recursion guards to prevent multi-agent spawn loops, added after earlier recursion "consumed API tokens at 10x the normal rate" during a multi-agent spawning incident [30]. The canonical first hook for a small team is the one the Dataworkz team enforced mechanically: mandatory unit tests, and tests must pass before anything is pushed [36].

The team-versus-personal split for hooks parallels the substrate split. Safety hooks — force-push prevention, credential-leak detection — belong in the committed .claude/settings.json so every team member gets the same rails [30][6]. Taste-level hooks stay in individual configs. Hooks themselves go through pull-request review: they are shell scripts running with file and system access.

Skills: when to build one, and how to govern it

Skills, not slash commands, are the packaging unit for recurring workflows. Anthropic's documentation states the change directly: "custom slash commands have been merged into skills. Files in .claude/commands/ still work, but skills (.claude/skills/) are now the recommended approach" — a skill is a SKILL.md plus optional supporting files [8]. OpenAI's Codex documentation describes skills with the same .agents/skills/ convention for team sharing [13].

The layer ordering determines when to build them: not in month one, and not speculatively. The trigger is repetition — "when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact" [5]. Skills nobody invokes cost context and yield nothing [2].

When a skill does earn its place, the governance is settled. One practitioner guide distills it into a sentence: "Every skill needs: an owner, a version, and a deprecation path" [27]. Operationally: one job per skill, with smaller composable skills preferred over a monolith that spans multiple workflows; SKILL.md kept under 500 lines with detailed reference material in separate files that load on demand [27], since skill metadata loads at session start and full instructions only when the skill triggers, so bloated skills tax every session [8]; a named owner per skill; explicit version pins in production with latest only during development, and deprecation rather than silent rot [27]; a quarterly maintenance review for accuracy and breaking-change communication [27]; and security review for third-party skills, since Snyk research cited in the same guide found 36% of AI-agent skills in public directories contain security flaws [27].

Descriptions are load-bearing because they are what the model uses to decide whether a skill applies. Naming conventions converge on gerund forms — generating-reports, reviewing-code, analyzing-data — for discoverability [27]. The combined description and when_to_use text is "truncated at 1,536 characters in the skill listing" [5], so the operational instruction is to "put the key use case first" [5] and "keep descriptions short and lead with words a request would contain" [7]. The recurring failure modes are monolithic SKILL.md files that try to do everything and over-broad descriptions that cause invocation on unrelated queries — the standard example being an "incident report" skill that activates on every mention of problems [27]. Both are caught by testing that a skill triggers on obvious phrasings, on paraphrased requests, and fails to trigger on unrelated queries [27].

Subagents are the adjacent mechanism, and the selection rule is about context rather than capability. Subagents "run in their own context window with a custom system prompt, specific tool access, and independent permissions… use subagents when a side task would flood your main conversation with search results, logs, or file contents you won't reference again: the subagent does that work in its own context and returns only the summary" [11]. The best-practices documentation also names an adversarial-review pattern: "have a subagent review the diff in a fresh context and report gaps" [8]. For a small team, three to five named subagents committed to .claude/agents/ — a code reviewer, a security reviewer, a release-notes writer — covers most cases.

Distribution: committed directories, plugins, and marketplaces

Distribution is where small teams most often over-engineer, and the vendor guidance is a two-row table plus one rule. Standalone configuration in .claude/ suits "personal workflows, project-specific customizations, quick experiments"; plugins suit "sharing with teammates, distributing to community, versioned releases, reusable across projects" [9]. The rule: "Start with standalone configuration in .claude/ for quick iteration, then convert to a plugin when you're ready to share" [9].

For a single-repository team of 5–20 people, committed .claude/ files are usually the whole answer. Skills committed to .claude/skills/ reach everyone who clones the repository [7], hooks in .claude/settings.json reach everyone likewise [6], and both pass through the normal pull-request path — "because skills are plain Markdown, colleagues can adopt them immediately" once the file is shared [12]. The plugin layer earns its cost at a stated threshold: "When shared skills need their own version history or must work across repositories, package them as a plugin instead" [7]. Version history and cross-repository reach are the two triggers, and neither is present in a single-repo team.

When the threshold is crossed the mechanics are documented. A team keeps a marketplace "internal to your team [by hosting] the marketplace in a private repository" [10] and registers it in the repository's .claude/settings.json under extraKnownMarketplaces, after which "once a team member trusts the repository folder, Claude Code adds these marketplaces without a further prompt" [10]. Installation offers three scopes mirroring the settings tiers: user scope across all projects, project scope "for all collaborators on this repository," and local scope [10]. One security note belongs in any distribution recommendation: "Plugins and marketplaces are highly trusted components that can execute arbitrary code on your machine with your user privileges" [10].

A lighter intermediate exists for teams with several repositories that want the same library in each without the plugin apparatus: a git submodule, added as git submodule add https://github.com/your-org/team-skills.git .claude/skills [28]. A widely-shared practitioner account proposes three distribution tiers scaled to organizational maturity — submodules for small teams, an installation script for polyglot environments, and an npm or Python package with semantic versioning for "platform engineering teams supporting hundreds of engineers" — with an honest caveat that "submodules can be cumbersome for developers unfamiliar with updating them" [29]. This is a single moderate-credibility source describing its own deployment, with no independent corroboration and no evidence that the size thresholds are more than the author's judgment; it is a plausible decision heuristic rather than an established one.

The tooling also supports the pruning half of the lifecycle. Claude Code flags plugins "you installed yourself but haven't used in at least two weeks, over a span of at least 10 sessions" under a "Not used recently" header [10], and skill usage can be instrumented directly: enabling the OpenTelemetry logs exporter with OTEL_LOG_TOOL_DETAILS=1 records every invocation in the skill_activated event's skill.name attribute, alongside an invocation_trigger field recording whether a command, the model, or a nested skill invoked it — "which tells you what to consolidate or retire" [7].

Cross-tool coordination through AGENTS.md

Small teams rarely standardize on one agent, and the evidence does not suggest they should. Most production teams run two or three tools side by side — "Cursor for daily IDE flow, Codex for autonomous background tasks, and Claude Code for complex refactors needing deep codebase context" [41] — and a task-fit argument runs alongside the ergonomics: "no single agent performs best across all task types: Claude Code leads in documentation and features, while Cursor excels in fix tasks" [42]. The five-person team documented at Dataworkz "ran multiple models simultaneously (Antigravity, Claude, Codex) but chose among them based on task requirements rather than standardizing on one tool," holding process constant instead [36]. That position is workable only if the shared context does not fragment along tool lines.

AGENTS.md is the convergence point. It describes itself as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project" [19], is stewarded by the Agentic AI Foundation under the Linux Foundation, and reports use by "over 60k open-source projects" [19]. Tool support "spans 20+ platforms: Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Google Jules, VS Code, Devin, Aider, Zed, Warp, Semgrep, JetBrains Junie, and others" [18]. Cursor lists it as a first-class alternative to .cursor/rules [20], and Claude Code "reads AGENTS.md as a fallback when no CLAUDE.md is found in a directory" [18]. OpenAI's Codex documentation treats it as the canonical hierarchy — "a global AGENTS.md for personal defaults… a repo-level file for shared standards, and more specific files in subdirectories for local rules" [13] — and names the operational appeal: "once the rules are in the file, every Codex session in that repository starts with them automatically… The guidance is in the repository, which means it's version-controlled, reviewable, and consistent" [14].

The pattern that follows is to maintain AGENTS.md and symlink everything else to it. The published commands are ln -s AGENTS.md CLAUDE.md, ln -s ../AGENTS.md .github/copilot-instructions.md, and ln -s ../.agents/skills .claude/skills, on the rationale that "if you maintain separate files, they drift apart and your team gets inconsistent AI behavior depending on which tool they use" [22]. A second practitioner source prescribes the same fix for the same reason: "AGENTS.md is the cross-tool standard for AI coding instructions, but some tools still look for their own files… Instead of maintaining multiple copies, use symlinks so every convention resolves to the same source" [23]. Two caveats travel with it, and both matter more for a team than for an individual. Scope the symlinks: "Don't symlink the entire .claude/ directory — only symlink skills, since .claude/settings.json is Claude Code-specific" [22]. And Windows needs configuration — "if symlinks appear as plain text files, run: git config core.symlinks true" [22] — a real onboarding step on a mixed-OS team.

Skills port by the same mechanism because the file format is shared: a skill folder can be symlinked "into both .claude/skills/ and .agents/skills/, as the SKILL.md format is identical" [24]. Claude Code supports this natively — a skill entry "can be a symlink to a directory elsewhere on disk," and Claude Code "follows the symlink and reads SKILL.md from the target directory" [5].

A more disciplined variant exists for teams that find symlinks insufficient. One practitioner maintains "a single version-controlled directory for the durable agent configuration" with peer subtrees — agent-config/claude/{CLAUDE.md,hooks,skills} and agent-config/codex/{AGENTS.md,hooks,skills} — plus a manifest and a sync tool, and enforces parity with a pre-commit guard that "blocks commits with a Claude/Codex configuration change without the corresponding counterpart" [25]. That is a single-user setup, so it transfers as a pattern rather than as evidence of team-scale success; the pre-commit parity check is the portable idea.

What does not port should be stated plainly, since assuming otherwise produces silent divergence. Settings files are tool-specific: Claude Code reads .mcp.json while Codex reads config.toml [25][22], and hook syntax and lifecycle differ across tools, which most teams accept as duplication cost. Nesting semantics do align. For AGENTS.md, "the closest file to the edited file wins; explicit user chat prompts override everything" [19]; Codex concatenates "from root down [with] closer files overriding earlier guidance" [15]; Claude Code uses the same shape for CLAUDE.md [7].

Monorepo layouts and the settings-inheritance gotcha

The monorepo pattern is stable and identical in shape across tools: a root file for repository-wide rules, and a file per package for that area's conventions.

Claude Code "loads every CLAUDE.md file from your working directory and every parent directory at launch, then loads each subdirectory's file on demand when it reads files there," with the guidance to "commit these files to the repository so teammates inherit them" and each directory's owner typically maintaining its file [7]. AGENTS.md prescribes the same: "Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence" [19]. Skills follow suit — they live under .claude/skills/ inside the directory, committed "alongside that area's code so anyone who clones the repository gets them," which "in a monorepo… can be one set of skills per package" [7] — and load lazily, becoming available "when Claude reads or edits a file in a subdirectory" [5].

Settings do not behave like context files, and the difference is easy to miss. "Project settings in .claude/settings.json load only from your starting directory and are not inherited from parent directories the way CLAUDE.md files are: a .claude/settings.json at the repository root applies only when you start from the root" [7]. A team that puts its hooks in the root settings file and then tells everyone to start sessions from their package directory has quietly disabled its own guardrails. The documented remedy is to make each area's settings file self-contained and duplicate rules that must apply everywhere [7].

Worktrees are the other durable mechanism, and they answer the most common source of multi-session friction: "Never let two agent sessions work on the same branch" [33]. Anthropic's documentation names the same mechanism — "Worktrees: run separate CLI sessions in isolated git checkouts so edits don't collide" [8] — and the team-relevant part is that the configuration is committable. The worktree.sparsePaths setting "uses git sparse-checkout to write only the listed directories plus root-level files to disk, so worktrees start faster and use less space," and "if everyone working in this directory needs the same paths, commit the setting to .claude/settings.json" [7].

Discoverability is the failure mode at the far end of the pattern. Starting from the repository root accumulates skills "from every subdirectory Claude touches during the session, which can accumulate into the hundreds," and descriptions "are shortened when there are many," which "can strip the keywords Claude uses to decide whether a skill applies" [7]. At 5–20 people this is a future problem, but writing descriptions correctly from the start costs nothing. Anthropic is candid that the layering eventually stops scaling: "Per-directory CLAUDE.md files can become hard to govern as the codebase grows. Conventions drift, files go stale, and no one owns the root" [7]. That is the moment the plugin layer becomes worth its cost.

Champion-led adoption and sustaining rituals

The strongest statement of the problem comes from a first-party engineering blog describing what does not work: "The tools are enabled. A Slack announcement went out. A few demos were shared. Everyone is expected to try it when they find time. Then the day-to-day work barely changes" [37]. Anthropic's Champion Kit opens on the same observation from the other side: "Adoption of a developer tool rarely happens because of a rollout announcement. It happens because someone on the team begins using the tool well, talks about it openly, and makes it easy for others to follow" [12].

What replaces the announcement is a small set of rituals, and the notable property of the vendor-published version is that it is costed. The champion role budgets roughly 15 minutes a week posting wins and prompts, 20 minutes answering questions in a shared channel, 5 minutes hosting a weekly show-and-tell thread, and 0–30 minutes on optional pairing [12] — about 40 minutes a week for the core. The Champion Kit is explicit that "the activities below are intended to fit inside a normal working week, and the role should remain a multiplier on your existing work rather than an additional support responsibility" [12].

The 30-day sequence is the most concrete published ramp. Week one: seed a dedicated channel, pin the quickstart, and post two or three of your own worked examples with the prompts that produced them. Week two: start the weekly show-and-tell thread, answer every question publicly, share one custom skill or context snippet. Week three: offer two or three short pairing sessions and consolidate common questions into a pinned FAQ. Week four: identify a second champion and share a brief summary of what is working with leadership [12].

Three practices recur across sources. Answer with the prompt: "When a colleague asks how you accomplished something, the most useful response is the prompt you actually used" [12] — the worked example being a colleague asking how a race condition was found, answered with the literal prompt, "The test in @tests/scheduler.test.ts is flaky, figure out why," not a walkthrough [12]. Share the artifact rather than describing it: post the actual SKILL.md [12]. And pair once: "Offer a single fifteen-minute pairing session to anyone getting started. One successful outcome on their own code is more persuasive than any presentation" [12]. Independent practitioner accounts converge on the same principle. Carta's staff engineer: "We knew that you have to make people want it. You can't tell them a better way; you need to show them" [39]. AutoScout24: "The first win is the hardest. After someone has used an agent to build, debug, or refactor something real, the conversation changes" [37].

Concerns are resolved by single experiences, not arguments. The Champion Kit's table of common engineer concerns — "I am faster without it," "I tried it once and it hallucinated," "we do not have time to learn another tool" — shares one response pattern: acknowledge, reframe briefly, propose one concrete demonstration on the person's own code, because "most concerns are resolved by a single successful experience" [12]. The hardest resistance in the one first-hand small-team account came from strong solo contributors, and the resolution was reframing: "Directing an agent is a delegation skill — naming this as a leadership transition, not a tooling problem, eased adoption" [36].

The success and succession signals are observable rather than measured: "questions in the channel are being answered by people other than you," and "the colleague who asks you the most questions is usually ready to take on this role" [12]. There is also a mechanized onboarding shortcut. /team-onboarding, added in Claude Code v2.1.101 on 10 April 2026, "analyzes the last 30 days of sessions, commands, and MCP usage to generate a shareable Markdown guide" [43]; run in a project where a power user has spent real time, it produces "a guide a new teammate can paste as their first message to replay your setup" [12]. For a small team with one or two power users the action takes about five minutes.

Two findings from larger organizations transfer despite the scale gap. A maturity ladder makes progress legible — Level 0 no AI use, Level 1 chat-style prompting, Level 2 AI in the development environment on real code, Level 3 coding agents with repo context and custom skills, Level 4 orchestrating multiple agents — with the primary goal being to move people from 0–1 to 2 [37]. A ten-person team can place every engineer on that ladder in an afternoon. And manager participation is load-bearing: "Without Engineering Manager hands-on experience and integration into 1:1s and retros, adoption remains optional" [37].

The cadence evidence does not transfer. AutoScout24 runs live sessions "twice a week, for thirty minutes," drawing "3400 total attendees… across 20 sessions" from an organization of 170+ engineers [38]; Carta runs weekly office hours, domain-specific show-and-tell sessions, dedicated Slack channels, and a refactoring hackathon, identifying power users through a token-usage dashboard [39]. A twelve-person team running twice-weekly thirty-minute sessions would spend a meaningful fraction of its capacity on enablement. What transfers is the structural finding underneath — "Predictability mattered: fixed scheduling lowered barriers to attendance," and "Honesty over polish: leaders sharing failures built trust" [38] — along with the design principle for any hands-on session: "Real problems beat generic exercises. People care more when the output could remove something annoying from their actual week" [37]. The Champion Kit's own show-and-tell is the small-team-sized version: each Friday, post "What did Claude help you with this week?" — "No preparation, slides, or meeting are required; screenshots and short descriptions are sufficient" [12].

The unifying principle is stated directly: "Adoption that depends on a single person is fragile. Adoption that is carried by shared habits continues to compound on its own" [12].

Ownership, permission posture, and light instrumentation

Someone must own the configuration. Anthropic's rollout guidance reports that in successful deployments "a small team, sometimes even just one person, wired up the tooling so Claude already fit developer workflows when they first touched it" [1], and defines the minimum viable structure for organizations without a platform team: "one person as a Designated Responsible Individual with authority over configuration, settings, permissions policy, plugins, and CLAUDE.md conventions" [1]. At 5–20 people the DRI model is not the minimum but the whole answer. It is compatible with the champion role and distinct from it: the champion drives usage [12], the DRI owns the artifacts [1]. The small-team-specific argument for naming an owner early is that variance is expensive at low headcount — "if one person adopts a sloppy workflow, it's a meaningful fraction of the team" [36] — and the same account's resolution, standardize process rather than tooling [36], is what makes a single owner tractable.

Permission posture during ramp settles consistently across sources. Start with acceptEdits, which "auto-approves file reads and searches but prompts for file writes and command execution. This is the sweet spot for most organisations" [34], on the reasoning that "if developers have to manually approve every file read, they will abandon the tool within a day" [34]. Small teams are told explicitly to "skip complex policy-check hooks initially. Begin with acceptEdits mode and audit logs only, adding stricter enforcement if problems emerge" [34]. OpenAI's Codex documentation prescribes the analogous posture: "Keep approval and sandboxing tight by default, then loosen permissions only for trusted repos or specific workflows once the need is clear" [13].

MCP introduction follows the same incremental shape: "Do not start by wiring in every tool you use. Start with one or two tools that clearly remove a manual loop you already do often, then expand from there" [13]. The access pattern that recurs is read-broad, write-narrow — give the agent read access broadly and write access narrowly; let it query the database but not mutate it [33]. Whatever the whole team needs goes in a project-scoped .mcp.json at the repository root so configuration is uniform across developers [35][33].

Instrumentation should stay proportionate. The available telemetry is real: the skill_activated event records every invocation with the skill name and an invocation_trigger distinguishing command-invoked from model-invoked from nested calls, which "tells you what to consolidate or retire" [7], and the plugin manager surfaces components unused "in at least two weeks, over a span of at least 10 sessions" [10]. Carta used a token-usage dashboard for a specific and limited purpose: identifying power users who could become champions [39]. At 5–20 engineers that is the right scope for measurement — finding people and finding dead artifacts. No source in this evidence base demonstrates that a metrics dashboard causes adoption at small scale, and the most-circulated "five metrics" framework in this space traces to a self-declared composite whose numbers are constructed [44]. Measurement here is a maintenance tool rather than a management tool.

The durable-quality practices that make agent output reviewable are better established. Investing in end-to-end tests yields "behavioral contracts that grant us the freedom to rebuild and reimplement" [40], which matters more when code is cheap to regenerate, and intent needs recording separately because "tests detail our goals while code encodes our methods, but neither captures the why" [40]. Set against the observation that "code is cheap, but maintenance isn't" [40], the disposition the evidence favors is a reviewer's rather than a generator's.

A 90-day sequence

The following ordering synthesizes the layer guidance [1], the 30-day champion playbook [12], and the constraints reported by the one first-hand account at this scale [36]. It is a synthesis of this evidence base, not a single source's prescription.

Days 1–30, foundation. Name a DRI [1]. Write one AGENTS.md at the repository root — under 200 lines, imperative, with exact build, test, and lint commands, and nothing CI already enforces [3][26]. Symlink CLAUDE.md and any other tool-specific instruction paths to it [22]. Add two or three hooks encoding the non-negotiables — tests must pass before push is the canonical one [36][30]. Commit .claude/settings.json, start in acceptEdits mode [34], and confirm every developer's personal preferences sit in their local file [4][3]. If anyone uses Codex, make trusting the repository an explicit onboarding step [17]. Create a channel and seed it with real prompts from real work [12].

Days 31–60, leverage. Start the weekly show-and-tell thread [12]. Convert repeatedly-pasted procedures into skills one at a time, not speculatively, giving each an owner and a deprecation path [5][27]. Share a project-scoped .mcp.json for any MCP server the whole team needs, starting with one or two [35][13]. Offer fifteen-minute pairing to anyone who has not had a first win [12][37]. Place everyone on the 0–4 ladder and target moving the 0s and 1s to 2 [37]. Run /team-onboarding in the repository a power user knows best and commit the output [43][12].

Days 61–90, durability. Add the pull-request checkbox for context-file updates [26]. Hand the champion role to a second person — the colleague who asks the most questions [12]. Audit permissions and confirm safety hooks live in team settings rather than personal ones [30][34]. Review skill activations and retire what nobody uses [7][10]. Decide — with evidence rather than in advance — whether cross-repository reach or independent versioning justifies packaging anything as a plugin [7][9]. Schedule the quarterly prune [26][27].

Contradictions and limits of the evidence base

Four tensions are recorded rather than smoothed over.

Skills underperform context files in the one controlled comparison available, yet vendors promote skills heavily. Vercel found a skill produced zero improvement over baseline by default and went uninvoked in 56% of cases [2], while vendor documentation presents skills as a headline capability [5][9]. The tension resolves partly on task type — Vercel's caveat that "skills work better for vertical, action-specific workflows that users explicitly trigger" [2] is close to what Anthropic's own guidance says skills are for [3] — but a team reading vendor material alone would plausibly over-invest in skills. The eval is single-source, silent on model version, and unreplicated.

"Standardize on one tool" and "let the agents vary" are both defended. The drift argument favors standardization [22]; the only first-hand small-team account deliberately ran three agents concurrently and standardized process instead [36]. The reconciliation adopted above — hold the context and guardrails constant, let the agent vary — is a synthesis rather than a sourced finding.

Personal-over-project skill precedence contradicts the shared-configuration prescription. Claude Code resolves conflicts so that "personal overrides project" [5], which cuts directly against the recommendation that team conventions live in the repository [3][4]. This is documented behavior rather than an inconsistency among sources, but it means the prescription requires an active defense — namespacing or plugins — rather than holding by default.

Distribution-tier guidance is unsupported at the size boundaries. The submodule, script, and package progression [29] is asserted by one moderate-credibility source describing its own deployment, with no corroboration.

Beyond the contradictions, four limits bound everything above. The 5–20 band is thinly evidenced: exactly one source is a first-hand account of a team inside the target range, a five-person team, self-reported and without metrics [36]. The remaining case-study evidence comes from organizations of 170+ [38][37] or larger [39]. Ritual structures and configuration mechanisms plausibly transfer downward; cadences, headcounts, and attendance figures do not, and that boundary is marked at each occurrence above rather than laundered into small-team advice.

The most-circulated small-team case study is not usable as evidence. The widely-shared "30-dev shop" study carries a publisher disclaimer that it is an "illustrative anonymised composite" whose "specific numbers, artefact counts and quotes are illustrative constructions… rather than a single billed client" [44]. Its productivity, onboarding, and PR-velocity figures support no claim here, and readers encountering those numbers elsewhere should treat them as marketing.

Vendor documentation is over-represented. Vendors are the correct authority for mechanism — how precedence works, which file is gitignored, what a hook can block — and were treated as such. For outcome claims they are interested parties, and independent corroboration was required before stating that something works rather than that it exists.

Timing risk is unusually high. Every mechanism described here changed materially during the twelve months preceding August 2026 [5][19][17]. Version-specific details in particular — flags, setting names, precedence edge cases — should be verified against current documentation before being written into a team's onboarding guide; Anthropic's own Champion Kit carries that warning [12]. Four coverage gaps remain open: cost management at small-team scale, how mixed-discipline teams differ from pure engineering teams, non-English-language teams, and whether any of these patterns hold beyond a twelve-month horizon. No academic or peer-reviewed source evaluating team-level agentic configuration practice was located.