Claude Code,
the way it works.

Claude Code works best when you set it up in three layers:

# If you find yourself correcting the same thing twice, that’s a missing rule, not a missing reminder.

Three files live in ~/.claude/ and apply to every project.

A · ~/.claude/CLAUDE.md, your defaults

One markdown file telling the model how you want it to behave everywhere:

• Response style. “Keep answers short. No long preambles. Show the diff, not a recap.”
• Stack defaults. “Backend NestJS, frontend Next.js, mobile Kotlin. Use repository pattern, DTOs, DI.”
• Code style. “No comments unless explaining a non obvious why. Custom error classes, not generic Error.”
• Git safety. “Never run git commit / push / merge / rebase on the main tree unless I say go.”
• Before claiming done. “Run tests, lint, types. All green.”

# Response style
- Keep answers under 8 lines unless I ask for more.
- After a tool call, one line saying what changed. No recap.
- No tables or headers for simple yes/no answers.

# Git
- Suggest git write commands, don't run them, unless I say go.
- Worktrees are always allowed.

# Done means done
Before saying a task is done:
1. Run the test suite. All green.
2. Run the linter. Zero warnings.
3. Run the type checker. Zero errors.

B · ~/.claude/settings.json, runtime config

Allowlist common commands so you stop clicking “allow”.

{
  "permissions": {
    "allow": [
      "Bash(bun run:*)",
      "Bash(bun test:*)",
      "Bash(npx tsc:*)",
      "Bash(chmod:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/block-dangerous-git.sh"
      }]
    }]
  }
}

C · The one global hook worth it

A tiny bash script that blocks dangerous git commands before they run. Save as ~/.claude/hooks/block-dangerous-git.sh, then chmod +x:

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

patterns=(
  'git reset --hard'
  'git clean -f'
  'git branch -D'
  'git checkout \.'
  'git restore \.'
  'push --force'
  'push -f'
  'push --no-verify'
)

for p in "${patterns[@]}"; do
  if [[ "$cmd" =~ $p ]]; then
    echo "Blocked: $p. Run it yourself if you really mean it." >&2
    exit 2
  fi
done
exit 0

Two minutes to set up. Catches mistakes you’d wish you hadn’t made.

Every non-trivial repo gets a CLAUDE.md at the root.

What goes in it

1. One line: what this repo is.
2. Stack: versions, runtimes.
3. How to run it: install, dev, test, build, deploy.
4. Architecture: the main folders and what lives in each.
5. Rules: the things that should never happen.
6. Done checklist: the exact commands to run before claiming done.

# Acme Dashboard

Internal admin dashboard for Acme. Next.js 14, PostgreSQL, Prisma.

## Run
- bun install
- bun dev          (local at :3000)
- bun test         (vitest)
- bun run build

## Layout
- app/             Next.js routes
- lib/db/          Prisma client, queries
- lib/api/         REST handlers
- components/      Reusable UI

## Rules
- Never query the DB from app/ directly. Go through lib/db/.
- All API responses use { success, data, error }.
- No CSS-in-JS. Use Tailwind.

## Done means done
1. bun test       all pass
2. bun lint       zero warnings
3. bunx tsc       zero errors
4. Manually open the page you changed and click through it.

You don’t need 800 lines. You need the rules a new teammate would ask about on day one.

Optional but nice: .claude/settings.json per project

Same pattern as global, scoped to this project.

{
  "permissions": {
    "allow": [
      "Bash(bun run:*)",
      "Bash(bun test:*)",
      "Bash(docker compose:*)",
      "Bash(prisma:*)"
    ]
  }
}

For anything bigger than a one-liner, use this rhythm. Feels slow the first time. Saves hours after that.

You:    Let's add invoice PDF export. Brainstorm first.

Claude: A few questions. Server side render or client?
        Header / footer template fixed or per tenant?
        Async (queue + email) or sync (download)?

You:    Server side, fixed template, sync download.

You:    Plan it.

Claude: [returns 6 step plan, files to touch, libraries to add]

You:    Looks good, execute.

Claude: [works through steps, marks each done]

You:    Verify.

Claude: bun test  -> 47 pass
        bun lint  -> 0 warnings
        bunx tsc  -> 0 errors
        Manually tested /invoices/123/pdf. Renders.

Install once, use everywhere. Skip the rest, they cost context tokens.

Install with /plugin install <name>.

Same task, different specificity. The second one saves you a round trip.

fix the bug in users

In app/users/page.tsx, the list shows duplicate rows when
filtering by status. Investigate why, write a failing test
that reproduces it, then fix it. Don't touch unrelated code.

add invoices

Add an invoices module. Brainstorm with me first, then plan,
then execute. Follow the rules in CLAUDE.md (response shape,
db access through lib/db only).

make this faster

The /dashboard page takes 4s to first paint. Profile it
(use chrome-devtools), find the top 3 culprits, propose fixes.
Don't implement until I pick which to do.

Things that aren’t obvious until someone tells you.

Audit my ~/.claude/CLAUDE.md and ~/.claude/settings.json.
Tell me what's missing, what's weak, what I should add.
Then propose the fixes as diffs.

This session is getting long. I want to add feature X next.
Should we continue here or start a new session?
If new, dump the context I need to bring over.

Before I act on this plan, run /grill-me on it.
What's wrong with it? What did I miss?
Don't agree with me, find the holes.

Session 1: "Give me a prompt to start a new feature
            that does X, Y, Z."
           -> Claude writes the prompt.

Session 2: Paste the prompt fresh.
           -> Claude executes the task.

Session 1: "Here's what session 2 produced: <paste>.
            Validate it. Does it match what you asked for?"

Explain how Claude Code hooks work. Then write me a
PreToolUse hook that blocks any Bash command containing
`rm -rf` or `DROP TABLE`. Put it in ~/.claude/hooks/.

fix the bug in the dashboard

fix the bug in app/dashboard/page.tsx, the useEffect
on line 58 fires twice on mount

Show me the diff of what you changed before moving on.
I want to see the actual edit, not a summary.

How confident are you in this fix, low / medium / high?
What could still break? What did you not check?

Before fixing this bug, write a failing test that reproduces
it. Run it, confirm it fails. Then write the fix and confirm
it passes.

If you’re starting from zero, this is the entire setup.

1. [01]Create ~/.claude/CLAUDE.md with response style, stack defaults, git rule, done checklist.
2. [02]Create ~/.claude/settings.json with the permission allowlist and git safety hook.
3. [03]Create ~/.claude/hooks/block-dangerous-git.sh, paste the snippet, chmod +x.
4. [04]Install plugins: superpowers, context7, serena, code-review.
5. [05]In a real project, run /init and edit the generated CLAUDE.md down to essentials.
6. [06]Try the workflow on a real task: brainstorm, plan, execute, verify.

# An hour writing CLAUDE.md will save you a hundred prompts later.