claudekit

为 Claude Code 提供智能护栏和工作流自动化——实时捕获错误、保存检查点，并通过专家子代理增强 AI 编码能力

🚀 安装

⚠️ 需要： Claude Code Max 方案（以实现最佳 token 使用）• Node.js 20+

npm install -g claudekit
# 或：yarn global add claudekit
# 或：pnpm add -g claudekit

⚡ 快速入门

# 在您的项目中初始化
claudekit setup

# 在 Claude Code 中，尝试以下命令：
/git:status                      # 按类型分组更改并建议提交策略
/spec:create "您的下一个功能" # 研究代码库并编写完整规范
/code-review                     # 6 个专业代理并行分析代码

🎯 它的作用

Claudekit 在您使用 Claude 进行编码时充当您的安全网：

之前：Claude 添加 'any' 类型 → ❌ 在代码审查中发现丢失了类型安全性  
之后：Claude 添加 'any' 类型 → ✅ 即时阻止：“请使用具体类型：User | null”

之前：危险的重构失败 → ❌ 需要进行 Git 考古来寻找可用版本  
之后：危险的重构失败 → ✅ 一条命令：/checkpoint:restore

之前：Claude 导致测试失败 → ❌ 您是在 Claude 完成后才发现的  
之后：Claude 导致测试失败 → ✅ Claude 立即看到错误并修复它

之前：让 Claude 进行代码审查 → ❌ 浅层分析、通用反馈、顺序执行  
之后：使用 /code-review → ✅ 6 个专业代理并行分析，动态调用特定于技术领域的专业知识

核心功能

🗺️ 即时代码库导航

Claude 会自动查看您的整个项目结构——省去了大部分查找步骤。

• 直接跳转到代码：直接定位到文件、函数和类
• 无需反复试错：避免翻阅测试文件、文档和其他无关内容
• 自信地访问代码：Claude 清楚地知道哪些内容存在以及它们的位置
• 查看关系：Claude 瞬间理解依赖关系和架构
• 自动设置：首次提示时隐形运行，并随您的编码更新

代码库地图指南 →

🔍 全面代码审查

• 多方面分析：6 个并行代理分别负责架构、安全、性能、测试、质量和文档
• 智能定位：根据文件类型和范围自动选择相关审查代理
• 结构化报告：按优先级列出问题（严重/高/中），附带类型图标和可操作的解决方案
• 质量指标：评分系统及问题分布跟踪，便于衡量改进效果

🚀 迭代式规范实施

• 6 阶段工作流程：实现 → 编写测试 → 代码审查 → 迭代改进 → 提交 → 进度跟踪
• 动态代理选择：实时检测可用的专业代理，并自动回退至备用方案
• 质量关卡：每个阶段都会进行验证，确保高质量交付
• 原子提交：标准化提交信息，包含全面的变更说明

规范工作流程指南 →

🛡️ 实时错误预防

• 🔒 高级 Bash 安全分析：全面防护敏感文件通过 Shell 命令被访问
  • 智能命令解析：分析复杂的 Bash 管道、变量赋值和 Shell 结构
  • 模式检测：识别通过 xargs、find、管道和命令替换等方式访问敏感文件的行为
  • 路径提取：安全处理 curl 和 httpie 上传中的通配符、变量和 @file 引用
  • 安全启发式：在执行前检测到类似 find -name '*.env' | xargs cat 的危险模式
• 🔒 增强的敏感文件保护：涵盖云凭证、加密货币、数据库、令牌和生产数据等 12 个类别，共 195+ 种模式
• 多类别保护：环境文件、SSH 密钥、云服务商凭证（AWS/Azure/GCP）、包管理器认证、加密钱包、生产数据库
• TypeScript 防护：在 Claude 编辑时阻止 any 类型和类型错误
• 代码风格检查：立即捕捉样式问题
• 反模式检测：防止代码被注释覆盖
• 测试运行器：在文件更改时运行相关测试
• 多工具忽略文件支持：尊重 .agentignore、.aiignore、.aiexclude、.geminiignore、.codeiumignore 和 .cursorignore

💾 Git 检查点系统

• 自动保存：当 Claude 停止时创建检查点
• 轻松恢复：使用 /checkpoint:restore 撤销更改
• 检查点管理：列出、恢复或清理检查点

检查点指南 →

🤖 AI 子代理

