Working with AI in a Team

The Coordination Gap

When you use AI by yourself, your setup is entirely your own. Your system prompts, your .cursorrules, your prompt habits — they live on your machine and evolve with your preferences. You tune them over time. They get good because you use them constantly and fix what doesn't work.

When you work on a team, this breaks in two specific ways.

The divergence problem. Eight developers, each with their own AI configuration, each building slightly different habits around prompting, each getting slightly different output. One person always asks for tests. One never does. One gets results in the team's error-handling style. Another gets a different pattern that AI invented. Over time, the codebase accumulates these variations. Reviews get harder. Patterns are inconsistent. Nobody is wrong — but nobody is coordinated.

The knowledge silo problem. You've spent three weeks learning what prompts work well for your specific codebase — how to ask for code that fits your service layer, how to get tests in the right format, what context AI needs to stop hallucinating the internal API. That knowledge lives in your head. When a teammate asks AI for the same thing, they're starting from scratch. A solution that took you three hours to arrive at takes them a whole day.

This guide covers four areas: shared context files (where AI gets its instructions), AI in the PR workflow (before and during review), shared prompt strategies (accumulated team knowledge), and onboarding (using AI to learn a new codebase and teaching others to do the same).

Part 1: Shared Context Files

Every major AI coding tool reads a project-level configuration file that tells it how to behave in your specific codebase. These files are the single highest-leverage place for team coordination around AI. When they're good, every developer's AI sessions start with the right context automatically. When they're missing or neglected, every session starts from scratch.

The Files and What They Do

The file format varies by tool, but the concept is the same: instructions that AI reads at the start of every session, before you say anything.

• Claude Code: CLAUDE.md in the project root. Also supports CLAUDE.md files in subdirectories for module-specific instructions.
• Cursor: .cursorrules (legacy, still works) or .cursor/rules/ directory with .mdc files — one rule file per concern.
• GitHub Copilot: .github/copilot-instructions.md
• Windsurf: .windsurfrules in the project root

All of these files should live in version control. They're part of the project, not part of an individual developer's setup.

What to Put in the Context File

The goal is to tell AI everything it needs to generate code that fits your codebase — without you explaining it in every session. A useful team context file covers:

# [Project Name] — AI Context

## Stack
# List versions that matter. AI's training data contains multiple
# versions of every library. Specifying versions prevents it from
# suggesting deprecated patterns.
- TypeScript 5.x, Node.js 20+
- Express 4.x — NOT Fastify, NOT Hono
- PostgreSQL via Kysely (NOT TypeORM, NOT raw SQL except migrations)
- Zod for validation — applied at every API boundary
- Vitest for unit tests, Supertest for integration tests

## Project structure
# Tell AI where things live so it puts new code in the right place.
- src/routes/     — route handlers (thin, no business logic here)
- src/services/   — business logic
- src/db/queries/ — database queries (never inline in services)
- src/middleware/  — Express middleware
- src/types/       — shared TypeScript types
- tests/           — mirrors src/ structure

## Patterns to follow
# Positive instructions: what to do.
- Use Result<T, AppError> return types for operations that can fail
- Log with the logger at src/lib/logger.ts — never console.log
- Read config from src/config.ts — never process.env directly
- Service functions are pure: no request/response objects

## Patterns to avoid
# Negative instructions are often more important than positive ones.
# AI will default to these patterns if you don't explicitly forbid them.
- Do NOT use `any` in TypeScript — use `unknown` and narrow explicitly
- Do NOT put business logic in route handlers or middleware
- Do NOT use class components in React — functional components only
- Do NOT import directly from node_modules paths — use the re-exports in src/lib/

## Security rules (non-negotiable)
# Security constraints stated here apply to every session automatically.
- Never log request bodies that may contain passwords, tokens, or PII
- All external input must pass Zod validation before touching business logic
- Use parameterized queries — never string-concatenate SQL
- Auth middleware is src/middleware/auth.ts — always apply to protected routes
- No hard-coded secrets, even in tests — use environment variables

## Testing conventions
- Every service function needs a unit test
- Every API endpoint needs an integration test against a test database
- Test files live next to source files: src/services/user.ts → src/services/user.test.ts
- Use describe/it blocks, not test()
- Mock at the module boundary, not inside functions

Cursor's Rule Files in Depth

Cursor's .cursor/rules/ directory lets you split your context into multiple files, each activated differently. This is useful for larger teams where different parts of the codebase have different conventions.

