Claude Code Best Practices Guide

TL;DR

Anthropic published a best‑practices guide for Claude Code, a low‑level, unopinionated command‑line tool that gives engineers raw access to Claude for agentic coding. The guide explains how to configure the environment, extend tooling, and adopt proven workflows to boost productivity and safety.

1. Customize Your Setup

1a. Create CLAUDE.md files

CLAUDE.md is automatically loaded into Claude’s prompt context. Use it to document common commands, utility functions, code‑style guidelines, testing instructions, repository etiquette, environment setup, and any project‑specific quirks. Place the file at the repository root, in parent or child directories for monorepos, or in ~/.claude/ for global defaults. The /init command can generate a starter file.

1b. Tune CLAUDE.md content

Treat CLAUDE.md like a frequently used prompt: iterate on its wording, keep it concise, and emphasize critical instructions (e.g., with “IMPORTANT” or “YOU MUST”). Use the # key to have Claude add documentation automatically, and consider running the file through Anthropic’s Prompt Improver for higher adherence.

1c. Curate the allowed‑tools list

Claude Code conservatively requests permission for any system‑modifying action. You can whitelist tools via:

  • Selecting Always allow during a session.
  • Running the /permissions command (e.g., Edit, Bash(git commit:*)).
  • Editing .claude/settings.json or ~/.claude.json (check the former into source control).
  • Using the --allowedTools CLI flag for one‑off sessions.

1d. Install the GitHub CLI (gh)

With gh installed, Claude can create issues, open PRs, and read comments directly. Without it, Claude falls back to the GitHub API or an MCP server.

2. Give Claude More Tools

2a. Leverage bash utilities

Claude inherits your shell environment. To expose custom scripts, describe the tool name and usage, ask Claude to run --help, and document the tool in CLAUDE.md.

2b. Connect to MCP servers

Claude Code acts as both MCP client and server. Register tools in project‑level config, global config, or a checked‑in .mcp.json. Use --mcp-debug to troubleshoot configuration.

2c. Define custom slash commands

Store reusable prompt templates in .claude/commands/*.md. They appear under the / menu and can accept arguments via the $ARGUMENTS placeholder. Commit these files to share across the team.

3. Proven Workflows

3a. Explore → Plan → Code → Commit

  1. Read relevant files or URLs without writing code.
  2. Plan using the “think” hierarchy (think, think hard, think harder, ultrathink) to allocate more computation budget.
  3. Implement the solution, asking Claude to verify reasoning.
  4. Commit and optionally generate a PR or update documentation.

3b. Test‑Driven Development (TDD)

  1. Prompt Claude to write failing tests.
  2. Run the tests and confirm failure.
  3. Commit the tests.
  4. Instruct Claude to write code that passes the tests, iterating until all pass.

3c. Visual iteration with screenshots

Provide design mocks via pasted screenshots, drag‑and‑drop, or file paths. Ask Claude to implement the UI, capture screenshots of the result, and iterate until the mock matches.

3d. Safe “YOLO” mode

Use claude --dangerously-skip-permissions to bypass permission checks for quick, low‑risk tasks (e.g., lint fixes). Run inside an isolated, internet‑blocked container to mitigate data‑loss risks.

3e. Codebase Q&A

Treat Claude as a pair‑programmer: ask questions like “How does logging work?” or “What does async move { … } do on line 134 of foo.rs?” Claude will search the repository and answer without special prompting.

3f. Git interactions

Claude can:

  • Search git history for changes or ownership.
  • Draft commit messages based on diffs.
  • Perform complex git operations (reverts, rebases, patch grafting).

3g. GitHub automation

Claude understands shorthand like “pr” to create pull requests, can fix review comments, triage issues, and label them automatically.

3h. Jupyter notebook support

Claude can read/write .ipynb files, interpret output images, and improve notebook aesthetics when instructed.

4. Workflow Optimizations

4a. Be specific

Clear, detailed instructions dramatically improve Claude’s success rate on first attempts.

4b. Provide images

Paste or drag‑and‑drop screenshots, diagrams, or design mocks; Claude processes them directly.

4c. Mention target files

Use tab‑completion to reference exact file paths, ensuring Claude works on the correct resources.

4d. Supply URLs

Paste URLs for Claude to fetch; add domains to the allowlist via /permissions to avoid repeated prompts.

4e. Course‑correct early and often

  • Ask Claude to plan before coding.
  • Press Escape to interrupt and retain context.
  • Double‑tap Escape to edit previous prompts.
  • Use undo to revert unwanted changes.

4f. Clear context with /clear

Periodically reset the context window during long sessions to keep Claude focused.

4g. Use checklists and scratchpads

For large, multi‑step tasks, maintain a Markdown checklist or GitHub issue as a shared scratchpad, letting Claude tick off completed items.

4h. Pass data efficiently

Combine copy‑paste, piping (cat foo.txt | claude), bash commands, MCP tools, or file reads to feed logs, CSVs, or other data into Claude.

5. Headless Mode for Automation

Run Claude non‑interactively with -p "<prompt>" --output-format stream-json for CI, pre‑commit hooks, or other scripts.

5a. Issue triage automation

Trigger Claude via GitHub Actions to label new issues, as demonstrated in the public Claude Code repository.

5b. Subjective linting

Use Claude in a GitHub Action to provide nuanced code‑review comments beyond static linters.

6. Multi‑Claude Workflows

6a. Parallel verification

Run one Claude instance to generate code and a second to review or test it, then feed feedback back to the first.

6b. Multiple checkouts

Spawn separate git checkouts (or worktrees) and run independent Claude sessions on each, allowing parallel task execution.

6c. Git worktrees for lightweight parallelism

Create worktrees (git worktree add …) and launch Claude in each directory to isolate tasks while sharing history.

6d. Headless pipelines

  • Fan‑out: Generate a task list, then loop over items, invoking Claude with --allowedTools for each.
  • Pipelining: Pipe Claude’s JSON output into downstream commands for further processing.

“Claude Code is intentionally low‑level and unopinionated, providing close to raw model access without forcing specific workflows.” — Anthropic

Bottom line: By configuring CLAUDE.md, curating tool permissions, extending Claude with MCP and custom slash commands, and following proven workflows such as plan‑first coding or test‑driven development, engineers can harness Claude Code as a safe, flexible, and highly productive agentic coding assistant.

Sources