claude-code-guide（Claude 代码指南）

Claude Code Guide

Comprehensive reference for Claude Code, Anthropic's official CLI tool for AI-assisted development.

When to Use This Skill

• Learning Claude Code features
• Configuring Claude Code settings
• Understanding keyboard shortcuts
• Setting up MCP servers
• Creating custom sub-agents
• Troubleshooting issues
• Optimizing workflows

Installation

macOS/Linux

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

Windows

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

Verify Installation

claude --version

Authentication

API Key Setup

# Set API key
export ANTHROPIC_API_KEY="your-key"

# Or via CLI
claude auth login

Check Auth Status

claude auth status

Basic Commands

Keyboard Shortcuts

Navigation

Editing

Special

Slash Commands

Configuration

Config File Location

~/.claude/settings.json

Settings Options

{
  "model": "claude-sonnet-4-20250514",
  "theme": "dark",
  "editor": "vscode",
  "autoSave": true,
  "permissions": {
    "allowFileWrite": true,
    "allowBash": true,
    "allowNetwork": true
  }
}

Project Settings

Create .claude/settings.json in project root:

{
  "systemPrompt": "You are helping with a Node.js project...",
  "allowedPaths": ["src/", "tests/"],
  "blockedPaths": ["node_modules/", ".env"]
}

MCP (Model Context Protocol)

What is MCP?

MCP allows Claude to interact with external tools and services through standardized servers.

MCP Configuration

// ~/.claude/mcp.json
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/home/user/projects"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Available MCP Servers

• @anthropic-ai/mcp-server-filesystem - File operations
• @anthropic-ai/mcp-server-github - GitHub integration
• @anthropic-ai/mcp-server-postgres - Database queries
• @anthropic-ai/mcp-server-puppeteer - Browser automation

Sub-Agents

Creating Custom Agents

Create in ~/.claude/agents/:

---
name: code-reviewer
description: Reviews code for best practices
model: claude-sonnet-4-20250514
---

# Code Review Agent

You are a senior code reviewer. When reviewing code:

1. Check for security issues
2. Verify error handling
3. Assess readability
4. Suggest improvements

Be constructive and educational in feedback.

Using Agents

# List agents
claude agents list

# Use specific agent
claude --agent code-reviewer

Skills

Installing Skills

# From marketplace
claude skills install skill-name

# From GitHub
claude skills install github:user/repo

Skill Location

~/.claude/skills/skill-name/SKILL.md

Creating Skills

See skill-creator skill.

Hooks

Pre/Post Hooks

// .claude/hooks.json
{
  "preCommand": ["echo 'Starting...'"],
  "postCommand": ["echo 'Done!'"],
  "preFileWrite": ["backup.sh"],
  "postFileWrite": ["format.sh"]
}

Permissions

Permission Levels

• ask - Prompt for each action
• allow - Allow without prompting
• deny - Block action

Configure Permissions

{
  "permissions": {
    "file:write": "ask",
    "bash:execute": "ask",
    "network:fetch": "allow"
  }
}

Performance Tips

1. Use .claudeignore: Exclude large directories
2. Project Context: Set in .claude/ folder
3. Compact Mode: For faster responses
4. Specific Prompts: Be precise in requests
5. File References: Use @filename syntax

Troubleshooting

Common Issues

"Command not found"

# Reinstall
npm install -g @anthropic-ai/claude-code
# Check PATH
echo $PATH

"Authentication failed"

# Re-authenticate
claude auth logout
claude auth login

"Rate limited"

• Wait and retry
• Check API usage dashboard
• Consider upgrading plan

Debug Mode

claude --debug

Logs Location

~/.claude/logs/

Best Practices

1. Clear Context: Start fresh for unrelated tasks
2. Incremental Requests: Break large tasks
3. Review Changes: Always review file modifications
4. Use Git: Commit before major operations
5. Custom Instructions: Set project-specific prompts

Resources

• Official Docs
• GitHub Issues
• Community Discord

Credits

Guide created by zebbern. Licensed under MIT.