type: daily_note
title: 刘小排 Phase 1 补完 - Claude Code 高级功能 + 自动备份/Git Hook
date: 2026-07-18
person: 刘小排
phase: 1
---
# 2026-07-18 学习笔记
## 笔记区（学的时候随手记）
### 核心观点
- Claude Code 的功能远不止写代码，它是一个完整的开发环境（CLI 工具箱 + Hook 自动化 + Plugin 生态）
- 一个功能如果官方文档 fetch 不到，直接跑 `claude --help` 或实测验证，不要编
- Plugin 就是 skill 的包装分发机制，没有想象中复杂
- Hook 系统的核心价值：自动化的安全网和记录仪
- 自动备份 + Git commit 双保险：有仓库没仓库都能回滚
### 关键方法/流程
**本次确认的 Claude Code CLI 完整工具箱：**
1. **`claude --worktree / -w`**
- 开个隔离小房间，让另一个 Claude 进去干活，不影响你现在的工作区
- 需要 git 仓库才能用，否则报错
- 跟 `--bg` 区别：`-w` 开个前台新会话（你看着它干活），`--bg` 丢后台跑（你看不见，关终端也不死）
2. **`claude agents`** — 后台会话管理
- `claude --bg "任务"` → 启动后台会话
- `claude agents` / `claude agents --json` → 管理，可看状态
- 当前后台会话用 `claude agents --json` 查看
3. **Settings 三级体系：** 用户级(~/.claude/settings.json) → 项目级 → 本地级(settings.local.json)，层层覆盖
4. **Hook 系统：**
- PreToolUse：操作前触发（备份、安全检查、CLAUDE.md 门禁）
- PostToolUse：操作后触发（格式化、语法检查、git commit）
- 当前共 7 个 hook 脚本
5. **自定义 Agent 人格（纠正后）：** `.claude/agents/<name>.md` 文件 + YAML frontmatter
- `--agents JSON` 参数实测不生效，正确的做法是写文件
- 优先级：内置 > CLI 参数 > 项目级 > 用户级 > 插件
6. **Plugin 系统：** 就是 skill 的打包分发机制
- 已装：code-review / claude-hud / security-guidance / frontend-design / skill-creator
- 插件里的 skill 带命名空间（`plugin-name:skill-name`）防冲突
7. **`--output-format` / `--json-schema`**
- `--output-format json`：让 Claude 的回答不跟你聊天，直接吐 JSON 格式数据，给脚本用的
- `--json-schema 你的格式定义`：强制 Claude 按你规定的格式输出。比如你规定要返回 `message`（文字）和 `length`（数字），它就只给你这两个字段
- 实战场景：你写个脚本每天早上让 Claude 分析日志，脚本只要数据不要人看，直接拿 JSON 结果继续跑
8. **Effort Level：** `--effort low/medium/high/xhigh/max`，当前默认 high
9. **Context 管理：** Compaction（自动压缩旧内容）+ Prompt caching（缓存固定内容）
10. **`--bare` 极简模式：** 跳过 hook/LSP/plugin/CLAUDE.md 自动发现，纯干活（CLAUDE.md 需手动加载）
11. **`claude doctor`：** 健康检查，更新出问题时用
### 实战记录
**1. 自动备份 + Git Commit 双保险 Hook**
- 新建 `~/.claude/hooks/auto-backup.sh` → PreToolUse，每次 Write/Edit 前备份原文件
- 新建 `~/.claude/hooks/git-auto-commit.sh` → PostToolUse，有 git 仓库时自动 commit
- 备份路径：`~/.claude/backups/<盘符>/<原路径>/<文件名>_<时间戳>.bak`
- commit 格式：`auto(Write): /路径/文件`
- 注册到 `~/.claude/settings.json` 全局生效
**2. 自定义 Agent 的正确方式**
- 在 `.claude/agents/` 目录下放 Markdown 文件，带 YAML frontmatter 定义 name、description、tools 等
- 优先级：内置 > CLI 参数 > 项目级 > 用户级 > 插件
- 注意：`claude --agents` 命令行方式定义的 prompt 会被 CLAUDE.md 覆盖，不生效
**3. `claude --worktree` 报错**
- 在 `C:\Users\AR-fi` 跑 `claude -w` 报错
- 原因：用户目录不是 git 仓库
- 解决：必须在 git 仓库根目录内跑
**4. Hook PreToolUse 门禁**
- 每次操作前检查是否读过 CLAUDE.md -> 没读就拦截
- 被拦了一整天，但用户认为这是必要的
---
## 线索区（学完后合上材料，自问自答）
> 先看问题 → 自己回答 → 点开对照。答不上来的就是没学透。
**Q: 有 git 仓库和没 git 仓库的场景，怎么分别回滚代码？**
A: 有仓库 → `git log --oneline` 找 commit → `git reset --hard HEAD~N` 或 `git reset --hard <hash>`。没仓库 → `Get-ChildItem ~/.claude/backups/ -Recurse` 找备份 → `Copy-Item` 恢复。
**Q: Plugin 和普通 skill 有什么区别？**
A: Plugin 是 skill 的包装盒。plugin 可以带 skill + hook + agent + MCP 一起打包，有命名空间防冲突。普通 skill 就是一个 .md 文件放 `~/.claude/skills/` 下。
**Q: `--bare` 和 `-p` 的区别？**
A: `-p` 是问完就走不交互。`--bare` 是连 hook/plugin/LSP 全跳过，CLAUDE.md 不自动加载。可以组合用：`claude --bare -p "问题"`（待实测确认）
**Q: 为什么 `--agents JSON` 方式定义自定义 Agent 不生效？**
A: 正确的定义方式是把 .md 文件放 `.claude/agents/` 目录下，带 YAML frontmatter。`--agents` 命令行参数的定义会被 CLAUDE.md 和默认系统 prompt 覆盖。
**Q: security-guidance 插件怎么工作的？它拦不拦截操作？**
A: 三层：① 写文件时正则检测危险模式（yaml.load、pickle）② 写完 LLM 审查 diff ③ commit 时跨文件追踪。只是提醒+让 Claude 自动修，不拦截。
---
## 总结（50字以内）
Claude Code CLI 工具箱全过了一遍，亲手配了自动备份+git commit 双保险 hook，纠正了自定义 agent 的错误理解，Plugin 就是 skill 包装盒。
---
## 复习卡片
| 概念 | 一句话 | 我的场景 |
| `claude --bg` | 启动后台独立 Claude 会话 | 睡觉时派复杂任务 |
| `claude -w` | 开隔离 worktree + 新 Claude 会话 | 跟 --bg 区别：前台+隔离，后台无隔离 |
| Settings 三级 | 本地级 > 项目级 > 用户级 | 个人覆盖项目配置 |
| Hook 系统 | 操作前后自动触发脚本 | 备份/格式化/语法检查/git commit |
| 自定义 Agent | `.claude/agents/name.md` 文件定义 | 专用审查/教学角色 |
| Plugin | skill 的打包分发机制 | code-review、hud 等现成功能 |
| `--json-schema` | 强制 Claude 输出结构化 JSON | 脚本里调 Claude 自动化 |
| Effort Level | 控制思考深度和 token 消耗 | 简单问题 low，复杂问题 max |
| auto-backup hook | Write/Edit 前自动备份原文件 | 没 git 仓库也能回滚 |
| git-auto-commit hook | Write/Edit 后自动 git commit | 有仓库随时 reset 回滚 |
