Agent 工具使用笔记——Claude Code

Claude Code 是 Anthropic 官方的终端型 coding agent。它在本地项目目录里运行，可以读代码、改文件、执行命令，也能通过 CLAUDE.md、settings、slash commands、MCP、hooks 这些机制适配项目工作流。

这里先只记官方 Claude Code 的基本用法。第三方 Anthropic-compatible API 的接入放到 API 那篇里。

安装和启动

官方快速开始要求 Node.js 18 或更新版本，登录用 Claude.ai 账号或 Anthropic Console 账号。

1
2
3

npm install -g @anthropic-ai/claude-code
cd your-project
claude

第一次运行 claude 按提示登录即可。我一般在 Git 仓库根目录启动，省得上下文和可写范围混乱。

常用命令

claude
claude --version
claude config list
claude config get <key>
claude config set <key> <value>
claude config set -g <key> <value>

claude config 默认修改项目配置；加 -g / --global 修改用户级全局配置。

settings.json

settings.json 用来配权限、环境变量和工具行为。

常用位置：

~/.claude/settings.json：用户级配置，作用于所有项目。
.claude/settings.json：项目共享配置，可以提交到仓库。
.claude/settings.local.json：项目本地个人配置，不应提交。
企业托管配置：由组织在系统位置统一下发，优先级最高。

配置优先级从高到低：

Enterprise managed policies
Command line arguments
Local project settings
Shared project settings
User settings

常见配置示例：

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "120000"
  }
}

敏感文件最好直接用 permissions.deny 藏掉，不要只靠口头提醒 agent “不要读”。

CLAUDE.md memory

CLAUDE.md 是 Claude Code 的 memory 文件，适合放项目说明、常用命令、代码风格和长期偏好。

常见位置：

~/.claude/CLAUDE.md：用户 memory，只对自己生效。
./CLAUDE.md：项目 memory，适合随仓库共享。
企业级 CLAUDE.md：组织统一下发。

初始化项目 memory：

/init

编辑 memory：

/memory

也可以在输入中用 # 快速添加一条 memory，然后按提示选择写入位置。

适合写入 CLAUDE.md 的内容：

常用 build / test / lint 命令。
项目架构和目录约定。
命名、代码风格、测试约定。
只对该项目长期成立的注意事项。

不要写入 API key、token、私有代理账号或一次性任务提示。

slash commands

Claude Code 的交互命令以 / 开头。我常看的主要是：

/help：查看帮助。
/status：查看账号和系统状态。
/config：查看或修改配置。
/permissions：查看或更新权限。
/model：选择或切换模型。
/clear：清空当前会话历史。
/compact：压缩上下文。
/memory：编辑 memory 文件。
/mcp：管理 MCP 连接。
/review：请求代码审查。

自定义 slash command 本质上是 Markdown 文件：

1 2	.claude/commands/<command-name>.md ~/.claude/commands/<command-name>.md

项目级 command 可以提交给团队共享，用户级 command 适合个人常用 prompt。命令名来自文件名，例如 .claude/commands/security-review.md 对应 /security-review。

权限和工具

Claude Code 可以读文件、搜索、编辑、执行 shell，也有 WebFetch、WebSearch、Notebook 等工具。读文件和搜索通常比较低风险，编辑、写文件、执行命令、联网这些则要看权限规则。

我的基本做法：

项目共享配置中允许稳定的检查命令，例如 lint、test。
明确 deny .env、secrets、credentials、部署凭据。
对 curl、发布命令、删除命令、云服务命令保持默认询问或禁止。
不把 API key 写进 .claude/settings.json 或 CLAUDE.md。

排查顺序

用官方登录方式确认 Claude Code 本身可用。
用 /status 检查账号、模型和系统状态。
用 /doctor 检查安装健康状态。
检查 settings.json 是否覆盖了权限或环境变量。
检查 CLAUDE.md 是否包含过期命令或冲突说明。
权限问题优先看 /permissions 和 permissions.deny / permissions.allow。