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 rules files, 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 teammate may repeat the same investigation without seeing the examples or limitations you already found.

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

Several coding tools support repository instructions, with different loading rules and feature coverage. Keep the shared conventions in version control and verify which files your tool actually loads. Instructions guide the model; tests, authorization and deployment controls enforce the requirements that must hold.

The Files and What They Do

The format, scope and activation vary by tool. Check the feature you use, such as chat, an agent or code review, rather than assuming one file applies everywhere:

• Claude Code: project CLAUDE.md files provide context. Files in the working directory and its ancestors load at launch; instructions in subdirectories load on demand. Use /context to inspect the loaded memory files.
• Cursor: .cursor/rules/ contains .mdc project rules. Frontmatter chooses always-applied, file-scoped, agent-selected or manual activation. They guide Agent; Cursor's FAQ says they do not affect Cursor Tab.
• GitHub Copilot: repository instructions use .github/copilot-instructions.md; path-specific instructions use .github/instructions/NAME.instructions.md. Check support and settings for the particular IDE, agent or code-review feature.
• Devin Desktop (formerly Windsurf): the FAQ confirms that the root .windsurfrules file is still read. For directory rules, .devin/rules/ is preferred over the fallback .windsurf/rules/. Directory rules have activation metadata; that directory precedence does not mean a root rule is ignored.
• Shared convention: AGENTS.md provides plain Markdown instructions for supporting agents. Cursor and Copilot document support, including nested files, but loading and precedence remain tool-specific.

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

Start with the commands, paths and decisions that a teammate can verify. The template below is a fictional team policy: replace its version placeholders and paths with your repository's actual values before using it.

# [Project Name] — AI Context

## Stack
# Copy versions from the lockfile and runtime configuration.
# Check generated calls against those versions; a prompt is not validation.
- TypeScript [locked version], Node.js [project runtime version]
- Express 5.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
- Keep services independent of Express: no request/response objects
- Pass database, clock and network dependencies explicitly where practical

## Patterns to avoid
# Record concrete team decisions and their approved alternatives.
- 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)
# Verify these instructions load; enforce critical requirements in code and CI.
- 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
- Apply src/middleware/auth.ts to protected routes
- Authorize the user for the requested resource, not just for login
- 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 mirror src/: src/services/user.ts → tests/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. Configure each file's metadata explicitly; the filename alone does not activate a rule. The directory below proposes scopes for this example project.

.cursor/rules/
  base.mdc           # Set alwaysApply: true for core conventions
  frontend.mdc       # Set globs for src/components/ and src/pages/
  backend.mdc        # Set globs for src/routes/ and src/services/
  migrations.mdc     # Example frontmatter shown below
  tests.mdc          # Set globs for **/*.test.ts and **/*.spec.ts

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

# Migration Rules

- Preserve applied migrations; add a new migration for the next change
- Separate the expansion phase from destructive cleanup. Remove old columns
  only after old callers are retired and the recovery plan is reviewed
- Record lock and transaction requirements for index creation separately
- This project runs forward migrations in filename order; use timestamp names
- Test against a representative disposable database before merging
- Document and test rollback or forward recovery. Dropping a column in DOWN
  does not recover data already removed by UP

With alwaysApply: false and the listed globs, Cursor documents auto-attachment when a matching file is in context. An open editor tab alone is not the complete activation rule. Verify the configured rule type and pattern in Customize → Rules, then try a matching migration file and an unrelated frontend file in separate chats. These are instruction-loading checks; they do not prove a migration is safe.

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 violates a convention, fix the code and identify the cause. Add a short reusable instruction for a repeated gap; put enforceable requirements in validation, tests or CI as well. Record the failed example so a revised prompt can be checked against it.
• Keep it honest. An outdated rule is worse than no rule. If you migrated from TypeORM to Kysely, remove the TypeORM section. Stale instructions can steer output toward an abandoned pattern.
• 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

Keep agent instructions focused and readable for teammates who review them. Link to the longer style guide, wiki or architecture decision when detail is needed:

