第 3 章：Claude Code 的工程思想

本章导读

• 核心问题：从 Claude Code 中提炼可迁移的 Agentic Coding 工程方法。
• 关键词：Agentic Coding、Explore-Plan-Act-Verify、AGENTS.md、只读分析
• 学习产出：把研发 Agent 设计成能读取环境、调用工具、验证证据的工程系统。

1. 本章要解决什么问题

Claude Code 经常被误解成“更强的代码聊天机器人”。

但从 Anthropic 的设计思想看，Claude Code 不是一个普通 Chatbot，也不是一个简单的 IDE 插件，而是一个面向软件开发任务的 agentic coding environment。

它和传统代码助手最大的区别是：

传统代码助手：你问，它答。
Claude Code：你给目标，它读代码、执行命令、修改文件、运行验证，并根据反馈继续工作。

这意味着 Claude Code 的核心不只是“生成代码”，而是：

理解代码库
  ↓
规划修改
  ↓
编辑文件
  ↓
运行命令
  ↓
读取错误
  ↓
继续修复
  ↓
提交可验证结果

本章要回答的问题是：

• 为什么 Claude Code 更像 Runtime，而不是聊天窗口；
• Agentic Coding 的基本循环是什么；
• 为什么“先探索、再计划、再编码”非常重要；
• 为什么验证命令比代码生成更重要；
• CLAUDE.md / AGENTS.md 这类项目知识文件应该如何写；
• 如何把 Claude Code 的思想迁移到 Java / Spring Boot 企业研发 Agent 平台中。

2. 对应 Anthropic 文章

本章主要对应 Anthropic Engineering 的文章：

• Claude Code: Best practices for agentic coding

这篇文章并不是单纯介绍 Claude Code 的命令技巧，而是在展示一种新的软件开发范式：

人类不再只把模型当作“代码补全器”，而是把它放进一个可以读取、修改、执行、验证的开发环境中。

这也是本书后续设计企业研发 Agent 平台的重要参考。

3. 原文核心观点

3.1 Claude Code 是 Agentic Coding Environment

Anthropic 对 Claude Code 的定位非常明确：

Claude Code can read your files, run commands, make changes, and autonomously work through problems.

这句话背后的含义非常重要。

一个普通聊天机器人只能做：

输入文本
  ↓
输出文本

而 Claude Code 可以做：

读取文件
  ↓
搜索代码
  ↓
运行命令
  ↓
修改文件
  ↓
查看测试结果
  ↓
继续调整

这就是 Agent 与 Chatbot 的根本区别。

工程解释

Claude Code 的关键不是模型更会写代码，而是它拥有一个受控开发环境。

这个环境至少包含：

• 文件系统访问；
• Shell 命令执行；
• Git Diff 观察；
• 测试与构建命令；
• 项目知识文件；
• 权限确认机制；
• 会话上下文；
• 验证与停止条件。

这些能力组合起来，才形成了 Coding Agent。

3.2 Context Window 会很快被填满

Claude Code 最重要的约束之一是：

Context window fills up fast, and performance degrades as it fills.

编码任务尤其容易消耗上下文，因为一次任务可能包含：

• 用户需求；
• 多轮对话；
• 多个文件内容；
• 搜索结果；
• 命令输出；
• 测试日志；
• 错误堆栈；
• Git Diff；
• Agent 的计划和解释。

如果不管理这些内容，Agent 很快会陷入两个问题：

上下文太少：不知道项目真实情况。
上下文太多：重要信息被噪声淹没。

这也是为什么本书第二部分要专门讨论 Context Engineering。

工程解释

Coding Agent 不应该“尽可能多读文件”。

它应该：

按任务目标读取
按代码结构搜索
按证据链保留
按阶段压缩
按验证结果更新上下文

换句话说，Claude Code 的最佳实践，本质上是在教我们如何管理代码任务中的上下文生命周期。

3.3 先探索，再计划，再编码

Anthropic 强调：

Explore first, then plan, then code.

这条原则非常重要。

