Top 10 Common Claude Code Issues and Practical Solutions

1. CLAUDE.md – purpose and impact

CLAUDE.md is a project "team charter" that Claude Code reads at startup. Without it Claude must ask many questions to understand the project, consuming extra tokens. A concise CLAUDE.md (100‑200 lines) describing the tech stack, coding conventions, and common commands reduces token usage by about half and cuts background conversation rounds.

# CLAUDE.md

## 项目简介
用户订单系统，Spring Boot 3.2 + MyBatis-Plus + MySQL 8.0

## 常用命令
- 启动: `mvn spring-boot:run`
- 测试: `mvn test`
- 构建: `mvn clean package -DskipTests`

## 代码规范
- 命名: 驼峰命名，表名用下划线分隔
- 分层: Controller 只做参数校验和路由，业务逻辑全部在 Service 层
- 数据库: 禁止在代码里写 SQL，统一用 XML mapper

## 已知坑点
- 订单表的 create_time 字段用的是 UTC，前端展示需要转东八区
- 第三方支付回调地址必须用 HTTPS，本地调试用 ngrok

In a 120 k‑line Java project, using CLAUDE.md cut the average number of dialogue rounds from 3‑4 to a single round and halved token consumption.

Scope of CLAUDE.md (three levels)

Project root/CLAUDE.md – current project – tech stack, coding conventions, common commands

~/.claude/CLAUDE.md – all projects – personal preferences, universal rules

Subdirectory/CLAUDE.md – specific module – module‑specific architecture notes

2. Reducing token cost

Typical daily cost is $3‑8. If you see $20+, one of the following is likely:

Use /compact to compress long conversations; a 50 k‑token context can be reduced to 8 k, dropping a request cost from $0.30 to $0.05.

Break large tasks into smaller steps (e.g., refactor a single service instead of the whole module).

Switch models with --model: use cheap Sonnet for routine coding and Opus for complex architecture design.

# Compact command in terminal
/compact
# Keep recent code changes and bug discussion
/compact 保留最近的代码修改记录和当前的bug讨论

Model pricing:

Sonnet – input $3/M tokens, output $15/M tokens – suitable for daily coding, file edits, bug fixes.

Opus – input $15/M tokens, output $75/M tokens – suitable for architecture design, large‑scale refactoring.

3. Configuring MCP

MCP (Model Context Protocol) is an open protocol that lets Claude Code attach external tools (databases, APIs, browsers). It is configured in .claude/settings.json (project) or ~/.claude/settings.json (global).

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

Common pitfalls: Node.js version must be >= v18 and paths must be correct; check with node --version. The author’s typical MCP combo (PostgreSQL, Browser, Fetch) covers ~80% of backend scenarios.

4. Skill system vs MCP

One‑sentence distinction: MCP provides atomic tools, Skill defines workflows.

Analogy: MCP is a screwdriver, Skill is the IKEA instruction booklet that tells you which board to assemble first.

Skill files live in ~/.claude/skills/:

~/.claude/skills/my-skill/
├── SKILL.md      # required, defines trigger and flow
├── references/   # optional
└── templates/    # optional

Use MCP when you need a capability (e.g., query a database); use Skill when you need a multi‑step workflow (e.g., generate a technical article).

5. Permission management

Claude Code prompts for confirmation on risky actions. An allowlist (whitelist) in the settings file reduces prompts.

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(mvn test)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log:*)",
      "Read",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)"
    ]
  }
}

Three safety principles:

Only allow commands you trust (e.g., git status, mvn test).

Use glob patterns (e.g., Bash(git log:*)) to cover families of commands.

Separate global ( ~/.claude/settings.json) and project‑level ( .claude/settings.json) configurations.

Real data: a 15‑rule global allowlist reduced daily permission prompts from 30+ to 3‑5.

6. Claude Code vs Cursor / Copilot

Core difference is interaction mode.

Interaction mode : Claude Code – terminal dialogue; Cursor – IDE‑embedded dialogue; Copilot – IDE autocomplete.

Core advantage : Claude Code – OS‑level, can run commands, read/write files; Cursor – high IDE integration, WYSIWYG; Copilot – fast completion, seamless IDE embedding.

Suitable scenarios : Claude Code – large‑scale refactoring, multi‑file coordination; Cursor – single‑file editing, daily coding; Copilot – line‑level/function‑level completion.

Context capability : Claude Code – full‑project scan + external tools; Cursor – current file + editor context; Copilot – current file + cursor vicinity.

Recommendation: use Cursor (or Copilot) for everyday coding because of speed, and switch to Claude Code for heavyweight tasks that require dialogue‑driven, multi‑file reasoning.

7. Hooks

Hooks are automatic scripts triggered on specific Claude Code events.

Two practical scenarios:

After each file edit, run lint automatically.

At conversation start, load environment info (e.g., current branch and latest commit).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npm run lint -- --fix"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '当前分支:' $(git branch --show-current) '最新commit:' $(git log --oneline -1)"
          }
        ]
      }
    ]
  }
}

Hook event types and typical uses:

PreToolUse – before tool execution (input validation, permission checks).

PostToolUse – after tool execution (lint formatting, automated tests).

Notification – when Claude needs user attention (e.g., send message to Slack/Feishu).

Stop – when conversation ends (clean temporary files, generate summary).

Long‑running hooks (>3 s) can slow Claude Code; keep them fast or run asynchronously.

8. Handling long or truncated context

Claude Code’s context window is limited (e.g., 200 K tokens for Claude Sonnet 4). Four remedies:

Run /compact to compress history.

Use a .claudeignore file to exclude large files (e.g., node_modules/, dist/, *.min.js, coverage/).

Specify exact files instead of vague requests.

Start a new conversation with /clear when topics diverge.

# .claudeignore
node_modules/
Dist/
*.lock
*.min.js
coverage/

Example: adding .claudeignore reduced initial scan time from 8 s to 2 s and cut context usage by ~40%.

9. IDE integration

Claude Code supports CLI, Desktop App, Web App, and IDE plugins.

VS Code setup (most mature): install the "Claude Code" extension from the marketplace or via command line:

# Install VS Code extension
code --install-extension anthropic.claude-code

JetBrains setup: install the plugin from the Plugins marketplace and restart the IDE.

Both IDE plugins share the same .claude/settings.json configuration, so you only need to configure once.

Performance note: JetBrains plugin startup is 2‑3 s slower than VS Code, but offers richer inline suggestions.

10. Prompt engineering

Three immediate techniques:

Provide full context (file path, method name, expected vs actual behavior) instead of vague descriptions.

Break complex tasks into ordered steps rather than a single massive request.

Leverage CLAUDE.md to encode recurring preferences (e.g., comment style, async/await usage).

Advanced tip: let Claude generate an initial CLAUDE.md with a single command:

claude "分析这个项目的代码结构、技术栈和编码规范，生成一份 CLAUDE.md 文件"

Additional Q&A

Claude Code requires network connectivity; code files stay local unless data sharing is manually enabled.

Claude Pro ($20 / month) includes sufficient quota for personal development; heavy usage may benefit from API pay‑as‑you‑go.

Supported languages: all text languages, with best experience for Python, JavaScript/TypeScript, Java, Go.

Code review is possible, e.g.,

git diff main | claude "审查这些改动，指出潜在的 bug 和代码风格问题"

.

No offline mode; for offline work consider local models (Ollama + Continue) with reduced capability.