核心能力一览

系统要求

安装步骤

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# 首次运行 (会引导 OAuth 登录)
claude

配置文件

Claude Code 的配置存储在 ~/.claude.json 中，包含全局设置和项目级设置。

// 主要配置项分类 (源自 utils/config.ts)

// UX 设置
theme: string           // 主题
verbose: boolean        // 详细输出
editorMode: string      // 编辑器模式
autoCompactEnabled: boolean  // 自动压缩历史

// 权限设置
bypassPermissionsModeAccepted: boolean
allowedTools: string[]  // 允许的工具列表

// MCP 服务器
mcpServers: Record<string, McpServerConfig>

// 模型偏好
// 通过 --model 或 /model 命令设置

环境变量

启动方式

# 交互式 REPL (最常用)
claude

# 带初始提示启动
claude "帮我分析这个项目的架构"

# 非交互模式 (输出结果后退出)
claude -p "解释 src/main.ts 的作用"

# 指定模型
claude --model opus

# 限制最大轮次
claude --max-turns 10

# 管道输入
cat error.log | claude -p "分析这个错误日志"

# 恢复上次会话
claude --resume

交互式 REPL 界面

常用操作示例

❯ 解释 src/utils/auth.ts 中的
  认证流程

❯ 这个函数有 bug，用户输入为空
  时会崩溃，帮我修复

❯ 将 UserService 类重构为使用
  依赖注入模式

❯ 为 calculateTotal 函数编写
  单元测试

❯ 将当前修改提交，写一个有意义
  的 commit message

❯ 创建一个 React + Vite 项目，
  配置好 Tailwind CSS

在 REPL 中输入 / 即可触发

Claude Code 的 30+ 内置工具

Claude 会根据你的需求自动选择合适的工具。你不需要手动指定，但了解这些工具有助于更高效地与 Claude 协作。

文件操作工具

搜索工具

// Claude 会这样使用:
Grep: pattern="function auth"
      type="ts" path="src/"

// Claude 会这样使用:
Glob: pattern="**/*.test.ts"

执行与交互工具

可用模型与别名

模型选择优先级：/model 会话设置 → --model 启动参数 → ANTHROPIC_MODEL 环境变量 → 配置文件 → 默认值

思考力度 (Effort)

通过 /effort 命令或 CLAUDE_CODE_EFFORT_LEVEL 环境变量控制 Claude 的思考深度。

# 使用环境变量设置
export CLAUDE_CODE_EFFORT_LEVEL=high
claude

# 或在会话中切换
/effort high

五种权限模式

在 REPL 中按 Shift+Tab 切换权限模式。

工具级权限控制

# 通过 /permissions 命令管理
/permissions

# 允许特定工具
# 例如: 总是允许 Bash 执行 npm test
# 工具名: BashTool  规则: npm test

# 拒绝特定 MCP 工具
# 工具名: mcp__server__dangerous_tool

文件层级与加载顺序

加载优先级 (从低到高):

