Day 4 下午场，花了 4 小时精读官方文档，把 Subagent 从头改造了一遍，还系统学了 Git 完整工作流。一共踩了 4 个坑，最狠的一个是——做了一上午的工具，分类全搞错了。

坑1：web_fetch 被 robots.txt 封锁，官方文档读不了

需要读 Claude Code 官方文档，直接用 web_fetch 抓取：

直接用 web_fetch 抓取 https://code.claude.com/docs/zh-CN/overview

返回 ROBOTS_DISALLOWED，权限错误，读不了。

正确做法：

调用 Claude in Chrome 浏览器工具→ tabs_context_mcp 获取标签页→ navigate 导航到目标 URL→ get_page_text 读取页面内容

踩坑原因：web_fetch 遵守 robots.txt，浏览器工具直接渲染页面，绕过了限制。

记住：官方文档被 robots.txt 封锁时，换用 Claude in Chrome 浏览器工具导航读取。

概念：Skills 和旧版 commands 是同一个东西

官方文档原文：

自定义命令已合并到 skills 中。

.claude/commands/ = .claude/skills/（等价）

什么时候会用到：判断一个工具是 Skill 还是 Subagent，先看文件在哪个目录——放 skills/ 就是 Skill，放 agents/ 才是 Subagent。

以为命名问题搞清楚就完事了——没想到接下来这个才是最大的坑。

坑2：上午做的工具，分类全搞错了

一上午把 /check-api、/audit-frontend 都当成 Subagent 来设计，做完才发现：放在 .claude/skills/ 或 .claude/commands/ 目录下的，全都是 Skills，不是 Subagent。

踩坑原因：混淆了 Skills 和 Subagents 的概念，没有先读文档就动手做。

记住：AI 编程前先读官方文档，搞清楚机制再下手，否则方向错了全部返工。

概念：四大机制全景图，选工具不再混淆

什么时候会用到：每次新建工具前，先对照这个表判断用哪个机制。

技巧1：Skills frontmatter 调用控制字段

有副作用的 Skill（比如 /smart-commit），必须防止 CC 自动触发：

---name: my-skilldescription: 触发条件描述disable-model-invocation: true   # 只有你能触发，CC 不自动调用user-invocable: false            # 只有 CC 能调用，不出现在 / 菜单allowed-tools: Read, Grep, Bashcontext: fork                    # 在子代理中运行---$ARGUMENTS 占位符

效果：有副作用的 Skill 必须加 disable-model-invocation: true，否则 CC 可能在你不知情的情况下自动执行。

技巧2：Subagents frontmatter 标准配置

---name: check-apidescription: API 健康检查专家。当需要检测后端接口是否正常、验证 API 服务状态时使用。tools: Bash, Readmodel: haiku                     # 指定模型，省钱permissionMode: dontAsk          # default / acceptEdits / dontAsk / bypassPermissionsmemory: user                     # 持久记忆：user / project / local---系统提示内容

效果：permissionMode: dontAsk + model: haiku 是只读+执行脚本类 Subagent 的黄金组合，消除权限弹窗，大幅降低 token 成本。

坑3：Subagent 看不到主对话历史，重复创建了脚本

把 /check-api 改造成 Subagent 后，让它去执行 API 检查，CC 先用 ls 探测目录：

Bash(ls -la D:\AiWorkSpace\my-shop\scripts 2>/dev/null || echo "scripts 目录不存在")

脚本明明存在，Subagent 却准备重新生成一份。

正确做法：在 Subagent 系统提示里明确写清：

第二步：直接执行已有脚本（不要重新生成）执行：python scripts/check_api.py脚本已存在，直接执行即可

踩坑原因：Subagent 在新实例中运行，上下文是空的，看不到主对话历史，不知道项目结构。

记住：Subagent 系统提示里必须写清"脚本已存在于 xxx 路径，直接执行，不要重新生成"。

坑4：Subagent 执行 Bash 命令时频繁弹权限询问

Subagent 文件里没配置 permissionMode，执行多行 Bash 命令时 CC 弹出：

Bash command contains newlines, confirm execution?

每次都要手动确认，打断了自主执行。

正确做法：frontmatter 加一行：

permissionMode: dontAsk

或者在 CLAUDE.md 里永久声明：

## 执行权限以下操作无需询问确认，直接执行：- 创建/修改项目内的文件- 执行终端命令（npm/python/curl/git）- 发起 localhost 的网络请求

踩坑原因：CC 对含换行符的 Bash 命令默认触发安全确认，Subagent 没单独配置时继承这个行为。

记住：只读+执行脚本类 Subagent 标配 permissionMode: dontAsk。

概念：Subagent 独立上下文机制

主对话上下文    ├── 你的对话历史（Subagent 看不到）    ├── CLAUDE.md（会加载）    └── 委派任务 → [新实例] Subagent                       ├── 全新的上下文窗口（空的）                       ├── 只有 Subagent 自己的系统提示                       ├── 执行任务...                       └── 返回结果摘要 → 主对话（只有摘要进主上下文）

什么时候会用到：每次写 Subagent 系统提示前，先想清楚"它看不到的信息，我有没有在提示里写清楚"。

上面是机制层面。接下来是工程化和 Git 实操——项目越大，这部分越重要。