很多 Agent 编码失败，不是因为代码写错，而是因为一开始就解决了错误的问题。

错误路径通常是：

用户提出需求
  ↓
Agent 立刻修改代码
  ↓
修改方向不对
  ↓
测试失败
  ↓
继续在错误方向上修补

正确路径应该是：

用户提出需求
  ↓
Agent 先阅读相关代码
  ↓
理解现有模式
  ↓
提出修改计划
  ↓
用户确认或 Agent 自检
  ↓
再开始编码

这也是优秀工程师的工作方式。

工程解释

Coding Agent 的第一阶段应该是 Exploration，而不是 Implementation。

在企业研发 Agent 平台中，可以把编码任务拆成三个阶段：

Explore
  ↓
Plan
  ↓
Implement

每个阶段都有不同目标：

如果没有 Explore 和 Plan，Agent 很容易变成“高速犯错机器”。

3.4 让 Agent 展示证据，而不是只说成功

Anthropic 建议让 Claude 展示 evidence：

• 它运行了什么命令；
• 命令返回了什么结果；
• 哪些测试通过；
• 哪些截图或输出证明任务完成；
• 哪些文件被修改。

这非常关键。

因为在软件工程中，“我认为完成了”没有意义。

真正有意义的是：

测试输出
构建结果
Lint 结果
Git Diff
日志证据
运行截图

工程解释

企业级 Coding Agent 的最终输出不应该只是自然语言总结，而应该包含可审计证据：

{
  "status": "SUCCESS",
  "changedFiles": ["src/main/java/..."],
  "commands": [
    {
      "command": "mvn test",
      "exitCode": 0,
      "summary": "All tests passed"
    }
  ],
  "diffSummary": "Added validation for empty request body",
  "risks": ["Only unit tests were run; integration tests not executed"]
}

这类结构化结果比“已经修好了”可靠得多。

3.5 CLAUDE.md 是项目级操作手册

Anthropic 强调应该用 CLAUDE.md 管理项目知识。

这类文件适合包含：

• Claude 猜不到的 Bash 命令；
• 项目特有的代码风格；
• 测试命令和测试偏好；
• Git 工作流；
• 项目特定架构决策；
• 开发环境特殊要求；
• 常见坑点。

不适合包含：

• 模型可以通过读代码自己发现的信息；
• 标准语言规范；
• 过长 API 文档；
• 经常变化的信息；
• 文件级代码说明；
• “写干净代码”这类空泛要求。

工程解释

CLAUDE.md / AGENTS.md 本质上是项目级 Skill。

它不是普通文档，而是面向 Agent 的操作上下文。

好的 AGENTS.md 应该回答：

这个项目怎么构建？
怎么测试？
哪些命令不能乱跑？
代码风格有什么特殊约定？
哪些目录不要修改？
提交前必须做什么验证？
遇到常见错误怎么办？

它应该像代码一样维护：

• 进入 Git；
• 接受 Code Review；
• 定期精简；
• 根据 Agent 失败案例更新；
• 避免变成冗长文档。

3.6 非交互模式让 Coding Agent 进入自动化流程

Claude Code 支持非交互模式，例如在 CI、pre-commit hook 或脚本中运行。

这体现了一个重要趋势：

Coding Agent 不只是人机对话工具，也可以成为自动化工程流水线的一部分。

例如：

CI 失败
  ↓
触发 Coding Agent 分析日志
  ↓
生成失败原因报告
  ↓
必要时创建 Issue

或者：

提交前
  ↓
Agent 检查测试覆盖和风险点
  ↓
输出 Review 建议

工程解释

当 Coding Agent 进入自动化流程时，它必须具备：

• 结构化输入；
• 结构化输出；
• 超时控制；
• 权限限制；
• 可解析日志；
• 可重复执行；
• 失败降级机制。

这就从“工具使用技巧”进入了“Agent Runtime 设计”。

4. 工程视角重新解释

从工程角度看，Claude Code 的设计思想可以概括为一句话：

把 LLM 放进一个真实但受控的软件开发环境中，让它通过工具和验证循环完成任务。