.cursor/rules/
  base.mdc           # Always active — core stack, patterns, security rules
  frontend.mdc       # Active when editing files in src/components/ or src/pages/
  backend.mdc        # Active when editing files in src/routes/ or src/services/
  migrations.mdc     # Active when editing files in migrations/
  tests.mdc          # Active when editing *.test.ts or *.spec.ts files

---
description: Rules for writing database migrations
globs: migrations/**/*.ts, migrations/**/*.sql
alwaysApply: false
---

# Migration Rules

- All migrations are irreversible by default — write them to be safe to run in production
- Never DROP COLUMN or DROP TABLE in a migration — mark columns as deprecated in a comment and schedule removal for a future release
- Add indexes in a separate migration from the column change — never in the same ALTER TABLE
- Migrations run in filename order — prefix with timestamp: 20260414_add_user_roles.ts
- Test migrations against a copy of production schema before merging
- Every migration needs a corresponding rollback script in migrations/rollbacks/

The globs field activates the rule only when the open file matches the pattern. Developers editing a migration file automatically get migration-specific rules without those rules polluting every other context.

Maintaining the Context File as a Team

The context file is a living document. It should evolve as your codebase evolves, as you discover new AI failure modes, and as your conventions change. The maintenance process is simple but important:

• Changes go through PR review. The context file affects every developer's AI sessions. A change that adds a bad instruction causes AI to generate wrong code for the whole team. Treat it with the same care as a shared library.
• Update after AI failures. When AI generates code that violates a convention — wrong error handling, wrong logging pattern, missing validation — add a rule to prevent it from happening again. This is how the file gets good over time.
• Keep it honest. An outdated rule is worse than no rule. If you migrated from TypeORM to Kysely, remove the TypeORM section. AI will follow stale instructions as faithfully as current ones.
• One owner, team contributions. Designate someone to merge changes — not to gatekeep, but to prevent conflicts and ensure consistency. Anyone on the team should be able to propose additions.

What Doesn't Belong in the Context File

The context file is not a style guide, a wiki, or a document for human readers. Keep it focused on instructions AI needs to generate code correctly:

• Don't explain why a rule exists — state the rule. (Why belongs in ADRs or comments, not in AI instructions.)
• Don't include information AI can infer from the code — like your folder structure if it's already self-evident.
• Don't put aspirational guidelines in there — only rules you'll actually enforce. If AI violates a rule and nobody notices, the rule doesn't belong in the file.
• Don't include sensitive information — the context file is in version control and may be sent to AI providers' APIs.

Part 2: AI in PR Review

Pull request review is where the quality of AI-generated code gets tested. It's also the place where teams accumulate the most inconsistency in how they handle AI. Some developers disclose everything. Some disclose nothing. Some use AI to review before submitting. Some submit immediately. Without a shared approach, reviewers can't calibrate their expectations.

Before You Open the PR: AI Self-Review

The most valuable use of AI in the PR workflow happens before review opens — when you review your own AI-assisted work before anyone else sees it. This catches the category of errors that AI is most likely to introduce: hallucinated API usage, missing error paths, authorization gaps.

The key is adversarial framing. Don't ask AI to validate your code — ask it to find problems:

Run this on every PR where AI did significant work. You'll catch a category of issues that your own review misses — because when you wrote the code alongside AI, you're too close to it to see the gaps.

What to Include in the PR Description

The standard PR description was designed for human-authored code. For AI-assisted PRs, reviewers need additional information to calibrate their review depth and attention. A minimal addition to your PR template:

## AI assistance
- [ ] Fully AI-generated from prompt
- [ ] AI-suggested approach, manually implemented
- [ ] AI-assisted (significant manual modification)
- [ ] Human-written with AI review only

## Self-review checklist (AI-assisted PRs)
- [ ] Verified all external API calls exist in the version we're using
- [ ] Manually tested error paths, not just happy path
- [ ] Checked authorization, not just authentication
- [ ] Database operations are transaction-safe
- [ ] No sensitive data in logs

## Where to look hardest
[What parts of this PR are you least confident about?
Where did AI struggle? Where did you override AI suggestions?]

The "where to look hardest" field is the most valuable addition. AI-assisted code often has a specific part where the developer was uncertain — where AI gave plausible-but-unverified output, or where the domain complexity exceeded what AI could handle well. Making that uncertainty explicit directs reviewer attention to where it's most needed.

How Reviewers Should Use AI on PRs