概念：解决"重复建设 + CLAUDE.md 不更新"的三套方案

方案一：/project-sync Skill（推荐先做）

---name: project-syncdescription: 项目同步检查，定期运行以发现重复文件、更新 CLAUDE.mddisable-model-invocation: true---扫描 scripts/、.claude/agents/、.claude/skills/ 目录找出功能疑似重复的文件，审查 CLAUDE.md 是否过期生成更新建议报告，询问是否确认更新

方案二：CLAUDE.md 工具清单登记制度

## 项目工具清单| 文件 | 功能 | 状态 ||------|------|------|| scripts/check_api.py | API 健康检测 | ✅ 现役 |## 强制规则新建 scripts/、.claude/agents/、.claude/skills/ 下的文件前，先检查本清单，确认无重复后再创建，创建后立即更新本清单。

方案三：/new-tool Skill 统一入口

用法：/new-tool check_api.py 用于检测接口健康状态功能：新建前检查重复 → 确认无重复 → 创建 → 自动更新 CLAUDE.md 清单

三套方案从"定期巡检"→"登记规范"→"创建拦截"层层递进，推荐执行顺序：方案一 → 方案二 → 方案三。

概念：everything-claude-code 优秀案例对比

核心差距：自己的方案是"人治"，优秀案例是"系统治"。

下一步升级方向：建立 .claude/rules/ 目录 + doc-updater Subagent + 持续学习系统。

技巧3：Claude Code token 优化配置

{  "model": "sonnet",  "env": {    "MAX_THINKING_TOKENS": "10000",    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"  }}

效果：Subagent 隔离大量输出，主对话只收摘要，长任务下总消耗反而更低。

技巧4：Git 完整协作流程（分支→PR→合并→同步→清理）

# 第一阶段：提交代码到分支git branch -a                              # 查看所有分支git checkout -b feature/subagent-check-api # 创建并切换git add .                                  # 暂存所有改动git commit -m "feat(subagent): 新增 check-api subagent 实现 API 健康检测自动委派"# 第二阶段：推送到远程git push origin feature/subagent-check-api# 第三阶段：GitHub 上处理 PR（手动）# → Compare & pull request → 填写标题和描述 → Merge pull request# → 推荐选 "Squash and merge"（个人项目保持主线干净）# → Delete branch（合并后直接删远程分支）# 第四阶段：本地同步 maingit checkout maingit pull origin main# 第五阶段：删除本地分支git branch -d feature/subagent-check-api   # -d 安全删除（已合并才能删）git branch -a                              # 验证清理结果

效果：完整 Git 协作闭环，从功能开发到代码合并全流程独立操作。

概念：三种 PR 合并方式的区别

什么时候会用到：个人项目日常用 Squash and merge，避免主线被零散 commit 污染。

技巧5：Git 撤销和回滚操作速查

核心原则：

没 push 出去 → 用 reset 随便改历史已经 push → 只能用 revert 生成新提交抵消，不能改历史

技巧6：让 Claude Code 自动生成 commit message

方式 A：直接对话：

帮我把当前所有修改提交，生成规范的提交信息

方式 B：/smart-commit Skill（推荐）：

---name: smart-commitdescription: 分析当前改动，生成规范提交信息并执行提交disable-model-invocation: true---第一步：了解改动全貌执行：git diff --staged 和 git diff，理解本次改动内容第二步：生成提交信息（Conventional Commits 规范）- feat: 新功能- fix: 修复 bug- refactor: 重构- docs: 文档更新- chore: 构建/工具变动第三步：暂存并提交git add .git commit -m "生成的提交信息"第四步：询问是否推送告诉我提交完成，问是否需要 git push origin 当前分支

效果：CC 自动 git diff 分析改动，生成符合 Conventional Commits 规范的提交信息，不再手写。

概念：Git merge vs rebase 的区别

merge（保留历史，有合并节点）：A---B---C  main     \      D---E  feature          ↓ git merge featureA---B---C---F  main（F是合并节点）         \ /          D---Erebase（线性历史，更干净）：A---B---C---D'---E'  main（D/E被移植过来，成为新提交）

什么时候会用到：初学者日常用 merge 保持历史清晰；熟练后可用 rebase 维护干净的线性历史。

今日踩坑清单

关键配置备忘

Claude Code token 优化配置（~/.claude/settings.json）：

{  "model": "sonnet",  "env": {    "MAX_THINKING_TOKENS": "10000",    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"  }}

Subagent frontmatter 标准模板（只读+执行类）：

---name: check-apidescription: API 健康检查专家。当需要检测后端接口是否正常时使用。tools: Bash, Readmodel: haikupermissionMode: dontAsk---

Skills 防误触发配置（有副作用的操作）：

---name: smart-commitdescription: ...disable-model-invocation: true---

Prompt 技巧速查：

先读文档再动手，能省掉一上午返工的时间。Subagent 的独立上下文机制，是 Claude Code AI 编程里最容易踩坑的地方。

你在用 Claude Code 做 AI 编程的时候，有没有遇到过 Subagent 不按预期执行的情况？当时是怎么解决的？

明天继续：实操 Git 完整流程 + 建立 .claude/rules/ 目录 + 创建 /smart-commit Skill。

#AI编程# #ClaudeCode# #Git工作流# #零基础编程##氛围编程#