Claude Code 实战：AI 编程智能体命令行工作流

2026年10月15日工具推荐 suzhe

Claude Code 是 Anthropic 推出的 agentic（智能体式）命令行编程工具：你用自然语言描述需求，它在终端里自主读代码、改文件、跑命令，直到把变更交付成可审查的 diff。对已经习惯在 shell 里工作的开发者来说，它把”AI 编程智能体”从 IDE 插件变成了随手调用的命令。本文基于实战经验，拆解它的安装、权限模型、子代理与 CI 集成，帮你把 Claude Code 真正接进日常开发流。

一、Claude Code 是什么，和 Roo Code / Cursor 有何不同

市面上的 AI 编程产品大致分两类：一类是”编辑器内的补全/对话”（如 Cursor、VS Code 的 Copilot），一类是”独立智能体”（你给目标，它自己干活）。Claude Code 属于后者，而且它运行在终端里，天然适合接管道、CI 和远程服务器。

1.1 与 Roo Code 的差异

Roo Code 是 VS Code 里的多模式智能体扩展，依赖编辑器环境；Claude Code 是纯命令行工具，可以在无头服务器、tmux、GitHub Actions 里直接跑。两者可以互补——如果你更在意 IDE 交互，可参考我们此前的 Roo Code 实战。关于”AI 如何从补全走向自主编程”的范式变化，AI 编程智能体一文有更系统的梳理。简单说，需要图形化 diff、断点、补全提示时用 IDE 智能体更舒服；需要把任务丢给服务器后台跑、或写进 shell 脚本批量处理时，命令行形态反而更顺手，也更容易接进现有自动化。

二、安装与初始化

Claude Code 通过 npm 分发，需要 Node 18+。全局安装后，在任意 git 仓库目录下执行 claude 即可进入交互式 REPL。

# 全局安装
npm install -g @anthropic-ai/claude-code

# 进入项目目录并启动
cd ~/projects/my-app
claude

# 非交互模式：直接把任务作为字符串传入（适合脚本/CI）
claude -p "为 src/utils 下的函数补全 JSDoc 注释"

认证有两种方式：登录 Claude 订阅账号（Pro/Max，命令内走 OAuth），或设置环境变量 ANTHROPIC_API_KEY 走 API 计费。在服务器上没浏览器时，推荐后者：

export ANTHROPIC_API_KEY="sk-ant-****"
claude -p "列出当前目录里超过 200 行的文件"

三、三种核心交互模式

3.1 交互式 REPL

最常用。启动后像聊天一样给指令，Claude Code 会边读仓库边改文件，遇到需要执行命令（如跑测试）时按权限策略征求你同意。会话里随时用 /cost 看 token 消耗、用 /clear 清空上下文、用 /memory 把长期偏好写进项目记忆，避免每次重新交代背景。长任务跑完一轮后主动 compact，能显著降低后续对话的上下文成本。

3.2 管道 / 非交互模式（-p）

-p（print）模式把任务当参数传入，输出结果到 stdout，方便接进 shell 管道和自动化。配合 --output-format stream-json 还能拿到结构化事件流。

# 把任务作为单行字符串，静默跑完
claude -p "修复 lint 报错并总结改了哪些文件" --permission-mode acceptEdits

# 结构化输出，便于程序消费
echo "为新增的 API 写单元测试" | claude -p --output-format stream-json

3.3 权限模式

Claude Code 用 --permission-mode 控制它能自动做什么，这是它和”无脑全权限”工具最关键的边界：

模式	行为	适用场景
default	文件编辑与命令执行前都询问	首次接触陌生仓库
acceptEdits	自动接受文件改动的写，命令仍询问	信任的代码库日常开发
plan	只读，只产出方案不改动	评审 / 调研阶段
bypassPermissions	全部自动批准（危险）	仅隔离的沙箱环境

四、用 CLAUDE.md 沉淀项目记忆

在仓库根放一个 CLAUDE.md，Claude Code 每次启动会自动加载，相当于给智能体的”项目说明书”：技术栈、约定、禁区。这比每次重复讲背景省太多 token。CLAUDE.md 还支持多级：仓库根的一份面向全项目，子目录的一份可面向某个模块；Claude Code 会按当前路径自动叠加加载，越往下越具体。团队把它提交进 git，新人克隆下来就能立刻拿到”老鸟才知道的坑”。

