2026-09-01·技能与命令

Claude Code 2026 实战教程——安装 CLI、/init 项目初始化、CLAUDE.md 记忆策略、四种权限模式（default/acceptEdits/plan/bypassPermissions）、MCP server 集成、6 个最常用命令、CI/Docker 生产部署，外加上下文管理常见坑与三个完整任务实战。

Claude Code 完全指南：从首次安装到日常工作流（2026）

Q: 我能在脚本或 CI 里非交互地用 Claude Code 吗？

能。-p 标志让 Claude 非交互地处理管道输入并打印响应，例如 cat error.log | claude -p "这个错误是什么原因？"。这是把 Claude Code 接进 shell 脚本、git hook 和 CI 流水线的方式。要用到生产自动化，Agent SDK 提供同样的能力，且是可编程的。

Q: Claude Code 怎么调用 MCP server？

启动时自动加载配置的 server——.mcp.json（项目级）+ ~/.claude.json（用户级）+ 企业 MDM。优先级：MDM > 项目 > 用户，高优先级覆盖低。配置写错（如 JSON 解析失败、token 缺失）时 claude-code 静默跳过那个 server，但其他仍加载。运行 /mcp 看当前所有 server 的连接状态；claude --debug 启动会打印握手字节流。

Q: 容器 / Docker 跑 Claude Code 需要哪些 secret？

最少 2 个：ANTHROPIC_API_KEY（认证）+ GITHUB_TOKEN（如果用 GitHub Action 触发）。用 Bedrock / Vertex 时还要 AWS_REGION + AWS_ROLE_ARN（或 GCP 等价物）。Docker 镜像里把 secret 注入到容器而不是打包——用 docker run -e 或 Kubernetes Secret 引用，避免镜像层泄露。

Q: Claude Code 会话越来越长、变慢又变贵，该怎么办？

用 /clear 或 /compact 主动管理上下文。/clear 清空对话历史、保留会话，适合切换到不相关的新任务；/compact 把到此为止的历史总结成摘要再腾出窗口，适合同一任务的长程推进。同时把关键决定写回 CLAUDE.md 或计划文件，避免压缩后丢失。

Q: CLAUDE.md、CLAUDE.local.md 和 ~/.claude/CLAUDE.md 有什么区别？规则该放哪一层？

项目根目录的 ./CLAUDE.md 是团队共享的项目记忆，提交进 git；CLAUDE.local.md 默认被 gitignore，放机器特定或私密的笔记；~/.claude/CLAUDE.md 是用户记忆，放跨项目的个人偏好。按受众分层：团队约定进项目记忆，个人习惯进用户记忆，不想提交的进 local。运行 /memory 可核对当前会话实际加载了哪些文件。

Claude Code 是 Anthropic 在 2025 年发布并快速成为事实标准的终端原生 agent 编程工具——基于 Claude Sonnet / Opus 系列模型，通过 CLAUDE.md 项目记忆 + 工具调用循环 + MCP server 扩展，让你在终端里直接说出需求、它改文件、跑命令、搜代码库、交付功能。本文基于 Claude Code 2026 年 8 月版本，覆盖：完整安装与配置、/init 项目初始化、CLAUDE.md 记忆策略、allow/deny 权限边界、6 个最常用命令、一个真实代码库上经得起考验的日常工作流。

TL;DR

Claude Code = 终端原生 agent 编程工具；CLI 全局包 @anthropic-ai/claude-code

3 个核心机制：CLAUDE.md 记忆 + 工具调用循环 + MCP server 扩展

2026 年现状：与 Claude Agent SDK 一体两面（CLI 是 SDK 的 headless 模式）

安装：npm i -g @anthropic-ai/claude-code → 在项目目录跑 claude

首次必做：/init 让 Claude 探索项目生成 CLAUDE.md，再 /login 认证

权限用 allow / deny allowlist——不要走 bypassPermissions 除非沙箱里

安装 Claude Code

Claude Code 是一个以 npm 包形式分发的终端工具。你需要先装好 Node.js（任意较新的 LTS 版本都行），然后：

npm install -g @anthropic-ai/claude-code

这会全局安装 claude 命令。确认它在你的 PATH 上：

claude --version

首次启动时，claude 会引导你用 Anthropic 账号（或一个 API key，或受支持的 Bedrock / Vertex 后端）完成认证。认证完成后，进入项目目录，不带任何参数运行 claude 即可启动交互式会话。Claude Code 的设计是从仓库根目录运行，这样它能把整个项目读进上下文。

