Claude Code best practices: a checklist for CLAUDE.md, hooks, subagents and permissions

Claude Code gets better when you stop adding to it and start sorting. Most setups I see have one long CLAUDE.md doing the job of a hook, a skill, a permission rule and a README. The fix is a placement rule: guidance goes in CLAUDE.md, must-happen actions go in hooks, on-demand procedures go in skills, noisy research goes to subagents, and safety limits go in permission rules.

This is a checklist version of that rule, checked on 2026-10-23 against Anthropic's own pages (best practices, memory, permissions, hooks guide and worktrees). Claude Code changes quickly, so if a key below errors on your version, check the linked page first.

Already read our explainers? This post is the short, opinionated pass. For the longer versions see the skills vs hooks vs subagents decision guide, the hooks guide and how to write a CLAUDE.md.

The one constraint behind every tip

Anthropic's best-practices page opens with the constraint that explains the rest: the context window fills fast, and performance degrades as it fills. Every file Claude reads and every command output sits in that window. So the checklist below is mostly about keeping the window clean and giving Claude a way to check itself.

What belongs in CLAUDE.md, and what doesn't

CLAUDE.md is read at the start of every conversation. That makes it expensive real estate. The best-practices page gives an include/exclude table; here is my compressed version of it.

Include:

• Commands Claude can't guess (pnpm test:unit -- --run, the one lint script that matters)
• Code style rules that differ from defaults
• Test instructions and the preferred runner
• Branch naming and PR conventions
• Project-specific architecture decisions and environment quirks
• Gotchas that aren't obvious from reading the code

Exclude:

• Anything Claude can work out by reading the code
• Standard language conventions
• Long API documentation (link to it)
• Anything that changes weekly
• File-by-file tours of the repo
• Self-evident rules like "write clean code"

The docs also give a test worth stealing: for each line, ask whether removing it would cause Claude to make mistakes. If not, cut it. And the memory page says to target under 200 lines per file.

A CLAUDE.md that follows this, with commands I invented for an imaginary Node project (unrun, adapt to yours):

# Commands
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Typecheck: `pnpm tsc --noEmit` (run after every batch of edits)
- Lint and fix: `pnpm lint --fix`

# Conventions
- API handlers live in `src/api/`; never import from `src/ui/` there
- Money is integer paise. Never use floats for amounts.

# Workflow
- Branch names: `feat/<slug>`, `fix/<slug>`
- IMPORTANT: run the single relevant test file before reporting done
- When compacting, always preserve the list of modified files and the test commands

Two details from the docs are in there on purpose. Emphasis like "IMPORTANT" works only if you use it on a line or two; emphasize ten and none stand out. And the compaction instruction comes straight from the best-practices page as a way to make sure critical context survives summarization.

Run /init to generate a starter file, then prune it. If you keep rules for one part of the repo, use .claude/rules/ files with paths: frontmatter so they load only when Claude touches matching files. If your team also uses other agents, the memory page says Claude Code (v2.1.277 or later, per the docs) reads an AGENTS.md when there is no CLAUDE.md, or you can import it; our AGENTS.md vs CLAUDE.md comparison covers the tradeoffs.

Hooks, skills, subagents, slash commands: which one?

My placement table. Docs support for each row is linked above; the "my rule" column is opinion.

The best-practices page shows a fix-issue skill with disable-model-invocation: true and says to use that flag for workflows with side effects you want to trigger manually. Its example subagent lives at .claude/agents/security-reviewer.md with name, description, tools and model frontmatter. Custom commands and skills overlap now, which our explainer covers, so I don't create .claude/commands/ files in new projects.

One more judgement call: subagents are for isolation, not savings. Each one makes its own requests. Use one when exploration would flood your context, and see the subagents practical guide for patterns.

Hooks that earn their place

The hooks guide says hooks are deterministic: certain actions always happen rather than relying on the model to choose to run them. Two to start with.

A formatter after every edit. This is the docs' own example, adapted into .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

A guard that blocks destructive Bash commands. The hook reads JSON on stdin, where tool_input.command holds the shell command, and exit code 2 blocks the call with stderr fed back to Claude. I wrote this script and ran it on 2026-10-23 against four sample inputs:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -Eq 'rm -rf|git push (-f|--force)'; then
  echo "Blocked: destructive command. Ask the user first." >&2
  exit 2
fi

exit 0

Real output from piping fake hook JSON through it (this tested the script, not a live Claude Code session):

command: npm test -> exit 0
command: rm -rf build/ -> exit 2
command: git push --force origin main -> exit 2
command: git push origin feature -> exit 0

Register it under PreToolUse with "matcher": "Bash". Two traps from the docs: exit 0 from a PreToolUse hook does not approve the call, it just continues into the normal permission flow, and a grep like mine is easy to evade (/bin/rm -rf, a script that calls rm). Treat it as a seatbelt, not a wall. The docs say the same about permission rules, covered next.

