跳转到内容
Claude Code 使用教程

深入内部机制

本教程揭示 Claude Code 的内部工作原理。理解这些机制可以帮助你更有效地使用它，并在遇到问题时更好地诊断。

主循环

Section titled “主循环”

Claude Code 的核心是一个简单的 while 循环：

┌─────────────────────────────────────────────────────────────┐
│                    主循环（简化版）                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   你的提示                                                   │
│       │                                                     │
│       ▼                                                     │
│   ┌────────────────────────────────────────────────────┐    │
│   │   Claude 推理（无分类器，无路由器）                   │    │
│   └───────────────────────┬────────────────────────────┘    │
│                           │                                 │
│              需要工具？    │                                 │
│                     ┌─────┴─────┐                           │
│                    是          否                            │
│                     │           │                           │
│                     ▼           ▼                           │
│              执行工具     文本回复（完成）                    │
│                     │                                       │
│                     └──────── 将结果反馈给 Claude            │
│                                        │                    │
│                               （循环继续）                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

工具库

Section titled “工具库”

Claude Code 拥有 8 个核心工具：

工具用途
Bash执行 shell 命令（通用适配器）
Read读取文件内容（最多 2000 行）
Edit修改现有文件（基于 diff）
Write创建/覆盖文件
Grep搜索文件内容（基于 ripgrep）
Glob按模式查找文件
Task派生子 Agent（隔离上下文）
TodoWrite跟踪进度（旧版，见下文）

任务管理系统

Section titled “任务管理系统”

Claude Code 提供两种任务管理方式：

推荐方案 — 持久化、跨会话、支持依赖

特性说明
持久化磁盘存储（~/.claude/tasks/）
多会话跨会话存活
依赖关系任务 A 阻塞任务 B
协调多 Agent 广播
状态pending / in_progress / completed / failed

可用工具：

  • TaskCreate — 创建带层级和依赖的新任务
  • TaskUpdate — 修改任务状态、元数据和依赖
  • TaskGet — 获取单个任务详情
  • TaskList — 列出当前任务列表中的所有任务

配置任务持久化

Section titled “配置任务持久化”
Terminal window
# 启用多会话任务持久化
export CLAUDE_CODE_TASK_LIST_ID="project-name"
claude


# 示例：项目特定的任务列表
export CLAUDE_CODE_TASK_LIST_ID="api-v2-auth-refactor"
claude

任务 Schema 示例

Section titled “任务 Schema 示例”
{
  "id": "task-auth-login",
  "title": "实现登录端点",
  "description": "POST /auth/login 带 JWT token 生成",
  "status": "in_progress",
  "dependencies": [],
  "metadata": {
    "priority": "high",
    "estimated_duration": "2h",
    "related_files": ["src/auth/login.ts", "src/middleware/auth.ts"]
  }
}

何时使用 Tasks API

Section titled “何时使用 Tasks API”

跨多个编码会话的项目

任务状态在会话之间自动保留

复杂任务层级和依赖

任务 A 完成后才能开始任务 B

多 Agent 协调场景

多个 Claude 实例共享任务状态

上下文压缩后恢复工作

任务状态不受 /compact 或 /clear 影响

Tasks API 限制

Section titled “Tasks API 限制”

解决方案

Section titled “解决方案”
  • 使用 Tasks API 进行状态跟踪和依赖协调
  • 使用仓库中的 markdown 文件保存详细实施计划
  • 示例：docs/plans/auth-refactor.md + Tasks 用于状态

任务层级设计

Section titled “任务层级设计”
项目（父级）
└── 功能 A（子级）
    ├── 组件 A1（叶子任务）
    │   ├── 实现
    │   └── 测试（依赖于实现）
    └── 组件 A2

最佳实践

Section titled “最佳实践”
  1. 创建任务时始终定义依赖关系
  2. 使用任务 ID（而非标题）作为依赖引用
  3. 执行前用 TaskGet 验证依赖
  4. 开始工作时标记 in_progress（防止并行执行）
  5. 频繁更新状态以保持可见性
  6. 只有完全完成时才标记 completed（测试通过、已验证）
  7. 对失败的任务使用 failed 状态并附加错误元数据

元数据约定

Section titled “元数据约定”
{
  "priority": "high|medium|low",
  "estimated_duration": "2h",
  "related_files": ["path/to/file.ts"],
  "related_issue": "https://github.com/org/repo/issues/123",
  "type": "feature|bugfix|refactor|test"
}

任务列表作为诊断工具

Section titled “任务列表作为诊断工具”

当 Claude 的任务列表与你的意图不匹配时，问题不在 Claude — 在于你的指令。

任务列表是指令清晰度的镜子：

你的指令："重构认证系统"


Claude 的任务列表：
- [ ] 读取所有认证相关文件
- [ ] 识别代码重复
- [ ] 提取共享工具
- [ ] 更新导入
- [ ] 运行测试


你的反应："这不是我的意思 — 我想从 session 切换到 JWT"


诊断：你的指令有歧义。"重构" 不等于 "替换"。

偏差类型及含义

Section titled “偏差类型及含义”
偏差类型含义修复
任务太宽泛指令缺乏具体性添加什么、在哪里、如何做、如何验证
任务太窄指令过于详细，缺少全局视角陈述目标，而非仅列步骤
优先级错误缺少关于什么重要的上下文添加约束和优先级
缺少任务隐含知识未共享在提示中明确假设
多余任务Claude 推断了你未意图的需求添加明确的范围边界