Claude Code: How It Actually Works

Essential Files & Folder Structure

🎯

What to show: Open a real project folder in your terminal. Run ls -la and point out these files as they appear.

your-project/ — What Claude Code sees when it opens your project

your-project/

📄 CLAUDE.md ← Claude's brain for THIS project

📄 CLAUDE.local.md ← YOUR personal overrides (gitignored)

📁 .claude/ ← Claude Code config folder

⚙️ settings.json ← permissions, MCP, tools

📄 settings.local.json ← your local settings override

📁 src/

📄 package.json

📄 README.md

~/.claude/ ← global, across ALL your projects

📄 CLAUDE.md ← your personal preferences, always loaded

📁 memory/ ← Claude's auto-saved notes

⚙️ settings.json ← global defaults

          CLAUDE.md — Starter Template
          MARKDOWN
        

# My Project Name

## What This Project Is
A dashboard for tracking client KPIs.
Built for non-technical users.

## Stack
- HTML, CSS, vanilla JavaScript
- No frameworks (keep it simple)
- Data: paste from Google Sheets

## Rules Claude Must Follow
- Never use jargon in comments
- Always add mobile-responsive CSS
- Keep components under 100 lines
- Use semantic HTML (no div soup)

## Current Status
- ✅ Hero section done
- 🔄 KPI cards in progress
- ⬜ Chart component todo
        

          .claude/settings.json — Permissions
          JSON
        

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read(**)",
      "Write(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Write(.env)"
    ]
  },
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["notion-mcp"]
    }
  }
}
        

💡

Teaching moment: The settings file is where you control what Claude Code is allowed to do. It's like giving an assistant a job description with clear boundaries — they can write to your src/ folder but can never delete files or touch your secrets.

The 4-Layer Memory System

🧠

Key insight to convey: Claude Code has NO memory between sessions by default — but CLAUDE.md is how you give it permanent memory. Click each layer to expand.

🌍

Layer 1 — Global

~/.claude/CLAUDE.md

All projects

Always loaded, every project. Put things here that are true about YOU as a builder — your preferred stack, communication style, naming conventions you always use.

Example contents: "Always write comments in plain English. I prefer dark-themed UI. I'm a non-technical founder so explain decisions in simple terms."

📁

Layer 2 — Project

CLAUDE.md (project root)

This project only

The most important file. Lives at the root of your project. Loaded every session. Contains: what the project does, the tech stack, rules Claude must follow, current status, and any context a new "team member" would need.

Critical behavior: This file survives /compact — even when Claude forgets the conversation, it re-reads this file from disk.

📂

Layer 3 — Directory

src/api/CLAUDE.md

That folder only

Scoped rules for specific folders. Only loads when Claude works in that subdirectory. Use this for different rules in different parts of your app — e.g. strict validation rules for your API folder, looser rules for prototypes.

Advanced use: override project-level rules for a specific component or module.

🤖

Layer 4 — Auto Memory

~/.claude/memory/ (auto-generated)

Claude writes this

Claude takes its own notes. Requires v2.1.59+. Claude decides what's worth saving — build commands, debugging insights, your preferences, architecture decisions. Organized into 4 categories: user preferences, your feedback/corrections, project context, and reference pointers.

Run /memory to browse what Claude has saved. Everything is plain Markdown you can read, edit, or delete.

      Best-Practice CLAUDE.md for Non-Technical Builders
      MARKDOWN
    

# Project: [Name]
# This file tells Claude everything it needs to know. Update it as the project evolves.

