Frequently Asked Questions

While using Claude Code, you may encounter various issues. This section summarizes common problems and solutions.

Token Usage Is Too Fast?

Fast token consumption is one of the most common issues. Below is a complete optimization strategy.

Diagnosis:

First run /context to inspect current token usage:

/context

Focus on:

• Token usage rate: if over 70%, consider context compression
• Number of referenced files: more files means higher token consumption
• Large files: check which files consume most tokens

Optimization strategy:

1. Improve .claudeignore

Make sure .claudeignore includes unnecessary files:

# must ignore
node_modules/
dist/
build/
*.log
.env

# project-specific
# React
.next/
out/

# Vue
.nuxt/
.output/

# generic
.vscode/
.idea/
coverage/
*.min.js
*.bundle.js

2. Compress context regularly

Long conversations accumulate many tokens. It is recommended to run /compact every 5-6 rounds:

# after long conversation
/compact

# continue
Now let's implement order module...

3. Reference files precisely

Avoid referencing entire directory if not needed:

# not recommended
@src/ Explain this code

# recommended
@src/utils/auth.ts @src/components/Login.tsx Explain login flow

4. Avoid reading huge files

If /context shows one file consuming many tokens, consider:

• do you really need it?
• can you reference only a section?
• can this file be split into smaller modules?

Claude Does Not Understand the Project?

If Claude answers inaccurately or repeatedly asks basic project info, it lacks project context.

Solutions:

1. Generate CLAUDE.md

Run /init to generate project config:

/init

After generation, validate:

• is project summary accurate?
• is stack complete?
• are common commands correct?
• are coding conventions clear?

2. Manually edit CLAUDE.md

If auto-generated config is not detailed enough, add:

## Project-Specific Information

### Architecture Decisions
- Why choose X over Y?
- What are core design patterns?

### Common Pitfalls
- When using useEffect, watch out for...
- DB queries must...

### Third-Party Integrations
- Payments via Stripe
- Email via SendGrid
- File storage via AWS S3

3. Use Rules directory

For large projects, organize conventions in Rules:

.claude/rules/
├── 00-architecture.md    # architecture overview
├── 01-coding-style.md    # coding style
├── 10-frontend.md        # frontend rules
├── 11-backend.md         # backend rules
└── 20-testing.md         # testing rules

4. Add context in prompt when needed

For specific tasks, append relevant background:

We use a custom useAuth Hook for authentication.
It returns { user, login, logout, isLoading }.
Please build a user-menu component based on this Hook.

How to Roll Back Operations?

Claude Code provides multiple rollback mechanisms for different scenarios.

Scenario 1: rollback conversation state

If you only mistyped or dislike response:

Double Esc  -> rollback previous turn
Triple Esc  -> clear all conversation history

Note: this only rolls back conversation state, not file edits.

Scenario 2: undo file edits

If Claude already modified files, undo manually:

# check changes
!git status
!git diff

# revert one file
git checkout -- src/utils/helpers.ts

# revert all working tree changes
git checkout -- .

# if already committed
# soft rollback (keep changes)
git reset --soft HEAD~1

# hard rollback (discard changes)
git reset --hard HEAD~1

Scenario 3: preventively use Git workflow

Best practice: save current work before Claude session:

# save current state before starting
git add .
git commit -m "WIP: before Claude Code session"
# or use stash
git stash push -m "before claude"

# develop with Claude Code...

# if result is unsatisfactory, full rollback
git reset --hard HEAD~1
# or
git stash pop

Too Many Permission Prompts?

Frequent permission confirmations hurt efficiency. Proper permission config can make workflow smoother.

Permission model:

Claude Code permissions are three levels:

• allow: auto-allow
• ask: ask before execution
• deny: fully deny

Optimization config:

Edit .claude/settings.json:

{
  "permissions": {
    "allow": [
      // Git read operations
      "Bash(git status)",
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(git branch)",

      // test and checks
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run typecheck)",

      // dev server
      "Bash(npm run dev:*)",

      // source edits
      "Edit(src/**/*.{ts,tsx})",
      "Edit(tests/**/*.test.ts)",
      "Write(src/**/*.ts)"
    ],
    "ask": [
      // Git write operations
      "Bash(git commit:*)",
      "Bash(git push:*)",
      "Bash(git pull:*)",

      // package management
      "Bash(npm install:*)",
      "Bash(npm uninstall:*)",

      // build and deployment
      "Bash(npm run build)",
      "Bash(npm run deploy:*)",

      // config file edits
      "Edit(package.json)",
      "Edit(tsconfig.json)",

      // sensitive file reads
      "Read(.env)",
      "Read(config/secrets.*)"
    ],
    "deny": [
      // dangerous commands
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl * | sh)",
      "Bash(wget * | sh)",

      // system files
      "Edit(/etc/*)",
      "Write(/usr/*)",

      // Git internals
      "Edit(.git/*)"
    ]
  }
}

Progressive permission strategy:

• Learning phase: keep defaults and understand what Claude tries to execute
• Familiar phase: add common safe operations (like git status, npm test) into allow
• High-efficiency phase: create fine-grained rules based on project characteristics

How to Use in Mainland China?

Due to network constraints, users in China may not directly access Anthropic official services. Here are several options.

Option 1: use API proxy service

Many cloud providers offer Anthropic-compatible API proxy service:

# set env vars
export ANTHROPIC_BASE_URL="https://your-api-proxy.com/v1"
export ANTHROPIC_API_KEY="your-api-key"

# start Claude Code
claude

Option 2: use third-party Claude Code compatible tools

Some domestic providers offer compatible tooling:

# install compatible version
npm install -g @some-provider/claude-code

# configure API key
claude config set api.key your-api-key
claude config set api.baseUrl https://api.some-provider.com

Option 3: use other AI coding tools

If Claude Code is unavailable, consider alternatives:

Option 4: let AI Agent help configure

If you are unsure how to configure, ask AI Agent:

I want to use Claude Code, but I cannot directly access it in mainland China.
I bought an API from provider XXX.
API endpoint is https://api.xxx.com,
key is sk-xxx.

Please configure environment variables so Claude Code can work correctly.

Common questions:

• Q: still cannot connect after configuration?

  • A: check API endpoint correctness, including /v1 path
  • A: check API key validity and balance
  • A: check whether local network needs proxy

• Q: response is slow?

  • A: choose provider with closer geographic region
  • A: use coding-optimized plan instead of generic API plan
  • A: use /compact to reduce token usage

• Q: some features are unavailable?

  • A: some third-party providers may not fully support all Claude Code features
  • A: check provider docs for supported feature scope

Reference Resources

• Claude Code Official Docs
• Claude Code GitHub
• Everything Claude Code