​

Complete Claude Code Tutorial

​

1. Claude Code Introduction and How It Works

​

What is Claude Code?

• Claude Code is a command-line (CLI) tool / agentic coding tool provided by Anthropic that allows you to interact directly with your codebase using natural language: letting Claude understand your project structure, generate/modify code, execute shell commands, submit Git changes, and more.
• It’s not just a simple code completion or chatbot, but an intelligent agent that can proactively take actions (editing files, running commands, Git operations, etc.).
• Claude Code attempts to incorporate project context (file contents, history, prompts) into consideration to make informed decisions.

​

How Claude Acquires Context / Memory

• On startup, Claude Code recursively searches upward from the current directory for CLAUDE.md or CLAUDE.local.md files (CLAUDE.md is currently mainstream), and reads these contents as “memory” or “context”.
• If certain subdirectories (subtrees) also have CLAUDE.md, when entering these subdirectories and reading these subtrees, the CLAUDE.md files in these subtrees will also be included in the context. They are not preloaded at startup.
• The contents of CLAUDE.md become part of Claude’s default “system prompt / background”, meaning Claude will reference the instructions within it when thinking/making decisions.
• During conversations, you can use shortcuts (such as lines starting with #) to write content into CLAUDE.md. For example:
  Copy

  # Always use descriptive variable names
  

• Claude will prompt you to place this line into a specific memory file (i.e., which CLAUDE.md).
• In conversations, you can also use the /memory command to directly edit memory files (i.e., open CLAUDE.md or other memory files for modification).
• CLAUDE.md supports importing other files (using @path/to/file.md syntax), allowing you to split instructions or configurations into multiple files.
• To avoid conflicts or security issues, the import syntax is not interpreted as an import within Markdown code blocks or backticks (``` or `).

​

Claude Code Installation and Configuration

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install node

npm install -g @anthropic-ai/claude-code

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bash_profile
echo 'export ANTHROPIC_BASE_URL="https://gptproto.com"' >> ~/.bash_profile
source ~/.bash_profile

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://gptproto.com"' >> ~/.zshrc
source ~/.zshrc

# Navigate to your project directory
cd your-project-folder

# Start Claude Code
claude

• Select your preferred theme (press Enter)
• Confirm security notice (press Enter)
• Use default Terminal configuration (press Enter)
• Trust working directory (press Enter)
• Start coding! 🚀

​

2. Why Write CLAUDE.md - Its Purpose

1. Setting “Behavioral Guidelines” for the Project/Team For example: variable naming rules, code style, important module descriptions, tool script usage, developer conventions, etc. This helps Claude make decisions or modify code in accordance with team standards.
2. Reducing Repetitive Background in Each Prompt Since it’s loaded at startup, your subsequent natural language prompts to Claude can omit re-explaining these conventions or rules.
3. Guiding Claude’s Behavior / Restricting Permissions / Specifying Tools You can specify in CLAUDE.md which tools are safe to use, which require caution, or tell Claude “use this script/command in this situation”.
4. Project Structure Description / Key Modules and Conventions In multi-person collaboration or large projects, CLAUDE.md helps Claude quickly understand module responsibilities, entry files, dependencies, etc., leading to more reasonable suggestions.
5. Hierarchical Memory / Subdirectory Customization Different submodules or subdirectories in a project can have their own CLAUDE.md to customize local behavior. This way, even when calling Claude in a submodule, it can reference the submodule’s specific rules.
6. Import / Combine Multiple Instructions Using @ syntax, you can split descriptions of different functional modules into multiple .md files, then import them in the main CLAUDE.md. This makes the structure clearer and easier to maintain.
7. Improve Claude’s Decision Quality / Reduce Guessing Many users report: the more standardized and explicit the CLAUDE.md, the more stable and expected Claude’s output becomes.

​

3. How to Create and Configure CLAUDE.md

​

1. Initialize CLAUDE.md

• In your project root directory, run:
  Copy

  /init
  

• Claude Code will attempt to read the project structure, key files, dependencies, etc., then automatically generate a preliminary CLAUDE.md.
• After generation, it’s recommended to manually review and modify it.

​

2. Placement Location and Hierarchy

• Usually placed in the project root directory: ./CLAUDE.md.
• For monorepos or multi-module projects, you can also place additional CLAUDE.md files in parent or subdirectories. When Claude works in a subdirectory, it will prioritize loading the subdirectory’s CLAUDE.md.
• You can also place personal preferences / cross-project instructions in your user directory (such as ~/.claude/CLAUDE.md).
• Currently CLAUDE.local.md (old name) is gradually being deprecated, with the import mechanism recommended as a replacement.

​

3. CLAUDE.md Content Structure and Recommended Format

# Project Name / Introduction

A brief one or two lines: what this project does, key modules, tech stack, etc.

---

## Conventions and Rules

- Code style / formatting (e.g., ESLint rules, indentation, naming style, etc.)
- Naming rules (variable names, function names, class names, interface names, etc.)
- Branch strategy / Git workflow
- Commit conventions / commit message format
- Testing / coverage requirements
- Build / deployment / environment variable descriptions

---

## Directory Structure and Module Descriptions

- `src/`: Frontend code
- `backend/`: Backend services
- `scripts/`: Utility scripts
- `database/`: Database migrations, schema descriptions

(Can also import README, architecture docs, etc.)

---

## Common Commands / Utility Scripts

- `npm run dev`: Start development mode
- `npm run build`: Build
- `npm test`: Run tests
- `scripts/generate-report.sh`: Report generation script

---

## Special Behaviors / Edge Cases / Warnings

- In certain environments, a certain module must be started in a specific way
- Certain files cannot be modified or are restricted
- Performance-sensitive modules require attention

---

## Imports (Optional)

You can use `@path/to/file.md` syntax to import other documentation files:

@README.md
@docs/api-guidelines.md

---

(You can add more sections, such as code examples, convention templates, examples, etc.)

• Keep it concise and clear, avoid cramming too many details. Overly long backgrounds might make it harder for Claude to grasp the key points.
• Write rules in natural language rather than just code snippets. Claude can understand such instructions.
• Moderately provide examples/templates in rules to help Claude understand the meaning.
• When the project evolves or standards change, update CLAUDE.md promptly.
• For team projects, you can commit the main CLAUDE.md to version control so team members can share it.

​

4. Importing Other Files (@syntax)

# Main CLAUDE.md

Project introduction and general conventions are here.

# Subsystem Descriptions
@backend/backend-guidelines.md
@frontend/style-guidelines.md

​

4. Claude Code Basic Usage Flow / Common Commands

​

Installation and Configuration

• Install globally using npm (prerequisite is Node.js installed):
  Copy

  npm install -g @anthropic-ai/claude-code
  

• First startup will go through a configuration process, including OAuth, API key, permission authorization, etc.
• After installation, you can run claude doctor to check environment and version status.
• On Windows, you may need to run it in WSL or Git Bash environment.

​

Common Interactions / Commands

cat logs.txt | claude -p "analyze these errors and suggest fixes"

• Use -p prompt + --output-format stream-json to get JSON output
• Headless mode doesn’t preserve conversation context (each is an independent request)

​

Example Flow: A Typical Task

1. Start Claude: claude
2. Present requirement: > Add user login and registration functionality to this project
3. Claude will scan CLAUDE.md, project files, list a plan (subtask checklist), may ask you to confirm the plan first
4. After you confirm the plan, Claude will make changes to files sequentially (generate, modify, delete, etc.), asking if you accept each modification before proceeding
5. Finally, Claude will generate commits, PRs, commit messages, etc.
6. You can then have Claude review changes, write documentation, refactor, fix bugs, etc.

​

5. Practical Examples (Including CLAUDE.md + Input/Output)

​

Example 1: Small Node.js Project

my-app/
  CLAUDE.md
  package.json
  src/
    index.js
    user.js
  tests/
    user.test.js

# MyApp

This is a simple user management service, including user registration, login, and query interfaces.

---

## Conventions and Rules

- Using JavaScript (Node.js, ES6+)
- Naming style: variables use `camelCase`, class names `PascalCase`
- Use async/await async style, not callbacks
- All request inputs must be validated
- Commit messages use "<module>: <description>" format

---

## Common Commands

- `npm run dev`: Start
- `npm test`: Run tests
- `npm run lint`: Static check

> Add user registration and login functionality to this project (with email + password), and write tests.

1. Claude reads CLAUDE.md, understands project background and conventions
2. Scans project file structure, finds src/user.js and tests/user.test.js
3. Returns a plan, for example:
   Copy

   I suggest implementing in the following steps:
   1. Add register and login methods in src/user.js
   2. Write unit tests for register/login in tests/user.test.js
   3. Add corresponding routes and calls in index.js
   4. Add necessary dependencies in package.json (e.g., bcrypt, jsonwebtoken)
   5. Run lint & tests, ensure everything passes
   

4. After you confirm, Claude generates code changes step by step, asking if you accept each step
5. Finally generates a commit (e.g., “user: add register & login with tests”)

> Review the recent changes, any optimization suggestions?

​

Example 2: Using Imports for Multiple Documentation Files

# Large Project

General background and descriptions are here.

## Frontend Description
@frontend/CLAUDE.md

## Backend Description
@backend/CLAUDE.md

# Frontend Module Rules

- Using React + TypeScript
- CSS modular or Tailwind
- Naming: Component names capitalized, props use camelCase
- Use React Hook style

# Backend Module Rules

- Using Node.js + Express
- Route controller separation
- Unified error handling
- Logging uses Winston

> Add a GET /users endpoint to the backend, returning a user list

​

Example 3: Debug Logs + Pipe Input

cat error.log | claude -p "Analyze this error log and suggest possible root causes and fixes"

​

6. Advanced Tips and Best Practices Summary

​

Summary

• Have Claude follow project coding standards and best practices
• Reduce repetitive work of explaining project background
• Improve quality of code generation and modification
• Better control Claude’s behavior and permissions