第 40 章

CLAUDE.md 系统：三层配置 / Auto Memory / 路径规则的完整设计

第四十章：Claude Code 核心工作流：文件编辑、bash 执行与项目导航

40.1 Claude Code 的工具系统

Claude Code 内置了一套核心工具，这些工具使其能够真正操作代码库而不仅仅是提供建议。理解这些工具的工作方式，是高效使用 Claude Code 的关键。

40.1.1 内置工具清单

工具	功能	典型调用场景
`Read`	读取文件内容	分析代码、理解配置
`Write`	覆盖写入文件	创建新文件
`Edit`	精确修改文件中的特定内容	修复 bug、重构代码
`MultiEdit`	在单次操作中对文件进行多处修改	大规模重构
`Bash`	执行 bash 命令	运行测试、git 操作、编译
`Glob`	基于模式匹配查找文件	定位特定类型的文件
`Grep`	在文件内容中搜索	查找变量使用、函数引用
`LS`	列出目录内容	了解项目结构
`TodoWrite`	维护任务列表	追踪多步骤任务的进度
`Agent`	启动子 Agent	委托独立的子任务

40.1.2 工具调用的透明性

Claude Code 默认显示所有工具调用，让你清楚地看到 AI 正在做什么：

● Reading file: src/api/auth.py
● Searching: "def validate_token" in src/
● Bash: pytest tests/test_auth.py -v
● Editing: src/api/auth.py (lines 45-67)

可以通过 /verbose 命令切换显示详细程度。

40.2 文件编辑工作流

40.2.1 Read + Edit 精确修改模式

Claude Code 最常用的编辑模式是"先读取，再精确修改"——这比直接覆盖整个文件安全得多，因为 Edit 工具需要精确匹配要修改的内容：

用户请求：

"在 src/utils/validators.py 的 validate_email 函数中，
添加对 .edu.cn 域名的支持"

Claude Code 的执行流程：

Step 1: Read
  ● Reading: src/utils/validators.py
  
  # 读取到的内容（片段）：
  def validate_email(email: str) -> bool:
      pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
      return bool(re.match(pattern, email))

Step 2: Edit
  ● Editing: src/utils/validators.py
  
  # 修改内容：
  old: r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
  new: r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.(?:[a-zA-Z]{2,}|[a-zA-Z]{2,3}\.[a-zA-Z]{2})$'

Step 3: Bash（可选）
  ● Running: pytest tests/test_validators.py -v

40.2.2 Write 工具：创建新文件

当需要创建全新文件时，使用 Write 工具：

用户请求：

"为 User 模型创建 FastAPI 路由文件，包含 CRUD 端点"

Claude Code 执行：

Step 1: Read（了解现有代码结构）
  ● Reading: src/models/user.py
  ● Reading: src/api/posts.py（参考现有路由的写法）

Step 2: Write
  ● Writing: src/api/users.py
  
  # 创建内容：
  from fastapi import APIRouter, Depends, HTTPException, status
  from sqlalchemy.orm import Session
  from app.core.database import get_db
  from app.models.user import User
  from app.schemas.user import UserCreate, UserUpdate, UserResponse
  
  router = APIRouter(prefix="/users", tags=["users"])
  
  @router.get("/", response_model=list[UserResponse])
  async def list_users(
      skip: int = 0,
      limit: int = 100,
      db: Session = Depends(get_db)
  ):
      return db.query(User).offset(skip).limit(limit).all()
  
  # ... 其他 CRUD 端点

Step 3: Edit（将新路由注册到主 app）
  ● Editing: src/main.py
  
  # 添加：
  from app.api.users import router as users_router
  app.include_router(users_router)

40.2.3 MultiEdit：批量修改

当需要在同一文件中进行多处修改时，MultiEdit 比多次 Edit 更高效（一次性展示所有变更）：

用户：「将 database.py 中的所有 print 语句替换为 logger.debug 调用」

Claude Code 使用 MultiEdit，一次提交所有替换：
- print("Connecting...") → logger.debug("Connecting...")
- print(f"Query: {sql}") → logger.debug(f"Query: {sql}")
- print("Connection closed") → logger.debug("Connection closed")

40.2.4 大文件处理策略

对于超大文件（超过模型上下文窗口的文件），Claude Code 采用分块处理策略：

用户：「重构这个 3000 行的 legacy_processor.py，
      拆分成符合单一职责原则的多个模块」

