codebase-context-builder

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