Agent 深度实战指南

一、理解 Agent 的本质

Agent 不是聊天，是自主执行

普通对话：
  你：写一个排序函数
  AI：给你代码
  你：改一下
  AI：改好了
  （每一步都需要你驱动）

Agent 模式：
  你：给项目添加完整的用户认证系统
  AI：[自主规划] → [读代码] → [写代码] → [跑测试] → [修 bug] → [再跑测试]
  （AI 自己驱动整个流程）

Agent 的核心能力

1. 规划 — 把大任务拆成小步骤
2. 执行 — 逐步调用工具完成任务
3. 验证 — 检查执行结果是否正确
4. 纠错 — 发现问题后自动修复
5. 循环 — 重复以上步骤直到完成

Agent vs 普通对话

二、Claude Code 中的 Agent 使用

子 Agent（Agent 工具）

Claude Code 可以启动子 Agent 来处理特定任务：

主 Agent（Claude Code 本体）
    │
    ├── 子 Agent 1：搜索代码
    ├── 子 Agent 2：分析依赖
    └── 子 Agent 3：执行测试

什么时候用子 Agent

✅ 适合用子 Agent：
- 跨多个文件的搜索任务
- 需要并行处理的独立任务
- 复杂的探索性分析
- 避免污染主对话上下文

❌ 不适合用子 Agent：
- 单文件修改（直接 Edit）
- 简单命令执行（直接 Bash）
- 需要你逐步确认的操作

子 Agent 类型

# Explore — 快速搜索
"找到项目中所有用了 deprecated API 的地方"
# Agent 会并行搜索多个文件，结果汇总返回

# General Purpose — 复杂任务
"分析 src/ 下所有模块的依赖关系，画出依赖图"
# Agent 会读取多个文件，分析后输出结果

# Plan — 方案设计
"设计一个消息队列系统的架构方案"
# Agent 会分析需求，给出多个方案对比

实战：用子 Agent 做代码探索

# 场景：接手一个陌生项目
"帮我理解这个项目的架构：
1. 找到所有入口文件
2. 分析模块间的依赖关系
3. 找到核心业务逻辑在哪里
4. 画出数据流向图"

# Claude 会启动子 Agent：
# - Agent 1：搜索 package.json、tsconfig.json 等配置
# - Agent 2：搜索所有 import/require 语句
# - Agent 3：分析 src/ 目录结构
# 汇总后给你完整的项目地图

实战：用子 Agent 做并行任务

# 场景：同时处理多个独立任务
"同时做以下三件事：
1. 检查 src/api/ 的安全漏洞
2. 分析 src/services/ 的性能瓶颈
3. 找出 src/utils/ 中可以删除的死代码"

# Claude 会启动 3 个子 Agent 并行处理
# 每个 Agent 独立完成自己的任务
# 最后汇总结果

三、Claude Code Headless 模式

非交互式执行

# 直接执行任务
claude -p "检查项目中有没有 TypeScript 类型错误"

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

# 输出 JSON
claude -p "列出所有 TODO 注释" --output-format json

集成到脚本

#!/bin/bash
# 自动化代码审查脚本

# 获取 PR diff
DIFF=$(git diff main...HEAD)

# 用 Claude 审查
REVIEW=$(echo "$DIFF" | claude -p "审查这个代码改动，指出潜在问题")

# 输出结果
echo "$REVIEW"

# 如果有问题，退出码非零
if echo "$REVIEW" | grep -q "🔴"; then
  exit 1
fi

CI/CD 集成

# GitHub Actions
- name: AI Code Review
  run: |
    DIFF=$(git diff origin/main...HEAD)
    REVIEW=$(echo "$DIFF" | claude -p "审查代码改动")
    echo "$REVIEW" >> $GITHUB_STEP_SUMMARY

四、Agent 工作流模式

模式一：TDD Agent 工作流

"用 TDD 方式实现用户注册功能：

第一步：写测试
- 为注册接口写完整的测试用例
- 覆盖正常、边界、异常场景
- Mock 数据库调用

第二步：确认测试
- 运行测试，确认全部失败（因为还没实现）
- 给我看测试覆盖了哪些场景

第三步：实现代码
- 实现注册接口使所有测试通过
- 不要修改测试

第四步：验证
- 运行测试确认全部通过
- 检查代码覆盖率"