## Project Overview
[2 sentences: what this does and who it's for]

## My Technical Level
Non-technical founder. Explain decisions in plain English.
No jargon. If code must be complex, add a comment explaining why.

## Stack (Keep Simple)
- HTML + CSS + vanilla JS only (no React, no frameworks)
- No external dependencies unless absolutely necessary
- Single-file components preferred

## Non-Negotiable Rules
- Mobile responsive on EVERY component
- Accessibility: always use semantic HTML
- Never delete files — move to /archive instead
- Always ask before touching anything in /data

## Current Sprint (update weekly)
Building: [feature name]
Blocked on: [anything]
Done this week: [list]

## Key Decisions Made
- Chose vanilla JS over React: simpler to maintain without a dev
- Using CSV for data: easier for client to update in Google Sheets
- No backend yet: launching with static site first
    

⚠️

Common mistake: People treat CLAUDE.md like a chat message — too long, too conversational. Keep it under 200 lines. Use bullet points. Think of it as a README written for Claude, not for humans. Files over 200 lines reduce how well Claude follows the instructions.

The Build Workflow — Session to Session

🎬

Demo this live: Open a fresh folder in your terminal. Walk through steps 1–4 in real time. The audience sees Claude Code go from blank folder to working product.

01

Install & Launch

One-time setup. Requires Node.js 18+. After install, just type claude from any folder to start a session.

$ npm install -g @anthropic-ai/claude-code

$ claude

💡

Claude Code runs in your terminal — it can see your files, run commands, and write code directly to your disk. This is what makes it different from the web chat.

02

Initialize the Project Memory

Run /init inside an existing project folder. Claude reads your codebase and auto-generates a CLAUDE.md — then you edit it to match your rules.

claude> /init

Claude will generate:

        ✅ CLAUDE.md with project overview

        ✅ Build commands it detected

        ✅ Architecture notes from your files

        → Your job: review and edit it to add your rules

03

Build in Plain English

Describe what you want. Claude reads your files, writes code, runs commands, and shows you results. You review and approve or redirect.

Example session

You:    Build a pricing page with 3 tiers. 
        Monthly/annual toggle. Dark mode.

Claude: Reading CLAUDE.md... ✓
        Creating pricing.html... ✓
        Adding toggle JS logic... ✓
        Done. Open index.html to preview.

You:    Make the Pro plan glow and add 
        a "Most Popular" badge.

Claude: Updating pricing.html... ✓
          

04

Use Plan Mode for Big Changes

For major features, switch to Plan Mode first. Claude shows you exactly what it will do — no files are changed. You approve, then it executes.

$ claude --plan

🎯

Teaching moment: Plan Mode = show, don't touch. It's like asking a contractor to give you the project plan before they start demolition. Always use it before building something large or touching existing code.

05

Compact When Context Gets Long

After a long session, Claude's context window fills up. /compact summarizes the conversation but CLAUDE.md is preserved — so nothing important is lost.

claude> /compact

✅

This is why CLAUDE.md matters so much — it's the thing that survives compaction. Anything important that's only in the chat conversation gets lost. Write it in CLAUDE.md.

06

Update CLAUDE.md as You Build

After each session, update CLAUDE.md with decisions made, status changes, and new rules. Think of it as a living project log that Claude reads on every future session.

          ## After Session 3 — Update log:

          + Added: pricing.html with 3 tiers

          + Decision: no backend, using Stripe links

          + Next: auth flow, user dashboard

          - Bug: mobile toggle breaks below 320px

Essential Slash Commands

⌨️

Show these live: Open Claude Code and type / — the autocomplete menu appears. Walk through the most important ones.

/init

Scans your project and auto-generates a CLAUDE.md file. Run this first in any new project.

💡 Start every new project with this

/plan

Shows what Claude will do before it does it. No files are modified. Review and approve the plan first.

💡 Use before any large or risky change

/compact

Summarizes the conversation to free up context window space. CLAUDE.md survives; chat history is summarized.

💡 Use when sessions run long (1hr+)

/clear

Clears the conversation entirely and starts fresh. CLAUDE.md is still re-loaded. Good for starting a new task.

💡 Between different features/tasks

/review

Ask Claude to review the code it just wrote — catch bugs, accessibility issues, performance problems before shipping.

💡 Always run before sending to a client

/status

Shows what's currently in context — which files are loaded, what Claude knows about the session so far.

💡 Use when Claude seems confused

/memory

Opens the memory management panel. Browse, edit, or delete what Claude has auto-saved. Toggle auto-memory on/off.

💡 Check this after a few sessions

# [instruction]

Prefix with # to give Claude a rule for the current conversation only. Claude will suggest adding it to CLAUDE.md permanently.

💡 "# Always explain what you changed"

@path/to/file.md

Import another file's contents directly into CLAUDE.md using @ syntax. Reference docs, specs, or style guides without copy-pasting.

💡 Keep CLAUDE.md lean, import detail

/config

Open configuration settings — model, theme, keybindings, auto-approval preferences, and more.

/mcp

Manage connected MCP servers — see what's connected, add new connections, troubleshoot issues.

/doctor

Diagnoses common issues — checks Node version, API key, permissions, and MCP server connectivity.

💡 First thing to run if something breaks

claude --version

Check which version of Claude Code you're running. Auto-memory requires v2.1.59+.

The Agentic Loop — What's Actually Happening

🔄

The big insight: Claude Code isn't just chatting — it's running a loop of read → think → act → verify → report. You're the manager approving each cycle.

You

💬 Plain English

"Build a login page"

→

Claude

🧠 Reads + Plans

CLAUDE.md + your files

→

Tools

🔧 Takes Action

Writes files, runs code

→

Output

✅ Shows Result

You review & redirect

↩

What Claude Code can DO

📄

Read files — browses your entire codebase

✏️

Write files — creates and edits code directly

⚡

Run commands — npm install, git commit, tests

🌐

Fetch URLs — reads docs and APIs

🔌

Use MCP tools — Notion, GitHub, Slack, etc.

Your role as the builder

🎯

Define the goal — in plain English, be specific

✅

Approve actions — Claude asks before risky moves

🔀

Redirect — "not quite, make it darker, add X"

📝

Update CLAUDE.md — lock in decisions

🚢

Ship it — you decide when it's done

🎯

Analogy that works for non-technical audiences: Claude Code is like a very talented contractor who works in your house. They're skilled, but they need your approval before knocking down walls. The CLAUDE.md is the brief you hand them on day one. Your job is direction, not construction.

MCP Connectors — Giving Claude Superpowers

🔌

The unlock: MCP (Model Context Protocol) lets Claude Code talk to external tools. Instead of copying data between apps, Claude accesses them directly.

        How MCP changes the workflow
      

Without MCP:
You: "Here's the Notion doc I copied... [pastes 800 words] 
     Now build a dashboard from this"

With MCP (Notion connected):
You: "Read my Notion project tracker and build a 
     status dashboard from it"
Claude: Connecting to Notion... reading tracker... 
        Building dashboard... ✓
      

📓

Notion

Read/write databases, pages, tasks directly from Claude Code

🐙

GitHub

Create PRs, read issues, manage repos without leaving terminal

💬

Slack

Read channel history, send messages, summarize threads

📊

Google Sheets

Pull live data, update cells, trigger Claude from sheet changes

📮

Linear

Create tickets, update status, query sprint data

🗄️

Postgres / SQLite

Query your database in natural language, no SQL needed

🌐

Browser (Puppeteer)

Scrape pages, automate forms, take screenshots

📧

Gmail / Calendar

Draft emails, schedule meetings, read inbox context

      Add an MCP server to .claude/settings.json
      JSON
    

"mcpServers": {
  "notion": {
    "command": "npx",
    "args": ["-y", "@notionhq/notion-mcp-server"],
    "env": { "NOTION_API_KEY": "your-key-here" }
  },
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" }
  }
}
    

🎯

For your audience: MCP is the difference between Claude Code being a code writer vs. a full AI coworker. Once connected to Notion + GitHub + Slack, you can say: "Look at what's in my Linear sprint, write the code for the top task, and post a Slack update when it's done."