Claude Code Hands-on #1 — Context Management to Custom Commands

This post is a translation and summary of the official Anthropic course Claude Code in Action. This is the first installment of the Hands-on series.

What Is Context Management#

When bringing Claude Code into a development project, context management is the single most important skill to master.

A project might have dozens or hundreds of files, but Claude only needs a small fraction of them at any given moment. In fact, providing too much irrelevant information actively degrades Claude's performance.

The goal is straightforward — guide Claude to see only the information it needs right now.

/init — First-Run Project Analysis#

When running Claude Code on a new project for the first time, start with the /init command. Claude will analyze the entire codebase to understand:

• The project's purpose and overall architecture
• Key commands and the locations of important files
• Coding patterns and structure

After the analysis, Claude summarizes its findings and generates a CLAUDE.md file.

When it asks for permission to create files, press Enter to approve each one individually, or press Shift+Tab to allow file writes freely for the entire session.

The CLAUDE.md File#

CLAUDE.md is a file that Claude Code automatically reads with every request. It serves two purposes:

• Helps Claude quickly understand the codebase so it can find relevant code
• Acts as a place to store general instructions to pass along to Claude

Claude Code recognizes CLAUDE.md at three different levels:

All three files are included in every request sent to Claude.

Memory Mode — The # Shortcut#

Typing # activates Memory Mode, which lets you intelligently edit CLAUDE.md files.

For example, if Claude is adding comments too frequently, type:

# don't write comments so often

Claude will automatically merge this instruction into the appropriate CLAUDE.md file.

Once added, Claude won't repeat the same mistake in future conversations. This is especially powerful when paired with the Escape to stop → # to correct → continue workflow.

@ File Mentions#

When Claude needs to look at a specific file, type @ followed by the file path to automatically include that file's contents in the request.

How does the auth system work? @auth

This is far more efficient than having Claude search through the codebase on its own. By pointing directly to the relevant file, you get an answer immediately — no searching required.

You can use the same @ syntax inside CLAUDE.md as well. If a file is referenced frequently across many parts of the project, registering it in CLAUDE.md upfront is a good idea.

# Reference the @prisma/schema.prisma file anytime you need to understand
# the structure of data inside the database

Files registered this way are automatically included in the context of every request, so Claude can respond immediately to related questions.

Communicating with Screenshots#

One of the most effective ways to communicate with Claude is through screenshots.

When you want to modify a specific part of the UI, attaching a screenshot lets Claude understand exactly what you're referring to.

To paste a screenshot, use Ctrl+V. On macOS, this is Ctrl+V — not Cmd+V. After pasting the image, describe the changes you want and Claude will take it from there.

Planning Mode#

To encourage Claude to thoroughly explore the codebase before starting implementation on complex tasks, activate Planning Mode.

Press Shift + Tab twice. (If you're already in auto-approval mode, once is enough.)

In Planning Mode, Claude will:

• Read project files more broadly
• Write a detailed implementation plan
• Show you exactly what it intends to do
• Wait for your approval before taking any action

As you review the plan, you can redirect Claude on the spot if anything looks off.

Thinking Mode#

Claude offers a Thinking Mode that allows it to spend more time reasoning through complex problems before responding.

All you need to do is include one of these keywords in your request:

Each level allocates more tokens to Claude, enabling deeper analysis of difficult problems.

Keep in mind that both features consume additional tokens, so factor in the cost implications.

Planning vs Thinking — When to Use Which#

The two modes address different types of complexity.

Planning Mode is best for:

• Tasks that require understanding the codebase broadly
• Changes affecting multiple files or components
• Multi-step implementations

Thinking Mode is best for:

• Complex logic problems
• Hard-to-diagnose bugs
• Algorithm challenges

Using both modes together gives you both breadth and depth.

Conversation Flow Control#

When working through complex tasks, you'll sometimes need to take direct control of the conversation flow.

Escape — Stopping Claude#

When Claude is heading in the wrong direction or trying to do too much at once, pressing Escape immediately stops the response.

This is especially useful when Claude keeps making the same mistake:

1. Press Escape to stop the current response
2. Use the # shortcut to add the correct approach to memory
3. Continue the conversation with the updated guidance

The same error won't repeat in future exchanges.

Escape Twice — Rewinding the Conversation#

As a long conversation grows, it tends to accumulate solved debugging steps and tangential content that clutters the context.

Pressing Escape twice displays a list of sent messages and lets you rewind to any earlier point.

• Claude's accumulated understanding of the codebase is preserved
• Only the unnecessary conversation history is removed

/compact#

The /compact command summarizes the entire conversation while preserving the key information Claude has learned.

Use it when:

• Claude has built up significant knowledge about the current task
• You want to move on to a related next task
• The conversation has grown long but still contains important context

/clear#

The /clear command completely wipes conversation history and starts fresh.

Use it when switching to an entirely different task, or when previous context might interfere with the new work.

Custom Commands#

Beyond the built-in commands, Claude Code lets you register frequently used workflows as custom commands.

How to Create One#

1. Open the .claude folder in your project
2. Create a commands directory inside it
3. Create a Markdown file named after the command you want (e.g., audit.md)

The filename becomes the command name. audit.md → /audit

After adding a custom command, restart Claude Code for it to be recognized.

Example — /audit#

Here's a /audit command for checking dependency vulnerabilities:

1. Run `npm audit` to find vulnerable packages
2. Run `npm audit fix` to apply updates
3. Run tests to verify nothing broke

Passing Arguments — $ARGUMENTS#

Use the $ARGUMENTS placeholder to pass dynamic arguments to a command.

For example, create a write_tests.md file like this:

Write comprehensive tests for: $ARGUMENTS

Testing conventions:
* Use Vitest with React Testing Library
* Place test files in a __tests__ directory next to the source file
* Name test files as [filename].test.ts(x)
* Use @/ prefix for imports

Coverage:
* Test happy paths
* Test edge cases
* Test error states

Then invoke it like this:

/write_tests the use-auth.ts file in the hooks directory

Arguments aren't limited to file paths — you can pass any string that gives Claude direction and context.

Summary#