Context Management and Project Setup

Now that we’re comfortable with basic conversation-driven development, it’s time to learn one of the most critical skills for productive AI-assisted development: context management. We’ve already learned how to ask Claude about a codebase and get useful responses. Here’s the challenge: what happens when a project has hundreds or thousands of files? How does Claude know which files are most relevant to our question? How do we ensure that Claude understands our project’s unique patterns, conventions, and architecture without overwhelming it with irrelevant information? That’s where context management comes in.

What is context management?

Context management is the practice of strategically controlling what information Claude has access to when helping with code. Think of it as curating Claude’s knowledge about a specific project and ensuring it knows exactly what it needs to know, when it needs to know it, without being overwhelmed by irrelevant details.

At its core, context management involves three key activities.

• Establishing project understanding: Through systematic analysis and documentation, teach Claude about the project’s architecture, conventions, and important patterns.

• Providing targeted information: Include specific files, configurations, and code snippets that are relevant to the current task or question.

• Maintaining persistent knowledge: Create a knowledge base that Claude can reference across conversations, so we don’t have to re-explain fundamentals.

The goal is to transform Claude from a generic coding assistant into a knowledgeable team member who understands the specific project, the team’s conventions, and architectural decisions. Consider two scenarios:

• Suppose we’re working on a large React application with authentication, complex state management, custom API integrations, and team-specific coding conventions. We ask Claude: “How should I implement user profile editing?” Without proper context, Claude might provide a generic React form example that doesn’t match our authentication patterns, ignores our state management approach, and violates our team’s coding standards. We would spend more time adapting suggestions than writing the code ourselves.

• Too much context is just as problematic as too little. If we dump the entire codebase into every conversation, Claude gets overwhelmed, and its performance decreases.

The skill is learning to provide precisely the right context for each situation. Hence, the next step in our journey is to actually use the built-in features Claude Code comes equipped with to deal with context management.

What is the /init command?

Every meaningful relationship starts with proper introductions. The /init command is how we introduce Claude Code to a project in a systematic, intelligent way. When we run /init, Claude Code executes an analysis prompt that instructs Claude to examine the codebase. While the exact prompts are proprietary and evolve over time, we can get a sense of the intent by looking at similar prompts used in the AI coding community:

This shows that /init is designed to create concise, actionable context for AI agents. The prompt focuses on two critical pieces of information: how to run and test the code, and what coding conventions to follow. It can also incorporate existing AI tool configurations from other editors like Cursor.

Let’s see this in action. Try running the /init command in the terminal below:

We can see that when Claude completes its analysis, it will show a comprehensive project summary and ask permission to create a CLAUDE.md file. Pay close attention to this summary, because it reveals how Claude understands the project. If something seems wrong or incomplete, this is the moment to correct it before it becomes part of the persistent context.

When Claude asks for permission to create the CLAUDE.md file, you have two choices:

• Press “Enter”: Approve each individual file write operation. This gives fine-grained control over every change, but it requires more interaction.

• Press “Shift+Tab”: Allow Claude to write files freely throughout the session. This is faster, but it gives Claude broader permissions.

For most projects, “Shift+Tab” is the right choice. You can always review and modify the generated CLAUDE.md file afterward.

How does the CLAUDE.md file work?

The CLAUDE.md file is more than documentation; it’s Claude’s persistent memory of the project. Every time we start a new conversation with Claude Code in this repository, the contents of this file are automatically included in the context. This is so that Claude remembers project specifics without repeated explanations. Here’s an example of a well-structured CLAUDE.md for a Next.js e-commerce application:

We can see immediately how useful this will be to our conversations. But what if there are coding conventions or important context we need to include that aren’t already present? Will Claude Code be confined to the contents of the CLAUDE.md it created? Not necessarily.

Claude Code recognizes a hierarchy of context files, each with a different scope.

• Project-level CLAUDE.md (in the project root): Created by /init, it contains the project’s architecture, conventions, and important files. As it’s committed to source control, any teammate using Claude Code in the project shares the same context.

