Using Claude Code in a Team

Claude Code delivers different results for different people on the same team — unless the team agrees on how to use it. Without shared practices, one developer gets precise, well-structured output while another gets inconsistent results on the same codebase. Shared standards make Claude Code a team-wide multiplier instead of an individual tool.

Why Teams Need Claude Code Guidelines

When each developer uses Claude differently, three problems emerge:

Problem 1 — Inconsistent code style
Developer A asks Claude to write functional components.
Developer B asks Claude to write class components.
The codebase mixes both. Maintenance becomes harder.

Problem 2 — Conflicting conventions
Developer A tells Claude to use async/await.
Developer B tells Claude to use Promise chains.
Both approaches appear in the same module.

Problem 3 — Security gaps
Developer A always asks Claude to add input validation.
Developer B accepts the generated code as-is.
Some routes are protected, some are not.

Team guidelines prevent these problems before they appear.

The CLAUDE.md Team File

The most effective team practice is a shared CLAUDE.md file at the root of the project repository. Every team member's Claude Code session reads this file automatically at startup. It becomes the single source of truth for how Claude behaves on your project.

What to Put in the Team CLAUDE.md

# Project: [Name]
# Purpose: [One sentence about what this does]

## Stack
- Language: TypeScript 5.2 (strict mode, no `any`)
- Framework: Next.js 14 App Router
- Database: PostgreSQL + Prisma ORM
- Testing: Vitest + React Testing Library
- Styles: Tailwind CSS (no inline styles)

## Code Conventions
- All components: functional, named exports only
- API routes: always validate input with Zod
- Error handling: use Result type, do not throw
- Commits: conventional commits format
- Functions: max 30 lines, single responsibility

## Security Rules
- Never hardcode credentials — use process.env
- All inputs validated before database writes
- Auth middleware required on all /api/protected routes

## What Claude Should Never Do
- Add new dependencies without a comment explaining why
- Change the database schema without noting it clearly
- Use console.log in production code
- Write inline SQL — always use Prisma query builder

This file travels with the codebase. New team members get Claude aligned with project standards from day one without a lengthy orientation.

Shared Prompt Library

A prompt library is a collection of pre-written prompts that the team reuses for common tasks. Instead of each developer crafting their own prompt for the same type of work, the team agrees on the best prompt once and everyone uses it.

Where to Keep Shared Prompts

Option 1: A /prompts folder in the repo
  /prompts/new-api-route.md
  /prompts/code-review.md
  /prompts/write-tests.md
  /prompts/write-migration.md

Option 2: A team Notion or Confluence page

Option 3: A team README section titled "Claude Prompts"

Example Shared Prompt — New API Route

## Prompt: Create New API Route
─────────────────────────────────────────────────────────
"Create a [METHOD] API route at [/path] in our Next.js
App Router project. Follow these requirements:
- Validate request body with Zod schema
- Use Prisma for database operations
- Return typed ApiResponse<T> — see types/api.ts
- Add requireAuth middleware
- Handle errors with our AppError class
- Write a Vitest test file alongside the route

Entity name: [entity]
Fields: [list fields and types]"
─────────────────────────────────────────────────────────

Every developer fills in the bracketed placeholders. The core prompt stays the same. The generated route matches your team's standards every time.

Code Review Workflows With Claude

Claude Code fits into your existing pull request review process as a first-pass reviewer. The human reviewer focuses on architecture decisions, business logic, and team fit. Claude handles the mechanical checks.

Two-Stage Review Process

STAGE 1 — Claude Review (automated, fast)
Developer asks Claude to review their PR diff before submitting.
Claude checks: bugs, security, style, missing tests.
Developer fixes issues found.
        ↓
STAGE 2 — Human Review (focused, high-value)
Human reviewer sees code that already passed Claude's checks.
Human reviewer focuses on: design decisions, team context,
long-term maintainability, business logic correctness.

This approach makes human review faster. Reviewers spend less time on mechanical issues and more time on the things only a human can judge.

Shared Code Review Prompt

"Review this pull request diff as a senior engineer
on our team. Check against our CLAUDE.md standards.
Flag: bugs, missing validation, auth gaps, missing tests,
and any code that violates our conventions.
Format findings as: ISSUE / SEVERITY / LINE / FIX"

Onboarding New Developers With Claude

New developers need time to learn a codebase before they contribute effectively. Claude Code compresses that ramp-up significantly.

Day-One Onboarding Flow

Hour 1: Read CLAUDE.md — understand team conventions
        ↓
Hour 2: Ask Claude to explain the project architecture
        "Explain how this Next.js codebase is organized.
         What is the purpose of each folder in /src?"
        ↓
Hour 3: Ask Claude to walk through a key existing feature
        "Explain how user authentication works in this codebase,
         from the login form to the JWT cookie."
        ↓
Day 2:  First task — use team prompts to generate code
        Claude follows team standards automatically via CLAUDE.md

Codebase Exploration Prompts for New Hires

"Explain the data flow when a user submits the checkout form."

"What does the UserService class do? What are its dependencies?"

"Which files would I need to change to add a new field
to the Product model?"

"What testing patterns does this project use?
Show me an example test and explain the pattern."

Documentation as a Team Practice

Documentation falls behind because writing it takes time no one has. Claude Code makes documentation fast enough to keep up with development.

Assign Claude Documentation Tasks in Your Workflow

Before merging a PR:
"Write a README section documenting the new
/api/webhooks/stripe endpoint. Include:
what it does, expected payload, and error responses."

After a sprint:
"Read the files changed in this sprint's PRs and
write a changelog entry for version 2.4.0."

When refactoring:
"The AuthService class just changed significantly.
Update the JSDoc comments to match the new behavior."

Setting Boundaries — What the Team Uses Claude For

Some teams use Claude for everything. Others restrict it to specific tasks. Both approaches work, but the team should agree explicitly rather than leaving it unspoken.

Areas Where Most Teams Use Claude

✅ Boilerplate generation (CRUD, forms, API routes)
✅ Test writing
✅ Documentation
✅ Code review first pass
✅ Commit messages and PR descriptions
✅ Debugging help
✅ Script writing for one-off tasks

Areas Where Many Teams Apply Extra Caution

⚠ Core business logic (always human-reviewed carefully)
⚠ Authentication and authorization code
⚠ Database migrations (irreversible changes)
⚠ Payment processing logic
⚠ Data deletion or cleanup scripts

Define these boundaries in a team document so every developer knows where Claude's output requires extra scrutiny.

Measuring the Impact on the Team

Track a few simple metrics to understand whether Claude Code is helping your team. This also shows leadership concrete value from the investment.

Metric                    │ How to measure
──────────────────────────┼──────────────────────────────
PR review time            │ Average time from open to merge
Test coverage %           │ Coverage report before and after
Documentation freshness   │ Time since last doc update
Bug rate in new code      │ Bugs found per feature shipped
Onboarding time           │ Days until first PR merged

Key Points

  • A shared CLAUDE.md file in the project root aligns Claude's behavior for every team member automatically
  • A prompt library saves time and ensures consistency — the team writes the best prompt once and everyone reuses it
  • Use Claude as a first-pass code reviewer so human reviewers can focus on architecture and business logic
  • New developers can use Claude to explore and understand an unfamiliar codebase much faster than reading alone
  • Assign Claude documentation tasks as part of the PR process — it keeps docs current without adding developer burden
  • Agree as a team on which areas require extra human scrutiny — especially auth, payments, and database migrations
Previous lessons
Back to courses
Next lessons

Leave a Comment