iTranslated by AI
A Beginner's Guide to Anthropic's Claude Code Best Practices
Hello, I'm Tomada.
"I want to use AI tools to make coding more efficient!"
Have you started using Claude Code with that thought, but are struggling because you're not getting the results you expect?
In this article, I will extract and explain snippets from the Claude Code Best Practices published by Anthropic in a way that is easy for beginners to understand!
By reading this, you should be able to master Claude Code more effectively.
By the way, I work as a freelance engineer and provide support for introducing AI-driven development.
I also offer multiple AI-driven development courses on Udemy, and several have become bestsellers.
Leveraging that experience, I will explain things carefully so that even beginners can understand!
Summary for Busy People
- Share development rules with the
CLAUDE.mdfile - Balance safety and efficiency with proper tool permission settings
- Development flows using Test-Driven Development (TDD) and visual mocks are effective
- Run multiple Claude Code instances in parallel to improve productivity
- Utilize version control and PR reviews using GitHub CLI
- Improve development efficiency by customizing commands
- Usage with an awareness of security and safety is crucial
- Automation via headless mode is also possible
Also, if you haven't used Claude Code yet, you can learn from this book I've published for free.
What is Claude Code?
First, let me briefly explain Claude Code again.
Claude Code is an AI-driven coding assistance tool provided by Anthropic.
It can be used directly from the command line and supports a wide range of development tasks, from creating and editing files to running tests and integrating with Git and GitHub.
A characteristic feature is that the AI doesn't just generate code; it can actually manipulate files and execute commands.
However, there are a few tricks to mastering this powerful functionality.
Now, let's look at specific best practices.
Efficient Team Development with CLAUDE.md
A Mechanism to Share Project Rules
Claude Code has a special file called CLAUDE.md.
If you place this file in the project's root directory, Claude Code will automatically read it.
In other words, if you list development rules or frequently used commands that you want to share with the whole team, you won't need to explain them every time.
Examples of Using CLAUDE.md
For example, it is useful to include information like the following:
# Project Commands
- npm run build: Build the project
- npm run typecheck: Run type checking
# Coding Standards
- Use ES modules (do not use CommonJS)
- Write imports using destructuring where possible
# Development Flow
- Always run typecheck after changes
- Run tests individually (avoid running all at once)
By writing it this way, Claude Code will automatically proceed with development according to these rules.
New team members can also quickly understand how to proceed with development just by looking at this file.
I have explained the detailed writing style and usage of CLAUDE.md in another article.
What is CLAUDE.md? Understanding Claude Code Project Configuration Files
Where to Place CLAUDE.md
The CLAUDE.md file can be placed in the following locations:
- Project Root: The most common location
- Parent Directory: Useful when you have multiple projects in a monorepo
- Child Directory: Automatically loaded when working within a specific folder
-
Home Folder (
~/.claude/CLAUDE.md): Common settings for all projects
Solving Complex Problems with Sub-agents
What are Sub-agents?
Sub-agents are independent AI agents specialized for specific tasks.
Each has its own dedicated context window and tool permissions, allowing them to work separately from the main conversation.
They are defined in Markdown format in the .claude/agents/ folder and managed using the /agents command.
Although it's a slightly older article, I've explained it in detail here:
Leveraging Sub-agents in the Exploration Phase
When tackling complex problems, leaving everything to the main Claude Code instance can cause the context to become overloaded.
In such cases, it is effective to let a sub-agent handle the detailed investigation.
For example, you can give instructions like this:
Please read the related files and establish an implementation plan.
If there are any technically unclear points, use a sub-agent to investigate in detail.
By doing this, the main Claude Code can focus on the overall strategy while delegating detailed technical research to the sub-agent.
Since sub-agents operate in an independent context, they don't clutter the main conversation, allowing for deeper investigation and improved implementation accuracy.
Use for Implementation Verification
A common pitfall in Test-Driven Development is creating an "implementation that only passes the tests."
To prevent this, instructions like the following are effective:
Once you have an implementation that passes all tests,
use an independent sub-agent to verify if the implementation is appropriate.
Ask it to check if it's overly dependent on the tests.
Sub-agents can evaluate the implementation from a different perspective than the main instance, enabling a more objective code review.
I have explained the mechanism and detailed usage of sub-agents in another article.
What are Claude Code Sub-agents? Parallel Processing and Context Isolation Mechanism
How to Manage Sub-agents
To create or edit sub-agents, use the /agents command.
/agents
With this command, you can:
- List existing sub-agents
- Create new sub-agents
- Edit or delete sub-agents
- Configure available tools
Project-specific sub-agents are saved in .claude/agents/, while common sub-agents for all projects are saved in ~/.claude/agents/.
Efficient Long-term Work with Context Management
Context refers to the information the AI holds.
Just like humans, if there is too much context, the ability to accurately recall information decreases.
Using the /clear Command Strategically
When using Claude Code for long periods, does it start to feel slow or give irrelevant suggestions?
This happens because the context window becomes full of unnecessary information.
Therefore, you can reset the context by using the /clear command.
/clear
In human terms, it's like "refreshing and resetting your mind."
When moving on to implement a different feature, don't hesitate to use /clear.
However, be careful as /clear resets all context.
If you want to continue working while saving space, you can use the /compact command to compress the context.
/compact
"Compression" here means summarizing the work done so far to save context.
Since this carries over the previous context, use /clear when moving to a completely different task.
By the way, if you make significant feature additions or design changes, you can update CLAUDE.md using the /init command.
/init
You can run /init as many times as you like, so if you've made major changes, go ahead and execute it.
Rest assured that the content of CLAUDE.md is preserved even when using /clear or /compact.
Detailed context management techniques are explained in another article.
Complete Guide to Claude Code Context Management: Using /clear, /compact, and /context
Tips for Long Sessions
Create Checklists
When you have a large number of tasks (for example, fixing lint errors), it's useful to create a checklist in a Markdown file.
1. List all lint errors in checklist.md
2. Fix them one by one, and check them off when finished
3. Report progress after fixing every 10 items
This way, even if the context grows, it remains clear how much progress has been made.
Save Important Decisions in External Files
Keep implementation plans and important decisions in separate files.
Summarize the implementation plan for this task in implementation_notes.md,
then /clear and proceed to the next task.
This helps when you later wonder, "What was the plan at that time?"
This is an important point for both AI and humans.
Extending Tools with MCP (Model Context Protocol)
Integrating with External Tools via MCP Servers
Claude Code also acts as an MCP client, allowing integration with external tools.
I didn't quite get it at first either, but you can just think of it as "a mechanism to increase the tools Claude Code can use."
For example, in web app development, using the Chrome DevTools MCP server allows you to perform UI and performance checks, which significantly improves development efficiency.
Additionally, by creating a .mcp.json file in the project root, the entire team can use the same tools.
// Example: When using Sentry MCP server
{
"mcpServers": {
"sentry": {
"type": "http",
"url": "https://mcp.sentry.dev/mcp",
"args": ["--sentry-auth-token", "your-auth-token"]
},
}
}
In team development, including this configuration file in Git is convenient as it allows all members to work in the same environment.
MCP's basic mechanism and setup methods are explained in detail in another article.
What is MCP? Explaining Model Context Protocol for Integrating External Tools with Claude Code
Ensuring Safety with Proper Permission Settings
Why Permission Settings are Important
Claude Code is a powerful tool, but it is capable of operations that affect the system, such as editing files and executing commands.
Therefore, by default, it asks for permission for many operations.
However, being asked for permission every time is not efficient.
To work efficiently while maintaining safety, appropriate permission settings are important.
How to Configure Permissions
There are four ways to configure permissions:
- Select "Always allow" during a session
- Use the
/permissionscommand - Edit the configuration file directly
- Use the
--allowedToolsflag
It is convenient to add frequently used tools to the allowlist in advance.
There are various ways to do this, but configuring them in settings.json is recommended as it's easy to organize.
A detailed guide on permission settings and how to balance security and convenience is explained in another article.
Optimizing Claude Code Permission Settings: Balancing Security and Convenience
If you are collaborating with GitHub, I also recommend installing the gh CLI.
Practicing Effective Development Flows
Workflow: Exploration, Planning, Implementation, and Committing
In development using Claude Code, a flow like the following is effective:
- Exploration: Have it read related files.
- Planning: Create an implementation plan.
- Implementation: Write the code.
- Committing: Save the changes.
The key is not to have it write code immediately, but to have it create a plan first.
By the way, if you use the word "think," Claude Code will spend more time thinking.
Please read the related files and propose an implementation plan for this feature think
Furthermore, if you want it to think even more deeply, you can use phrases like "think hard," "think harder," or "ultrathink."
These specific phrases are mapped directly to increasing levels of thinking budget in the system: "think" < "think hard" < "think harder" < "ultrathink." Each level allocates progressively more thinking budget for Claude to use.
Alternatively, pressing the tab key will also enter "think" mode.
Leveraging Test-Driven Development (TDD)
Writing tests before implementation is also highly effective in AI-driven development in general, not just with Claude Code.
- Write tests: Define the expected behavior clearly.
- Verify test failure: Confirm the implementation is missing.
- Commit tests: Lock in the test requirements.
- Write implementation: Repeat until tests pass.
- Commit implementation: Save the completed code.
With this approach, Claude Code works toward a clear goal (passing the tests), which often leads to better results.
"Setting the goal first and having it work toward it" is a fundamental principle of AI-driven development.
Development Using Visual Mocks
When building a UI, preparing a design mock and having it implement based on that is also effective.
- Provide a design mock: Give it an image or screenshot.
- Request implementation: Have it write code based on the mock.
- Check with screenshots: Verify the implementation results using images.
- Iterate: Refine until it matches the mock.
With visual feedback, Claude Code can provide much more accurate implementations.
Visual mocks aren't just for Claude Code; they can also be used with tools like Cursor and Codex.
Leveraging Git and GitHub
Automating Version Control
Claude Code is also proficient in version control using Git commands. You can delegate many tasks such as creating commit messages, managing branches, and performing merges.
Verify the changes and commit with an appropriate commit message
If you are uneasy about having it commit immediately in a real-world setting, try instructing it to "Suggest a commit message." By following up with "Please commit," you can proceed with confidence.
Leveraging GitHub Integration
If you are using GitHub and have the GitHub CLI installed, you can perform tasks such as:
- Creating pull requests
- Commenting on issues
- Responding to code reviews
- Fixing build errors
In particular, fixing issues pointed out in code reviews is an area where Claude Code excels. In my case, I have it retrieve review comments the AI left on a PR and then execute the fixes.
For more information on GitHub CLI, this article is easy to understand:
When using GitHub CLI, it is convenient to add something like the following to your CLAUDE.md:
# Create a PR using the GitHub CLI
gh pr create
...(Write various other things)
This also helps the AI understand that "I can use the GitHub CLI."
Customizing Commands
Creating Slash Commands
You can register frequently used tasks as custom commands. By creating a Markdown file in the .claude/commands folder, you can use it as a slash command.
For example, to create a command that performs fixes based on a GitHub issue:
# .claude/commands/fix-github-issue.md
Check GitHub issue #$ARGUMENTS and perform the following:
1. Read the issue content
2. Identify related files
3. Implement fixes
4. Run tests
5. Create a pull request
You would execute it like this:
/fix-github-issue 1234
By using $ARGUMENTS within the Markdown file, you can pass values when running the command. In this case, passing the issue number triggers the fix for that specific issue.
Additionally, if you place it in ~/.claude/commands/ in your home directory, it will be available as a common command across all projects.
Detailed instructions on creating custom commands and setting YAML front matter are explained in another article.
Introduction to Claude Code Custom Commands: How to Create Slash Commands
Ensuring Security and Safety
Avoiding Dangerous Operations
Since Claude Code is a powerful tool, it is important to be aware of the following points:
- Do not use in production environments: Limit usage to development environments.
- Do not handle sensitive information: Manage API keys and passwords separately.
- Back up important files: Always create a backup before starting work.
Leveraging Container Environments
If you want to use it more safely, running it within a Docker container is recommended.
docker run -it --rm -v $(pwd):/workspace ubuntu:latest
# Run Claude Code inside the container
This ensures that even if something happens, the impact on the host system is minimized.
Parallel Use of Multiple Claude Code Instances
I don't do this very often myself, but since it is also mentioned in the best practices published by Anthropic, I will introduce it here.
However, this is a bit of an advanced technique, so beginners don't need to force themselves to do it.
Improving Efficiency with Parallel Work
In large projects, there is a method to significantly improve development efficiency by running multiple instances of Claude Code simultaneously.
For example, you can divide tasks like this:
- Claude A: Implementing new features
- Claude B: Creating tests
- Claude C: Updating documentation
- Claude D: Bug fixes
Leveraging Git Worktrees
By using the Git worktree feature, you can work on different branches of the same repository in parallel.
git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude
This allows you to progress with multiple feature developments at the same time.
Automation with Headless Mode
I haven't fully utilized this myself either, but since it's also in the best practices from Anthropic, I'll introduce it.
Integration into CI/CD Pipelines
Claude Code also operates in headless mode (without interaction).
This allows you to integrate it into your CI/CD pipeline for automation.
claude -p "Analyze the review comments on this pull request and suggest improvements" --output-format stream-json
Automatic Issue Categorization
Example of automatically categorizing GitHub issues:
claude -p "Review new issues and apply appropriate labels" --dangerously-skip-permissions
However, please use the --dangerously-skip-permissions flag with caution.
Summary
Claude Code is a tool that can multiply your development efficiency many times over if used correctly.
By putting the best practices introduced this time into practice, you should be able to achieve safer and more efficient development.
The following three points are especially important, so please keep them in mind:
- Formalize development rules in CLAUDE.md
- Practice a step-by-step development workflow
- Ensure proper permission settings and security
I recommend trying out Claude Code's features little by little while keeping these points in mind.
If you start with small tasks and gradually delegate more complex work, it will surely become an indispensable tool.
I hope you all use Claude Code to achieve more efficient development!
Other Related Articles on Claude Code
【Copy-paste OK】Set rules to avoid technical debt (Supports Claude Code, Codex, Cursor)
I also post practical videos on AI-driven development on YouTube!
If you like, please subscribe to the channel and catch up on practical information about AI-driven development!
📚 Learn More with Udemy Courses
For those who want to learn the content of this article even more deeply:
I have released a Udemy course that systematically explains six extension features: CLAUDE.md, rules, custom commands, sub-agents, Skills, and Hooks.
You can learn how to maximize development efficiency while saving context through a hands-on format.
You can take the course using the 1,500 yen special coupon from the link above.
Discussion