概述

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

核心价值：

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

资料来源：README.md:1-20

概述

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

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

./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 支持六种模板变体，覆盖了主流的编程语言和框架：

系统架构

模板变体系统的核心组件

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

变体定制化层级

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 生态系统设计，包含以下特定功能：

.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 桌面应用框架提供支持：

该变体包含 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 团队配置

斜杠命令集

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

自动触发技能

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

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

MCP 权限配置

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

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

工作流强制钩子

使用流程

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[项目初始化完成]

变体选择指南

相关资源

• 详细文档：docs/templates.md
• 入门指南：docs/getting-started.md
• 仓库地址：github.com/dagonet/claude-code-toolkit

概述

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 矩阵

资料来源：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 工作流程

标准开发流程

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 配置位于对应的目录中：

资料来源：README.md:1-15

Agent 定义文件格式

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

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

Agent 协作机制

状态管理

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

上下文共享

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

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

工具调用

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

与 Slash Commands 的集成

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

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 映射

资料来源：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 负责，确保开发过程既高效又保持高质量标准。该系统的高度可配置性使其能够适应不同的技术栈和项目需求。

概述

斜杠命令系统（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

系统架构

整体架构图

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

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 条命令可分为以下六个主要类别：

开发命令

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

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

架构命令

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

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

代码质量命令

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

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

需求工程命令

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

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

协作命令

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

资料来源：user-level-reference/README.md:48

维护命令

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

资料来源：user-level-reference/README.md:49

命令工作流模式

通用工作流结构

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

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 定义文件包含以下标准章节：

# /command-name - 功能描述

简短的功能说明段落。

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

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

## Rules
- 规则一
- 规则二

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

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

核心命令详解

/build - 项目构建

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

参数说明

工作流程

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

/test - 测试执行

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

参数说明

工作流程

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

/commit - 变更提交

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

工作流程

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

/sprint - 冲刺执行

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

参数说明

工作流程

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

/arch-doc - 架构文档生成

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

参数说明

工作流程

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 命令按照正确的架构模式为项目搭建新功能的基础结构。

参数说明

工作流程

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 命令评估和量化代码库中的技术债务。

参数说明

分析维度

债务评分标准

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

/api-design - API 设计审查

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

工作模式

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

审查检查项

资料来源：user-level-reference/commands/api-design.md

/traceability - 需求追踪

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

参数说明

追溯矩阵结构

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

/user-story - 用户故事生成

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

参数说明

生成格式

## Feature: [功能名称]

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

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

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

INVEST 标准

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

Agent 集成

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

Agent 角色映射

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

Agent 工作流

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 包含以下工作流强制机制：

资料来源：README.md:20

MCP 工具集成

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

资料来源：README.md:22

最佳实践

命令使用建议

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

组合使用示例

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 环境中直接执行复杂的开发任务，减少上下文切换，提高开发效率。

概述

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

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

系统架构

组件关系

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

技能分类与功能

核心技能列表

资料来源：README.md

自动触发机制

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

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

技能定义规范

SKILL.md 文件格式

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

代码审查技能示例

# 代码审查技能

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

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

资料来源：user-level-reference/skills/code-review/SKILL.md

错误修复技能示例

# 错误修复技能

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

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

资料来源：user-level-reference/skills/fix-errors/SKILL.md

技能评估与验证

skill-eval 命令

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

#### 命令参数

资料来源：user-level-reference/commands/skill-eval.md

#### 评估流程

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

评估维度

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

技能系统集成

与命令系统的集成

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

与智能体团队的协作

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
• 命令系统参考：/skill-eval 命令
• 技能目录：user-level-reference/skills

概述

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

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

资料来源：user-level-reference/README.md:30

核心设计理念

权限注册机制

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

资料来源：user-level-reference/README.md:33

工具优先策略

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

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 权限配置：

资料来源：user-level-reference/README.md:33

MCP 配置模板

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

