CLAUDE.md is a special file that Claude automatically pulls into context when starting a conversation. This makes it an ideal place for documenting (View Highlight)
• Common bash commands
• Core files and utility functions
• Code style guidelines
• Testing instructions
• Repository etiquette (e.g., branch naming, merge vs. rebase, etc.) (View Highlight)
• Developer environment setup (e.g., pyenv use, which compilers work)
• Any unexpected behaviors or warnings particular to the project
• Other information you want Claude to remember (View Highlight)
You can place CLAUDE.md files in several locations:
• The root of your repo, or wherever you run claude from (the most common usage). Name it CLAUDE.md and check it into git so that you can share it across sessions and with your team (recommended), or name it CLAUDE.local.md and .gitignore it (View Highlight)
Any parent of the directory where you run claude. This is most useful for monorepos, where you might run claude from root/foo, and have CLAUDE.md files in both root/CLAUDE.md and root/foo/CLAUDE.md. Both of these will be pulled into context automatically (View Highlight)
Any child of the directory where you run claude. This is the inverse of the above, and in this case, Claude will pull in CLAUDE.md files on demand when you work with files in child directories (View Highlight)
Your home folder (~/.claude/CLAUDE.md), which applies it to all your claude sessions (View Highlight)
Your CLAUDE.md files become part of Claude’s prompts, so they should be refined like any frequently used prompt. A common mistake is adding extensive content without iterating on its effectiveness. Take time to experiment and determine what produces the best instruction following from the model. (View Highlight)
Ask Claude to make a plan for how to approach a specific problem. We recommend using the word "think" to trigger extended thinking mode, which gives Claude additional computation time to evaluate alternatives more thoroughly. These specific phrases are mapped directly to increasing levels of thinking budget in the system: (View Highlight)
Steps #1-#2 are crucial—without them, Claude tends to jump straight to coding a solution. While sometimes that's what you want, asking Claude to research and plan first significantly improves performance for problems requiring deeper thinking upfront. (View Highlight)
Ask Claude to write tests based on expected input/output pairs. Be explicit about the fact that you’re doing test-driven development so that it avoids creating mock implementations, even for functionality that doesn’t exist yet in the codebase. (View Highlight)
Tell Claude to run the tests and confirm they fail. Explicitly telling it not to write any implementation code at this stage is often helpful. (View Highlight)
Ask Claude to commit the tests when you’re satisfied with them. (View Highlight)
Ask Claude to write code that passes the tests, instructing it not to modify the tests. Tell Claude to keep going until all tests pass. It will usually take a few iterations for Claude to write code, run the tests, adjust the code, and run the tests again. (View Highlight)
Ask Claude to commit the code once you’re satisfied with the changes. (View Highlight)
Write code, screenshot result, iterate
Similar to the testing workflow, you can provide Claude with visual targets:
Give Claude a visual mock by copying / pasting or drag-dropping an image, or giving Claude the image file path.
Ask Claude to implement the design in code, take screenshots of the result, and iterate until its result matches the mock.
Ask Claude to commit when you're satisfied. (View Highlight)
When onboarding to a new codebase, use Claude Code for learning and exploration. You can ask Claude the same sorts of questions you would ask another engineer on the project when pair programming. Claude can agentically search the codebase to answer general questions like: (View Highlight)
• How does logging work?
• How do I make a new API endpoint?
• What does async move { ... } do on line 134 of foo.rs?
• What edge cases does CustomerOnboardingFlowImpl handle?
• Why are we calling foo() instead of bar() on line 333?
• What’s the equivalent of line 334 of baz.py in Java? (View Highlight)
At Anthropic, using Claude Code in this way has become our core onboarding workflow, significantly improving ramp-up time and reducing load on other engineers. (View Highlight)
Claude Code’s success rate improves significantly with more specific instructions, especially on first attempts. Giving clear directions upfront reduces the need for course corrections later.
For example:
Poor
Good
add tests for foo.py
write a new test case for foo.py, covering the edge case where the user is logged out. avoid mocks
why does ExecutionFactory have such a weird api?
look through ExecutionFactory's git history and summarize how its api came to be (View Highlight)
add a calendar widgetlook at how existing widgets are implemented on the home page to understand the patterns and specifically how code and interfaces are separated out. HotDogWidget.php is a good example to start with. then, follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. Build from scratch without libraries other than the ones already used in the rest of the codebase. (View Highlight)
Ask Claude to make a plan before coding. Explicitly tell it not to code until you’ve confirmed its plan looks good. (View Highlight)
Press Escape to interrupt Claude during any phase (thinking, tool calls, file edits), preserving context so you can redirect or expand instructions. (View Highlight)
Double-tap Escape to jump back in history, edit a previous prompt, and explore a different direction. You can edit the prompt and repeat until you get the result you're looking for. (View Highlight)
Ask Claude to undo changes, often in conjunction with option #2 to take a different approach. (View Highlight)
Use checklists and scratchpads for complex workflows
For large tasks with multiple steps or requiring exhaustive solutions—like code migrations, fixing numerous lint errors, or running complex build scripts—improve performance by having Claude use a Markdown file (or even a GitHub issue!) as a checklist and working scratchpad: (View Highlight)
For example, to fix a large number of lint issues, you can do the following:
Tell Claude to run the lint command and write all resulting errors (with filenames and line numbers) to a Markdown checklist
Instruct Claude to address each issue one by one, fixing and verifying before checking it off and moving to the next (View Highlight)
