Claude Code 正在改变"AI 写代码"的含义。它不是一个编辑器插件，而是一个直接运行在终端中的自主编码 AI Agent——在一个连续的上下文里读写文件、执行命令、操作 Git。本文讲清楚它日常究竟怎么用、如何基于它的 SDK 构建应用、如何接入 CI/CD，以及——因为终端 Agent 是带着真实权限在运行——当你把这份访问权交出去时，需要守住哪些安全边界。

核心要点

  • 终端原生：Claude Code 运行在命令行中，能自主读写文件、执行 Shell 命令、操作 Git，无需 IDE。
  • SDK 可编程：TypeScript/Python SDK 与 Headless 模式让你把它嵌入任意自动化管道。
  • CI/CD 集成：官方 GitHub Action 能审查 PR、处理 Issue——在你授予的权限范围内。
  • 持久上下文：CLAUDE.md 每次会话自动加载项目约定，它会塑造输出，但不强制执行任何东西。
  • 真实权限：一个能跑你 Shell、能向仓库推送的 Agent 是一个有实权的身份——要审查它的输出，也要收窄它的访问范围。

Claude Code 是什么：终端原生的编码 Agent

Claude Code 是 Anthropic 官方推出的 Agentic Coding 工具，它以终端为载体，将大语言模型（LLM）的推理能力直接接入你的开发环境。

它的发展轨迹值得当作一个"方向"而非"规格表"来理解：从 Research Preview 起步，逐步加入持久记忆系统和可编程调用的 SDK，走向正式可用（GA），并随时间补齐了 CI/CD 集成和多 Agent 审查。具体版本号和里程碑日期变化很快，请以 Anthropic 官方 changelog 的当前状态为准，而不要迷信任何一张"截至某时"的表格。

真正重要的是架构层面的选择：**Claude Code 不嵌入 IDE，而是作为一个独立的 Agent 进程运行在终端中。**这意味着它能直接操作文件系统、执行构建命令、运行测试套件、管理 Git 分支，所有这些都在一个连续的上下文中完成。它同时也意味着——从第一条命令起——它就是带着你的文件系统和 Shell 权限在行动，这一点我们会在安全小节再回来讨论。

bash 
# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 在项目根目录启动
cd your-project
claude

启动后，Claude Code 会扫描项目结构，读取 CLAUDE.md（如果存在），并进入交互式会话，你可以用自然语言描述任务。

核心能力：终端中的自主编码

Claude Code 的核心价值在于自主性。它不是一个等待你逐行确认的补全工具，而是一个能独立完成多步骤任务、随后把结果交给你审查的 Agent。

多文件编辑与代码生成

Claude Code 能同时理解和修改多个文件。当你要求"给这个 Express 应用添加 JWT 认证中间件"时，它会：

  1. 读取现有路由和中间件结构
  2. 创建认证中间件文件
  3. 修改路由文件以引入中间件
  4. 更新 package.json 添加依赖
  5. 生成对应的单元测试
typescript 
// Claude Code 生成的 JWT 中间件
import jwt from 'jsonwebtoken';
import { Request, Response, NextFunction } from 'express';

interface AuthRequest extends Request {
  userId?: string;
}

export const authMiddleware = (req: AuthRequest, res: Response, next: NextFunction) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET!) as { userId: string };
    req.userId = decoded.userId;
    next();
  } catch {
    return res.status(401).json({ error: 'Invalid token' });
  }
};

这是一个有用的起点，同时它也提前暴露了一条值得点名的边界：这个中间件做的是认证——它证明调用者是谁——但它不做授权。它并不检查该用户是否有权操作某条具体记录。这样一段生成的中间件不是对象级访问控制；你的路由处理逻辑仍必须在每一次请求上强制执行授权。审查生成的鉴权代码时要带着这个区分，而不是假设"测试通过"就等于"安全"。

Git 操作与版本管理

Claude Code 对 Git 的理解不止于 add 和 commit。它能分析 diff、生成语义化的 commit message，并把变更拆分成多个原子 commit：

bash 
# 在 Claude Code 交互会话中
> 把我最近的改动拆分成合理的原子 commit

# Claude Code 会：
# 1. 分析 git diff 的所有变更
# 2. 按功能语义分组
# 3. 依次创建 commit，每个都附带清晰的 message

