Master Claude

Most people think Claude Code is just Claude in a terminal. It is not. It is an agentic coding system that reads your codebase, understands your architecture, writes code, runs tests, and manages git ~ all in a loop where it decides what tools to use next. Understanding the agentic loop is the first step to using it well. This lesson covers the core architecture: how messages flow, how tools are selected, and why giving Claude Code the right context changes everything.

The Agentic Loop

Claude Code runs in a loop: receive input, think, pick a tool, execute, observe the result, think again. Each iteration it decides whether to read a file, run a command, edit code, or respond to you. The loop continues until the task is done or it needs your input. Understanding this loop is the key to working with it effectively ~ you are not chatting, you are collaborating with a system that acts.

Tools Available

Claude Code has access to: Read (read files), Edit (modify files), Write (create files), Bash (run commands), Glob (find files by pattern), Grep (search file contents), Agent (spawn sub-agents), and any MCP tools you configure. Each tool has specific strengths. Read is cheaper than Bash + cat. Glob is faster than find. Knowing which tool does what helps you prompt more effectively.

What Makes It Different

Unlike a chat interface, Claude Code sees your actual codebase. It can read your files, understand your imports, trace your dependencies, and modify code in place. It also persists state across the session ~ edits build on each other, context accumulates, and the system gets smarter about your project the longer you work together.

CLAUDE.md is the most powerful feature most people never use. It is a markdown file at the root of your project that tells Claude Code how your codebase works ~ your conventions, your architecture, your commands, your rules. Without it, Claude Code guesses. With it, Claude Code knows. This lesson covers how to write an effective CLAUDE.md, what to include, what to skip, and the interactive generator below helps you build yours from scratch.

What to Include

A good CLAUDE.md has four sections: tech stack and architecture, code conventions and style rules, common commands (dev, build, test, lint), and project-specific rules (never do X, always do Y). Keep it concise ~ Claude Code reads it at the start of every session, so every line costs tokens. The best CLAUDE.md files are under 100 lines and opinionated.

Where It Lives

CLAUDE.md at your project root is the primary file. Claude Code also reads ~/.claude/CLAUDE.md for global preferences that apply to all projects, and .claude/rules/ for additional rule files. Rules in subdirectories apply only when working in those directories. This hierarchy lets you set global defaults and override per-project.

Build Yours

Use the interactive generator below to build your CLAUDE.md. Pick a template, customize the sections, and copy the output to your project root. A well-written CLAUDE.md is the single highest-leverage thing you can do to improve Claude Code's output quality.

# my-project

## Code Style

- Use TypeScript strict mode
- Prefer named exports over default exports
- Use Tailwind CSS for styling

## Conventions

- Use kebab-case for file names
- Use PascalCase for components
- Never use em dash ~ use tilde instead

## Architecture

- Next.js App Router with src/ directory
- API routes in src/app/api/
- Shared components in src/components/

## Testing

- Run npx tsc --noEmit before committing

Claude Code can run shell commands, edit files, and push to git. That is powerful and dangerous in equal measure. Permission modes control what Claude Code can do without asking. Plan mode is read-only. Default mode asks for each action. Auto mode lets it execute freely. This lesson covers when to use each, how to configure allowlists for trusted commands, and the safety model that prevents Claude Code from running destructive operations without your explicit approval.

The Three Modes

Plan mode: Claude Code can only read files and think. It cannot edit, write, or execute. Use this when you want analysis without risk. Default mode: Claude Code asks permission before each tool use. You approve or deny each action. This is the safe default for new projects. Auto mode: Claude Code executes without asking. Fast but requires trust ~ only use on projects where you have version control and understand the blast radius.

Safety Model

Claude Code has built-in safety rails. It will not force push to main, delete files without confirmation, or run destructive operations silently. Even in auto mode, certain high-risk actions require explicit approval. The safety model is designed so that the worst case scenario of trusting Claude Code too much is a bad commit you can revert ~ not data loss.

Practical Setup

Start with default mode for a new project. As you build trust, add frequently-used commands to the allowlist. After a week, you will know which commands are safe to auto-approve and which you want to review every time. The goal is a permission setup that matches your comfort level ~ not maximum speed, not maximum caution, but the right balance for you.

