Team Collaboration: Shared Context and Rules

Two engineers on your team ask their AI assistant to add a new API endpoint. One gets a controller with try/catch and a custom error class; the other gets a bare async handler that throws raw errors. Folder layouts differ. Naming differs. The pull request review turns into a 40-comment style debate that has nothing to do with whether the feature works — because your conventions live in people’s heads, not in the repo.

The fix is not more review comments. It is moving the standards into version-controlled rule files that every team member’s AI loads automatically. When the conventions live next to the code, every engineer’s agent generates code that already looks like your codebase.

What You’ll Walk Away With

• A committed rules file for each tool (.cursor/rules/, CLAUDE.md, AGENTS.md) that enforces your conventions for the whole team
• A copy-paste prompt that drafts that rules file by inspecting your existing code, so you are not writing it from a blank page
• A workflow for turning code-review decisions into permanent, machine-enforced rules
• An onboarding prompt a new hire pastes on day one to map the codebase themselves
• The failure modes (rule drift, conflicting files, bloated context) and how to avoid them

The Foundation: Version-Controlled Rules

The single most important practice for team alignment is to define your project’s standards in shared, version-controlled rule files that ship with the repo. All three tools read project-level instruction files; the only difference is the filename and a few mechanics.

Cursor

Cursor reads rules from the .cursor/rules/ directory (one or more .mdc files). Commit this directory so every teammate’s Cursor picks up the same rules. Each rule file can be scoped with frontmatter: alwaysApply: true loads it into every request, or a globs pattern (e.g. src/api/**) loads it only when matching files are in context.

---
description: API conventions
globs: src/api/**
alwaysApply: false
---
- All route handlers live in src/api/<resource>/route.ts
- Wrap handlers in our asyncHandler() from src/lib/http.ts
- Throw AppError (src/lib/errors.ts), never raw Error
- Validate input with the matching Zod schema before any DB call

Claude Code

Claude Code reads CLAUDE.md from the project root (and nested directories). Commit it to the repo. You can pull in other files with @path imports so a single CLAUDE.md stays small while referencing detailed standards.

# Project conventions

## API endpoints
- Route handlers live in src/api/<resource>/route.ts
- Wrap handlers in asyncHandler() from src/lib/http.ts
- Throw AppError (src/lib/errors.ts), never raw Error
- Validate input with the matching Zod schema before any DB call

See @docs/architecture.md for the full request lifecycle.

Codex

Codex reads AGENTS.md files, starting at the repository root and walking down to the current directory. Commit AGENTS.md at the root for team-wide rules. For a sub-team with different conventions, drop an AGENTS.override.md in that directory — files closer to the working directory override broader guidance because Codex concatenates them root-first.

AGENTS.md

## API endpoints
- Route handlers live in src/api/<resource>/route.ts
- Wrap handlers in asyncHandler() from src/lib/http.ts
- Throw AppError (src/lib/errors.ts), never raw Error
- Validate input with the matching Zod schema before any DB call

Codex stops adding files once the combined size hits project_doc_max_bytes (32 KiB by default), so split large guidance across nested directories rather than one giant root file.

Once these files are committed, a developer who clones the repo gets the conventions for free — their AI loads the rules and generates code consistent with your existing patterns from the first prompt. That is the entire point: reviews stop being about style, because the style is enforced before the code is written.

Note

Maintaining three files (.cursor/rules/, CLAUDE.md, AGENTS.md) on a mixed-tool team feels redundant. Keep the substance identical and let each file be a thin wrapper: put the real standards in one Markdown doc (e.g. docs/conventions.md) and have each rule file reference it. Cursor and Claude Code support imports; for Codex, keep the AGENTS.md short and point to the doc by path.

The Workflow: From Blank File to Enforced Standard

You do not write a rules file from scratch. You let the AI draft it by reading the code you already have, then you edit and commit.

1. Generate a first draft from the codebase. Point the agent at representative directories and have it infer your actual conventions — the ones in the code, not the ones in the wiki nobody reads.

   Copy-paste prompt: draft a rules file from existing code

   Inspect this codebase and draft a team rules file that captures our
   real, current conventions. Read enough to be accurate, not exhaustive:
   
   - 3-4 files under src/api/ for our endpoint/error-handling pattern
   - 2-3 React components for naming, file structure, and state patterns
   - Our test files for how we name and structure tests
   - package.json and tsconfig.json for tooling and strictness
   
   Output a concise rules file with these sections: Project structure,
   Naming, Error handling, Testing, and "Do NOT" (anti-patterns you see
   us avoiding). Quote the real file paths and helper names you found.
   Keep it under 150 lines. Flag anything inconsistent so I can pick the
   canonical version instead of you guessing.

2. Review and pick the canonical pattern. The draft will surface inconsistencies (“two error-handling styles in src/api”). This is the valuable part — decide which one wins and make the rules file unambiguous.

3. Commit it to the right filename. Save as .cursor/rules/conventions.mdc, CLAUDE.md, or AGENTS.md per the tabs above (or all three, wrapping a shared doc). Commit and push so the whole team gets it on their next pull.

4. Codify review decisions as they happen. The rules file is a living document. When a code review establishes a new standard, do not just leave it in a PR comment where it dies — add it to the rules file in the same PR.

   Copy-paste prompt: codify a review decision into the rules

   We just decided in code review: every database query that can return
   zero rows must handle the empty case explicitly and return a typed
   Result, never null.
   
   Add this as a rule to our rules file. Write it as an imperative bullet
   with a one-line "why", and include a tiny before/after example using
   our actual Result type from src/lib/result.ts. Place it under the
   Error handling section. Show me only the diff.

Onboarding: Let New Hires Map the Codebase Themselves

The fastest onboarding is not a senior dev answering the same questions every quarter. It is a new hire pasting a prompt and getting an accurate, rules-aware tour on demand. Because the agent reads the committed rules, the answers reflect your conventions, not generic advice.

Copy-paste prompt: new-hire codebase orientation

I'm new to this codebase. Using our committed rules file and the code
itself, give me an orientation, not a lecture:

1. Where is authentication handled, and what is the request lifecycle
   for a logged-in API call (entry point to response)?
2. What are our error-handling and validation conventions, with the
   actual helper/util names I should reuse?
3. What naming and file-structure patterns should I follow for a new
   feature module?
4. Which directories are off-limits or auto-generated?

For each point, cite the specific files I should read next. End with a
"first PR checklist" of conventions reviewers will expect me to follow.

The AI as a Collaboration Hub

Shared rules align the code; integrations align the people. Codex’s multi-surface design is the strongest fit here: it connects to GitHub, Slack, and Linear, so the agent can act where your team already talks.

• Answer product questions in the open. A PM asks in a Slack channel how a feature behaves. Instead of a developer context-switching to read code, Codex (connected to the repo and Slack) can answer in-thread with a code-grounded explanation everyone sees — turning a DM into shared team knowledge.
• Tie work to tickets. With the GitHub and Linear integrations, Codex can open a PR from a task or summarize a change back onto the ticket, so the rationale lives where the work is tracked, not in someone’s terminal scrollback.

Cursor’s background agent and Claude Code’s headless mode (claude -p "..." in CI) cover the automation side: run the same rules-aware agent in a pipeline to flag convention violations on every PR. The principle is identical across all three — the agent is only as aligned as the committed rules it reads, so the rules file remains the source of truth.

When This Breaks

The rules file drifts from reality. Teams write a rules file once, the codebase evolves, and six months later the rules describe a pattern you abandoned. Re-run the “draft a rules file from existing code” prompt quarterly and diff it against the committed file — it surfaces exactly where reality moved on.

Conflicting instruction files. A root CLAUDE.md says one thing and a nested one says another; an AGENTS.override.md silently wins over the root AGENTS.md. When the AI ignores a rule, check whether a closer-scoped file is overriding it. Codex concatenates root-first (nearest wins); keep overrides deliberate and documented.

The rules file is too long, so it gets ignored or eats context. A 600-line rules file both burns context and buries the rules that matter. Codex hard-caps at 32 KiB by default. Keep the top-level file lean and push detail into referenced docs or scoped files (globs in Cursor, nested files in Codex, @imports in Claude Code).

Rules describe style but not “why.” “Use AppError” without a reason gets followed inconsistently. One-line rationales make rules stick and help the AI generalize to cases you did not enumerate.

Treating shared memory or a shared index as a rules substitute. Cursor maintains a per-project semantic index (and team plans can share it), but Claude Code and Codex navigate in real time with no pre-built shared index — so do not rely on “the AI already knows our patterns.” Committed rule files are the portable, tool-agnostic source of truth. See the indexing and memory guides below for what each tool actually persists.

What’s Next

Prompting Techniques Write prompts that get production-quality output from your team's rules-aware agents.

Managing Large Codebases Keep agents effective as the repo grows beyond what fits in one context window.

Privacy and Security Decide what belongs in committed rules and what must never reach an AI provider.

Memory Patterns What each tool persists across sessions with auto-memory and project rules.

Codebase Indexing How Cursor's shared semantic index differs from Claude Code and Codex real-time navigation.