推送前请先读一遍生成的 commit——语义分组是一种需要判断力的活儿，Agent 大多数时候做得对，偶尔也会做错。

测试生成与运行

Claude Code 不仅生成代码，还能即时运行验证。它会读取你现有的测试框架配置（Jest、Vitest、pytest 等），并遵循项目的测试风格：

bash 
> 为 src/utils/validator.ts 生成单元测试，覆盖边界情况

# Claude Code 输出：
# ✓ 创建 src/utils/__tests__/validator.test.ts
# ✓ 添加了覆盖正常输入、边界值、异常处理和类型校验的测试用例
# ✓ 运行 npm test -- --testPathPattern=validator
# ✓ 全部测试通过

有一条警示适用于任何 Agent 写的测试：一套通过的测试只能证明这些测试实际断言了什么。Agent 完全可能写出"能通过、但断言了错误行为"的测试，所以要读断言本身，而不是只看那个绿色的对勾。

Claude Code 工作流：典型使用模式

在日常开发中，Claude Code 的工作流可以分为交互模式和 Headless 模式两种范式。

交互模式：对话式开发

交互模式是最常用的方式。你在终端中启动 claude，然后通过自然语言描述任务：

flowchart LR A["开发者输入需求"] --> B["Claude 分析项目上下文"] B --> C["规划执行步骤"] C --> D["读写文件 / 执行命令"] D --> E["自我验证结果"] E -->|需要修正| C E -->|完成| F["输出结果摘要供审查"]

典型的交互流程示例：

bash 
# 启动 Claude Code
$ claude

# 场景1：代码重构
> 将 src/api/ 下所有 callback 风格的异步函数重构为 async/await

# 场景2：Bug 修复
> 用户报告 /api/orders 在分页参数为 0 时返回 500，帮我定位并修复

# 场景3：代码审查
> review 上次 commit 的改动，关注安全问题和性能隐患

Headless 模式：脚本化集成

Headless 模式通过 --print（或 -p）标志启动，适合嵌入脚本和自动化管道。它处理单次请求后退出，不进入交互式会话：

bash 
# 基本用法
claude -p "分析这个项目的依赖安全性"

# 指定模型和工具权限
claude -p "Fix all ESLint errors in src/" \
  --model opus \
  --allowedTools "Bash,Read,Write" \
  --permission-mode acceptEdits

# 管道化输入
echo "Explain the authentication flow" | claude -p

# JSON 结构化输出
claude -p "List all API endpoints" --output-format json

Headless 模式的关键参数：

参数 说明 示例
--print, -p 非交互模式 claude -p "query"
--model 指定模型 --model opus
--allowedTools 允许的工具列表 --allowedTools "Bash,Read"
--permission-mode 权限模式 --permission-mode acceptEdits
--output-format 输出格式 --output-format json

--allowedTools 和 --permission-mode 不只是便利选项——它们是一次无人值守运行的访问边界。在自动化里，给任务授予它真正需要的最小工具集（能只读就只读），而不是默认放开全部。

Claude Code SDK：构建自定义 Agent 应用

Claude Code SDK（现已更名为 Claude Agent SDK）让你能以编程方式调用 Claude Code 的全部能力，构建自定义的 Agent 应用。在基于它开发之前，请先在 Anthropic 文档中确认当前的包名和接口。

安装与基础用法

bash 
# TypeScript SDK
npm install @anthropic-ai/claude-agent-sdk

# Python SDK
pip install claude-agent-sdk

TypeScript SDK 的基本用法：

typescript 
import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

const agent = new ClaudeAgent({
  model: 'opus',
  workingDirectory: './my-project',
  allowedTools: ['Read', 'Write', 'Bash'],
  permissionMode: 'acceptEdits',
});

// 单次执行
const result = await agent.run('Refactor the database layer to use connection pooling');
console.log(result.output);

// 流式输出
const stream = agent.stream('Generate a comprehensive test suite');
for await (const event of stream) {
  if (event.type === 'text') {
    process.stdout.write(event.content);
  }
}

在编程调用中，allowedTools 和 permissionMode 这两个字段就是你的强制执行点（enforcement point）。如果你的应用在服务端运行这个 Agent，请把这些设置当作安全控制来对待，而不是默认值。

子 Agent（Subagent）模式

SDK 支持通过 Markdown 文件定义子 Agent，每个子 Agent 拥有独立的角色和工具权限，非常适合构建多 Agent 协作系统：