它不需要单独的 IDE 插件。Claude Code 在任何终端里都能用，也有针对 VS Code、JetBrains 这类编辑器的可选集成，可以从编辑器内启动会话。终端是它的主战场。

用 /init 给项目打底

在一个新项目里最值得跑的第一条命令是 /init。它让 Claude 探索你的代码库，生成一份 CLAUDE.md，把新贡献者需要知道的要点抓出来：构建和测试命令、目录布局、约定，以及任何值得知道的坑。产出的是一份草稿，你再把它删到真正有用的部分。

> /init

/init 跑完后，打开 CLAUDE.md，把任何错的或本来就显而易见的东西删掉。目标是短而准确的文件，而不是面面俱到的文件。一份好的 CLAUDE.md 大约两屏：怎么跑测试、入口在哪、Claude 写代码时要遵守的约定。其他都是每一轮都要烧 token 的噪音。

/init 不是强制的。你可以手写 CLAUDE.md、跳过草稿。但在新项目里跑一次是最快的启动方式，因为 Claude 读的是真实代码，而不是瞎猜。

CLAUDE.md 记忆文件

CLAUDE.md 是 Claude Code 里最重要的配置文件。它是一个纯 Markdown 文件，Claude 在每次会话开始时读取它，所以里面的任何东西都成了持久上下文。把它当成你交给一个从没见过这个代码库的新同事的说明。

Claude Code 从几个地方加载 CLAUDE.md，全部合并：

项目记忆 —— 仓库根目录的 ./CLAUDE.md（以及子目录里嵌套的 CLAUDE.md，当 Claude 在那个目录工作时加载）。提交到 git，团队共享。
用户记忆 —— ~/.claude/CLAUDE.md，跨所有项目的个人偏好。
本地覆盖 —— ./CLAUDE.local.md，被 gitignore 掉，用于机器特定或私密的笔记。

随时运行 /memory，可以查看当前会话到底加载了哪些文件。当 Claude 表现得像忘了什么时，这个命令非常有用——通常是你编辑的那个文件并不在已加载列表里。

CLAUDE.md 里该放什么？高价值的内容是：构建和测试命令、代码风格和命名约定、新代码该放哪、怎么跑 linter、以及任何项目特定的规则（「绝不要改生成的 dist 目录」「总要先加一条 changelog」）。保持简短、用祈使句。又长又散的 CLAUDE.md，模型会像人一样跳着读。

权限：allow 和 deny

因为 Claude Code 会跑命令、改文件，权限是你防止它做你不想做的事的手段。Claude Code 会把每次工具调用拿去跟你设置里的规则比对，并在第一次尝试规则没覆盖的动作时征求批准。

在一个会话里可以在四种权限模式间切换：

default —— 在可能有破坏性的动作前征求批准（正常模式）。
acceptEdits —— 自动批准文件编辑，命令仍会问。
plan —— 只读探索；Claude 提出方案但不做改动。
bypassPermissions —— 跳过所有批准提示（谨慎使用，通常只在沙箱环境）。

持久规则放在 settings.json 里（项目级在 .claude/settings.json，用户级在 ~/.claude/settings.json）的 permissions.allow 和 permissions.deny 下：

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint)",
      "Read(./src/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(./secrets/**)"
    ]
  }
}

两条实践中重要的规则：deny 永远优先于 allow（即使匹配了 allow，被 deny 的动作仍会被阻止），以及 hooks 在规则之前运行（PreToolUse hook 可以无视规则阻止或批准一次调用）。Read 和 Edit 的 deny 规则还会延伸到 Claude 在 Bash 里识别的文件命令——cat、head、tail、sed——所以你不会因为走 shell 而意外读到一个密钥文件。

调权限的目标是在「批准疲劳」和「完全放手」之间找平衡。一套典型设置：允许测试和 lint 命令、允许读源码树、拒绝任何碰密钥或强推的操作，其余的都留在默认的询问上。

你真正会用的命令

Claude Code 有一组用于会话控制的斜杠命令。日常会用到的有：

/init —— 生成 CLAUDE.md 草稿。
/memory —— 显示当前加载了哪些记忆文件。
/permissions —— 查看和编辑当前生效的权限规则。
/clear —— 重置对话上下文，保留同一个会话。
/compact —— 把到目前为止的对话总结一下，腾出上下文窗口。
/mcp —— 列出已连接的 MCP 服务器及其工具。
/model —— 切换底层模型。
/help —— 列出所有可用命令。

