Part 1 of 7 · Series: Building Your AI Developer Handbook · GitHub
The Full Series
| Part | Title | What you'll learn |
|---|---|---|
| 1 | Overview — the full system | Why discipline matters, how all 7 layers fit together |
| 2 | Your AI's Employee Handbook: CLAUDE.md | How to write the file Claude reads every session |
| 3 | Teaching an AI to Never Forget | The memory system — lessons that survive sessions |
| 4 | Battle Scars as Rules | The 8 feedback rules and the stories behind them |
| 5 | Your Coding DNA | Architecture, state management, and testing preferences |
| 6 | Context is King | Project context files and the template system |
| 7 | A Day in the Life | Complete 9-step session walkthrough with a real feature |
A plain-English walkthrough of my Claude Code workflow — written so anyone, including students, can understand what's happening and why.
The Problem With AI Coding Tools Out of the Box
AI coding assistants are fast. Dangerously fast.
They write code before they understand the problem. They touch files you didn't ask them to touch. They say "done!" before verifying anything works. They forget everything you told them last session.
Speed without discipline isn't productivity — it's just faster ways to create bugs.
This is the system I built to fix that.
What is Claude Code?
Claude Code is an AI assistant that runs in your terminal — not a chat window. It reads your files, runs your tests, writes and edits code, and operates as a real collaborator inside your project. Think of it as a pair programmer that never sleeps, but needs clear rules to not go rogue.
The files in this walkthrough are the rules I give Claude at the start of every session.
Layer 1 — The Handbook (~/.claude/CLAUDE.md)
Every employee gets an onboarding handbook. This file is Claude's.
It loads automatically at the start of every session, regardless of which project I'm in. It tells Claude who it's working with, how to behave, and what it's never allowed to do.
Four Core Principles That Prevent the Most Common AI Mistakes
1. Think before coding
2. Simplicity first
3. Surgical changes
4. Goal-driven
Think before coding — Claude will happily implement the wrong solution perfectly. This rule forces it to state its assumptions and ask when something is unclear, before writing a single line.
Simplicity first — AI models default to comprehensive. Ask for a button, get a button + loading state + error boundary + animation + accessibility wrapper. This rule enforces: write the minimum code that solves the problem. Nothing speculative.
Surgical changes — Claude will refactor your entire codebase if you let it. The rule: touch only what the task requires. Never improve unrelated code.
Goal-driven — Define a verifiable success criterion. Loop until it passes. Don't declare done until the goal is confirmed met — not assumed met.
Layer 2 — Model Rules (The Cost Control System)
Not all AI tasks need the same horsepower.
Main work: Sonnet (mid-tier — capable, cost-efficient)
Simple tasks: Haiku (cheapest — search, lint, single-file edits)
Hard problems: Opus (most powerful — only when explicitly needed)
Why this matters:
Claude models bill per token — roughly per word of input and output. Three tiers exist at very different price points. Using the most powerful model for every task is like hiring a senior architect to alphabetize your files.
The rule: Haiku for boring sub-tasks (searching files, running checks), Sonnet for real coding work, Opus only when Sonnet genuinely isn't enough. This keeps costs sane without sacrificing quality where it counts.
Layer 3 — The 9-Step Session Workflow
This is the most important part of the whole system.
Every coding session follows this exact sequence:
Step 1 — /status Confirm which model is loaded and at what effort level
Step 2 — /cost Snapshot current token spend (baseline before work starts)
Step 3 — /plan Design the solution BEFORE touching any code
Step 4 — Code Actual implementation
Step 5 — pnpm test BLOCKING. All tests must pass. Zero exceptions. Fix failures here.
Step 6 — /cost Check spend delta (don't burn budget reviewing broken code)
Step 7 — /code-review AI reviews the diff for bugs and design issues
Step 8 — /simplify AI cleans up messy code (not bug hunting — readability only)
Step 9 — /code-review --comment Post review findings as inline GitHub PR comments
Why this order matters:
Imagine building a house by picking up a hammer, building walls, then realizing you skipped the blueprint — so you tear it down and start over. That's what most developers do with AI: prompt, get code, ship, find bugs in production.
Each step in this sequence is a gate that catches a different class of failure:
- Plan first catches wrong solutions before any code is written
- Tests catch logic bugs — broken behavior
- Code review catches design bugs — bad structure, security issues, edge cases missed
- Simplify catches readability debt — code that works but nobody can maintain
- Second review confirms the cleanup didn't introduce new issues
Skipping any gate means that class of failure makes it further down the pipeline — where it costs more to fix.
Layer 4 — Universal Rules (The Non-Negotiables)
These rules apply to every project, every session, no exceptions.
Never Commit .env
Your .env file holds API keys, database passwords, and secrets. Committing it to GitHub means handing those keys to anyone who can view your repository — including strangers, bots, and automated scrapers that watch GitHub 24/7.
The pattern: maintain a .env.example file that shows the shape of your config (key names, no values). Anyone cloning the project knows what to fill in without getting your credentials.
Conventional Commits
feat: add user login flow
fix: correct token expiry check
chore: update dependencies
refactor: extract auth middleware
This naming convention makes git history readable by both humans and machines. Changelogs write themselves. CI pipelines can trigger on feat: commits but skip chore: ones. Future-you can scan three months of history in 30 seconds.
WCAG 2.1 AA Accessibility
Every interactive UI element must meet this accessibility standard. That means: screen readers can navigate it, keyboard-only users can operate it, color contrast is sufficient for low-vision users.
This is both an ethical baseline (your product should work for everyone) and a legal requirement in many countries. It's not optional.
Never Touch Code Outside Task Scope
The single biggest risk when using AI tools. Claude will "helpfully" refactor adjacent code, rename variables for consistency, or update comments in files you never mentioned. Every change outside scope is a change that wasn't reviewed, wasn't tested for, and wasn't asked for.
The rule keeps diffs reviewable and trust maintainable.
Layer 5 — Skills (Specialized Playbooks for Specific Situations)
Skills are structured workflows that Claude invokes when specific situations arise. Instead of improvising, it follows a proven checklist.
Building a new feature? → brainstorming → architecture decision → written plan → wait for approval
Found a bug? → systematic-debugging skill
UI change? → frontend-design → accessibility audit → performance check
Adding a dependency? → security audit first, always
Why not just ask Claude directly?
Because improvised AI work skips steps. Without structure, Claude jumps straight to implementation. The /brainstorming skill, for example, forces Claude to explore the problem space — alternative approaches, trade-offs, edge cases — before suggesting a solution.
Without it: technically correct solution to the wrong problem. With it: you catch misalignment before writing a single line.
Skills turn Claude from an improviser into a disciplined practitioner who follows proven processes for high-stakes situations.
Layer 6 — Token Hygiene (Performance and Cost Management)
Claude's "memory" within a session is like RAM — it's limited, and what you put in it matters.
.claudeignore
Every project gets this file:
node_modules/
dist/
.git/
*.log
coverage/
.next/
build/
node_modules/ alone can contain millions of lines of code. If Claude reads those files, it wastes its context window on irrelevant third-party code and charges you for every token. This file tells Claude "don't look here" — same idea as .gitignore.
/compact Command
After a long debugging session, Claude may have read 50 files, run 20 commands, and accumulated thousands of lines of context. That context slows responses and costs money to process.
/compact summarizes the session history, keeps the essential context, and frees space — like clearing browser tabs when your machine starts slowing down.
Targeted Reads
Never ask Claude to scan the entire codebase. Always point it at specific files. This keeps context clean, responses fast, and costs low.
Layer 7 — Memory (Lessons That Survive Sessions)
By default, Claude remembers nothing between sessions. Every conversation starts fresh. This is the biggest limitation of AI tools — you re-explain preferences, re-establish context, re-teach lessons from past mistakes.
The memory system fixes this. A folder of markdown files stores things Claude should remember across all future conversations.
Examples from Real Sessions
"Never mock the database in tests"
Mocked tests passed. Real production migration failed. The mocks didn't reflect actual DB behavior. Lesson: integration tests must hit a real database — no shortcuts.
"No useCallback/useMemo by default"
Premature optimization adds noise to every component. Only add memoization after a profiler confirms there's an actual re-render problem. Assumption-based optimization makes code harder to read and maintain.
"State management ladder: useState → Zustand → TanStack Query"
-
useState: local UI state, one component - Zustand: shared client state (modal flags, user preferences)
- TanStack Query: anything from a server (fetching, caching, mutations)
Never put server/async state in Zustand. This rule prevents the classic bug: stale server data living in a client store, getting out of sync with what the API actually returns.
"Feature-based folder structure"
/features/auth/
AuthForm.tsx
AuthForm.test.tsx
useAuth.ts
auth.types.ts
Everything related to a feature lives together. When you delete a feature, you delete one folder — not hunt through six directories for scattered files.
Putting It All Together
Here's what a typical session looks like in practice:
- Open terminal, navigate to project
- Claude loads the handbook (CLAUDE.md) automatically
- Run
/status— confirm correct model - Run
/cost— note starting spend - Run
/plan— describe the task, Claude designs the solution before coding - Review and approve the plan
- Claude implements, using Haiku sub-agents for simple search/read tasks
- Run tests — if any fail, fix before moving on
- Check
/cost— note delta - Run
/code-review— AI reviews the diff - Run
/simplify— clean up the code - Run
/code-review --comment— post findings to the PR
Total time per feature: slower than just prompting Claude and shipping. But the defect rate is dramatically lower, the code is actually maintainable, and nothing has ever reached production broken because a test gate was skipped.
The One-Paragraph Summary
Most AI coding tools are fast but undisciplined — they write code before understanding the problem, touch things they shouldn't, and forget everything between sessions. This workflow treats Claude like a disciplined senior developer: give it a handbook (CLAUDE.md), have it follow a process (9-step session workflow), use specialist playbooks for specialist problems (skills), remember lessons from past work (memory), and control costs by matching tool power to task complexity (model tiers). The result is an AI collaborator that's genuinely faster than working alone — without the "it worked on my machine" false confidence.
Built and refined over multiple projects. The system evolves — but the discipline doesn't.
The Full Series
| Part | Title | What you'll learn |
|---|---|---|
| 1 | Overview — the full system | Why discipline matters, how all 7 layers fit together |
| 2 | Your AI's Employee Handbook: CLAUDE.md | How to write the file Claude reads every session |
| 3 | Teaching an AI to Never Forget | The memory system — lessons that survive sessions |
| 4 | Battle Scars as Rules | The 8 feedback rules and the stories behind them |
| 5 | Your Coding DNA | Architecture, state management, and testing preferences |
| 6 | Context is King | Project context files and the template system |
| 7 | A Day in the Life | Complete 9-step session walkthrough with a real feature |
Next: Part 2 — Your AI's Employee Handbook: A Deep Dive Into CLAUDE.md
Top comments (0)