Adding Context in Claude Code: Managing Project Knowledge

When working with Claude on coding projects, context management is crucial. Your project might have dozens or hundreds of files, but Claude only needs the right information to help you effectively. Too much irrelevant context actually decreases Claude's performance, so learning to guide it toward relevant files and documentation is essential.

The /init Command

When you first start Claude in a new project, run the /init command. This tells Claude to analyze your entire codebase and understand:

• The project's purpose and architecture
• Important commands and critical files
• Coding patterns and structure

How to use it:

/init

After analyzing your code, Claude creates a summary and writes it to a CLAUDE.md file.

Approving File Writes

When Claude asks for permission to create this file, you have two options:

1. Press Enter - Approve each write operation individually
2. Press Shift+Tab - Let Claude write files freely throughout your session

What /init analyzes:

• Project structure and organization
• Package dependencies and configuration
• Entry points and main files
• Coding conventions and patterns
• Build and deployment scripts
• Testing setup

Example CLAUDE.md generated by /init:

# Project Overview

This is a React + TypeScript web application with a Node.js backend.

## Key Commands

- `npm run dev` - Start development server
- `npm test` - Run tests
- `npm run build` - Build for production

## Architecture

- Frontend: React with TypeScript
- Backend: Express.js API
- Database: PostgreSQL with Prisma ORM
- State Management: Redux Toolkit

## Important Files

- `src/App.tsx` - Main application component
- `server/index.ts` - API server entry point
- `prisma/schema.prisma` - Database schema

## Coding Style

- Use functional components with hooks
- Prefer TypeScript strict mode
- Follow Airbnb style guide

The CLAUDE.md File

The CLAUDE.md file serves two main purposes:

1. Guides Claude through your codebase, pointing out important commands, architecture, and coding style
2. Allows you to give Claude specific or custom directions

This file gets included in every request you make to Claude, so it's like having a persistent system prompt for your project.

Why CLAUDE.md Matters

Without CLAUDE.md:

• Claude has to rediscover your project structure with each question
• You repeat the same context over and over
• Claude might miss important conventions

With CLAUDE.md:

• Claude understands your project from the start
• Consistent behavior across all conversations
• Faster, more accurate responses

CLAUDE.md File Locations

Claude recognizes three different CLAUDE.md files in three locations:

1. Project CLAUDE.md

Location: ./CLAUDE.md (project root)

Purpose: Project-specific context shared with the team

Generated by: /init command

Committed to: Source control (Git)

Shared with: All team members

Example use cases:

• Project architecture and structure
• Team coding conventions
• Important commands and scripts
• Critical files and their purposes

2. Local CLAUDE.md

Location: ./CLAUDE.local.md (project root)

Purpose: Personal instructions for this project only

Generated by: You (manually)

Committed to: Not committed (add to .gitignore)

Shared with: Only you

Example use cases:

• Personal preferences for this project
• Experimental features you're working on
• Custom shortcuts or workflows
• Notes about areas you're focusing on

Example CLAUDE.local.md:

# Personal Instructions

- I'm currently refactoring the authentication system
- Focus on security best practices
- Use verbose logging for debugging
- Prefer explicit error handling over try/catch

3. Global CLAUDE.md

Location: ~/.claude/CLAUDE.md (home directory)

Purpose: Instructions for all projects on your machine

Generated by: You (manually)

Committed to: Not applicable (personal file)

Shared with: Only you, across all projects

Example use cases:

• Your personal coding style preferences
• Preferred libraries and frameworks
• Common patterns you always use
• General instructions that apply everywhere

Example ~/.claude/CLAUDE.md:

# Global Instructions

- Always use TypeScript strict mode
- Prefer functional programming patterns
- Write comprehensive tests for all features
- Use descriptive variable names
- Add JSDoc comments for public APIs

Priority Order

When multiple CLAUDE.md files exist, they're all included, but in this order:

1. Global (~/.claude/CLAUDE.md)
2. Project (./CLAUDE.md)
3. Local (./CLAUDE.local.md)

If there are conflicts, later files take precedence.

Adding Custom Instructions

You can customize how Claude behaves by adding instructions to your CLAUDE.md file.

Using the # Command (Memory Mode)

The # command enters "memory mode" - this lets you edit your CLAUDE.md files intelligently.

Example:

# Use comments sparingly. Only comment complex code.

Claude will merge this instruction into your CLAUDE.md file automatically.

More examples:

# Always use async/await instead of .then() for promises

# Prefer named exports over default exports

# Use Tailwind CSS for styling, not custom CSS

Manual Editing

You can also edit CLAUDE.md files directly:

Project-specific:

code CLAUDE.md

Personal (local):

code CLAUDE.local.md

Global:

code ~/.claude/CLAUDE.md

File Mentions with '@'

When you need Claude to look at specific files, use the @ symbol followed by the file path.

Basic Usage

How does the auth system work? @auth

Claude will:

1. Show you a list of auth-related files
2. Let you select which ones to include
3. Include the selected file contents in your conversation

Exact File Paths

Review @src/components/Header.tsx

Claude includes that specific file.

Multiple Files

How do these components work together? @Header @Footer @Layout

Claude includes all mentioned files.

Wildcards

