bkit-rules

bkit 核心规则

自动应用的规则，无需用户下达命令。

1. PDCA 自动应用规则

不猜测：如果不确定，先查阅文档 → 如果文档中没有，询问用户
SoR 优先级：代码 > CLAUDE.md > docs/ 设计文档

请求类型	Claude 的行为
新功能	检查 docs/02-design/ → 如果缺少设计，则先进行设计
Bug 修复	对比代码和设计 → 修复
重构	当前分析 → 规划 → 更新设计 → 执行
实现完成	建议进行差距分析

模板参考

文档类型	模板路径
计划	${CLAUDE_PLUGIN_ROOT}/templates/plan.template.md
设计	${CLAUDE_PLUGIN_ROOT}/templates/design.template.md
分析	${CLAUDE_PLUGIN_ROOT}/templates/analysis.template.md
报告	${CLAUDE_PLUGIN_ROOT}/templates/report.template.md

---

2. 自动检测级别

检测顺序

1. 检查 CLAUDE.md 中是否明确声明了级别
2. 根据文件结构进行检测

企业级（满足 2 项或更多条件）

• infra/terraform/ 文件夹
• infra/k8s/ 或 kubernetes/ 文件夹
• services/ 文件夹（2 个或更多服务）
• turbo.json 或 pnpm-workspace.yaml
• docker-compose.yml
• .github/workflows/（CI/CD）

动态级（满足 1 项或更多条件）

• .mcp.json 中的 bkend 设置
• lib/bkend/ 或 src/lib/bkend/
• supabase/ 文件夹
• firebase.json

入门级

不满足以上任何条件。

级别专属行为

方面	入门级	动态级	企业级
说明	友好，避免术语	技术化但清晰	简洁，使用专业术语
代码注释	详细	仅核心逻辑	仅架构相关
错误处理	分步指南	技术解决方案	简述原因和修复方法
PDCA 文档	简单	按功能区分	详细架构
主要 Agent	starter-guide	bkend-expert	enterprise-expert
参考 Skill	starter	dynamic	enterprise

级别升级信号

• 入门级 → 动态级：“添加登录”“保存数据”“管理页面”
• 动态级 → 企业级：“高流量”“微服务”“自有服务器”

分层 CLAUDE.md 规则

project/
├── CLAUDE.md                 # Project-wide (always reference)
├── services/CLAUDE.md        # Backend work context
├── frontend/CLAUDE.md        # Frontend work context
└── infra/CLAUDE.md           # Infrastructure context

规则：区域专属规则 > 项目范围规则

---

3. Agent 自动触发规则

按级别选择

当用户请求开发功能时：

1. 检测项目级别
2. 自动调用适当的 Agent

按任务选择

用户意图	自动调用的 Agent
“代码审查”“安全扫描”	bkit:code-analyzer
“设计审查”“规范检查”	bkit:design-validator
“差距分析”	bkit:gap-detector
“报告”“摘要”	bkit:report-generator
“QA”“日志分析”	bkit:qa-monitor
“流水线”“当前阶段”	bkit:pipeline-guide

主动建议

完成重要任务后，建议调用相关 Agent。

不要自动调用的情况

• 用户明确拒绝
• 任务很简单
• 用户想了解流程
• 同一任务已调用过 Agent

---

4. 代码质量标准

编码前检查

1. 是否已有类似功能？先搜索
2. 检查 utils/、hooks/、components/ui/
3. 如果已存在则复用；否则创建

核心原则

DRY：第二次使用时提取为通用函数
SRP：一个函数只负责一项职责
不硬编码：使用有意义的常量
可扩展性：采用通用模式编写

编码后自查

• 其他地方是否存在相同逻辑？
• 函数是否可以复用？
• 是否存在硬编码值？
• 函数是否只做一件事？

需要重构的情况

• 相同代码第二次出现
• 函数超过 20 行
• if-else 嵌套 3 层或更多
• 多个函数传入相同参数

---

5. 任务分类

对任务进行分类，以应用相应的 PDCA 级别：

分类	内容长度	PDCA 级别	操作
快速修复	< 50 个字符	无	立即执行
小幅变更	50-200 个字符	轻量	显示摘要后继续
功能	200-1000 个字符	标准	检查/创建设计文档
重大功能	> 1000 个字符	严格	必须提供设计并获得用户确认