Reviewers can use AI as a second reader — distinct from the author, with no prior context, asked to be adversarial. The value is that AI has no social pressure to be polite. It will name problems a human reviewer might soften.

Note the instruction to paste the relevant rules from your CLAUDE.md. Without this context, AI doesn't know what your team's standard patterns are, and it can't flag deviations.

The Speed Asymmetry Problem

AI writes code faster than humans review it. If a developer can produce three features a day with AI assistance, review becomes the bottleneck. The temptation is to review faster — to skim, to approve on the assumption that "AI probably got it right."

This is wrong in the specific direction AI fails. AI errors aren't random typos or syntax mistakes that jump out in a quick skim. They're structural: a method that doesn't exist, a missing authorization check, a database operation outside a transaction. These require deliberate reading, not faster reading.

The solution is tiered review — deciding how much attention a PR needs based on risk, not volume:

• Deep review (two reviewers, full verification): Auth changes, database schema changes, anything in the payment or billing flow, admin functionality, data export, security-sensitive middleware.
• Standard review (one thorough reviewer): New features, API endpoints, significant business logic changes.
• Light review (spot-check): Tests, documentation, configuration changes, UI-only changes with no business logic.

Classify PRs at creation time. The author self-declares a tier; reviewers can escalate. This keeps review quality high where it matters without creating a bottleneck on low-risk changes.

Part 3: Team Prompt Strategies

Good prompts are discovered, not invented. A prompt that works well for your codebase — that generates code in the right style, catches the right issues, asks the right clarifying questions — represents accumulated learning that took time to arrive at. That learning shouldn't live in one person's head.

A shared prompt library is how teams capture that learning. Not a Notion document with a few examples — a version-controlled set of prompts, structured for reuse, with honest documentation of where each prompt works and where it doesn't.

What Belongs in the Team Library

The criterion is simple: does this prompt depend on knowing your team's specific stack, conventions, or codebase? If yes, it belongs in the team library. Generic prompts that work anywhere don't need to be shared — they're the same for everyone.

Good candidates for a team prompt library:

• Code review prompts that reference your specific security requirements and coding conventions
• Test generation prompts that follow your testing framework and naming conventions
• Feature implementation prompts that include your error handling and response formats
• PR description generation prompts matched to your team's PR template
• Debugging prompts tuned to your logging format and error code structure
• Onboarding prompts for exploring unfamiliar parts of the codebase
• Migration prompts that know your database migration conventions

Structure for Reusable Prompts

A prompt that works for you in your session often doesn't work for a teammate who doesn't have the surrounding context you had. Reusable prompts need to be self-contained — enough context baked in that anyone on the team can use them without additional explanation.

# New API Endpoint

## When to use
When adding a new route to the Express API.

## Context to provide before using this prompt
- Paste the relevant Zod schema (or describe the data shape)
- Describe what the endpoint should do
- Mention which service functions already exist vs. which need to be created

## The prompt
I need to add a new API endpoint to our Express/TypeScript/PostgreSQL application.

Stack context:
- Routes go in src/routes/ — thin handlers only, no business logic
- Business logic goes in src/services/ — plain functions, no req/res
- Database queries in src/db/queries/ — using Kysely
- All inputs validated with Zod before reaching service layer
- Services return Result<T, AppError> — never throw from services
- Errors are handled by the global error handler in src/middleware/errors.ts
- Use the logger at src/lib/logger.ts — never console.log

Endpoint spec:
[DESCRIBE THE ENDPOINT HERE]

Please:
1. Create the Zod validation schema for the request
2. Create the route handler in src/routes/[ROUTE FILE]
3. Create or update the service function in src/services/[SERVICE FILE]
4. Add the database query to src/db/queries/[QUERY FILE] if needed
5. Write unit tests for the service function
6. Write an integration test for the route using Supertest

## Expected output
Separate code blocks for each file, with the file path as the label.
Each file should be complete and importable without modification.

## Known limitations
- Does not generate DB migrations — run that separately
- May not know about custom middleware applied to specific route groups — check src/routes/index.ts
- Integration tests may need the test DB seed updated if new data shapes are needed

Where to Store the Prompt Library

The library lives in the repository, in a prompts/ directory at the root. Organized by category, version-controlled, reviewed like code. Not in Notion, not in a shared Slack channel, not as bookmarks in someone's browser.

