Skip to main content

Context Files

"Teach AI your project once, benefit forever."


What Are Context Files?​

Context files are project-specific instructions that AI tools read automatically. Instead of explaining your conventions, architecture, and preferences in every conversation, you encode them once.

Common context files:

  • CLAUDE.md: For Claude Code and Anthropic tools
  • .cursorrules: For Cursor IDE
  • .github/copilot-instructions.md: For GitHub Copilot
  • AI.md or CONTEXT.md: Generic convention

Why Context Files Matter​

Without Context Files​

Every conversation:

"When writing code, use TypeScript with strict mode,
our naming convention is camelCase for variables,
PascalCase for components, we use Tailwind CSS,
prefer named exports, handle errors with Result pattern..."

With Context Files​

Every conversation:

"Add a new component for user profiles"

AI already knows your conventions.


What to Include​

1. Project Overview​

What is this project? What does it do? What are the main technologies?

# Project Overview
This is a Next.js 14 e-commerce platform using App Router.
- TypeScript with strict mode
- PostgreSQL with Prisma ORM
- Tailwind CSS + shadcn/ui components
- Jest + Testing Library for tests

2. Architecture​

How is the project structured?

# Architecture
- `src/app/`: Next.js App Router pages and layouts
- `src/components/`: Reusable UI components
- `src/lib/`: Utilities and shared logic
- `src/server/`: Server-only code (API, database)
- `prisma/`: Database schema and migrations

3. Conventions​

How should code be written?

# Conventions
- Use named exports, not default exports
- Components: one per file, PascalCase filename
- Use `type` over `interface` unless extending
- Error handling: use Result<T, E> pattern from `src/lib/result`
- Prefer `const` arrow functions for components

4. Patterns to Follow​

Reference examples in the codebase:

# Patterns
- Component structure: see `src/components/Button/`
- API routes: see `src/app/api/users/`
- Form handling: see `src/components/forms/LoginForm.tsx`
- Data fetching: use `useQuery` hook (see `src/hooks/useQuery.ts`)

5. Things to Avoid​

What NOT to do:

# Avoid
- Never use `any` type, use `unknown` and narrow
- Don't use `index.ts` barrel files (causes circular imports)
- Don't put business logic in components, use `src/lib/`
- Don't use inline styles, use Tailwind classes

6. Common Gotchas​

Project-specific pitfalls:

# Gotchas
- Server components can't use hooks or browser APIs
- `prisma` client must be imported from `src/lib/db`
- Auth is handled by middleware, check `src/middleware.ts`
- Tests must mock the Prisma client (see `src/test/setup.ts`)

Complete Example​

# CLAUDE.md

## Project: Acme E-Commerce Platform

Next.js 14 e-commerce platform with App Router, TypeScript, and PostgreSQL.

## Architecture
- `src/app/`: App Router pages, layouts, API routes
- `src/components/`: React components (one per file)
- `src/lib/`: Utilities, helpers, shared logic
- `src/server/`: Server-only code (database, services)
- `src/hooks/`: Custom React hooks
- `prisma/`: Schema and migrations

## Tech Stack
- Next.js 14 with App Router
- TypeScript (strict mode)
- PostgreSQL + Prisma
- Tailwind CSS + shadcn/ui
- Jest + Testing Library

## Conventions

### Naming
- Components: PascalCase (`UserProfile.tsx`)
- Hooks: camelCase with `use` prefix (`useCart.ts`)
- Utils: camelCase (`formatCurrency.ts`)
- Types: PascalCase with descriptive names (`UserProfile`, `CartItem`)

### Code Style
- Named exports only (no default exports)
- `type` over `interface` unless extending
- Prefer `const` arrow functions for components
- Destructure props in function signature
- Use early returns for guard clauses

### Error Handling
- Use Result pattern from `src/lib/result.ts`
- Never throw in service functions
- API routes return `{ data, error }` shape
- Display errors via toast (see `src/hooks/useToast`)

## Patterns

### Components
See `src/components/ui/Button.tsx` for structure:
- Props type at top
- Minimal component logic
- Tailwind for styling
- Forwarded ref when needed

### API Routes
See `src/app/api/products/route.ts`:
- Validate input with Zod
- Use service functions from `src/server/`
- Return consistent response shape
- Handle errors gracefully

### Data Fetching
Use `useQuery` from `src/hooks/useQuery.ts`:
- Handles loading/error states
- Automatic caching
- TypeScript-safe

## Avoid
- `any` type, use `unknown` and narrow
- Barrel files (`index.ts`), causes circular imports
- Business logic in components, extract to `src/lib/`
- Inline styles, use Tailwind
- `console.log` in production code, use logger

## Gotchas
- Server components can't use hooks or browser APIs
- Import Prisma from `src/lib/db`, not directly from `@prisma/client`
- Auth state available via `useAuth()` hook
- Environment variables: server-only unless prefixed `NEXT_PUBLIC_`

## Testing
- Run: `npm test`
- Coverage: `npm run test:coverage`
- Mock Prisma: `src/test/mocks/prisma.ts`
- Test utilities: `src/test/utils.tsx`

Tool-Specific Locations​

ToolFileLocation
Claude CodeCLAUDE.mdProject root
Cursor.cursorrulesProject root
GitHub Copilot.github/copilot-instructions.md.github/ folder
Codycody.yamlProject root
GenericAI.md or CONTEXT.mdProject root

Tips for Effective Context Files​

Keep It Focused​

Include what AI needs to make good decisions. Not comprehensive documentation, but decision-relevant information.

Use Examples​

"See src/components/Button/" is better than describing the pattern in words.

Update It​

When conventions change, update the context file. Stale context is worse than no context.

Layer Them​

Personal context + team context + project context can coexist. More specific overrides more general.

Test Understanding​

Ask AI: "Based on CLAUDE.md, what are our error handling conventions?"


Team Context Files​

For teams, context files should be:

  • Version controlled: Part of the repository
  • Reviewed: Changes go through code review
  • Shared: Everyone uses the same base context
  • Documented: Explain why conventions exist

Individual customization can layer on top:

~/.claude/CLAUDE.md          # Personal global context
~/work/CLAUDE.md # Work-wide context
~/work/project/CLAUDE.md # Project-specific context

Common Mistakes​

Too Long​

If it's longer than 2 pages, AI might not prioritize the important parts. Focus on what matters most.

Too Vague​

"Write good code" isn't helpful. "Use named exports, handle errors with Result pattern" is.

Never Updated​

Outdated context actively misleads AI. Review quarterly at minimum.

Not Verified​

If you're not sure AI reads it, ask: "What project conventions do you know about?"