分类关键词

快速修复：fix、typo、correct、adjust、tweak 小幅变更：improve、refactor、enhance、optimize、update 功能：add、create、implement、build、new feature 重大功能：redesign、migrate、architecture、overhaul、rewrite

---

6. 输出风格自动选择（v1.5.1）

检测到项目级别后，自动建议匹配的输出风格：

级别	建议风格	触发条件
Starter	bkit-learning	检测到 Starter 级别
Dynamic	bkit-pdca-guide	检测到 Dynamic 级别
Enterprise	bkit-enterprise	检测到 Enterprise 级别

自动选择规则

• 会话开始时：建议与检测到的级别匹配的输出风格
• 使用 /starter init、/dynamic init、/enterprise init 时：自动建议该级别对应的风格
• PDCA 阶段转换时：如果尚未启用 bkit-pdca-guide，则建议使用
• 用户可随时通过 /output-style 覆盖设置

可用的输出风格

风格	适用场景	主要特点
bkit-learning	初学者、学习	学习要点、TODO(learner) 标记、概念说明
bkit-pdca-guide	PDCA 工作流	状态徽章、检查清单、阶段进度、差距分析建议
bkit-enterprise	架构决策	权衡分析、成本影响、部署策略、SOLID 合规性

---

7. Agent Teams 自动建议（v1.5.1）

满足条件时建议使用 Agent Teams：

建议触发条件

条件	建议
重大功能（>= 1000 个字符）且为 Dynamic/Enterprise 级别	“Agent Teams 可并行处理 PDCA 阶段。试试 /pdca team {feature}”
匹配率 < 70% 且为 Dynamic/Enterprise 级别	“可考虑使用 Agent Teams，加快并行的 Check-Act 迭代”
初始化 Enterprise 项目	“你的项目支持 4 名队友的 Agent Teams 模式”
初始化 Dynamic 项目	“你的项目支持 2 名队友的 Agent Teams 模式”

团队可用性

级别	可用	队友数	角色
Starter	否	-	-
Dynamic	是	2	developer、qa
Enterprise	是	4	architect、developer、qa、reviewer

要求

• 环境：CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• 如果未设置环境变量：在团队模式有帮助时，建议设置该变量
• 命令：使用 /pdca team {feature} 启动团队模式

---

8. Agent Memory 感知（v1.5.1）

所有 bkit Agent 均自动启用 Agent Memory。无需用户操作。

工作原理

• Agent 通过 memory: project 范围跨会话记住项目上下文
• 部分 Agent（starter-guide、pipeline-guide）使用 memory: user 进行跨项目学习
• 记忆保存在 .claude/agent-memory/（项目）或 ~/.claude/agent-memory/（用户）中

记忆范围

范围	使用该范围的 Agent	持久性
project	9 个 Agent（code-analyzer、gap-detector、pdca-iterator 等）	按项目保存，跨会话保留
user	2 个 Agent（starter-guide、pipeline-guide）	全局保存，适用于所有项目

主动提示

• 会话开始时：“Agent Memory 已启用——Agent 会跨会话记住上下文”
• 调用 Agent 时：Agent 可能会引用之前会话的上下文
• 无需配置——完全自动运行

9. 插件热重载（v1.6.0）

修改 bkit 插件文件后，使用 /reload-plugins 即可应用更改，无需重启 Claude Code。

• 无需退出并重新进入会话
• 对技能、Agent、钩子和模板的更改会立即生效
• 注意：要完全刷新 CLAUDE.md 中的更改，需使用 /clear

通配符权限（CC 2.1.0+）

CC 2.1.0+ 支持 Bash(pattern*) 通配符权限。

bkit 推荐模式

• Bash(npm *) - 允许所有 npm 命令
• Bash(git log*) - 允许各种 git log 命令
• Bash(node *) - 允许执行 node
• Bash(npx *) - 允许执行 npx

拒绝建议

• Bash(rm -rf*) - 拒绝递归删除（危险）
• Bash(git push --force*) - 拒绝强制推送

配置

添加到 .claude/settings.json：

{
  "permissions": {
    "allow": ["Bash(npm *)", "Bash(git log*)"],
    "deny": ["Bash(rm -rf*)"]
  }
}