# https://github.com/dagonet/claude-code-toolkit 项目说明书

生成时间：2026-06-01 22:16:28 UTC

## 目录

- [快速开始](#quick-start)
- [模板变体系统](#template-variants)
- [Agent 团队系统](#agent-team)
- [斜杠命令系统](#slash-commands)
- [技能系统](#skills-system)
- [MCP 集成](#mcp-integration)
- [工作流钩子与强制执行](#workflow-hooks)
- [扩展与定制](#extensibility)
- [系统架构](#architecture)
- [相关项目](#related-projects)

<a id='quick-start'></a>

## 快速开始

### 相关页面

相关主题：[模板变体系统](#template-variants), [Agent 团队系统](#agent-team)

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

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

- [README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)
- [docs/getting-started.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/getting-started.md)
- [docs/setup.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/setup.md)
- [setup-project.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/setup-project.sh)
- [setup-project.ps1](https://github.com/dagonet/claude-code-toolkit/blob/main/setup-project.ps1)
</details>

# 快速开始

## 概述

Claude Code Toolkit 是一个开源项目，旨在帮助开发者使用 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 工作流快速启动生产级别的项目开发。通过一条命令即可引导整个项目，包含多智能体团队、斜杠命令、自动触发技能、MCP 权限和工作流强制钩子。

**核心价值：**
- 开箱即用的 `/build`、`/test`、`/commit`、`/sprint` 等命令
- 预配置的多智能体协作团队
- 支持多种技术栈的模板变体
- 自动化代码质量和格式检查

资料来源：[README.md:1-20](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)

---

## 前置条件

### 通用依赖

| 工具 | 版本要求 | 说明 |
|------|----------|------|
| git | 最新版本 | 版本控制 |
| Node.js | 18+ | Claude Code CLI 运行基础 |

### Claude Code CLI 安装

```bash
npm install -g @anthropic-ai/claude-code
```

### 各技术栈特定依赖

| 技术栈 | 额外依赖 | 文档位置 |
|--------|----------|----------|
| .NET | .NET SDK 8.0+ | docs/getting-started.md |
| Rust | Rust 工具链 + Tauri CLI | docs/getting-started.md |
| Java | JDK 17+ | docs/getting-started.md |
| Python | Python 3.9+ | docs/getting-started.md |
| .NET MAUI | .NET MAUI SDK | docs/getting-started.md |

资料来源：[README.md:35-40](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)

---

## 项目变体

Claude Code Toolkit 提供 6 种预配置模板变体，适用于不同的技术栈和开发场景。

### 变体列表

| 变体名称 | 技术栈 | 适用场景 | 构建命令 |
|----------|--------|----------|----------|
| `general` | 通用 | 任意语言项目 | 自定义 |
| `dotnet` | C# / .NET 8 | Web API、服务端应用 | `dotnet build` |
| `dotnet-maui` | .NET MAUI | 跨平台移动应用 | `dotnet build` |
| `rust-tauri` | Rust + Tauri | 桌面应用 | `cargo build` |
| `java` | Java 17+ | Java 应用 | `mvn build` |
| `python` | Python 3.9+ | Python 应用 | `poetry build` |

### 智能体团队配置

每个变体包含 7-8 个预配置的智能体：

| 智能体角色 | 模型 | 职责 |
|------------|------|------|
| architect | opus | 系统架构设计 |
| code-reviewer | sonnet | 代码质量审查 |
| coder | opus | 功能实现 |
| doc-generator | haiku | 文档生成 |
| requirements-engineer | sonnet | 需求分析 |
| test-writer | sonnet | 单元测试编写 |
| tester | sonnet | QA 测试验证 |
| [语言]-coder | - | 语言特定开发（如 dotnet-coder） |

资料来源：[README.md:22-28](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)

---

## 安装步骤

### 步骤 1：安装前置依赖

确保系统中已安装所有必需工具：

```bash
# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

# 安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version
```

### 步骤 2：克隆仓库

```bash
git clone https://github.com/dagonet/claude-code-toolkit
cd claude-code-toolkit
```

### 步骤 3：选择并应用模板

使用 setup 脚本为新项目应用模板：

#### Linux / macOS

```bash
./setup-project.sh --variant python --project-name MyApp --target-path ../my-app
```

#### Windows PowerShell

```powershell
.\setup-project.ps1 -Variant python -ProjectName MyApp -TargetPath ..\my-app
```

#### 参数说明

| 参数 | 缩写 | 必需 | 说明 |
|------|------|------|------|
| `--variant` | `-v` | 是 | 项目模板变体 |
| `--project-name` | `-n` | 是 | 新项目名称 |
| `--target-path` | `-t` | 是 | 目标路径 |
| `--help` | `-h` | 否 | 显示帮助信息 |

资料来源：[setup-project.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/setup-project.sh) 和 [setup-project.ps1](https://github.com/dagonet/claude-code-toolkit/blob/main/setup-project.ps1)

---

## 工作流程概览

```mermaid
graph TD
    A[安装前置依赖] --> B[克隆 Toolkit 仓库]
    B --> C[运行 setup 脚本]
    C --> D{选择变体}
    D -->|dotnet| E[.NET 项目模板]
    D -->|python| F[Python 项目模板]
    D -->|rust| G[Rust 项目模板]
    D -->|java| H[Java 项目模板]
    D -->|general| I[通用项目模板]
    E --> J[进入项目目录]
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K[初始化 Claude Code]
    K --> L[使用斜杠命令开始开发]
```

---

## 核心功能组件

### 斜杠命令（23个）

#### 开发命令

| 命令 | 功能 |
|------|------|
| `/build` | 构建项目并迭代修复错误 |
| `/test` | 运行测试并修复失败 |
| `/commit` | 通过 MCP git 工具暂存和提交 |
| `/new-feature` | 使用正确的架构模式搭建新功能 |
| `/add-tests` | 为现有代码生成单元测试 |
| `/godot-run` | 运行 Godot 项目并捕获调试输出 |
| `/sprint` | 执行冲刺，多智能体并行工作 |

#### 架构命令

| 命令 | 功能 |
|------|------|
| `/arch-doc` | 从代码分析生成架构文档 |
| `/api-design` | 审查或设计 REST API 契约 |
| `/challenge` | 两轮结构化审查挑战计划 |
| `/dependency-audit` | 查找循环依赖和孤立项目 |

#### 其他命令

| 命令 | 功能 |
|------|------|
| `/traceability` | 需求追踪矩阵 |
| `/user-story` | 生成用户故事 |
| `/spec-to-issues` | 规格文档转 GitHub Issues |
| `/tech-debt` | 技术债务评估 |
| `/coverage-report` | 测试覆盖率报告 |
| `/nuget-audit` | NuGet 包审计 |
| `/pre-release` | 发布前检查清单 |

资料来源：[user-level-reference/README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/README.md)

---

## 自动触发技能（11个）

技能会根据当前操作上下文自动加载：

| 技能类型 | 触发场景 |
|----------|----------|
| debug | 调试模式 |
| refactor | 重构代码 |
| explore | 探索新代码库 |
| [更多...] | 根据开发活动自动识别 |

资料来源：[README.md:32-34](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)

---

## MCP 权限配置

工具包预配置了以下 MCP 服务的权限：

| MCP 服务 | 权限范围 |
|----------|----------|
| git | 仓库操作 |
| github | GitHub API |
| dotnet | .NET 构建工具 |
| rust | Rust 工具链 |
| ollama | 本地 LLM |
| sqlite | 数据库操作 |
| windows-mcp | Windows 系统 |
| searxng | 搜索服务 |
| open-brain | 知识管理 |

权限按作用域注册，而非按项目注册。

资料来源：[README.md:33-36](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)

---

## 工作流强制钩子

工具包内置多项工作流强制机制：

| 钩子类型 | 规则 |
|----------|------|
| Bash(git/gh *) | 阻止直接使用 Bash，强制使用 MCP |
| commit-time | 提交前必须通过格式检查 |
| no-push-to-main | 禁止直接推送到 main 分支 |
| tier-before-coder | 必须在 coder 之前通过审查 |

---

## 常见问题

### Q1: 如何选择正确的变体？

**决策树：**

```mermaid
graph TD
    A{技术栈} -->|.NET| B{移动端?}
    A -->|Rust| C[rust-tauri]
    A -->|Java| D[java]
    A -->|Python| E[python]
    A -->|其他| F[general]
    B -->|是| G[dotnet-maui]
    B -->|否| H[dotnet]
```

### Q2: Windows 环境无法运行 .sh 脚本？

使用 PowerShell 版本的 setup 脚本：

```powershell
.\setup-project.ps1 -Variant dotnet -ProjectName MyApp -TargetPath .\my-app
```

### Q3: 如何验证安装成功？

```bash
claude
# 在 Claude Code CLI 中测试斜杠命令
/build
```

---

## 下一步

- 阅读完整文档：[docs/getting-started.md](docs/getting-started.md)
- 查看高级配置：[docs/setup.md](docs/setup.md)
- 探索斜杠命令详情：[user-level-reference/commands/](user-level-reference/commands/)
- 贡献代码：查看 CONTRIBUTING.md

---

<a id='template-variants'></a>

## 模板变体系统

### 相关页面

相关主题：[快速开始](#quick-start), [系统架构](#architecture)

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

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

- [templates/general](https://github.com/dagonet/claude-code-toolkit/blob/main/templates/general)
- [templates/dotnet](https://github.com/dagonet/claude-code-toolkit/blob/main/templates/dotnet)
- [templates/dotnet-maui](https://github.com/dagonet/claude-code-toolkit/blob/main/templates/dotnet-maui)
- [templates/rust-tauri](https://github.com/dagonet/claude-code-toolkit/blob/main/templates/rust-tauri)
- [templates/java](https://github.com/dagonet/claude-code-toolkit/blob/main/templates/java)
- [templates/python](https://github.com/dagonet/claude-code-toolkit/blob/main/templates/python)
- [docs/templates.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/templates.md)
</details>

# 模板变体系统

## 概述

模板变体系统是 Claude Code Toolkit 的核心特性之一，它允许用户通过一条命令将项目引导为具备生产级 Claude Code 工作流的形态。该系统提供了六种预定义的模板变体，每种变体都针对特定的编程语言和技术栈进行了优化配置。 资料来源：[README.md:1-20]()

用户可以通过以下命令快速初始化项目：

```bash
./setup-project.sh --variant python --project-name MyApp --target-path ../my-app
# Windows
.\setup-project.ps1 -Variant python -ProjectName MyApp -TargetPath ..\my-app
```

## 支持的模板变体

Claude Code Toolkit 支持六种模板变体，覆盖了主流的编程语言和框架：

| 变体名称 | 技术栈 | 特定功能 |
|----------|--------|----------|
| `general` | 通用 | 基础工作流配置，适用于任何语言 |
| `dotnet` | .NET | .NET SDK 构建钩子、C# 编码规范 |
| `dotnet-maui` | .NET MAUI | 跨平台移动开发模板 |
| `rust-tauri` | Rust + Tauri | Rust 编译检查、Tauri 构建集成 |
| `java` | Java | JDK 构建工具、Maven/Gradle 支持 |
| `python` | Python | pip/poetry 环境管理、格式化工具 |

## 系统架构

### 模板变体系统的核心组件

```mermaid
graph TB
    subgraph 模板引擎
        A[setup-project.sh] --> B[模板选择器]
        B --> C[变体配置解析器]
    end
    
    subgraph 变体类型
        D[general]
        E[dotnet]
        F[dotnet-maui]
        G[rust-tauri]
        H[java]
        I[python]
    end
    
    subgraph 输出产物
        J[Agent 团队]
        K[斜杠命令]
        L[自动触发技能]
        M[MCP 权限配置]
        N[工作流钩子]
    end
    
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H
    C --> I
    
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    
    D --> K
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K
```

### 变体定制化层级

```mermaid
graph TD
    A[用户执行 setup-project] --> B{选择变体类型}
    
    B -->|general| C[通用基础配置]
    B -->|dotnet| D[.NET 特定配置]
    B -->|dotnet-maui| E[MAUI 特定配置]
    B -->|rust-tauri| F[Rust-Tauri 特定配置]
    B -->|java| G[Java 特定配置]
    B -->|python| H[Python 特定配置]
    
    C --> I[应用语言无关组件]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I
    
    I --> J[Agent 团队配置]
    I --> K[斜杠命令配置]
    I --> L[MCP 权限配置]
    
    J --> M[输出到项目目录]
    K --> M
    L --> M
```

## 变体配置详情

### 通用变体 (general)

通用变体提供基础的 Claude Code 工作流配置，不包含任何特定语言的构建工具或编码规范。它适合以下场景：

- 项目使用不在支持列表中的编程语言
- 需要高度自定义的团队
- 作为创建新变体的基础模板

通用变体包含的组件包括基础的 Agent 团队、核心斜杠命令子集以及基本的 MCP 权限配置。 资料来源：[templates/general]()

### .NET 变体 (dotnet)

.NET 变体专门针对 .NET 生态系统设计，包含以下特定功能：

| 组件 | 描述 |
|------|------|
| dotnet-coder | 专门的 C# 编码代理，熟悉 .NET 约定和最佳实践 |
| 构建钩子 | `dotnet build` 和 `dotnet test` 命令集成 |
| 格式检查 | dotnet format 工具集成 |
| 项目分析 | 解决方案和项目文件解析工具 |

.NET 变体包含的 Agent 包括：architect、code-reviewer、coder、dotnet-coder、doc-generator、requirements-engineer、test-writer 和 tester。 资料来源：[templates/dotnet]()

### .NET MAUI 变体 (dotnet-maui)

.NET MAUI 变体在 dotnet 变体基础上增加了跨平台移动开发的支持：

- MAUI 特定的构建配置
- 平台特定代码处理规范
- 移动应用测试集成

MAUI 变体继承所有 dotnet 变体的功能，并针对多平台目标进行了扩展。 资料来源：[templates/dotnet-maui]()

### Rust-Tauri 变体 (rust-tauri)

Rust-Tauri 变体为 Rust 语言和 Tauri 桌面应用框架提供支持：

| 组件 | 功能 |
|------|------|
| rust-coder | Rust 编码专家代理 |
| Cargo 集成 | Rust 包管理器和构建工具 |
| Tauri 配置 | 桌面应用特定的工作流 |
| 安全审计 | Rust 依赖安全检查 |

该变体包含 8 个 Agent，其中 rust-coder 替代了通用 coder 的部分职责。 资料来源：[templates/rust-tauri]()

### Java 变体 (java)

Java 变体针对 Java 生态系统进行了优化：

- java-coder 专用编码代理
- Maven 和 Gradle 构建工具支持
- JDK 版本检查和兼容性验证
- Java 编码规范集成

### Python 变体 (python)

Python 变体为 Python 项目提供完整支持：

- python-coder 专用编码代理
- pip 和 poetry 环境管理
- Black、isort 等格式化工具
- venv/Conda 环境集成

## 输出产物

每个变体初始化后都会在目标目录生成以下产物：

### Agent 团队配置

| Agent 名称 | 模型 | 职责 |
|------------|------|------|
| architect | opus | 系统架构设计和规划 |
| code-reviewer | sonnet | 代码审查、质量和结构分析 |
| coder | opus | 通用代码实现 |
| doc-generator | haiku | API 文档生成 |
| requirements-engineer | sonnet | 需求分析和用户故事编写 |
| test-writer | sonnet | 单元测试编写 |
| tester | sonnet | QA 测试和验证 |
| *-coder | 变体特定 | 语言特定的编码辅助 |

### 斜杠命令集

系统提供 23 个用户级斜杠命令，分为以下类别：

| 类别 | 命令示例 | 描述 |
|------|----------|------|
| 开发 | `/build`, `/test`, `/commit` | 基本的开发工作流命令 |
| 功能 | `/new-feature`, `/add-tests` | 功能开发和测试添加 |
| 架构 | `/arch-doc`, `/api-design` | 架构文档和 API 设计 |
| 质量 | `/code-review`, `/tech-debt` | 代码审查和技术债务评估 |

### 自动触发技能

系统包含 11 个自动触发技能，它们会根据当前工作上下文自动激活：

- 调试模式检测并激活调试技能
- 重构上下文检测并提供重构建议
- 新代码库探索时自动加载项目结构分析

### MCP 权限配置

预配置的 MCP 权限覆盖以下工具域：

- Git/GitHub 操作
- dotnet CLI
- Rust 工具链
- SQLite 数据库
- Windows 系统操作
- Ollama 本地模型
- SearXNG 搜索

### 工作流强制钩子

| 钩子类型 | 行为 |
|----------|------|
| Bash 限制 | 阻止直接使用 `git/gh` 命令，引导使用 MCP 工具 |
| 提交时格式门禁 | 提交前自动检查代码格式 |
| 分支保护 | 禁止直接推送到 main 分支 |
| 层级审查 | 要求架构师评审后才能进行编码 |

## 使用流程

```mermaid
graph LR
    A[安装前置依赖] --> B[克隆仓库]
    B --> C[运行 setup 脚本]
    C --> D{选择变体}
    D -->|dotnet| E[应用 .NET 模板]
    D -->|python| F[应用 Python 模板]
    D -->|general| G[应用通用模板]
    E --> H[生成 Agent 团队]
    F --> H
    G --> H
    H --> I[配置 MCP 权限]
    I --> J[启用斜杠命令]
    J --> K[项目初始化完成]
```

## 变体选择指南

| 使用场景 | 推荐变体 |
|----------|----------|
| C#/.NET 后端服务 | `dotnet` |
| 跨平台移动应用 | `dotnet-maui` |
| Rust 桌面应用 | `rust-tauri` |
| Java 企业应用 | `java` |
| Python 数据科学/Web | `python` |
| 其他语言或自定义需求 | `general` |

## 相关资源

- 详细文档：[docs/templates.md](docs/templates.md)
- 入门指南：[docs/getting-started.md](docs/getting-started.md)
- 仓库地址：[github.com/dagonet/claude-code-toolkit](https://github.com/dagonet/claude-code-toolkit)

---

<a id='agent-team'></a>

## Agent 团队系统

### 相关页面

相关主题：[斜杠命令系统](#slash-commands), [技能系统](#skills-system)

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

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

- [AGENTS.md](https://github.com/dagonet/claude-code-toolkit/blob/main/AGENTS.md)
- [user-level-reference/README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/README.md)
- [user-level-reference/agents](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/agents)
- [templates/general/.claude/agents](https://github.com/dagonet/claude-code-toolkit/blob/main/templates/general/.claude/agents)
</details>

# Agent 团队系统

## 概述

Agent 团队系统是 Claude Code Toolkit 的核心组件之一，它定义了一组专业化的 AI Agent 角色，用于在软件开发过程中承担不同的职责。每个 Agent 都被分配了特定的模型、明确的职责范围和协作模式，形成一个高效的分布式开发团队。

该系统支持 6 种模板变体（general、dotnet、dotnet-maui、rust-tauri、java、python），每个变体包含 7-8 个专业 Agent，并根据语言特性添加特定领域的编码 Agent（如 `dotnet-coder`、`rust-coder`、`java-coder`、`python-coder`）。

资料来源：[user-level-reference/README.md:1-30]()

## Agent 角色定义

### 核心 Agent 矩阵

| Agent 角色 | 默认模型 | 主要职责 |
|------------|----------|----------|
| architect | opus | 架构决策、模式验证、可维护性保证 |
| coder | opus | 实现变更、遵循高质量工程标准 |
| code-reviewer | sonnet | 代码质量、风格、结构、测试覆盖率审查 |
| doc-generator | haiku | 为代码变更生成文档（公共 API、使用示例） |
| requirements-engineer | sonnet | 将功能想法细化为详细规格说明（用户故事、验收标准、边界情况） |
| test-writer | sonnet | 为新代码编写综合测试（行为测试、边界情况） |
| tester | sonnet | QA 测试验证（UI 自动化、数据库检查、日志分析） |

资料来源：[user-level-reference/README.md:15-20]()

### 架构师 Agent

架构师（architect）Agent 是团队中的技术决策领导者，负责：

- 制定和维护架构决策
- 验证设计模式的一致性应用
- 确保系统的可扩展性和可维护性
- 审查技术方案并提供改进建议

架构师使用 `opus` 模型，这是性能最强的模型，适合处理复杂的架构分析和决策任务。

资料来源：[user-level-reference/README.md:15]()

### 编码 Agent

编码 Agent 是团队的主要实现者，具有以下特点：

- **通用编码能力**：基于 `opus` 模型，具备全面的软件开发能力
- **语言特定变体**：针对不同技术栈提供专门的编码 Agent
  - `dotnet-coder`：.NET/C# 开发
  - `rust-coder`：Rust 开发
  - `java-coder`：Java/Kotlin 开发
  - `python-coder`：Python 开发

编码 Agent 遵循高质量工程标准，包括代码风格规范、测试要求、文档注释等。

资料来源：[user-level-reference/README.md:16]()

### 代码审查 Agent

代码审查 Agent（code-reviewer）负责代码质量保证：

- 审查代码风格和结构
- 检查测试覆盖率
- 识别潜在问题和改进点
- 不会修改代码，仅提供审查意见

使用 `sonnet` 模型，在保证审查质量的同时平衡成本效率。

资料来源：[user-level-reference/README.md:17]()

### 文档生成 Agent

文档生成 Agent（doc-generator）专注于代码文档：

- 生成公共 API 文档
- 编写使用示例
- 更新相关说明文档
- 使用 `haiku` 模型，适合轻量级但精确的文档任务

资料来源：[user-level-reference/README.md:18]()

### 需求工程 Agent

需求工程 Agent（requirements-engineer）负责需求分析和细化：

- 将功能想法转化为详细规格说明
- 创建用户故事
- 定义验收标准
- 识别边界情况和异常处理场景

资料来源：[user-level-reference/README.md:19]()

### 测试编写 Agent

测试编写 Agent（test-writer）负责测试开发：

- 为新代码编写单元测试
- 编写集成测试
- 覆盖边界情况和异常场景
- 使用 `sonnet` 模型处理复杂的测试逻辑

资料来源：[user-level-reference/README.md:20]()

### QA 测试 Agent

QA 测试 Agent（tester）负责验证功能：

- UI 自动化测试（使用 FlaUI）
- 数据库状态检查
- 日志分析
- 端到端功能验证

资料来源：[user-level-reference/README.md:21]()

## Agent 工作流程

### 标准开发流程

```mermaid
graph TD
    A[需求输入] --> B[requirements-engineer<br/>需求分析]
    B --> C[architect<br/>架构设计]
    C --> D[coder<br/>代码实现]
    D --> E[test-writer<br/>编写测试]
    E --> F[code-reviewer<br/>代码审查]
    F -->|需要修改| D
    F -->|审查通过| G[doc-generator<br/>生成文档]
    G --> H[tester<br/>QA 验证]
    H -->|测试失败| D
    H -->|测试通过| I[交付]
```

### Sprint 流程

在 Sprint 执行过程中，多个 Agent 可以并行工作：

1. **并行工作流**：根据任务分配，多个 Agent 同时处理不同功能
2. **状态同步**：通过共享上下文保持一致性
3. **依赖管理**：处理任务间的依赖关系

资料来源：[user-level-reference/README.md:8]()

## Agent 配置结构

### 模板变体

每个模板变体的 Agent 配置位于对应的目录中：

| 模板变体 | Agent 目录路径 | 特定 Agent |
|----------|----------------|------------|
| general | `templates/general/.claude/agents/` | - |
| dotnet | `.claude/agents/` | dotnet-coder |
| dotnet-maui | `.claude/agents/` | dotnet-coder |
| rust-tauri | `.claude/agents/` | rust-coder |
| java | `.claude/agents/` | java-coder |
| python | `.claude/agents/` | python-coder |

资料来源：[README.md:1-15]()

### Agent 定义文件格式

每个 Agent 由一个 Markdown 文件定义，包含：

- **角色名称**：Agent 的标识符
- **模型选择**：使用的 AI 模型（opus/sonnet/haiku）
- **系统提示**：Agent 的行为规范和职责定义
- **工具权限**：Agent 可使用的工具范围
- **输出格式**：响应格式规范

## Agent 协作机制

### 状态管理

```mermaid
stateDiagram-v2
    [*] --> 空闲: 初始化
    空闲 --> 任务分配: 接收任务
    任务分配 --> 执行中: 开始工作
    执行中 --> 等待审查: 完成交付
    等待审查 --> 执行中: 审查反馈
    等待审查 --> 完成: 审查通过
    完成 --> [*]
```

### 上下文共享

Agent 之间通过共享工作区上下文进行通信：

- 项目状态信息
- 当前任务进度
- 代码变更记录
- 审查意见和反馈

### 工具调用

每个 Agent 都有预定义的工具权限：

| Agent | 主要工具集 |
|-------|------------|
| architect | 代码结构分析、依赖图生成 |
| coder | 文件读写、执行命令、代码生成 |
| code-reviewer | 代码分析、静态检查 |
| doc-generator | 文档模板、Markdown 生成 |
| requirements-engineer | 需求解析、用户故事生成 |
| test-writer | 测试框架、测试代码生成 |
| tester | UI 自动化、数据库查询、日志分析 |

## 与 Slash Commands 的集成

Agent 系统与 Slash Commands 深度集成，每个命令可以调用相应的 Agent：

```mermaid
graph LR
    subgraph Slash Commands
        A[/build] --> B[architect + coder]
        C[/test] --> D[tester]
        E[/arch-doc] --> B
        F[/code-review] --> G[code-reviewer]
    end
```

### 命令与 Agent 映射

| 命令 | 调用的 Agent |
|------|--------------|
| `/build` | architect、coder |
| `/test` | tester |
| `/commit` | coder |
| `/arch-doc` | architect、doc-generator |
| `/code-review` | code-reviewer |
| `/new-feature` | architect、requirements-engineer |
| `/user-story` | requirements-engineer |
| `/add-tests` | test-writer |

资料来源：[user-level-reference/README.md:23-50]()

## 最佳实践

### Agent 选择原则

1. **复杂架构决策**：使用 `architect`（opus 模型）
2. **核心代码实现**：使用 `coder`（opus 模型）
3. **代码审查**：使用 `code-reviewer`（sonnet 模型）
4. **轻量级文档**：使用 `doc-generator`（haiku 模型）
5. **测试开发**：使用 `test-writer`（sonnet 模型）

### 协作建议

- **明确任务边界**：每个 Agent 应有清晰的职责范围
- **适当的模型选择**：根据任务复杂度选择合适的模型
- **迭代式工作**：充分利用审查反馈循环改进代码
- **文档同步**：确保文档与代码变更保持同步

## 总结

Agent 团队系统通过专业化的角色分工和智能化的模型分配，为软件开发提供了完整的 AI 驱动工作流。从需求分析到代码实现、测试验证、文档生成，每个环节都有专门的 Agent 负责，确保开发过程既高效又保持高质量标准。该系统的高度可配置性使其能够适应不同的技术栈和项目需求。

---

<a id='slash-commands'></a>

## 斜杠命令系统

### 相关页面

相关主题：[Agent 团队系统](#agent-team), [工作流钩子与强制执行](#workflow-hooks)

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

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

- [user-level-reference/commands](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands)
- [README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)
- [user-level-reference/README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/README.md)
- [user-level-reference/commands/build.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/build.md)
- [user-level-reference/commands/test.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/test.md)
- [user-level-reference/commands/commit.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/commit.md)
- [user-level-reference/commands/sprint.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/sprint.md)
- [user-level-reference/commands/arch-doc.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/arch-doc.md)
- [user-level-reference/commands/new-feature.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/new-feature.md)
- [user-level-reference/commands/tech-debt.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/tech-debt.md)
- [user-level-reference/commands/coverage-report.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/coverage-report.md)
- [user-level-reference/commands/api-design.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/api-design.md)
- [user-level-reference/commands/traceability.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/traceability.md)
- [user-level-reference/commands/user-story.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/user-story.md)
- [user-level-reference/commands/spec-to-issues.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/spec-to-issues.md)
- [user-level-reference/commands/nuget-audit.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/nuget-audit.md)
</details>

# 斜杠命令系统

## 概述

斜杠命令系统（Slash Command System）是 Claude Code Toolkit 项目中的核心功能模块，为开发者提供了一套完整的命令行工作流自动化解决方案。该系统通过预定义的斜杠命令（以 `/` 开头的指令）简化了软件开发过程中的常见任务，包括代码构建、测试执行、提交管理、架构分析等。

Claude Code Toolkit 提供了 **23 个用户级斜杠命令**，覆盖了从日常开发到架构设计的完整生命周期。这些命令遵循统一的设计模式，支持参数传递、上下文感知和工作流集成，使开发者能够在 Claude Code 环境中直接执行复杂的开发任务。

斜杠命令系统的主要特点包括：

- **开箱即用**：安装模板后立即可用，无需额外配置
- **多语言支持**：针对 .NET、Java、Python、Rust+Tauri 等不同技术栈提供专属命令
- **工作流集成**：与 MCP（Model Context Protocol）工具深度集成
- **交互式设计**：支持动态参数输入和用户确认流程

资料来源：[README.md:1-30]()

## 系统架构

### 整体架构图

斜杠命令系统采用分层架构设计，由命令定义层、工作流引擎层和工具集成层三部分组成。

```mermaid
graph TD
    subgraph 命令定义层
        CMD[/build /test /commit<br/>命令元数据]
    end
    
    subgraph 工作流引擎层
        WF[Workflow Engine<br/>工作流引擎]
        ARG[Arguments Parser<br/>参数解析器]
        AGENT[Agent Router<br/>智能体路由]
    end
    
    subgraph 工具集成层
        MCP[MCP Tools<br/>MCP 工具集]
        GIT[Git/Hub CLI]
        BUILD[Build Tools<br/>构建工具]
    end
    
    CMD --> WF
    WF --> ARG
    WF --> AGENT
    AGENT --> MCP
    AGENT --> GIT
    AGENT --> BUILD
```

### 目录结构

斜杠命令的定义文件位于 `user-level-reference/commands/` 目录下，采用 Markdown 格式存储每条命令的完整规范。

```
user-level-reference/
└── commands/
    ├── README.md              # 命令总览索引
    ├── build.md               # 构建命令
    ├── test.md                # 测试命令
    ├── commit.md              # 提交命令
    ├── sprint.md              # 冲刺命令
    ├── arch-doc.md            # 架构文档生成
    ├── new-feature.md         # 新功能搭建
    ├── api-design.md          # API 设计审查
    ├── tech-debt.md           # 技术债务评估
    ├── coverage-report.md     # 覆盖率报告
    ├── traceability.md         # 需求追踪
    ├── user-story.md          # 用户故事生成
    ├── spec-to-issues.md      # 规范转 Issues
    ├── challenge.md           # 方案挑战
    ├── code-review.md         # 代码审查
    └── sync-template.md       # 模板同步
```

资料来源：[user-level-reference/README.md:1-30]()

## 命令分类

斜杠命令系统中的 23 条命令可分为以下六个主要类别：

### 开发命令

开发命令是日常编码过程中最常用的命令集，负责项目的构建、测试和部署流程。

| 命令 | 功能描述 | 适用场景 |
|------|----------|----------|
| `/build` | 构建项目并迭代修复错误 | 编译验证、CI/CD 流程 |
| `/test` | 运行测试并修复失败用例 | TDD 流程、回归测试 |
| `/commit` | 通过 MCP git 工具暂存并提交变更 | 版本控制、日常提交 |
| `/new-feature` | 使用正确的架构模式搭建新功能 | 功能开发初期 |
| `/add-tests` | 为现有代码生成单元测试 | 测试覆盖率提升 |
| `/godot-run` | 运行 Godot 项目并捕获调试输出 | 游戏开发 |
| `/sprint` | 执行冲刺，支持并行 Agent 工作流 | 敏捷开发 |

资料来源：[user-level-reference/README.md:28-35]()

### 架构命令

架构命令用于分析和生成项目的技术架构文档，帮助团队理解系统结构。

| 命令 | 功能描述 | 输出内容 |
|------|----------|----------|
| `/arch-doc` | 从代码分析生成架构文档 | 依赖图、技术栈说明 |
| `/api-design` | 审查或设计 REST API 契约 | 端点定义、请求/响应模型 |
| `/dependency-audit` | 查找循环依赖和孤立项目 | 依赖关系报告 |

资料来源：[user-level-reference/README.md:36-38]()

### 代码质量命令

代码质量命令用于评估和改进代码的技术债务和测试覆盖率。

| 命令 | 功能描述 | 分析维度 |
|------|----------|----------|
| `/tech-debt` | 量化技术债务 | 代码复杂度、架构债务、依赖债务 |
| `/coverage-report` | 生成测试覆盖率报告 | 行覆盖率、分支覆盖率、方法覆盖率 |
| `/code-review` | 审查代码质量、风格和结构 | 分类发现结果 |
| `/nuget-audit` | 审计 NuGet 包依赖 | 安全漏洞、过时版本 |

资料来源：[user-level-reference/README.md:39-43]()

### 需求工程命令

需求工程命令帮助团队将业务需求转化为可追踪的技术实现。

| 命令 | 功能描述 | 核心输出 |
|------|----------|----------|
| `/user-story` | 生成结构化用户故事 | INVEST 格式故事、验收标准 |
| `/traceability` | 链接需求-代码-测试 | 追溯矩阵 |
| `/spec-to-issues` | 将规范转换为 GitHub Issues | 结构化 Issues |

资料来源：[user-level-reference/README.md:44-47]()

### 协作命令

协作命令用于团队间的方案讨论和决策。

| 命令 | 功能描述 | 应用场景 |
|------|----------|----------|
| `/challenge` | 挑战计划、方案或设计 | 决策前的多轮评审 |

资料来源：[user-level-reference/README.md:48]()

### 维护命令

维护命令用于项目模板的更新和同步。

| 命令 | 功能描述 | 操作对象 |
|------|----------|----------|
| `/sync-template` | 同步项目模板 | Claude Code Toolkit 模板 |

资料来源：[user-level-reference/README.md:49]()

## 命令工作流模式

### 通用工作流结构

斜杠命令遵循统一的工作流设计模式，确保一致的用户体验和可预测的行为。

```mermaid
graph LR
    START([用户输入<br/>/command arg]) --> PARSE[解析参数<br/>$ARGUMENTS]
    PARSE --> VALIDATE{参数验证}
    VALIDATE -->|无效| ASK[请求补充信息]
    ASK --> PARSE
    VALIDATE -->|有效| ANALYZE[分析上下文]
    ANALYZE --> EXECUTE[执行工作流]
    EXECUTE --> PRESENT[呈现结果]
    PRESENT --> USER([用户确认])
    USER -->|修改| ADJUST[调整参数]
    ADJUST --> EXECUTE
    USER -->|确认| FINALIZE[完成操作]
```

### 标准命令模板

每条斜杠命令的 Markdown 定义文件包含以下标准章节：

```markdown
# /command-name - 功能描述

简短的功能说明段落。

## Arguments
- `$ARGUMENTS` - 参数说明

## Workflow
1. **步骤一**：操作描述
2. **步骤二**：操作描述
3. **步骤三**：操作描述

## Rules
- 规则一
- 规则二

## Output Template
适当的输出格式示例
```

资料来源：[user-level-reference/commands/new-feature.md:1-30]()

## 核心命令详解

### /build - 项目构建

`/build` 命令是开发流程中的核心命令，负责编译项目并自动修复构建错误。

**参数说明**

| 参数 | 类型 | 描述 |
|------|------|------|
| `$ARGUMENTS` | 可选 | 构建目标或构建配置 |

**工作流程**

```mermaid
graph TD
    START[/build] --> CTX[确定根目录<br/>检查 .sln 或项目文件]
    CTX --> BUILD[执行 dotnet build]
    BUILD --> ERR{有错误?}
    ERR -->|否| SUCCESS[构建成功]
    ERR -->|是| ANALYZE[分析错误原因]
    ANALYZE --> FIX[应用修复]
    FIX --> RETRY[重新构建]
    RETRY --> ERR
    SUCCESS --> REPORT[报告结果]
```

**核心规则**

- 构建失败时自动分析错误原因
- 提供最多 N 次自动修复迭代
- 每次修复后重新验证构建
- 修复失败时报告问题并停止

资料来源：[user-level-reference/commands/build.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/build.md)

### /test - 测试执行

`/test` 命令执行项目测试套件并处理测试失败情况。

**参数说明**

| 参数 | 类型 | 描述 |
|------|------|------|
| `$ARGUMENTS` | 可选 | 测试筛选器或测试项目 |

**工作流程**

```mermaid
graph TD
    START[/test] --> LOCATE[定位测试项目]
    LOCATE --> RUN[运行测试]
    RUN --> RESULT{结果判定}
    RESULT -->|全部通过| SUCCESS[报告成功]
    RESULT -->|有失败| ANALYZE[分析失败原因]
    ANALYZE --> DIAGNOSE[诊断问题]
    DIAGNOSE --> FIX[修复测试或代码]
    FIX --> RERUN[重新运行测试]
    RERUN --> RESULT
```

**输出模式**

- **摘要模式**（默认）：仅显示测试结果摘要
- **详情模式**：用户回复 "show details" 后显示详细的测试信息

资料来源：[user-level-reference/commands/test.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/test.md)

### /commit - 变更提交

`/commit` 命令通过 MCP git 工具执行变更的暂存和提交操作。

**工作流程**

```mermaid
graph TD
    START[/commit] --> CHECK[检查 git 状态]
    CHECK --> STAGED{有暂存内容?}
    STAGED -->|否| ADD[显示更改摘要<br/>提示用户选择]
    STAGED -->|是| REVIEW[审查变更]
    ADD --> SELECT[用户选择文件]
    SELECT --> STAGED
    REVIEW --> DIFF[显示 diff]
    DIFF --> MSG[生成提交信息]
    MSG --> CONFIRM{用户确认?}
    CONFIRM -->|修改| EDIT[编辑提交信息]
    CONFIRM -->|确认| PUSH[推送到远程]
    EDIT --> MSG
```

**核心规则**

- `Bash(git/gh *)` 命令被阻止，强制使用 MCP 工具
- 提交前执行格式检查
- 禁止直接推送到 main 分支
- 遵循约定式提交规范

资料来源：[user-level-reference/commands/commit.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/commit.md)

### /sprint - 冲刺执行

`/sprint` 命令支持敏捷开发中的冲刺执行，通过并行 Agent 工作流提高团队效率。

**参数说明**

| 参数 | 类型 | 描述 |
|------|------|------|
| `$ARGUMENTS` | 必填 | 冲刺目标或 Issue 列表 |

**工作流程**

```mermaid
graph TD
    START[/sprint goal] --> PARSE[解析冲刺目标]
    PARSE --> FETCH[获取 Issue 列表]
    FETCH --> BATCH[分批并行处理]
    BATCH --> AGENT1[Agent 1: 编码]
    BATCH --> AGENT2[Agent 2: 测试]
    BATCH --> AGENT3[Agent 3: 文档]
    AGENT1 --> MERGE[结果汇总]
    AGENT2 --> MERGE
    AGENT3 --> MERGE
    MERGE --> REPORT[生成冲刺报告]
```

资料来源：[user-level-reference/commands/sprint.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/sprint.md)

### /arch-doc - 架构文档生成

`/arch-doc` 命令从代码分析生成项目的架构文档。

**参数说明**

| 参数 | 类型 | 描述 |
|------|------|------|
| `$ARGUMENTS` | 可选 | 输出格式（markdown、mermaid）或特定关注区域 |

**工作流程**

1. **分析解决方案结构**：调用 `map_dotnet_structure(root)` 和 `analyze_project_references`
2. **识别关键组件**：读取入口点、DI 注册、配置文件
3. **映射项目职责**：确定每项目的层级和职责
4. **生成依赖图**：使用 Mermaid 语法绘制架构图

**输出格式**

默认使用摘要模式，生成概要型架构文档。用户回复 "show details" 可切换到详情模式查看具体文件路径和代码行号。

资料来源：[user-level-reference/commands/arch-doc.md:1-30]()

### /new-feature - 新功能搭建

`/new-feature` 命令按照正确的架构模式为项目搭建新功能的基础结构。

**参数说明**

| 参数 | 类型 | 描述 |
|------|------|------|
| `$ARGUMENTS` | 必填 | 功能名称或描述 |

**工作流程**

```mermaid
graph TD
    START[/new-feature name] --> UNDERSTAND[理解需求]
    UNDERSTAND --> ANALYZE[分析现有架构]
    ANALYZE --> PLAN[规划功能结构]
    PLAN --> PRESENT[呈现计划]
    PRESENT --> APPROVE{用户批准?}
    APPROVE -->|拒绝| ADJUST[调整计划]
    APPROVE -->|批准| SCAFFOLD[创建文件]
    SCAFFOLD --> REGISTER[注册依赖]
    REGISTER --> TESTS[创建初始测试]
    TESTS --> COMPLETE[完成]
```

**生成文件示例**

```
src/Domain/Entities/[Name].cs
src/Application/[Name]/Commands/Create[Name]Command.cs
src/Application/[Name]/Queries/Get[Name]Query.cs
tests/UnitTests/[Name]Tests.cs
```

资料来源：[user-level-reference/commands/new-feature.md:1-35]()

### /tech-debt - 技术债务评估

`/tech-debt` 命令评估和量化代码库中的技术债务。

**参数说明**

| 参数 | 类型 | 描述 |
|------|------|------|
| `$ARGUMENTS` | 可选 | 评估路径，或 "full" 进行完整评估 |

**分析维度**

| 类别 | 评估项 | 权重 |
|------|--------|------|
| 代码质量债务 | 复杂方法、God 类、大文件 | 10-15 分/项 |
| 架构债务 | 循环依赖、层边界违反 | 10-20 分/项 |
| 依赖债务 | 过时包、安全漏洞 | 5-20 分/项 |
| 文档债务 | 缺失 XML 文档、过期 README | 5-10 分/项 |

**债务评分标准**

| 等级 | 分数范围 |
|------|----------|
| 低 | 0-50 |
| 中 | 51-150 |
| 高 | 151-300 |
| 严重 | 300+ |

资料来源：[user-level-reference/commands/tech-debt.md:1-50]()

### /api-design - API 设计审查

`/api-design` 命令用于审查现有 API 或设计新的 REST API 契约。

**工作模式**

**审查模式**：分析现有 API 控制器
**设计模式**：根据需求设计新 API

**审查检查项**

| 检查项 | 说明 |
|--------|------|
| HTTP 方法 | 是否使用正确的方法（GET/POST/PUT/PATCH/DELETE） |
| 路由命名 | 是否使用复数名词、不含动词 |
| 状态码 | 是否返回正确的 HTTP 状态码 |
| 请求/响应模型 | DTO 是否正确分离 |
| 验证属性 | 是否包含适当的验证注解 |
| 安全属性 | 认证、授权、限流是否正确配置 |

资料来源：[user-level-reference/commands/api-design.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/api-design.md)

### /traceability - 需求追踪

`/traceability` 命令建立需求到代码到测试的完整追溯链。

**参数说明**

| 参数 | 类型 | 描述 |
|------|------|------|
| `$ARGUMENTS` | 可选 | 需求 ID、功能名称，或 "full" 生成完整矩阵 |

**追溯矩阵结构**

| 状态 | 计数 | 占比 |
|------|------|------|
| 完全追溯 | X | XX% |
| 部分追溯 | X | XX% |
| 不可追溯 | X | XX% |

资料来源：[user-level-reference/commands/traceability.md:1-40]()

### /user-story - 用户故事生成

`/user-story` 命令从需求生成结构化的用户故事。

**参数说明**

| 参数 | 类型 | 描述 |
|------|------|------|
| `$ARGUMENTS` | 必填 | 功能描述或需求文本 |

**生成格式**

```markdown
## Feature: [功能名称]

### User Story 1
**As a** [用户类型]
**I want to** [目标功能]
**So that** [业务价值]

#### Acceptance Criteria
- [ ] 标准 1
- [ ] 标准 2

#### Edge Cases
- [ ] 边界情况 1
```

**INVEST 标准**

| 标准 | 说明 |
|------|------|
| Independent | 可独立开发 |
| Negotiable | 细节可协商 |
| Valuable | 为用户提供价值 |
| Estimable | 可估算工作量 |
| Small | 可在一个冲刺内完成 |
| Testable | 可验证完成情况 |

资料来源：[user-level-reference/commands/user-story.md:1-80]()

## Agent 集成

斜杠命令系统与 Claude Code 的 Agent 系统深度集成，每个命令可能调用不同的专业 Agent。

### Agent 角色映射

| 命令类型 | 调用的 Agent | 模型 |
|----------|--------------|------|
| 架构设计 | `architect` | Sonnet |
| 代码实现 | `coder` | Opus |
| 代码审查 | `code-reviewer` | Sonnet |
| 文档生成 | `doc-generator` | Haiku |
| 需求工程 | `requirements-engineer` | Sonnet |
| 测试编写 | `test-writer` | Sonnet |
| QA 测试 | `tester` | Sonnet |

资料来源：[user-level-reference/README.md:15-24]()

### Agent 工作流

```mermaid
graph TD
    CMD[/command] --> ROUTER[智能体路由]
    ROUTER --> AGENT[选择合适的 Agent]
    AGENT --> TASK[分配任务]
    TASK --> EXECUTE[Agent 执行]
    EXECUTE --> RESULT[返回结果]
    RESULT --> USER[呈现给用户]
```

## 输出模式规范

斜杠命令系统采用双模式输出设计，平衡信息密度和用户需求。

### 摘要模式（默认）

- 提供执行结果的概要信息
- 高亮关键发现和建议
- 适合快速了解执行结果

### 详情模式（按需触发）

用户回复以下指令切换到详情模式：

- `show details`
- `drill in`
- `show me the code`
- 任何包含"详情"、"详细"等词的表达

切换后显示：

- 具体文件路径
- 代码行号
- 完整的分析数据

资料来源：[user-level-reference/commands/arch-doc.md:4-10]()

## 配置与扩展

### 工作流强制钩子

Claude Code Toolkit 包含以下工作流强制机制：

| 钩子类型 | 规则 | 说明 |
|----------|------|------|
| Git 工具限制 | `Bash(git/gh *)` 阻止 | 强制使用 MCP 工具 |
| 格式门控 | 提交前格式检查 | 确保代码风格一致 |
| 分支保护 | 禁止推送到 main | 强制通过 PR 流程 |
| 角色分离 | tier-before-coder | 设计评审优先于编码 |

资料来源：[README.md:20]()

### MCP 工具集成

斜杠命令系统预配置了以下 MCP 工具权限：

| 工具类别 | 工具集 |
|----------|--------|
| 版本控制 | git, github |
| 构建工具 | dotnet, rust |
| 运行时 | ollama, sqlite |
| 平台集成 | windows-mcp, searxng, open-brain |

资料来源：[README.md:22]()

## 最佳实践

### 命令使用建议

1. **按需选择命令**：根据开发阶段选择合适的命令
2. **使用摘要模式**：日常操作使用默认摘要模式
3. **按需深入详情**：需要具体信息时切换到详情模式
4. **遵循工作流**：按照命令设计的流程操作

### 组合使用示例

```mermaid
graph LR
    START([开始功能开发]) --> STORY[/user-story]
    STORY --> SPEC[/spec-to-issues]
    SPEC --> ARCH[/arch-doc]
    ARCH --> FEATURE[/new-feature]
    FEATURE --> BUILD[/build]
    BUILD --> TEST[/test]
    TEST --> COMMIT[/commit]
    COMMIT --> COVERAGE[/coverage-report]
```

## 总结

斜杠命令系统是 Claude Code Toolkit 的核心功能模块，通过 23 条预定义的斜杠命令覆盖了软件开发的完整生命周期。该系统采用统一的工作流设计、交互式输出模式和智能 Agent 集成，为开发者提供了高效、一致的命令行工作体验。

系统的模块化设计允许按需使用单个命令，同时也支持命令间的有机组合，形成完整的开发工作流。通过与 MCP 工具的深度集成，斜杠命令系统能够在 Claude Code 环境中直接执行复杂的开发任务，减少上下文切换，提高开发效率。

---

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

## 技能系统

### 相关页面

相关主题：[Agent 团队系统](#agent-team), [MCP 集成](#mcp-integration)

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

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

- [user-level-reference/skills](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills)
- [user-level-reference/skills/code-review/SKILL.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills/code-review/SKILL.md)
- [user-level-reference/skills/fix-errors/SKILL.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills/fix-errors/SKILL.md)
- [user-level-reference/commands/skill-eval.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/skill-eval.md)
- [README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)
</details>

# 技能系统

## 概述

技能系统（Skills）是 Claude Code Toolkit 中的核心自动化机制之一，旨在为开发工作流提供上下文感知的辅助能力。该系统包含 11 个自动触发技能，能够根据当前开发活动的类型自动加载对应的技能模块，涵盖调试、重构、代码审查、新代码库探索等常见开发场景。

技能系统作为工具包的重要组成部分，与智能体团队（Agents）和命令系统（Commands）协同工作，共同构成了完整的开发辅助生态。

## 系统架构

### 组件关系

```mermaid
graph TD
    subgraph "Claude Code Toolkit"
        subgraph "技能系统"
            SKILL[技能模块]
            TRIGGER[触发机制]
            CONTEXT[上下文检测]
        end
        
        subgraph "智能体团队"
            ARCH[架构师]
            CODER[编码员]
            REVIEWER[代码审查员]
        end
        
        subgraph "命令系统"
            BUILD[/build]
            TEST[/test]
            SPRINT[/sprint]
        end
    end
    
    CONTEXT --> TRIGGER
    TRIGGER --> SKILL
    SKILL --> CODER
    SKILL --> REVIEWER
```

### 技能文件结构

每个技能以独立的 Markdown 文件形式存在，统一存放于 `user-level-reference/skills/` 目录下。典型的技能文件结构如下：

```
user-level-reference/skills/
├── code-review/
│   └── SKILL.md          # 代码审查技能
├── fix-errors/
│   └── SKILL.md          # 错误修复技能
├── [其他技能目录]/
│   └── SKILL.md
```

资料来源：[user-level-reference/skills](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills)

## 技能分类与功能

### 核心技能列表

| 技能名称 | 功能描述 | 触发场景 |
|---------|---------|---------|
| code-review | 代码审查 | 代码变更提交前 |
| fix-errors | 错误修复 | 编译错误或运行时异常 |
| 调试技能 | 调试辅助 | 调试模式激活时 |
| 重构技能 | 重构建议 | 重构操作执行时 |
| 探索技能 | 代码库探索 | 首次接触新代码库 |

资料来源：[README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)

### 自动触发机制

技能系统具备智能上下文检测能力，能够自动识别开发者的当前活动类型并加载相应技能。这一机制确保了：

- **零配置使用**：开发者无需手动激活技能
- **即时响应**：技能在检测到对应场景后立即可用
- **资源优化**：仅在需要时加载相关技能模块

## 技能定义规范

### SKILL.md 文件格式

每个技能通过标准化的 SKILL.md 文件定义，包含以下核心要素：

| 要素 | 说明 | 必需性 |
|-----|------|--------|
| 触发条件 | 何时激活该技能 | 必需 |
| 执行流程 | 技能执行的具体步骤 | 必需 |
| 输出格式 | 技能执行后的输出规范 | 可选 |
| 错误处理 | 异常场景的处理策略 | 可选 |

### 代码审查技能示例

```markdown
# 代码审查技能

## 触发条件
- 开发者执行 `/code-review` 命令
- 提交前自动检查
- 代码变更超过阈值时提醒

## 执行流程
1. 分析代码变更范围
2. 检查代码质量指标
3. 识别潜在问题
4. 生成审查报告
```

资料来源：[user-level-reference/skills/code-review/SKILL.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills/code-review/SKILL.md)

### 错误修复技能示例

```markdown
# 错误修复技能

## 触发条件
- 编译错误发生
- 运行时异常捕获
- 测试失败检测

## 执行流程
1. 解析错误信息
2. 定位问题源代码
3. 分析错误根因
4. 生成修复方案
5. 验证修复结果
```

资料来源：[user-level-reference/skills/fix-errors/SKILL.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills/fix-errors/SKILL.md)

## 技能评估与验证

### skill-eval 命令

`/skill-eval` 命令用于对技能进行系统化评估，确保技能定义的有效性和执行质量。

#### 命令参数

| 参数 | 说明 | 类型 |
|-----|------|-----|
| `$ARGUMENTS` | 技能名称或评估模式 | 字符串 |

资料来源：[user-level-reference/commands/skill-eval.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/skill-eval.md)

#### 评估流程

```mermaid
graph TD
    START[启动技能评估] --> LOAD[加载技能定义]
    LOAD --> PARSE[解析 SKILL.md]
    PARSE --> VALIDATE{验证完整性}
    VALIDATE -->|通过| TEST[执行测试场景]
    VALIDATE -->|失败| REPORT[生成验证报告]
    TEST --> COVERAGE[检查覆盖范围]
    COVERAGE --> RESULT[输出评估结果]
    REPORT --> END
    RESULT --> END
```

### 评估维度

技能评估涵盖以下关键维度：

| 维度 | 评估内容 | 权重 |
|-----|---------|-----|
| 完整性 | 必需要素是否齐全 | 30% |
| 可执行性 | 流程定义是否清晰 | 25% |
| 覆盖度 | 覆盖的开发场景 | 25% |
| 可维护性 | 定义的可扩展性 | 20% |

## 技能系统集成

### 与命令系统的集成

技能系统与命令系统深度集成，命令执行时可自动调用相关技能：

| 命令 | 关联技能 |
|-----|---------|
| `/build` | 编译检查、错误修复 |
| `/test` | 测试分析、问题定位 |
| `/code-review` | 代码审查 |
| `/commit` | 提交前检查 |
| `/sprint` | 需求追踪、任务分配 |

### 与智能体团队的协作

```mermaid
graph LR
    subgraph "技能触发"
        EVENT[开发事件] --> DETECT[上下文检测]
        DETECT --> MATCH[技能匹配]
    end
    
    subgraph "智能体执行"
        MATCH --> AGENT[选择智能体]
        AGENT --> LOAD[加载技能上下文]
        LOAD --> EXECUTE[执行任务]
    end
    
    EXECUTE --> RESULT[返回结果]
```

## 使用最佳实践

### 技能定义规范

1. **明确的触发条件**：每个技能应清晰定义激活条件
2. **详细的执行流程**：步骤应具有可操作性
3. **适当的错误处理**：包含异常场景的处理指引
4. **可验证的输出**：定义明确的成功/失败标准

### 维护建议

- 定期使用 `/skill-eval` 验证技能有效性
- 根据项目需求扩展技能覆盖范围
- 保持技能定义与实际工作流同步
- 记录技能使用中的改进建议

## 相关资源

- 智能体团队文档：[README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)
- 命令系统参考：[/skill-eval 命令](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/skill-eval.md)
- 技能目录：[user-level-reference/skills](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills)

---

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

## MCP 集成

### 相关页面

相关主题：[技能系统](#skills-system), [扩展与定制](#extensibility)

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

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

- [README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)
- [user-level-reference/README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/README.md)
- [user-level-reference/commands/arch-doc.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/arch-doc.md)
</details>

# MCP 集成

## 概述

MCP（Model Context Protocol，模型上下文协议）是一种标准化通信协议，用于在 Claude Code 工作流中连接外部工具和服务。claude-code-toolkit 项目预置了 MCP 权限配置，使开发团队能够在项目中直接调用版本控制、系统构建、代码搜索等多种外部工具的能力。

claude-code-toolkit 的 MCP 集成采用 **"一次注册，作用域级管理"** 的设计理念——MCP 权限在项目级别注册一次，而非在每个命令或任务中重复配置。这种设计既简化了工具调用的复杂性，又保持了权限管理的精确性。

资料来源：[user-level-reference/README.md:30]()

## 核心设计理念

### 权限注册机制

传统工具集成需要在每个调用点单独配置凭证和权限，而 claude-code-toolkit 采用了预置权限配置方案：

| 特性 | 说明 |
|------|------|
| 作用域注册 | MCP 工具按项目作用域（scope）注册一次 |
| 复用性 | 注册后可在所有命令和任务中复用 |
| 权限粒度 | 可针对不同作用域配置不同权限集 |
| 工作流强化 | 通过 `Bash(git/gh *)` 阻止直接 shell 调用，强制使用 MCP |

资料来源：[user-level-reference/README.md:33]()

### 工具优先策略

项目明确优先使用 MCP 工具而非原生 bash 命令：

```mermaid
graph TD
    A[开发者执行命令] --> B{命令类型?}
    B -->|Git 操作| C[MCP Git 工具]
    B -->|GitHub 操作| D[MCP GitHub 工具]
    B -->|其他命令| E[Bash 执行]
    C --> F[标准化输出]
    D --> F
    E --> G[可能触发警告]
```

资料来源：[user-level-reference/README.md:33]()

## 预置 MCP 工具

claude-code-toolkit 为以下工具类别提供了预置 MCP 权限配置：

| 工具类别 | 工具名称 | 用途 |
|----------|----------|------|
| 版本控制 | git | 代码仓库操作 |
| 协作平台 | github | GitHub API 操作（Issue、PR、Repo 管理）|
| 构建工具 | dotnet | .NET 项目构建与测试 |
| 系统语言 | rust | Rust 项目编译与包管理 |
| 嵌入式数据库 | sqlite | 轻量级数据存储查询 |
| 操作系统 | windows-mcp | Windows 特定操作 |
| 搜索服务 | searxng | 元搜索引擎集成 |
| AI 服务 | ollama | 本地大模型推理 |
| 知识管理 | open-brain | 知识库/笔记系统集成 |

资料来源：[user-level-reference/README.md:33]()

## MCP 配置模板

项目提供了标准化的 MCP 配置文件模板，用于在项目中注册和管理 MCP 工具权限。

### 配置结构

MCP 配置文件采用 JSON 格式，定义工具的作用域、命令路径和参数：

```json
{
  "mcpServers": {
    "server-name": {
      "command": "executable-path",
      "args": ["optional", "arguments"]
    }
  },
  "permissions": {
    "scopes": ["scope1", "scope2"]
  }
}
```

### 配置作用域

权限按作用域（scope）进行隔离管理，常见的作用域划分：

| 作用域 | 访问范围 |
|--------|----------|
| `global` | 全局可用，所有项目共享 |
| `project` | 仅当前项目可用 |
| `session` | 仅当前会话有效 |

资料来源：[user-level-reference/.mcp.json.template](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/.mcp.json.template)

## 工作流集成

### 命令执行流程

MCP 工具在 claude-code-toolkit 的命令工作流中被广泛使用，以 `/arch-doc` 命令为例：

```mermaid
graph LR
    A[执行 /arch-doc] --> B[分析项目结构]
    B --> C[调用 map_dotnet_structure]
    C --> D[调用 analyze_project_references]
    D --> E[调用 check_framework_compatibility]
    E --> F[读取入口文件]
    F --> G[生成架构文档]
```

资料来源：[user-level-reference/commands/arch-doc.md:9-14]()

### Git 工作流强制

项目通过工作流强化机制确保 Git 操作使用 MCP 而非直接 bash：

| 操作 | 允许方式 | 阻止方式 |
|------|----------|----------|
| Git 提交 | MCP `git commit` | ❌ `Bash(git commit)` |
| Git 推送 | MCP `git push` | ❌ `Bash(git push)` |
| GitHub Issue | MCP `gh issue` | ❌ `Bash gh issue` |

资料来源：[user-level-reference/README.md:33]()

## 工具使用规范

### 调用约定

在 claude-code-toolkit 项目中使用 MCP 工具时，应遵循以下约定：

1. **显式声明**：在需要调用 MCP 工具的 Agent 定义中明确指定工具名称
2. **作用域匹配**：确保调用的工具已在当前作用域注册
3. **权限验证**：检查目标操作是否在允许的权限范围内

### 错误处理

当 MCP 工具调用失败时，项目采用分级处理策略：

```mermaid
graph TD
    A[MCP 调用] --> B{成功?}
    B -->|是| C[返回结果]
    B -->|否| D{可重试?}
    D -->|是| E[指数退避重试]
    D -->|否| F[降级到 Bash]
    E --> A
    F --> G[执行结果或报错]
```

## 多语言支持

claude-code-toolkit 的 MCP 集成针对不同技术栈提供了专门的配置：

| 技术栈 | MCP 工具 | 配置路径 |
|--------|----------|----------|
| .NET | dotnet | `.mcp.json` 中的 `dotnet` 条目 |
| Rust | rust | `.mcp.json` 中的 `rust` 条目 |
| Java | java | `.mcp.json` 中的 `java` 条目 |
| Python | python | `.mcp.json` 中的 `python` 条目 |

资料来源：[user-level-reference/README.md:16-17]()

## 扩展 MCP 配置

### 添加新工具

在项目中添加新的 MCP 工具需要以下步骤：

1. 编辑项目根目录的 `.mcp.json` 配置文件
2. 在 `mcpServers` 节中添加新服务器定义
3. 在 `permissions.scopes` 中声明需要的作用域
4. 重启 Claude Code 会话以加载新配置

### 配置示例

添加 SearXNG 搜索工具的配置示例：

```json
{
  "mcpServers": {
    "searxng": {
      "command": "searxng-mcp",
      "args": ["--base-url", "http://localhost:4000"]
    }
  },
  "permissions": {
    "scopes": ["project", "global"]
  }
}
```

## 安全考量

### 权限隔离

MCP 集成支持精细的权限控制，确保敏感操作在受控范围内执行：

- **只读操作**：可配置为全局可用
- **写操作**：限制在特定作用域，需明确授权
- **删除操作**：需要额外确认机制

### 凭证管理

MCP 工具的凭证不存储在代码仓库中，而是通过环境变量或密钥管理服务引用：

```bash
# 典型环境变量配置
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
SQLITE_DB_PATH=./data/app.db
```

## 总结

MCP 集成是 claude-code-toolkit 实现自动化开发工作流的基础设施层。通过预置权限配置、作用域级管理和工具优先策略，该项目使开发团队能够：

- 在统一的接口下调用多种外部工具
- 确保 Git/GitHub 操作通过标准化 MCP 协议执行
- 通过工作流强化机制避免绕过安全控制的直接 shell 调用
- 根据项目技术栈灵活扩展 MCP 工具集

这种设计既保持了工具集成的灵活性，又通过集中化的权限管理确保了安全性和可维护性。

---

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

## 工作流钩子与强制执行

### 相关页面

相关主题：[斜杠命令系统](#slash-commands), [系统架构](#architecture)

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

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

- [hooks/block-bash-vcs.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/block-bash-vcs.sh)
- [hooks/no-push-main.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/no-push-main.sh)
- [hooks/pre-commit-test.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/pre-commit-test.sh)
- [hooks/read-size-gate.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/read-size-gate.sh)
- [hooks/tier-before-coder.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/tier-before-coder.sh)
- [docs/hook-enforcement-ideas.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/hook-enforcement-ideas.md)
</details>

# 工作流钩子与强制执行

## 概述

工作流钩子是 Claude Code Toolkit 中的核心组件，用于在关键开发环节强制执行质量门禁和规范。这些 shell 脚本作为 Git 钩子部署，在特定的版本控制操作前自动触发，确保团队遵循既定的开发流程和最佳实践。

工作流钩子解决了几个核心问题：防止直接操作版本控制系统、强制代码审查流程、控制代码变更规模、以及确保正确的开发阶段顺序。通过在本地环境中自动执行这些检查，团队可以在代码合并到主分支之前捕获违规行为，减少后期修复成本。

## 架构设计

### 钩子组织结构

Claude Code Toolkit 的钩子系统采用模块化设计，每个钩子负责单一的检查职责。这种设计允许独立启用、禁用或修改各个检查，而不影响其他功能。钩子文件统一存放在 `hooks/` 目录下，通过符号链接或 Git 配置集成到项目的 Git 钩子生命周期中。

```mermaid
graph TD
    A[Git 操作触发] --> B[pre-commit 钩子链]
    B --> C[pre-commit-test.sh]
    B --> D[read-size-gate.sh]
    B --> E[block-bash-vcs.sh]
    
    F[pre-push 钩子链] --> G[no-push-main.sh]
    
    H[开发流程钩子] --> I[tier-before-coder.sh]
    
    C --> J{检查结果}
    D --> J
    E --> J
    G --> J
    I --> J
    
    J -->|通过| K[操作继续]
    J -->|失败| L[操作终止 + 错误信息]
```

### 钩子执行流程

钩子按照预定义的顺序执行，每个钩子独立运行并返回成功或失败状态。当任一钩子返回失败状态时，整个操作将被终止，用户需要修复问题后重新尝试。这种fail-fast机制确保了问题在早期被捕获，避免了不规范的代码进入版本控制系统。

## 核心钩子详解

### block-bash-vcs.sh — 版本控制操作拦截

**目的：** 阻止开发者直接使用 bash 命令行执行 git 或 gh 操作，强制所有版本控制操作通过 MCP 工具完成。

**实现机制：** 该钩子通过解析传递给 bash 的参数，检测是否存在直接调用 git 或 gh 命令的模式。当检测到违规模式时，脚本输出友好的错误消息，指导用户使用 MCP 工具替代。

```mermaid
graph LR
    A[bash 命令执行] --> B{检测 git/gh 调用?}
    B -->|是| C[输出错误信息]
    B -->|否| D[继续执行]
    C --> E[建议使用 MCP 工具]
    D --> F[命令正常执行]
```

**关键检测模式：**

| 检测模式 | 示例 | 说明 |
|---------|------|------|
| 直接 git 调用 | `bash git push origin main` | 检测 git 命令直接执行 |
| gh CLI 调用 | `bash gh pr create` | 检测 GitHub CLI 使用 |
| 管道组合 | `bash git \| grep` | 检测复杂的命令组合 |

**来源：** [hooks/block-bash-vcs.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/block-bash-vcs.sh)

### no-push-main.sh — 主分支推送保护

**目的：** 防止开发者直接将代码推送到 main 或 master 等受保护分支，确保所有变更都通过 Pull Request 流程合并。

**实现机制：** 该钩子在 pre-push 阶段检查目标分支名称。如果目标分支是受保护分支，钩子将拒绝推送操作并提示用户创建功能分支。

**保护策略：**

| 分支模式 | 策略 | 说明 |
|---------|------|------|
| `main` | 阻止推送 | 主发布分支 |
| `master` | 阻止推送 | 传统主分支命名 |
| `release/*` | 阻止推送 | 发布准备分支 |
| `feature/*` | 允许推送 | 功能开发分支 |
| `hotfix/*` | 需要审批 | 热修复分支 |

**来源：** [hooks/no-push-main.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/no-push-main.sh)

### pre-commit-test.sh — 提交前测试验证

**目的：** 在每次提交前自动运行测试套件，确保新代码不会破坏现有功能，维护代码库的持续可用状态。

**实现机制：** 该钩子在 pre-commit 阶段执行项目对应的测试命令。对于不同语言的项目，钩子会根据项目配置选择合适的测试运行器。

**语言特定测试命令：**

| 语言/框架 | 测试命令 | 说明 |
|----------|---------|------|
| .NET | `dotnet test` | .NET 测试框架 |
| Python | `pytest` 或 `python -m unittest` | Python 测试 |
| Rust | `cargo test` | Rust 测试框架 |
| Java | `mvn test` 或 `gradle test` | Java 测试 |

**失败处理：** 当测试失败时，钩子会输出详细的测试报告，帮助开发者快速定位问题。提交操作将被暂停，直到所有测试通过。

**来源：** [hooks/pre-commit-test.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/pre-commit-test.sh)

### read-size-gate.sh — 变更规模控制

**目的：** 防止单次提交包含过大的文件或变更集，通过设置文件大小阈值来维护代码库的健康度和可维护性。

**实现机制：** 钩子计算即将提交的文件大小总和，并与预定义的门禁值进行比较。如果总大小超过阈值，提交将被拒绝。

**配置参数：**

| 参数 | 默认值 | 说明 |
|------|-------|------|
| 单文件大小限制 | 100KB | 单个文件的最大大小 |
| 变更集大小限制 | 500KB | 一次提交的最大总大小 |
| 大小检查豁免扩展 | .bin, .dll, .zip | 不受检查的文件类型 |

**来源：** [hooks/read-size-gate.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/read-size-gate.sh)

### tier-before-coder.sh — 开发阶段顺序强制

**目的：** 确保开发流程遵循规定的阶段顺序，在执行编码工作之前必须完成需求分析和技术设计阶段。

**实现机制：** 该钩子检查项目中是否存在已完成的前置阶段文件或标记。如果 coder 角色被调用而 tier 阶段尚未完成，钩子会阻止操作并提示完成必要的前置工作。

**阶段依赖关系：**

```mermaid
graph LR
    A[Tier 阶段] --> B{阶段完成检查}
    B -->|未完成| C[阻止 coder 执行]
    B -->|已完成| D[允许 coder 执行]
    D --> E[Coder 阶段]
    E --> F[Code Review]
```

**检查内容：**

| 阶段标记 | 文件/目录 | 说明 |
|---------|----------|------|
| 技术设计 | `docs/architecture/` | 架构设计文档 |
| 需求分析 | `docs/requirements/` | 需求规格说明 |
| 技术评审 | `.tier-complete` | 阶段完成标记 |

**来源：** [hooks/tier-before-coder.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/hooks/tier-before-coder.sh)

## 钩子配置与管理

### 安装钩子

Claude Code Toolkit 提供了自动化安装脚本，将钩子符号链接到 Git 钩子目录：

```bash
# 使用项目提供的安装脚本
./setup-project.sh --variant <variant-name>

# 或手动安装
ln -s ../../hooks/pre-commit-test.sh .git/hooks/pre-commit
ln -s ../../hooks/no-push-main.sh .git/hooks/pre-push
```

### 跳过钩子（紧急情况）

在紧急修复场景下，可能需要临时跳过钩子检查。Git 提供了 `--no-verify` 选项来绕过钩子，但应谨慎使用：

```bash
# 跳过 pre-commit 钩子直接提交
git commit --no-verify -m "Emergency fix"

# 跳过 pre-push 钩子直接推送
git push --no-verify origin feature-branch
```

### 钩子禁用

可以在项目根目录创建 `.git-hooks-disabled` 文件来全局禁用钩子：

```bash
# 禁用所有钩子
touch .git-hooks-disabled

# 禁用特定钩子
echo "pre-commit-test" >> .git-hooks-disabled
```

## 强制执行理念

根据项目文档，工作流钩子的设计遵循以下核心原则：

| 原则 | 说明 | 来源 |
|------|------|------|
| 自动化优于人工 | 减少对人工遵守规范的依赖，通过自动化检查确保一致性 | docs/hook-enforcement-ideas.md |
| 早期失败 | 在开发周期的早期发现问题，比后期修复成本更低 | docs/hook-enforcement-ideas.md |
| 明确反馈 | 钩子失败时提供清晰的错误消息和修复建议 | docs/hook-enforcement-ideas.md |
| 灵活性与刚性平衡 | 允许紧急情况下的绕过机制，但默认强制执行 | docs/hook-enforcement-ideas.md |

## 最佳实践

### 开发团队指南

1. **始终使用 MCP 工具** 进行版本控制操作，避免直接使用 bash git/gh 命令
2. **保持提交小型化**，每次提交专注于单一功能或修复
3. **确保测试通过** 后再尝试提交，充分利用本地测试反馈
4. **遵循阶段顺序**，在开始编码前完成必要的技术设计

### CI/CD 集成

虽然本地钩子提供了第一道防线，但在持续集成环境中也应部署相同的检查，以确保无法绕过的质量门禁：

```yaml
# CI 环境中的等效检查
lint:
  script:
    - ./hooks/block-bash-vcs.sh || exit 1
    
test:
  script:
    - ./hooks/pre-commit-test.sh || exit 1
```

## 故障排查

### 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 提交被莫名阻止 | pre-commit-test.sh 检测到测试失败 | 修复失败的测试或相关代码 |
| 无法推送到功能分支 | 目标分支名称包含受保护模式 | 检查分支命名是否符合规范 |
| bash 命令被拦截 | 误用了 git/gh 命令 | 改用 MCP 工具执行版本控制操作 |
| 文件大小超限 | 提交了大型二进制文件 | 使用 Git LFS 或拆分提交 |

### 调试钩子

启用调试模式查看钩子执行详情：

```bash
# 启用 bash 调试输出
bash -x .git/hooks/pre-commit-test.sh

# 查看详细的 Git 钩子执行信息
GIT_TRACE=1 git commit -m "test"
```

## 相关资源

- [钩子强制执行理念文档](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/hook-enforcement-ideas.md)
- [Git 钩子官方文档](https://git-scm.com/docs/githooks)
- Claude Code Toolkit 主 README

---

<a id='extensibility'></a>

## 扩展与定制

### 相关页面

相关主题：[Agent 团队系统](#agent-team), [MCP 集成](#mcp-integration), [相关项目](#related-projects)

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

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

- [CONTRIBUTING.md](https://github.com/dagonet/claude-code-toolkit/blob/main/CONTRIBUTING.md)
- [docs/template-sync.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/template-sync.md)
- [user-level-reference/skills/contribute-upstream/SKILL.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills/contribute-upstream/SKILL.md)
- [user-level-reference/skills/sync-template/SKILL.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills/sync-template/SKILL.md)
- [user-level-reference/skills/new-feature/SKILL.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/skills/new-feature/SKILL.md)
</details>

# 扩展与定制

Claude Code Toolkit 是一个专为 Claude Code 工作流设计的生产级工具包，支持通过多种方式进行扩展和定制。本页面详细介绍如何基于现有架构扩展功能、定制 Agent 行为、以及参与上游项目贡献。

## 概述

Claude Code Toolkit 提供了完整的开发生命周期支持，包括 6 种模板变体、7-8 个专用 Agent、23 个用户级命令和 11 个自动触发技能。所有组件都遵循可扩展原则设计，允许开发者根据项目需求进行深度定制。

资料来源：[README.md:1-30]()

## 模板变体体系

### 支持的变体类型

Claude Code Toolkit 提供以下模板变体，每个变体包含语言特定的构建钩子、格式校验和约定规范：

| 变体名称 | 语言/框架 | 特定 Agent | 主要用途 |
|---------|----------|-----------|---------|
| `general` | 通用 | - | 适用于任何语言的基础模板 |
| `dotnet` | .NET | dotnet-coder | C#/.NET Core 企业级开发 |
| `dotnet-maui` | .NET MAUI | dotnet-coder | 跨平台移动应用开发 |
| `rust-tauri` | Rust + Tauri | rust-coder | 轻量级桌面应用 |
| `java` | Java | java-coder | Java/Kotlin 企业应用 |
| `python` | Python | python-coder | Python 数据科学/后端 |

资料来源：[README.md:1-30]()

### 变体架构

```mermaid
graph TB
    subgraph "模板变体层"
        G[general]
        D[dotnet]
        DM[dotnet-maui]
        R[rust-tauri]
        J[java]
        P[python]
    end
    
    subgraph "共享基础设施"
        CMDS[23 用户命令]
        AGENTS[7-8 Agents]
        SKILLS[11 自动技能]
        MCP[MCP 权限]
    end
    
    subgraph "工作流钩子"
        BUILD[构建钩子]
        FORMAT[格式校验]
        COMMIT[提交规范]
    end
    
    G --> CMDS
    D --> CMDS
    R --> CMDS
    CMDS --> AGENTS
    CMDS --> SKILLS
    AGENTS --> MCP
```

资料来源：[README.md:1-30]()

## Agent 定制

### Agent 角色体系

每个模板变体包含以下 Agent 角色，形成完整的开发闭环：

| Agent 角色 | 默认模型 | 职责范围 |
|-----------|---------|---------|
| `architect` | opus | 架构设计与技术决策 |
| `coder` | opus | 功能实现与代码编写 |
| `code-reviewer` | sonnet | 代码审查与质量评估 |
| `doc-generator` | haiku | 文档生成 |
| `requirements-engineer` | sonnet | 需求分析与用户故事 |
| `test-writer` | sonnet | 测试用例编写 |
| `tester` | sonnet | QA 验证与自动化测试 |
| `* coder` | - | 语言特定开发（如 dotnet-coder） |

资料来源：[user-level-reference/README.md:1-50]()

### 自定义 Agent 行为

通过编辑 `CLAUDE.md` 文件中的 Agent 定义，可以定制 Agent 的行为参数：

```markdown
# Agent 定义示例
- name: coder
  model: opus
  description: 通用代码编写专家
  instructions: |
    - 优先遵循 .editorconfig 规范
    - 复杂逻辑必须添加注释
    - 单个文件不超过 300 行
```

## 命令扩展

### 现有命令概览

Claude Code Toolkit 提供 23 个用户级斜杠命令，涵盖开发全流程：

**开发类命令**

| 命令 | 功能描述 |
|-----|---------|
| `/build` | 构建项目并迭代修复错误 |
| `/test` | 运行测试并修复失败 |
| `/commit` | 通过 MCP git 工具暂存和提交 |
| `/new-feature` | 脚手架新功能模块 |
| `/add-tests` | 为现有代码生成单元测试 |
| `/sprint` | 并行 Agent 工作流执行 |

**架构类命令**

| 命令 | 功能描述 |
|-----|---------|
| `/arch-doc` | 从代码分析生成架构文档 |
| `/api-design` | 审查或设计 REST API 契约 |
| `/challenge` | 挑战计划、方案或设计 |
| `/dependency-audit` | 查找循环依赖和孤立项目 |

资料来源：[user-level-reference/README.md:1-50]()

### 新功能脚手架工作流

`/new-feature` 命令是扩展项目功能的核心入口，其完整工作流程如下：

```mermaid
graph TD
    A[解析 feature 名称和需求] --> B{需求是否清晰?}
    B -->|否| C[询问澄清问题]
    C --> A
    B -->|是| D[分析现有架构]
    D --> E[调用 map_dotnet_structure]
    D --> F[调用 analyze_project_references]
    E --> G[规划功能结构]
    F --> G
    G --> H[呈现创建计划]
    H --> I{用户批准?}
    I -->|否| J[等待用户修改]
    J --> H
    I -->|是| K[创建脚手架文件]
    K --> L[注册依赖项]
    L --> M[创建初始测试]
```

**文件创建规划**

执行 `/new-feature` 时，系统会分析项目结构并输出待创建文件列表：

```
## Feature: [Name]

### Files to Create
- [ ] src/Domain/Entities/[Name].cs
- [ ] src/Application/[Name]/Commands/Create[Name]Command.cs
- [ ] src/Application/[Name]/Queries/Get[Name]Query.cs
- [ ] tests/UnitTests/[Name]Tests.cs

### Dependencies
- [ ] Register in DI container
- [ ] Add to DbContext (if applicable)
```

资料来源：[user-level-reference/commands/new-feature.md:1-60]()

## 技能系统

### 自动触发技能

Claude Code Toolkit 包含 11 个自动触发技能，它们会根据上下文自动加载：

| 技能名称 | 触发场景 | 功能 |
|---------|---------|-----|
| `debugger` | 调试时 | 断点、日志分析、堆栈追踪 |
| `refactor` | 重构时 | 代码结构优化、依赖分析 |
| `explore` | 探索新代码库 | 快速理解项目结构 |
| `contribute-upstream` | 贡献上游时 | 同步上游变更 |
| `sync-template` | 同步模板时 | 模板更新同步 |

资料来源：[README.md:1-30]()

### 技能文件结构

技能定义文件遵循统一结构，位于 `user-level-reference/skills/` 目录下：

```
user-level-reference/skills/
├── contribute-upstream/
│   └── SKILL.md          # 上游贡献技能
├── sync-template/
│   └── SKILL.md          # 模板同步技能
└── new-feature/
    └── SKILL.md          # 新功能技能
```

## 模板同步机制

### sync-template 技能

`sync-template` 技能允许用户将上游模板更新同步到已存在的项目中，避免重复配置：

```mermaid
graph TD
    A[执行 /sync-template] --> B[获取当前配置差异]
    B --> C{是否强制同步?}
    C -->|是| D[应用所有更新]
    C -->|否| E[用户选择保留项]
    E --> F[应用选定更新]
    F --> G[更新 CLAUDE.md]
    D --> G
    G --> H[同步命令定义]
    H --> I[同步 Agent 定义]
    I --> J[报告变更摘要]
```

### 同步策略

| 策略 | 说明 | 使用场景 |
|-----|------|---------|
| `force` | 强制覆盖所有本地修改 | 全新项目或完全重构 |
| `interactive` | 交互式选择保留项 | 保留部分自定义配置 |
| `check-only` | 仅检查差异，不应用 | 评估同步影响 |

资料来源：[docs/template-sync.md](), [user-level-reference/skills/sync-template/SKILL.md]()

## 上游贡献

### contribute-upstream 技能

当用户希望将改进贡献回上游项目时，`/contribute-upstream` 技能提供完整的贡献工作流：

```mermaid
graph LR
    A[准备变更] --> B[创建 Fork]
    B --> C[提交 PR]
    C --> D[响应审查]
    D --> E{审查通过?}
    E -->|否| F[修改代码]
    F --> D
    E -->|是| G[合并完成]
```

### 贡献工作流规范

| 阶段 | 操作 | 规范要求 |
|-----|------|---------|
| 分支创建 | 基于 main 创建功能分支 | `feat/xxx` 或 `fix/xxx` 格式 |
| 提交规范 | 遵循 Conventional Commits | `type(scope): description` |
| 测试覆盖 | 新功能必须包含测试 | 单元测试 + 集成测试 |
| 文档更新 | API 变更需同步文档 | 更新相关 Markdown 文件 |

资料来源：[CONTRIBUTING.md](), [user-level-reference/skills/contribute-upstream/SKILL.md]()

## MCP 集成扩展

### 预配置 MCP 权限

Claude Code Toolkit 提供预配置的 MCP 权限，在每个作用域注册一次，而非按项目注册：

| MCP 服务 | 权限范围 | 用途 |
|---------|---------|-----|
| git | 所有操作 | 版本控制 |
| github | 仓库管理 | Issue/PR 操作 |
| dotnet | 构建/测试 | .NET 项目操作 |
| rust | Cargo 操作 | Rust 项目管理 |
| ollama | LLM 交互 | 本地模型调用 |
| sqlite | 数据库操作 | 数据验证 |
| windows-mcp | Windows 特定 | 系统级操作 |
| searxng | 搜索功能 | 知识检索 |
| open-brain | 知识库 | 上下文增强 |

资料来源：[README.md:1-30]()

### 扩展 MCP 配置

用户可以通过编辑项目根目录的 MCP 配置文件添加新的服务：

```json
{
  "mcpServers": {
    "custom-service": {
      "command": "npx",
      "args": ["-y", "@org/custom-mcp"]
    }
  }
}
```

## 工作流钩子

### 提交前钩子

Claude Code Toolkit 实施工作流强制钩子，确保代码质量：

| 钩子类型 | 拦截条件 | 说明 |
|---------|---------|-----|
| Git 命令限制 | `Bash(git/gh *)` | 强制使用 MCP 工具 |
| 格式校验 | 提交时检查 | 遵循项目格式规范 |
| 主分支保护 | 禁止直接推送 main | 必须通过 PR 合并 |
| Tier 分级 | coder 任务前置检查 | 需经过 architect 评审 |

资料来源：[README.md:1-30]()

## 快速开始

### 1. 安装依赖

```bash
# 基础依赖
git
Node.js 18+

# Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 变体特定依赖
# .NET: .NET SDK
# Rust: Rust 工具链
# Java: JDK
# Python: Python 环境
```

### 2. 创建项目

```bash
# 克隆工具包
git clone https://github.com/dagonet/claude-code-toolkit
cd claude-code-toolkit

# 初始化项目
./setup-project.sh --variant python --project-name MyApp --target-path ../my-app

# Windows
.\setup-project.ps1 -Variant python -ProjectName MyApp -TargetPath ..\my-app
```

### 3. 验证安装

```bash
# 检查可用命令
claude-code --help

# 测试工作流
claude-code "/build"
claude-code "/test"
```

## 最佳实践

### 定制建议

1. **保持模板更新**：定期执行 `/sync-template` 以获取上游改进
2. **遵循 Agent 角色**：不同任务使用对应 Agent，避免越权操作
3. **完善文档**：新增功能应同步更新文档和测试用例
4. **贡献上游**：通用改进应考虑贡献回上游仓库

### 扩展检查清单

在扩展 Claude Code Toolkit 时，参考以下检查项：

- [ ] 新增命令是否遵循现有命名规范
- [ ] 新增 Agent 是否定义清晰的职责边界
- [ ] 新增技能是否配置适当的触发条件
- [ ] MCP 集成是否遵循安全最佳实践
- [ ] 变更是否包含相应的测试覆盖

---

<a id='architecture'></a>

## 系统架构

### 相关页面

相关主题：[快速开始](#quick-start), [模板变体系统](#template-variants), [工作流钩子与强制执行](#workflow-hooks)

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

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

- [README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)
- [user-level-reference/commands/arch-doc.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/arch-doc.md)
- [user-level-reference/commands/new-feature.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/new-feature.md)
- [user-level-reference/commands/api-design.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/api-design.md)
- [user-level-reference/commands/tech-debt.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/commands/tech-debt.md)
- [user-level-reference/README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/user-level-reference/README.md)
</details>

# 系统架构

## 概述

Claude Code Toolkit 是一个用于快速启动生产级 Claude Code 工作流的工具包。其核心目标是让开发者通过一条命令即可获得一套包含智能体团队、斜杠命令、自动触发技能、MCP 权限和工作流执行钩子的完整开发环境。

资料来源：[README.md:1-15]()

## 整体架构

### 架构设计原则

Claude Code Toolkit 采用模块化设计，支持多语言变体，每个变体都包含语言特定的构建钩子、格式门禁和开发约定。系统通过模板引擎生成项目结构，确保所有生成的项目遵循统一的架构规范。

### 核心组件层次

```mermaid
graph TB
    subgraph 用户交互层
        CMD[斜杠命令]
        SKILL[自动触发技能]
    end
    
    subgraph 智能体层
        ARCH[架构师]
        CODER[编码器]
        REVIEWER[代码审查员]
        DOC[文档生成器]
        RE[需求工程师]
        TW[测试编写者]
        TEST[测试员]
    end
    
    subgraph 工具层
        MCP[MCP 工具集]
        GIT[Git/GitHub]
        BUILD[构建系统]
    end
    
    subgraph 执行层
        WORKFLOW[工作流钩子]
        FORMAT[格式门禁]
    end
    
    CMD --> ARCH
    CMD --> CODER
    CMD --> REVIEWER
    SKILL --> ARCH
    SKILL --> DOC
    ARCH --> MCP
    CODER --> GIT
    CODER --> BUILD
    REVIEWER --> FORMAT
    WORKFLOW --> GIT
```

资料来源：[user-level-reference/README.md:1-25]()

## 模板架构

### 模板变体

项目提供 6 种模板变体，每种针对特定技术栈优化：

| 变体 | 语言 | 特定智能体 | 构建工具 | 格式门禁 |
|------|------|------------|----------|----------|
| general | 通用 | - | - | 通用 |
| dotnet | C#/.NET | dotnet-coder | dotnet build | dotnet format |
| dotnet-maui | .NET MAUI | dotnet-coder | dotnet build | dotnet format |
| rust-tauri | Rust | rust-coder | cargo build | rustfmt |
| java | Java | java-coder | Maven/Gradle | google-java-format |
| python | Python | python-coder | pip/poetry | black/isort |

资料来源：[README.md:19-26]()

### 模板结构

每个模板包含以下核心文件：

```mermaid
graph TD
    T[模板目录]
    T --> AGENT[AGENT_TEAM.md]
    T --> CTX[PROJECT_CONTEXT.md]
    T --> CMDS[commands/]
    T --> SKILLS[skills/]
    T --> CFG[.claude/]
    
    AGENT --> DEF[智能体定义]
    CTX --> PROJ[项目上下文]
    CMDS --> SLASH[斜杠命令]
    SKILLS --> TRIGGER[触发规则]
    CFG --> MCP_PERMS[MCP 权限配置]
```

资料来源：[README.md:26-35]()

## 智能体团队架构

### 智能体矩阵

| 智能体名称 | 模型 | 职责范围 |
|------------|------|----------|
| architect | sonnet | 系统架构设计、模式选择、技术栈规划 |
| coder | opus | 实现功能变更，遵循高质量工程标准 |
| code-reviewer | sonnet | 质量、风格、结构审查，发布分类报告，不编写代码 |
| doc-generator | haiku | 公共 API 和使用示例的文档生成 |
| requirements-engineer | sonnet | 将功能想法细化为详细规格、用户故事、验收标准 |
| test-writer | sonnet | 为新代码编写全面测试，聚焦行为和边界情况 |
| tester | sonnet | 通过 UI 自动化、数据库检查和日志分析验证功能 |

资料来源：[user-level-reference/README.md:8-18]()

### 智能体协作流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant CMD as 斜杠命令
    participant ARCH as 架构师
    participant RE as 需求工程师
    participant TW as 测试编写者
    participant CODER as 编码器
    participant REVIEWER as 代码审查员
    
    U->>CMD: /new-feature
    CMD->>ARCH: 分析需求
    ARCH->>RE: 细化规格
    RE->>TW: 编写测试规范
    TW->>CODER: 提供测试用例
    CODER->>REVIEWER: 提交代码
    REVIEWER-->>U: 审查报告
```

## 斜杠命令系统

### 命令分类

项目包含 23 个斜杠命令，分为以下类别：

#### 开发命令

| 命令 | 功能描述 |
|------|----------|
| /build | 构建项目并迭代修复错误 |
| /test | 运行测试并修复失败 |
| /commit | 通过 MCP git 工具暂存并提交变更 |
| /new-feature | 使用正确的架构模式脚手架新功能 |
| /add-tests | 为现有代码生成单元测试 |
| /godot-run | 运行 Godot 项目并捕获调试输出 |
| /sprint | 执行冲刺，并行运行智能体工作流 |

资料来源：[user-level-reference/README.md:27-34]()

#### 架构命令

| 命令 | 功能描述 |
|------|----------|
| /arch-doc | 从代码分析生成架构文档 |
| /api-design | 审查或设计 REST API 契约 |
| /challenge | 用两个结构化步骤挑战计划、方案或设计 |
| /dependency-audit | 查找循环依赖和孤立项目 |

资料来源：[user-level-reference/README.md:41-45]()

### 架构文档生成流程

`/arch-doc` 命令遵循系统化的架构分析流程：

```mermaid
flowchart TD
    START[开始分析] --> STRUCTURE[分析解决方案结构]
    STRUCTURE --> CALL1[调用 map_dotnet_structure]
    CALL1 --> CALL2[调用 analyze_project_references]
    CALL2 --> CALL3[调用 check_framework_compatibility]
    CALL3 --> ENTRY[读取入口点]
    ENTRY --> DI[识别 DI 注册]
    DI --> CONFIG[定位配置文件]
    CONFIG --> INTERFACES[查找关键接口]
    INTERFACES --> MAPPING[映射项目用途]
    MAPPING --> DIAGRAM[生成依赖图]
    DIAGRAM --> OUTPUT[输出文档]
```

资料来源：[user-level-reference/commands/arch-doc.md:8-20]()

### 新功能脚手架流程

`/new-feature` 命令使用 Clean Architecture 模式：

```mermaid
flowchart LR
    subgraph Domain
        E[实体]
        VO[值对象]
        I[接口]
    end
    
    subgraph Application
        CMD[命令/查询]
        HAND[处理器]
        VAL[验证器]
    end
    
    subgraph Infrastructure
        REPO[仓储]
        EXT[外部服务]
    end
    
    subgraph API
        CTRL[控制器]
        REQ[请求模型]
        RESP[响应模型]
    end
```

资料来源：[user-level-reference/commands/new-feature.md:20-35]()

## MCP 工具集成

### MCP 权限配置

系统为以下工具预配置了 MCP 权限，按作用域注册而非按项目注册：

| 工具类别 | MCP 工具 |
|----------|----------|
| 版本控制 | git, github |
| 构建系统 | dotnet, rust |
| 运行时 | ollama, sqlite |
| 平台特定 | windows-mcp |
| 搜索 | searxng |
| AI | open-brain |

资料来源：[README.md:36-38]()

### 工作流执行钩子

系统实现了严格的工作流执行钩子机制：

| 钩子类型 | 规则 |
|----------|------|
| Bash 限制 | `Bash(git/gh *)` 被阻止，优先使用 MCP |
| 提交门禁 | 提交时必须通过格式检查 |
| 分支保护 | 禁止直接推送到 main 分支 |
| 审批流程 | tier-before-coder（分层审批） |

资料来源：[README.md:39-40]()

## 技能系统

### 自动触发技能

项目包含 11 个自动触发技能，它们根据当前工作上下文自动加载：

```mermaid
graph LR
    subgraph 技能类型
        DEBUG[调试技能]
        REFACTOR[重构技能]
        EXPLORE[代码探索技能]
    end
    
    subgraph 触发条件
        ERR[错误状态]
        CODE[代码变更]
        NEW[新代码库]
    end
    
    ERR --> DEBUG
    CODE --> REFACTOR
    NEW --> EXPLORE
```

技能系统通过监视文件变化和用户操作，自动激活相应的技能模块，提供上下文感知的辅助。

## 架构分析工具

### 技术债务评估

`/tech-debt` 命令使用多维度分析：

| 分析类别 | 检查项 | 权重 |
|----------|--------|------|
| 代码质量债务 | 复杂方法、上帝类、大型文件 | 5-15 分/项 |
| 架构债务 | 循环依赖、层边界违反 | 计入总分 |
| 依赖债务 | 过时包、弃用包、安全漏洞 | 5-20 分/项 |
| 文档债务 | 缺失 XML 文档、过期 README | 计入总分 |

资料来源：[user-level-reference/commands/tech-debt.md:60-85]()

### 依赖审计

系统通过以下方式检测依赖问题：

```mermaid
flowchart TD
    SCAN[扫描依赖] --> VULN[检查安全漏洞]
    VULN --> OUTDATED[检查过时版本]
    OUTDATED --> TRANSITIVE[分析传递依赖]
    TRANSITIVE --> CONFLICT[检测版本冲突]
    CONFLICT --> REPORT[生成报告]
```

## 部署架构

### 快速启动流程

```mermaid
flowchart TD
    A[安装前置条件] --> B[克隆仓库]
    B --> C[运行设置脚本]
    C --> D[选择模板变体]
    D --> E[配置目标路径]
    E --> F[生成项目结构]
    F --> G[初始化工作流]
    G --> H[验证环境]
```

### 环境要求

| 组件 | 最低版本 | 说明 |
|------|----------|------|
| git | - | 版本控制 |
| Node.js | 18+ | Claude Code CLI 运行基础 |
| Claude Code CLI | 最新 | npm install -g @anthropic-ai/claude-code |
| 变体特定 | 见文档 | .NET SDK、Rust、JDK、Python 等 |

资料来源：[README.md:47-50]()

## 扩展架构

### 添加新模板变体

添加新变体需要创建以下结构：

```
templates/
└── [variant-name]/
    ├── AGENT_TEAM.md      # 智能体定义
    ├── PROJECT_CONTEXT.md # 项目上下文
    ├── commands/          # 变体特定命令
    ├── skills/            # 变体特定技能
    └── .claude/           # MCP 配置
```

### 添加新命令

新命令需要在 `user-level-reference/commands/` 目录下创建 Markdown 文件，包含：

- 命令描述和参数定义
- 工作流程步骤
- 输出模板
- 规则和约束

## 总结

Claude Code Toolkit 的系统架构采用分层设计，通过模板系统实现多语言支持，智能体团队提供专业分工，斜杠命令简化日常开发操作，MCP 集成确保工具链一致性，工作流钩子保证代码质量标准得到执行。这套架构使得团队能够快速建立标准化的开发工作流，同时保持足够的灵活性以适应不同技术栈的需求。

---

<a id='related-projects'></a>

## 相关项目

### 相关页面

相关主题：[MCP 集成](#mcp-integration), [扩展与定制](#extensibility)

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

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

- [README.md](https://github.com/dagonet/claude-code-toolkit/blob/main/README.md)
- [docs/getting-started.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/getting-started.md)
- [docs/dotnet-specific.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/dotnet-specific.md)
- [docs/python-specific.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/python-specific.md)
- [docs/java-specific.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/java-specific.md)
- [docs/rust-specific.md](https://github.com/dagonet/claude-code-toolkit/blob/main/docs/rust-specific.md)
- [setup-project.sh](https://github.com/dagonet/claude-code-toolkit/blob/main/setup-project.sh)
</details>

# 相关项目

## 概述

Claude Code Toolkit 提供 **6 种项目模板变体（Template Variants）**，每种变体针对特定的编程语言和技术栈进行了优化配置。这些变体预先集成了语言特定的构建钩子（Build Hooks）、代码格式门禁（Format Gates）以及约定俗成的开发规范，使开发团队能够在不同技术栈上快速启动标准化的工作流程。资料来源：[README.md:1-15]()

项目变体通过 `setup-project.sh` 脚本的 `--variant` 参数指定，支持的命令包括 `general`、`dotnet`、`dotnet-maui`、`rust-tauri`、`java` 和 `python`。每种变体都会生成对应的代理团队、命令集、技能和工作流配置。资料来源：[setup-project.sh:45-80]()

## 项目变体总览

| 变体名称 | 技术栈 | 特定代理 | 构建命令 | 格式工具 |
|---------|--------|----------|----------|----------|
| `general` | 通用 | 默认团队 | 无特定 | 无特定 |
| `dotnet` | .NET 8 | dotnet-coder | `dotnet build` | `dotnet format` |
| `dotnet-maui` | .NET MAUI | dotnet-coder | `dotnet build` | `dotnet format` |
| `rust-tauri` | Rust + Tauri | rust-coder | `cargo build` | `cargo fmt` |
| `java` | Java | java-coder | `mvn build` | `google-java-format` |
| `python` | Python | python-coder | `pip/poetry` | `black` / `ruff` |

资料来源：[README.md:18-25]()

## 架构设计

### 变体继承关系

```mermaid
graph TD
    A[通用基础配置] --> B[General Variant]
    A --> C[.NET Variant]
    A --> D[Rust-Tauri Variant]
    A --> E[Java Variant]
    A --> F[Python Variant]
    
    C --> C1[dotnet-maui]
    
    B --> G[Agent Team]
    C --> G
    D --> G
    E --> G
    F --> G
    
    G --> H[7-8 Agents per Variant]
    H --> H1[architect]
    H --> H2[code-reviewer]
    H --> H3[coder]
    H --> H4[doc-generator]
    H --> H5[requirements-engineer]
    H --> H6[test-writer]
    H --> H7[tester]
    H --> H8[Language-Specific Coder]
```

每个变体都继承通用配置，并添加语言特定的工具链、代理和工作流。这种分层设计确保了核心功能的统一性，同时保留了各技术栈的独特需求。资料来源：[README.md:25-30]()

### 工作流集成

```mermaid
graph LR
    A[setup-project.sh] --> B[Project Structure]
    B --> C[Agents]
    B --> D[Commands]
    B --> E[Skills]
    B --> F[MCP Permissions]
    
    C --> G[/build /test /commit /sprint]
    D --> G
```

项目变体生成后，立即可用的工作流包括 `/build`（构建并迭代修复错误）、`/test`（运行测试并修复失败）、`/commit`（通过 MCP git 工具暂存和提交）以及 `/sprint`（并行代理工作流的敏捷执行）。资料来源：[README.md:45-55]()

## 各变体详细说明

## .NET 变体

### dotnet

适用于标准 .NET 8 应用程序开发。该变体包含 `dotnet-coder` 代理，专门处理 C# 代码生成和 .NET 特定模式。构建系统使用 `dotnet build`，代码格式化使用 `dotnet format`，测试框架默认为 xUnit。资料来源：[docs/dotnet-specific.md:1-20]()

关键集成点：

- **MCP 权限**：`dotnet` 工具链的完整访问权限
- **格式门禁**：提交前自动检查代码格式
- **构建钩子**：集成到 CI/CD 流程的构建验证

### dotnet-maui

针对 .NET Multi-platform App UI (MAUI) 项目进行了优化。除了标准 .NET 变体的所有功能外，还包含移动端构建配置、平台特定资源处理以及设备模拟器集成。资料来源：[docs/dotnet-specific.md:25-40]()

## Rust-Tauri 变体

Rust-Tauri 变体专为使用 Rust 语言和 Tauri 框架构建跨平台桌面应用程序的开发者设计。`rust-coder` 代理熟悉 Cargo 工作区结构、crate 依赖管理以及 Tauri 前端集成模式。资料来源：[docs/rust-specific.md:1-25]()

| 组件 | 工具 | 说明 |
|------|------|------|
| 构建系统 | Cargo | Rust 包管理器和构建工具 |
| 格式工具 | cargo fmt | Rust 官方格式化工具 |
| 前端框架 | Tauri | 轻量级桌面应用框架 |
| 包注册表 | crates.io | Rust 官方 crate 仓库 |

## Java 变体

Java 变体针对使用 Maven 或 Gradle 构建的企业级 Java 应用程序。`java-coder` 代理遵循 Spring Boot 约定，支持 Jakarta EE 规范，并使用 `google-java-format` 确保代码风格一致。资料来源：[docs/java-specific.md:1-30]()

项目结构遵循标准 Maven 约定：
- 源代码位于 `src/main/java`
- 测试代码位于 `src/test/java`
- 资源文件位于 `src/main/resources`

## Python 变体

Python 变体支持现代 Python 开发工作流，可选择 Poetry 或 pip 作为包管理器。`python-coder` 代理熟悉虚拟环境管理、类型提示规范（PEP 484）以及 pytest 测试框架。资料来源：[docs/python-specific.md:1-30]()

| 工具 | 用途 | 配置位置 |
|------|------|----------|
| black | 代码格式化 | pyproject.toml |
| ruff | Linting/代码检查 | pyproject.toml |
| pytest | 测试框架 | pytest.ini |
| mypy | 类型检查 | mypy.ini |

## General 变体

通用变体不针对任何特定语言，适合多语言项目或技术栈尚未确定的初始阶段。它提供了基础的代理团队和工作流，所有语言特定的工具钩子保持禁用状态。资料来源：[docs/getting-started.md:15-25]()

当团队需要支持混合技术栈（如 Python 后端配合 Rust 微服务）时，General 变体可作为统一的起点，后续根据需要扩展特定语言配置。

## 项目创建工作流

### 命令行接口

```bash
./setup-project.sh --variant <VARIANT> --project-name <NAME> --target-path <PATH>
# Windows PowerShell
.\setup-project.ps1 -Variant <VARIANT> -ProjectName <NAME> -TargetPath <PATH>
```

参数说明：

| 参数 | 必填 | 说明 | 示例值 |
|------|------|------|--------|
| `--variant` | 是 | 项目模板变体 | `python` |
| `--project-name` | 是 | 项目名称（PascalCase） | `MyApp` |
| `--target-path` | 是 | 目标目录路径 | `../my-app` |

资料来源：[setup-project.sh:45-55]()

### 生成内容

每个变体创建的文件结构包括：

```
<target-path>/
├── CLAUDE.md              # Claude Code 工作流指南
├── agents/               # 代理配置文件
├── commands/             # 自定义斜杠命令
├── skills/               # 自动触发技能
├── .claude/              # MCP 权限配置
│   └── permissions.yml
├── hooks/                # 工作流钩子
│   ├── pre-commit        # 提交前检查
│   └── pre-push          # 推送前检查
└── [语言特定文件]
```

资料来源：[docs/getting-started.md:30-50]()

## MCP 权限配置

每种变体都预配置了相应的 MCP 权限，按作用域注册而非按项目注册，避免重复配置。资料来源：[README.md:50-55]()

| 变体 | MCP 工具集 |
|------|-----------|
| general | git, github, sqlite |
| dotnet | dotnet, git, github |
| rust-tauri | rust, ollama, git, github |
| java | git, github, open-brain |
| python | python, git, github, searxng |

## 自动触发技能

项目变体包含 **11 个自动触发技能**，根据当前工作上下文自动加载，无需手动调用。资料来源：[README.md:40-45]()

| 技能类型 | 触发条件 | 功能 |
|---------|----------|------|
| 调试技能 | 错误日志出现 | 分析堆栈跟踪、定位问题 |
| 重构技能 | 重构标记存在 | 识别代码异味、建议改进 |
| 探索技能 | 首次访问代码库 | 生成代码地图、依赖关系图 |
| 代码审查技能 | PR 创建时 | 自动审查代码质量 |

## 相关资源

- [入门指南](docs/getting-started.md) - 详细的安装和配置说明
- [Agent 团队文档](agents/README.md) - 各代理角色职责说明
- [命令参考](commands/README.md) - 所有斜杠命令的完整文档
- [技能系统](skills/README.md) - 自动触发技能的工作原理

## 总结

Claude Code Toolkit 的 6 种项目变体覆盖了主流的软件开发技术栈，每种变体都提供了开箱即用的完整工作环境。通过统一的代理团队、命令集和 MCP 权限配置，团队可以在不同项目间保持一致的开发体验，同时享受各技术栈特定工具链带来的效率提升。资料来源：[README.md:1-60]()

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：dagonet/claude-code-toolkit

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1163854955 | https://github.com/dagonet/claude-code-toolkit | host_targets=claude, claude_code

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

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1163854955 | https://github.com/dagonet/claude-code-toolkit | README/documentation is current enough for a first validation pass.

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

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1163854955 | https://github.com/dagonet/claude-code-toolkit | last_activity_observed missing

## 4. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1163854955 | https://github.com/dagonet/claude-code-toolkit | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1163854955 | https://github.com/dagonet/claude-code-toolkit | no_demo; severity=medium

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1163854955 | https://github.com/dagonet/claude-code-toolkit | issue_or_pr_quality=unknown

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

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1163854955 | https://github.com/dagonet/claude-code-toolkit | release_recency=unknown

<!-- canonical_name: dagonet/claude-code-toolkit; human_manual_source: deepwiki_human_wiki -->