模式二：重构 Agent 工作流

"重构 src/services/ 目录：

第一步：分析现状
- 列出所有文件和函数
- 分析依赖关系
- 找出重复代码
- 识别代码异味

第二步：制定方案
- 给出重构方案
- 说明每步改什么
- 分析风险点

第三步：确认方案
- 等我确认后再执行

第四步：分步执行
- 每次只改一个文件
- 改完跑测试
- 测试通过再改下一个

第五步：验证
- 运行完整测试套件
- 确认没有引入新问题"

模式三：Bug 修复 Agent 工作流

"修复用户反馈的登录问题：

第一步：复现
- 读取相关代码
- 分析可能的原因
- 列出排查步骤

第二步：定位
- 读取日志
- 分析数据流
- 找到根因

第三步：修复
- 实现修复
- 写回归测试

第四步：验证
- 运行测试
- 确认修复有效"

模式四：新功能 Agent 工作流

"实现文章搜索功能：

第一步：需求分析
- 理解搜索需求
- 确定搜索范围（标题、内容、标签）
- 确定排序规则

第二步：技术方案
- 分析技术选型（数据库全文搜索 vs Elasticsearch）
- 给出方案对比
- 等我确认

第三步：实现
- 数据库层：添加搜索查询
- 服务层：实现搜索逻辑
- API 层：添加搜索接口
- 测试：写单元测试和集成测试

第四步：验证
- 运行测试
- 性能测试
- 代码审查"

五、开发自定义 Agent

用 Claude API 构建 Agent

import anthropic
import json

client = anthropic.Anthropic()

class CodingAgent:
    def __init__(self):
        self.tools = [
            {
                "name": "read_file",
                "description": "读取文件内容",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "path": {"type": "string"}
                    },
                    "required": ["path"]
                }
            },
            {
                "name": "write_file",
                "description": "写入文件",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "path": {"type": "string"},
                        "content": {"type": "string"}
                    },
                    "required": ["path", "content"]
                }
            },
            {
                "name": "run_command",
                "description": "执行 shell 命令",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "command": {"type": "string"}
                    },
                    "required": ["command"]
                }
            }
        ]

    def read_file(self, path):
        with open(path, 'r') as f:
            return f.read()

    def write_file(self, path, content):
        with open(path, 'w') as f:
            f.write(content)
        return f"Written to {path}"

    def run_command(self, command):
        import subprocess
        result = subprocess.run(
            command, shell=True, capture_output=True, text=True
        )
        return result.stdout + result.stderr

    def execute_tool(self, name, input_data):
        if name == "read_file":
            return self.read_file(input_data["path"])
        elif name == "write_file":
            return self.write_file(input_data["path"], input_data["content"])
        elif name == "run_command":
            return self.run_command(input_data["command"])

    def run(self, task):
        messages = [{"role": "user", "content": task}]

        while True:
            response = client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=4096,
                tools=self.tools,
                messages=messages
            )

            # 检查是否有工具调用
            if response.stop_reason == "tool_use":
                # 执行所有工具调用
                tool_results = []
                for block in response.content:
                    if block.type == "tool_use":
                        result = self.execute_tool(block.name, block.input)
                        tool_results.append({
                            "type": "tool_result",
                            "tool_use_id": block.id,
                            "content": result
                        })

                # 添加到消息历史
                messages.append({"role": "assistant", "content": response.content})
                messages.append({"role": "user", "content": tool_results})
            else:
                # 没有工具调用，返回结果
                return response.content[0].text

# 使用
agent = CodingAgent()
result = agent.run("给项目添加一个健康检查接口 /api/health")
print(result)

带规划能力的 Agent

class PlanningAgent(CodingAgent):
    def plan(self, task):
        """先规划，再执行"""
        planning_prompt = f"""
        任务：{task}

        请制定一个详细的执行计划：
        1. 列出所有需要执行的步骤
        2. 每个步骤的具体操作
        3. 步骤之间的依赖关系
        4. 预期的输出

        输出 JSON 格式：
        {{
            "steps": [
                {{
                    "id": 1,
                    "description": "步骤描述",
                    "action": "具体操作",
                    "depends_on": []
                }}
            ]
        }}
        """

        plan_text = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=2048,
            messages=[{"role": "user", "content": planning_prompt}]
        ).content[0].text

        return json.loads(plan_text)

    def execute_plan(self, task):
        """规划并执行"""
        plan = self.plan(task)
        results = []

        for step in plan["steps"]:
            print(f"执行步骤 {step['id']}: {step['description']}")
            result = self.run(step["action"])
            results.append({
                "step": step["id"],
                "result": result
            })

        return results