斜杠命令之外，主要的交互就是用自然语言打字提需求。你也可以管道输入：cat error.log | claude -p "这个错误是什么原因？" 会让 Claude 非交互地处理管道内容并打印响应，这是把 Claude Code 接进脚本和 CI 的方式。

一个经得起考验的日常工作流

在真实代码库上效果较好的工作流：

从仓库根目录开始，这样 Claude 能把整个项目纳入视野。运行 /memory 确认正确的 CLAUDE.md 已加载。
先用 plan 模式探索。 对任何非琐碎任务，先用 plan 模式，让 Claude 读代码、提方案，再动手改文件。审一遍方案、调整，然后切回 default 模式执行。
改动的同一轮要测试。 当你提一个功能或修复需求时，在同一轮里把测试也要了。改动和测试一起写，Claude Code 才最靠谱。
让它跑测试。 允许 npm test（或你的等价命令），这样 Claude 能验证自己的改动。Agent 自己确认过通过测试套件的改动，远比没确认的可信。
接受前审每个 diff。 机械改动用 acceptEdits 提速，但遇到微妙之处就切回 default 模式。模型写的代码得你来维护。
小块提交。 让 Claude 把改动按逻辑分组暂存并描述，而不是一个大提交。如果你在 CLAUDE.md 里写明了格式，Conventional Commits 风格的消息会很干净。

贯穿所有这些的模式：决策上保持人在环里，让 Claude 干打字的活。Claude Code 在机械工作上很快——读目录、写样板改动、跑测试、重生 fixture——而在无人监督下做产品判断时最弱。扬长避短。

用技能、命令和 hooks 做定制

基础打通后，定制层是 Claude Code 在特定项目上变强大的地方。

技能（Skills） 把可复用的流程打包成一个按需加载的 SKILL.md——详见我们的 Claude Code Skills 指南。
自定义斜杠命令 放在 .claude/commands/ 下，是 Markdown 提示词文件；输入 /project:你的命令 即可运行。
Hooks 在生命周期事件（PreToolUse、PostToolUse、Stop）上跑脚本，用于像「每次编辑后自动格式化」或「阻止危险命令」这类事。

它们可以组合。一套成熟的配置可能有：一个用于代码审查清单的技能、一个用于部署流程的斜杠命令、一个在 Claude 每次写文件后跑格式化器的 PostToolUse hook。回报是 Claude 会按你团队期望的方式行事，而你不必每个会话都重新解释一遍。

Claude Code × MCP：让 CLI 接入任意工具

Claude Code 启动时自动加载配置的 MCP server，让 Claude 直接调用工具——读 Slack、查 Postgres、抓 GitHub PR、跑浏览器。配置入口有两个：

项目级 .mcp.json（提交到 git）—— 整个团队共享：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

用户级 ~/.claude.json（个人）—— 跨项目可用，例如私人 SQLite MCP server。

配置加载顺序：企业托管 MDM → 项目级 .mcp.json → 用户级 ~/.claude.json，高优先级覆盖低优先级。同一 slug（如 github）的 server 出现多次时取最高层。

启动后 Claude Code 显示 mcp 命令列出所有 server 与状态。易错点：env 里写死的 token 会被提交到 git——正确做法是用 ${ENV_VAR} 占位 + 从密钥管理器注入（参考 mcp-servers-configuration 指南）。

权限模式：四种状态机的边界与陷阱

Claude Code 权限文档定义了四种权限模式，会话内可随时切换：

| 模式 | 行为 | 何时用 | |---|---|---| | default | 有破坏性的动作前征求批准（默认） | 日常开发 | | acceptEdits | 自动批准文件编辑，命令仍问 | 写代码密集场景 | | plan | 只读探索；Claude 提出方案但不做改动 | 重构 / 调研陌生代码 | | bypassPermissions | 跳过所有批准提示 | 仅沙箱（容器化、临时环境） |

坑 1：allow / deny 规则有顺序敏感性。deny 永远优先——如果一个动作同时匹配 allow 和 deny 规则，它会被阻止。Read 和 Edit 的 deny 规则还会延伸到 Bash 里的等价命令（cat、head、tail、sed），所以你不会因为走 shell 而读到一个被拒绝的文件。