这里有三个关键词。

4.1 真实环境

Agent 必须接触真实代码、真实命令、真实测试结果。

否则它只能基于猜测工作。

真实环境包括：

代码库
构建系统
测试框架
Git 历史
依赖管理
运行日志
CI 输出

4.2 受控环境

Agent 不能无限制操作。

它必须受到约束：

只允许访问当前项目
写操作需要权限
危险命令需要确认
最大迭代次数
最大执行时间
敏感文件不可读
生产环境不可直接操作

4.3 验证循环

软件开发的本质不是“写代码”，而是“通过验证证明代码满足目标”。

因此 Coding Agent 的核心循环应该是：

Plan
  ↓
Edit
  ↓
Test
  ↓
Observe
  ↓
Fix
  ↓
Retest

没有验证能力的 Coding Agent，只是代码生成器。

有验证能力的 Coding Agent，才接近真正的软件工程助手。

5. 架构图 / 流程图

5.1 Claude Code 的 Agentic Coding Loop

5.2 Coding Agent 的上下文来源

5.3 企业研发 Agent 平台中的 Coding Agent

6. Java / Spring Boot 落地方案

如果要在企业中实现一个类似 Claude Code 思想的研发 Agent，不应该从“让模型写代码”开始，而应该先设计运行时边界。

6.1 核心模块

建议至少包含：

agent-coding
  CodingAgent
  CodingTask
  CodingPlan
  CodingStep

agent-repository
  RepositoryContextProvider
  CodeSearchService
  FileSnapshotService

agent-tool
  FileReadTool
  FileWriteTool
  PatchTool
  ShellCommandTool
  GitTool

agent-verification
  VerificationRunner
  TestCommandResolver
  BuildResultParser

agent-audit
  StepRecorder
  DiffRecorder
  CommandAuditLog

6.2 CodingTask

public record CodingTask(
    String id,
    String repositoryId,
    String objective,
    String issueId,
    CodingTaskType type,
    Map<String, Object> metadata
) {}

任务类型可以包括：

public enum CodingTaskType {
    ANALYZE_FAILURE,
    IMPLEMENT_FEATURE,
    FIX_BUG,
    ADD_TEST,
    REFACTOR,
    REVIEW_CODE
}

6.3 CodingPlan

在正式改代码之前，Agent 应先形成计划：

public record CodingPlan(
    String taskId,
    List<String> relevantFiles,
    List<String> proposedChanges,
    List<String> verificationCommands,
    List<String> risks
) {}

这个计划可以展示给用户，也可以由 Harness 自动评估。

6.4 RepositoryContextProvider

public interface RepositoryContextProvider {
    RepositoryContext load(String repositoryId, CodingTask task);
}

RepositoryContext 不应该包含整个代码库，而应该包含：

public record RepositoryContext(
    String repositoryId,
    String overview,
    List<String> buildCommands,
    List<String> testCommands,
    List<ContextChunk> relevantFiles,
    List<String> codingRules
) {}

其中 overview 可以来自 README，codingRules 可以来自 AGENTS.md。

6.5 VerificationRunner

验证器是 Coding Agent 的核心。

public interface VerificationRunner {
    VerificationResult run(VerificationRequest request);
}

请求：

public record VerificationRequest(
    String repositoryId,
    List<String> commands,
    Duration timeout
) {}

结果：

public record VerificationResult(
    boolean passed,
    List<CommandResult> commands,
    String summary
) {}

其中 CommandResult 应包含：

public record CommandResult(
    String command,
    int exitCode,
    String stdoutSummary,
    String stderrSummary,
    Duration duration
) {}

注意：不要把完整 stdout / stderr 全部塞进模型上下文。应该先做摘要和错误提取。

6.6 CodingHarness

CodingHarness 负责组织完整循环：

public class CodingHarness {

    private final RepositoryContextProvider contextProvider;
    private final LlmClient llmClient;
    private final ToolExecutor toolExecutor;
    private final VerificationRunner verificationRunner;
    private final StepRecorder stepRecorder;

