Claude Code Best Practices and Usage Tips

Claude Code is an intelligent programming assistant launched by Anthropic, directly integrated into the terminal environment, capable of understanding codebases and helping with programming through natural language commands.

This article systematically shares Claude Code best practices and usage tips from a practitioner's perspective.

1️⃣ Initial Configuration

1.1 Installing Claude Code

# Global installation
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

1.2 Creating CLAUDE.md File

CLAUDE.md is Claude Code's core configuration file that is automatically read and included in the context.

File content should include:

• Project basic information and architecture description
• Common commands and build scripts
• Code standards and conventions
• Testing guidelines
• Development environment configuration
• Other necessary context information (can reference project files through @path/to/import)

Creation methods:

# Use /init command for automatic generation
claude> /init

# Or create manually and fill content
touch CLAUDE.md

File location priority:

• Project root directory: ./CLAUDE.md (recommended, can be committed to git)
• Project local: ./CLAUDE.local.md (not committed to git)
• Global configuration: ~/.claude/CLAUDE.md
• Parent and subdirectories are also automatically read

1.3 Configuring Tool Permissions

Claude Code adopts a conservative permission strategy by default. You can explicitly authorize through four methods:

1. Interactive authorization prompts at startup
2. Running /permissions command
3. Manually editing .claude/settings.json
4. Startup parameter --allowedTools

# Use /permissions command to manage permissions
> /permissions

# Or through command line parameters
claude --allowedTools Edit,Bash(git commit:*)

Recommended allowed tools:

• Edit: File editing
• Bash(git commit:*): Git commit operations
• WebFetch(*): Access to URL websites

1.4 Installing Supporting Tools

Recommended to install GitHub CLI to automate GitHub workflows:

# Install GitHub CLI
brew install gh

# Configure GitHub authentication
gh auth login

2️⃣ Workflows

2.1 Explore - Plan - Code - Commit Workflow

This is the most universal workflow, suitable for most development tasks:

# 1. Exploration phase - understand existing code
"Please read relevant files to understand the current architecture, but don't write code yet"

# 2. Planning phase - use extended thinking (press Shift+TAB twice to enter PLAN mode)
"Please ultrathink and create a detailed implementation plan, and instruct sub-agents to verify key details in parallel"

# 3. Coding phase
"Please implement the functionality according to the plan"

# 4. Commit phase
"Please commit changes and create PR"

2.2 Test-Driven Development Workflow

For functionality that can be verified through tests:

# 1. Write tests
"Please write tests based on expected inputs and outputs, ensure tests will fail"

# 2. Run tests to confirm failure
"Run tests to confirm failure, don't write implementation code"

# 3. Commit tests
"Please commit test code"

# 4. Implement functionality
"Please write code to make tests pass, don't modify tests"

# 5. Commit implementation
"Please commit implementation code"

2.3 UI Development Iteration Workflow

For frontend development:

# 1. Provide design mockups
# Drag images to Claude Code interface

# 2. Implement UI
"Please implement the interface according to the design mockup"

# 3. Screenshot comparison
"Please take a screenshot of current implementation, compare with design mockup and improve"

# 4. Iterative optimization
"Please continue optimizing until the effect is satisfactory"

3️⃣ Advanced Features and Tips

3.1 Using MCP Extensions

Claude Code supports MCP (Model Context Protocol) to extend functionality:

// .mcp.json example
{
  "mcpServers": {
    "playwright": {
      "args": ["@playwright/mcp@latest", "--headless"],
      "command": "npx"
    },
    "context7": {
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "command": "npx"
    }
  }
}

3.2 Custom Slash Commands

Create custom commands in the .claude/commands/ directory.

Example: Create issue.md for fixing GitHub Issues

# .claude/commands/issue.md
Please analyze and fix the Github issue: $ARGUMENTS.

Follow these steps:

## PLAN
1. Use 'gh issue view' to get the issue details
2. Understand the problem described in the issue
3. Ask clarifying questions if necessary
4. Understand the prior art for this issue
   - Search the scratchpads for previous thoughts related to the issue
   - Search PRs to see if you can find history on this issue
   - Search the codebase for relevant files
5. Think harder about how to break the issue down into a series of small, manageable tasks.
6. Document your plan in a new scratchpad
   - include the issue name in the filename
   - include a link to the issue in the scratchpad.

## CREATE
- Create a new branch for the issue
- Solve the issue in small, manageable steps, according to your plan.
- Commit your changes after each step.

## TEST
- Use puppeteer via MCP to test the changes if you have made changes to the UI
- Write unit tests to describe the expected behavior of your code
- Run the full test suite to ensure you haven't broken anything
- If the tests are failing, fix them
- Ensure that all tests are passing before moving on to the next step

## SUBMIT
- Push and open a PR on Github.

