Gate: Could another senior developer implement this from the architecture doc alone?
Define data models, API contracts, module boundaries. Architecture changes mid-build mean starting over.
You design, Claude validates. Use Claude to stress-test your design — edge cases, inconsistencies, missing pieces.
The document is the interface. Everything Claude generates in later phases is bounded by what you define here.
● Phase 3 of 5
Task Generation
Owner:ClaudeInput: your architecture · Deliverable: Task list with acceptance criteria
Gate: Does every task have clear acceptance criteria that can be verified by a test?
Feed your architecture doc to Claude. The more precise your architecture, the more precise the task list.
Each task has a clear done signal. Acceptance criteria that can become a failing test before any code is written.
Tasks are the contract for Phase 4. Claude Code implements against these — vague tasks produce vague PRs.
● Phase 4 of 5
TDD Implementation
Owner:ClaudeInput: your tasks · Deliverable: Working code with tests
Gate: Do all tests pass and does the code match the architecture decisions from Phase 2?
Tests first, then code. Claude writes a failing test, then makes it pass. No test means no done.
Your tasks are the guardrails. Claude operates within the scope you defined — one task at a time.
You are the reviewer at every gate. Confirm each passing test before Claude moves to the next task.
● Phase 5 of 5
Review & Merge
Owner:You + ClaudeDeliverable: Approved PR
Gate: Would I mass-merge this without reading it? If yes, I haven't reviewed properly.
Read every diff. Never merge what you haven't understood. The PR is a record of everything the code does.
Claude surfaces issues, you decide. Use Claude to check for edge cases, security gaps, test coverage — but the approve is yours.
The gate question is the discipline. If you'd merge without reading, the framework has broken down.
● Framework
Three Scenarios, One Framework
The entry point changes. The discipline doesn't.
Greenfield
Enter at Phase 1. You have a blank slate. Start with requirements — define the problem before the solution.
Phase 1 → 2 → 3 → 4 → 5
New Feature
Enter at Phase 2. The system exists. Understand the current architecture first, then design how your feature fits.
Phase 2 → 3 → 4 → 5
Bugfix
Phase 1 becomes root cause analysis. Before writing any fix, understand why the bug exists and what would prove it's fixed.
Phase 1 (RCA) → 3 → 4 → 5
● Claude Code
Claude Code is not a chatbot
The framework tells you how to build. Claude Code is the tool that executes it — a terminal-native agent that reads your entire codebase, takes real actions, and works within the boundaries you set.
What it actually does
Reads your codebase. Not just one file — the full project context, architecture, and conventions.
Takes real actions. Edits files, runs tests, executes shell commands, commits to git — autonomously.
Reasons across phases. It can spec, plan, implement, test, and review — if you direct it correctly.
Works with your tools. Terminal, VS Code, JetBrains, CI/CD — meets you where you already work.
What it needs from you
Clear requirements. Claude Code can't guess business context. Your spec is its starting point — vague in, broken out.
Architectural decisions upfront. Claude generates code within the architecture you define. Changing structure mid-build means starting over.
Well-scoped tasks. Small, precise tasks with clear acceptance criteria produce mergeable PRs. Large vague tasks produce large vague code.
Your review at every gate. Claude flags issues — you decide. Never merge what you haven't read.
Claude Code is capable of building almost anything. The constraint is never the tool — it's the clarity of your direction.
● Anatomy
Where does Claude Code live?
Claude Code runs everywhere. Understanding the surfaces helps you pick the right tool for the moment.
💻
Terminal (Primary)
The original and most powerful surface. Full CLI flags, headless mode, worktrees, all features available. This is where we'll work tonight.
📝
IDE Extensions
VS Code extension, JetBrains plugin. Integrated into your editor workflow. Same engine, different interface.
🌐
Desktop, Web, Mobile
Desktop app, claude.ai/code (web), iOS. For quick interactions when you're not in a full dev session.
# Install (native, auto-updates)
curl -fsSL https://claude.ai/install.sh | bash
# Verify everything works
claude doctor
# Check your version
claude --version
● Setup
Before your first prompt: the setup sequence
Claude Code reads its instructions from several layers. Getting this right once means every session starts with Claude already knowing your project, your standards, and your workflows.
Install claude doctor
→
Settings ~/.claude/settings.json
→
CLAUDE.md project instructions
→
Skills on-demand workflows
→
Start coding
Configuration — once per project
Settings and CLAUDE.md are set up once and persist across all sessions. Get them right and you stop fighting the tool at the start of every session.
Skills — once per workflow type
Skills are written once and used indefinitely. They encode your team's repeatable workflows — review checklists, test patterns, deployment steps.
The next two slides cover Settings and CLAUDE.md. Skills come after the break — they're a different kind of layer.
● Settings
The 5-Level Settings Hierarchy
Claude Code loads settings from five levels. Higher levels override lower ones — and all five load on every startup.
5
Managed
Enterprise/OS-level. Cannot be overridden by users.
Per-project, gitignored. Your personal overrides for this project.
2
Project — .claude/settings.json
Committed to git. Shared with your team.
1
User — ~/.claude/settings.json
Your global defaults across all projects.
Claude Code loads all five levels on every startup and merges the values together. Higher levels win — a CLI flag overrides a project setting, which overrides a user default. Understanding this prevents "why isn't my config working?" moments.
● Settings
Quick Check: Which value wins?
The same setting is defined at three levels. Which model does Claude Code actually use when you launch it?
Level 1 · User
~/.claude/settings.json
{ "model": "claude-sonnet-4-6" }
Level 2 · Project
.claude/settings.json
{ "model": "claude-opus-4-7" }
Level 3 · Local
.claude/settings.local.json
{ "model": "claude-haiku-4-5" }
Which model does Claude Code use?
claude-haiku-4-5 — from .claude/settings.local.json (Level 3)
Level 3 (Local) overrides Level 2 (Project), which overrides Level 1 (User). The highest applicable level wins — no merging, just a clean override down the chain.
● CLAUDE.md
CLAUDE.md — Your most powerful lever
A well-configured Sonnet outperforms a poorly configured Opus. This file is where the leverage lives.
Over 200 = reduced adherence. Anthropic's own teams target 60.
Be specific, not vague. "Use 2-space indent in TypeScript" beats "format code nicely."
Use @path imports. Reference additional files without bloating the root file.
Use paths: frontmatter in .claude/rules/ — rules load only when Claude works in matching directories.
Critical instructions at the top. Models over-attend to beginning and end of context (lost-in-the-middle effect).
Unlike settings (which override), CLAUDE.md files concatenate — all applicable ones load and stack into context together. User-level and project root load every session. Rules files load only when paths match. Subdirectory files load lazily. This is why the 80-line limit matters: the total across all loaded files is what Claude sees.
● CLAUDE.md — Rules
Rules — conditional instructions for specific directories
Rules are CLAUDE.md extensions that load automatically only when Claude works in a matching directory. The middle ground between always-loaded and on-demand.
How rules work
# .claude/rules/api.md---description:API development rulespaths: - "src/api/**" - "src/routes/**"---# These rules only load when Claude# is editing files in src/api/ or# src/routes/ — not for frontend work
Always validate request bodies with zod.
Return 400 for validation errors, never 500.
Never expose internal error messages.
Two ways to use rules
With paths: — loads only when Claude edits matching files. Path-conditional. Use for domain-specific conventions (API, frontend, tests).
Without paths: — loads every session, unconditionally. Use for project-wide topics you want to keep as separate, named files rather than one big CLAUDE.md.
# Matteo Collina's typescript.md --- name:typescript description:TypeScript config and type stripping metadata: tags: typescript, ts-node ← his own notes, ignored by Claude --- no paths: → loads every session
Practical examples
src/api/** → REST conventions, auth rules src/components/** → React patterns, styling rules tests/** → Test structure, mock conventions migrations/** → DB safety rules, no destructive ops
Rules solve two problems: conditional loading (path-scoped) and organisational modularity (no paths, always loads). Either way, they keep your root CLAUDE.md lean and focused.
● CLAUDE.md vs Rules
CLAUDE.md or a Rule — how to decide
One question determines it: does this instruction need to be true everywhere, or only in certain parts of the codebase?
Put it in CLAUDE.md when…
It applies to every file in the project — tech stack, language version, package manager.
It's a team-wide standard — commit message format, PR checklist, branch naming.
Claude must know it before touching anything — architecture decisions, off-limits files, deployment constraints.
It would be dangerous to forget — "never delete the users table", "always use the internal logger".
Examples:
We use Node.js 22 + TypeScript 5.8
All PRs need a test for every new path
Never commit .env files
Put it in a Rule when…
It only matters in specific directories — API conventions, frontend patterns, DB migration rules.
Loading it for unrelated tasks wastes context — React component rules don't help when editing a migration.
You want to organise CLAUDE.md by topic — break one big file into named, focused rule files (even without paths:).
The instruction is too long to fit in CLAUDE.md without pushing it over 80 lines.
Examples:
src/api/** → validate with Zod, return {data} | {error}
tests/** → one assertion per test, no mocks on DB
typescript.md → TS config rules (no paths, always loads)
If you're unsure — start in CLAUDE.md. When it goes over 60 lines, look at what you can extract into a rule. That's the refactoring signal.
● The Siblings
What about the other AI coding tools?
Every serious AI coding tool needs the same thing: a place for persistent project instructions. Claude Code's system is the most sophisticated — but the mental model transfers everywhere.
Instructions file
Conditional rules
On-demand skills
Claude Code
CLAUDE.md
.claude/rules/*.md
.claude/skills/*/SKILL.md
Opencode
AGENTS.md
—
—
Codex (OpenAI)
AGENTS.md
—
—
Gemini CLI
GEMINI.md
—
—
GitHub Copilot
.github/copilot-instructions.md
—
—
Cursor
.cursorrules
.cursor/rules/*.mdc
—
Windsurf
.windsurfrules
—
—
The skill transfers. Whatever tool your team uses, the question is the same: where does this tool read its project instructions, and am I giving it good ones? Claude Code is just the one that took the architecture furthest — settings, rules, skills, hooks, worktrees. Others will catch up.
● Part 2
Configuration done. Now: how you work.
Settings and CLAUDE.md are one-time setup. What follows are the daily habits that determine whether every session is productive or chaotic.
Session Hygiene
Skills & Context
● Session Hygiene
Work clean, think clearly
Session hygiene matters more than prompting technique. These habits prevent long sessions from feeling "stupid."
🧹
One Session, One Task
Start /clear between unrelated tasks. One session per PR. Context compounding means costs grow faster than expected.
📊
Know Your Context
/context — where are your tokens going? /cost — how much are you spending? /compact — manually compress at natural checkpoints.
Use ultrathink for architecture. Think for routine tasks.
⚡
Effort Levels
/effort low — quick answers, less thinking /effort medium — balanced (default) /effort high — thorough, careful work /fast — shortcut for low effort
📋
Plan Mode
Shift+Tab to cycle permission modes. Use Plan mode for read-only exploration before you start coding. Think first, code second — even inside Claude Code.
● Skills — Why
The context problem — and how skills solve it
Context is your scarcest resource. Every token spent on instructions Claude doesn't need right now is a token that can't hold your codebase, your history, or your task.
The problem: CLAUDE.md bloat
CLAUDE.md loads every session. Review checklists, test templates, deployment steps — all 200 lines load even for a 2-line bugfix.
Adherence drops past 80 lines. Claude's attention isn't uniform. Long files mean later instructions get quietly ignored.
Context fills fast. Large codebase + bloated CLAUDE.md + conversation history = hitting the limit mid-task.
The solution: load only what you need
Skills load on demand. A /review skill only loads when you run /review. Every other session, those tokens are free.
~15,000 tokens recovered per session. Moving heavy workflows from CLAUDE.md into skills pays off immediately.
Better adherence. A focused 50-line skill at the right moment outperforms a 200-line CLAUDE.md that's always present but rarely attended to.
CLAUDE.md for what Claude always needs to know. Skills for what Claude needs to know sometimes.
● Skills
Skills — extend Claude without wasting context
Now that you understand the problem, let's understand the solution — what a skill actually is, where it lives, and how you write one.
What is a Skill?
On-demand instructions. Unlike CLAUDE.md (always loaded), skills load only when triggered — by slash command or auto-discovery.
Location:.claude/skills/<name>/SKILL.md (project), ~/.claude/skills/<name>/SKILL.md (user-global), or inside a marketplace plugin (installable via /plugin install).
Auto-discovery: Claude reads the description field and decides when to activate — LLM reasoning, not keyword matching.
Supporting files: Templates, examples, scripts can live alongside SKILL.md.
SKILL.md Anatomy
# .claude/skills/review/SKILL.md---name:reviewdescription:Run code review checklist
on changed filesallowed-tools:Read, Grep, Glob---
Review code changes against our
team's quality checklist:
1. Error handling completeness
2. Test coverage for new paths
3. Breaking API changes
4. Security implications
🎬 Think Matrix. Neo sits in the chair, Morpheus says "I need to show you something" — and in 20 seconds Neo opens his eyes: "I know kung fu." He didn't know it before. He doesn't carry it around after. It loaded exactly when needed, he fought Morpheus, and it was gone. That's a skill. You type /review — Claude loads the review instructions, runs the checklist, done. Next session: zero overhead.
● Skills — Mechanics
How skills actually work
Skills are to CLAUDE.md what functions are to global variables — scoped, purposeful, loaded only when called. Understanding the mechanics makes you a better skill author.
The lifecycle
1
TriggerUser types /review or Claude decides based on context
2
LoadSKILL.md injected into context — only now, only this skill
3
ExecuteClaude follows the skill's instructions using only its allowed tools
/review loads the review skill immediately. Arguments pass through: /review src/auth → $ARGUMENTS becomes "src/auth" inside the skill.
Implicit — auto-discovery
Claude reads every skill's description field at session start and activates skills when context matches. Write descriptions as "Use when..." — trigger conditions, not feature lists.
Skills are functions. CLAUDE.md is a global. Globals run everywhere — functions run when called. Put your workflows in functions.
● Skills — Config
SKILL.md frontmatter options
The frontmatter controls when and how a skill runs. These options let you fine-tune behavior.
name + description
Name becomes the slash command: /review. Description is what Claude reads to decide auto-activation. Write it as "Use when..." — trigger conditions, not a feature list.
allowed-tools
Restrict which tools the skill can use. Read, Grep, Glob for read-only skills. Include Write, Edit, Bash for skills that modify code.
model + effort
Override the model or effort level per skill. Use model: haiku for cheap exploration skills, model: opus for critical decisions.
$ARGUMENTS — use this placeholder in your skill body. When a user types /review src/auth, the text "src/auth" replaces $ARGUMENTS in the skill instructions.
● Skills — Ecosystem
Install existing skills, don't start from scratch
The ecosystem already has production-grade skills. Install, learn from their structure, then write your own.
Start simple. One skill, one job. A /generate-tests skill that follows your project's test conventions.
Study existing skills. Read Addy's SKILL.md files — notice the "Common Rationalizations" and "Red Flags" sections that prevent Claude from cutting corners.
Include supporting files. Templates, checklists, examples alongside SKILL.md give Claude concrete patterns to follow.
More skills:github.com/ComposioHQ/awesome-claude-skills — curated community collection.
● Real World · Example 1
Matteo Collina's setup — Rules & Skills in practice
Matteo Collina (Node.js core, Fastify creator) uses Claude Code on production open-source work. His setup is a masterclass in scoping instructions correctly.
Files to open
CLAUDE.md — the root project instructions. Notice what he puts here vs what he delegates to rules.
.claude/rules/ — domain-specific rules per directory. See how rules keep the root file lean.
.claude/skills/ — the workflow skills he's written. Read the description fields carefully.
Pay attention to what is not in CLAUDE.md. The absence of certain things is deliberate — those are in rules or skills.
What to explain
The 80-line discipline. Show the actual line count. Discuss what he chose to keep vs delegate.
Rules by directory. Walk through each rule file and its paths: frontmatter — connect it to what you just taught.
Skill description fields. Read them aloud — show how precise "Use when..." descriptions enable auto-discovery.
The structure as a system. Nothing is accidental — every file is in the right layer for a reason.
● Real World · Example 2
Addy Osmani's setup — Skills & Plugins at scale
Addy Osmani (Google AI Engineering Director) published the agent-skills repo — 19 production-grade skills mapped to the full software lifecycle. This is the ecosystem in action.
Files to open
A SKILL.md file — open /spec or /plan. Read it top to bottom. Notice the "Common Rationalizations" and "Red Flags" sections.
The plugin manifest — shows how skills are packaged and distributed as a single installable unit.
Supporting files — templates and examples sitting alongside SKILL.md. These are what give Claude concrete patterns.
Install it live: /plugin marketplace add addyosmani/agent-skills
What to explain
"Common Rationalizations." This section explicitly prevents Claude from cutting corners. Discuss: without this, what would Claude do?
Skills as guardrails, not just prompts. Addy's skills don't just say what to do — they say what to refuse to do.
The plugin model. One install, 19 skills — show how distribution works. Your team can publish internal plugins.
Lifecycle coverage. Each skill maps to one phase — /spec, /plan, /build, /test, /review, /ship. The whole framework, encoded in skills.
● Full Stack
The complete picture
Every layer you've learned, assembled into one system.
The instruction stack
~/.claude/settings.json→ global defaults.claude/settings.json→ team shared configCLAUDE.md→ always-loaded knowledge.claude/rules/*.md→ conditional rules.claude/skills/*/SKILL.md→ on-demand instructionssession management/clear /compact /cost
One sentence per layer
Settings control what Claude is allowed to do.
CLAUDE.md controls what Claude always knows.
Rules narrow what Claude knows to specific directories.
Skills control what Claude does when triggered.
Session hygiene keeps it all sharp as context grows.
These layers don't compete — they compose. A well-designed stack means Claude arrives at every task already knowing who you are, what you're building, and how you want to work.
● Recap
What you now know
✓The 5-phase agentic framework
✓Claude Code — what it is, what it does
✓Settings hierarchy — 5 levels
✓CLAUDE.md mastery — hierarchy, rules, limits
✓Session hygiene — clear, compact, thinking modes
✓Skills — on-demand instructions, the ecosystem
A well-configured Sonnet outperforms a poorly configured Opus.
Continued in Session 2: MCP · Hooks · Agents · Worktrees