1. 项目定位与目标

claude-code-toolkit 是一个面向 Claude Code 的可复用配置与代理工具集合，目标是为开发者提供"开箱即用"的 Agent、命令钩子（hooks）与文档模板，从而缩短在新项目中启用 Claude Code 协作的时间。仓库以脚本化安装为核心交付方式，配套维护说明性文档。资料来源：README.md

项目的整体定位决定了它具有以下特征：

• 配置驱动：所有能力通过 .claude/ 目录下的 Markdown 配置文件注入，便于版本控制与审阅。
• 脚本化安装：提供 setup-project.sh 一键脚本，自动化完成目录创建与文件拷贝。
• 文档同步：每个核心能力均配套独立 Markdown 文档（getting-started.md、setup.md、verification.md），保证文档与代码同源。
• 多 Agent 协作：通过 AGENTS.md 描述多个领域专属 Agent 的职责分工。

资料来源：AGENTS.md、docs/setup.md

2. 核心组件一览

下表概括了仓库主要交付物及其作用，便于读者快速建立心智模型。

资料来源：README.md、docs/setup.md、docs/verification.md

3. 快速入门流程

标准化的快速入门遵循"克隆 → 配置 → 安装 → 验证"四步：

1. 克隆仓库：将 claude-code-toolkit 拉取到本地工作区。
2. 阅读入口文档：优先阅读 README.md 与 docs/getting-started.md，了解可用 Agent 与命令。
3. 执行安装脚本：运行 setup-project.sh，将模板文件注入目标项目目录。
4. 执行验证：参照 docs/verification.md 中的检查清单确认配置生效。

资料来源：docs/getting-started.md、setup-project.sh

setup-project.sh 通常会完成以下动作：

• 创建目标项目中的 .claude/ 配置目录；
• 拷贝 AGENTS.md 及相关 Markdown 模板；
• 输出安装摘要，便于在终端确认执行结果。

资料来源：setup-project.sh、docs/setup.md

4. 验证与最佳实践

完成安装后，应通过 docs/verification.md 中描述的方式核对关键文件是否就位、Agent 是否能在 Claude Code 中被正确调用。常见的验证项包括：

• .claude/ 目录结构是否符合预期；
• AGENTS.md 中声明的 Agent 能否被识别；
• 钩子或命令在典型交互中是否触发。

资料来源：docs/verification.md

最佳实践方面，建议：

• 将 .claude/ 纳入版本控制，使团队成员共享同一套 Agent 定义。
• 在变更 Agent 配置后重新执行验证，避免配置漂移。
• 遵循文档分层结构：README.md 负责导航，docs/ 子目录负责细节，按需查阅。

资料来源：README.md、docs/getting-started.md、docs/verification.md

系统定位与设计目标

claude-code-toolkit 的"模板变体与项目脚手架"模块为不同技术栈的项目提供即用型 CLAUDE.md 配置文件，使 Claude Code 在打开新仓库时能够立刻加载符合该语言/框架约定的协作规则。该模块既面向新项目的引导（scaffolding），也负责在多模板之间保持一致的元信息与同步机制，避免不同变体随时间漂移。资料来源：docs/templates.md:1-40。

模块的设计目标是：

• 提供按语言/框架分类的最小可用 CLAUDE.md 模板集合。
• 通过同步命令将模板复制到用户级或仓库级目标位置。
• 通过自动化校验脚本持续保证各变体与权威源保持一致。

模板变体结构

模板以目录形式组织在 templates/ 下，每个子目录代表一个变体，对应一种项目类型：

每个变体目录下都有一个 CLAUDE.md 文件作为脚手架的入口内容，分别承载通用与 .NET 专用的协作指引。资料来源：templates/general/CLAUDE.md:1-40、资料来源：templates/dotnet/CLAUDE.md:1-40。

模板同步机制

docs/template-sync.md 描述了模板同步流程，用于将仓库内维护的权威模板分发到使用者的本地环境或目标项目中。其核心思路是：以仓库内的 templates/ 为单一权威源（single source of truth），通过同步脚本把所选变体落到用户级目录（如 ~/.claude）或仓库级位置，从而保证"仓库源 → 本地副本"的方向不会出现双向漂移。资料来源：docs/template-sync.md:1-60。

flowchart LR
    A[templates/ 权威源] --> B[模板同步脚本]
    B --> C[用户级 ~/.claude]
    B --> D[仓库级 .claude/]
    C --> E[Claude Code 运行时]
    D --> E

一致性与漂移校验

模块提供两个互补的校验脚本，用于在不同维度上捕捉漂移：

• scripts/verify-template-consistency.sh：检查 templates/ 下各变体之间的结构一致性，例如必备文件、CLAUDE.md 的必需段落是否齐备。资料来源：scripts/verify-template-consistency.sh:1-40。
• scripts/verify-user-level-drift.sh：检查用户级副本与仓库权威源之间的差异，识别本地被手工修改、长期未同步的副本。资料来源：scripts/verify-user-level-drift.sh:1-40。