The third hook worth having is a Stop hook that runs your tests and blocks the turn from ending until they pass; the best-practices page lists it as the deterministic version of "verify your work". Check the hooks reference for the Stop input and its cap on consecutive blocks before you build it.

Permission settings that don't punish you

Two facts shape everything. First, rules are evaluated deny, then ask, then allow, and the first match wins. Specificity doesn't matter, so an allow can't carve an exception out of a deny. Second, the docs warn that Bash patterns constraining arguments are fragile.

A starting settings.json using only keys and syntax shown on the permissions page:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

Notes that save debugging time:

• Bash(ls *) matches ls -la but not lsof; the space before the trailing * matters.
• A rule like Bash(safe-cmd *) won't approve safe-cmd && other-cmd; Claude Code splits on &&, ||, ;, | and newlines and matches each part.
• Path rules use Read(...) and Edit(...). A Write(...) path rule is accepted but never matched, per the docs.
• A .claudeignore file has no effect; use Read deny rules.
• Choosing "Yes, and don't ask again" in a worktree session saves the rule to the main checkout's .claude/settings.local.json.

For lower friction without giving up control, the docs point to /permissions for allowlists and /sandbox for OS-level isolation of shell commands. If you run in a mode that skips checks, do it inside a container or VM; our coding agent sandbox post covers that setup.

Plan first, but only when the diff is bigger than a sentence

The docs' rule: planning helps when you're unsure of the approach, the change touches several files, or you don't know the code. If you could describe the diff in one sentence, skip the plan. Start plan mode with Shift+Tab until the status bar shows plan mode, or launch with claude --permission-mode plan. Press Ctrl+G to edit the plan in your editor before Claude proceeds.

A prompt shape from the docs that works well: name the area, ask what files change, ask for a plan. Then review the plan like a pull request. For multi-step refactors, see our plan mode workflow.

Give Claude a check it can run

This is the item with the biggest payoff. Anthropic's page says Claude stops when the work looks done, and without a check it can run, "looks done" is the only signal. A check can be a test suite, a build exit code, a linter, a script that diffs against a fixture, or a screenshot.

Prompt pattern, adapted from the docs' before/after table (untested template):

Write a function validateEmail. Cases: user@example.com is true,
"invalid" is false, user@.com is false. Run the tests after
implementing and show me the output. Fix the root cause if they fail,
do not weaken the tests.

Escalation ladder from the same page: ask in the prompt, set a /goal condition for a session, add a Stop hook as a hard gate, or have a reviewer subagent try to refute the result. A practitioner summary on InfoQ (dated 2026-01-10, reporting tips attributed to Claude Code's creator Boris Cherny) puts the feedback loop first among his tips and mentions plan mode, a team CLAUDE.md kept in git, and avoiding --dangerously-skip-permissions. Secondhand, but it matches the official docs.

Context hygiene habits

From the docs, in the order I use them:

1. /clear between unrelated tasks.
2. After two failed corrections on the same issue, /clear and write a better first prompt.
3. Send investigation to a subagent: "use subagents to investigate how token refresh works".
4. /compact Focus on the API changes when you want control over what survives.
5. Esc Esc or /rewind to roll back, but remember checkpoints don't track changes made through Bash. Git is still your safety net.
6. /btw for side questions that shouldn't enter history.

The review checklist

Paste this into your team wiki. Each line is a yes/no.

• CLAUDE.md is under 200 lines and every line passes the "would removal cause a mistake" test
• Repeated rules were promoted to hooks, not bolded
• Side-effect workflows are skills with disable-model-invocation: true
• .env and secrets have Read deny rules
• git push is denied or asked, not allowed
• Every task prompt names a check Claude can run
• Plans are reviewed before edits on multi-file changes
• A fresh-context reviewer sees the diff before merge

Running it without a US card

If you're in India and want to try this setup without an international card, one option is an API gateway billed in rupees. AICredits lists a minimum top-up of Rs 50 on its homepage (its own steps say Rs 100 or more, so check at checkout), UPI payment, and per its community docs an Anthropic-style base URL of https://api.aicredits.in (no /v1) plus an OpenAI-style one at https://api.aicredits.in/v1. Our Claude Code India setup guide walks through it, but its summary and body disagree on whether the base URL carries /v1, so copy the value from AICredits' own docs, not from either of us. Its docs list no Claude Code guide, so test with a one-line request first. Alternatives that aren't affiliates: Anthropic's own plans and API, or the cloud routes Anthropic documents such as Amazon Bedrock and Google Cloud.

Disclosure: the AICredits link below is an affiliate link. I may earn a commission if you sign up, at no cost to you. AICredits

What I could not verify

I did not run these settings in a live Claude Code session, only the hook script against sample JSON. I did not verify the ask array key by name on the permissions page (the evaluation order mentions ask rules). Version-specific behavior, like AGENTS.md reading, is quoted from the docs as of 2026-10-23.