code agent 的使用

前言

永远是快hvv的时候最忙，整个45月份基本都有活，下周还有个竞赛得参加，趁着中间这空隙，学了学claude code的使用和一些设计理念

对于现阶段ai技术发展的一些思考

从个人使用体验来看，Agent 的广泛应用并非偶然，而是大模型技术发展到一定阶段后的必然结果。虽然提示词工程在 2023 年便已成为大模型应用的重要研究方向，但 Agent 系统则是在 2025 年进入公众视野。

我认为 Agent 的快速发展主要受到两方面因素的推动。
首先，基础大模型能力的持续提升为 Agent 的落地提供了技术基础。近年来，大模型的上下文窗口不断扩大，同时 API Token 成本持续下降。这使得 Agent 可以在更长的上下文中以可接受的成本完成复杂任务，从而逐渐从概念验证阶段走向实际应用阶段。
其次，大模型训练与部署的成本门槛仍然较高。对于个人开发者和中小型团队而言，自主训练或持续迭代先进基础模型所需的成本往往难以承担。相比之下，直接调用成熟商业模型的 API 服务，通常能够以更低的成本获得更先进的模型能力。

Learn Claude Code

根据项目https://github.com/shareAI-lab/learn-claude-code的内容学习编写

Claude Code 是 Anthropic 推出的官方命令行 AI 编程助手，本质是一个基于LLM的Code Agent。与Copilot这种补全式工具不同，Claude Code是一个具备自主规划和执行能力的智能体——它能理解整个项目结构，能跨文件修改代码，能执行shell命令，还能通过MCP协议扩展自己的能力边界。

Claude Code格式的api和消息体结构

理解Claude Code的消息体结构，是深入使用它的基础。Claude Code底层调用的是Anthropic的Messages API，消息体的核心结构如下：

基础消息格式：

{
    "max_tokens": 8000,
    "messages": [ //历史对话
        {
            "role": "user",//user是用户
            "content": "你在吗"
        },
        {
            "role": "assistant",//ai为assistant
            "content": [
                {
                    "signature": "ca12bf84-bb88-4be3-aef5-dbb3c59333bb",
                    "thinking": "The user just said ....",
                    "type": "thinking"
                },
                {
                    "text": "在的！有什么我可以帮你的吗？",
                    "type": "text"
                }
            ]
        },
        {
            "role": "user",
            "content": "当前是哪个目录"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "signature": "e82bb112-6b2c-4bec-81b2-ee70e4b749b9",
                    "thinking": "用户想知道当前所在的目录。",
                    "type": "thinking"
                },
                {
                    "id": "call_00_uEQlMFqLhfMpqyUK70qD1063",
                    "input": {
                        "command": "pwd"  
                    },
                    "name": "bash",
                    "type": "tool_use"//工具调用 传入参数和工具名称
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result", //用户电脑返回的工具调用结果
                    "tool_use_id": "call_00_uEQlMFqLhfMpqyUK70qD1063",
                    "content": "'pwd' 不是内部或外部命令，也不是可运行的程序\n或批处理文件。"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "signature": "621f42a1-2210-4c8c-91a6-f73faafefb7b",
                    "thinking": "Windows 环境下 pwd 不可用，使用 cd 或 echo %cd% 来获取当前目录。",
                    "type": "thinking"
                },
                {
                    "id": "call_00_e3TWSYVYHyUPqR9Hmdii0633",
                    "input": {
                        "command": "echo %cd%"
                    },
                    "name": "bash",
                    "type": "tool_use"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "call_00_e3TWSYVYHyUPqR9Hmdii0633",
                    "content": "E:\\user\\Desktop\\ai\\learn-claude-code-main"
                }
            ]
        }
    ],
    "model": "deepseek-v4-pro",
    "system": "You are a coding agent ....",
    "tools": [ //工具列表
        {
            "name": "bash",
            "description": "Run a shell command.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "command": {
                        "type": "string"
                    }
                },
                "required": [
                    "command"
                ]
            }
        }
    ]
}

System Prompt 的构成：

Claude Code的system prompt是其能力的核心，它并不是简单的一句话指令，而是由多个层次组合而成的复杂提示词系统：