• Local CLAUDE.md (also in the project root): Adds personal instructions without affecting teammates. For example, you might prefer more verbose explanations or have specific focus areas.

• Global CLAUDE.md (in the home directory): Captures personal coding philosophy and preferences that apply across projects.

When Claude processes a request, it combines all three files in this order:

1. Global CLAUDE.md (universal preferences).

2. Project-level CLAUDE.md (shared project context).

3. Local CLAUDE.md (personal customizations).

If there are conflicts, the more specific file takes precedence. Local overrides global, which overrides project-level.

Can Claude add instructions to the memory files themselves?

While the /init command creates an excellent baseline context; every project evolves. You’ll discover new patterns, establish additional conventions, and want Claude to understand aspects that weren’t apparent during the initial analysis.

The # command puts you into “memory mode,” a streamlined way to add instructions to CLAUDE.md without manual edits. The simplest form is typing # followed by an instruction:

Claude will intelligently merge this instruction into the appropriate section of your CLAUDE.md file, maintaining good organization, and avoiding duplication. Why don’t you go ahead and try doing this in the terminal below?

We can see that when you use the # command, Claude will merge this instruction into the appropriate section of a CLAUDE.md file, keeping the organization tidy and avoiding duplication. When you use the # command, Claude asks where to save the memory and shows the available CLAUDE.md files, so updating them doesn’t disrupt your workflow.

How do we refer to specific files in Claude Code?

One of Claude Code’s most powerful features is including specific files in a conversation using the @ symbol. This lets us include exactly the files that are relevant to the current question.

The simplest form is @ followed by a file path or pattern:

This automatically includes the contents of src/pages/blog/[...slug].astro, so Claude can answer based on the actual Astro implementation.

Claude Code also supports intelligent file matching. You don’t need exact paths, and a command like @blog can show a list of matches:

We can also include multiple files in a single question:

This gives Claude a complete picture of the blog post layout, component structure, and content configuration, enabling comprehensive suggestions.

Use @ when:

• You’re asking about specific functionality that exists in particular files.

• You want Claude to modify or extend existing code.

• You’re debugging an issue and know which files are involved.

• You need Claude to maintain consistency with existing patterns.

Don’t use @ when:

• You’re asking general questions about the project (Claude can find relevant files on its own).

• You’re not sure which files are relevant (let Claude explore first).

• You’re including so many files that you overwhelm the context.

Can we add context files in CLAUDE.md too?

While the @ symbol includes files in individual conversations, referencing files directly in CLAUDE.md creates persistent context that’s available in every conversation, which is powerful for complex projects.

When files are referenced in CLAUDE.md, their contents are incorporated into Claude’s baseline understanding of your project. This means:

• No repetition: You don’t have to keep referencing the same important files.

• Consistent context: Every conversation starts with the same foundation.

• Automatic updates: If referenced files change, the context updates automatically.

• Team consistency: All team members share the same persistent context.

Add file references to CLAUDE.md using the same @ syntax. For example, a Next.js e-commerce project might include:

However, remember that not every file should be in persistent context. Choose files that are frequently referenced, architecturally important, or convention-defining.

How do we diagnose poor responses after setting up CLAUDE.md?

Persistent context is powerful, but too much can overwhelm Claude and slow down responses. When answers don’t seem quite right, the issue is often context-related.

• If Claude gives generic advice that doesn’t fit the project, the context is insufficient. Add more persistent file references and project conventions to CLAUDE.md.

• If Claude suggests patterns that conflict with existing code, conventions might be missing or outdated. Use # commands to update coding standards and patterns.

• If Claude asks for file contents it should already know, persistent file references are missing. Add frequently referenced files to CLAUDE.md with the @ syntax.

• If responses are slow or inconsistent, the context is overloaded. Prune persistent context to the most essential files.

With solid context management in place, we’re ready for what comes next. In upcoming lessons, we’ll explore advanced communication patterns to orchestrate complex, multi-step development tasks. We’ll learn to give Claude sophisticated planning capabilities, control conversation flow for complex debugging sessions, and eventually coordinate multiple AI agents working on different aspects of a codebase.