• 研究专家：research-expert 可进行综合并行研究，时间缩短 90%，自动分析来源并生成结构化报告
• 代码搜索：code-search 可快速并行搜索代码库，速度提升 3–10 倍
• 分诊专家：triage-expert 用于初步诊断问题并将其分配给专业人员
• 领域专家：TypeScript、React、数据库、测试、基础设施和文档方面的专家
• 代码审查：专门的 code-review-expert 代理，从 6 个方面进行专注分析
• 框架专家：Next.js、Nest.js、AI SDK 和构建工具方面的专家
• 性能优化：通过 disableHooks 配置智能管理钩子，在专业操作期间跳过不必要的验证
• 强制委托：所有技术问题必须由专业子代理处理
• 主动帮助：运行 /agents-md:init 更新 AGENTS.md/CLAUDE.md，以实现子代理的自动委派

📊 挂钩性能剖析

• 性能监控：使用 claudekit-hooks profile 分析挂钩执行时间和输出大小
• 批量分析：自动剖析 .claude/settings.json 中配置的所有挂钩
• 统计分析：支持多次迭代并取平均值以获得准确的测量结果
• 智能警告：对耗时超过 5 秒的慢速挂钩和超出输出大小限制的情况进行颜色编码提醒
• Claude Code 集成：为注入上下文的 UserPromptSubmit 挂钩设置专用限制
• Token 估算：计算挂钩输出的预估 Token 使用量

挂钩剖析指南 →

🧠 增强型 AI 推理

• 自动增强：thinking-level 挂钩可在无需手动提示工程的情况下，隐形地提升 Claude 的推理能力
• 4 种可配置级别：从禁用（0）到最大推理能力（3），并提供智能默认值
• 隐形运行：关键词会在用户不知情的情况下悄然注入
• 轻量级：开销小于 5 毫秒，且 Token 使用量极低
• 会话感知：在首次用户提示时激活，从而在整个会话中持续增强 AI 推理能力

思考层级指南 →

🎛️ 基于会话的挂钩控制

• 临时控制：可为单个 Claude Code 会话禁用或启用挂钩
• 会话隔离：更改仅影响当前会话，不会波及其他开发者
• 智能状态管理：采用 4 状态系统（已启用/已禁用/未配置/未找到）
• 模糊匹配：支持部分挂钩名称，并提供智能建议
• 无永久性更改：不会修改任何配置文件

会话挂钩控制指南 →

🔬 多智能体研究系统

• 并行信息收集：同时启动 5–10 个研究智能体，使调查速度提升 90%
• 智能查询分类：自动确定研究策略（广度优先、深度优先或简单事实查询）
• 全面的来源分析：跨多个领域交叉核对研究结果，并自动管理引用
• 结构化研究报告：包括执行摘要、关键发现、详细分析及方法论文档
• 文件系统产物：子智能体将完整报告写入 /tmp/research_*.md，以便高效整合和优化 Token 使用

📝 智能命令

• /research [query] - 使用专业子智能体进行深度并行研究，并生成结构化报告
• /code-review - 使用 6 个并行智能体进行多维度代码审查
• /git:commit - 按照项目规范创建提交
• /git:checkout - 智能创建分支并切换，命名符合常规
• /git:ignore-init - 初始化 AI 安全的 .gitignore 模板，保护敏感文件
• /validate-and-fix - 运行所有质量检查并修复问题
• /spec:create - 生成全面的规格说明书
• /spec:execute - 按照迭代式质量保证流程实施规格说明书
• /create-subagent - 构建自定义 AI 助手
• /hook:disable [hook-name] - 临时禁用当前会话中的挂钩
• /hook:enable [hook-name] - 重新启用当前会话中已禁用的挂钩
• /hook:status [hook-name] - 显示挂钩状态（已启用/已禁用/未配置）

CLI 命令

claudekit setup              # 交互式设置向导
claudekit setup --yes        # 使用默认设置快速安装
claudekit setup --all        # 安装所有组件（所有智能体）
claudekit setup --user       # 安装到用户目录 (~/.claude)，而非项目目录
claudekit list               # 显示所有组件（挂钩、命令、智能体、配置）
claudekit list agents        # 列出可用智能体及其 Token 数量
claudekit list commands      # 列出可用命令及其 Token 数量
claudekit show agent <id>    # 展示智能体提示，供外部使用
claudekit show command <id>  # 展示命令提示，供外部使用
claudekit show agent <id> -f json    # 将智能体元数据和内容以 JSON 格式输出
claudekit show command <id> -f json  # 将命令元数据和内容以 JSON 格式输出
claudekit doctor             # 检查您的安装情况，并验证文档链接是否有效

# 工具状态检查
claudekit status stm         # 检查 Simple Task Master (STM) 的安装和初始化状态