# CLAUDE.md 示例
- 后端用 Spring Boot 3 + Java 21，禁止引入新的 XML 配置
- 前端走 Vite + Pinia，状态必须集中到 store
- 数据库迁移只能用 Flyway，禁止手动改表
- 提交前必须跑 ./gradlew test 且零红

关于如何在 Java 项目里接入大模型能力、以及用 Flyway 管迁移，可分别参考 Spring AI 实战与 Flyway 实战。

五、实战闭环：从需求到 PR

一个典型工作流：让 Claude Code 实现功能 → 它自测 → 你 review diff → 提交并开 PR。下面是最小可跑的闭环：

# 1) 让它实现并自测（auto-accept 文件改动）
claude -p "在 UserController 增加按邮箱查询的接口，并补集成测试" \
  --permission-mode acceptEdits

# 2) review 改动
git diff --stat

# 3) 提交开 PR（需先配好 gh）
git add -A && git commit -m "feat: add query-by-email endpoint" && git push
gh pr create --fill

需要让大模型”调用你的接口 / 工具”时，先定义好 function 描述，思路与 Function Calling 实战一致；想要更自主的多步推理，可回看从零手写 AI Agent。

六、子代理与多文件重构

复杂任务可以拆给子代理并行干。Claude Code 内置 Task 工具，也支持在 .claude/agents/ 下定义领域子代理。比如一个”重构向导”专管重命名、一个”测试生成器”专管补用例。

# 定义项目级子代理 .claude/agents/refactor.md
---
name: refactor
description: 负责跨文件重命名与接口收敛
tools: Read, Edit, Grep
---
你只做重构，不新增功能。每次改动后用 git diff 汇报。

会话内可用 /agents 查看可用子代理，用 Task 显式派活。子代理彼此隔离上下文，主代理只拿结果，既能并行又不互相污染——处理”先重构再补测试”这类多步任务时尤其省心。对”把一个智能体拆成多个协作角色”的更通用做法，A2A 协议给出了开放标准，详见 A2A 协议实战。

七、接进 CI：GitHub Actions

Claude Code 官方提供了 anthropics/claude-code-action，可在 PR 评论里 @claude 触发它修 bug、补测试、回答疑问。最小配置：

# .github/workflows/claude.yml
name: claude
on:
  issue_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@beta
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: ${{ github.event.comment.body }}

把自动化跑在 GitHub Actions 上与本文的”命令行智能体”思路一脉相承，关于流水线搭建可参考 GitHub Actions 实战。

八、进阶：hooks 与 MCP

8.1 Hooks：在事件上挂脚本

通过 settings.json 的 hooks 字段，可在工具调用前后插入自定义脚本，例如”每次写文件后自动格式化””提交前跑安全扫描”。

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit", "hooks": [{ "type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS" }] }
    ]
  }
}

8.2 MCP：接外部能力

用 claude mcp add 把 MCP 服务器挂上，智能体就能访问数据库、内部 API、云资源。这与”让大模型调用你的工具”本质相同，只是走的是开放协议。

claude mcp add --transport stdio my-db npx -y my-db-mcp-server
claude mcp list

九、常见坑与排障

现象	原因	解决
认证失败	API key 无效或订阅未激活	重设 ANTHROPIC_API_KEY 或重新 claude 登录
一直询问权限	用 default 模式	信任仓库时加 –permission-mode acceptEdits
改错文件	缺少 CLAUDE.md 约束	补全项目记忆与禁区说明
上下文爆炸	长会话未压缩	用 /compact 或定期 /clear 重置

十、小结

Claude Code 的价值不在”替你写几行”，而在把”描述需求 → 改代码 → 自测 → 交付”变成一条可在终端、CI、远程机上复用的命令。先用 CLAUDE.md 立规矩，再用 acceptEdits 提效率，最后用 hooks / MCP 把边界扩到整个研发系统，才是把它用顺的姿势。

作者：suzhe

链接：https://fsdata.site/2026/10/claude-code-practical/

文章版权归作者所有，未经允许请勿转载。