TopolearnA team gets consistent, safe results only when instructions, permissions and extensions are versioned and reviewed like code.
On a team, every developer's Claude should follow the same conventions and safety rules. The tool supports this through layers you already know, used deliberately.
Commit the shared layer. The repository's .claude/ folder holds settings.json (permissions, hooks, enabled plugins), skills/, agents/ and rules/, next to CLAUDE.md and .mcp.json. Review changes to them in pull requests exactly like code: a new hook or MCP server runs on every teammate's machine. Personal tweaks stay in .claude/settings.local.json, CLAUDE.local.md and ~/.claude/.
Keep always-loaded context small. In a large repo a single CLAUDE.md grows until rules get ignored. Split it:
- nested
CLAUDE.mdfiles in subprojects load only when Claude works there, .claude/rules/*.mdwith apaths:list in frontmatter load only for matching files,- long procedures become skills,
claudeMdExcludesskips other teams' instruction files in a monorepo.
If the repo also serves other agents, an AGENTS.md can be the shared file; a CLAUDE.md containing @AGENTS.md imports it and adds Claude-specific notes.
Enforce with managed settings. Organization admins can deploy managed settings (by file, device management or the claude.ai admin console) and a managed CLAUDE.md. Managed keys override everything else: required deny rules, sandbox enforcement, allowed models, disabling bypassPermissions or auto mode, and restricting which hooks, MCP servers and plugin marketplaces may run. Use managed settings for rules that must hold, and CLAUDE.md for guidance.
Measure and iterate. /insights reports how you use Claude Code and where sessions go wrong; usage dashboards and telemetry export cover whole teams. Prune instructions that no longer change behavior, and turn rules Claude keeps missing into hooks or permissions.
Example
repo/
├── CLAUDE.md # short: commands, conventions, gotchas
├── .mcp.json # shared MCP servers (reviewed in PRs)
├── .claude/
│ ├── settings.json # team permissions, hooks, enabledPlugins
│ ├── rules/
│ │ ├── api.md # frontmatter: paths: ["src/api/**/*.ts"]
│ │ └── testing.md
│ ├── skills/release/SKILL.md # /release, disable-model-invocation: true
│ └── agents/reviewer.md # fresh-context reviewer subagent
├── services/payments/CLAUDE.md # loads only when working in payments/
└── .gitignore # CLAUDE.local.md, .claude/settings.local.jsonRemember
- Commit .claude/ (settings, rules, skills, agents) and review it like code
- Keep always-on context small with nested CLAUDE.md, path-scoped rules and skills
- Managed settings enforce org policy; CLAUDE.md only guides
Watch out for
- Merging a teammate's new project hook or MCP server without review, which then runs on everyone's machine.