带验证能力的 Agent

class ValidatingAgent(CodingAgent):
    def validate(self, task, result):
        """验证执行结果"""
        validation_prompt = f"""
        原始任务：{task}

        执行结果：{result}

        请验证：
        1. 任务是否完成？
        2. 结果是否正确？
        3. 有没有遗漏？
        4. 有没有引入新问题？

        输出：
        - PASS: 任务完成且正确
        - FAIL: 有问题，需要修复
        - 附带具体问题描述
        """

        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            messages=[{"role": "user", "content": validation_prompt}]
        ).content[0].text

        return response

    def run_with_validation(self, task, max_retries=3):
        """执行并验证，失败自动重试"""
        for attempt in range(max_retries):
            result = self.run(task)
            validation = self.validate(task, result)

            if "PASS" in validation:
                return result
            else:
                print(f"验证失败（第 {attempt + 1} 次）: {validation}")
                # 把验证反馈加入下一轮的上下文
                task = f"{task}\n\n上次尝试的问题：{validation}"

        return f"经过 {max_retries} 次尝试仍未通过验证"

六、Agent 开发框架

Anthropic Agent SDK

注意：以下为概念示例，展示 Agent SDK 的 API 模式。实际包名和 API 请参考 Anthropic 官方文档。Claude Agent SDK 的具体包名和用法以官方最新版本为准。

pip install anthropic-agent-sdk  # 示例包名，请以官方文档为准

from anthropic_agent import Agent, Tool

# 定义工具
@Tool
def search_code(query: str) -> str:
    """搜索代码"""
    import subprocess
    result = subprocess.run(
        ["grep", "-r", query, "src/"],
        capture_output=True, text=True
    )
    return result.stdout

@Tool
def run_tests() -> str:
    """运行测试"""
    import subprocess
    result = subprocess.run(
        ["npm", "test"],
        capture_output=True, text=True
    )
    return result.stdout

# 创建 Agent
agent = Agent(
    model="claude-sonnet-4-6",
    tools=[search_code, run_tests],
    system_prompt="你是一个高级软件工程师，擅长代码开发和测试。"
)

# 运行
result = agent.run("给 src/services/user.ts 添加单元测试")
print(result)

多 Agent 协作

from anthropic_agent import Agent, Tool

# Agent 1：代码分析
analyst = Agent(
    model="claude-sonnet-4-6",
    name="analyst",
    system_prompt="你是代码分析专家，负责分析代码结构和问题。"
)

# Agent 2：代码实现
developer = Agent(
    model="claude-sonnet-4-6",
    name="developer",
    system_prompt="你是高级开发者，负责编写高质量代码。"
)

# Agent 3：代码审查
reviewer = Agent(
    model="claude-sonnet-4-6",
    name="reviewer",
    system_prompt="你是代码审查专家，负责发现代码中的问题。"
)

# 协作流程
def collaborate(task):
    # 1. 分析
    analysis = analyst.run(f"分析这个任务：{task}")
    print(f"分析结果：{analysis}")

    # 2. 实现
    code = developer.run(f"根据分析结果实现：{analysis}")
    print(f"实现代码：{code}")

    # 3. 审查
    review = reviewer.run(f"审查这段代码：{code}")
    print(f"审查结果：{review}")

    # 4. 如果有问题，修复
    if "问题" in review.lower():
        fixed = developer.run(f"根据审查意见修复：{review}")
        return fixed

    return code

result = collaborate("实现用户注册接口")

七、Agent 最佳实践

1. 明确任务边界

# 差：任务太模糊
"帮我改进这个项目"

# 好：任务明确
"重构 src/services/ 目录，提取公共函数到 utils.ts，
消除重复代码，保持外部 API 不变"

2. 提供足够上下文

# 差：没有上下文
"写一个 API 接口"