Review all API routes @src/api/*.ts

Claude includes all matching files.

Referencing Files in CLAUDE.md

You can mention files directly in your CLAUDE.md file using the same @ syntax. This is useful for files that are relevant to many aspects of your project.

Example:

# Database Schema

The database schema is defined in @prisma/schema.prisma. Reference it anytime you need to understand the structure of data stored in the database.

# API Routes

All API routes are defined in @src/api/routes.ts. Check this file when adding new endpoints.

# Configuration

Environment variables are documented in @.env.example.

When you mention a file this way, its contents are automatically included in every request, so Claude can answer questions about your data structure immediately without having to search for and read the schema file each time.

Best Practices

1. Run /init Early

Run /init when you first start working on a project. This gives Claude a solid foundation.

2. Keep CLAUDE.md Concise

Don't dump everything into CLAUDE.md. Focus on:

• High-level architecture
• Important conventions
• Critical files
• Common commands

❌ Too much:

# Every Single File

- src/components/Button.tsx - A button component
- src/components/Input.tsx - An input component
- src/components/Select.tsx - A select component
...(100 more files)

✅ Just right:

# Key Components

- Component library in @src/components
- Shared utilities in @src/utils
- API client in @src/api/client.ts

3. Use @ for Specific Context

Don't include files in CLAUDE.md unless they're frequently needed. Use @ mentions in your questions instead.

When to include in CLAUDE.md:

• Database schema (referenced often)
• API route definitions (referenced often)
• Configuration files (referenced often)

When to use @ in questions:

• Specific components you're working on
• Individual utility functions
• Test files

4. Update CLAUDE.md as Project Evolves

When you make significant changes:

• Add new important files
• Update architecture notes
• Document new conventions

5. Use CLAUDE.local.md for Experiments

Testing new patterns? Add them to CLAUDE.local.md first:

# Experimental: New State Management

Trying Zustand instead of Redux. Use Zustand for new features.

If it works well, promote it to the main CLAUDE.md.

Common Patterns

Pattern 1: Database Schema Reference

CLAUDE.md:

# Database

Schema: @prisma/schema.prisma

Reference this file when:
- Adding new models
- Understanding relationships
- Writing queries

Pattern 2: API Documentation

CLAUDE.md:

# API Routes

All routes defined in @src/api/routes.ts

Follow RESTful conventions:
- GET for retrieval
- POST for creation
- PUT for updates
- DELETE for removal

Pattern 3: Component Library

CLAUDE.md:

# Components

UI components in @src/components

Use existing components before creating new ones.
Follow the pattern in @src/components/Button.tsx

Pattern 4: Testing Standards

CLAUDE.md:

# Testing

Test files in @src/**/*.test.ts

Every feature requires:
- Unit tests
- Integration tests
- E2E tests (for critical paths)

Follow the pattern in @src/components/Button.test.tsx

Example Workflow

Starting a New Project

1. Initialize:

   /init
   

2. Review generated CLAUDE.md:

   cat CLAUDE.md
   

3. Add custom instructions:

   # Always use async/await for promises
   # Prefer named exports
   # Use Tailwind for styling
   

4. Reference key files:

   Database schema: @prisma/schema.prisma
   API routes: @src/api/routes.ts
   

Working on a Feature

1. Ask with context:

   How should I implement user authentication? @src/api/auth.ts @prisma/schema.prisma
   

2. Claude responds with full context of your auth system and database schema

3. Follow up:

   Add password reset functionality
   

4. Claude remembers the files you mentioned and continues with that context

Troubleshooting

Claude Doesn't Understand My Project

Solution: Run /init to generate CLAUDE.md

Claude Ignores My Instructions

Solution: Check that your instructions are in CLAUDE.md (not just in chat)

Too Much Context Slows Claude Down

Solution:

• Remove file references from CLAUDE.md that aren't always needed
• Use @ mentions in questions instead
• Keep CLAUDE.md under 500 lines

CLAUDE.md Not Being Used

Solution:

• Ensure file is named exactly CLAUDE.md
• Check file is in project root
• Restart Claude Code

Advanced Tips

Conditional Context

Use sections in CLAUDE.md for different scenarios:

# Frontend Development

When working on UI:
- Component library: @src/components
- Styling: Use Tailwind CSS
- State: Use Redux Toolkit

# Backend Development

When working on API:
- Routes: @src/api/routes.ts
- Database: @prisma/schema.prisma
- Auth: @src/api/auth.ts

Project-Specific Shortcuts

# Shortcuts

- "auth" refers to @src/api/auth.ts and @src/components/Auth
- "db" refers to @prisma/schema.prisma
- "api" refers to @src/api/routes.ts

Documentation Links

# External Documentation

- React: https://react.dev
- TypeScript: https://www.typescriptlang.org/docs
- Prisma: https://www.prisma.io/docs

Key Takeaways

1. Run /init when starting a new project
2. CLAUDE.md is included in every request
3. Three locations - global, project, local
4. Use @ to mention files in questions
5. Reference files in CLAUDE.md for frequently needed context
6. Use # command to add instructions intelligently
7. Keep it concise - too much context hurts performance

Quick Reference

Commands

• /init - Analyze project and create CLAUDE.md
• # - Enter memory mode to add instructions
• @filename - Include file in conversation

File Locations

• ./CLAUDE.md - Project context (shared)
• ./CLAUDE.local.md - Personal project context (not shared)
• ~/.claude/CLAUDE.md - Global context (all projects)

File Mentions

• @auth - Search for auth-related files
• @src/api/routes.ts - Include specific file
• @src/api/*.ts - Include all matching files

Conclusion

Effective context management is the key to productive conversations with Claude:

• Start with /init to establish project understanding
• Use CLAUDE.md for persistent, project-wide context
• Use @ mentions for specific, situational context
• Keep it focused - quality over quantity

The right context at the right time makes Claude a powerful coding partner. Too much context overwhelms. Too little context leaves Claude guessing. Master the balance, and you'll have a coding assistant that truly understands your project.

Start every new project with /init, maintain your CLAUDE.md file as the project evolves, and use @ mentions to provide specific context when needed. With these tools, Claude becomes an expert in your codebase.