Part 3: CLAUDE.md, Skills and Hooks — encoding your judgment

By the time engineers reach this part of the series, they have run a few sessions in VS Code (Part 2) and noticed something: good results require good context. The session where you explained the project's conventions produced better output than the session where you just described the task.

That observation is the foundation of this guide. Context should not live in your head, re-explained every session. It belongs in configuration files that Claude reads automatically.

CLAUDE.md: the session instruction file

Place a file named CLAUDE.md in your repository root and Claude reads it at the start of every session in that repo. No special commands required — it is automatically loaded.

CLAUDE.md is instruction, not documentation. The distinction matters: documentation explains what exists; instruction tells an agent what to do, what to avoid, and what matters in this specific codebase.

What belongs in CLAUDE.md: - Testing conventions and which test runner to use - Code style rules that differ from language defaults - Directories to never touch without explicit instruction - How to handle migrations, secrets, and environment variables - Architectural decisions that are already made and should not be re-litigated

What does not belong: - General explanations of how the project works (Claude can read the code) - Instructions that apply globally to all Claude sessions (those go in ~/.claude/settings.json) - Documentation for human readers (keep that in README.md)

A CLAUDE.md does not have to be long. The most effective ones are one to two pages of specific, actionable rules. Start with the three or four rules whose violation would cause the most damage and expand from there.

Without CLAUDE.md, every session starts from zero. With it, the agent inherits the team's accumulated judgment from the moment the first prompt is sent.

Nesting CLAUDE.md files

You can place CLAUDE.md files in subdirectories. Claude loads the relevant ones based on which files it is working with — a CLAUDE.md in src/backend/ applies when Claude reads backend files, in addition to the root-level file. This is useful for monorepos or projects with distinct frontend and backend conventions.

Skills: process codified as executable instruction

Skills are markdown files that expand into structured prompts when invoked with a /command. They encode repeatable process — what to do, in what order, with what standards — so that process is consistent across sessions and across engineers.

A team-defined /review skill might specify: check security implications, verify test coverage, validate error handling, flag any deviation from the project's established patterns. Every review invocation follows that sequence, not the sequence Claude improvises based on the prompt.

The same pattern appears in Anthropic's Code Review feature, where a REVIEW.md file defines what the review agents look for in each PR. REVIEW.md is a skill, deployed at scale.

Where to define Skills: - User scope (~/.claude/): available in all your projects - Project scope (.claude/ in repo root): shared with all collaborators via version control - Local scope: only for you in this repo

Defining a project-scoped skill means every engineer who works in that repository can invoke the same /review, /deploy, or /debug workflow. Process knowledge is no longer tribal; it is executable.

Hooks: policy enforcement at the tool boundary

Hooks are shell commands that fire at specific moments in the Claude Code lifecycle. They run before or after tool calls — file reads, file writes, bash executions, session start and end.

This is the mechanism for hard constraints that should not depend on prompt discipline. Examples:

• A pre-write hook that rejects any write outside specified directories
• A post-bash hook that logs all executed commands to an audit trail
• A pre-commit hook that runs the linter before Claude can make a commit
• A session-start hook that validates the environment before any work begins

Hooks are defined in ~/.claude/settings.json (user scope) or in .claude/settings.json in the repository (project scope). Project-scoped hooks apply to all engineers working in that repo.

The key property of hooks: they enforce policy at the system level, not the prompt level. No individual can accidentally bypass a hook by writing a different prompt. The constraint is structural.

Configuration hierarchy

Claude Code has a layered configuration system. From broadest to narrowest:

1. ~/.claude/settings.json — global settings, apply to all sessions for this user
2. .claude/settings.json (repo root) — project settings, shared via version control
3. .claude/settings.local.json — local overrides, not committed to git

Project-scoped configuration (settings.json in the repo) is the most valuable layer for teams. It ensures everyone working in the repo has the same Skills available, the same Hooks enforced, and the same baseline behavior — regardless of individual user settings.

The practical starting point

For a first CLAUDE.md, focus on three questions:

1. What would cause the most damage if Claude got it wrong in this repo?
2. Which conventions does Claude consistently miss without being told?
3. What project-specific context cannot be inferred from the code?

Answers to those three questions give you a first draft. Maintain it the same way you maintain a README: update it when the project changes, add rules when you catch Claude making the same mistake twice.

The time investment is small. The leverage is significant: a well-maintained CLAUDE.md scales across every engineer on the team and every session in that repo, compounding over time.

---

Previous: Part 2 — Getting started in VS Code Next: Part 4 — Subagents, MCP and team scale

Sources: How Claude Code works · Features overview