# 好：上下文完整
"写一个用户注册接口：
- 框架：Express.js + TypeScript
- 数据库：PostgreSQL + Prisma
- 参考：src/services/userService.ts 的代码风格
- 验证：用 zod
- 错误处理：用 AppError 类"

3. 设置检查点

"实现用户管理模块，每完成一个步骤都让我确认：
1. 数据模型设计 → 确认
2. CRUD 接口实现 → 确认
3. 测试编写 → 确认
4. 代码审查 → 确认"

4. 限制执行范围

"重构 src/utils/helpers.ts
限制：
- 只改这个文件
- 不改变任何函数签名
- 不引入新依赖
- 每次只改一个函数"

5. 要求验证

"实现这个功能后：
1. 运行所有测试
2. 检查 TypeScript 类型
3. 运行 lint
4. 给出代码覆盖率报告"

八、Agent 的局限性

Agent 不擅长的事

1. 业务决策
   - 该用什么数据库？
   - 该设计什么 API？
   → 这些需要人类判断

2. 创新方案
   - 如何解决一个从未见过的问题？
   → Agent 倾向于用已知方案

3. 性能优化的"最后一公里"
   - 从 100ms 优化到 10ms
   → 需要人类的性能直觉

4. 复杂的并发问题
   - 竞态条件、死锁
   → Agent 容易遗漏

5. 安全审计
   - 发现 0-day 漏洞
   → Agent 只能检查已知模式

什么时候不该用 Agent

1. 简单修改
   - 改个变量名
   → 直接 Edit 更快

2. 需要逐步确认的操作
   - 生产环境部署
   → 每一步都需要你确认

3. 探索性学习
   - 理解一个新框架
   → 需要你自己动手

4. 调试复杂 bug
   - 需要人类直觉
   → Agent 可能误导你

九、Agent 的未来趋势

当前（2026）

- Claude Code 内置子 Agent
- 简单的任务委派
- 基本的并行处理

近期（2026-2027）

- 更强的规划能力
- 多 Agent 协作
- 自我学习和改进
- 更好的错误恢复

远期（2028+）

- 完全自主的开发 Agent
- 团队级 Agent 协作
- Agent 之间的知识共享
- 持续学习和进化

十、实战案例

案例一：自动化代码审查 Agent

class CodeReviewAgent:
    def __init__(self):
        self.client = anthropic.Anthropic()

    def review_pr(self, pr_diff):
        """审查 PR"""
        prompt = f"""
        审查以下代码改动：

        {pr_diff}

        检查维度：
        1. 安全漏洞
        2. 性能问题
        3. 代码风格
        4. 边界条件
        5. 错误处理

        输出格式：
        - 文件：行号
        - 问题描述
        - 严重程度：高/中/低
        - 修复建议
        """

        response = self.client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            messages=[{"role": "user", "content": prompt}]
        )

        return response.content[0].text

    def auto_fix(self, review_result):
        """根据审查结果自动修复"""
        # 实现自动修复逻辑
        pass

案例二：自动化测试 Agent

class TestingAgent:
    def generate_tests(self, code_file):
        """为代码生成测试"""
        prompt = f"""
        为以下代码生成完整的单元测试：

        {code_file}

        要求：
        1. 使用项目已有的测试框架
        2. 覆盖所有公开方法
        3. 包含正常、边界、异常场景
        4. Mock 外部依赖
        """

        response = self.client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            messages=[{"role": "user", "content": prompt}]
        )

        return response.content[0].text

    def fix_failing_tests(self, test_output):
        """修复失败的测试"""
        prompt = f"""
        以下测试失败了：

        {test_output}

        分析失败原因并修复。
        """

        response = self.client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            messages=[{"role": "user", "content": prompt}]
        )

        return response.content[0].text

案例三：文档生成 Agent

class DocumentationAgent:
    def generate_docs(self, codebase):
        """为代码库生成文档"""
        # 1. 分析代码结构
        structure = self.analyze_structure(codebase)

        # 2. 为每个模块生成文档
        docs = {}
        for module in structure["modules"]:
            docs[module] = self.generate_module_docs(module)

        # 3. 生成整体文档
        overview = self.generate_overview(structure, docs)

        return {
            "overview": overview,
            "modules": docs
        }

    def analyze_structure(self, codebase):
        """分析代码结构"""
        # 实现分析逻辑
        pass

    def generate_module_docs(self, module):
        """为模块生成文档"""
        # 实现文档生成逻辑
        pass

    def generate_overview(self, structure, docs):
        """生成整体概述"""
        # 实现概述生成逻辑
        pass