这两个脚本共同构成"变体内部一致 + 副本与源一致"的双重保障，确保脚手架在长期演进中不会因局部修改而失同步。

脚手架使用流程

对新项目接入 claude-code-toolkit 模板的典型步骤为：

1. 在 templates/ 下选择最贴近目标技术栈的变体（如 .NET 项目选择 templates/dotnet/）。资料来源：templates/dotnet/CLAUDE.md:1-20。
2. 通过模板同步流程将该变体的 CLAUDE.md 复制到目标位置（用户级或仓库级）。资料来源：docs/template-sync.md:1-60。
3. 根据项目实际情况对同步后的内容进行有限裁剪，而非自由改动；若需要长期偏离，应在仓库中新建/调整变体以保留权威源。资料来源：docs/templates.md:1-40。
4. 在 CI 或本地使用 verify-template-consistency.sh 与 verify-user-level-drift.sh 进行回归检查，及时发现漂移。资料来源：scripts/verify-template-consistency.sh:1-40、资料来源：scripts/verify-user-level-drift.sh:1-40。

小结

"模板变体与项目脚手架"模块通过"权威源 + 同步 + 校验"三层结构，把分散在不同项目中的 CLAUDE.md 配置文件收敛为可治理、可验证的资产集合：变体目录承担多技术栈适配，模板同步承担分发，一致性与漂移脚本承担守门，从而支撑 Claude Code 在新仓库中以最小配置成本获得上下文感知的协作行为。

系统定位与总体架构

claude-code-toolkit 的 user-level-reference 目录为用户提供了一套"可插拔的运行时扩展层"，由三类核心机制构成：子代理（Sub-agents）、斜杠命令（Slash Commands） 与 技能（Skills）。它们共同作用在 Claude Code 的会话上下文之上，分别承担"专业角色"、"显式指令触发"与"可复用知识包"三种职责。

顶层入口文档 user-level-reference/README.md 描述了这些机制的目录布局与加载优先级；user-level-reference/CLAUDE.md 则是面向 Claude 的根级上下文文件，充当"项目记忆"，被所有会话与子代理自动加载。user-level-reference/settings-reference.md 进一步说明了这些扩展如何在 settings.json 中注册与启用 资料来源：user-level-reference/README.md。

graph TD
    A[CLAUDE.md 项目记忆] --> B[Claude Code 会话]
    C[settings.json] --> B
    B --> D{触发方式}
    D -->|@提及| E[子代理 Agents]
    D -->|/命令| F[斜杠命令 Commands]
    D -->|自动加载| G[技能 Skills]
    E --> H[architect]
    E --> I[code-reviewer]
    E --> J[coder]

子代理（Sub-agents）：专业角色封装

子代理是具备独立系统提示词、工具权限与任务边界的"专家实例"。每个代理对应 user-level-reference/agents/ 目录下的一个 Markdown 文件，文件名即代理标识符。

• architect.md：架构师角色，专注于系统设计、模块边界划分与技术选型评估。它倾向于在动手编码前先输出结构化方案，避免过早陷入实现细节 资料来源：user-level-reference/agents/architect.md。
• code-reviewer.md：代码审查角色，负责对现有改动进行质量、安全、可维护性评审，并产出可执行的整改建议 资料来源：user-level-reference/agents/code-reviewer.md。
• coder.md：实现工程师角色，承担具体功能的编写、重构与调试任务，强调最小改动与可验证交付 资料来源：user-level-reference/agents/coder.md。

通过在会话中 @architect、@coder 等提及方式，主代理可将子任务委派给相应子代理，从而复用其专用指令集。settings-reference.md 中定义了这些代理的启用规则、可用工具白名单以及上下文继承策略 资料来源：user-level-reference/settings-reference.md。

斜杠命令（Slash Commands）：显式用户指令

斜杠命令是用户主动触发的快捷指令，形式如 /review、/plan、/test。它们在 settings-reference.md 中以 commands 节点进行配置，可绑定到具体的 Markdown 提示词模板，从而在调用时展开为完整指令注入会话 资料来源：user-level-reference/settings-reference.md。

与子代理的"角色化"不同，斜杠命令更强调"一次性动作"：例如调用一次代码审查流程、生成一份特定格式的文档骨架。README.md 指出，命令的解析优先级高于普通文本，因此适合用于需要确定性行为的场景 资料来源：user-level-reference/README.md。

技能（Skills）：可复用知识包

技能是一类按需加载的结构化知识片段，通常以 Markdown 或配套脚本的形式存放在 user-level-reference/ 下的子目录中。它们不同于子代理的"持续性角色"，也不同于命令的"瞬时触发"，而是提供"何时使用何种方法"的领域知识。

技能由 CLAUDE.md 中的元数据声明，并通过会话上下文或特定命令按需引用。README.md 强调技能应当保持单一职责，便于跨项目复用 资料来源：user-level-reference/README.mduser-level-reference/CLAUDE.md。

三者的协同关系

