Skip to main content

Customize Claude Code for a Real Repo

Intermediate
What you'll learn
  • Turn a fresh checkout into a tuned Claude Code setup in about 20 minutes
  • Understand WHY each of the four customizations earns its place — CLAUDE.md, permissions, a hook, a command
  • Write permission rules that cut interruptions on safe actions and hard-stop the risky ones
  • Verify each piece actually works instead of assuming it did

Let's turn a fresh checkout into a Claude Code setup that knows your project and respects your rules — in about 20 minutes. We'll string together the core features with the rationale for each.

The end state​

Step 1 — Generate and trim CLAUDE.md​

Run /init to draft a CLAUDE.md, then edit it down to what's true: stack, how to run/test/lint, real conventions, and guardrails ("run tests before done", "don't touch /generated"). Why: it's the highest-leverage customization — Claude reads it every session.

Grab a starter from CLAUDE.md Templates.

Step 2 — Set permissions​

Add a .claude/settings.json (reference) that pre-allows safe, repetitive commands and denies the dangerous:

{
  "permissions": {
    "allow": ["Read", "Bash(npm run test:*)", "Bash(npm run lint)", "Bash(git diff:*)"],
    "ask": ["Write", "Bash(npm install:*)"],
    "deny": ["Read(./.env)", "Bash(git push --force:*)"]
  }
}

Why: fewer interruptions on safe actions, hard stops on risky ones. See Permissions.

Step 3 — Add a formatting hook​

Auto-format after every edit (hooks):

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write",
  "hooks": [ { "type": "command", "command": "f=$(jq -r '.tool_input.file_path'); npx prettier --write \"$f\" 2>/dev/null || true" } ] } ] } }

Why: consistent formatting, guaranteed — not "please remember."

Step 4 — Add a /commit command​

Drop the /commit recipe from the Slash Command Library into .claude/commands/. Why: one word for a repeatable workflow.

Step 5 — Use Plan Mode for the first real task​

Give a real goal in Plan Mode, review the plan, then let it execute. Why: build trust by separating thinking from doing.

Verify it worked​

Don't assume — check each piece independently. Each test isolates one customization, so a failure tells you exactly which file to fix.

Guided walkthrough1 of 4
  1. Start a NEW session and give a normal task. Claude should reference your conventions unprompted, without you pasting them.

Kick off the first real task in Plan Mode

Add pagination to the users list endpoint. Plan it first — I want to review before you touch anything.
Key takeaways
  • CLAUDE.md is the highest-leverage customization because Claude reads it every session — generate it with /init, then edit it down to what's actually true
  • Permissions are a two-sided tool: pre-allow safe repetitive commands to cut interruptions, and deny the dangerous ones to get hard stops
  • A hook makes formatting guaranteed rather than "please remember" — behavior enforced by the harness beats behavior requested in a prompt
  • A slash command turns a repeatable workflow into one word
  • Plan Mode separates thinking from doing, which is how you build trust before handing over more autonomy
  • Verify each customization with its own test so a failure points at one file

Check yourself

0/3
  1. Why is CLAUDE.md called the highest-leverage customization?
  2. You want auto-formatting to be guaranteed, not merely requested. What's the right mechanism?
  3. In the example settings.json, why are some commands in "allow" and others in "ask"?

Next​