1. 基础身份和行为约束：定义Claude Code是什么、能做什么、行为边界
2. 环境信息注入：当前工作目录、操作系统、Git状态、Shell类型等
3. 编码规范：代码风格约定、命名规范、注释密度要求
4. 安全策略：权限模式、危险操作确认机制
5. 用户自定义指令：CLAUDE.md文件中的项目级指令

这种分层设计的好处是：每一层职责清晰，模型能准确理解自己的角色和能力边界，同时用户可以通过CLAUDE.md灵活定制行为。

Tool Use 的消息流：

Claude Code与模型的交互遵循”思考-行动-观察”的循环模式：

User Message → Assistant (text + tool_use) → Tool Result (tool_result) → Assistant (text + tool_use) → ...

关键点：tool_result是以user角色注入到消息流中的，这意味着模型将工具返回视为”用户的输入”——这是Anthropic API设计上的一个巧妙之处，保证了对话流的连贯性。

设计理念

Claude Code的设计理念可以从架构、交互、安全三个维度来理解。

架构设计：Agentic Loop

Claude Code的核心架构是一个Agentic Loop（智能体循环）：

┌─────────────────────────────────────────────────┐
│                   Claude Code                     │
│                                                    │
│   用户输入 ──→ LLM推理 ──→ 决策（工具调用？）    │
│       ↑                        ↓                  │
│       │                    是  否                 │
│       │                    ↓    ↓                 │
│       │              执行工具  输出回复           │
│       │                    ↓                      │
│       └──── 工具结果注入 ◄──┘                     │
│                                                    │
└─────────────────────────────────────────────────┘

这个循环的核心思想来自ReAct（Reasoning + Acting）模式，即模型交替进行推理（思考下一步做什么）和行动（调用工具执行操作），行动的观察结果又会成为下一轮推理的输入。

与传统IDE插件（如Copilot）的”补全式”交互不同，Claude Code是任务导向的——你给它一个目标，它自主拆解、分步执行、验证结果、修正错误。这种设计使得Claude Code能处理”帮我重构这个模块”这种复杂任务，而不只是”帮我写完这行代码”。

工具设计：最小原语原则

Claude Code的工具集合遵循最小原语原则——每个工具只做一件原子化的事情，复杂操作由模型组合工具完成：

工具类别	具体工具	设计意图
文件读取	Read	精确读取文件内容
文件写入	Write, Edit	Write全量覆盖，Edit精确替换
代码搜索	Grep, Glob	Grep内容搜索，Glob文件名匹配
命令执行	Bash	所有shell操作的统一入口
任务编排	Agent, Workflow	子智能体分发，多智能体编排
交互控制	AskUserQuestion, EnterPlanMode	关键决策点的人类确认

为什么不多提供几个”高级”工具，比如一个”重构函数”的工具？因为这会让工具的语义变得模糊——LLM需要猜测工具的内部行为，反而降低可靠性。一个Edit工具做精确字符串替换，模型能完全预测其结果，这种确定性是可靠Agent的基础。

安全设计：权限分层与人类审核

Claude Code运行在本地终端，拥有文件读写和命令执行的权限——这在提供强大能力的同时也带来了安全风险。其安全模型分为三层：

1. 权限模式：用户在首次使用时选择权限级别，决定哪些类操作需要确认，哪些可以自动执行
2. 危险操作检测：对rm -rf、git push --force、sudo等命令进行模式匹配，触发额外确认
3. 沙箱隔离：支持在git worktree中运行子智能体，即使子智能体的操作出错也不影响主工作区

上下文管理：分层注入

Claude Code的上下文管理非常精巧。它并不是把所有信息一次性塞给模型，而是分层注入：

第一层：System Prompt（固定）
   ├── 身份定义
   ├── 工具Schema
   └── 行为规范

第二层：项目上下文（会话开始时加载一次）
   ├── CLAUDE.md（项目指令）
   ├── .claude/settings.json（项目配置）
   └── Git状态概览

第三层：即时上下文（每次对话动态注入）
   ├── 当前打开的文件列表
   ├── IDE选中的代码
   └── 用户消息

这种设计保证了模型始终拥有”足够且不过量”的上下文。过量的上下文会稀释模型的注意力（即常说的”Lost in the Middle”问题），而分层注入确保最相关的信息优先级最高。

claude code 的使用

