bkit-doctor
v1.1.1
Published
Diagnose, scaffold, and maintain Claude Code project structure
Maintainers
dotoricodeReadme
English · 한국어 · 日本語 · 中文 · Español
🚀 3秒快速开始
npx bkit-doctor setup就这样。一条命令扫描项目、修复问题，并将 Claude Code 接入自动文档化流程 — 永久生效。
bkit-doctor setup
[1/4] 🔍 智能检查 — 扫描缺失的 AI 配置文件...
✔ 找到 .claude/ 目录
✔ 找到 CLAUDE.md
⚠ hooks.json 缺失 → 将自动修复
[2/4] 🏗️ 交互式初始化 — 脚手架缺失的结构...
✔ 已创建 hooks.json
✔ 已创建 settings.local.json
✔ 已脚手架 docs/
[3/4] 🛠️ 自动修复 — 应用 CLAUDE.md...
✔ CLAUDE.md 已写入 (备份: CLAUDE_20260330_backup.md)
[4/4] 🤖 技能注入 — 生成 SKILL.md + npm 脚本...
✔ 已创建 SKILL.md
✔ 已添加到 package.json: bkit:check, bkit:fix, bkit:setup
设置完成。Claude Code 现在将自动遵循 PDCA 工作流。设置完成后，使用 npm 快捷命令：
npm run bkit:check # 项目诊断
npm run bkit:fix # 自动修复所有问题
npm run bkit:setup # 随时重新运行向导幂等性 & CI 安全。 运行两次
setup始终安全。在非 TTY 环境（CI/CD）中会跳过交互提示并保留现有文件。
🤖 Claude Code 自动化原理
setup 将 SKILL.md 注入项目根目录。Claude Code 将其作为项目上下文读取，并在每个任务中自动遵循三条规则。无需再每次说"请帮我文档化"。
graph LR
A[💬 输入提示词] --> B[Claude 读取 SKILL.md]
B --> C{规则匹配}
C -->|RULE 1| D[📋 pdca-plan 自动运行]
C -->|RULE 2| E[🔍 pdca-list 状态检查]
D --> F[⚙️ 与 Claude 一起编码]
E --> F
F -->|RULE 3| G[📝 pdca-do/check/report 自动运行]
G --> H[✅ 审计追踪完成]注入项目的三条规则：
| 规则 | 触发时机 | 动作 |
|------|---------|------|
| RULE 1: 主动文档化 | 编码前 | 自动运行 pdca-plan 生成结构化计划 |
| RULE 2: 状态同步 | 编码前 | 用 pdca-list 检查现有 PDCA 状态 |
| RULE 3: 流水线 | 编码后 | 自动运行 pdca-do → pdca-check → pdca-report |
Claude Code 将
SKILL.md作为项目上下文读取。无需安装插件 — 开箱即用。
结果： 每个功能开发、Bug 修复、重构都被自动计划、执行、验证和报告 — 零手动操作，构建完整的审计追踪。
📦 细粒度命令（精细控制）
适合想单独执行 setup 各步骤的进阶用户。
🔍 check — 项目健康扫描
npx bkit-doctor check [--path <dir>]对项目结构执行 16 项诊断检查，报告每项的 pass、warn、fail。硬性失败时退出码为 1 — 适合 CI。
| 类别 | 检查内容 | 严重度 |
|------|---------|--------|
| structure | .claude/ 目录 | hard (exit 1) |
| config | CLAUDE.md | hard (exit 1) |
| config | hooks.json、settings.local.json | soft |
| agents | 4 个代理定义文件 | soft |
| skills | .claude/skills/ 下 7 个技能文件 | soft |
| policies & templates | 4 + 4 个文件 | soft |
| docs | docs/01-plan/ → docs/04-report/、output/pdca/ | soft |
| changelog | CHANGELOG.md | soft |
🏗️ init — 结构脚手架
npx bkit-doctor init [--preset <name>] [--target <name>] [--yes]脚手架特定目标或完整预设。
| 目标 | 创建内容 |
|------|---------|
| claude-root | .claude/ 目录 |
| hooks-json | .claude/hooks.json |
| settings-local | .claude/settings.local.json |
| agents-core | 4 个代理定义文件 |
| skills-core | .claude/skills/ 下 7 个 SKILL.md 文件 |
| templates-core | 4 个文档模板 |
| policies-core | 4 个策略文件 |
| docs-core | 所有 docs/ 目录 |
| docs-pdca | output/pdca/ 目录 |
| docs-changelog | CHANGELOG.md |
预设： default（完整）· lean（最小）· workflow-core · docs
🛠️ fix — 自动修复
npx bkit-doctor fix [--yes] [--dry-run]按序执行 check → recommend → init。--dry-run 预览变更，--yes 跳过确认提示。
🤖 skill — 注入自动化规则
npx bkit-doctor skill [--append-claude] [--overwrite] [--stdout] [--dry-run]生成包含三条 PDCA 自动化规则的 SKILL.md。使用 --append-claude 可直接注入 CLAUDE.md。
🛠️ 高级功能 & 维护
🧹 clear — 安全清理
npx bkit-doctor clear [--path <dir>]⚠️ 需要明确确认。 交互式展示 bkit-doctor 生成的文件列表，删除前必须确认。不会静默删除数据。
📋 pdca — PDCA 文档引擎
为任何任务生成结构化的 Plan-Do-Check-Act 文档。状态追踪在 .bkit-doctor/pdca-state.json 中。
# 一键生成完整指南
npx bkit-doctor pdca "用户认证" --type feature --owner alice --priority P1
# 或分阶段执行
npx bkit-doctor pdca-plan "用户认证"
npx bkit-doctor pdca-do "用户认证"
npx bkit-doctor pdca-check "用户认证"
npx bkit-doctor pdca-report "用户认证"
# 查看所有追踪中的主题
npx bkit-doctor pdca-list文档类型：guideline · feature · bugfix · refactor
输出：output/pdca/<slug>-pdca-{stage}.md — 默认 git-ignore。使用 -o <path> 写入仓库内可进行 git 追踪。
🔗 与 bkit 配合使用更强大
bkit-doctor 强制执行结构并注入自动化规则。bkit 是在 Claude Code 内部运行 AI 工作流引擎的插件。
| | bkit-doctor | bkit（插件） | |--|-------------|------------| | 项目结构 | ✅ 创建 & 验证 | — | | CLAUDE.md / SKILL.md | ✅ 生成 | 读取 | | PDCA 文档引擎 | ✅ 文件生成 | 编排 | | AI 代理 & 技能 | — | ✅ 31 个代理 / 36 个技能 | | 运行环境 | 终端 | Claude Code |
# 在 Claude Code 内安装 bkit
/plugin marketplace add popup-studio-ai/bkit-claude-codeCI 使用
# GitHub Actions
- name: 检查项目结构
run: npx bkit-doctor check
# .claude/ 或 CLAUDE.md 缺失时退出码为 1贡献
欢迎贡献。请先开一个 Issue 讨论您想做的更改。
- Fork 仓库
- 创建功能分支：
git checkout -b feat/my-feature - 运行测试：
npm test - 提交 Pull Request
许可证
Apache-2.0 © dotoricode