# https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know 项目说明书

生成时间：2026-07-04 01:45:04 UTC

## 目录

- [Claude Code 概述与安装配置](#page-overview)
- [技能与斜杠命令](#page-skills)
- [钩子系统（Hooks）](#page-hooks)
- [子代理与专业代理](#page-subagents)
- [代理团队协调](#page-agent-teams)
- [MCP 模型上下文协议集成](#page-mcp)
- [提示工程与努力级别](#page-prompting)
- [模型、FAQ 与更新日志](#page-reference)

<a id='page-overview'></a>

## Claude Code 概述与安装配置

### 相关页面

相关主题：[技能与斜杠命令](#page-skills), [提示工程与努力级别](#page-prompting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/README.md)
- [.claude/settings.json](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/settings.json)
- [CONTRIBUTING.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/CONTRIBUTING.md)
- [LICENSE](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/LICENSE)
- [docs/installation.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/installation.md)
- [docs/overview.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/overview.md)
- [.gitignore](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.gitignore)
</details>

# Claude Code 概述与安装配置

本页面向新用户介绍 Claude Code 的核心定位、安装步骤与基础配置方式，所有内容均以本仓库内现有文件为依据。

## 一、Claude Code 是什么

Claude Code 是 Anthropic 提供的命令行（CLI）形态的 AI 编程助手，旨在把大语言模型的能力直接嵌入开发者的本地开发环境。项目仓库 `wesammustafa/Claude-Code-Everything-You-Need-to-Know` 作为一份汇总性指南，整理了 Claude Code 的关键概念、命令、配置项与常见用例。

仓库本身通过根目录的 `.claude/settings.json` 演示了 Claude Code 在工程中的配置入口，证明其既可作为终端交互工具，也可与项目级配置深度集成。资料来源：[README.md:1-40]()

仓库定位于"Everything-You-Need-to-Know"，意味着读者既能在此获得入门指引，又能通过子文档深入特定主题。资料来源：[README.md:5-20]()

## 二、安装前置条件

在执行安装前，需要确认本地环境满足以下条件：

| 组件 | 要求 | 说明 |
|---|---|---|
| Node.js | ≥ 18.x | Claude Code CLI 基于 Node.js 运行 |
| npm / pnpm / yarn | 任选其一 | 用于全局安装 CLI 包 |
| API Key | Anthropic API Key | 通过环境变量注入 |
| 终端 | 支持 ANSI | 用于展示输出与进度 |

资料来源：[docs/installation.md:10-35]()

如已有 Node.js 环境，可跳过运行时检查，直接进入下一步。

## 三、安装步骤

仓库建议的安装流程分为三步：获取工具、注入凭据、验证版本。

1. **全局安装 CLI**：在终端执行 `npm install -g @anthropic-ai/claude-code`（或仓库文档中记载的等价命令），将命令注册到 PATH。资料来源：[docs/installation.md:40-55]()
2. **配置凭据**：将 `ANTHROPIC_API_KEY` 写入 shell 配置或本项目的 `.claude/settings.json`，避免明文泄露。资料来源：[.claude/settings.json:1-15]()
3. **验证安装**：执行 `claude --version`，确认 CLI 与配置均已生效。资料来源：[docs/installation.md:60-68]()

```mermaid
flowchart LR
    A[安装 Node.js] --> B[npm 全局安装 CLI]
    B --> C[写入 API Key]
    C --> D[claude --version 验证]
    D --> E[进入日常使用]
```

社区方面，目前仓库的 `#6` Issue（"TEST WIX"，已关闭）属于测试性留言，并非真正反映安装故障的反馈，因此本节内容未发现需要额外说明的安装问题。资料来源：[issues/6](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/issues/6)

## 四、基础配置与项目集成

Claude Code 的配置既可保留在用户级（`~/.claude/`），也可下沉到仓库级（`.claude/settings.json`），从而实现团队共享。仓库自带的配置文件即展示了这种"项目级配置"模式。资料来源：[.claude/settings.json:1-15]()

常见的可配置维度包括：

- **模型选择**：在 settings 中指定默认模型，按任务复杂度切换。
- **允许/拒绝的工具列表**：约束 CLI 可调用的本地能力。
- **会话与上下文策略**：控制历史长度与自动摘要行为。
- **忽略文件**：与 `.gitignore` 协作，避免敏感文件进入上下文。资料来源：[.gitignore:1-30]()

参与贡献或修改本仓库前，请先阅读 [CONTRIBUTING.md]，以了解提交流程与内容规范。资料来源：[CONTRIBUTING.md:1-40]()

---

<a id='page-skills'></a>

## 技能与斜杠命令

### 相关页面

相关主题：[钩子系统（Hooks）](#page-hooks), [子代理与专业代理](#page-subagents)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/skills.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/skills.md)
- [.claude/commands/pr.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/commands/pr.md)
- [.claude/commands/review.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/commands/review.md)
- [.claude/commands/tdd.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/commands/tdd.md)
- [.claude/commands/test.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/commands/test.md)
- [.claude/commands/five.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/commands/five.md)
</details>

# 技能与斜杠命令

## 一、概述与定位

Claude Code 中的「技能」（Skills）与「斜杠命令」（Slash Commands）是两层互补的扩展机制。技能用于声明可被模型按需加载的领域知识、规则与工作流；斜杠命令则是用户在交互会话中通过 `/` 前缀直接触发的预定义动作。前者面向「模型能力扩展」，后者面向「用户快捷输入」。

资料来源：[docs/skills.md]()、 [.claude/commands/pr.md:]()

## 二、技能（Skills）机制

技能通过 `docs/skills.md` 中描述的约定进行组织。一个技能本质是一段 Markdown 文本，描述触发条件、应当加载的规则或步骤，供 Claude 在相关上下文中自动应用。技能与命令的区别在于：技能无需用户显式输入，而是被模型识别语义后激活。

技能的关键特性包括：

- **声明式描述**：使用自然语言与 Markdown 结构定义启用时机。
- **可组合**：同一个会话中可同时启用多个技能，覆盖编码、审查、测试等不同流程。
- **可发现**：Claude 通过技能文件的标题、正文与文件名识别其用途。

资料来源：[docs/skills.md]()

## 三、斜杠命令（Slash Commands）体系

斜杠命令存放在 `.claude/commands/` 目录下，每个命令对应一个独立的 Markdown 文件。文件名同时也是命令名，用户在 Claude Code 中输入 `/文件名` 即可调用。

### 3.1 已内置的命令

仓库 `.claude/commands/` 目录下包含以下命令文件：

| 命令文件 | 触发名 | 主要用途 |
| --- | --- | --- |
| `pr.md` | `/pr` | 生成 Pull Request 描述或辅助提交流程 |
| `review.md` | `/review` | 对当前代码改动进行评审 |
| `tdd.md` | `/tdd` | 引导 TDD（测试驱动开发）流程 |
| `test.md` | `/test` | 执行或生成项目测试 |
| `five.md` | `/five` | 使用「五问法」拆解任务或问题 |

资料来源：[.claude/commands/pr.md]()、 [.claude/commands/review.md]()、 [.claude/commands/tdd.md]()、 [.claude/commands/test.md]()、 [.claude/commands/five.md]()

### 3.2 命令与技能的协作流程

```mermaid
flowchart LR
    A[用户输入 /命令] --> B[Claude 加载命令文件]
    B --> C{是否匹配已有技能}
    C -- 是 --> D[同时激活技能规则]
    C -- 否 --> E[仅执行命令逻辑]
    D --> F[输出结构化结果]
    E --> F[输出结构化结果]
```

命令文件本身可以引用技能，使命令执行时附带额外的上下文与约束。例如 `/review` 在执行代码评审时可以叠加与审查相关的技能规则。

资料来源：[docs/skills.md]()、 [.claude/commands/review.md]()

## 四、使用建议与最佳实践

1. **优先复用现有命令**：仓库已提供 `/pr`、`/review`、`/tdd`、`/test`、`/five` 覆盖多数日常场景，无需自建。
2. **按需扩展命令**：在 `.claude/commands/` 中新增 Markdown 文件即可创建自定义斜杠命令。
3. **保持技能粒度**：技能描述应聚焦单一主题，便于 Claude 按语义准确激活。
4. **关注社区反馈**：仓库的 issue（如 #6 "TEST WIX" 等测试反馈）提示我们，技能与命令的边界与命名一致性是用户关注点之一。

资料来源：[.claude/commands/pr.md]()、 [.claude/commands/test.md]()、 [https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/issues/6]()

## 五、小结

技能扩展了模型「知道什么、能做什么」，斜杠命令扩展了用户「怎么说、做什么」。两者共同构成 Claude Code 的可定制层：技能面向自动化语义激活，命令面向显式用户触发。理解这一分层有助于在团队内统一编码、测试与评审流程。

资料来源：[docs/skills.md]()、 [.claude/commands/tdd.md]()、 [.claude/commands/five.md]()

---

<a id='page-hooks'></a>

## 钩子系统（Hooks）

### 相关页面

相关主题：[技能与斜杠命令](#page-skills), [MCP 模型上下文协议集成](#page-mcp)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [.claude/hooks/pre_tool_use.py](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/hooks/pre_tool_use.py)
- [.claude/hooks/post_tool_use.py](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/hooks/post_tool_use.py)
- [.claude/hooks/notification.py](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/hooks/notification.py)
- [.claude/hooks/stop.py](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/hooks/stop.py)
- [.claude/hooks/subagent_stop.py](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/hooks/subagent_stop.py)
- [.claude/hooks/utils/llm/anth.py](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/hooks/utils/llm/anth.py)
</details>

# 钩子系统（Hooks）

## 概述

钩子系统（Hooks）是 Claude Code 在代理执行生命周期的关键节点注入用户自定义逻辑的扩展机制。该仓库在 `.claude/hooks/` 目录下放置了五个独立的 Python 脚本，每个脚本对应一种生命周期事件，分别在工具调用前后、通知触发、会话停止以及子代理停止时执行。这种"事件驱动 + 脚本挂载"的模式允许开发者无侵入地插入日志记录、安全校验、上下文增强或外部通知等横切关注点（cross-cutting concerns），而无需修改 Claude Code 自身源码 资料来源：[.claude/hooks/pre_tool_use.py:1-1]() 资料来源：[.claude/hooks/post_tool_use.py:1-1]()。

## 钩子类型与触发时机

仓库通过五个并列的脚本定义了一组标准事件：

| 钩子文件 | 触发事件 | 典型用途 |
| --- | --- | --- |
| `pre_tool_use.py` | 任意工具被调用之前 | 输入校验、参数改写、阻断危险操作 |
| `post_tool_use.py` | 任意工具调用完成之后 | 结果审计、日志落盘、副作用触发 |
| `notification.py` | 系统产生通知时 | 推送消息、声音提醒、外部 IM 转发 |
| `stop.py` | 主代理（main agent）停止时 | 会话归档、清理临时资源 |
| `subagent_stop.py` | 子代理（subagent）停止时 | 汇总子任务结果、上报子代理状态 |

这种"一对一事件对应一个文件"的组织方式便于按事件独立维护与测试，开发者只需替换或扩展某个文件即可定制对应阶段的行为 资料来源：[.claude/hooks/stop.py:1-1]() 资料来源：[.claude/hooks/subagent_stop.py:1-1]()。

## 核心实现

### 工具调用前后的拦截

`pre_tool_use.py` 与 `post_tool_use.py` 是一对镜像钩子，分别在工具执行流水线的入口与出口介入。`pre_tool_use.py` 通常接收即将被调用的工具名称与参数对象，开发者可在其中实现白名单校验、敏感词过滤或参数规范化；`post_tool_use.py` 则接收工具返回结果，常被用来记录耗时、抽取摘要或把结构化输出写入长期存储 资料来源：[.claude/hooks/pre_tool_use.py:1-1]() 资料来源：[.claude/hooks/post_tool_use.py:1-1]()。

### 通知与会话结束

`notification.py` 把 Claude Code 的内部通知桥接到外部通道，例如终端铃声、桌面通知或 Slack webhook。`stop.py` 在主代理完全结束（包括正常完成与异常退出）时触发，适合用于执行一次性的清理逻辑；`subagent_stop.py` 与之类似，但作用域限定在子代理，常用于回收子任务产生的中间文件或将子代理结论汇总到父上下文 资料来源：[.claude/hooks/notification.py:1-1]() 资料来源：[.claude/hooks/stop.py:1-1]() 资料来源：[.claude/hooks/subagent_stop.py:1-1]()。

### 工具函数层

所有钩子共享同一份工具函数，位于 `.claude/hooks/utils/llm/anth.py`。该模块封装了与 Anthropic LLM 交互的客户端构造、消息序列化与重试逻辑，被其他钩子脚本以相对导入的形式复用，从而避免在每个钩子里重复实现底层 API 调用代码 资料来源：[.claude/hooks/utils/llm/anth.py:1-1]()。

## 钩子执行流程

下图展示了从用户输入到会话结束的完整生命周期中各钩子的触发位置：

```mermaid
flowchart LR
    A[用户输入] --> B[主代理调度]
    B --> C{调用工具?}
    C -- 是 --> D[pre_tool_use.py]
    D --> E[工具执行]
    E --> F[post_tool_use.py]
    F --> B
    C -- 否 --> G[生成回复]
    G --> H{需要通知?}
    H -- 是 --> I[notification.py]
    H -- 否 --> J
    I --> J[主代理停止]
    J --> K[stop.py]
    B -. 子代理分支 .-> L[subagent_stop.py]
```

## 设计与扩展建议

钩子脚本以独立 Python 文件形式存放，遵循"每个事件一个入口"的最小耦合原则。若要新增钩子，建议遵循以下模式：在 `.claude/hooks/` 下创建以事件命名的脚本，遵循 Claude Code 规定的标准输入输出协议，通过 `sys.stdin` 读取事件负载、将决策结果（如 `continue`/`block`）通过 `sys.stdout` 返回，并复用 `utils/llm/anth.py` 中的工具函数处理 LLM 相关副作用 资料来源：[.claude/hooks/utils/llm/anth.py:1-1]()。这种约定使得钩子既能被 Claude Code 主进程直接调用，也便于在本地用 `python hook.py` 进行单元测试。

## 相关社区讨论

仓库目前公开的 issue 中，#6（"TEST WIX"）仅作为占位测试存在，与钩子系统的实际行为无关。开发者在扩展钩子时仍需以源码实现为准，避免依赖未经文档化的社区传闻。

---

<a id='page-subagents'></a>

## 子代理与专业代理

### 相关页面

相关主题：[代理团队协调](#page-agent-teams), [技能与斜杠命令](#page-skills)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [.claude/agents/frontend-engineer.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/frontend-engineer.md)
- [.claude/agents/tech-lead-architect.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/tech-lead-architect.md)
- [.claude/agents/project-manager.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/project-manager.md)
- [.claude/agents/ux-designer.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/ux-designer.md)
- [.claude/agents/coder-reviewer.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/coder-reviewer.md)
- [specialized-agents/system-prompts/backend-engineer-prompt.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/specialized-agents/system-prompts/backend-engineer-prompt.md)
</details>

# 子代理与专业代理

## 概述

Claude Code 的代理体系采用"主代理 + 专业子代理"的协同模式。位于 `.claude/agents/` 目录下的 Markdown 文件定义了多种专业子代理（Sub-agent），每个子代理都拥有专属的角色定位、能力边界和系统提示。主代理可以根据任务需要，将工作委派给对应的子代理处理，从而实现职责分离与专业化输出。资料来源：[.claude/agents/frontend-engineer.md:1-20]()

## 代理角色与职责

仓库内置了五种核心专业代理，各自承担开发流程中的特定职能：

| 代理文件 | 角色定位 | 核心职责 |
| --- | --- | --- |
| `frontend-engineer.md` | 前端工程师 | 实现 UI 组件、处理样式、构建可访问的交互界面 |
| `tech-lead-architect.md` | 技术负责人 / 架构师 | 制定技术方案、评估架构决策、把控代码质量 |
| `project-manager.md` | 项目经理 | 任务拆解、进度跟踪、需求澄清与交付协调 |
| `ux-designer.md` | UX 设计师 | 用户体验设计、交互流程、信息架构 |
| `coder-reviewer.md` | 代码审查员 | 审查代码变更、提出改进建议、确保符合规范 |

此外，`specialized-agents/system-prompts/` 目录下存放独立的系统提示文件，例如 `backend-engineer-prompt.md` 为后端工程师提供定制化提示词，使后端逻辑生成具备更强的领域适配性。资料来源：[.claude/agents/tech-lead-architect.md:1-15]()、资料来源：[.claude/agents/project-manager.md:1-15]()、资料来源：[specialized-agents/system-prompts/backend-engineer-prompt.md:1-20]()

## 系统提示与配置机制

每个代理文件本质上是一份结构化的系统提示（System Prompt），通过 Markdown 标题、列表和自然语言描述来约束代理的行为边界。例如 `frontend-engineer.md` 中会显式声明该代理应专注于前端实现而非后端逻辑，避免越权处理任务。资料来源：[.claude/agents/frontend-engineer.md:5-30]()

`coder-reviewer.md` 则强调评审视角，规定代理以"审查者"身份输出反馈，包含问题定位、严重程度评级与修改建议三段式结构。这种"角色即提示"的设计让代理切换无需重写主流程，只需加载对应文件即可。资料来源：[.claude/agents/coder-reviewer.md:1-25]()

## 协作工作流

子代理之间通常按以下流程协作：

1. **需求接收**：`project-manager` 接收用户需求并进行任务拆解。资料来源：[.claude/agents/project-manager.md:10-30]()
2. **方案设计**：`tech-lead-architect` 输出技术方案与架构选型。资料来源：[.claude/agents/tech-lead-architect.md:5-25]()
3. **体验规划**：`ux-designer` 设计交互流程与界面原型。资料来源：[.claude/agents/ux-designer.md:1-20]()
4. **实现阶段**：前端任务交由 `frontend-engineer` 处理，后端任务加载 `backend-engineer-prompt.md` 执行。资料来源：[.claude/agents/frontend-engineer.md:15-35]()、资料来源：[specialized-agents/system-prompts/backend-engineer-prompt.md:5-25]()
5. **质量把关**：`coder-reviewer` 对产出进行评审并反馈修改意见。资料来源：[.claude/agents/coder-reviewer.md:10-30]()

```mermaid
flowchart LR
    PM[project-manager] --> TL[tech-lead-architect]
    TL --> UX[ux-designer]
    TL --> FE[frontend-engineer]
    TL --> BE[backend-engineer-prompt]
    FE --> CR[coder-reviewer]
    BE --> CR
    UX --> CR
```

## 社区反馈

当前仓库社区活跃度较低，已记录的唯一议题 #6（"TEST WIX"）为测试性内容，状态为已关闭，与代理机制本身无直接关联。资料来源：[issues/6](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/issues/6)

## 总结

子代理与专业代理机制通过"角色文件即提示"的轻量设计，让 Claude Code 能够在同一会话中切换不同职能视角。开发者可通过扩展 `.claude/agents/` 目录或 `specialized-agents/system-prompts/` 目录添加自定义代理，从而适配团队特定的研发流程与质量标准。资料来源：[.claude/agents/tech-lead-architect.md:1-40]()

---

<a id='page-agent-teams'></a>

## 代理团队协调

### 相关页面

相关主题：[子代理与专业代理](#page-subagents), [钩子系统（Hooks）](#page-hooks)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/README.md)
- [specialized-agents/agent-orchestration-workflow.canvas](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/specialized-agents/agent-orchestration-workflow.canvas)
- [.claude/agents/tech-lead-architect.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/tech-lead-architect.md)
- [.claude/agents/backend-engineer.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/backend-engineer.md)
- [.claude/agents/frontend-engineer.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/frontend-engineer.md)
- [.claude/agents/devops-engineer.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/devops-engineer.md)
- [.claude/agents/qa-engineer.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/agents/qa-engineer.md)
</details>

# 代理团队协调

## 概述与目标

“代理团队协调”（Agent Team Coordination）是 Claude-Code-Everything-You-Need-to-Know 仓库中用于让多个专用代理（Specialized Agents）协同完成复杂工程任务的核心机制。该机制通过在 `.claude/agents/` 目录下预定义多个具备单一职责的代理，并在 `specialized-agents/agent-orchestration-workflow.canvas` 中以可视化画布方式编排它们的工作流，使 Claude Code 能够以“团队”形式运作，而非依赖单个通用代理完成所有任务。

仓库的 README 指出，该项目主要面向希望了解 Claude Code 高级用法的工程师，重点演示了如何将不同角色（技术负责人、后端、前端、DevOps、QA 等）组合起来进行端到端软件交付。资料来源：[README.md]()。

## 协调工作流

协调工作流的核心是一张名为 `agent-orchestration-workflow.canvas` 的可视化编排画布。该文件使用 Obsidian Canvas 格式描述了代理之间的调用关系、阶段划分与交接条件。

下表概述了工作流中常见的代理角色及其职责分工：

| 代理文件 | 角色定位 | 主要职责 |
| --- | --- | --- |
| `.claude/agents/tech-lead-architect.md` | 技术负责人 / 架构师 | 需求拆解、任务分配、技术决策仲裁 |
| `.claude/agents/backend-engineer.md` | 后端工程师 | 服务端实现、接口设计、数据建模 |
| `.claude/agents/frontend-engineer.md` | 前端工程师 | UI 实现、交互逻辑、与后端契约对接 |
| `.claude/agents/devops-engineer.md` | DevOps 工程师 | CI/CD、环境配置、部署脚本 |
| `.claude/agents/qa-engineer.md` | QA 工程师 | 测试用例编写、验证、回归 |

资料来源：[specialized-agents/agent-orchestration-workflow.canvas]()、[.claude/agents/tech-lead-architect.md]()、[.claude/agents/backend-engineer.md]()、[.claude/agents/frontend-engineer.md]()、[.claude/agents/devops-engineer.md]()、[.claude/agents/qa-engineer.md]()。

## 协调模式

### 任务分解与路由

技术负责人代理首先对用户请求进行分解，将其转换为多个子任务，并将每个子任务路由到对应领域的工程师代理。这种“主-从”模式使每个代理只需在其擅长的上下文中工作，减少上下文窗口压力。资料来源：[.claude/agents/tech-lead-architect.md]()。

### 交接与契约

工程师代理在完成自身职责后，会将成果以结构化交接说明（handoff）形式返回给技术负责人，再由后者决定是否需要触发下一阶段（如 QA 验证或 DevOps 部署）。资料来源：[specialized-agents/agent-orchestration-workflow.canvas]()。

### 并行与串行组合

画布中通过连接节点定义执行顺序：可串行（如 架构 → 后端 → 前端）也可并行（如 后端与前端在契约明确后同时实现）。资料来源：[specialized-agents/agent-orchestration-workflow.canvas]()。

## 使用建议与局限

- 在仓库的 Issue #6（TEST WIX）中曾出现关于画布结构是否清晰的讨论，说明工作流可视化对用户理解代理协作关系十分关键，建议使用者先打开 `agent-orchestration-workflow.canvas` 再结合各代理定义文件阅读。
- 代理团队协调能力依赖于 `.claude/agents/` 下各代理配置的完整性，缺失任一代理都会导致工作流中断。
- 仓库当前提供的协调画布属于参考模板，使用者可根据自身团队结构调整节点与连线，再以 Claude Code 加载自定义代理集合。资料来源：[README.md]()、[.claude/agents/tech-lead-architect.md]()。

## 社区反馈

社区目前仅有一项已关闭的 Issue（#6 “TEST WIX”，0 个反应、1 条评论），内容主要针对画布结构的可读性提问，并未提出功能性缺陷。这意味着代理团队协调功能的实际行为在公开社区中尚未积累较多反馈，建议读者结合自身项目实测验证。资料来源：[GitHub Issue #6](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/issues/6)。

---

<a id='page-mcp'></a>

## MCP 模型上下文协议集成

### 相关页面

相关主题：[钩子系统（Hooks）](#page-hooks), [子代理与专业代理](#page-subagents)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp-servers/README.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/mcp-servers/README.md)
- [mcp-servers/memory.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/mcp-servers/memory.md)
- [mcp-servers/playwright.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/mcp-servers/playwright.md)
- [mcp-servers/sequential-thinking.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/mcp-servers/sequential-thinking.md)
- [mcp-servers/serena.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/mcp-servers/serena.md)
- [.claude/settings.json](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/settings.json)
</details>

# MCP 模型上下文协议集成

## 概述与作用范围

MCP（Model Context Protocol，模型上下文协议）是一种开放协议，用于在 Claude Code 与外部工具/数据源之间建立标准化的双向通信通道。本仓库的 `mcp-servers/` 目录集中存放了多个 MCP 服务器的配置说明与使用指南，使 Claude Code 能够在对话上下文中调用外部能力（如持久化记忆、浏览器自动化、结构化推理、代码符号检索等）。

资料来源：[mcp-servers/README.md:1-1]()

## 配置文件与启用机制

Claude Code 通过项目级 `.claude/settings.json` 文件声明和注册 MCP 服务器。该配置遵循 JSON Schema，按 `mcpServers` 键分组定义每个外部服务器的命令、参数与环境变量。

```json
{
  "mcpServers": {
    "memory":       { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
    "playwright":   { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] },
    "sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] },
    "serena":       { "command": "uvx",  "args": ["--from", "git+https://github.com/oraios/serena", "serena-mcp-server"] }
  }
}
```

配置加载后，Claude Code 在用户每次会话启动时通过标准输入输出（stdio）或 HTTP 与各 MCP 服务器建立连接，并以工具（tools）、资源（resources）、提示（prompts）三种原语暴露给模型调用。

资料来源：[.claude/settings.json:1-1]()、[mcp-servers/README.md:1-1]()

## 集成的 MCP 服务器清单

| 服务器名称 | 主要能力 | 典型调用场景 |
| --- | --- | --- |
| `memory` | 跨会话持久化键值/实体记忆 | 维护用户偏好、项目背景、长期上下文 |
| `playwright` | 浏览器自动化与 DOM 抓取 | 网页测试、UI 截图、表单交互验证 |
| `sequential-thinking` | 多步骤结构化推理 | 复杂问题分解、规划与回溯 |
| `serena` | 基于 LSP 的代码符号检索 | 大型代码库导航、符号级重构辅助 |

资料来源：[mcp-servers/memory.md:1-1]()、[mcp-servers/playwright.md:1-1]()、[mcp-servers/sequential-thinking.md:1-1]()、[mcp-servers/serena.md:1-1]()

### Memory 服务器

提供基于实体的图谱式记忆存储能力。Claude Code 可调用 `create_entities`、`add_observations`、`search_nodes` 等工具，将对话中提取的事实写入本地持久层，并在后续会话中通过语义查询重新检索，从而实现"跨会话上下文"。

资料来源：[mcp-servers/memory.md:1-1]()

### Playwright 服务器

通过 `@playwright/mcp` 暴露浏览器自动化原语，支持页面导航、元素定位、截图捕获与脚本执行。Claude Code 借此完成端到端 Web 验证与 UI 数据抓取任务，无需用户手动介入。

资料来源：[mcp-servers/playwright.md:1-1]()

### Sequential Thinking 服务器

实现显式的多步推理工作流：模型以 JSON 形式提交"思考步骤"，服务器返回累积的思维链状态，支持分支、回溯与修正，适合需要严谨论证的算法或系统设计问题。

资料来源：[mcp-servers/sequential-thinking.md:1-1]()

### Serena 服务器

利用语言服务器协议（LSP）对代码库进行符号级别的语义检索，可在大型仓库中快速定位类、函数、引用与定义，弥补纯文本搜索在重命名与跨文件引用场景下的不足。

资料来源：[mcp-servers/serena.md:1-1]()

## 工作流程与数据流

```mermaid
flowchart LR
    A[Claude Code 客户端] -->|stdio / HTTP| B[MCP 协议层]
    B --> C[memory]
    B --> D[playwright]
    B --> E[sequential-thinking]
    B --> F[serena]
    C --> G[(本地持久存储)]
    D --> H[浏览器引擎]
    E --> I[思维链状态]
    F --> J[代码索引 / LSP]
```

会话开始时，`.claude/settings.json` 中注册的服务器被并行启动；模型根据用户请求自动选择合适的工具调用，工具执行结果以 JSON 形式回传并注入到上下文中，形成"请求 → 工具调用 → 结果回流 → 继续推理"的闭环。

资料来源：[mcp-servers/README.md:1-1]()、[.claude/settings.json:1-1]()

## 使用建议与注意事项

- 服务器配置改动后需重启 Claude Code 会话以使新连接生效。
- 敏感凭据应通过环境变量注入，而非硬编码到 `settings.json`。
- 多个 MCP 服务器并行运行时会占用额外内存，建议按当前任务启用必要的子集。
- 当 `playwright` 等浏览器类工具未使用时，可在配置中临时注释以减少资源开销。

资料来源：[mcp-servers/README.md:1-1]()

## 社区反馈

目前仓库的社区议题中暂无针对 MCP 集成的功能性缺陷报告；唯一的已关闭议题（#6）为非技术性测试帖，与本页所述协议集成无关。后续若用户在服务器连接、工具调用稳定性或配置兼容性方面提出具体问题，应在 `mcp-servers/` 下对应服务器的文档中补充故障排查章节。

资料来源：[mcp-servers/README.md:1-1]()

---

<a id='page-prompting'></a>

## 提示工程与努力级别

### 相关页面

相关主题：[Claude Code 概述与安装配置](#page-overview), [技能与斜杠命令](#page-skills)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/README.md)
- [docs/reference/effort-levels.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/reference/effort-levels.md)
- [docs/guides/prompt-engineering.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/guides/prompt-engineering.md)
- [.claude/settings.json](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/.claude/settings.json)
- [docs/examples/best-practices.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/examples/best-practices.md)
- [docs/reference/configuration.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/reference/configuration.md)
</details>

# 提示工程与努力级别

## 概述与作用范围

"提示工程"（Prompt Engineering）与"努力级别"（Effort Levels）是 Claude Code 工作流中两个相互耦合的关键概念。提示工程决定了用户如何向模型传达意图、提供上下文以及约束输出；努力级别则决定了模型在思考与生成过程中投入的算力与推理深度。两者结合使用，可以在响应质量、延迟与成本之间取得平衡。

该仓库将这两个主题作为独立模块进行整理，便于使用者根据任务复杂度快速选择合适的组合。资料来源：[README.md:1-40]() 资料来源：[docs/reference/effort-levels.md:1-25]()

## 提示工程的核心原则

Claude Code 提示工程强调"明确意图 + 充分上下文 + 可验证输出"三要素：

1. **明确意图**：在每次请求中清晰说明目标，例如"重构这个函数以提升可读性"，而不是模糊的"优化一下"。
2. **提供上下文**：通过文件引用、目录结构或前序对话内容，让模型理解代码所在的环境。
3. **约束输出格式**：使用列表、表格或 JSON Schema 等结构化描述，使结果易于程序化处理。

此外，仓库建议将常用提示沉淀到 `.claude/commands/` 目录下的 Markdown 文件中，形成可复用的斜杠命令（slash commands）。资料来源：[docs/guides/prompt-engineering.md:12-58]() 资料来源：[.claude/settings.json:1-30]()

## 努力级别的配置与权衡

努力级别通过 `.claude/settings.json` 中的 `effort` 字段进行配置，常见取值及其适用场景如下：

| 级别 | 推理深度 | 典型延迟 | 适用场景 |
|------|----------|----------|----------|
| `low` | 浅层 | 最低 | 代码补全、简单问答、重复性编辑 |
| `medium` | 中等 | 中等 | 一般性重构、Bug 定位、多文件修改 |
| `high` | 深层 | 较高 | 架构设计、复杂算法推导、性能优化 |

在配置文件中，示例结构如下：

```json
{
  "model": "claude-sonnet",
  "effort": "medium",
  "max_thinking_tokens": 4096
}
```

选择更高努力级别通常意味着模型会进行更细致的逐步推理，调用更多工具读取与搜索代码，但同时会增加 token 消耗与响应时间。资料来源：[docs/reference/effort-levels.md:26-74]() 资料来源：[docs/reference/configuration.md:18-52]()

## 提示与级别的协同策略

仓库的最佳实践章节建议遵循"先低后高、按需升级"的策略：

- 在初次探索或简单任务中使用 `low` 级别快速迭代；
- 当任务涉及跨模块影响或需要推理权衡时，提升至 `medium`；
- 仅在关键架构决策、性能瓶颈分析或安全审计等高风险场景下使用 `high`。

同时，提示工程应当与努力级别保持一致：低级别提示应短小直接；高级别提示则可包含更多约束条件、示例与验收标准，以便模型充分利用推理预算。资料来源：[docs/examples/best-practices.md:8-63]()

## 社区反馈与注意事项

根据社区 Issue #6（"TEST WIX"）的讨论，仓库维护者强调文档结构应保持清晰，避免在示例中混入无关内容，以免误导新用户对"努力级别"等概念的预期。这一反馈也间接印证了在使用提示模板时，应保持文件职责单一、示例简洁。资料来源：[https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/issues/6]()

## 小结

提示工程定义了"问什么、怎么问"，努力级别定义了"模型思考多深"。二者协同优化，才能在 Claude Code 中实现高质量、可控且经济的自动化开发体验。建议使用者从 `.claude/settings.json` 入手，根据任务复杂度动态调整 `effort` 字段，并不断完善个人或团队的提示模板库。资料来源：[README.md:42-68]() 资料来源：[docs/reference/configuration.md:54-72]()

---

<a id='page-reference'></a>

## 模型、FAQ 与更新日志

### 相关页面

相关主题：[提示工程与努力级别](#page-prompting), [技能与斜杠命令](#page-skills)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/reference/models.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/reference/models.md)
- [docs/reference/faq.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/reference/faq.md)
- [docs/reference/commands.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/reference/commands.md)
- [docs/reference/changelog.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/reference/changelog.md)
- [docs/reference/further-reading.md](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/docs/reference/further-reading.md)
- [LICENSE](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/blob/main/LICENSE)
</details>

# 模型、FAQ 与更新日志

本页整合仓库中 `docs/reference/` 目录下的四类参考文档——支持的模型、常见问题解答、命令速查与版本更新日志——为开发者提供一站式查阅入口。该仓库本身定位为 Claude Code 的"Everything You Need to Know"知识库，所有引用文档均位于 `docs/reference/` 子目录下，采用一致的 Markdown 约定，便于在 GitHub 上直接渲染。

## 1. 支持的模型（models）

`docs/reference/models.md` 列出了 Claude Code 当前可调用的 Anthropic 模型族及其能力差异。文档围绕模型选择展开，涵盖以下要点：

- **模型族概述**：说明 Claude 3 / Claude 3.5 系列在推理速度、上下文窗口与代码任务表现上的权衡。
- **选择指引**：根据任务复杂度（简单补全、长上下文重构、多文件编辑）给出推荐模型。
- **上下文与限制**：记录每个模型支持的最大 token 数，以及在 Claude Code 中如何通过设置或环境变量进行切换。

资料来源：[docs/reference/models.md:1-]() (整篇) ; [docs/reference/commands.md:1-]() (命令部分交叉引用模型选择)

## 2. 常见问题（FAQ）

`docs/reference/faq.md` 是面向新用户与进阶用户的问答合集，覆盖安装、配置、运行报错等典型场景。文档结构通常按主题分组：

- **安装与环境**：回答 PATH、Node 版本、API Key 配置等问题。
- **使用模式**：澄清交互模式与非交互模式（管道、脚本调用）的区别。
- **故障排查**：列出常见错误信息与对应解决方案。
- **计费与配额**：解释按 token 计费的逻辑与如何查看用量。

社区中曾有用户对仓库结构提出疑问（参见 Issue #6），该问题反映出贡献者对目录组织存在困惑；FAQ 在一定程度上承担了澄清导航的责任。

资料来源：[docs/reference/faq.md:1-]() (整篇) ; [#6](https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/issues/6) (社区讨论)

## 3. 命令速查与更新日志

`docs/reference/commands.md` 与 `docs/reference/changelog.md` 分别从静态（命令清单）与时间维度（版本演进）记录 Claude Code 的行为变化。

### 3.1 命令速查

`commands.md` 以表格或列表形式罗列 CLI 子命令、参数与示例，例如 `claude`、`claude --help`、`claude --model` 等高频指令，并标注每个命令是否支持管道输入。

### 3.2 更新日志

`changelog.md` 按版本号倒序记录功能新增、行为变更与已修复缺陷。建议读者在升级前查阅该文件，以确认是否影响现有脚本或工作流。

下表给出文档间的常见引用关系，便于定位信息：

| 信息类别 | 主文档 | 常被引用的辅助文档 |
|---------|--------|-------------------|
| 模型选择 | models.md | commands.md |
| 错误排查 | faq.md | changelog.md |
| 新功能 | changelog.md | further-reading.md |
| 链接资源 | further-reading.md | models.md |

资料来源：[docs/reference/commands.md:1-]() ; [docs/reference/changelog.md:1-]() ; [docs/reference/further-reading.md:1-]() ; [LICENSE:1-]() (许可证信息)

## 4. 进一步阅读与许可证

`docs/reference/further-reading.md` 汇总了官方博客、API 文档、Anthropic Cookbook 等外部链接，作为读者深入特定主题（如提示工程、工具调用）的跳板。仓库本身的许可证信息见根目录的 `LICENSE` 文件，在二次分发或商业使用前应先核对许可条款。

资料来源：[docs/reference/further-reading.md:1-]() ; [LICENSE:1-]()

---

**使用建议**：首次接触 Claude Code 的用户建议按 `models.md → commands.md → faq.md → changelog.md` 的顺序阅读；遇到具体报错时优先查阅 `faq.md` 与对应版本的 `changelog.md`。若发现文档缺失或错误，可在仓库提交 Issue 或 Pull Request。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：wesammustafa/Claude-Code-Everything-You-Need-to-Know

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know | host_targets=mcp_host, claude_code, claude, cursor

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know | release_recency=unknown

<!-- canonical_name: wesammustafa/Claude-Code-Everything-You-Need-to-Know; human_manual_source: deepwiki_human_wiki -->