Claude Code Workflow for Teams: Setup and Best Practices

The gap we keep seeing: Individual engineers on a team get 20 to 40% productivity gains from Claude Code. The team as a whole does not. The difference is always the same: no shared context, no shared standards.

Why individual vs. team adoption matters

When a single engineer uses Claude Code, they benefit from their own coding standards being implicit context. When they ask Claude to write a component, it reflects their style. When they ask for tests, the output is close to what they would write.

When a second engineer on the same team uses Claude Code, their component looks different. Different naming conventions, different error handling patterns, different test styles. Two inconsistent AI-generated codebases merge together, and the thing that was supposed to improve consistency has made it worse.

The solution is shared context: a CLAUDE.md file that all engineers use, .cursor/rules/ that enforce project conventions, and shared slash commands that standardize high-frequency tasks. Setting this up takes 1 to 2 weeks. The benefit compounds for years.

The CLAUDE.md structure that works

Most CLAUDE.md files we see in the wild are either too vague (“write clean code”) or too long (a 5,000-word document nobody reads). The right length is 300 to 500 words. It should answer exactly three questions:

1. What is this project and what stack does it use?
2. What are the conventions the AI needs to know that are not obvious from the codebase?
3. What should the AI never do?

Here’s the structure we use:

# Project Context
[2-3 sentences about what the product does and who uses it]

## Stack
- Frontend: Next.js 15 (App Router), TypeScript strict, Tailwind v4
- Backend: tRPC v11, Prisma 6, PostgreSQL on Neon
- Auth: Better Auth with email + Google OAuth
- Testing: Vitest + Testing Library + Playwright for E2E

## Conventions

### TypeScript
- Strict mode, no `any`, no `@ts-ignore` without a comment explaining why
- Zod for all external input validation (API routes, form data, URL params)
- Prefer `type` over `interface` for most things; use `interface` only for things that get extended

### React patterns
- Server Components by default, Client Components only when you need interactivity
- Custom hooks live in `/hooks/` and start with `use`
- No prop drilling beyond 2 levels, use context or Jotai
- Every user-triggered mutation gets a loading state and an error state

### API routes (tRPC procedures)
- Protected procedures check auth with `protectedProcedure`, not manual session checks
- All procedures have Zod input schemas
- Errors thrown with `TRPCError`, never raw `Error`

### Database
- All queries through Prisma, no raw SQL unless there's a specific performance reason
- Use transactions for anything that touches more than one table
- Never query in a loop, always batch

## Always
- Add error handling to every async function
- Write at least one test for every utility function added
- Use the project's existing component library before creating a new component

## Never
- `console.log` in production code, use the `logger` utility
- Hardcode environment-specific values, use env vars
- Skip the loading state on mutations
- Add a package without asking first, check if there's an existing utility

Concise. Specific. Refers to actual packages the project uses. The “never” section is the most important part. It encodes the issues that surface in code review repeatedly.

The .cursor/rules/ setup

Cursor supports per-glob rules files in .cursor/rules/. These are auto-applied when the matched files are in context. This is where you put the more detailed conventions that do not need to be visible all the time.

Useful rules files for a typical TypeScript project:

api.mdc (applied to src/server/api/**/*.ts):

All tRPC procedures must:
- Use protectedProcedure for anything that touches user data
- Have explicit Zod input validation
- Return typed outputs (not unknown)
- Use ctx.db for database access, never instantiate PrismaClient directly

Error handling:
- Database errors: catch and throw TRPCError with code 'INTERNAL_SERVER_ERROR'
- Auth failures: throw TRPCError with code 'UNAUTHORIZED'
- Not found: TRPCError with code 'NOT_FOUND'
- Validation failures: handled by tRPC automatically from Zod schemas

components.mdc (applied to src/components/**/*.tsx):

Component conventions:
- File name: PascalCase, one component per file
- Props interface: ComponentNameProps, defined above the component
- No default exports, named exports only
- Styles: Tailwind only, no inline styles, no CSS modules
- Icons: lucide-react only, no other icon libraries
- No hardcoded strings visible to users, all user-facing strings should use the i18n helper

tests.mdc (applied to **/*.test.ts, **/*.test.tsx):

Testing conventions:
- Describe blocks match the module/function being tested
- Test names: "should [expected behavior] when [condition]"
- Mock at the module level, not inside test bodies
- Prefer Testing Library queries in priority order: getByRole > getByLabelText > getByText > getByTestId
- Never use implementation details (internal state, private methods) in assertions
- Every async test must have an awaited assertion or an explicit timeout

The three slash commands that change daily workflow

Slash commands are the highest-leverage addition to a team Claude Code setup. They turn repeated prompts into one-word invocations. The three we add to every project:

/pr-review

Review the staged changes for this PR. Check for:
1. The six common issues in CLAUDE.md
2. Missing error handling on any async operations  
3. Any hardcoded values that should be env vars
4. Test coverage, is there a test for any new utility function?
5. Type safety, any `any` types or type assertions without comments?

Format: bullet list of issues found, with file:line references. If nothing found, say so explicitly.

/add-tests

Generate Vitest tests for the file at [file path].
- Test every exported function
- Cover the happy path and at least 2 error cases per function
- Use the mocking patterns from the existing test files in the same directory
- Don't test implementation details, test observable behavior
- Target: 80% branch coverage on this file

/update-schema

I've updated the Prisma schema. Generate:
1. The migration SQL (don't run it, just show it)
2. Any TypeScript types or Zod schemas that need to change
3. Any tRPC procedures that need to be updated to handle the schema change
4. A checklist of places in the codebase that might be affected

Add these to a .claude/commands/ directory in the repo. All engineers get them automatically.

The habits that make the difference

Code review the AI’s output, not just the functionality. A passing test suite does not mean the code is good. The AI may produce code that is functionally correct but does not follow conventions. Review Claude Code’s output with the same standards you would apply to a PR from a contractor who is unfamiliar with your codebase.

Iterate on the CLAUDE.md when you see patterns. If the same issue appears in three separate AI-generated PRs, it belongs in CLAUDE.md or a rules file. The document should evolve with the codebase.

Keep task scope small. “Refactor the auth system” is too large. “Add rate limiting to the login endpoint” is right-sized. Smaller tasks produce more predictable AI output and are easier to review.

Use Claude Code for what it handles well: generating boilerplate, writing tests for known-correct code, exploring unfamiliar APIs, and drafting first versions of new utilities. Apply human judgment for architecture decisions, security-sensitive code, and anything requiring deep context about business logic.

Do not use it when you need to think. Writing code is thinking. If you are working out the architecture of a new feature, start with a diagram, a conversation with a colleague, or a spec document. Bring Claude Code in once you know what you are building, not to figure out what you are building.

The measurement

We track before and after for every team setup engagement:

• Sprint velocity (features shipped per sprint)
• PR first-pass approval rate (PRs approved without change requests)
• Review cycle count (average rounds of review per PR)
• Test coverage trend

Typical 8-week results: velocity up 2 to 3 times, first-pass approval rate up from approximately 30% to 60%, average review cycles down from 2.8 to 1.4. The consistency gains often matter more than the velocity gains. Predictable output is easier to plan around than occasional bursts.

The setup takes 2 weeks. The payoff compounds for as long as the team exists.