markdown 
<!-- .claude/agents/security-reviewer.md -->
# Security Reviewer Agent

你是一个安全审查专家。你的职责是：
1. 检查代码中的安全漏洞（SQL注入、XSS、CSRF等）
2. 验证认证和授权逻辑的正确性
3. 检查敏感数据处理是否合规

## 允许的工具
- Read（只读，不修改代码）
- Bash（仅限 grep、find 等查找命令）
typescript 
// 在主 Agent 中调用子 Agent
const result = await agent.run(
  'Use the security-reviewer agent to audit the authentication module'
);

关于这种模式，有两点必须想清楚。第一，角色提示（"你是一个安全审查专家"）塑造行为，但并不约束能力——真正约束能力的是文件里的工具权限。要让一个审查子 Agent 真的只读，靠的是它 allowedTools 里的只读工具，而不只是指令里的一句话。第二，子 Agent 报告"未发现问题"是一种分析，不是放行签字；对涉及安全的改动，人工审查依然要做。关于多 Agent 系统架构，可参考我们的 AI Agent 开发实战指南。

GitHub Actions 集成：CI/CD 中的 Agent 自动化

Claude Code 的 GitHub Actions 集成将 Agent 编程从本地终端推向了 CI/CD 流水线。通过官方 anthropics/claude-code-action，Claude 可以自动审查 PR、处理 Issue、生成文档。

基础配置

yaml 
# .github/workflows/claude.yml
name: Claude Code Assistant

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, labeled]
  pull_request:
    types: [opened, synchronize]

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: "opus"

上面这个 permissions 块不是可有可无的样板——它就是"爆炸半径"。这个 workflow 能向你的仓库写入，所以只授予任务真正需要的 scope，并把 API Key 放进 GitHub 加密 Secrets，绝不内联明文。对由 fork 仓库 PR 评论触发的 workflow 要格外小心：一个不受信任的外部贡献者的输入，可能会到达一个持有写权限的 Agent 手中。

工作模式

集成支持两种核心模式。

Tag 模式（按需触发）：在 PR 或 Issue 的评论中使用 @claude 触发：

yaml 
- uses: anthropics/claude-code-action@v1
  with:
    mode: "tag"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

使用方式：

code 
@claude 这个 PR 有潜在的 N+1 查询问题，请帮我优化 UserService 中的数据库访问
@claude 为这个新增的 API 端点生成 OpenAPI 文档

Auto 模式（自动触发）：在新 PR 或 Issue 创建时自动执行分析：

yaml 
- uses: anthropics/claude-code-action@v1
  with:
    mode: "auto"
    direct_prompt: "Review this PR for security issues and performance problems"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

这样每次有新 PR 提交，Claude 都会自动进行代码审查并留下结构化评论。这与我们在 LLM 结合 CI/CD 自动化代码审查 中讨论的理念一致——但要带上同一个前提：自动化审查是一次帮你把"需要关注的地方"翻出来的首轮扫描，而不是一道能替代人工判断的关卡，尤其是面对高风险改动时。

当你授予 Agent 真实访问权限时的安全

一个能编辑文件、执行 Shell 命令、向仓库推送的终端 Agent，是带着真实权限在运行。无论 Agent 多强，有几条边界都不会移动：

  • 只授予刚好够用的权限。 用 --allowedTools（以及 SDK 的 allowedTools）界定 Agent 能做什么。只读的审查 Agent 不应拥有写权限或任意 Shell 权限。在 CI 里，把 workflow 的 permissions 收敛到最小。
  • 认证是身份，不是授权。 生成的鉴权代码——比如上面的 JWT 中间件——证明的是调用者是谁，而不是这个调用者有权操作某条具体记录。对象级和租户级的访问控制留在你的服务端，在每一次请求上强制执行。
  • CLAUDE.md 和 MEMORY.md 是约定辅助，不是控制。 它们塑造 Agent 倾向于做什么，但并不强制任何东西。CLAUDE.md 里写一句"绝不直接访问数据库"是一个有用的提示，而不是一道护栏——真正的护栏活在你的架构和权限里。
  • 测试和绿色 CI 只证明它们覆盖的东西。 Agent 能写出"通过、却断言了错误行为"的测试，所以要把一次绿色运行当作对被断言行为的证据，而不是安全放行。
  • 把不可信输入当作不可信。 当 Agent 处理 Issue 文本、PR 评论，或通过 MCP 拉取的内容时，那些内容是数据，而不是带授权的指令。fork PR 和公开 Issue 是最明显的风险面。