prompts/
  README.md              # How to use the library, how to contribute
  backend/
    new-api-endpoint.md
    add-validation.md
    security-review.md
    database-query.md
  frontend/
    new-component.md
    add-form.md
    state-management.md
  review/
    pre-submit-review.md
    security-check.md
    pr-description.md
  testing/
    unit-test-generation.md
    integration-test.md
    edge-cases.md
  debugging/
    error-investigation.md
    performance-analysis.md
  onboarding/
    explore-module.md
    understand-flow.md

Contributing a New Prompt

The contribution process should be lightweight — a PR with the prompt file and a brief note about what problem it solves. The review bar is practical, not pedantic:

• Does the prompt have a clear "when to use" section?
• Does it specify what context to provide before using it?
• Does it document known limitations honestly?
• Has the contributor tested it at least twice on real problems?

A prompt that meets these criteria is better than most of what individuals run in their personal sessions. The bar isn't perfection — it's "documented and tested."

Keeping the Library Useful

Prompt libraries decay. Dependencies major-version. Conventions change. New patterns replace old ones. A stale prompt library is worse than no library — people discover the prompts are wrong and stop trusting all of them.

• Update triggers: When a dependency upgrades, run through prompts that reference it. When a convention changes, update affected prompts in the same PR as the convention change.
• Retire prompts: Delete prompts that no longer apply. A smaller, trusted library beats a large untrusted one.
• Add to the retrospective: Once a sprint, ask: which prompts produced bad output this sprint? That's a maintenance signal — the prompt needs updating, the context file needs a rule, or the prompt should be retired.

Part 4: Onboarding with AI

Joining a new codebase is one of the hardest things a developer does. The first weeks are spent pattern-matching: how does error handling work here, where does business logic live, how are tests structured, which parts of the code are stable and which are in flux. Previously this required a mix of documentation (sparse), pair programming (expensive), and reading a lot of code (slow).

AI changes this significantly. You can ask the codebase to explain itself.

The First Day: Getting the Mental Model

On day one, before writing a single line of code, spend an hour with AI building a map of how the system works. This isn't about generating code — it's about understanding enough to generate code correctly later.

This conversation produces something that would take days to assemble from documentation: a concise explanation of how this specific codebase works, in language calibrated to what you actually asked about. It's not perfect — AI will occasionally misread patterns or miss context that's obvious to experienced team members — but it's dramatically faster than reading code cold.

The Onboarding Prompt Set

Several prompts are worth having in the library specifically for new joiners:

# Explore an Unfamiliar Module

## When to use
When you need to understand a part of the codebase before making changes to it.

## Context to provide
- Paste the files in the module you need to understand
- Describe what you're trying to do (what change are you planning to make?)

## The prompt
I'm about to make changes to [MODULE NAME] in our codebase. I'm not yet familiar with this part.
Please explain:

1. What this module is responsible for (its role in the system)
2. What the main data flows are — how data enters, transforms, and leaves
3. What patterns this module uses for error handling and validation
4. What tests exist and what they cover
5. What I should be careful not to break when making changes in this area
6. What I should read next to understand the parts that depend on this module

Files I'm attaching: [LIST THE FILES]

Be specific to these files, not generic. If something is unclear or I've given you
insufficient context, tell me what additional files would help.

## Expected output
A structured explanation with the five sections above. Specific references to
the actual code patterns you see in the files provided.

## Known limitations
- AI builds its explanation from the files you provide — if you miss an important
  dependency, the explanation will be incomplete
- May miss informal conventions that aren't visible in the code (ask a teammate for those)
- Should be treated as a starting point for understanding, not a definitive reference

# Trace a Request Flow

## When to use
When you want to understand how a specific user action is handled end-to-end.

## Context to provide
Describe the user action or API call you want to trace.
Paste the relevant route handler, service, and DB query files.

## The prompt
Trace this request through the system: [DESCRIBE THE REQUEST — e.g., "POST /tasks with a title, due date, and project_id"]

Walk through each step:
1. Where does validation happen? What gets rejected and why?
2. What does the route handler do with valid input?
3. What does the service layer do? What can fail here?
4. What database operation happens? What does the query return?
5. How does the response get built?
6. What does the error path look like if the database is unavailable? If the input is invalid? If the user doesn't have permission?

Reference actual function names and file paths from the code I've provided.

## Expected output
A numbered walkthrough with specific references to functions and files.
Separate "happy path" from "error paths."

Onboarding New Teammates

When a new developer joins your team, the context file and prompt library you've built are as useful for onboarding as they are for daily development. During onboarding:

