Claude Code 上手：安装、CLAUDE.md、子 agent、hooks 和权限

这篇适合谁

想在真实项目里长期使用 Claude Code 的人，不是只想试一次的人。先读安装和第一个会话，再读 CLAUDE.md 这个项目记忆，最后读权限模式。读完你应该能装好 Claude Code、开一个会话、写出一份 CLAUDE.md、加一个子智能体（subagent），并且知道当前处在哪种权限模式里。

它是什么

Claude Code 是一个智能体式的编程工具，可以在终端、IDE、桌面应用和浏览器中使用 ^[2]。大多数入口需要 Claude 订阅或 Anthropic Console 账号 ^[2]。

安装之前

Claude Code 按 API token 消耗量计费，订阅套餐价格见 claude.com/pricing。Team 和 Enterprise 套餐的用量从成员的席位额度中扣，Claude Console 和云服务商上的用量则按 token 计费到组织 ^[12]。

如果你用 npm 安装，这个包要求 Node.js 22 或更新版本 ^[4]。

安装和第一个会话

在 macOS、Linux 和 WSL 上，官方推荐的原生安装命令是 ^[2]：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell 上使用 irm https://claude.ai/install.ps1 | iex ^[2]。用 Homebrew 安装，执行 brew install --cask claude-code。Homebrew 提供两个 cask：claude-code 跟随稳定版通道，claude-code@latest 跟随最新版通道 ^[2]。Windows 上可以用 winget install Anthropic.ClaudeCode 安装，之后用 winget upgrade Anthropic.ClaudeCode 升级 ^[2]。快速开始还列出了 Debian、Fedora、RHEL 和 Alpine 上的 apt、dnf 和 apk 安装方式 ^[2]。

如果你习惯用 npm，就全局安装这个包 ^[4]：

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

升级 npm 安装的版本时，执行 npm install -g @anthropic-ai/claude-code@latest。不要用 npm update -g，也不要用 sudo npm install -g ^[4]。

装好后，用 claude --version 确认安装成功 ^[3]。然后在项目目录里开始会话 ^[3]：

cd /path/to/your/project
claude

会话里，/help 列出可用命令，/clear 开始一段新对话，/exit 退出 Claude Code ^[3]。输入 / 可以看到命令列表，输入 / 加几个字母可以过滤。命令只有在消息开头才会被识别，它后面的文字会成为它的参数 ^[11]。/cost 是 /usage 的别名，用来查看本次会话的花费、套餐用量限制和活动统计；/stats 是另一个别名 ^[11]。

CLAUDE.md：长期有效的指令

CLAUDE.md 是一个 Markdown 文件，用来给 Claude 长期有效的指令。Claude 在每次会话开始时都会读取它 ^[5]。它可以放在几个位置，作用范围各不相同 ^[5]：

• ~/.claude/CLAUDE.md 放适用于所有项目的个人指令。
• ./CLAUDE.md 或 ./.claude/CLAUDE.md 放某一个项目的指令。
• ./CLAUDE.local.md 放只属于本地的个人偏好。

工作目录上层目录里的 CLAUDE.md 和 CLAUDE.local.md 在启动时加载；子目录里的文件则在 Claude 读取、写入或编辑了该目录中的文件之后按需加载 ^[5]。

子智能体

子智能体是一个独立的 Claude 实例，有自己的系统提示词和工具集合。当前项目的子智能体文件放在 .claude/agents/，对所有项目都生效的放在 ~/.claude/agents/ ^[6]。文件开头是 YAML frontmatter 形式的配置，后面是 Markdown 写的系统提示词。只有 name 和 description 是必填的 ^[6]。

文档列出的 frontmatter 字段包括 name、description、tools、disallowedTools、model、permissionMode、maxTurns、skills、mcpServers、hooks、memory、background、effort、isolation 和 color ^[6]。官方的最小示例是 ^[6]：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

这个子智能体只能用 Read、Glob 和 Grep 读取和搜索，并且运行在 sonnet 模型上。description 决定 Claude 什么时候把工作交给它。系统提示词只写一项职责，效果最好。