Every task you do with Claude Code falls into one of five categories: understand code, fix bugs, add features, refactor, and write tests. Each has an optimal approach. Understanding code? Start with a question, not an instruction. Fixing bugs? Paste the error, point to the file. Adding features? Describe the behavior, not the implementation. This lesson maps all five workflows with the exact prompting patterns that produce the best results.

1. Understand Code

Ask questions, not instructions. 'How does the authentication flow work?' is better than 'Read the auth files'. Claude Code will trace imports, read related files, and build a mental model. Follow up with specifics: 'Where does the JWT get validated?' The key is treating it as a pair programmer who has read the entire codebase.

2. Fix Bugs

Paste the error message. Point to the file if you know it. Let Claude Code trace the root cause. The pattern: 'I am getting this error [paste error] when I [describe action]. The relevant code is in src/auth/. Fix it.' Claude Code will read the files, understand the error, propose a fix, and apply it. Always run the failing test after to verify.

3. Add Features

Describe the behavior, not the implementation. 'Add a dark mode toggle to the settings page that persists in localStorage' is better than 'Create a useState for dark mode and add a button'. Let Claude Code decide the implementation details ~ it knows your codebase better than a generic instruction.

4. Refactor

Be specific about what and why. 'Extract the email validation logic from UserForm.tsx into a shared utility ~ it is duplicated in RegisterForm.tsx and ProfileForm.tsx.' Claude Code will read all three files, extract the common logic, and update the imports.

5. Write Tests

Point to the file and say what to test. 'Write unit tests for src/utils/pricing.ts ~ cover edge cases for zero quantities and discount codes.' Claude Code will read the file, understand the functions, and generate tests using your project's testing framework.

Context is tokens. Tokens cost money and fill up the window. The best Claude Code operators actively manage context ~ they know when to use /compact to summarize, when to start a fresh session, and when to let the context grow. They write CLAUDE.md files that front-load the right information. They use sub-agents for research so the main context stays clean. This lesson teaches you to think about context as a resource you manage, not a buffer that fills up.

Context is Money

Every token in the context window costs money. A session that reads 50 files to answer a question costs more than one where you point to the right file upfront. Write better CLAUDE.md files. Give specific file paths when you know them. Use /compact when the context grows large. Start fresh sessions for unrelated tasks.

/compact ~ Your Best Friend

The /compact command summarizes the entire conversation into a compressed form. It preserves the key decisions, file changes, and context while dramatically reducing token count. Use it when you notice the session getting slow, when you are switching to a different part of the codebase, or when Claude Code starts repeating itself.

Sub-Agents for Research

When Claude Code needs to search broadly ~ finding all usages of a function, understanding a module's architecture ~ it spawns sub-agents. These agents do the heavy reading in their own context and report back a summary. The main context stays clean. You can also trigger this explicitly by asking questions that require broad codebase exploration.

Claude Code understands git natively. It can create branches, stage changes, write commit messages, create pull requests, and even review PRs by reading diffs and comments. The key is knowing how to ask. This lesson covers the git workflows: from committing with good messages to reviewing someone else's PR to resolving merge conflicts. The goal is a git workflow where Claude Code handles the mechanics and you handle the judgment calls.

Commits That Tell a Story

Claude Code writes excellent commit messages when you let it. After making changes, just say 'commit this'. It will stage the right files, write a message that describes the why (not just the what), and include a Co-Authored-By attribution. If you want a specific style, put your commit conventions in CLAUDE.md.

PR Reviews

Claude Code can review PRs by reading the diff, understanding the changes in context, and providing actionable feedback. It checks for bugs, security issues, performance problems, and style violations. The output is a structured review with specific line references. Use this for self-review before requesting human review ~ it catches things you miss after staring at code for hours.

Branch Strategy

Claude Code works best on feature branches. Create a branch, make changes, commit, create a PR. If you are working on multiple features, use separate sessions for each branch. Claude Code tracks the branch context and will not accidentally mix changes across branches.