# 代码检查与验证
claudekit lint-commands      # 检查斜杠命令的 Markdown 文件
claudekit lint-agents        # 检查智能体 Markdown 文件（原名 lint-subagents）

# 挂钩管理和剖析
claudekit-hooks run <hook>   # 手动执行特定挂钩
claudekit-hooks profile      # 剖析所有已配置挂钩的性能
claudekit-hooks profile <hook> --iterations 5  # 对特定挂钩进行剖析，并取平均值

# 基于会话的挂钩控制（在 Claude Code 会话中）
claudekit-hooks disable <hook>  # 禁用当前会话中的挂钩
claudekit-hooks enable <hook>   # 重新启用当前会话中的挂钩  
claudekit-hooks status <hook>   # 显示挂钩状态（已启用/已禁用）

与外部 LLM 结合使用提示

show 命令可提取智能体和命令的提示，用于 Claude Code 的非交互模式以及其他 AI 编程工具：

# 提取智能体提示，用于 Claude Code CLI
EXPERT=$(claudekit show agent typescript-expert)
cat src/app.ts | claude -p --append-system-prompt "$EXPERT" "Review this code"

# 获取结构化元数据，便于与其他工具集成
claudekit show agent typescript-expert --format json | jq '.description'

# 可与任何 AI 编程 CLI 工具配合使用
claudekit show agent react-expert | amp -x "Fix React hooks violations"

更多关于 Claude Code、Amp、Gemini CLI 等工具的示例，请参阅 与外部 LLM 结合使用提示指南。

斜杠命令

您可以在 Claude Code 中直接使用以下命令：

Git 与检查点

• /checkpoint:create [msg] - 保存当前状态
• /checkpoint:restore [n] - 恢复到指定检查点
• /checkpoint:list - 查看所有检查点
• /git:commit - 智能提交，遵循规范
• /git:status - 智能 Git 分析
• /git:checkout [branch] - 智能创建分支并切换，命名符合常规
• /git:ignore-init - 初始化 AI 安全的 .gitignore 模板

代码质量

• /code-review [target] - 使用并行智能体进行多维度代码审查
• /validate-and-fix - 运行所有质量检查

开发工具

• /research [query] - 使用专业子智能体进行深度并行研究
• /spec:create [feature] - 生成功能规格说明书
• /spec:execute [file] - 按照 6 阶段迭代流程实施规格说明书
• /agents-md:init - 配置 AI 助手
• /create-subagent - 构建自定义智能体
• /create-command - 创建自定义命令

查看所有命令 →

挂钩

挂钩会在 Claude 工作时自动强制执行质量标准：

可用钩子

文件安全钩子（PreToolUse - 在文件访问前执行）

• file-guard - 使用忽略文件模式阻止 AI 访问敏感文件（.env、密钥、凭据）

文件变更钩子（PostToolUse - 在编辑后执行）

• typecheck-changed - 对文件变更运行 TypeScript 类型检查
• lint-changed - 对已更改文件运行代码风格检查（Biome、ESLint 等）
• test-changed - 为已更改文件运行测试
• check-any-changed - 禁止已更改的 TypeScript 文件中出现任何类型
• check-comment-replacement - 检测代码是否被注释替换
• check-unused-parameters - 检测懒惰重构：参数被添加下划线前缀而非直接移除

用户提示提交钩子（在每个会话的首次用户提示时执行）

• codebase-map - 使用 codebase-map CLI 每会话提供一次不可见的代码库上下文
• thinking-level - 注入思考层级关键词以增强 Claude 的推理能力

PostToolUse 钩子（也包括文件监控）

• codebase-map-update - 当文件发生变更时增量更新代码库地图

项目级钩子（通常用于 Stop/SubagentStop 事件）

• typecheck-project - 对整个项目进行 TypeScript 验证
• lint-project - 对整个项目进行代码风格检查（Biome、ESLint 等）
• test-project - 运行完整的测试套件
• create-checkpoint - 在停止时自动创建 Git 检查点
• check-todos - 验证待办事项是否已完成
• self-review - 增强的目标性自审，可检测实现完整性，优先关注模拟实现、占位符代码和未完成的功能，而非代码质量问题

自审指南 →

钩子事件

• PreToolUse - 在文件访问（读取、写入、编辑、多文件编辑）之前触发，用于权限控制
• PostToolUse - 在文件修改（写入、编辑、多文件编辑）之后触发
• Stop - 当 Claude Code 停止或对话结束时触发
• SubagentStop - 当子代理完成任务时触发
• UserPromptSubmit - 当用户在会话中提交第一条提示时触发