• Don't write essays — but do keep a short reason with rules that aren't obvious. One clause of motivation ("never log request bodies — they can contain tokens") helps the model apply the rule to cases you didn't list; the full rationale belongs in ADRs.
• 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. Treat its findings as hypotheses: inspect the cited API, reproduce the failing path, and keep human review responsible for acceptance.

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. A fresh conversation can provide a second reading, but it can still overlook defects or invent findings. Ask for evidence and verify the result independently.

Supply the relevant approved rules and inspect their changes as part of review. GitHub documents that Copilot code review reads instruction files from the PR's head branch. A PR can therefore change the guidance used to review it. Inspect those changes before relying on the review output; use separate required checks for critical controls.

The Speed Asymmetry Problem

If generated changes arrive faster than reviewers can verify them, 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 output can contain both ordinary mistakes and structural defects: a nonexistent method, a missing resource authorization check or a transaction gap. Read the relevant paths and test their failure cases.

The following tiers are a proposed team policy. Assign review effort by impact and evidence, and adapt the staffing to your project:

• 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): Low-impact copy or presentation changes with bounded effects. Classify tests, configuration and UI by what they control: CI permissions, deployment settings, security assertions and access-sensitive screens require deeper review.

Classify PRs at creation time. The author self-declares a tier; reviewers can escalate. Escalate when a small diff changes a critical control or the reviewer cannot explain its effects.

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.
List required application types, exports, authorization checks and middleware.
Mark missing contracts explicitly instead of inventing APIs or imports.
Show which existing project checks should validate the proposed files.

## 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

Use a version-controlled prompts/ directory as the canonical library, organized by category and reviewed like code. Team wikis and discovery channels can link to the reviewed revision so copies do not drift.

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?

Use this as an entry checklist, then record the test inputs, expected outcomes, tool/model versions and failures. Two successful trials alone do not establish that a prompt works across the team's tasks.

Keeping the Library Useful

Prompt libraries decay. Dependencies move to new major versions. 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.

Treat the response as a draft map. Open each named file, follow one real request through validation, service and query layers, and ask a teammate about decisions absent from the code. Correct the map when a claimed function or edge is missing; keep those uncertainties visible before making changes.

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 six sections above. Specific references to
the actual code patterns you see in the files provided. Mark missing evidence
as unknown and name the additional file needed to resolve it.

## 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. Choose a bounded task with a clear result and an existing test path, such as a utility function or an additional test. Ask the new teammate to explain the change and demonstrate its failure case. 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. Nominate an owner to review a discovery against a reproducible example before promoting it to the context file or prompt library. Reactions can identify interest; they do not validate the advice.

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. Use the following as a proposed responsibility split, then validate it against your team's actual outcomes and risk controls:

• Bounded drafting (AI proposes, human verifies): Boilerplate CRUD operations, test generation for existing service logic, documentation, migration scaffolding, type definitions from an existing JSON shape.
• Closely supervised changes: New service logic with clear spec, refactoring well-tested code, debugging with known error messages, data transformations.
• Specialist review required: Auth and authorization logic, concurrency-sensitive code, novel architecture decisions, anything involving PII or sensitive data.
• Restricted operations under explicit team policy: 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":

The aim of this four-week pilot is a reviewed context file, a small prompt library, explicit PR expectations and a maintenance owner. Record what is still unverified and revise the schedule rather than treating the calendar as proof that the workflow is ready.

Sources and review scope

Tool behavior was checked against Claude Code memory and instruction loading, Cursor Rules, GitHub repository instructions, the AGENTS.md convention and Devin Desktop's rules FAQ. Keeping a short reason with a rule follows Anthropic's prompting best practices. Sources checked Oct 29, 2026; recheck by Nov 28, 2026 or when a tool changes its instruction format. The policy, migration rules, prompts, review tiers and four-week schedule are proposed examples for a fictional team. The eight blocks are Markdown templates, directory layouts and one MDC configuration, not executable application code. No model responses, tool UI sessions or team productivity outcomes were tested. Validate loading and prompt behavior in your own tool and repository before adopting them.

Related Guides