坑 2：hooks 在规则之前运行。PreToolUse hook 可以无视权限规则阻止或批准一次调用——即使规则允许，hook 也能否决。参考 Claude Code Hooks 文档看具体写法。

坑 3：bypassPermissions 是单向门。一旦启用，会话内无法回滚到「询问」模式——只能重启。建议只对临时容器或 CI 环境用。

实战模式：CI / Docker / 团队分发

把 Claude Code 装进 CI 或 Docker 是 2026 年最常见的规模化路径——按 Claude Code GitHub Actions 指南：

# .github/workflows/claude.yml
on: [issue_comment, pull_request_review]
permissions:
  contents: read
  issues: write
  pull-requests: write
  id-token: write  # OIDC for Bedrock/Vertex
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: claude_mention  # 仅 @claude 触发，省 token
          allowed_users: "octocat,dependabot[bot]"

三个 2026 年新坑：

OIDC 与 Bedrock/Vertex 的 audience 绑定——必须用 id-token: write 权限，且 server 端的 IAM role 要 trust 正确的 GitHub OIDC provider（iam 文档）。
@claude mention 必须小写、@ 直接接名字——大写 @Claude 不会触发。
fork PR 上 claude-code-action 仍会触发，但拿不到父仓库 secrets——跑出 401。设 allowed_users 白名单限制触发者是团队成员。

Docker 部署：把 claude-code-action 塞进容器 + 自带 ANTHROPIC_API_KEY 镜像——让 sandbox + bypassPermissions 在容器内生效。即使 claude-code 误操作也只影响容器，不影响 host。

常见坑与反模式：CLAUDE.md、上下文与会话管理

权限类陷阱（allow/deny 优先级、hooks 先行、bypassPermissions 单向门）上一节已经讲完。这一节集中回答另一类高频事故——Claude「没记住」「忘掉了」「越用越差」。它们几乎都不是模型能力问题，而是上下文管理问题。

坑 1：改了 CLAUDE.md，Claude 却「没记住」。 现象：规则明明写了，新回答仍然不遵循。原因：文件不在当前会话的加载列表里——CLAUDE.md 有项目级、用户级、子目录级多层，放错层级（比如规则写在子目录、工作却在仓库根做）就不会被读入。修法：运行 /memory 核对当前实际加载了哪些文件，把规则挪到正确层级；会话中途的改动，重开会话才生效。

坑 2：CLAUDE.md 越写越长，遵循率反而下降。 现象：规则越加越多，一部分开始被忽略。原因：整个文件每轮都会读入上下文，长文件摊薄注意力、烧 token，模型和人类一样会跳读。修法：正文控制在两屏左右，低频细节挪进按需加载的 skills 或子目录 CLAUDE.md——子目录的文件只有当 Claude 读到该路径下的文件时才会加载（见官方记忆文档）。

坑 3：长会话后半段「忘记」早前决定。 现象：开头约定的命名、结构在几十轮后被悄悄放弃。原因：上下文窗口滚动，早期消息被压缩或移出窗口。修法：重要约定产生时立即落盘——写回 CLAUDE.md 或计划文件，不要指望模型「记住」对话内容。

坑 4：/clear 与 /compact 混用。 现象有两个方向：换了不相关任务后质量下降、成本升高——该 /clear 没 clear；或者 compact 之后细节丢失——不该 compact 时 compact 了。/clear 清空历史保留会话，适合任务切换；/compact 把历史压成摘要腾出窗口，适合同一任务的中场休整。一个是换任务，一个是续任务，别用反。

坑 5：acceptEdits 长开无人审。 现象：一大批 diff 被静默接受，跑测试才发现方向性错误。acceptEdits 自动批准所有文件编辑，机械批量改动用它提速没问题；微妙逻辑改动要切回 default 逐个审 diff。长会话的开销管理见官方成本文档。

实战案例：三个真实任务的完整执行过程

三个来自日常开发的任务，各给完整的驱动方式与「为什么这么跑」。更多官方推荐流程见 common-workflows。

案例 A：修一个生产 bug。 CI 挂了，日志 200 行。第一步用非交互模式做只读诊断：cat error.log | claude -p "定位根因，列出涉及的文件"——只让它分析报告，不许改代码。拿到根因清单后，再开交互会话修复；同一轮里让它补回归测试并运行 npm test 自证。最后人工审 diff、小块提交。理由：诊断与修复分离，避免模型边分析边顺手改动，把自己的假设写进代码。