Claude Code 的策略：
1. 先读取文件头部（了解模块级结构）
2. 用 Grep 搜索所有类定义和主要函数
3. 分块读取各个功能区域
4. 制定拆分方案（用 TodoWrite 追踪进度）
5. 逐步创建新文件并修改原文件

40.3 Bash 执行工作流

40.3.1 Bash 工具的能力与限制

Claude Code 的 Bash 工具在一个沙箱化的环境中执行命令：

可以执行的操作：

运行测试套件（pytest、npm test、go test 等）
执行 git 命令（status、diff、add、commit、push）
编译构建（make、cargo build、npm run build 等）
包管理（pip install、npm install）
文件系统操作（ls、cp、mv、mkdir 等）

默认需要确认的操作：

删除文件（rm）
系统级修改（sudo）
网络请求（curl、wget）
数据库修改操作

40.3.2 测试驱动的开发循环

Claude Code 最强大的工作流之一是测试驱动的自动修复循环：

用户请求：

"运行测试套件，找到所有失败的测试，逐一修复，直到所有测试通过"

Claude Code 的执行流程：

Step 1: Bash
  ● Running: pytest tests/ -v --tb=short
  
  输出：
  FAILED tests/test_auth.py::test_login_invalid_password - AssertionError
  FAILED tests/test_user.py::test_create_user_duplicate_email - IntegrityError
  
  2 failed, 45 passed

Step 2: 分析第一个失败
  ● Reading: tests/test_auth.py（查看测试代码）
  ● Reading: src/api/auth.py（查看被测代码）
  
  分析：test_login_invalid_password 期望返回 401，但代码返回 400

Step 3: Edit
  ● Editing: src/api/auth.py
  # 修改：将 raise HTTPException(status_code=400) 改为 status_code=401

Step 4: Bash（验证修复）
  ● Running: pytest tests/test_auth.py::test_login_invalid_password -v
  
  输出：PASSED ✓

Step 5: 分析第二个失败
  [重复上述流程...]

Step 6: 最终验证
  ● Running: pytest tests/ -v
  
  输出：47 passed ✓

40.3.3 Git 工作流自动化

Claude Code 可以完整地管理 git 工作流：

用户：「创建一个新分支，实现用户头像上传功能，
      完成后提交并推送」

Claude Code 的执行流程：

Step 1: Bash - 创建分支
  ● Running: git checkout -b feat/user-avatar-upload
  
Step 2: Read（了解现有用户相关代码）
  ● Reading: src/models/user.py
  ● Reading: src/api/users.py

Step 3: Write（创建文件上传处理模块）
  ● Writing: src/services/file_upload.py
  
Step 4: Edit（更新用户模型添加 avatar_url 字段）
  ● Editing: src/models/user.py

Step 5: Edit（添加头像上传 API 端点）
  ● Editing: src/api/users.py

Step 6: Bash - 生成数据库迁移
  ● Running: alembic revision --autogenerate -m "add avatar_url to users"

Step 7: Bash - 运行测试确认无回归
  ● Running: pytest tests/ -x

Step 8: Bash - 提交并推送
  ● Running: git add src/ migrations/
  ● Running: git commit -m "feat(users): add avatar upload functionality"
  ● Running: git push origin feat/user-avatar-upload
  
输出：
  Branch pushed to remote.
  Create PR: https://github.com/org/repo/compare/feat/user-avatar-upload

40.3.4 长时间运行的任务

对于耗时较长的操作（如大型测试套件、构建过程），Claude Code 会：

显示命令开始执行
实时显示输出（如果有进度信息）
在完成后分析输出并决定下一步

# 对于可能超时的操作，Claude Code 会提示
"这个构建过程可能需要几分钟。我会在后台执行，完成后分析结果。"

# 用户可以通过 Ctrl+C 中断等待，Claude Code 会询问下一步

40.4 项目导航工作流

40.4.1 Glob 文件发现

Glob 工具使用模式匹配定位文件，是项目导航的基础：

用户：「找到所有使用了 deprecated_function 的文件，
      并将其替换为 new_function」

