Claude Code CLI 学习笔记

记录每节课的核心要点，便于日后快速回顾。

第1课：项目配置基础

三层 CLAUDE.md

关键文件

• CLAUDE.md — Claude 每次对话都会读，写清楚它就听话
• settings.json — 团队共享的权限和 hooks（提交 git）
• settings.local.json — 个人私有配置（不提交 git）
• .gitignore — 安全底线，.env 和 settings.local.json 绝不提交

要点

1. /init 可以自动生成初始 CLAUDE.md
2. CLAUDE.md 越清晰，AI 输出越精准
3. 新项目第一件事：init git + 写 CLAUDE.md + 配 settings.json

第2课：日常高效操作

Prompt 五段位

不确定时的三种方法

1. 追问法：”你觉得应该怎么设计？先给方案，不要直接写代码”
2. 选项法：”给我 2-3 个方案，我选一个你再写”
3. 场景法：”场景是 xxx，你来设计需要哪些函数，列出来我确认”

口诀：不确定就让 Claude 先出方案，你只负责选。

斜杠命令

快捷键

核心习惯：Claude 跑偏 → 立刻 Esc，不要等它写完再纠正。

第3课：权限管理

三层权限架构

全局 ~/.claude/settings.json        → 个人习惯，所有项目通用
项目 .claude/settings.json          → 团队共享，提交 git
本地 .claude/settings.local.json    → 私有配置，不提交

优先级：本地 > 项目 > 全局

deny 永远赢

• 任何层的 deny 都不可被其他层的 allow 覆盖
• 这是安全设计的基石

匹配语法

Bash(git status)     ← 精确匹配
Bash(git log*)       ← 前缀通配
Bash(npm *)          ← 允许所有 npm 子命令
Read(**)             ← 允许读取任何文件

安全等级

🟢 安全（只读）     git status, git log*, ls*, find*, which*
🟡 中等（副作用）   npm test*, npm run build*
🔴 危险（别白名单） rm *, git push --force*, Edit(**)

什么放哪里

实用命令

• /fewer-permission-prompts — 扫描历史，自动添加常用命令到白名单（积累一段时间后再用）

第4课：Hooks 自动化

4个触发点

Hook 配置结构

{
  "hooks": {
    "触发点": [
      {
        "matcher": "工具名",    // 空 = 匹配所有
        "hooks": [
          {
            "type": "command",
            "command": "要执行的命令或脚本路径"
          }
        ]
      }
    ]
  }
}

PreToolUse 返回值

matcher 值

执行顺序

• 同触发点：全局 Hook 先执行，项目 Hook 后执行
• 任何一个返回 block 就停止后续执行

双重保护设计

第1道：permissions.deny     ← 静态字符串匹配
第2道：PreToolUse Hook     ← 灵活脚本检测（grep/正则/外部工具）

注意事项

• Hook 脚本必须 chmod +x 加执行权限
• 脚本通过 stdin 接收 JSON，stdout 返回 JSON
• Hook 应快速执行（<5秒），否则影响交互体验

第5课：MCP 进阶

MCP 是什么

MCP Server 是独立进程，Claude 通过标准协议调用它提供的”工具”，扩展能力边界。

Claude Code ←→ MCP 协议 ←→ MCP Server ←→ 外部服务

配置结构

{
  "mcpServers": {
    "服务名": {
      "command": "启动命令",
      "args": ["参数"],
      "env": { "KEY": "value" }
    }
  }
}

配置位置

常用 MCP Server

安全三问

1. 这个 MCP server 能访问什么？（沙盒范围）
2. 我信任这个 server 的代码吗？（官方 vs 第三方）
3. Token/Key 放哪里？（永远放 local，不放项目级）

注意事项

• 修改 MCP 配置后必须重启 Claude Code 才生效
• MCP server 在会话启动时连接，中途修改不会自动重载

第6课：Sub-agents 子代理

核心价值

• 保护上下文 — 探索/搜索结果不污染主对话
• 专业分工 — 每个子代理有专属 prompt 和工具集
• 控制成本 — 可用更便宜的模型（如 Haiku）
• 安全隔离 — 限制子代理只能读不能写

定义方式

文件格式：Markdown + YAML frontmatter，存放在：

• .claude/agents/ — 项目级（提交 git，团队共享）
• ~/.claude/agents/ — 用户级（所有项目可用）

关键 Frontmatter 字段

调用方式

