Claude Code best practices
By Mari Luukkainen · 9 min read · Last updated
On this page
- 1. Commit before every task
- 2. Write the goal, the check and the limits
- 3. Explore, plan, code, commit
- 4. One task per session, one worktree per parallel task
- 5. Keep CLAUDE.md short and true
- 6. Approve commands you can read
- 7. Make the tool run its own checks, and add hooks
- 8. Read the diff, not the summary
- 9. Keep secrets out of the folder
- 10. Write down decisions once
- 11. Add a guardrail after every incident
- 12. Review as a separate pass, with a separate agent
- How I set up my own agents
- A one-page checklist
- What do you type when a session goes wrong?
- What does a well-run session look like?
- Frequently asked questions
The best practices for Claude Code are: commit before each task, write the goal with a check the tool can run, keep CLAUDE.md short, approve only commands you can read, review the diff, and start a fresh session for each task. Each one prevents a specific, common failure.
The twelve habits below each name the failure they prevent and the exact words to use. They apply to other terminal agents as well. New to the tool? Start with how to use Claude Code.
Ask AI about this pageChatGPTClaudePerplexityGoogle AI ModeGrok
1. Commit before every task
Failure prevented: a task goes wrong and you cannot tell which of forty changed files was good. Check that git status shows nothing before you write the task. To drop a failed task, git restore . resets tracked files but leaves any new files Claude created. Use git stash -u to set everything aside, including new files, and be careful with git clean, which deletes untracked files for good.
2. Write the goal, the check and the limits
Failure prevented: the tool guesses what done means. The structure I use: the outcome and who it is for, what done looks like in numbers, the reason, which decisions the model can make and which are mine (post). Add the command that proves it.
Goal: new users should see their first invoice within two clicks of signing in.
Done means: from /dashboard, one click on "Invoices" and one on "New invoice" opens the form; a test covers the path.
Why: support gets this question daily.
Decide yourself: layout and labels. Ask me before changing the database.
Check: npm test and npm run build must pass.3. Explore, plan, code, commit
Failure prevented: ten minutes of work in the wrong direction. Run the loop in order. Explore: ask it to read the relevant files and explain them, with no edits. Plan: "Before you edit anything, list the files you will change and why. Wait for my OK." Plan mode (Shift+Tab) does the same. Code: approve the plan, with changes in words. Commit: only after you read the diff.
4. One task per session, one worktree per parallel task
Failure prevented: drift. After many messages the tool carries old context and can contradict an early rule. Finish, commit, run /clear. To continue a half-done task tomorrow, ask for a summary of the state in a file such as NOTES.md and start the next session by reading it.
To run two tasks at once, give each its own Git worktree, a second checkout of the same repository in a separate folder (git worktree add ../app-feature-x feature-x). The sessions cannot overwrite each other's files. Remove the worktree after you merge (git worktree remove ../app-feature-x).
5. Keep CLAUDE.md short and true
Failure prevented: ignored instructions. A file of 400 lines is read, but its rules compete. Keep the commands, the folder map, and five to ten rules that came from real mistakes. Remove a line when it stops being true. If other tools work in the same repository, write AGENTS.md as the source and put the single line @AGENTS.md in CLAUDE.md.
- Do not edit existing tests to make them pass. Tell me if a test looks wrong.
- Do not add dependencies without asking.
- Only touch files needed for the task.
- After every task run npm test and npm run build and show me the output.6. Approve commands you can read
Failure prevented: a destructive command. Allow the repetitive safe ones (test, build, lint). Stop and read anything with rm, git reset, git push, sudo, curl, or a package install. If you do not understand a command, reply: "Explain that command and what could go wrong." Know what "Yes, don't ask again" does on a shell command: it saves a permanent rule in .claude/settings.local.json for that repository and command, so choose it only for commands you would approve every time.
Allow rules go in the settings file. Read-only commands such as git status and git diff already run without a prompt, so they do not need an entry:
{
"permissions": {
"allow": ["Bash(npm test)", "Bash(npm run build)"],
"deny": ["Read(./.env)", "Read(./.env.*)"]
}
}Keep git commit and anything that deletes or sends data out of the allow list. Review the list once a month.
7. Make the tool run its own checks, and add hooks
Failure prevented: "done" without proof. End every task with "run the tests and the build and show me the output". If there are no tests, ask for a failing test first.
A hook removes the need to ask. A hook is a command Claude Code runs automatically at a set point. A hook that runs the linter and the type check after every file edit means a type error shows up while the tool is still working on it (hooks docs).
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "npm run lint && npx tsc --noEmit" }]
}
]
}
}8. Read the diff, not the summary
Failure prevented: a confident summary that leaves things out. Run git diff --stat to see how many files changed, then git diff on the ones you care about. A one-line request that changed twelve files needs a second look.
9. Keep secrets out of the folder
Failure prevented: leaking a key into a prompt or a commit. Put keys in a .env file that is listed in .gitignore. A line in CLAUDE.md saying "never read .env" is guidance and blocks nothing, so add the deny rule shown in habit 6. Scan before every push with a secret scanner such as gitleaks, which checks the files and the Git history. If a key was committed, treat it as exposed and replace it, because removing the commit does not remove the key from the history other people may have copied.
10. Write down decisions once
Failure prevented: the same decision made differently each session. I keep one markdown file per topic in a private repository, and a new session reads the relevant one before it works (post). You can start with one file: DECISIONS.md with lines such as "Dates are stored in UTC" and "Forms validate on the server".
11. Add a guardrail after every incident
Failure prevented: the same outage twice. From my own setup: two builds ran on one 16 GB server at once, used all the memory and took down every app on it, so every build now takes a lock and runs one per box. A compose file I edited by hand was rewritten by a tool and lost a production database container's definition, so the file is validated before anything touches it. When something breaks in your project, add a rule or a check the same day.
12. Review as a separate pass, with a separate agent
Failure prevented: the tool defending its own work. Open a fresh session, or a subagent, and ask for a review with no edits. The reviewer is never the session that built the change. The security prompt in is vibe coding bad is a starting point, and the prompt library has more.
How I set up my own agents
This is the setup I run across my apps. One file, AGENTS.md, holds the rules for every tool I use, Claude Code and Cursor included. The CLAUDE.md in each project is one line, @AGENTS.md, so Claude Code reads the same rules.
I split the work into roles, and each role gets a named model. A fixer builds a scoped change from a spec and a file list, on Sonnet. A hunter does deep read-only reviews and bug hunts, on Opus. An evaluator judges a finished change before it is pushed and answers APPROVE or REJECT, also on Opus. The main session plans and decides what gets merged.
Three rules carry most of the weight. The reviewer is never the agent that built the change. Every change passes lint, typecheck and build before it is merged. A worktree is removed as soon as its work is pushed. Deploys happen by pushing to the main branch, and the server builds from there.
## Model routing
- Sub-agents and delegated build/fix work: Sonnet.
- Reviews (code review, bug hunt, check before merge): Opus.
- Main session: planning, coordination, merge decisions.
- Always name the model when starting a sub-agent.
- The reviewer must not be the agent that built the change.
- Validate sub-agent work with lint, typecheck and build before merging.
## Worktrees
- Remove your worktree when its work is pushed or merged.
- Never remove one with uncommitted changes or unpushed commits.
## Deploy
- Push to the default branch; the server builds it.A one-page checklist
| Before | During | After |
|---|---|---|
| git status is clean | Plan first for bigger tasks | git diff, then run the app |
| Goal, check and limits written | Read commands before approving | Tests and build output shown |
| CLAUDE.md up to date | Stop with Esc when it drifts | Review in a fresh session, commit or discard, then /clear |
Compare with other tools in the alternatives list.
What do you type when a session goes wrong?
It is stuck in a loop
The same error appears after the third attempted fix. Stop it with Esc and type:
Stop. Do not try another fix yet. List the three attempts you made, what each changed, and why each failed. Then give me two different explanations for the cause and the one-line check that would tell them apart.It is drifting from the task
Re-read my original task: [paste it]. List which of the changes you made so far are needed for it and which are not. Revert the ones that are not.It chose the wrong direction
Discard this approach. Before you edit anything, give me two other ways to do this, with one risk for each, and wait for my choice.It touched too many files
List every file you changed and the reason it was necessary for the task. Revert every file where you cannot give a reason in one sentence.Esc twice or /rewind also restores Claude's own file edits from the checkpoint before your last prompt. It does not undo changes made by shell commands.
What does a well-run session look like?
This is an illustration of the habits above, not a recording of a real session. The task is to add a "Sort by price" dropdown to a product list.
| Step | You | Tool |
|---|---|---|
| 1 | git status is clean. Write goal, done criteria, check | Nothing yet |
| 2 | Ask for the plan first | Lists app/products/page.tsx, components/ProductList.tsx and a test file |
| 3 | Approve the plan, with "do not change the data format" | Edits the two files, asks to run npm test |
| 4 | Approve the test command for this session | A test fails: sorting is alphabetical on the price text |
| 5 | Wait | Converts the price to a number, runs the test again, it passes |
| 6 | Ask "Show me the build output" | Runs npm run build, shows a clean result |
| 7 | git diff --stat shows three files. Run the app, try three sorts | Nothing |
| 8 | Commit, then /clear | Nothing |
Frequently asked questions
Is it safe to use auto mode?
Auto mode uses a classifier to approve or block actions, so you see fewer prompts. It is not a review of what changed. Keep the project in Git, read the diff and keep secrets behind deny rules.
Is it safe to run Claude Code with permission checks turned off?
Only in a disposable environment such as a throwaway virtual machine or container, with no secrets and nothing you cannot rebuild. The bypassPermissions mode appears only when you enable it, and it skips the prompts that would have stopped a destructive command.
Should I let Claude Code make the Git commits?
You can, but commit yourself after you read the diff until you trust the setup. A commit by the tool records changes you have not reviewed, and a clean history is what lets you return to a good state.
Next guideClaude Code skills →