常用指令

Claude Code的交互模型是以斜杠指令（Slash Commands）为核心的，这些指令本质上是预设好的Prompt模板，触发特定的工作流。

基础交互指令

指令	功能	使用场景
/help	显示帮助信息	查看所有可用指令
/clear	清空当前对话上下文	话题切换，避免上下文污染
/compact	压缩对话上下文	对话过长时，让模型自动总结并压缩历史
/context	显示当前上下文信息	查看模型能看到什么
/cost	显示当前会话的token消耗	成本控制
/model	切换使用的模型	在sonnet/opus/haiku之间切换
/status	显示Claude Code的状态	查看当前配置和连接状态

代码相关指令

/init # 初始化项目CLAUDE.md
/code-review # 代码审查（审查当前diff）
/review # PR审查
/security-review # 安全审查
/verify # 验证改动是否生效
/simplify # 简化/重构代码

其中/init是最常用的指令之一。它会在项目根目录创建一个CLAUDE.md文件，这个文件是Claude Code的项目级System Prompt补充。运行/init后，Claude Code会自动扫描项目结构、依赖、构建系统，生成一份结构化的项目文档：

CLAUDE.md中的内容会在每次会话开始时作为system prompt的一部分注入，确保Claude Code始终了解项目约定。

交互控制指令

/plan # 进入计划模式（先规划再执行）
/exit-plan # 退出计划模式
/config # 配置Claude Code的行为
/memory # 添加记忆
/permissions # 管理权限

计划模式（Plan Mode）是Claude Code中非常有特色的一个功能。开启后，模型在动手写代码前会先制定详细计划，包括：

• 需要修改哪些文件
• 修改的先后顺序
• 每个修改的目的和预期效果
• 可能的风险和回退方案

用户审阅并批准计划后，模型才开始执行。这种”先思后行”的交互模式，在重构、架构调整等高风险场景下特别有价值。

记忆指令（/memory）用于管理Claude Code的持久化记忆系统。通过这些指令，Claude Code可以在不同项目间积累和复用经验。

/memory add "本项目使用FastAPI框架，所有API端点需要Bearer Token认证" # 添加一条项目记忆
/memory list # 查看已保存的记忆
/memory delete <memory-id> # 删除某条记忆

记忆系统使得Claude Code能够”记住”跨会话的重要信息，比如项目的技术栈偏好、团队的编码规范、某段代码的特殊约定等。在长时间的协作中，这种持久化状态会显著提升效率——你不需要每次都解释”为什么这个函数需要异常处理”。

自动化指令

/loop 5m /test # 循环执行某个指令
/cron # 定时任务

/loop指令让Claude Code定期执行某个操作，比如每5分钟检查一次CI状态。这在需要持续监控的场景下很有用。

CLI参数

除了交互式使用，Claude Code也支持通过命令行参数进行非交互式调用：

# 单次问答模式（不进入交互循环）
claude -p "解释这段代码的作用" --file src/main.py

# 指定工作目录
claude --cwd /path/to/project

# 指定使用的模型
claude --model claude-opus-4-8

# 允许所有权限（CI/CD环境）
claude --dangerously-skip-permissions -p "运行测试并修复失败用例"

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

# 从stdin读取内容
cat error.log | claude -p "分析这个错误日志"

在CI/CD流水线中，Claude Code可以作为一个自动化代码审查员：

# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code Review
        run: |
          claude --dangerously-skip-permissions \
            -p "审查这个PR的改动，重点关注安全问题和逻辑错误"

skill

Skill是Claude Code的可插拔能力扩展机制。每个Skill是一个独立的Markdown文件，定义了特定领域的知识和操作流程。当用户的请求匹配某个Skill的触发条件时，该Skill会被自动激活并注入到System Prompt中。

Skill的本质

从实现角度看，一个Skill就是一个加在System Prompt前面的领域指令。它内部可能包含：

• 该领域的工作流程
• 常用工具和命令
• 输出格式要求
• 常见问题处理策略

这种设计非常巧妙——Skill不需要修改Claude Code的核心代码，只需要通过Prompt Engineering就能赋予模型全新的能力。它本质上是一种Prompt注入，只不过这里是我们主动、受控地注入。

Skill的工作原理