这些都不会削减 Claude Code 的价值——它们定义的是"在什么条件下，这份价值可以安全地被收下"。

Claude Code vs Cursor vs Copilot：不同的形态

到 2026 年，AI 编程工具格局稳定成了三种可辨识的形态，每一种都是一次不同的设计押注，而不是一个排名：

维度 Claude Code Cursor GitHub Copilot
交互界面 终端 CLI VS Code Fork IDE IDE 插件
设计押注 终端原生 Agent 可视化 Agent IDE 生态整合平台
模型 Claude（Opus/Sonnet） 多模型 多模型
Tab 补全 非重点 专用模型 核心功能
Agent 模式 全程 Agent Composer / Background Agent Agent Mode
CLI 集成 原生 有限 有限
CI/CD 集成 官方 GitHub Action 有限 GitHub 原生
最佳场景 复杂重构、CI/CD 自动化 交互式日常开发 补全、GitHub 工作流

具体的模型名称、能力和定价经常变动，所以把这张表当作一张"形态地图"，并到各家官方核验当前细节。这里没有普适的赢家——正确的选择取决于哪种形态匹配你的瓶颈。想在你自己的任务上（而不是在功能条数上）得出一个可重复的判断，参见 如何自己评测 Cursor、Claude Code 和 Copilot；想看更宽的全景，参见 2026 AI 编程工具对比。

对很多团队而言，务实的答案是组合使用：用 IDE 助手做交互式编辑，用 Claude Code 处理终端优先的任务和 CI/CD 自动化。至于让它们中任何一个真正产出价值的工作纪律，参见 Vibe Coding 实战指南。

长时间自主执行：到底改变了什么

近期 Claude 模型带来的实质变化是：一个编码 Agent 能跨越一个较长的会话完成多步骤任务，而不再局限于单轮提示——它能持有上下文、保持一致的风格、并自我修正早期引入的问题。

但要小心怎么读这件事。真正有用、能长期成立的论断是定性的：长时间自主执行已经从"连贯的几分钟"进步到"一个持续的会话"，这正是委派变得可行的原因。而任何附着在它上面的具体数字——某个厂商 demo 里的小时数、某个跑分解决率、某个每 Token 价格——都是一个带日期的数据点，往往是在厂商自己的环境上测出来的，且随每次发布变化。如果你确实需要这些数字，请连同来源和日期一起记录，并在依赖它之前核验：

json 
{
  "claim": "模型解决率 / 最大自主时长 / Token 价格",
  "value": "以官方发布为准",
  "plan_or_scope": "它所适用的基准或套餐",
  "source_url": "厂商文档或模型卡片",
  "checked_at": "YYYY-MM-DD",
  "checked_by": "姓名或系统"
}

更重要的是，没有任何跑分能预测一个模型在你自己的代码库上如何表现。如果"长任务上的自主性"对你的决策很关键，就在你自己的真实工作上跑一个小规模试点——上面评测指南里的方法可以直接套用。

最佳实践：CLAUDE.md 与 Memory 系统

CLAUDE.md 是 Claude Code 最重要的配置机制——它是你项目的"说明书"，每次会话自动加载。它是一种约定辅助：它改变 Agent 倾向于产出什么，这正是它值得好好写的原因，也正是它不能替代真正控制的原因。

CLAUDE.md 配置示例

markdown 
# CLAUDE.md

## 项目概述
这是一个基于 Next.js 14 + TypeScript 的 SaaS 平台，使用 Prisma ORM 连接 PostgreSQL。

## 常用命令
- 开发服务器：`npm run dev`
- 运行测试：`npm test`
- 类型检查：`npx tsc --noEmit`
- 代码检查：`npm run lint`
- 数据库迁移：`npx prisma migrate dev`

## 代码规范
- 使用函数式组件 + Hooks，禁止 class 组件
- 所有 API 路由必须包含输入验证（使用 Zod）
- 错误处理使用自定义 AppError 类
- 所有用户可见文本使用 i18n（next-intl）

