Abhishek Pandit

Posted on Jun 10

Your AI's Employee Handbook: A Deep Dive Into CLAUDE.md

#claudecode #ai #productivity #beginners

Part 2 of 7 · Series: Building Your AI Developer Handbook · GitHub

The Problem This File Solves

Imagine hiring a brilliant intern — photographic memory, types 500 words per minute, knows every programming language. But there's a catch: every morning they walk in with zero memory of yesterday. They don't know your name, your project, your rules, or what you told them last week.

That's Claude without a CLAUDE.md file.

CLAUDE.md is the handbook you hand that intern on Day 1. It loads automatically at the start of every session. Claude reads it before doing anything else.

"Rules written down are remembered. Rules spoken once are forgotten." — Every manager ever.

Where This File Lives

~/.claude/CLAUDE.md          ← loads for EVERY project (global)
your-project/.claude/CLAUDE.md  ← loads only for this project

Two levels:

Global = rules about you (who you are, how you work, what you never break)
Project = rules about this codebase (which framework, which patterns, which shortcuts)

Section 1: Who I Am

Senior full-stack engineer. macOS. Read code first.
Verify external API/library behavior with context7 — training data may be stale.

This two-line description changes everything. Claude adjusts its explanations based on who it's talking to. Tell it you're a senior engineer — it skips the basics and goes straight to trade-offs.

It's like the difference between explaining a recipe to a chef versus a 10-year-old. Same recipe. Very different explanation.

The context7 note tells Claude: "Before you answer anything about an external library, go look it up — don't trust your memory."

Section 2: Four Core Principles

1. Think before coding
2. Simplicity first
3. Surgical changes
4. Goal-driven

These four rules prevent the four most common AI coding mistakes.

Think Before Coding — AI models are eager. Ask Claude to "fix the login bug" and it will immediately start editing files — even if it misunderstood the bug. This rule forces Claude to state its assumptions out loud before touching anything.

"A surgeon who cuts before diagnosing is a butcher with a medical degree."

Simplicity First — AI models default to comprehensive. Ask for a button — get a button with loading states, error handling, animations, analytics, and an accessibility wrapper. This rule enforces: write the minimum code that solves the problem.

"Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." — Antoine de Saint-Exupéry

Surgical Changes — Claude will "helpfully" clean up adjacent code, rename variables, update unrelated comments. Every change outside the task scope wasn't asked for, wasn't tested for, and could break something unrelated.

"If you ask a cleaner to mop the floor, you don't expect them to rearrange your furniture while they're at it."

Goal-Driven — Define a verifiable success criterion before writing code. "Add a login button" is not a goal. "Users can click the login button and be redirected to the dashboard" is.

"Done means it works, not that you finished typing."

Section 3: Model Rules — Cost Control

Main thread: claude-sonnet-4-6
Sub-agents:  claude-haiku-4-5-20251001  (cheap, fast, simple tasks)
Opus:        only when explicitly asked

Model	Speed	Cost	Best For
Haiku	Fast	Cheap	Search a file, lint, simple edits
Sonnet	Balanced	Moderate	Features, debugging, reviews
Opus	Slower	Expensive	Deep architecture, hard trade-offs

"You don't hire a senior architect to alphabetize your files."

Using Opus for everything is like driving a Formula 1 car to the grocery store. Sub-agents always use Haiku — that one rule cuts session costs by ~40%.

Section 4: The Session Workflow

1. /status   → confirm model
2. /cost     → baseline
3. /plan     → design first, never skip
4. Code
5. pnpm test → BLOCKING
6. /cost     → delta check
7. /code-review
8. /simplify
9. /code-review --comment

This is a pilot's pre-flight checklist.

"Pilots don't skip checklist items because they're in a hurry. The checklist exists because being in a hurry is when mistakes happen."

Each step catches a different failure. Step 5 is blocking — if tests fail, you fix them before proceeding. No exceptions.

Section 5: Universal Rules

Never commit .env

"Your .env file is like your house key. You wouldn't nail it to your front door for strangers to copy."

Bots scan GitHub 24/7 for exposed credentials. An exposed key can be exploited within minutes. Keep .env.example (key names, no values) in the repo. Keep .env only on your machine.

Conventional commits

feat: add login button
fix: correct password validation
chore: update dependencies

"A well-labeled filing cabinet takes 10 seconds to search. A pile of random papers takes 10 minutes."

WCAG 2.1 AA accessibility — every interactive UI must work for screen readers, keyboard-only navigation, and low-contrast displays. Both an ethical standard and a legal requirement in many countries.

Never touch code outside task scope — every change outside scope wasn't reviewed, wasn't tested for, wasn't asked for.

Write Your Own CLAUDE.md

Here's the minimum viable version for a beginner:

# My Claude Handbook

## Who I Am
[Your role, experience level, languages/frameworks you use]

## Rules
1. Ask before assuming anything
2. Write the simplest code that works
3. Never change code I didn't ask you to change
4. Don't say done until I can verify it works

## Never Do
- Commit .env files
- Add features I didn't ask for
- Change files I didn't mention

Start simple. Add rules every time Claude does something you didn't want. Over time, it becomes a precise description of how you work.

Key Takeaway

CLAUDE.md doesn't make Claude smarter. It makes Claude consistent. Consistent with your standards. Consistent with your rules. Consistent whether it's your first session or your hundredth.