1. ~/.claude/CLAUDE.md          # 全局用户级记忆
2. 项目根/CLAUDE.md             # 项目级记忆 (提交到 Git)
3. 项目根/.claude/CLAUDE.md     # 项目级 (隐藏目录)
4. 项目根/.claude/rules/*.md    # 规则文件 (可多个)
5. 项目根/CLAUDE.local.md       # 本地记忆 (不提交到 Git)

CLAUDE.md 示例

# 项目: My API Service

## 技术栈
- Node.js + TypeScript
- Express.js
- PostgreSQL + Prisma ORM
- Jest 测试框架

## 构建命令
- 安装依赖: `npm install`
- 开发服务器: `npm run dev`
- 运行测试: `npm test`
- 构建生产版: `npm run build`
- 数据库迁移: `npx prisma migrate dev`

## 编码规范
- 使用 2 空格缩进
- 变量命名使用 camelCase
- 文件命名使用 kebab-case
- 所有函数必须有 TypeScript 类型注解
- 每个模块必须有对应的测试文件

## 项目结构
- src/routes/     — API 路由
- src/services/   — 业务逻辑
- src/models/     — 数据模型
- src/middleware/  — 中间件
- src/utils/      — 工具函数

## 注意事项
- 不要修改 src/generated/ 下的文件
- PR 必须通过所有测试才能合并
- 敏感配置使用环境变量，不要硬编码

管理记忆文件

# 初始化 CLAUDE.md (交互式引导)
/init

# 编辑记忆文件
/memory

# 在对话中让 Claude 更新记忆
❯ 把刚才约定的编码规范写入 CLAUDE.md

什么是 MCP？

Model Context Protocol (MCP) 是 Anthropic 推出的开放标准，允许 AI 连接外部工具和数据源。通过 MCP，Claude Code 可以访问数据库、API、自定义工具等。

添加 MCP 服务器

# 通过斜杠命令添加
/mcp

# 通过 CLI 参数添加 (stdio 类型)
claude mcp add my-server -- node /path/to/server.js

# 添加 SSE 类型服务器
claude mcp add my-api --transport sse \
  --url https://api.example.com/mcp

# 查看已配置的服务器
claude mcp list

# 移除服务器
claude mcp remove my-server

三种传输方式

claude mcp add db-tool \
  -- node db-mcp-server.js

claude mcp add remote \
  --transport sse \
  --url https://mcp.example.com

claude mcp add api \
  --transport http \
  --url https://api.example.com/mcp

MCP 工具命名规则

MCP 服务器的工具在 Claude Code 中以特殊前缀命名：

格式: mcp__<服务器名>__<工具名>

示例: mcp__database__query
      mcp__github__create_issue
      mcp__slack__send_message

这种命名方式便于权限管控 —— 你可以拒绝整个服务器的所有工具：

拒绝规则: mcp__untrusted_server  → 屏蔽该服务器全部工具

高效使用心法

常用工作流

# 工作流 1: 代码审查
claude -p "审查最近的 git diff，指出问题"

# 工作流 2: 从头搭建项目
claude "创建一个 Python FastAPI 项目，包含用户认证和数据库"

# 工作流 3: 调试问题
npm test 2>&1 | claude -p "分析测试失败原因并修复"

# 工作流 4: 文档生成
claude "为 src/api/ 下的所有路由生成 OpenAPI 文档"

# 工作流 5: 数据库迁移
claude "我需要给 User 表添加 avatar_url 字段，
  生成 Prisma 迁移"

方法 1：--dangerously-skip-permissions 标志

启动时加上此标志，跳过所有权限确认，自动允许所有操作（写文件、执行命令、删除等）。

# 交互式 REPL，跳过所有权限确认
claude --dangerously-skip-permissions

# 简写也可以
claude --dangerously-skip-permissions "重构这个模块"

方法 2：-y / --yes 标志

自动对所有确认提示回答 "Yes"，适合快速开发场景。

# 交互式模式，自动回答 yes
claude -y

# 非交互式管道模式 + 自动 yes
claude -p --yes "帮我修复这个 bug"

# 等价写法
claude -p -y "为所有函数添加类型注解"

方法 3：管道模式 (-p) 用于脚本和 CI/CD

-p 为非交互式管道模式，不会等待用户输入。搭配 --dangerously-skip-permissions 实现完全自动化。

# 最常见的 CI/CD 全自动化组合
claude -p --dangerously-skip-permissions "运行测试并修复失败的用例"

# 管道传入上下文
npm test 2>&1 | claude -p --dangerously-skip-permissions "分析并修复这些测试失败"

# 从文件读取 prompt
claude -p --dangerously-skip-permissions < prompt.txt

# 搭配 --output-format json 获取结构化输出
claude -p -y --output-format json "列出项目中的 TODO"

方法 4：配置 autoApprove 永久跳过特定工具确认

如果你不想全局跳过，可以只对特定工具设置自动批准，粒度更细。

# 设置全局自动批准的工具列表
claude config set --global autoApprove "Bash,Write,Edit"

# 查看当前配置
claude config get autoApprove

# 只批准 Bash 工具 (如 npm test, git 等命令)
claude config set --global autoApprove "Bash"

# 批准更多工具
claude config set --global autoApprove "Bash,Write,Edit,MultiEdit,NotebookEdit"

方法 5：通过 /permissions 命令配置规则

在 REPL 中使用 /permissions 添加细粒度规则，允许特定命令模式自动执行。

# 在 Claude Code REPL 中输入
/permissions

# 添加允许规则示例：
# 工具: Bash  规则: npm test        → npm test 自动执行
# 工具: Bash  规则: git *           → 所有 git 命令自动执行
# 工具: Bash  规则: npx prisma *    → prisma 命令自动执行

场景对照表

GitHub Actions 中的完整示例

# .github/workflows/claude-autofix.yml
name: Claude Auto Fix
on:
  issues:
    types: [opened]
jobs:
  autofix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Claude
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p --dangerously-skip-permissions \
            "分析 issue #${{ github.event.issue.number }} 并尝试修复"

源码来源

本教程基于通过 npm 包 @anthropic-ai/claude-code 中 cli.js.map 的 sourcesContent 还原出的 TypeScript 源码。

核心源码结构

src/
├── entrypoints/
│   ├── cli.tsx        # CLI 入口 (快速路径)
│   └── init.ts        # 初始化
├── main.tsx           # 主函数 (Commander)
├── replLauncher.tsx   # REPL 挂载
├── QueryEngine.ts     # Agent 核心循环
├── query.ts           # 底层查询
├── Tool.ts            # Tool 类型定义
├── tools.ts           # 工具注册表
└── commands.ts        # 命令注册表

src/
├── tools/             # 30+ 工具实现
│   ├── BashTool/
│   ├── FileEditTool/
│   ├── GrepTool/
│   ├── AgentTool/
│   ├── MCPTool/
│   └── ...
├── services/
│   ├── api/claude.ts  # API 调用
│   └── mcp/client.ts  # MCP 客户端
├── screens/REPL.tsx   # 主 REPL 屏幕
├── components/        # Ink UI 组件
├── state/AppState.tsx # 应用状态
└── bootstrap/state.ts # 全局状态

src/
├── coordinator/    # 多 Agent 协调
├── assistant/      # 助手模式
├── plugins/        # 插件系统
├── skills/         # 技能系统
├── voice/          # 语音交互
├── vim/            # Vim 模式
├── daemon/         # 守护进程
└── utils/
    ├── swarm/      # 蜂群协作
    ├── permissions/ # 权限
    ├── model/      # 模型选择
    └── config.ts   # 配置管理

src/constants/
├── prompts.ts         # 系统提示构建
├── systemPromptSections.ts
├── cyberRiskInstruction.js
├── outputStyles.js
├── oauth.js
└── tools.js           # 工具常量

src/types/
├── message.ts         # 消息类型
├── permissions.ts     # 权限类型
├── hooks.ts           # 钩子类型
└── tools.ts           # 工具类型

五层架构

核心设计原则

完整启动链路

async function main(): Promise<void> {
  const args = process.argv.slice(2);
  // 快速路径: --version 零模块加载
  if (args[0] === '--version') {
    console.log(`${MACRO.VERSION} (Claude Code)`);
    return;
  }
  // 特殊子命令: --daemon, --background-session...
  // 最终: 动态 import main
  const { main: cliMain } = await import('../main.js');
  await cliMain();
}

export async function main() {
  startMdmRawRead();        // 并行预取
  startKeychainPrefetch();  // 并行预取
  // Commander 参数解析
  const program = new CommanderCommand()
    .name('claude')
    .option('-p, --print', '...')
    .option('--model <model>', '...');
  await init();             // 初始化所有子系统
  // 启动 REPL 或无头模式
  await launchRepl(root, appProps, replProps);
}

export async function launchRepl(root, appProps, replProps) {
  const { App } = await import('./components/App.js');
  const { REPL } = await import('./screens/REPL.js');
  await renderAndRun(root,
    <App {...appProps}>
      <REPL {...replProps} />
    </App>
  );
}

循环流程

核心代码

export class QueryEngine {
  private mutableMessages: Message[]
  private totalUsage: NonNullableUsage

  async *submitMessage(prompt): AsyncGenerator<SDKMessage> {
    // 1. 包装权限检查
    const wrappedCanUseTool = async (tool, input) => {
      const result = await canUseTool(tool, input)
      if (result.behavior !== 'allow')
        this.permissionDenials.push({ tool_name: tool.name })
      return result
    }
    // 2. 获取系统提示 (含 CLAUDE.md 记忆)
    const systemPrompt = await fetchSystemPromptParts(...)
    // 3. 进入多轮 Agent 循环
    for await (const msg of query({
      messages: this.mutableMessages,
      systemPrompt,
      tools: filteredTools,
      model: mainLoopModel,
      maxTurns,
      canUseTool: wrappedCanUseTool,
    })) {
      yield* this.processMessage(msg)
    }
    // 4. 持久化会话
    await flushSessionStorage(...)
  }
}

系统提示的构建

系统提示由多个分段拼装而成，分为静态缓存段和动态段：

// constants/prompts.ts (简化)
async function getSystemPrompt(tools, model) {
  return [
    getSimpleIntroSection(),      // 身份介绍 + 安全指令
    getSimpleSystemSection(),     // Markdown 输出、权限模式
    getSimpleDoingTasksSection(), // 编程规范、先读后改
    getActionsSection(),          // 破坏性操作确认
    getUsingYourToolsSection(),   // 工具使用指南
    getSimpleToneAndStyleSection(), // 语气和风格
    SYSTEM_PROMPT_DYNAMIC_BOUNDARY, // ← 缓存分界线
    loadMemoryPrompt(),           // CLAUDE.md 内容
    computeSimpleEnvInfo(),       // 环境信息
    // ... MCP 指令、scratchpad 等
  ]
}

Tool 接口

export type Tool = {
  name: string
  description: string
  inputSchema: ToolInputJSONSchema
  isEnabled(): boolean
  isReadOnly(): boolean
  needsPermissions(input): boolean
  // Generator 模式: 支持进度流式报告
  call(input, context): AsyncGenerator<
    ToolCallProgress, ToolCallResult, unknown
  >
  mcpInfo?: { serverName: string; toolName: string }
}

BashTool 实现细节

// tools/BashTool/BashTool.tsx (简化)
const BashTool = buildTool({
  name: 'Bash',
  maxResultSizeChars: 30_000,
  inputSchema: {
    command: string,        // 要执行的命令
    timeout: number,        // 超时 (秒)
    description: string,    // 命令描述
    run_in_background: bool // 后台运行
  },
  isReadOnly: (input) =>
    checkReadOnlyConstraints(input.command),
  call: async function*(input, context) {
    // 流式输出 shell 执行结果
    for await (const chunk of runShellCommand(...)) {
      yield { type: 'progress', content: chunk }
    }
    // 大输出持久化到磁盘
    if (output.length > 30_000) {
      persistToDisk(output)
      return { content: '<persisted-output>...' }
    }
    return { content: output }
  }
})

FileEditTool 实现细节

// tools/FileEditTool/FileEditTool.ts (简化)
// 输入: file_path, old_string, new_string, replace_all
async function* call(input, context) {
  // 1. 必须先读取过该文件 (防止盲改)
  if (!fileWasRead(input.file_path))
    throw Error('必须先用 FileRead 读取文件')

  // 2. 陈旧性检查 (文件是否被外部修改)
  if (isStale(input.file_path))
    throw Error('文件已被外部修改，请重新读取')

  // 3. 查找 old_string
  const matches = findActualString(content, old_string)
  if (matches.length === 0) throw Error('未找到匹配')
  if (matches.length > 1 && !replace_all)
    throw Error('多处匹配，需指定 replace_all')

  // 4. 执行替换，保留原始换行和编码
  const patched = applyPatch(content, old_string, new_string)
  await writeTextContent(file_path, patched)

  // 5. 通知 LSP / IDE
  notifyLSP(file_path)
}

流式 API 调用

// services/api/claude.ts (简化)
async function* queryModel(params): AsyncGenerator<StreamEvent> {
  const client = new Anthropic()
  const stream = await client.beta.messages.create({
    model,
    max_tokens: getModelMaxOutputTokens(model),
    messages: normalizeMessagesForAPI(messages),
    system: systemPrompt,
    tools: tools.map(toolToAPISchema),
    stream: true,
    thinking: thinkingConfig,  // 扩展思考
    betas: getMergedBetas(model),
  })
  for await (const event of stream) {
    yield processStreamEvent(event)
  }
}

关键特性

MCP 客户端架构

// services/mcp/client.ts (简化)
import { Client } from '@modelcontextprotocol/sdk/client'
import { StdioClientTransport } from '...sdk/client/stdio'
import { SSEClientTransport } from '...sdk/client/sse'
import { StreamableHTTPClientTransport } from '...sdk/client/streamableHttp'

async function connectMCPServer(config) {
  const client = new Client({
    name: 'claude-code',
    version: MACRO.VERSION,
  })
  // 选择传输方式
  const transport = config.type === 'stdio'
    ? new StdioClientTransport(config)
    : config.type === 'sse'
    ? new SSEClientTransport(config.url)
    : new StreamableHTTPClientTransport(config.url)

  await client.connect(transport)
  const tools = await client.listTools()

  // MCP 工具 → 标准 Tool 对象
  return tools.map(t => MCPTool.create(client, t))
}

// 工具名: mcp__${serverName}__${toolName}

React + Ink 终端渲染

Claude Code 使用 React + Ink 构建终端 UI —— 将 React 组件渲染为 ANSI 终端输出。

<App>                      # 顶级包装器
  ├── AppStateProvider      # 状态 Context
  ├── ThemeProvider          # 主题 Context
  └── <REPL>                # 主屏幕
      ├── <MessageList>     # 消息列表
      ├── <InputArea>       # 用户输入
      ├── <Spinner>         # 加载指示
      ├── <StatusBar>       # 状态栏
      └── <PermissionDialog> # 权限对话框

双层状态

type State = {
  originalCwd: string
  projectRoot: string
  totalCostUSD: number
  sessionId: SessionId
  modelUsage: { [model]: ModelUsage }
  isInteractive: boolean
  hookMatchers: RegisteredHookMatcher[]
  // 遥测计数器...
}

// React Context 驱动
const { getAppState, setAppState } = useAppState()
// QueryEngine 通过注入访问
new QueryEngine({ getAppState, setAppState, ... })

编译时特性门控

import { feature } from 'bun:bundle'
// 编译时: feature() 返回 false → 整个分支被移除
const SleepTool = feature('KAIROS')
  ? require('./tools/SleepTool').SleepTool : null

Coordinator 模式

Swarm 后端

静态前缀 vs 动态后缀

getSystemPrompt() 的核心设计是先构造静态部分（适合 cache），再拼接动态部分（每次会话可变）：

Prompt Cache Boundary：基础设施级思维

源码中明确存在 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记，并有注释说明：边界前尽量可 cache，边界后是用户/会话特定内容，不能乱改否则会破坏缓存逻辑。

各 Prompt 模块的行为价值

完整调度链路（14 步）

Fork Path vs Normal Path

三层分工

Background vs Foreground 生命周期

runAgent() 产品化证据

runAgent.ts 不是简单 wrapper，而是子 agent 的完整 runtime constructor，包含大量产品级细节：

六大内置 Agent

Explore Agent：绝对只读

exploreAgent.ts 的 prompt 非常严格，被故意裁成 read-only specialist：

Plan Agent：架构师而非执行者

planAgent.ts 被定义成 architect / planner，降低角色混杂：

• 只读，不准改文件
• 需要先理解需求
• 需要探索代码库的模式和架构
• 输出 step-by-step implementation plan
• 最后必须列出 Critical Files for Implementation

Verification Agent：对抗性验证器

verificationAgent.ts 是本轮深挖中非常重要的发现。它的 prompt 开头就点出两类失败模式：

Prompt 强制要求的验证清单：

Agent Prompt 中的"反懒 delegation"设计

AgentTool/prompt.ts 明确教育模型如何给子 agent 写 prompt：

✅ 正确做法:
- 像对新同事 briefing 一样写 prompt
- 说明目标和原因
- 说明你已经排除了什么
- 提供足够背景让它能做判断
- 给到 file path、line、具体改动要求

❌ 错误做法 (懒 delegation):
- "基于你的发现，修复 bug"
- "根据研究结果，实现它"
- 把理解任务的工作外包给 agent

Skill：Workflow Package

Skill 不是文档，而是 prompt-native workflow package：

Plugin：Prompt + Metadata + Runtime Constraints

插件不是普通 CLI 插件，而是模型行为层面的扩展单元。能提供的能力包括：

支持的 runtime 变量:
${CLAUDE_PLUGIN_ROOT}    — 插件根目录
${CLAUDE_PLUGIN_DATA}    — 插件数据目录
${CLAUDE_SKILL_DIR}      — 技能目录
${CLAUDE_SESSION_ID}     — 当前会话 ID
${user_config.X}         — 用户配置变量

Hook：运行时治理层

Hook 不仅能"记日志"，还是 runtime policy layer，支持三个阶段拦截：

Hook 可以返回的控制指令：

MCP：工具桥 + 行为说明注入通道

MCP 的价值远高于简单 tool registry，因为它能同时注入：

此外，Agent 还可以自带 agent-specific MCP servers：

• 从配置中按名字引用现有 MCP server
• 在 frontmatter 里内联定义 agent-specific MCP server
• Agent 结束时自动 cleanup

14 步执行管线

权限语义的关键粘合层

resolveHookPermissionDecision() 定义了 Hook 与权限系统的严格关系：

Hook Decision     Settings Rule     最终结果
─────────────     ─────────────     ──────────
allow             (无 deny/ask)     → 允许
allow             deny              → 仍然拒绝 ⚠️
allow             ask               → 仍然要问
ask               *                 → 作为 forceDecision 传递
deny              *                 → 直接拒绝

11 层护城河

四个核心优势

一句话总结

Claude Code 的真正秘密，不是一段 system prompt，而是一个把 prompt architecture、tool runtime、permission model、agent orchestration、skill packaging、plugin system、hooks governance、MCP integration、context hygiene 和 product engineering 全部统一起来的系统。这就是为什么它不像一个"会调工具的聊天机器人"，而更像一个真正可扩展、可治理、可产品化的 Agent Operating System。

架构亮点

学习路线建议

关键文件速查

基于 @anthropic-ai/claude-code v2.1.88 源码还原分析 · 仅供研究学习
第三部分深挖内容参考 Xiao Tan 的《Claude Code 源码深度研究报告》
源码版权归 Anthropic 所有