claude-code-best-practice-zh: Instructions file for Claude Code

CLAUDE.md

此文件在为代码仓库中的代码工作时为 Claude Code（claude.ai/code）提供指导。

仓库概述

这是 Claude Code 配置的最佳实践仓库，展示技能、子代理、钩子和命令的模式。它作为参考实现，而不是应用程序代码库。

关键组件

天气系统（示例工作流）

通过 命令 → 代理 → 技能 架构展示两种不同技能模式的演示：

• /weather-orchestrator 命令（.claude/commands/weather-orchestrator.md）：入口点 — 询问用户 C/F，调用代理，然后调用 SVG 技能
• weather-agent 代理（.claude/agents/weather-agent.md）：使用其预加载的 weather-fetcher 技能获取温度（代理技能模式）
• weather-fetcher 技能（.claude/skills/weather-fetcher/SKILL.md）：预加载到代理中 — 从 Open-Meteo 获取温度的说明
• weather-svg-creator 技能（.claude/skills/weather-svg-creator/SKILL.md）：技能 — 创建 SVG 天气卡片，写入 orchestration-workflow/weather.svg 和 orchestration-workflow/output.md

两种技能模式：通过 skills: 字段预加载的代理技能 vs 通过 Skill 工具调用的技能。参见 orchestration-workflow/orchestration-workflow.md 获取完整流程图。

技能定义结构

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

• name：显示名称和 /斜杠命令（默认为目录名）
• description：何时调用（推荐用于自动发现）
• argument-hint：自动补全提示（如 [issue-number]）
• disable-model-invocation：设为 true 防止自动调用
• user-invocable：设为 false 从 / 菜单中隐藏（仅后台知识）
• allowed-tools：技能活跃时无需权限提示即可使用的工具
• model：技能活跃时使用的模型
• context：设为 fork 在独立的子代理上下文中运行
• agent：context: fork 的子代理类型（默认：general-purpose）
• hooks：作用域限于此技能的生命周期钩子

演示系统

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

钩子系统

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

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

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

特殊处理：git 提交触发 pretooluse-git-committing 声音。

关键模式

子代理编排

子代理 无法 通过 bash 命令调用其他子代理。使用 Agent 工具（在 v2.1.63 中从 Task 重命名；Task(...) 仍然作为别名工作）：

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

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