配置结构

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

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

配置作用域

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

资料来源：user-level-reference/.mcp.json.template

工作流集成

命令执行流程

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

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：

资料来源：user-level-reference/README.md:33

工具使用规范

调用约定

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

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

错误处理

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

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

多语言支持

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

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

扩展 MCP 配置

添加新工具

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

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

配置示例

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

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

安全考量

权限隔离

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

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

凭证管理

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

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

总结

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

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

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

概述

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

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

架构设计

钩子组织结构

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

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 工具替代。

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

关键检测模式：

来源： hooks/block-bash-vcs.sh

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

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

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

保护策略：

来源： hooks/no-push-main.sh

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

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

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

语言特定测试命令：

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

来源： hooks/pre-commit-test.sh

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

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

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

配置参数：

来源： hooks/read-size-gate.sh

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

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

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

阶段依赖关系：

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

检查内容：

来源： hooks/tier-before-coder.sh

钩子配置与管理

安装钩子

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

# 使用项目提供的安装脚本
./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 选项来绕过钩子，但应谨慎使用：

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

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

钩子禁用

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

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

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

强制执行理念

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

最佳实践

开发团队指南

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

CI/CD 集成

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

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

故障排查

常见问题

调试钩子

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

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

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

相关资源

• 钩子强制执行理念文档
• Git 钩子官方文档
• Claude Code Toolkit 主 README

概述

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

资料来源：README.md:1-30

模板变体体系

支持的变体类型

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

资料来源：README.md:1-30

变体架构

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 角色，形成完整的开发闭环：

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

自定义 Agent 行为

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

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

命令扩展

现有命令概览

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

开发类命令

架构类命令

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

新功能脚手架工作流

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

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 个自动触发技能，它们会根据上下文自动加载：

资料来源：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 技能允许用户将上游模板更新同步到已存在的项目中，避免重复配置：

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[报告变更摘要]

同步策略

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

上游贡献

contribute-upstream 技能

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

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

贡献工作流规范

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

MCP 集成扩展

预配置 MCP 权限

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

资料来源：README.md:1-30

扩展 MCP 配置

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

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

工作流钩子

提交前钩子

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

资料来源：README.md:1-30

快速开始

1. 安装依赖

# 基础依赖
git
Node.js 18+

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

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

2. 创建项目

# 克隆工具包
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. 验证安装

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

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

最佳实践

定制建议

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

扩展检查清单

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

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

概述

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

资料来源：README.md:1-15

整体架构

架构设计原则

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

核心组件层次

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 种模板变体，每种针对特定技术栈优化：

资料来源：README.md:19-26

模板结构

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

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

智能体团队架构

智能体矩阵

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

智能体协作流程

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 个斜杠命令，分为以下类别：

#### 开发命令

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

#### 架构命令

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

架构文档生成流程

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

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 模式：

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 权限，按作用域注册而非按项目注册：

资料来源：README.md:36-38

工作流执行钩子

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

资料来源：README.md:39-40

技能系统

自动触发技能

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

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

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

架构分析工具

技术债务评估

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

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

依赖审计

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

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

部署架构

快速启动流程

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

环境要求

资料来源：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 集成确保工具链一致性，工作流钩子保证代码质量标准得到执行。这套架构使得团队能够快速建立标准化的开发工作流，同时保持足够的灵活性以适应不同技术栈的需求。

概述

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

项目变体总览

资料来源：README.md:18-25

架构设计

变体继承关系

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

工作流集成

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

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

General 变体

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

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

项目创建工作流

命令行接口

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

参数说明：

资料来源：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

自动触发技能

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

相关资源

• 入门指南 - 详细的安装和配置说明
• Agent 团队文档 - 各代理角色职责说明
• 命令参考 - 所有斜杠命令的完整文档
• 技能系统 - 自动触发技能的工作原理

总结

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

Pitfall Log / 踩坑日志

项目：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