    public CodingResult run(CodingTask task) {
        CodingSession session = CodingSession.start(task);

        RepositoryContext repositoryContext = contextProvider.load(task.repositoryId(), task);
        session.attachContext(repositoryContext);

        while (!session.shouldStop()) {
            CodingDecision decision = llmClient.nextCodingAction(session.toContextWindow());

            if (decision.requiresTool()) {
                ToolResult result = toolExecutor.execute(decision.toolCall());
                session.record(decision, result);
                stepRecorder.record(session, decision, result);
                continue;
            }

            if (decision.requiresVerification()) {
                VerificationResult result = verificationRunner.run(decision.verificationRequest());
                session.recordVerification(result);
                continue;
            }

            if (decision.isFinal()) {
                return session.complete(decision.summary());
            }
        }

        return session.stopped("Reached stop condition");
    }
}

这个结构体现了 Claude Code 的核心思想：

不是一次生成代码，而是持续执行、验证和修复。

7. CLAUDE.md / AGENTS.md 编写建议

在企业研发 Agent 平台中，建议统一使用 AGENTS.md 作为项目级 Agent 指南。

一个好的 AGENTS.md 可以这样写：

# AGENTS.md

## Project Overview

This is a Spring Boot service for order management.

## Build Commands

- Run all tests: `./mvnw test`
- Run one test: `./mvnw -Dtest=ClassName test`
- Run checkstyle: `./mvnw checkstyle:check`

## Coding Rules

- Use constructor injection, not field injection.
- Do not introduce new dependencies without approval.
- Keep controller logic thin; business logic belongs in service classes.

## Testing Rules

- Add unit tests for service-layer changes.
- Prefer integration tests for repository changes.
- Do not use external network calls in tests.

## Safety Rules

- Do not modify database migration files unless the task explicitly asks for it.
- Do not run destructive commands.
- Ask for confirmation before changing public API contracts.

## Common Gotchas

- Order status transitions are validated in `OrderStateMachine`.
- Test data builders live under `src/test/java/.../fixtures`.

这个文件不需要长，但必须具体。

坏的写法是：

请写高质量代码。
请遵循最佳实践。
请保证没有 bug。

这些内容太空泛，对 Agent 几乎没有帮助。

好的写法应该是：

修改 service 层逻辑后，必须运行 `./mvnw -Dtest=OrderServiceTest test`。
不要直接修改 `OrderStatus` 枚举，新增状态需要同步更新 `OrderStateMachine`。

8. 与其他工具和框架对比

8.1 与传统 IDE Copilot 类工具

传统代码补全工具主要工作在局部上下文：

当前文件
当前函数
附近代码

Claude Code 这类 Agentic Coding 工具则工作在任务级上下文：

需求
代码库
命令输出
测试反馈
Git Diff
多轮执行历史

所以二者的能力边界不同。

前者适合提升编码速度，后者适合承担完整开发任务的一部分。

8.2 与 CI/CD 系统

CI/CD 系统负责确定性验证：

构建
测试
打包
部署

Coding Agent 可以消费 CI/CD 的结果，并进行分析和修复建议：

CI 失败
  ↓
Agent 读取日志
  ↓
定位原因
  ↓
建议修复
  ↓
必要时创建补丁

因此 Agent 不替代 CI，而是增强 CI。

8.3 与 LangGraph

如果用 LangGraph 表达 Coding Agent，可以把流程建成状态图：

Explore → Plan → Edit → Test → Reflect → Done

但无论使用什么框架，核心仍然是：

• 如何读取代码；
• 如何限制工具；
• 如何运行验证；
• 如何记录证据；
• 如何管理上下文。

框架解决的是编排问题，不会自动解决工程边界问题。

9. 常见误区

9.1 误区一：Coding Agent 的核心是生成代码

不是。

核心是：

理解 → 修改 → 验证 → 修复

只会生成代码但不会验证的系统，不能称为成熟 Coding Agent。

9.2 误区二：让 Agent 读越多文件越好

不是。

读太少会缺信息，读太多会污染上下文。