以code-review这个Skill为例，当用户输入/code-review时，系统会执行以下步骤：

1. 匹配触发条件：用户输入匹配到code-review Skill
2. 加载Skill定义：读取对应的Markdown文件，获取该Skill的System Prompt扩展
3. 注入上下文：将Skill的指令、流程、输出格式要求注入到System Prompt
4. 执行工作流：模型按照Skill定义的流程执行操作
5. 格式化输出：按照Skill约定的格式输出结果

从消息体角度来看，Skill的注入发生在system prompt层面，对于模型来说就像”换了一个更专业的身份”一样。

创建自定义Skill

Skill的强大之处在于它是完全可编程的——任何人都可以创建自己的Skill。创建一个Skill只需要一个Markdown文件：

name: my-security-audit
description: |
  针对Web应用的自动化安全审计Skill。
  触发条件：用户提到"安全审计"、"漏洞扫描"、"代码审计"等关键词。

Skill与MCP的关系

Skill和MCP是Claude Code生态中的两个核心扩展机制，但它们解决的是不同层面的问题：

维度	Skill	MCP
扩展层面	认知层（教模型”怎么想”）	能力层（给模型”能做什么”）
实现方式	Prompt注入	协议+外部服务器
加载时机	匹配触发条件时	会话启动时
提供的能力	专业知识、工作流程	外部工具、数据源

实际使用中，Skill经常会调用MCP提供的外部工具。比如一个”数据库审计”Skill可能会在流程中调用PostgreSQL MCP来直接查询数据库结构。

一个Skill可以结合MCP工具实现更强大的功能。例如，JS逆向Skill内部就会调用浏览器MCP进行动态调试：

用户请求：”分析这个网站的登录签名算法”
↓
Skill激活：hello_js_reverse_skill
↓
Skill流程：

1. Grep搜索关键JS文件
2. 识别webpack打包结构
3. 调用浏览器MCP → 在登录按钮设置断点
4. 追踪加密函数调用链
5. 还原签名算法
6. 输出Burp Suite格式的请求包

mcp

MCP（Model Context Protocol）是Anthropic推出的模型上下文协议，你可以把它理解为”AI应用的USB-C接口”——一个标准化的、用于连接LLM与外部工具和数据源的开放协议。

为什么需要MCP

在没有MCP之前，每个AI应用要对接外部工具都需要单独开发集成代码。比如：

• Claude Code要访问数据库 → 需要写一个数据库插件
• Claude Code要调用浏览器 → 需要写一个浏览器插件

每个插件都有自己的认证方式、数据格式、错误处理，维护成本极高。

MCP通过定义统一的协议解决了这个问题：

传统模式（N×M集成）：
每个AI应用 → 单独对接 → 每个外部工具

MCP模式（N+M集成）：
所有AI应用 → 统一协议(MCP) → 所有外部工具

MCP架构

MCP采用经典的客户端-服务器架构：

┌──────────────────────────────────────────┐
│              Host（宿主机）                │
│  ┌────────────────────────────────────┐  │
│  │         Claude Code（客户端）       │  │
│  │  ┌──────────────────────────────┐  │  │
│  │  │     MCP Client Protocol      │  │  │
│  │  └──────────────────────────────┘  │  │
│  └────────────────────────────────────┘  │
│              │              │              │
│         JSON-RPC        JSON-RPC          │
│              │              │              │
│  ┌───────────┴──┐  ┌─────┴───────────┐  │
│  │ MCP Server A │  │ MCP Server B    │  │
│  │ (文件系统)    │  │ (数据库)         │  │
│  └──────────────┘  └─────────────────┘  │
└──────────────────────────────────────────┘

• Host：运行Claude Code的宿主环境（终端/IDE）
• Client：Claude Code内部的MCP客户端实现，负责管理与Server的连接
• Server：独立的进程，实现MCP协议，提供特定能力（文件操作、数据库查询、API调用等）

MCP协议核心概念

1. 传输层

MCP支持两种传输方式：

传输方式	适用场景	特点
stdio	本地进程通信	低延迟，适合本地工具
HTTP + SSE	远程服务	支持跨网络，适合云端服务

stdio模式下，Claude Code直接启动MCP Server作为子进程，通过标准输入输出进行通信：

// 配置文件 .claude/settings.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

