Codebase Context Builder

Prepare optimal context so AI assistants understand your codebase deeply.

When to Use

Setting up a new project for AI-assisted development
AI assistant generates code that doesn't fit your patterns
Creating CLAUDE.md, AGENTS.md, or similar context files
Preparing context for complex code generation tasks
Improving AI understanding of your architecture

The Context Hierarchy

┌─────────────────────────────────────────┐
│ Level 1: Project Context (Always Load)  │
│ - Tech stack, conventions, structure    │
│ - CLAUDE.md / AGENTS.md files           │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│ Level 2: Domain Context (Task-Specific) │
│ - Related files, types, interfaces      │
│ - Existing patterns to follow           │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│ Level 3: Task Context (Per-Request)     │
│ - Specific requirements                 │
│ - Examples of expected output           │
└─────────────────────────────────────────┘

Creating CLAUDE.md

Place in project root. AI assistants read this automatically.

# Project: [Name]

## Tech Stack
- **Frontend:** React 19, TypeScript 5.4, Tailwind CSS 4.0
- **Backend:** Node.js 22, Express 5, PostgreSQL 16
- **Testing:** Vitest, Playwright
- **Package Manager:** pnpm 9

## Project Structure

src/ ├── components/ # React components (PascalCase) ├── hooks/ # Custom hooks (use* prefix) ├── services/ # API clients and business logic ├── types/ # TypeScript interfaces ├── utils/ # Pure utility functions └── pages/ # Route components


## Code Conventions

### Naming
- Components: PascalCase (`UserProfile.tsx`)
- Hooks: camelCase with `use` prefix (`useAuth.ts`)
- Utils: camelCase (`formatDate.ts`)
- Types: PascalCase with `I` prefix for interfaces (`IUser`)

### Patterns
- Use functional components with hooks
- Prefer `const` arrow functions for components
- Use named exports, not default exports
- Error handling with custom `AppError` class

### Imports Order
1. External packages
2. Internal modules (absolute paths)
3. Relative imports
4. Styles

## API Conventions
- Base URL: `/api/v1`
- Auth: Bearer token in Authorization header
- Errors: `{ error: { code, message, details } }`

## Testing
- Unit tests: `*.test.ts` colocated with source
- E2E tests: `e2e/*.spec.ts`
- Run: `pnpm test` (unit), `pnpm test:e2e` (e2e)

## Common Commands
```bash
pnpm dev          # Start development
pnpm build        # Production build
pnpm test         # Run tests
pnpm lint         # Lint code

Important Files

src/services/api.ts - API client with interceptors
src/hooks/useAuth.ts - Authentication hook
src/types/index.ts - Shared type definitions


## Building Task-Specific Context

### Step 1: Identify Relevant Files

```bash
# Find files related to your task
# For a "user profile" feature:

# Find existing user-related code
grep -r "user" --include="*.ts" -l src/

# Find related types
grep -r "interface.*User" --include="*.ts" src/types/

# Find similar components
ls src/components/ | grep -i profile

Step 2: Include Key Dependencies

When asking AI to modify code, include:

The file to modify
Types/interfaces used
Related utilities
Similar existing implementations

Example prompt structure:

## Context Files

### src/types/user.ts
[paste file content]

### src/services/userService.ts
[paste file content]

### src/components/UserCard.tsx (similar component)
[paste file content]

## Task
Create a UserProfile component that displays user details
and allows editing. Follow the patterns in UserCard.

Step 3: Provide Examples

## Expected Output Example

The component should look similar to this pattern:

```tsx
export const UserProfile: React.FC<UserProfileProps> = ({ userId }) => {
  const { data, isLoading } = useUser(userId);

  if (isLoading) return <Skeleton />;

  return (
    <Card>
      {/* Component content */}
    </Card>
  );
};

Context Strategies by Task Type

For New Features

Include:
1. CLAUDE.md (project context)
2. Similar existing feature (as reference)
3. Relevant types and interfaces
4. API endpoint documentation
5. Design requirements or mockups

For Bug Fixes

Include:
1. The buggy code
2. Error message / stack trace
3. Expected vs actual behavior
4. Related test files
5. Recent changes to the file (git log)

For Refactoring

Include:
1. Current implementation
2. Target patterns/architecture
3. All usages of the code being refactored
4. Migration examples if changing APIs

For Tests

Include:
1. Code to be tested
2. Existing test patterns in the project
3. Test utilities and mocks
4. Coverage requirements

Context File Templates

AGENTS.md (For Multi-Agent Systems)

# Agent Configuration

## Available Agents
- **code-reviewer**: Reviews code for best practices
- **test-writer**: Generates comprehensive tests
- **doc-generator**: Creates documentation

## Shared Context
All agents have access to:
- Project structure in CLAUDE.md
- Type definitions in src/types/
- Coding standards in .eslintrc

## Agent-Specific Instructions

### code-reviewer
Focus on:
- Security vulnerabilities
- Performance issues
- Code style violations
- Missing error handling

### test-writer
Requirements:
- Minimum 80% coverage
- Include edge cases
- Mock external dependencies
- Use existing test utilities

.cursorrules / .claude/settings.json

{
  "contextFiles": [
    "CLAUDE.md",
    "src/types/index.ts",
    "docs/API.md"
  ],
  "excludePatterns": [
    "node_modules",
    "dist",
    "*.test.ts"
  ]
}

Optimizing Context Size

Token Budget Guidelines (2026)

Claude: 200K context, but 10-20K is optimal for speed
GPT-4: 128K context
Keep routine context under 5K tokens

Strategies

Summarize large files instead of including full content
Use file references when AI can read files directly
Include only relevant sections of large files
Create focused context files per feature area

Example: Summarized Context

## UserService Summary
- Location: src/services/userService.ts
- Methods: getUser, updateUser, deleteUser, listUsers
- Uses: apiClient, UserSchema validation
- Auth: Requires authenticated user context
- Key pattern: All methods return Promise<Result<T, AppError>>

Verifying Context Quality

Checklist

Tech stack and versions specified
File naming conventions documented
Import patterns shown
Error handling patterns included
Existing similar code referenced
Types and interfaces available
Test patterns documented

Test Your Context

Ask the AI a simple question about your codebase conventions. If it answers correctly, your context is working.

"What naming convention should I use for a new React hook in this project?"

Expected: "Use camelCase with 'use' prefix, like useAuth.ts"

codebase-context-builder