Step 1: Grep（定位所有引用）
  ● Searching: "deprecated_function" in **/*.py
  
  Found in:
  - src/utils/processor.py (line 23, 45)
  - src/api/legacy.py (line 12)
  - tests/test_processor.py (line 7, 34)

Step 2: Read（了解每个文件的上下文）
  [分别读取三个文件]

Step 3: Edit（逐文件替换）
  ● Editing: src/utils/processor.py (2 occurrences)
  ● Editing: src/api/legacy.py (1 occurrence)
  ● Editing: tests/test_processor.py (2 occurrences)

Step 4: Bash（运行测试验证）
  ● Running: pytest tests/ -v

40.4.2 代码库理解模式

当接手一个新的代码库时，利用 Claude Code 快速建立理解：

用户：「帮我理解这个项目的架构」

Claude Code 的探索流程：

1. 读取 CLAUDE.md 或 README.md（如果存在）
2. 查看顶层目录结构（LS）
3. 读取核心配置文件（package.json/pyproject.toml/Cargo.toml）
4. 识别入口文件（main.py/index.ts/main.go）
5. 读取入口文件
6. 读取主要的路由/控制器文件
7. 查看数据库 schema（如果是 web 应用）
8. 生成架构图（文本格式）

输出示例：
「这个项目是一个基于 FastAPI 的 RESTful API 服务，采用以下架构：

┌──────────────────────────────────────┐
│ FastAPI Application (src/main.py)    │
│                                      │
│  ┌─────────────────────────────┐     │
│  │ API Layer (src/api/)        │     │
│  │ - auth.py    - users.py     │     │
│  │ - posts.py   - comments.py  │     │
│  └──────────┬──────────────────┘     │
│             │                        │
│  ┌──────────▼──────────────────┐     │
│  │ Service Layer (src/services/)│    │
│  └──────────┬──────────────────┘     │
│             │                        │
│  ┌──────────▼──────────────────┐     │
│  │ Data Layer (src/models/)    │     │
│  └─────────────────────────────┘     │
└──────────────────────────────────────┘

数据库：PostgreSQL（通过 SQLAlchemy ORM）
认证：JWT（Bearer Token）
主要依赖：FastAPI 0.100+, Pydantic v2, SQLAlchemy 2.0

40.4.3 Grep 高级搜索

Grep 工具支持正则表达式，可以进行复杂的代码搜索：

# 查找所有没有 type hint 的 Python 函数
Claude Code 内部执行：
grep -rn "^def [a-zA-Z_]+(" src/ --include="*.py"
# 然后过滤出没有类型注解的函数

# 查找所有 TODO/FIXME 注释
grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.py"

# 查找循环导入的可疑位置
grep -rn "^from \." src/ --include="*.py"

40.5 任务追踪：TodoWrite 工具

TodoWrite 是 Claude Code 内置的任务列表工具，用于追踪多步骤任务的进度。当任务包含多个子任务时，Claude Code 会自动创建并维护一个 TODO 列表。

40.5.1 自动任务规划

用户：「将整个项目从 Python 3.9 迁移到 Python 3.11，
      利用新特性重构代码」

Claude Code 使用 TodoWrite 规划：

TODO 列表：
□ 1. 更新 pyproject.toml 中的 Python 版本要求
□ 2. 运行兼容性检查（pip-audit, python-requires）
□ 3. 将 Union[X, Y] 类型注解替换为 X | Y 语法
□ 4. 将 Optional[X] 替换为 X | None
□ 5. 替换 TypedDict 为原生 dataclass（适用处）
□ 6. 利用 match-case 替换复杂 if-elif 链
□ 7. 运行完整测试套件确认无回归
□ 8. 更新 CI/CD 配置中的 Python 版本
□ 9. 更新 Dockerfile 基础镜像
□ 10. 更新项目文档

开始执行...

✓ 1. 更新 pyproject.toml 中的 Python 版本要求
✓ 2. 运行兼容性检查
◎ 3. 将 Union[X, Y] 类型注解替换为 X | Y 语法（进行中）

40.5.2 进度恢复

如果会话中断，可以让 Claude Code 恢复进度：

用户：「继续上次的迁移任务」

Claude Code 读取 TodoWrite 状态：
「根据任务列表，我们已完成前两步。
  继续从第三步开始：将 Union[X, Y] 替换为 X | Y...」

40.6 子 Agent 模式

对于超大规模任务，Claude Code 可以启动子 Agent 并行处理：

用户：「为代码库中所有公共 API 函数生成完整文档字符串」

Claude Code 使用 Agent 工具：

Master Plan:
1. 用 Glob 列出所有 Python 文件（共 47 个）
2. 将文件分成 4 组，启动 4 个子 Agent 并行处理
3. 子 Agent 1: api/ 目录（12 个文件）
4. 子 Agent 2: services/ 目录（10 个文件）
5. 子 Agent 3: models/ 目录（8 个文件）
6. 子 Agent 4: utils/ 目录（17 个文件）
7. 收集所有子 Agent 的结果
8. 主 Agent 审查并统一文档风格

40.7 典型高效工作流示例

40.7.1 Bug 修复工作流

# 用户报告了一个 bug
用户：「用户无法重置密码，错误信息是 'Token has expired' 但 token 刚生成」

Claude Code 的诊断流程：

# 1. 搜索相关代码
Grep: "Token has expired" in src/
Found: src/utils/tokens.py line 45

# 2. 读取 token 生成和验证代码
Read: src/utils/tokens.py
Read: src/api/auth.py

# 3. 发现问题：token 过期时间使用了 UTC 而验证使用本地时间
Edit: src/utils/tokens.py
  old: expires_at = datetime.now() + timedelta(hours=1)
  new: expires_at = datetime.utcnow() + timedelta(hours=1)

# 4. 检查是否有类似问题
Grep: "datetime.now()" in src/
Found: 3 more occurrences

# 5. 修复所有相同问题
[修复其余 3 处]

# 6. 添加测试
Write: tests/test_token_timezone.py

# 7. 运行测试验证
Bash: pytest tests/test_token_timezone.py tests/test_auth.py -v

40.7.2 代码审查工作流

用户：「审查我今天写的代码变更」

Claude Code 执行：

# 1. 查看今日更改
Bash: git diff HEAD~3..HEAD --name-only

# 2. 逐文件读取并分析
[读取所有变更文件]

# 3. 运行测试
Bash: pytest tests/ -v --tb=short

# 4. 检查代码质量
Bash: flake8 src/ --max-line-length=100
Bash: mypy src/ --strict

# 5. 生成审查报告
「代码审查报告：

## 总体评估：良好，有几个需要关注的点

## 潜在问题
1. [严重] src/api/users.py 第 45 行：SQL 查询未参数化，
   存在 SQL 注入风险
   建议：使用 ORM 或参数化查询

2. [警告] src/services/email.py 第 23 行：
   邮件发送失败未记录错误，会导致问题难以追踪
   建议：添加 logger.error() 记录异常

3. [建议] src/models/user.py：
   User.created_at 字段缺少默认值
   建议：添加 server_default=func.now()

## 测试覆盖
- 新增代码覆盖率：78%（建议 > 80%）
- 缺少对邮件发送失败的测试用例」

40.7.3 功能开发完整工作流

用户：「实现一个 API 限流功能，每个用户每分钟最多 60 次请求」

Claude Code 的完整实现流程：

Step 1: 调研现有架构
  Read: src/main.py（了解中间件结构）
  Read: src/core/config.py（了解配置模式）
  Bash: pip list | grep redis（确认 Redis 可用）

Step 2: 规划实现（TodoWrite）
  TODO:
  □ 创建 RateLimiter 服务类
  □ 添加 Redis 连接配置
  □ 创建限流中间件
  □ 在主应用中注册中间件
  □ 添加限流相关的配置项
  □ 编写单元测试
  □ 编写文档

Step 3: 实现
  Write: src/services/rate_limiter.py
  Edit: src/core/config.py（添加 RATE_LIMIT_* 配置）
  Write: src/middleware/rate_limit.py
  Edit: src/main.py（注册中间件）
  Write: tests/test_rate_limiter.py

Step 4: 验证
  Bash: pytest tests/test_rate_limiter.py -v
  Bash: uvicorn app.main:app --reload &
  Bash: for i in $(seq 1 65); do curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8000/api/test; done
  # 应该前60次返回200，之后返回429

Step 5: 提交
  Bash: git add src/ tests/
  Bash: git commit -m "feat(api): implement per-user rate limiting (60 req/min)"

40.8 Claude Code 使用最佳实践

40.8.1 提供充分上下文

Claude Code 效果的好坏，很大程度上取决于上下文的质量：

低效提示：

"修复 bug"

高效提示：

"用户登录后，访问 /api/profile 接口返回 403 错误。
错误日志显示：'User 42 does not have permission to view profile'
但该用户确实存在于数据库中。
请分析 src/api/users.py 中的 get_profile 端点和 
src/middleware/auth.py 中的权限检查逻辑"

40.8.2 迭代式任务分解

对于大型任务，分步提交效果更好：

# 不推荐：一次性要求完整实现
"实现完整的用户认证系统，包括注册、登录、密码重置、
邮箱验证、OAuth、JWT刷新"

# 推荐：分阶段实现
Step 1: "实现基础的邮箱密码注册和登录"
Step 2: "在现有认证基础上添加 JWT 刷新令牌"
Step 3: "添加邮箱验证流程"
Step 4: "集成 Google OAuth"

40.8.3 利用 CLAUDE.md 减少重复说明

每次会话都需要说明"使用 Black 格式化"是低效的。一次性写入 CLAUDE.md，之后无需重复：

# CLAUDE.md
## 代码规范
- Python：Black 格式化，isort 排序导入，类型注解必填
- 函数长度：不超过50行；文件长度：不超过300行
- 测试：每个新函数需要至少一个单元测试

40.8.4 用 /cost 监控开销

Claude Code 的每次操作都会消耗 API token，对于长任务，定期检查开销：

/cost

输出：
Current session usage:
  Input tokens:  45,234
  Output tokens: 12,891
  Total cost:    $1.23 (approximate)
  Model:         claude-sonnet-4-5

40.8.5 利用 --print 模式进行脚本化

Claude Code 支持非交互式的 --print 模式，可以在 CI/CD 或脚本中调用：

# 非交互式代码审查
claude --print "审查 src/api/ 目录下所有 Python 文件的安全性" 2>&1

# 自动生成 commit message
COMMIT_MSG=$(claude --print "根据 git diff 生成一行 commit message")
git commit -m "$COMMIT_MSG"

# 在 CI 中集成代码质量检查
claude --print "分析测试失败原因并给出修复建议" < test_output.txt

小结

本章深入介绍了 Claude Code 的核心工作流：文件编辑（Read/Write/Edit/MultiEdit）、bash 执行（测试循环、git 自动化）和项目导航（Glob/Grep/LS）。这三类工具的组合构成了 Claude Code 作为 AI Agent 的基础能力。

关键要点：

Edit 工具通过精确字符串匹配修改文件，比 Write（完全覆盖）更安全
测试驱动的自动修复循环（运行测试→分析失败→修复→重跑）是最高效的工作流之一
TodoWrite 工具帮助追踪多步骤任务，支持会话中断后恢复
高质量的 CLAUDE.md 能显著减少每次会话中的重复说明
提供充分上下文（具体错误信息、相关文件路径）是提升 Claude Code 效果的最重要因素

这两章关于 Claude Code 的内容为后续更深入的实战使用打下了基础——从基础安装配置，到掌握核心工具，再到建立高效的工作流模式，Claude Code 的全部潜力正在逐步展开。

本章评分

4.5 / 5 (3 评分)

CLAUDE.md 系统：三层配置 / Auto Memory / 路径规则的完整设计

第四十章：Claude Code 核心工作流：文件编辑、bash 执行与项目导航

40.1 Claude Code 的工具系统

40.1.1 内置工具清单

40.1.2 工具调用的透明性

40.2 文件编辑工作流

40.2.1 Read + Edit 精确修改模式

40.2.2 Write 工具：创建新文件

40.2.3 MultiEdit：批量修改

40.2.4 大文件处理策略

40.3 Bash 执行工作流

40.3.1 Bash 工具的能力与限制

40.3.2 测试驱动的开发循环

40.3.3 Git 工作流自动化

40.3.4 长时间运行的任务

40.4 项目导航工作流

40.4.1 Glob 文件发现

40.4.2 代码库理解模式

40.4.3 Grep 高级搜索

40.5 任务追踪：TodoWrite 工具

40.5.1 自动任务规划

40.5.2 进度恢复

40.6 子 Agent 模式

40.7 典型高效工作流示例

40.7.1 Bug 修复工作流

40.7.2 代码审查工作流

40.7.3 功能开发完整工作流

40.8 Claude Code 使用最佳实践

40.8.1 提供充分上下文

40.8.2 迭代式任务分解

40.8.3 利用 CLAUDE.md 减少重复说明

40.8.4 用 /cost 监控开销

40.8.5 利用 --print 模式进行脚本化

小结

💬 留言讨论