Session 7 of 8 Week 4

Session 7: Team Integration

Integrating AI-assisted development practices across your team with shared configuration, conventions, and adoption strategy.

Session 6 gave you the full power-user toolkit — MCP servers, skills, subagents, hooks, and more. This session shifts focus from individual mastery to team-wide adoption: building shared CLAUDE.md conventions, configuring permissions and settings for the whole team, and choosing an adoption strategy that sticks.

Team CLAUDE.md and Shared Conventions

What it is: A team CLAUDE.md is the single highest-impact step for making Claude Code consistent across your engineering group. It lives at the project root, gets committed to git, and tells Claude about your tech stack, testing conventions, API patterns, code style, and “do not” rules. Without it, every engineer’s Claude session starts from scratch — one person gets JUnit 5 with AssertJ, another gets JUnit 4 with Hamcrest, and a third gets TestNG. With a shared CLAUDE.md, every session follows the same conventions automatically. The file should start small (10-20 lines covering stack, test commands, and the biggest gotchas) and grow organically as the team discovers what Claude keeps getting wrong. Treat CLAUDE.md changes like code changes: review them in PRs and discuss them in standups. The most powerful evolution pattern is compounding engineering — when you catch Claude making a mistake in a PR, add the correction to CLAUDE.md in the same PR. If you install the Claude Code GitHub Action (/install-github-app), you can tag @claude in PR comments with instructions to update CLAUDE.md automatically. Over weeks, corrections accumulate and Claude’s mistake rate drops measurably.

Demo prompt:

Read the existing test files in src/services/ and src/test/services/.
Identify the common patterns: test framework, assertion library,
naming convention, mock strategy, setup/teardown approach.

Then draft a CLAUDE.md section called "## Testing" that encodes
these conventions so Claude follows them automatically.

Try it now: Open Claude in your team’s real project and ask it to read three to five similar files (services, controllers, or test files) and extract the shared conventions. Review what it produces — does it capture the patterns your team actually follows? Edit the output into a CLAUDE.md section you could commit today. If you already have a CLAUDE.md, ask Claude to audit it against the actual codebase: “Read CLAUDE.md and then read 5 representative source files. Are there conventions in the code that CLAUDE.md doesn’t mention?”

Go deeper: CLAUDE.md Configuration — the full hierarchy from enterprise settings to personal overrides, what to include, what to leave out, and how to evolve it over time.

Shared Configuration and Permissions

What it is: While CLAUDE.md handles instructions and conventions, .claude/settings.json handles permissions and environment — what Claude can run without asking, what requires confirmation, and what is completely blocked. This file is committed to git and shared by the entire team. The permission model has three levels: allow (runs silently — use for test runners, linters, and git read commands), deny (completely blocked — use for destructive operations like rm -rf, git push --force, or curl to external services), and everything else falls into ask (Claude prompts for confirmation each time). Permission rules support wildcards — Bash(npm run test:*) pre-approves any npm test subcommand, Read(./secrets/**) blocks reading anything in the secrets directory recursively. Getting this right means Claude can run tests hundreds of times per session without interrupting you, while dangerous commands are always gated. Personal overrides go in .claude/settings.local.json (git-ignored) so individual engineers can add permissions for their local Docker setup or database tools without affecting the team.

Demo prompt:

Read .claude/settings.json and show me:
1. What commands can you run without asking?
2. What commands are completely blocked?
3. What common operations (like running tests or linting)
   are NOT in the allow list but should be?

Suggest an updated settings.json that adds missing safe
commands to the allow list and blocks any dangerous
operations that are currently unblocked.

Try it now: Check your project for a .claude/settings.json file. If it exists, run the audit prompt above to find gaps. If it does not exist, create one using the appropriate template for your stack. Start conservative — allow only your test runners and git read commands, deny destructive operations, and let everything else require confirmation. After a week of use, review what Claude keeps asking permission for and promote safe, frequent operations to the allow list.

Go deeper: Hooks — event-driven automation (PreToolUse, PostToolUse, and more) that fires deterministically, complementing the permission system in settings.json.

AI Strategy and Adoption Patterns

What it is: Rolling out AI-assisted development to a team is a change management challenge, not just a tooling decision. The most successful adoption follows a phased approach: start with one or two champions who use Claude Code daily for two weeks, documenting what works and building the initial CLAUDE.md. Then expand to the full team with training, shared configuration, and regular check-ins. After a month, integrate into CI/CD pipelines and begin measuring impact. Finally, document learnings and scale to other teams. The biggest mistakes are forcing adoption (let engineers discover value organically), skipping CLAUDE.md (the single most impactful setup step), starting too permissive with security settings, and not measuring results so you cannot demonstrate ROI. AI is also not just for writing code — it accelerates planning (requirements analysis, estimation, ADRs), review (first-pass code review, security audits), and operations (incident response, postmortems, runbook creation).

Demo prompt:

I'm leading AI adoption for a team of 6 engineers working on
a Java/React application. We've been using Claude Code individually
for 2 weeks. Help me create a 30-day adoption plan:

1. What shared configuration should we set up this week?
2. What conventions should go in our team CLAUDE.md first?
3. How should we measure whether this is working?
4. What common pitfalls should I watch for?

Be specific to our stack and team size.

Try it now: Think about your own team’s adoption stage. Are you a solo champion exploring Claude Code, or has the whole team started using it? Ask Claude to assess your current state and recommend next steps: “We’re a team of [N] engineers. [Describe current usage]. What should our next adoption milestone be, and what do we need to set up to get there?” Compare its recommendations to the phased rollout in the strategy guide.

Go deeper: Cheat Sheets — quick-reference prompts for every phase of development that your team can start using immediately. Continued Learning — Anthropic’s Skilljar courses, documentation, and community resources for ongoing skill development.

Key Takeaways

  • A shared CLAUDE.md is the single highest-impact step for team adoption. Start with 10-20 lines covering your stack, test commands, and top conventions — then grow it based on real pain points.
  • Permissions in .claude/settings.json should start conservative: allow test runners and read-only git commands, deny destructive operations, and let everything else require confirmation. Use wildcard patterns (Bash(npm run test:*)) to pre-approve whole categories of safe commands.
  • Compounding engineering: every time you catch Claude making a mistake in a PR, add the correction to CLAUDE.md. Over weeks, corrections accumulate and Claude’s output quality improves measurably.
  • Personal preferences belong in git-ignored files (CLAUDE.local.md and .claude/settings.local.json) so the team config stays clean and universal.
  • Successful adoption is phased: champion first, then team-wide training, then CI/CD integration, then scaling. Forcing adoption or skipping configuration steps leads to frustration and abandonment.
  • AI-assisted development extends beyond code generation. The biggest long-term wins come from applying it across planning, review, testing, and operations.
  • Teach your team context management: /compact between workflow phases, /clear between unrelated tasks, and session naming for multi-day work.
  • Standardize on a default model for your team and document cost expectations. Engineers can override locally, but a shared default prevents confusion.

Practice

If team members are at different experience levels with Claude Code, direct them to the right starting point: Foundations Scenarios for first-time users, Intermediate Scenarios for those comfortable with the basics, or Advanced Scenarios for engineers ready to use subagents and MCP servers.