案例 B：跨 10+ 文件的重构。 把回调风格的 REST 客户端迁到 async/await。先切 plan 模式产出迁移方案与受影响文件清单，人确认后再执行；CLAUDE.md 里写明「不改公共 API 签名」的约束；分批执行，每批跑一次测试；收尾让它汇总 changelog。理由：大重构最大的风险是方向性跑偏，plan 模式把纠错成本从「写完再改」提前到「动手之前」。

案例 C：新功能带测试一次交付。 给导出模块加 CSV 后端。同一轮提三个要求：实现、单元测试、更新文档；允许它运行 npm test；审完 diff 让它按 Conventional Commits 分组暂存、分别提交。理由：实现与测试同轮生成，对接口边界的理解不会在两次会话之间走样；分组提交把「一个功能」拆成可独立回滚的单元。

常见问题

什么是 CLAUDE.md，怎么创建？

CLAUDE.md 是一个纯 Markdown 文件，Claude Code 在每次会话开始时读取它，使其内容成为持久上下文。最快的创建方式是在项目根目录运行 /init——Claude 会探索代码库，生成一份草稿，涵盖构建命令、布局和约定，你再删到有用的部分。你也可以手写。随时运行 /memory 可查看当前加载了哪些 CLAUDE.md 文件。

Claude Code 有哪四种权限模式？

default 在可能有破坏性的动作前征求批准；acceptEdits 自动批准文件编辑但命令仍会问；plan 是只读探索，Claude 提方案但不改东西；bypassPermissions 跳过所有批准提示。你可以在一个会话里切换，持久的 allow/deny 规则放在 settings.json 里。

allow 和 deny 权限规则如何相互作用？

deny 永远优先。如果一个动作同时匹配 allow 和 deny 规则，它会被阻止。Read 和 Edit 的 deny 规则还会延伸到 Claude 在 Bash 里识别的文件命令，如 cat、head、tail、sed，所以你不会因为走 shell 而读到一个被拒绝的文件。hooks 在规则之前运行，所以 PreToolUse hook 可以无视权限规则阻止或批准一次调用。

我能在脚本或 CI 里非交互地用 Claude Code 吗？

能。-p 标志让 Claude 非交互地处理管道输入并打印响应，例如 cat error.log | claude -p "这个错误是什么原因？"。这是把 Claude Code 接进 shell 脚本、git hook 和 CI 流水线的方式。要用到生产自动化，Agent SDK 提供同样的能力，且是可编程的。

Claude Code 怎么调用 MCP server？

启动时自动加载配置的 server——.mcp.json（项目级）+ ~/.claude.json（用户级）+ 企业 MDM。优先级：MDM > 项目 > 用户，高优先级覆盖低。配置写错（如 JSON 解析失败、token 缺失）时 claude-code 静默跳过那个 server，但其他仍加载。运行 /mcp 看当前所有 server 的连接状态；claude --debug 启动会打印握手字节流。

容器 / Docker 跑 Claude Code 需要哪些 secret？

最少 2 个：ANTHROPIC_API_KEY（认证）+ GITHUB_TOKEN（如果用 GitHub Action 触发）。用 Bedrock / Vertex 时还要 AWS_REGION + AWS_ROLE_ARN（或 GCP 等价物）。Docker 镜像里把 secret 注入到容器而不是打包——用 docker run -e 或 Kubernetes Secret 引用，避免镜像层泄露。

Claude Code 会话越来越长、变慢又变贵，该怎么办？

用 /clear 或 /compact 主动管理上下文。/clear 清空对话历史、保留会话，适合切换到不相关的新任务；/compact 把到此为止的历史总结成摘要再腾出窗口，适合同一任务的长程推进。同时把关键决定写回 CLAUDE.md 或计划文件，避免压缩后丢失。

CLAUDE.md、CLAUDE.local.md 和 ~/.claude/CLAUDE.md 有什么区别？规则该放哪一层？

项目根目录的 ./CLAUDE.md 是团队共享的项目记忆，提交进 git；CLAUDE.local.md 默认被 gitignore，放机器特定或私密的笔记；~/.claude/CLAUDE.md 是用户记忆，放跨项目的个人偏好。按受众分层：团队约定进项目记忆，个人习惯进用户记忆，不想提交的进 local。运行 /memory 可核对当前会话实际加载了哪些文件。

官方参考资料

本文基于截至 2026 年 8 月的公开信息，相关 API 可能演进。