A journey through every best practice — with a real project.
The Example Project: TodoApp
Running Example
Every technique in this presentation is demonstrated on a TodoApp monorepo — showing the transformation from a plain project to one with full Claude Code configuration.
# With Claude Code Best Practices
todoapp/
.claude/# Claude Code configagents/# Custom subagentsskills/# Domain knowledgecommands/# Slash commandshooks/# Lifecycle scriptsrules/# Modular instructionssettings.json# Team settingssettings.local.json# Personal settingsbackend/
main.py
routes/
todos.py
users.py
models/
todo.py
user.py
tests/
test_todos.py
CLAUDE.md# Backend instructionsfrontend/
components/
TodoList.tsx
Sidebar.tsx
pages/
index.tsx
todos.tsx
lib/
api.ts
CLAUDE.md# Frontend instructions.mcp.json# Managed MCP serversCLAUDE.md# Project instructions
What is Vibe Coding?
This is where everyone starts. The question is: how fast can you move beyond it?
What Happens (Low Level)
> add a notes feature
Claude creates /api/notes with a random schema
Frontend gets a standalone page with no sidebar nav
Tests? None. Patterns? Ignored.
Every new feature is a coin flip. Code entropy increases with every prompt.
What We Want (High Level)
Claude knows the TodoApp architecture
New routes follow existing patterns in routes/todos.py
Frontend uses Sidebar.tsx nav and Tailwind tokens
Tests written automatically matching test_todos.py style
Consistent, tested, production-quality code — every time.
The Journey
From Low to High
Each section adds techniques that move you from vibe coding toward fully agentic engineering.
1Prerequisites
2Better Prompting — Low
3Project Memory — Medium
4Structured Workflows — Medium
5Domain Knowledge — High
6Agentic Engineering — High
Installing Claude Code
Prerequisite
Homebrew must be installed on your Mac.
Install via Homebrew
Run this in your terminal:
brew install claude-code
Verify Installation
claude --version
Update Later
brew upgrade claude-code
Run /doctor anytime to check your installation health.
Login Option A: Subscription
Use your Claude Pro or Max subscription via OAuth login:
claude# Select "Claude.ai" at the login prompt# Opens browser for OAuth
Subscription Tiers
Plan
Price
Weekly Limit
Sonnet 4.5
Opus 4.6
Pro
$20/mo
Base limit
✓
✗
Max 5x
$100/mo
5× Pro limit
✓
✓
Max 20x
$200/mo
20× Pro limit
✓
✓
Weekly limits reset every 7 days. Usage is shared across Claude web, desktop, and Claude Code. Opus 4.6 requires a Max plan.
Login Option B: API Key
Pay per token with an Anthropic API key — no weekly caps:
Token Pricing (per million tokens)
Model
Input
Output
Context Window
Opus 4.6
$5 / MTok
$25 / MTok
200K (1M beta)
Sonnet 4.5
$3 / MTok
$15 / MTok
200K (1M beta)
Haiku 4.5
$0.80 / MTok
$4 / MTok
200K (1M beta)
Setup
export ANTHROPIC_API_KEY=sk-ant-...
claude
Best for: Heavy usage, CI/CD pipelines, teams needing predictable billing
Your First Session
Start Claude Code
Navigate to your project and run:
cd ~/todoapp
claude
What Happens
Claude Code scans your project structure, reads CLAUDE.md (if it exists), and opens an interactive REPL where you can type prompts.
This IS Vibe Coding
Right now, with no CLAUDE.md, no skills, no agents — you're at the Low level. Claude will guess at everything. That's okay. We'll fix it step by step.
The Interface
+-----------------------------------------+|Claude Code v2.1.33
| Model: claude-opus-4-6
| Project: ~/todoapp
+-----------------------------------------+> Type your prompt here...
Quick Reference
⌨
EnterSubmit your prompt
↵
Shift+Enter or \New line (multiline input)
■
Ctrl+CCancel current generation
▶
Ctrl+D or /exitExit Claude Code
Part 2
Better Prompting
Level: Low — effective prompting that produces real, production-quality results.
Your First Prompt
Try This
Start simple — ask Claude to understand your project:
> Read the README.md and give me a summary of this project
Claude will use the Read tool to open the file, then summarize it. You'll see the tool call in the output.
What Just Happened?
1️⃣
Claude read your promptUnderstood you want a summary
2️⃣
Used the Read toolOpened README.md from your project
3️⃣
Responded with a summaryBased on actual file contents, not guessing
Good vs Bad Prompts
The difference between vibe coding and professional usage — shown on our TodoApp:
Vibe Coding
> add a notes feature
Claude creates a random /api/notes endpoint with a new schema that doesn't match models/todo.py. Frontend page has no sidebar nav.
Vague, no context, no constraints.
Professional
> In backend/routes/todos.py, add a
PUT /api/todos/{id}/complete endpoint.
Follow the existing route pattern and
update the Todo model's is_completed field.
Add a test in tests/test_todos.py.
Specific file, specific endpoint, specific pattern.
Providing Context
Key Rule
The more context you give, the better Claude performs. Use @ to reference files directly in your prompt.
TodoApp Example
> Look at @backend/routes/todos.py and @backend/models/todo.py
Add a priority field to the Todo model and update
the create endpoint to accept it.
Context Tips
📄
@file/pathReference specific files for Claude to read
📸
Paste screenshotsCtrl+V to paste images of errors or UI
📋
Paste error logsCopy the full error message into your prompt
Context Window & /compact
Key Concept
Claude has a context window — a limit on how much conversation it can remember. Every prompt, file read, and response fills it up.
What Fills Context
Your prompts and messages
Every file Claude reads
Bash command output
Claude's own responses
/compact — The Fix
> /compact
Compresses conversation history into a summary. Claude continues from that summary.
Best Practice
Run /compact manually at ~50% context usage. Don't wait until it auto-compacts — you lose control over what gets preserved.
/plan — Plan Before Code
Try This
> /plan
> Add user authentication to the TodoApp backend
Without /plan
Claude writes code immediately
Wrong approach — redo everything
50% of context gone before real work starts
With /plan
Claude explores codebase read-only
Proposes approach for your approval
Right approach from the start
Rule of Thumb
Always start with plan mode for any task that touches more than 2-3 files or involves architectural decisions.
Plan Mode in Practice
Step by Step
# Step 1: Enter plan mode> /plan
# Step 2: Describe what you want> Add pagination to the /api/todos endpoint
# Step 3: Claude explores and writes a plan# (reads routes/todos.py, checks models, proposes approach)# Step 4: Review the plan and approve it# Claude then executes the approved plan
TodoApp Benefit
In plan mode, Claude discovers your existing SQLAlchemy pagination pattern before writing a single line — no reinventing the wheel.
Prompting Best Practices
🎯
Be specific about files"In backend/routes/todos.py" not "in the backend code"
🔎
Describe the problem, not just the fix"The API returns 500 when..." not "make it work"
📐
Reference existing patterns"Follow the pattern in routes/todos.py" gives Claude a template
🧩
One task at a timeSmall, focused requests get better results than mega-prompts
✅
Ask Claude to verify"Run pytest after making changes" catches errors early
📸
Provide screenshots for UI issuesA picture is worth a thousand words of description
Part 3
Project Memory
Level: Medium — make Claude remember your project, conventions, and preferences.
CLAUDE.md & /init
Key Concept
CLAUDE.md is a markdown file that Claude reads at the start of every session. It's your project's instruction manual for Claude.
Create It
> /init
TodoApp CLAUDE.md
# CLAUDE.md## Project
TodoApp monorepo: FastAPI backend + Next.js frontend.
## Structure
- backend/routes/ — FastAPI route handlers
- backend/models/ — SQLAlchemy models
- frontend/components/ — React components
- frontend/lib/api.ts — API client
## Commands
- cd backend && uvicorn main:app --reload
- cd frontend && npm run dev
- cd backend && pytest
## Conventions
- Backend: follow route patterns in routes/todos.py
- Frontend: use Tailwind, add nav to Sidebar.tsx
- Always add tests for new endpoints
What to Include in CLAUDE.md
Include
Project architecture overview
Build and test commands
Key file locations
Coding conventions
Common patterns to follow
Critical do's and don'ts
Avoid
Entire API documentation
Long code examples
Secrets or API keys
Information that changes often
Anything over 150 lines total
Critical Rule
Keep CLAUDE.md under 150 lines. Longer files dilute the instructions — Claude may ignore parts of it. Use Rules and Skills for detail.
Keep It Under 150 Lines
If You Need More Space
📄
Use RulesPut topic-specific instructions in .claude/rules/*.md files
📚
Use SkillsPut domain knowledge in .claude/skills/ — loaded on demand
🔗
Reference filesPoint to docs rather than inlining content
Modular, topic-specific instructions in individual markdown files. Unlike CLAUDE.md, rules can be scoped to specific paths.
TodoApp Backend Testing Rule
# .claude/rules/backend-testing.md
---
globs: ["backend/tests/**"]
---
When writing tests for the backend:
- Use pytest with the existing conftest.py fixtures
- Follow the pattern in test_todos.py:
- Use TestClient from FastAPI
- Create test data with factory functions
- Assert status codes AND response body
- Clean up test database after each test
- Name tests: test_{action}_{entity}_{scenario}
- Always test both success and error cases
This rule only activates when Claude is working on test files — keeping context clean for other tasks.
/memory & Memory Hierarchy
Try This
> /memory
Opens your CLAUDE.md memory files in an editor. Changes here persist across all sessions.
Three Scopes (loaded in order)
# All combined at session start:
~/.claude/CLAUDE.md # Global — all projects
.claude/CLAUDE.md # Project — shared with team via git
.claude/CLAUDE.local.md # Local — personal, git-ignored
TodoApp Tip
Put your TodoApp CLAUDE.md in the repo root so the whole team shares it. Put personal preferences (editor, style) in CLAUDE.local.md.
Memory Best Practices
📏
CLAUDE.md under 150 linesBrief, focused, high-signal instructions
📂
Use rules for specificsPath-scoped rules in .claude/rules/ for targeted guidance
👥
Commit project CLAUDE.mdTeam shares project conventions via git
🔒
Use .local.md for personal prefsGit-ignored, won't affect teammates
🔄
Review and trim regularlyOutdated instructions cause confusion
Part 4
Structured Workflows
Level: Medium — systematic approaches that prevent wasted effort.
Task Lists
For complex tasks, Claude creates a task list to track progress:
> Add user authentication to the TodoApp:
- POST /api/register endpoint
- POST /api/login endpoint
- JWT auth middleware
- Protect /api/todos endpoints
- Tests for all auth endpoints
Claude breaks this into individual tasks and shows progress as it works through each one.
Best Practice
Break subtasks small enough that each can be completed in under 50% context. Commit after each subtask.
/model — Model Selection
Try This
> /model
Opens the model picker. Match the model to the task:
🧠
Opus 4.6 (Default)Complex tasks — "Add auth to the TodoApp backend with JWT"
⚡
Sonnet 4.5Everyday coding — "Add a completed_at field to the Todo model"
🏎
Haiku 4.5Simple tasks — "Read backend/routes/todos.py and summarize the endpoints"
Pro Tip
Use Option+P (Mac) or Alt+P to quickly switch models. Use /fast for faster Opus output on non-complex tasks.
Workflow Best Practices
🗺
Always start with plan modeFor any non-trivial task
🧩
Break tasks into small piecesEach subtask should complete in under 50% context
💾
Commit after each subtaskClean rollback points, not one mega-commit
📦
Manual /compact at ~50%Don't wait for auto-compact
🤖
Vanilla Claude Code for small tasksSimple tasks don't need elaborate workflows
Part 5
Domain Knowledge
Level: High — reusable knowledge that Claude loads on-demand.
What Are Skills?
Key Concept
Skills are markdown files that contain domain knowledge — instructions, patterns, or workflows that Claude can load when needed. Think of them as micro-manuals.
Why Skills?
📚
Progressive DisclosureKnowledge loaded only when relevant — doesn't bloat every session
♻
ReusableSame skill works across agents and workflows
👥
ShareableCommit to git — your whole team benefits
Skills vs CLAUDE.md
CLAUDE.md = always loaded, every session. Skills = loaded on-demand, when relevant. Use skills for knowledge that's only needed sometimes.
Creating Skills: TodoApp Frontend
Frontend Conventions Skill
# .claude/skills/frontend-conventions/SKILL.md
---
name: frontend-conventionsdescription: TodoApp frontend patterns and conventions
---
# Frontend Conventions
When creating or modifying frontend components:
## Sidebar Navigation
- Add new page routes to frontend/components/Sidebar.tsx
- Use the existing NavLink pattern with icon + label
- Keep alphabetical order in the nav list
## Component Patterns
- Use functional components with TypeScript
- Import API functions from lib/api.ts
- Follow TodoList.tsx as the reference component
- Use Tailwind classes: bg-white, rounded-lg, shadow-sm
## API Integration
- All API calls go through lib/api.ts
- Use the existing fetch wrapper with error handling
- Base URL: process.env.NEXT_PUBLIC_API_URL
Skill Frontmatter & Invocation
Frontmatter Options
📜
nameSkill identifier (uses directory name if omitted)
📝
descriptionWhen to invoke — helps Claude auto-discover the skill
🤖
modelOverride which model runs the skill
🔧
allowed-toolsRestrict which tools the skill can use
🔁
context: forkRun the skill in an isolated subagent context for complex workflows
Invocation & Execution Modes
# 1. Manual: slash command> /frontend-conventions
# 2. Auto: Claude discovers via description field# (happens when task matches description)# 3. Preloaded: in an agent's frontmatterskills:
- frontend-conventions
# 4. Optional isolation for heavy workflowscontext: fork
Level: High — custom agents that know your codebase and follow your patterns.
What Are Agents?
Key Concept
Agents are markdown files in .claude/agents/ that define a custom Claude persona with its own tools, model, skills, and behavior.
Two Ways to Use Agents
As Main Agent
Replaces default Claude for your conversation.
$ claude --agent frontend-engineer
As Subagent
Spawned in an isolated context via Agent tool.
Task(
subagent_type="frontend-engineer"
prompt="Add a settings page"
)
Frontend Engineer Agent
Without Agent
> add a settings page
Claude creates pages/settings.tsx with:
• Inline CSS (no Tailwind)
• Direct fetch calls (ignores api.ts)
• No sidebar nav entry
Standalone page that doesn't fit the app.
With Agent
Frontend agent already knows:
• Use Tailwind tokens from the design system
• Import API functions from lib/api.ts
• Add route to Sidebar.tsx
• Follow TodoList.tsx component pattern
Integrated page matching the app perfectly.
# .claude/agents/frontend-engineer.md
---
name: frontend-engineerdescription: Frontend development following TodoApp conventionstools: Read, Write, Edit, Bash, Glob, Grepmodel: sonnetskills:
- frontend-conventions
---
You are a frontend engineer for the TodoApp.
Always add new pages to the Sidebar navigation.
Use the existing API client in lib/api.ts.
Follow TodoList.tsx as your reference component.
Backend Engineer Agent
Without Agent
> add a tags feature
Claude creates random endpoint structure
Different error handling than existing routes
No tests, no model validation
With Agent
Backend agent follows existing patterns:
• Route structure from routes/todos.py
• SQLAlchemy model like models/todo.py
• Tests matching test_todos.py style
• Pydantic schemas for validation
# .claude/agents/backend-engineer.md
---
name: backend-engineerdescription: Backend development following TodoApp patternstools: Read, Write, Edit, Bash, Glob, Grepmodel: sonnetskills:
- backend-patterns
---
You are a backend engineer for the TodoApp.
Follow the route patterns in routes/todos.py.
Create SQLAlchemy models matching models/todo.py.
Always add pytest tests for new endpoints.
Use Pydantic schemas for request/response validation.
Agent Frontmatter
# .claude/agents/code-reviewer.md
---
name: code-reviewerdescription: Reviews code for quality and best practicestools: Read, Grep, Globmodel: sonnetcolor: greenskills:
- code-review
memory: user
---
You are a code reviewer. Check for security issues,
performance problems, and suggest improvements.
Review your memory for patterns you've seen before.
Key Fields
🔧
toolsWhat the agent can do (Read, Write, Edit, Bash, etc.)
📚
skillsKnowledge preloaded at startup
🧠
memoryPersistent learning across sessions (user/project/local)
Skills provide static knowledge (what to do). Agents provide execution context (how to do it, with which tools). Together, they're powerful.
Choosing a Model
🧠
opusComplex reasoning, architecture decisions
⚡
sonnetGood balance of speed and capability
🏎
haikuFast, cheap — great for simple, focused tasks
Subagents via Task Tool
Key Concept
Subagents run in an isolated context — separate from the main conversation. They do their work, return a summary, and their context is discarded.
# Claude spawns a subagent automatically or you can ask:> Use the frontend-engineer agent to add a settings page
# Claude uses the Agent tool internally:
Task(
subagent_type="frontend-engineer",
prompt="Add a user settings page to the TodoApp"
)
Built-in Subagent Types
ExplorePlanBashYour Custom Agents
Commands & Orchestration
Commands are the entry points for complex workflows — the Command → Agent → Skills pattern:
# .claude/commands/add-feature.md
---
description: Add a new feature to the TodoAppmodel: opus
---
# Add Feature Command
1. Ask the user what feature to add (AskUserQuestion)
2. Invoke the backend-engineer agent for API work:
- Task(subagent_type="backend-engineer", ...)
3. Invoke the frontend-engineer agent for UI work:
- Task(subagent_type="frontend-engineer", ...)
4. Run tests to verify: pytest + npm test
5. Summarize what was built
Invoke It
Commands live in .claude/commands/. Users invoke them as slash commands: > /add-feature
Hooks & MCP Servers
Hooks
Custom scripts at specific moments in Claude's lifecycle:
PreToolUse — validate commands
PostToolUse — auto-format code
Stop — check task completion
SessionStart — load context
16 hook events, 5 can block execution.
MCP Servers
Connect Claude to external tools via Model Context Protocol:
Playwright — browser automation
Chrome DevTools — console logs
Databases — query data directly
> /mcp
Command → Agent → Skills
The full architecture pattern for complex workflows:
+-----------------------------------------------+|/add-feature (Command) || Entry point — user invokes this || | || +----------+----------+ || v v ||backend-engineerfrontend-engineer|| (Agent) (Agent) || | | ||backend-patternsfrontend-conventions|| (Skill) (Skill) |+-----------------------------------------------+
Your TodoApp now has: CLAUDE.md for project context, Rules for path-scoped conventions, Skills for domain knowledge, Agents for consistent execution, Commands for orchestrated workflows, Hooks for lifecycle automation, and MCP servers for external tools.
Agent Memory
Key Feature
Agents can learn across sessions. Add memory: user to the frontmatter and the agent builds its own persistent knowledge store.
# Agent remembers patterns it discovers
~/.claude/agent-memory/code-reviewer/
MEMORY.md # First 200 lines auto-loaded
react-patterns.md # Topic-specific notes
security-checklist.md # Learned over time
Memory Scopes
user — cross-projectproject — team-sharedlocal — personal
Agents Summary
Creating Agents
Drop .md files in .claude/agents/
Set name, tools, model, skills, memory
Use /agents to manage interactively
Using Agents
Main agent:"agent" in settings.json
Subagent: Agent tool spawns it
CLI:--agent name
Best Practices
Feature-specific agents, not generic ones
Preload skills for domain knowledge
Use haiku model for simple focused tasks
Architecture
Command → Agent → Skills
Progressive disclosure of knowledge
Single execution context per agent
Appendix
Reference
Command references, workflows, settings, and customization options.
How Claude Uses Tools
Claude Code doesn't just generate text — it takes actions using tools:
File Tools
Read — Read file contents
Edit — Modify existing files
Write — Create new files
Glob — Find files by pattern
Grep — Search file contents
Action Tools
Bash — Run shell commands
Task — Spawn subagents
WebFetch — Fetch URLs
WebSearch — Search the web
Skill — Invoke skills
Important
Claude asks for permission before running potentially dangerous commands. Always review what it's about to do.
File Operations
Reading Files
> Read the package.json file
Editing Files
> In src/utils/format.ts, change the date format from MM/DD to DD/MM
Creating Files
> Create a new test file for the user service at tests/user.test.ts
Pro Tip
Always tell Claude which file to edit. Don't say "fix the bug" — say "fix the null check in src/handlers/auth.ts line 42".
Bash Commands & Search
Running Commands
> Run the test suite: npm test
> Check which port the server is using
> Install express as a dependency
Searching the Codebase
> Find all files that import the UserService class
> Search for any TODO comments in the src directory
> Find where the API_KEY environment variable is used
Pro Tip
Use ! prefix for quick bash commands: !git status runs the command and shows output without Claude analyzing it.
/help
Try This
> /help
Shows all available slash commands. This is your starting point when you forget a command.
Daily Use
/model — Switch models
/plan — Plan before coding
/compact — Free up context
/cost — Check spending
Project Setup
/init — Create CLAUDE.md
/memory — Edit memory
/config — Settings
/doctor — Diagnostics
/model — Effort Level
When Opus 4.6 is selected, you can adjust the effort level:
How to Set
Run /model, select Opus, then use ← → arrow keys to change effort.
🔥
High (Default)Full reasoning depth — complex architecture, tricky bugs, large refactors
⚖
MediumBalanced — everyday coding tasks
💨
LowMinimal reasoning — quick, simple tasks where speed matters
/fast — Faster Output
Try This
> /fast
What It Does
Toggles fast mode — same Opus 4.6 model with faster token output. It does NOT switch to a different model.
/context & /cost
/context — Visualize Usage
> /context
Shows a colored grid of your context window — how much is used, what's taking space.
/cost — Track Spending
> /cost
Shows token usage and cost for the current session.
/clear & /rewind
/clear — Fresh Start
> /clear
Clears conversation history completely. Use when switching tasks.
/rewind — Go Back
> /rewind
Rewinds conversation and/or code to an earlier point.
When to Use Which
/clear = new topic. /rewind = same topic, wrong turn. /compact = same topic, low on context.
/resume — Resume Sessions
Try This
# Resume most recent session$ claude --resume
# Or from inside Claude Code:> /resume
Opens a session picker showing your recent conversations. Select one to continue where you left off.
/doctor — Diagnostics
Try This
> /doctor
Checks the health of your Claude Code installation:
✅
AuthenticationVerifies your login is valid
✅
ConfigurationChecks settings.json for errors
✅
PermissionsDetects unreachable permission rules
✅
UpdatesChecks if a newer version is available
/config — Configuration
Try This
> /config
Opens the interactive settings UI. Key things you can configure:
🎨
ThemeLight or dark mode
📝
Output StyleExplanatory, Learning, or Custom
🔔
NotificationsEnable desktop notifications
🔒
Permission ModeHow Claude asks for approval
/permissions — Tool Access Control
Try This
> /permissions
Manage what Claude can do without asking. Supports wildcard syntax:
// Allow patterns
Bash(npm run *) // Any npm script
Bash(git *) // All git commands
Edit(src/**) // Edit any file in src/// Deny patterns
Bash(rm -rf *) // Block destructive commands
Read(.env) // Block reading secrets
/sandbox — Sandboxing
Try This
> /sandbox
What It Does
Enables file and network isolation for bash commands. Safer, with fewer permission prompts.
Commands Cheat Sheet
Session
/clear — Fresh start
/compact — Free context
/resume — Continue session
/rewind — Undo changes
Model & Mode
/model — Switch models
/fast — Toggle speed
/plan — Plan mode
/config — Settings
Project
/init — Create CLAUDE.md
/memory — Edit memory
/permissions — Tool access
/sandbox — Sandboxing
Info & Debug
/context — Context usage
/cost — Token spending
/doctor — Health check
/help — All commands
The Commit Workflow
Ask Claude to Commit
> Commit these changes with a descriptive message
Claude will:
1️⃣
Run git status & diffReviews all staged and unstaged changes
2️⃣
Draft a commit messageFocuses on "why" not "what", following your repo's style
3️⃣
Stage and commitAdds specific files (not git add -A) and creates the commit
The PR Workflow
Ask Claude to Create a PR
> Create a pull request for these changes
Claude will:
1️⃣
Review all commits on the branchAnalyzes the full diff from base branch
2️⃣
Write PR title & descriptionSummary, test plan, and changes overview
3️⃣
Push and create PR via gh CLIUses GitHub CLI to create the pull request