自定义命令和技能现在合并成了同一套机制。.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会创建 /deploy，工作方式相同 ^[7]。.claude 目录里，commands/*.md 放单文件提示词，agents/*.md 放子智能体定义，skills/<name>/SKILL.md 放可复用的提示词，通过 /name 调用 ^[14]。

权限模式

Claude Code 支持六种权限模式：default、acceptEdits、plan、auto、dontAsk 和 bypassPermissions ^[9]。最先会遇到的是下面两种：

• default 模式下，每个工具第一次使用时 Claude Code 都会请求许可，别名 manual 指的也是这个模式。acceptEdits 模式下，文件编辑和 mkdir、touch、mv、cp 这类常见文件系统命令会自动通过 ^[9]。
• plan 模式下，Claude 可以读文件、运行只读的 shell 命令来探索，但不会修改源代码 ^[9]。

bypassPermissions 会跳过所有权限提示。文档建议只在容器或虚拟机这类隔离环境中使用 ^[9]。

权限规则有 allow、ask 和 deny 三种，按这个顺序求值，格式是 Tool 或 Tool(specifier)。新会话的默认模式用设置文件里的 defaultMode 指定 ^[9]。Claude Code 从四个文件读取设置：~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json 和 managed-settings.json ^[13]。

在命令行里按 Shift+Tab 可以切换模式 ^[10]。想直接从某个模式启动，就加上参数，例如 claude --permission-mode plan ^[10]。

Hooks

Hooks 是在 Claude Code 生命周期的特定节点上自动执行的用户定义动作，可以是 shell 命令、HTTP 端点、MCP 工具调用、LLM 提示，或者一个子智能体 ^[8]。hooks 参考页列出了几十个事件，覆盖会话、工具调用、子智能体、配置变更等节点。事件名必须和参考页一致，写之前先对照一遍。

我们的做法

TellWorld 的日常维护就是在项目仓库里直接用 Claude Code 完成的。仓库里有 Go 写的 API、Astro 做的网站，以及 Node.js 的内容流水线 ^[1]。下面这些是我们自己的选择，不是通用的最佳实践。

我们保留两份指令文件：用户级的 CLAUDE.md 放适用于所有项目的规则，项目级的 CLAUDE.md 放 TellWorld 自己的约定。两份文件都在每次会话开始时加载 ^[1]。

用户级规则里有一些是通用的。比如，绝不结束用户的浏览器进程；新增任何数据库表或字段前必须先征得确认；编译器告警通过改写代码消除，而不是压掉；source map 之类不需要的构建产物，在构建工具的配置里不产出，而不是构建完再删 ^[1]。

项目级文件管的是成本。它要求智能体尽量少消耗额度：少轮询、少截图、少读大文件，汇报保持简短 ^[1]。

Claude Code 还有一套基于文件的记忆，索引文件是 MEMORY.md。我们用它记下一条长期选择：写作和生图不用某些外部模型 ^[1]。

生产环境的访问始终要经过人来决定。在自动模式下，Claude Code 发出的一条连接 TellWorld 生产服务器的 SSH 命令被拦下，直到维护者明确放行才执行 ^[1]。

定期的新闻更新被打包成一个 Claude Code 技能，用斜杠命令 /news-update 启动 ^[1]。这个技能的写法见配套的《怎么写一个 Agent Skill》。

限制和常见问题

• 成本取决于套餐。 在 API 或 Console 账号上按 token 付费，长会话里要留意 /cost ^[11][12]。
• 命令和技能同名时只会有一个。 两者都会创建同一个斜杠命令，所以每个名字只用一种写法 ^[7]。

下一步

按这个顺序读官方文档：先看概览，了解入口和系统要求 ^[2]；再看快速开始，完成第一个会话 ^[3]；然后读记忆页面了解 CLAUDE.md ^[5]；接着是子智能体页面 ^[6]；权限相关的两页 ^[9][10]；hooks 参考页 ^[8]；最后是设置页面，了解优先级 ^[13]。