Project Conventions With AI: How to Teach Your Codebase Rules to Claude

The Convention Communication Problem

Every team has conventions. Some are written down; most live in senior developers' heads and code review comments. AI assistants start each session fresh — they don't remember that your team uses named exports, prefers composition over inheritance, or has a specific error handling pattern.

The solution is systematic convention documentation that AI can read. This goes beyond CLAUDE.md — it's a full convention communication strategy.

The Convention Hierarchy

Structure your conventions in three tiers:

1. Hard rules — non-negotiable, always enforced (TypeScript no-any, no default exports)
2. Soft conventions — strong preferences, override requires comment (prefer server components, avoid useEffect for data)
3. Style choices — team preferences (naming patterns, file structure)

Writing the Conventions Document

# Coding Conventions

## Hard Rules (Never Violate)

### TypeScript
- No `any` types — use `unknown` and narrow, or write proper generics
- No non-null assertions (`!`) without explaining comment
- All functions must have explicit return types (except trivial inference)

### Imports/Exports
- Named exports only — no `export default` (except Next.js required files)
- Import order: Node built-ins, external packages, internal modules (alphabetical within groups)
- No barrel files (index.ts re-exports) — import from source directly

### Components
- One component per file
- File name matches export name, both in PascalCase
- Props interface defined in same file, named `[ComponentName]Props`

## Soft Conventions (Follow Unless Good Reason Not To)

### React Patterns
- Server Components by default; add "use client" only when required
- Custom hooks for reusable stateful logic (prefix: use[Name])
- Composition over complex prop drilling — use children or slot patterns

### Error Handling
- Always surface errors to the user — never silent catches
- Use error boundaries for React rendering errors
- API routes return consistent error shapes: { error: { message, code } }

## Style Choices
- Boolean props: prefer `isLoading` / `hasError` over `loading` / `error`
- Event handlers: `onSubmit` / `onClick` (not `handleSubmit` / `handleClick`)
- CSS: Tailwind utility classes, alphabetical order, cn() for conditionals

Teaching Conventions by Example

Abstract rules are less effective than examples. For each key convention, provide before/after:

Our error handling pattern:

Don't do this:
try {
  const data = await fetchData();
} catch (e) {
  console.error(e); // silent failure!
}

Do this:
try {
  const data = await fetchData();
} catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  throw new AppError(message, 'FETCH_FAILED');
}

Our AppError class:
[paste the class definition]

Reinforcing Conventions in Prompts

Build a [FEATURE] following our project conventions:

Key conventions to apply:
- [RELEVANT CONVENTION 1]
- [RELEVANT CONVENTION 2]

Reference this existing [similar component] for style:
[PASTE EXAMPLE]

The Convention Review Prompt

Review this PR diff for convention violations.

Our conventions (summarized):
[PASTE KEY CONVENTIONS]

For each violation:
1. Quote the offending code
2. State which convention it violates
3. Show the correct version

Diff:
[PASTE DIFF]

Making Conventions Stick

Document conventions in three places:

1. CLAUDE.md — for AI session context
2. Your team wiki — for human onboarding
3. ESLint/Biome rules — for automated enforcement

Conventions that can be linted should be linted. Use AI for the conventions that require judgment — style and architecture — not the ones a linter can catch mechanically.