CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指导。

仓库概述

这是 Claude Code 配置的最佳实践仓库，演示了 Skills、Subagents、Hooks 和 Commands 的模式。它作为参考实现，而非应用代码库。

关键组件

天气系统（示例工作流）

通过 命令 → Agent → Skill 架构演示两种不同的 Skill 模式：

• /weather-orchestrator 命令 (.claude/commands/weather-orchestrator.md)：入口点——询问用户温度单位（摄氏/华氏），调用 agent，然后调用 SVG skill
• weather-agent agent (.claude/agents/weather-agent.md)：使用其预加载的 weather-fetcher skill 获取温度（agent skill 模式）
• weather-fetcher skill (.claude/skills/weather-fetcher/SKILL.md)：预加载到 agent 中——从 Open-Meteo 获取温度的指令
• weather-svg-creator skill (.claude/skills/weather-svg-creator/SKILL.md)：Skill——创建 SVG 天气卡片，写入 orchestration-workflow/weather.svg 和 orchestration-workflow/output.md

两种 Skill 模式：agent skills（通过 skills: 字段预加载）vs skills（通过 Skill 工具调用）。完整流程图见 orchestration-workflow/orchestration-workflow.md。

Skill 定义结构

.claude/skills/<name>/SKILL.md 中的 Skills 使用 YAML frontmatter：

• name：显示名称和 /slash-command（默认为目录名）
• description：何时调用（建议用于自动发现）
• argument-hint：自动补全提示（如 [issue-number]）
• disable-model-invocation：设为 true 可防止自动调用
• user-invocable：设为 false 可从 / 菜单中隐藏（仅作为背景知识）
• allowed-tools：Skill 激活时无需权限提示即可使用的工具
• model：Skill 激活时使用的模型
• context：设为 fork 可在隔离的 subagent 上下文中运行
• agent：context: fork 的 subagent 类型（默认：general-purpose）
• hooks：此 Skill 作用域内的生命周期 Hooks

演示系统

参见 .claude/rules/presentation.md——所有演示工作都委托给 presentation-curator agent。

Hooks 系统

.claude/hooks/ 中的跨平台声音通知系统：

• scripts/hooks.py：Claude Code hook 事件的主处理器
• config/hooks-config.json：团队共享配置
• config/hooks-config.local.json：个人覆盖（git 忽略）
• sounds/：按 hook 事件组织的音频文件（通过 ElevenLabs TTS 生成）

.claude/settings.json 中配置的 Hook 事件：PreToolUse、PostToolUse、UserPromptSubmit、Notification、Stop、SubagentStart、SubagentStop、PreCompact、SessionStart、SessionEnd、Setup、PermissionRequest、TeammateIdle、TaskCompleted、ConfigChange。

特殊处理：git commit 会触发 pretooluse-git-committing 声音。

关键模式

Subagent 编排

Subagents 不能通过 bash 命令调用其他 subagents。请使用 Agent 工具（在 v2.1.63 中从 Task 重命名；Task(...) 仍作为别名可用）：

Agent(subagent_type="agent-name", description="...", prompt="...", model="haiku")

在 subagent 定义中明确说明工具使用。避免使用可能被误解为 bash 命令的模糊术语（如 "launch"）。

Subagent 定义结构

.claude/agents/*.md 中的 Subagents 使用 YAML frontmatter：

• name：Subagent 标识符
• description：何时调用（使用 "PROACTIVELY" 进行自动调用）
• tools：逗号分隔的工具允许列表（省略则继承所有）。支持 Agent(agent_type) 语法
• disallowedTools：要拒绝的工具，从继承或指定列表中移除
• model：模型别名：haiku、sonnet、opus 或 inherit（默认：inherit）
• permissionMode：权限模式（如 "acceptEdits"、"plan"、"bypassPermissions"）
• maxTurns：subagent 停止前的最大 agent 回合数
• skills：预加载到 agent 上下文中的 skill 名称列表
• mcpServers：此 subagent 的 MCP 服务器（服务器名称或内联配置）
• hooks：此 subagent 作用域内的生命周期 Hooks（支持所有 hook 事件；PreToolUse、PostToolUse 和 Stop 最常用）
• memory：持久记忆范围——user、project 或 local（参见 reports/claude-agent-memory.md）
• background：设为 true 则始终作为后台任务运行
• effort：努力级别覆盖：low、medium、high、max（默认：继承自会话）
• isolation：设为 "worktree" 则在临时 git worktree 中运行
• color：CLI 输出颜色，用于视觉区分

配置层级

1. 托管 (managed-settings.json / MDM plist / Registry)：组织强制，不可覆盖
2. 命令行参数：单会话覆盖
3. .claude/settings.local.json：个人项目设置（git 忽略）
4. .claude/settings.json：团队共享设置
5. ~/.claude/settings.json：全局个人默认值
6. hooks-config.local.json 覆盖 hooks-config.json

禁用 Hooks

在 .claude/settings.local.json 中设置 "disableAllHooks": true，或在 hooks-config.json 中禁用单个 Hooks。

回答最佳实践问题

当用户提出 Claude Code 最佳实践问题时，始终先搜索此仓库（best-practice/、reports/、tips/、implementation/ 和 README.md），然后再依赖训练知识或外部来源。此仓库是权威来源——仅在找不到答案时才回退到外部文档或网络搜索。

工作流最佳实践

根据本仓库的经验：

• 将每个 CLAUDE.md 文件控制在 200 行以内以确保可靠遵从
• 使用 commands 而非独立 agents 来执行工作流
• 创建具有 Skills（渐进式披露）的特定功能 subagents，而非通用 agents
• 在上下文使用量达到约 50% 时手动执行 /compact
• 对复杂任务先使用 plan 模式
• 对多步骤任务使用人工审核的任务列表工作流
• 将子任务拆分到能在 50% 上下文内完成的大小

调试技巧

• 使用 /doctor 进行诊断
• 将长时间运行的终端命令作为后台任务运行以获得更好的日志可见性
• 使用浏览器自动化 MCP（Claude in Chrome、Playwright、Chrome DevTools）让 Claude 检查控制台日志
• 报告视觉问题时提供截图

文档

文档标准参见 .claude/rules/markdown-docs.md。关键文档：

• best-practice/claude-subagents.md：Subagent frontmatter、hooks 和仓库 agents
• best-practice/claude-commands.md：斜杠命令模式和内置命令参考
• orchestration-workflow/orchestration-workflow.md：天气系统流程图