• Walk through the context file together. Don't just hand it to the new person — read through it with them. Explain why each rule exists. The decisions encoded in the file are exactly the things new teammates need to internalize, and hearing the reasoning is faster than inferring it from the rule alone.
• Point them to the prompt library. Show them the two or three prompts they'll use most in the first week. Let them use a prompt on their first real task — not as a shortcut, but to see how the team works with AI in practice.
• Share two or three real examples. Find PRs from the past month that demonstrate good AI use in the codebase — where AI generated something solid — and one or two where AI got something wrong and it was caught in review. Real examples from the actual codebase are worth more than abstract principles.
• Give them a low-stakes first task. Something where AI can do 70% of the work and they need to figure out the 30% — a new utility function, an additional test, a small endpoint. The goal is to experience the workflow before working on anything critical.

Using AI to Update Onboarding Materials

Onboarding documentation is the thing that gets most outdated fastest. Every team has a README that describes the architecture from two years ago. AI can help keep it current:

This doesn't write the documentation for you — it tells you what to fix. Run it every quarter, or before every significant new hire. The actual writing still needs human judgment, but identifying gaps is a mechanical task AI does well.

Part 5: Day-to-Day Team Habits

Beyond the systems — the context file, the prompt library, the PR process — there are habits that make day-to-day team AI use smoother. These are the small coordination practices that prevent common friction.

Sharing Discoveries in the Moment

When you find a prompt that works especially well, or discover that AI consistently gets something wrong in a specific situation, that's signal for the team. The question is where it goes: not in Slack where it'll be buried by tomorrow, but somewhere the team will actually use it.

A lightweight system that works: a dedicated Slack channel or GitHub Discussion thread called "AI discoveries" — one post per discovery, short, with a link to a PR where it was used or a code snippet of the failing output. Anything that gets three reactions gets promoted to the context file or prompt library.

Retrospective Questions Worth Asking

Add AI-specific questions to your regular retrospectives. Not "did we use AI enough?" — that question produces defensiveness, not learning. Questions about patterns and failures:

• What AI-generated code caused problems this sprint? What category of problem was it?
• Was there a task where AI slowed us down? What made it hard for AI to help there?
• Did anyone discover a prompt or pattern that worked well? Should it go in the library?
• Did AI output anything that violated a convention we care about? Should that convention be in the context file?
• Did any AI-generated code get merged that nobody could fully explain? How should we handle that?

The outputs from these questions go directly back into the context file and prompt library. This is how team AI configuration improves over time — not by individual developers getting better in isolation, but by collective learning feeding back into shared infrastructure.

Deciding What AI Handles vs. What It Doesn't

Not all tasks benefit from AI equally. Teams that use AI indiscriminately — for everything, without calibration — often waste time on tasks where AI is unreliable and miss opportunities where it's excellent. It's worth making explicit, as a team, what categories AI is trusted for:

• High confidence (AI does the first draft, human reviews): Boilerplate CRUD operations, test generation for existing service logic, documentation, migration scaffolding, type definitions from an existing JSON shape.
• Moderate confidence (AI suggests, human steers closely): New service logic with clear spec, refactoring well-tested code, debugging with known error messages, data transformations.
• Low confidence (AI consults, human writes): Auth and authorization logic, concurrency-sensitive code, novel architecture decisions, anything involving PII or sensitive data.
• Don't use AI (human writes or avoids entirely): Security-critical primitives, cryptographic operations, anything that touches production data directly.

These categories are specific to your team and codebase. The important thing is making them explicit so developers don't have to make the judgment individually every time.

Handling Disagreements About AI Use

Teams using AI will develop different comfort levels. Some developers will use it for almost everything; others will use it reluctantly for specific tasks. Both are legitimate. The coordination problem isn't about adoption rate — it's about the shared infrastructure.

Two things worth making explicit to prevent friction:

• The context file applies to everyone, regardless of personal AI use. Even if a developer writes all their code by hand, they should know the context file exists and should contribute to it when they establish or change a convention. The file represents team decisions, not just AI instructions.
• Review expectations are the same regardless of how code was written. AI-assisted code is not exempt from the same quality bar as human-written code. The PR disclosure process is transparency, not an apology — "this was AI-assisted" doesn't change what the code needs to be.

Getting Started

If your team is currently using AI individually with no shared coordination, don't try to implement everything at once. A realistic four-week path from "zero coordination" to "basic shared infrastructure":

After four weeks you'll have: a shared context file in version control, a small prompt library with a few trusted prompts, a PR process that makes AI use visible, and a retrospective practice that keeps it improving. That's the foundation everything else builds on.

Related Guides