1. 自动 — Claude 根据 description 自动委派（推荐）
2. /agents — 管理面板，查看/创建/编辑
3. CLI — claude --agents '{...}' 动态定义

工具权限设计

只读搜索 → tools: Read, Grep, Glob
能跑命令 → tools: Read, Grep, Glob, Bash + disallowedTools: Write, Edit
完全信任 → 不写 tools（继承全部，慎用）

内置子代理

与其他并行方式的区别

第7课：并行工作流

三种并行方式

Agent View 核心操作

claude agents                  # 打开监控台
claude --bg "任务描述"          # 派发后台任务
claude attach <id>             # 附加到会话介入
claude logs <id>               # 查看日志
claude stop <id>               # 停止
claude rm <id>                 # 移除

• 后台会话自动使用 worktree 隔离
• 关闭终端后会话仍在运行（daemon）
• 需要人工介入时 attach 进去

Worktree 工作流

claude -w fix-auth                # 创建 worktree + 进入
claude -w #123                    # 从 PR 创建
claude -w name --tmux             # 配合 tmux 多窗口
git worktree list                 # 查看所有
git worktree remove <path>        # 删除

路径：项目/.claude/worktrees/<name>/

隔离原理：独立 git checkout，文件互不可见。

-w 背后的 git 操作详解

执行 claude -w fix-auth-bug 等价于以下 git 命令序列：

# 1. 创建 worktree（独立目录 + 新分支）
git worktree add .claude/worktrees/fix-auth-bug -b fix-auth-bug
#   → 在 .claude/worktrees/fix-auth-bug/ 生成项目完整副本
#   → 自动创建并切换到 fix-auth-bug 分支（基于当前 HEAD）

# 2. Claude Code 将工作目录设为 worktree 路径
#   → 所有 Read/Write/Edit/Bash 操作在 worktree 内执行
#   → 主目录完全不受影响

# 3. 退出会话时提示：keep 或 remove

完整生命周期

# 创建 + 进入
claude -w fix-auth-bug

# --- 在 worktree 会话中 ---
# 修改文件、提交
git add examples/auth.ts
git commit -m "fix: 修复 null 检查"

# --- 退出会话后 ---
# 合并回主分支
git merge fix-auth-bug

# 清理
git worktree remove .claude/worktrees/fix-auth-bug
git branch -d fix-auth-bug

为什么不用 git stash + 切分支？

/batch 批量重构

/batch "把所有 console.log 替换为 logger.info"
→ 自动拆成 5-30 个子代理
→ 每个在独立 worktree 中工作
→ 每个完成后开 PR

适用：import 迁移、API 升级、风格统一、依赖替换。

选择指南

同时修多个独立 bug     → Agent View
实验性方案不影响 main  → 单个 Worktree
200 个文件批量改       → /batch
任务中间搜索大量代码   → Sub-agents（第6课）

注意事项

• 并行 = token 消耗翻倍
• 多个 worktree 改同一文件会冲突
• 先想清楚谁改哪些文件再拆分
• 并行的前提是任务之间无依赖

第8课：Headless & CLI 自动化

-p 打印模式

非交互执行，结果输出到 stdout 后退出。可以当普通命令行工具用。

# 基本用法
claude -p "分析这个项目的架构"

# 管道输入
cat error.log | claude -p "解释这些错误"

# 输出为 JSON（便于脚本解析）
claude -p "列出安全问题" --output-format json

# 限制预算
claude -p --max-budget-usd 1.00 "重构 auth 模块"

# 限制轮次
claude -p --max-turns 5 "写单元测试"

管道组合（Unix 哲学）

# 分析最近的日志
tail -200 app.log | claude -p "有异常吗？"

# 审查变更的文件
git diff main --name-only | claude -p "这些文件有安全风险吗"

# 批量翻译
claude -p "把新增的字符串翻译成法语，提一个 PR"

写进脚本

#!/bin/bash
# check-security.sh — 一键安全扫描
result=$(claude -p "扫描 examples/ 的安全漏洞，输出JSON格式" --output-format json)
echo "$result" | jq '.vulnerabilities'

CI/CD 集成

# GitHub Actions 示例
- name: Security scan
  run: |
    claude -p "审查这个 PR 的安全风险" \
      --output-format json \
      --max-turns 3 \
      --allowedTools "Read" "Grep" "Glob"

关键 flags

• Previous
  CodeBuddy CLI 团队使用指南