CLAUDE.md and Plan Mode

We have reached the real treasure, @name! These two features are what separate plain "chatting with an AI" from professional vibecoding with Claude Code.

CLAUDE.md - the heart of the project

The most important file in your work with Claude Code is CLAUDE.md - a markdown file in the root directory of the project that Claude loads automatically at the start of every session. It is the map you hand to your navigator before he even sets foot on deck.

It pays to be precise about what that file is, because sailors get it wrong. CLAUDE.md is a markdown project-memory file holding your conventions, architecture and commands. It is not an npm config that replaces

package.json

, it is not a log of TypeScript compiler errors, and it is certainly not a binary file with the Claude model inside. It is plain text you can read, edit and commit like any other file in the repo.

What to put in CLAUDE.md?

• Conventions - how to name files, what code style to use, how to format
• Architecture - directory structure, key modules
• Commands - how to run the project, the tests, the linter, the build

How do you generate it?

The easiest route is to let Claude do it for you. Type this in a session:

1/init

The process always runs in the same four steps: you type the

/init

command in a session, Claude analyzes the project structure, a ready CLAUDE.md file is created in the root directory, and from that point on Claude automatically loads it in every subsequent session. You can still edit it by hand afterwards, or open it from inside a session with the

/memory

command - that is the command that edits your project memory, not

/save

and not

/file

.

The CLAUDE.md file hierarchy

• ~/.claude/CLAUDE.md

  - global, works across all projects

• CLAUDE.md

  - in the project root directory

• CLAUDE.md

  in subdirectories - for specific parts of the project

Read that list from the most global to the most specific: the one in your home directory applies everywhere, the one in the project root applies to this ship only, and a nested one applies to a single deck of it. Claude merges them, and the more specific file wins where they disagree.

An example CLAUDE.md:

1# My Project - Online Store
2
3## Stack
4- Next.js + TypeScript
5- Tailwind CSS
6- Prisma + PostgreSQL
7
8## Commands
9- `npm run dev` - development server
10- `npm test` - tests
11- `npm run lint` - linter
12
13## Conventions
14- Components: PascalCase in src/components/
15- Always add TypeScript types
16- Tests next to the files, in a __tests__/ directory

Notice the shape of that file, because it is a good default: the project title first, then the Stack (Next.js, TypeScript, Tailwind), then the Commands (

npm run dev

,

npm test

), then the Conventions (PascalCase, TypeScript types). Stack before commands before conventions - you tell Claude what the ship is made of, then how to sail it, then the rules of the crew.

Plan Mode - the newest power

This is one of the newest and most important features in Claude Code. In Plan Mode Claude first explores the project and proposes a PLAN of action, and only edits files after you approve it.

That makes it perfect for large, risky changes - you see what Claude intends to do BEFORE it touches a single line of code.

How do you enable Plan Mode?

There are two ways:

1. The Shift+Tab key - it cycles through the permission modes inside a session, and one of them is exactly Plan Mode
2. A flag at startup:

1claude --permission-mode plan "Rebuild the auth system to use JWT"

The flag is

--permission-mode

followed by the value

plan

, then your prompt in quotes. Watch out for look-alikes that simply do not exist in Claude Code: there is no

--temperature plan

, no

--glob plan

and no

--output plan

. Only

--permission-mode plan

starts the session in planning mode.

Permission modes

Claude Code has a handful of modes that decide how much it may do on its own:

• default

  - asks for approval before important actions (this is the default)

• plan

  - only plans and explores, never edits until you approve

• acceptEdits

  - automatically accepts Claude's file edits

• bypassPermissions

  - skips permission prompts entirely (handle with care!)

Line them up from the most cautious to the most autonomous and you get:

plan

, then

default

, then

acceptEdits

, then

bypassPermissions

. Note that

acceptEdits

accepts edits automatically - it does not block editing, it does the opposite. You switch between modes on the fly with Shift+Tab or with the

--permission-mode

flag.

The Plan Mode workflow

1# 1. Enable Plan Mode
2claude --permission-mode plan "Add a shopping cart to the store"
3
4# 2. Claude explores the project and presents a PLAN:
5#    - which files it will create
6#    - which it will modify
7#    - in what order
8
9# 3. You read the plan and approve it
10
11# 4. Only now does Claude make the changes in the code

Those four steps never swap places: enable the mode, let Claude explore and present the plan of changes, read the plan and approve it, and only then does Claude make the changes in the code. If the plan looks wrong, you correct it in conversation and nothing has been broken - the cheapest mistake is the one caught on the map, not on the reef.

Settings and permissions (settings.json)

You steer the behaviour of Claude Code through settings files:

• .claude/settings.json

  - project settings (committed to the repo)

• ~/.claude/settings.json

  - global settings

In the settings you define permission rules - allow and deny patterns:

1// .claude/settings.json
2{
3  "permissions": {
4    "allow": [
5      "Bash(git*)",
6      "Bash(npm run test)"
7    ],
8    "deny": [
9      "Bash(rm -rf*)"
10    ]
11  }
12}

Read the pattern

Bash(git*)

piece by piece: the tool name

Bash

, an opening parenthesis, the command pattern

git*

, a closing parenthesis. It means "allow any git command without asking". Thanks to rules like these your

git

commands run without a prompt, while a dangerous

rm -rf

is blocked outright. The same file also holds environment variables, the default model and hooks (more on those in the next exercise). And note the filename - permission rules live in

.claude/settings.json

. There is no

.claude/temperature.json

, no

claude.config.js

, and

tsconfig.json

belongs to TypeScript, not to Claude.

Managing context in long sessions

The longer the conversation, the more context you burn. Two commands matter here:

1# Clear the context and start from a clean slate
2/clear
3
4# Summarize the conversation so far and continue (keeps the gist, saves tokens)
5/compact

So

/clear

resets the context and starts the conversation fresh, while

/compact

summarizes and continues a long conversation. You type the second one as a slash followed by the word

compact

. That is the whole toolkit - there are no

/context show

or

/context clear

commands, and you never have to restart the terminal to get a clean slate.

You can check the cost of a session with:

1/cost

/cost

shows your token usage and the session cost - useful when a long refactor starts to feel expensive. It is

/cost

, not

/context

, and not

/save

or

/file

either.

Context discipline also decides how you handle many files at once. There is no

--glob

flag that processes everything in one shot, but batch processing absolutely works - you just steer it yourself. Either write a bash for-loop that calls

claude -p

once per file, or pass several files via

@

in one prompt:

1# One file at a time - a bash for-loop calling claude -p per file
2for file in src/components/*.tsx; do
3  cat "$file" | claude -p "Add JSDoc comments to this component"
4done
5
6# Or several files at once, referenced with @ in a single prompt
7claude "Compare @src/api/users.ts and @src/api/orders.ts and unify the error handling"

The loop keeps every file in its own small, clean context, which is what you want for repetitive work across a whole directory. The single prompt with several

@

references is what you want when the files have to be understood together - a comparison, a shared refactor, a bug that spans two modules.

Summary

CLAUDE.md - project memory, loaded automatically; generate it with

/init

Hierarchy - global

~/.claude/CLAUDE.md

+ project root + nested files Plan Mode - Claude plans before editing;

Shift+Tab

or

--permission-mode plan

Permission modes - plan / default / acceptEdits / bypassPermissions settings.json - allow/deny rules (e.g.

Bash(git*)

), env, model Context -

/clear

,

/compact

, cost via

/cost

In the last two exercises you will meet subagents, skills, MCP and hooks - the genuinely new powers of Claude Code!

See you there!