Adding Context with CLAUDE.md

Context is everything when working with an AI coding assistant. Your project might contain hundreds of files, but Claude only needs the right information to help you effectively. Providing too much irrelevant context actually degrades performance, so learning to guide Claude toward exactly the right files and documentation is one of the most impactful skills you can develop.

The /init Command: Your First Step in Any New Project

When you first start Claude Code in a new project, run the /init command. This tells Claude to scan your entire codebase and build an understanding of:

• The project's purpose and high-level architecture
• Important commands for building, testing, and running the project
• Critical files and directories worth knowing about
• Coding patterns, conventions, and project structure

After analyzing your project, Claude generates a summary and writes it to a CLAUDE.md file. When prompted for permission, press Enter to approve or press Shift+Tab to let Claude write files freely for the rest of your session.

Understanding CLAUDE.md Files

The CLAUDE.md file acts as a persistent system prompt for your project. It serves two purposes: guiding Claude through your codebase (pointing out architecture, commands, and coding style) and providing a place for you to add custom directions that shape how Claude behaves.

Claude recognizes CLAUDE.md files in three locations, each serving a different scope:

The # Memory Shortcut

You can update your CLAUDE.md files without manually editing them. Use the # command to enter "memory mode" — simply type a hash followed by your instruction, and Claude will intelligently merge it into your CLAUDE.md file.

1# Use comments sparingly. Only comment complex logic.

This is especially powerful for correcting repeated mistakes. If Claude keeps adding excessive comments, one quick memory command fixes the behavior for every future session.

File Mentions with @

When you need Claude to focus on specific files, use the @ symbol followed by a file path. This directly includes that file's contents in your request, giving Claude immediate access without requiring it to search.

1How does the auth system work? @src/auth

Claude will display a list of matching files for you to select from. You can also reference files directly in your CLAUDE.md to ensure they are included in every request — ideal for database schemas, API specs, or other foundational files.

1The database schema is defined in @prisma/schema.prisma.
2Reference it whenever you need to understand data structure.