CLAUDE.md 作为统一锚点，被所有三类机制共享读取；settings-reference.md 则统一管理它们的注册、权限与解析顺序 资料来源：user-level-reference/CLAUDE.mduser-level-reference/settings-reference.md。这种"角色 + 动作 + 知识"的三元结构，使扩展层既能灵活适配不同工作流，又保持配置的可追溯性。

目的与范围

claude-code-toolkit 是一套围绕 Claude Code 的工程化工具集，专注于在用户级别提供可复用、可治理的开发辅助能力，其核心议题分为三类：基于 Hook 的工作流强制、MCP（Model Context Protocol）服务器集成以及整体参考架构。

参考架构文档 docs/architecture.md 描述了工具集在用户级别（~/.claude）与仓库级别（.claude/）之间的分层关系、配置文件加载顺序以及运行时事件流。资料来源：docs/architecture.md:1-40

工作流强制层负责拦截并审计 Claude Code 触发的工具调用，目标是减少误用 git、绕开测试或绕过 lint 等反模式。资料来源：docs/hook-enforcement-ideas.md:1-30

MCP 集成层通过声明式的 JSON 配置向 Claude Code 暴露外部工具与数据源，使模型可以在不修改宿主的前提下动态获得新能力。资料来源：mcp-servers/HOWTO.md:1-25

系统架构

工具集采用「配置 + 钩子 + 外部服务」的三段式结构：配置文件统一托管于 ~/.claude，钩子脚本驻留在 hooks/，外部能力通过 mcp-servers/ 下的 MCP 服务器暴露。

flowchart LR
    A[Claude Code 主机] --> B[加载配置<br/>settings.json / .mcp.json]
    B --> C[工具调用事件]
    C --> D{Hook 拦截层}
    D -->|允许| E[执行工具]
    D -->|拒绝| F[阻断并写审计]
    E --> G[MCP 服务器]
    G --> H[外部工具与数据]
    F --> I[workflow-audit 日志]

主机在每次工具调用前向已注册的 Hook 派发 JSON 事件，Hook 通过退出码表达「允许 / 拒绝」；MCP 服务器作为独立子进程通过 stdio 交换 JSON-RPC 消息，实现了能力扩展与宿主进程之间的解耦。资料来源：docs/architecture.md:10-60、hooks/block-bash-vcs.sh:1-20

工作流强制（Hooks）

hooks/block-bash-vcs.sh 是最典型的强制示例：它在 PreToolUse 阶段解析 Claude Code 传入的 JSON 事件，识别 Bash 工具调用中的 git 子命令（如 git commit、git push），一旦命中预设模式即返回非零退出码，使调用被主机拒绝。资料来源：hooks/block-bash-vcs.sh:1-40

docs/hook-enforcement-ideas.md 列出了若干扩展方向：限制特定目录的写入、强制单元测试前置、要求提交信息遵循 Conventional Commits 规范，以及对危险命令（rm -rf、curl | bash）做白名单匹配。资料来源：docs/hook-enforcement-ideas.md:20-80

所有拦截结果统一汇入审计通道。docs/workflow-audit.md 定义了审计日志格式（包含时间戳、工具名、被拒原因与重试次数）以及定期归档策略，便于事后追溯与合规检查。资料来源：docs/workflow-audit.md:1-50

MCP 集成与配置

mcp-servers/HOWTO.md 给出添加 MCP 服务器的标准流程：先在 mcp-servers/<name>/ 下放置服务器实现，再将其注册到用户级配置。资料来源：mcp-servers/HOWTO.md:1-30

user-level-reference/.mcp.json.template 是一份可直接复用的配置模板，核心字段包括 mcpServers（命名服务器集合）、command（启动可执行文件）、args（参数列表）、env（注入到子进程的环境变量）以及 disabled（临时停用某服务器）。资料来源：user-level-reference/.mcp.json.template:1-25

由于每个 MCP 服务器以独立子进程方式运行，与 Claude Code 主机通过 stdio 交换 JSON-RPC 消息，因此任何实现了 MCP 协议的程序（Node、Python、Go）都可以作为工具来源被即插即用。资料来源：docs/architecture.md:40-70

审计与协作

审计模块 docs/workflow-audit.md 不仅记录失败事件，也记录成功通过 Hook 校验的调用摘要，用于统计执行频次与发现异常模式。建议结合 git 的 pre-receive 钩子，在服务端再做一次策略复核，从而实现「客户端 Hook + 服务端策略」的双层防护。资料来源：docs/workflow-audit.md:30-70、docs/hook-enforcement-ideas.md:60-90

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 | https://github.com/dagonet/claude-code-toolkit | host_targets=claude_code, claude, mcp_host, cursor

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/dagonet/claude-code-toolkit | README/documentation is current enough for a first validation pass.

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/dagonet/claude-code-toolkit | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/dagonet/claude-code-toolkit | no_demo; severity=medium

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/dagonet/claude-code-toolkit | issue_or_pr_quality=unknown

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

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