钩子命令

# 查看所有可用钩子及其描述
claudekit-hooks list

# 分析钩子性能和输出大小
claudekit-hooks profile                   # 分析所有钩子
claudekit-hooks profile typecheck-changed  # 分析特定钩子
claudekit-hooks profile --iterations 5    # 多次运行以获取平均值

# 会话级别的钩子控制（需要活跃的 Claude Code 会话）
claudekit-hooks disable typecheck-changed  # 禁用当前会话中的特定钩子
claudekit-hooks enable typecheck          # 重新启用钩子（支持部分匹配）
claudekit-hooks status                     # 显示所有钩子的状态
claudekit-hooks status lint                # 显示特定钩子的状态

profile 命令有助于识别：

• 执行缓慢的钩子（>5秒），会拖慢工作流程
• 输出量大的钩子，会占用大量上下文窗口
• 接近 10k 字符限制的 UserPromptSubmit 钩子

通过会话级别的钩子控制，您可以在不修改配置文件的情况下，临时禁用特定 Claude Code 会话中的钩子。功能包括：

• 钩子名称的模糊匹配（支持部分匹配）
• 可视化状态指示器（🔒 已禁用，✅ 已启用）
• 会话隔离状态（更改仅影响当前会话）
• 自动通过会话记录 UUID 检测会话

钩子配置 → | 性能分析指南 →

子代理

针对不同领域的专业 AI 助手：

热门代理

• code-review-expert - 6 个并行代理进行代码评审（架构、安全、性能、测试、质量、文档）
• triage-expert - 收集上下文并诊断问题，然后将其分配给专业专家
• documentation-expert - 专注于文档结构、连贯性、流畅性和信息架构
• oracle - 深度调试和复杂问题分析（需单独设置）
• refactoring-expert - 检测代码异味并提供全面的重构指导
• typescript-expert - 专注于 TypeScript/JavaScript 开发和类型系统
• react-expert - 专注于 React 组件、Hooks 和性能优化
• testing-expert - 提供测试策略、覆盖率和最佳实践建议
• database-expert - 专注于查询优化和模式设计
• ai-sdk-expert - 专注于 Vercel AI SDK v5 流式传输和模型集成
• nestjs-expert - 专注于 Nest.js 架构和依赖注入
• kafka-expert - 专注于 Apache Kafka 生产者/消费者配置、主题管理、集群操作和性能调优
• loopback-expert - 专注于 LoopBack 4 框架开发、模型关系、认证和依赖注入

使用方法

# 列出所有可用代理及其令牌数量
claudekit list agents

# 安装特定代理
claudekit setup --agents typescript-expert,react-expert

安装完成后，代理会自动工作，也可以直接调用：

“请使用 oracle 代理来调试这个问题”
“让 typescript-expert 审核这个类型定义”

查看所有代理 →

安全

保护敏感文件

file-guard 钩子会自动保护敏感文件免受 AI 访问。快速设置方法如下：

# 新项目：安装带有 file-guard 保护的 claudekit
npm install -g claudekit && claudekit setup --yes --force --hooks file-guard

# 现有项目：将 file-guard 添加到现有设置中
claudekit setup --yes --force --hooks file-guard

或者手动创建 .agentignore 文件：