## 架构约定
- src/app/ - Next.js App Router 页面
- src/lib/ - 业务逻辑和工具函数
- src/components/ - React 组件（使用 shadcn/ui）
- prisma/schema.prisma - 数据库模型定义

## 禁止事项
- 不要修改 prisma/migrations/ 下的已有迁移文件
- 不要在客户端组件中直接访问数据库
- 不要使用 any 类型

Memory 层级体系

Claude Code 的 Memory 系统采用多层级结构，优先级从高到低：

层级 文件位置 作用范围 典型用途
企业级 通过管理后台配置 整个组织 安全合规策略、禁止操作列表
用户级 ~/.claude/CLAUDE.md 所有项目 个人编码风格偏好、常用工具链
项目级 ./CLAUDE.md 当前项目 项目架构、技术栈、常用命令
目录级 ./src/api/CLAUDE.md 子目录 特定模块的接口规范

使用 /init 命令可以快速为当前项目生成 CLAUDE.md 骨架：

bash 
$ claude
> /init

# Claude 会分析你的项目结构，自动生成包含：
# - 检测到的技术栈和框架
# - 常用的 build/test/lint 命令
# - 项目目录结构概览

自动记忆（Auto-Memory）

除了手动编写的 CLAUDE.md，Claude Code 还支持自动记忆功能。当你在会话中纠正 Claude 的行为时，它会把这些偏好保存到 MEMORY.md：

bash 
# 会话中的纠正会被记录
> 不要使用 console.log 调试，用 debug 库
> 数据库查询一律使用 prepared statements

# Claude 更新 MEMORY.md：
# - Prefer debug library over console.log
# - Always use prepared statements for database queries

这让一次改进能跨会话保留，而不必每次重新学习——再强调一次，这是约定辅助，不是安全边界。关于 提示工程（Prompt Engineering） 和上下文管理的底层纪律，以及 Claude Code 如何通过 MCP 扩展工具能力，可参考我们的 MCP 协议深度解析。

进阶技巧

斜杠命令速查

命令 功能
/init 初始化 CLAUDE.md
/memory 编辑自动记忆文件
/compact 压缩当前会话上下文
/clear 清空会话历史
/cost 查看当前会话 Token 用量和费用
/model 切换模型（opus/sonnet）
/permissions 查看和管理工具权限

/compact 很方便，但要记住：把一个长会话摘要化是有损的——细节会被丢掉。对任何"正确性攸关"的约束，把它写进 CLAUDE.md，而不要指望它能在压缩后幸存。

高效 Prompt 模式

在 Claude Code 中，好的 Prompt 遵循"目标 + 约束 + 验证标准"的三段式结构：

bash 
# ❌ 模糊指令
> 修一下登录

# ✅ 明确的三段式指令
> 修复登录接口的 Bug：用户使用 Google OAuth 登录时偶尔返回 500。
> 约束：不要修改数据库 schema，保持向后兼容。
> 验证：修复后运行 npm test -- auth，所有测试必须通过。

MCP 协议集成

Claude Code 支持 MCP（Model Context Protocol） 协议，可以连接外部工具服务器，让它不仅能操作本地文件，还能与数据库、API 平台、监控系统等外部服务交互。当你接入一个 MCP Server 时，请记住安全小节里的那条边界：一个"符合该 Server schema"的结果，只说明形状合法，并不说明它的内容可以安全地拿来执行——而且这条连接是带着你所授予的访问权限在运行的。

总结

Claude Code 代表了 AI 编程工具的一个关键转折点：从"辅助补全"到"自主 Agent"。它的终端原生设计、SDK 可编程性和 CI/CD 集成能力，让 AI Agent 技术真正落地到软件工程的全链路中。

它的收益是实实在在的：

  • 提升开发效率：自主完成重构、测试和首轮审查。
  • 降低 CI/CD 门槛：官方 GitHub Action 支持 Issue 与 PR 驱动的工作流。
  • 保持一致性：CLAUDE.md 让 Agent 与你的约定对齐。
  • 支持规模化：SDK 和子 Agent 机制支撑自动化管道。

但这份收益也以纪律为前提：收窄 Agent 的访问范围、审查它产出的东西，并把授权等真正的控制留在你的系统里，而不是一个配置文件或模型的输出里。从一个低风险任务上的简单 claude 命令开始，随着你的审查流程跟得上，再逐步扩大它的边界。

相关资源