2. 资源（Resources）

资源是MCP Server暴露的可读取的数据，类似于REST API的GET端点：

// 客户端请求列出可用资源
{
  "jsonrpc": "2.0",
  "method": "resources/list",
  "id": 1
}

// 服务端响应
{
  "jsonrpc": "2.0",
  "result": {
    "resources": [
      {
        "uri": "file:///project/src/main.py",
        "name": "main.py",
        "mimeType": "text/x-python",
        "description": "应用入口文件"
      },
      {
        "uri": "postgres://localhost/mydb/schema/users",
        "name": "users表结构",
        "mimeType": "application/json"
      }
    ]
  },
  "id": 1
}

3. 工具（Tools）

工具是MCP Server暴露的可执行的操作，类似于REST API的POST端点。这是MCP最核心的能力——让LLM能够调用外部世界的功能：

// 客户端调用工具
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      "query": "SELECT * FROM users WHERE created_at > '2024-01-01'"
    }
  },
  "id": 2
}

// 服务端返回工具执行结果
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\": 1, \"name\": \"Alice\"}, {\"id\": 2, \"name\": \"Bob\"}]"
      }
    ]
  },
  "id": 2
}

4. 提示模板（Prompts）

MCP Server可以提供预定义的提示模板，帮助用户更高效地与模型交互：

// 列出可用提示
{
  "jsonrpc": "2.0",
  "method": "prompts/list",
  "id": 3
}

// 服务端返回
{
  "jsonrpc": "2.0",
  "result": {
    "prompts": [
      {
        "name": "code_review",
        "description": "对当前选中的代码进行审查",
        "arguments": [
          {
            "name": "language",
            "description": "代码语言",
            "required": true
          }
        ]
      }
    ]
  },
  "id": 3
}

MCP在Claude Code中的运行机制

当配置了MCP Server后，Claude Code会在启动时执行以下流程：

1. 连接建立：按照配置启动MCP Server进程或连接远程地址
2. 能力发现：通过initialize握手获取Server支持的能力（工具列表、资源列表等）
3. 工具注册：将MCP Server提供的工具动态注册到模型的可用工具列表中
4. 运行时调用：当模型决定调用MCP工具时，通过JSON-RPC转发给Server执行

从模型视角看，MCP工具和内置工具（Read、Write等）在Schema层面是完全一样的——模型不需要知道一个工具是”内置的”还是”外部MCP提供的”。这种透明性是MCP协议设计的一大亮点。

实战：配置IDA Pro MCP

配置方式：

在.claude/settings.json中添加：

{
  "mcpServers": {
    "ida-pro-mcp": {
      "command": "python",
      "args": ["-m", "ida_pro_mcp.server"],
      "env": {
        "IDA_HOST": "localhost",
        "IDA_PORT": "1337"
      }
    }
  }
}

连接成功后，Claude Code的工具列表就会多出一系列IDA相关的工具：

工具名	功能
decompile_function	反编译指定地址的函数
disassemble_function	获取函数的汇编代码
get_xrefs_to	获取交叉引用
list_functions	列出所有函数
list_strings	列出所有字符串
rename_function	重命名函数
set_comment	设置注释
get_global_variable_value_by_name	读取全局变量值

这些工具让Claude Code成为二进逆向的得力助手。比如分析一个恶意样本时：

用户：分析这个样本中0x401000处的函数

Claude Code执行过程：
1. decompile_function("0x401000") → 获取伪代码
2. get_callees("0x401000") → 查看它调用了哪些函数
3. get_xrefs_to("0x401000") → 查看哪些地方调用了这个函数
4. list_strings_filter({filter: "http"}) → 搜索网络相关字符串
5. 综合分析 → 判断这是一个C2通信函数
6. 自动给关键位置添加注释

MCP的权限控制

MCP Server本质上拥有执行外部代码的能力，因此安全边界需要仔细考量：

1. Server级别的权限：在配置文件中声明Server允许访问的资源范围
2. 工具级别的确认：对敏感MCP工具（如数据库写入）可以设置需要用户确认
3. 网络隔离：远程MCP Server应部署在可信网络中

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
      "permission": {
        "tools": {
          "execute_sql": "ask"  // 每次执行SQL都询问用户
        }
      }
    }
  }
}