Remember to use the GitHub CLI ('gh') for all Github-related tasks.

Usage:

> /issue 1234

3.3 Context Management

Claude Code has limited context window, and overly long context leads to severe hallucinations, requiring proper management:

Management strategies:

• Use @ to reference files
• Use /clear to clear previous task information when switching tasks
• Regularly compress context during long sessions
• Restore from historical sessions when necessary
• Record important information to CLAUDE.md through # <context>

Command formats:

# Use file references
Please refer to the structure of @src/components/UserProfile.tsx

# Compress context
> /compact

# Clear context
> /clear

# Add memory
# <context>

# Restore historical session
/resume

Restore session at startup:

# Continue last session
claude --continue
claude --continue --print   # Suitable for script calls

# Choose from historical sessions to continue
claude --resume

4️⃣ Project Organization and Management

4.1 Using ROADMAP.md to Manage Projects

Create project roadmap:

# Project Development Roadmap

## Development Process

1. **Task Planning**
   - Analyze existing code foundation
   - Update ROADMAP.md to add new tasks
   - Insert priority tasks after the last completed task

2. **Task Creation**
   - Create detailed task files in `/tasks` directory
   - Naming format: `XXX-description.md`
   - Include specifications, related files, acceptance criteria

3. **Task Implementation**
   - Implement according to steps in task file
   - Update task file progress after completing each step
   - Pause after each step completion waiting for further instructions

## Task List

### Completed ✅
- **Task 001: Database Architecture** ✅
  - Reference: `/tasks/001-database.md`
  - Implemented core table structure and relationships

### In Progress 🔄
- **Task 002: User Interface** 🔄
  - Reference: `/tasks/002-ui.md`
  - Currently implementing login and registration pages

### Planned 📋
- **Task 003: API Interface**
  - Design RESTful API
  - Implement user authentication

4.2 Task Template

# Task XXX: Feature Description

## Progress Summary

**Status**: Not Started

- [ ] Step 1: Create component
- [ ] Step 2: Implement logic
- [ ] Step 3: Write tests
- [ ] Step 4: Integration verification

## Overview

Detailed description of functional requirements and expected effects.

## Current State Analysis

Analyze existing code foundation and related files.

## Target State

Describe the desired state after completion.

## Implementation Steps

### Step 1: Create Component

Detailed description of what needs to be done in the first step.

**Files involved:**
- `src/components/NewComponent.tsx`
- `src/types/index.ts`

### Step 2: Implement Logic

Detailed description of what needs to be done in the second step.

## Acceptance Criteria

### Functional Requirements
- [ ] Feature A works properly
- [ ] Feature B works properly

### Technical Requirements
- [ ] Pass all tests
- [ ] Code complies with standards
- [ ] Performance meets requirements

## Related Files

### New Files
- `src/components/NewComponent.tsx`
- `src/utils/helper.ts`

### Modified Files
- `src/app/page.tsx`
- `src/types/index.ts`

## Notes

- Maintain backward compatibility
- Ensure responsive design
- Consider accessibility

4.3 Parallel Workflows

When needing to develop multiple feature branches simultaneously, use in combination with git worktree:

# Create new worktree
git worktree add ../feature-branch feature/new-feature

# Start Claude Code in new worktree
cd ../feature-branch
claude

# Manage multiple worktrees
git worktree list
git worktree remove ../feature-branch

5️⃣ Common Commands Quick Reference

Basic Commands

claude                    # Start interactive mode
claude "describe task"    # One-time command
claude --continue         # Continue last session
claude --resume          # Choose historical session

Interactive Commands

/init                    # Initialize project configuration
/permissions             # Manage tool permissions
/clear                   # Clear context
/compact                 # Compress context
/resume                  # Resume session

File Operations

@filename                # Reference file
@folder/                # Reference directory
# <context>             # Add context marker

Custom Commands

/project:command-name    # Project-level custom command
/user:command-name       # User-level custom command

6️⃣ Best Practices Summary

1. Project Initialization

   • Create detailed CLAUDE.md configuration file
   • Set appropriate tool permissions
   • Establish project documentation structure

2. Workflows

   • Follow the standard explore-plan-code-commit process
   • Use test-driven development for important features
   • Use design mockup comparison iteration for UI development

3. Context Management

   • Timely clear and compress context
   • Reasonably use file references
   • Record important information to configuration files

4. Project Management

   • Use ROADMAP.md to plan projects
   • Create detailed task templates
   • Utilize git worktree for parallel development

5. Efficiency Enhancement

   • Create commonly used custom commands
   • Configure MCP extension tools
   • Combine GitHub CLI for automated processes

Through these best practices, you will be able to fully utilize Claude Code's powerful features and significantly improve development efficiency and code quality.

---

💡 Tip: It's recommended to use this guide as a reference manual and adjust and optimize workflows according to project characteristics in actual development.