正确方式是：

先读项目说明
再按任务搜索
再读取关键文件
再保留必要证据

9.3 误区三：AGENTS.md 越详细越好

不是。

太长的指令文件会让关键信息被淹没。

AGENTS.md 应该短、准、可执行。

9.4 误区四：测试失败就说明 Agent 没用

不是。

测试失败是重要反馈。

真正的问题是：

Agent 能不能读取失败原因，并正确调整下一步？

如果系统没有把失败结果反馈给 Agent，那才是设计问题。

9.5 误区五：Coding Agent 可以直接在生产环境执行

绝对不应该。

Coding Agent 应该运行在受控环境中：

• 本地开发环境；
• 沙箱；
• CI 环境；
• 临时工作区；
• Git Worktree；
• 权限受限容器。

生产系统操作必须通过严格审批和审计。

10. 贯穿案例：CI 失败分析 Agent

CI 失败分析 Agent 是 Claude Code 工程思想的一个只读版本。

它暂时不修改代码，但同样遵循 agentic coding 的基本流程：

Explore：读取 CI 摘要、AGENTS.md、Git Diff
Plan：判断需要查看哪些测试和业务代码
Inspect：调用 search_code、read_file_range 等工具
Verify：检查根因假设是否有日志和代码证据
Report：输出证据化分析报告

对于 build #4312，Agent 不应该直接猜测“状态机有问题”，而应先收集证据：

• CI 日志中的失败测试和异常；
• Git Diff 中新增的 PENDING_REVIEW；
• OrderStateMachine.allowedTransitions 中缺少对应流转；
• OrderServiceTest 中触发审批流程的测试。

这与 Claude Code 的核心思想一致：不要只让模型“回答”，而是让它在真实工程环境中读取文件、调用工具、观察结果，并用证据支持结论。

第一版 CI 失败分析 Agent 保持只读，是因为企业落地时应先验证 Agent 的分析质量，再逐步开放写操作、局部测试和自动修复能力。

11. 本章小结

本章讨论了 Claude Code 的工程思想。

核心结论有六点：

1. Claude Code 不是普通 Chatbot，而是 Agentic Coding Environment。
2. Coding Agent 的能力来自真实开发环境：文件、命令、测试、Git、日志。
3. “先探索、再计划、再编码”可以避免 Agent 过早进入错误方向。
4. 验证证据比自然语言声明更重要。
5. CLAUDE.md / AGENTS.md 是项目级 Agent 操作手册，应短小、具体、可维护。
6. 企业研发 Agent 平台应把 Coding Agent 设计为受控 Runtime，而不是简单模型调用。

一句话总结本章：

Claude Code 的本质不是让模型写代码，而是把模型放进一个可读、可写、可执行、可验证的软件工程闭环中。

12. 实践任务

任务 1：为你的项目编写 AGENTS.md

请选择一个 Java / Spring Boot 项目，编写一个 AGENTS.md。

至少包含：

• 项目简介；
• 构建命令；
• 测试命令；
• 代码风格；
• 禁止事项；
• 常见坑点；
• 修改后必须运行的验证命令。

要求：

不要超过 100 行。
每条规则必须具体、可执行。
不要写空泛口号。

任务 2：设计 Coding Agent 的工具集

为企业研发 Agent 设计最小工具集：

请补充每个工具的输入、输出和错误信息。

任务 3：实现 CodingHarness 伪代码

参考本章的 CodingHarness，用 Java 写出更完整的伪代码。

要求支持：

• 最大迭代次数；
• 工具白名单；
• 验证命令；
• Step 记录；
• 失败停止；
• 最终证据输出。

任务 4：设计 CI 失败分析 Agent

设计一个只读型 Coding Agent：

输入：CI 失败日志
输出：失败原因、证据、建议修复方向
限制：不能修改代码，只能读取日志、搜索代码、查看 Git 历史

这是企业研发 Agent 平台最适合作为 MVP 的场景之一，因为它风险较低，但足以覆盖 Agentic Coding 的核心循环。