十一、实战常见问题与处理

问题：Agent 陷入死循环

症状：Agent 反复执行同一个操作，不停修改同一个文件

原因：
1. 测试一直失败，Agent 反复尝试修复
2. 验证条件不明确，Agent 不知道什么时候停
3. 任务本身有矛盾（要求 A 同时要求非 A）

# 解决：
# 1. 设置明确的退出条件
"实现这个功能，如果测试失败超过 3 次就停下来告诉我问题在哪"

# 2. 限制执行范围
"最多改 5 个文件，如果需要改更多就先停下来"

# 3. 要求检查点
"每完成一步就告诉我进度，不要一口气做完"

# 4. 紧急中断
# 在 Claude Code 中按 Ctrl+C 中断
# 或者输入 "停！不要继续了"

问题：Agent 做了破坏性修改

症状：Agent 不仅改了目标文件，还顺手改了其他文件，引入了新 bug

原因：
1. 任务描述太宽泛
2. Agent "自作主张"优化了关联代码
3. 没有明确的边界约束

# 解决：
# 1. 事前：明确边界
"只修改 src/services/auth.ts，不要动其他文件"

# 2. 事前：用否定约束
"不要重构，不要优化，不要改函数签名，只修 bug"

# 3. 事后：用 git diff 检查
"看看除了 auth.ts 还改了什么文件"

# 4. 事后：回滚不需要的改动
"把 auth.ts 以外的所有改动都撤销"

问题：Headless 模式超时

症状：claude -p "做某件事" 执行很久后超时

原因：
1. 任务太复杂
2. 读取了太多文件
3. 模型响应慢

# 解决：
# 1. 简化任务
# 差：
claude -p "重构整个 src/ 目录"
# 好：
claude -p "重构 src/utils/helpers.ts 中的 string 相关函数"

# 2. 给更多上下文减少探索
# 差：
claude -p "修复登录 bug"
# 好：
claude -p "src/services/auth.ts 第 45 行的 login 函数，
当密码错误时没有返回正确的错误码，修复它"

# 3. 用 --max-turns 限制执行轮数
claude -p "实现用户注册接口" --max-turns 10

问题：子 Agent 返回结果不准确

症状：子 Agent 搜索的结果有遗漏或不相关

原因：
1. 搜索关键词不精确
2. 代码库命名不规范
3. 子 Agent 的上下文有限

# 解决：
# 1. 给更精确的搜索指令
# 差："找到所有 API 接口"
# 好："找到 src/app/api/ 下所有 export async function 的路由文件"

# 2. 分多步搜索
"先搜索所有 router.get 和 router.post 的使用"
"再搜索 @app.get 和 @app.post 的使用"

# 3. 验证结果
"你找到的这些文件中，有哪些是真正处理用户认证的？"

问题：Agent 执行测试时数据库报错

症状：Agent 写完代码后跑测试，数据库连接失败

原因：
1. 测试数据库没有启动
2. 测试环境的数据库配置不对
3. Agent 不知道测试数据库的连接方式

# 解决：
# 在 CLAUDE.md 中写清楚测试环境
# "测试数据库：postgresql://test:test@localhost:5432/testdb"
# "测试前确保数据库已启动：docker-compose up -d db"
# "测试命令：npm run test（会自动创建和销毁测试数据）"

# 或者在对话中告诉 Agent
"测试前先检查数据库是否可达，如果连不上就先启动 docker"

问题：多 Agent 并行时互相干扰

症状：同时启动多个 Agent，它们改了同一个文件

原因：
1. 任务划分不清晰
2. 有共享资源

# 解决：
# 1. 确保任务完全独立
# 差："同时改 auth 和 user 模块"（可能有依赖）
# 好："同时检查 auth 模块的安全性和 user 模块的性能"（只读，不冲突）

# 2. 让 Agent 只分析，不修改
"分析这三个模块的问题，但不要改代码，最后汇总给我"

# 3. 如果需要并行修改，确保文件不重叠
"Agent 1 只改 src/api/，Agent 2 只改 src/services/"