# .agentignore
.env
.env.*
*.key
*.pem
.aws/credentials
.ssh/*

# 允许示例文件
!.env.example

file-guard 钩子支持多种忽略文件格式（.agentignore、.aiignore、.cursorignore、.geminiignore、.codeiumignore、.aiexclude），并将所有这些格式中的模式合并在一起——这一独特功能可在团队使用任何 AI 工具时提供全面保护。

关键特性：

• 高级 Bash 命令分析：解析复杂的 Shell 命令以检测敏感文件访问模式
• 管道安全：检测如 find -name '*.env' | xargs cat 和 echo '.env' | xargs cat 等危险构造
• 变量扩展：安全处理 Bash 变量、命令替换和参数扩展
• 上传保护：阻止通过 curl、httpie、scp、rsync 以及云 CLI 工具（aws、gcloud、az）上传文件
• 合并所有忽略文件中的模式（不同于其他工具）
• 支持 gitignore 样式的语法，包括否定规则（!）
• 解析符号链接以防止绕过
• 阻止项目之外的路径遍历尝试

有关详细配置和最佳实践，请参阅 File Guard 指南。

配置

Claudekit 使用两个配置文件：

.claude/settings.json - 项目设置（钩子、命令）

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read|Edit|MultiEdit|Write",
      "hooks": [{"type": "command", "command": "claudekit-hooks run file-guard"}]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [{"type": "command", "command": "claudekit-hooks run typecheck-changed"}]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "claudekit-hooks run create-checkpoint"}]
    }],
    "SubagentStop": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "claudekit-hooks run create-checkpoint"}]
    }],
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "claudekit-hooks run codebase-map"}]
    }]
  }
}

.claudekit/config.json - 钩子配置

{
  "hooks": {
    "typecheck-changed": {
      "command": "npm run typecheck"
    },
    "thinking-level": {
      "level": 2
    },
    "codebase-map": {
      "include": ["src/**", "lib/**"],
      "exclude": ["**/*.test.ts", "**/*.spec.ts"],
      "format": "dsl"
    }
  }
}

配置指南 →

获取帮助

• 文档: 完整文档
• 问题: GitHub Issues
• 快速测试: 运行 claudekit doctor 检查设置

常见问题

钩子未触发？

claudekit doctor                # 检查配置
npm list -g claudekit           # 确认安装

测试超时？ 使用超快的测试配置来执行钩子：

{
  "hooks": {
    "test-project": {
      "command": "npm run test:fast",
      "timeout": 30000
    }
  }
}

或者配置一个自定义的更快测试命令：

{
  "hooks": {
    "test-project": {
      "command": "npm run test:unit",
      "timeout": 50000
    }
  }
}

代码库地图未生成？ 安装代码库地图 CLI 工具：

npm install -g codebase-map
# 检查安装：
codebase-map --version

完整故障排除 →

MCP 集成

部分命令支持可选的 MCP 服务器集成：

Context7（用于访问文档）

# 全局安装
npm install -g @upstash/context7-mcp

# 添加到 Claude Code
claude mcp add context7 context7-mcp

启用 /spec:create 功能，以获取最新的库文档。

开发

# 克隆并安装
git clone https://github.com/claudekit/claudekit.git
cd claudekit
npm install

# 构建
npm run build

# 测试
npm test

# 验证生产构建
npm run validate:build         # 检查依赖和构建产物
npm run validate:install       # 测试干净安装

# 创建开发用符号链接
npm run symlinks

贡献

我们欢迎贡献！请参阅 CONTRIBUTING.md 查看指南。

许可证

MIT © claudekit 贡献者

claudekit 快速上手指南

claudekit 是为 Claude Code 打造的智能护栏与工作流自动化工具。它能实时拦截错误、保存代码检查点，并通过专家级子代理（Subagents）增强 AI 编程能力。

环境准备

在开始之前，请确保满足以下系统要求：

• Claude Code 订阅：需要 Max plan（以优化 Token 使用并获得最佳体验）。
• Node.js 版本：需安装 Node.js 20 或更高版本。
  • 检查版本命令：node -v
• 包管理器：推荐使用 npm、yarn 或 pnpm。
  • 国内加速建议：如下载缓慢，可配置淘宝镜像源：

    npm config set registry https://registry.npmmirror.com
    

安装步骤

使用以下任一命令全局安装 claudekit：

# 使用 npm (推荐)
npm install -g claudekit

# 或使用 yarn
yarn global add claudekit

# 或使用 pnpm
pnpm add -g claudekit

安装完成后，在项目根目录运行初始化向导：

claudekit setup

提示：若希望使用默认配置快速完成设置，可运行 claudekit setup --yes。

基本使用

初始化后，直接在 Claude Code 会话中使用以下增强命令即可：

1. 智能代码审查

并行调用 6 个专用代理对代码进行多维度分析（架构、安全、性能等）：

/code-review

2. 需求规格生成

让 AI 研究现有代码库并撰写完整的功能规格说明书：

/spec:create "你的下一个功能描述"

3. Git 工作流增强

按类型分组变更并建议提交策略：

/git:status

4. 错误恢复与检查点

如果重构失败或出现意外，一键恢复到之前的安全状态：

/checkpoint:restore

核心特性速览

• 实时防护：自动阻止 TypeScript 中的 any 类型滥用，即时发现测试失败。
• 安全护栏：内置高级 Bash 安全分析，防止敏感文件（如 .env、SSH 密钥）被意外读取或泄露。
• 极速导航：自动构建代码库地图，让 Claude 直接定位文件与依赖，减少无效搜索。
• 多代理协作：内置研究专家、代码搜索专家及各类领域专家（React, DB, Next.js 等），自动分配复杂任务。