bkit-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

bkit Core Rules

bkit 核心规则

Automatically applied rules that don't require user commands.

无需用户指令即可自动应用的规则

1. PDCA Auto-Apply Rules

1. PDCA 自动应用规则

No Guessing: If unsure, check docs → If not in docs, ask user SoR Priority: Code > CLAUDE.md > docs/ design documents

Request Type	Claude Behavior
New feature	Check `docs/02-design/` → Design first if missing
Bug fix	Compare code + design → Fix
Refactoring	Current analysis → Plan → Update design → Execute
Implementation complete	Suggest Gap analysis

禁止猜测：若有疑问，先查阅文档 → 文档中无相关内容则询问用户 信息源优先级：代码 > CLAUDE.md > 文档/设计文档

请求类型	Claude 行为
新功能开发	检查 `docs/02-design/` 目录 → 若缺失则先完成设计
Bug 修复	对比代码与设计文档 → 修复问题
代码重构	当前分析 → 制定计划 → 更新设计文档 → 执行重构
实现完成	建议进行差距分析

Template References

模板参考

Document Type	Template Path
Plan	`${CLAUDE_PLUGIN_ROOT}/templates/plan.template.md`
Design	`${CLAUDE_PLUGIN_ROOT}/templates/design.template.md`
Analysis	`${CLAUDE_PLUGIN_ROOT}/templates/analysis.template.md`
Report	`${CLAUDE_PLUGIN_ROOT}/templates/report.template.md`

文档类型	模板路径
计划	`${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. Level Auto-Detection

2. 项目等级自动检测

Detection Order

检测顺序

Check CLAUDE.md for explicit Level declaration
File structure based detection

检查CLAUDE.md文件中的明确等级声明
基于文件结构进行检测

Enterprise (2+ conditions met)

企业级（满足2个及以上条件）

infra/terraform/ folder
infra/k8s/ or kubernetes/ folder
services/ folder (2+ services)
turbo.json or pnpm-workspace.yaml
docker-compose.yml
.github/workflows/ (CI/CD)

infra/terraform/ 目录
infra/k8s/ 或 kubernetes/ 目录
services/ 目录（包含2个及以上服务）
turbo.json 或 pnpm-workspace.yaml 文件
docker-compose.yml 文件
.github/workflows/ 目录（CI/CD相关）

Dynamic (1+ conditions met)

动态级（满足1个及以上条件）

bkend settings in .mcp.json
lib/bkend/ or src/lib/bkend/
supabase/ folder
firebase.json

.mcp.json 文件中包含bkend配置
lib/bkend/ 或 src/lib/bkend/ 目录
supabase/ 目录
firebase.json 文件

Starter

入门级

None of the above conditions met.

未满足上述任何条件。

Level-specific Behavior

不同等级的行为差异

Aspect	Starter	Dynamic	Enterprise
Explanation	Friendly, avoid jargon	Technical but clear	Concise, use terms
Code comments	Detailed	Core logic only	Architecture only
Error handling	Step-by-step guide	Technical solutions	Brief cause + fix
PDCA docs	Simple	Feature-specific	Detailed architecture
Primary Agent	`starter-guide`	`bkend-expert`	`enterprise-expert`
Reference Skill	`starter`	`dynamic`	`enterprise`

维度	入门级	动态级	企业级
解释风格	友好易懂，避免专业术语	技术化但清晰明了	简洁专业，使用行业术语
代码注释	详细全面	仅保留核心逻辑注释	仅保留架构相关注释
错误处理	分步引导式说明	提供技术解决方案	简要说明原因及修复方法
PDCA文档	简洁版	功能专属版	详细架构版
主要Agent	`starter-guide`	`bkend-expert`	`enterprise-expert`
参考Skill	`starter`	`dynamic`	`enterprise`

Level Upgrade Signals

等级升级信号

Starter → Dynamic: "Add login", "Save data", "Admin page"
Dynamic → Enterprise: "High traffic", "Microservices", "Own server"

入门级 → 动态级：用户提出“添加登录功能”、“保存数据”、“管理页面”等需求
动态级 → 企业级：用户提出“高流量支持”、“微服务架构”、“自有服务器部署”等需求

Hierarchical CLAUDE.md Rules

分层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

Rule: Area-specific rules > Project-wide rules

project/
├── CLAUDE.md                 # 项目全局规则（始终优先参考）
├── services/CLAUDE.md        # 后端工作上下文规则
├── frontend/CLAUDE.md        # 前端工作上下文规则
└── infra/CLAUDE.md           # 基础设施上下文规则

规则：领域专属规则 > 项目全局规则

3. Agent Auto-Trigger Rules

3. Agent 自动触发规则

Level-Based Selection

基于等级的选择

When user requests feature development:

Detect project level
Invoke appropriate agent automatically

当用户请求功能开发时：

检测项目等级
自动调用对应的Agent

Task-Based Selection

基于任务的选择

User Intent	Auto-Invoke Agent
"code review", "security scan"	`bkit:code-analyzer`
"design review", "spec check"	`bkit:design-validator`
"gap analysis"	`bkit:gap-detector`
"report", "summary"	`bkit:report-generator`
"QA", "log analysis"	`bkit:qa-monitor`
"pipeline", "which phase"	`bkit:pipeline-guide`

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

Proactive Suggestions

主动建议

After completing major tasks, suggest relevant agents.

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

Do NOT Auto-Invoke When

禁止自动调用的场景

User explicitly declines
Task is trivial
User wants to understand process
Agent already invoked for same task

用户明确拒绝
任务过于琐碎
用户希望了解流程细节
同一任务已调用过该Agent

4. Code Quality Standards

4. 代码质量标准

Pre-coding Checks

编码前检查

Does similar functionality exist? Search first
Check utils/, hooks/, components/ui/
Reuse if exists; create if not

是否已有类似功能？先进行搜索
检查utils/、hooks/、components/ui/目录
若存在则复用；不存在则新建

Core Principles

核心原则

DRY: Extract to common function on 2nd use SRP: One function, one responsibility No Hardcoding: Use meaningful constants Extensibility: Write in generalized patterns

DRY原则：同一逻辑第2次使用时，提取为公共函数 单一职责原则：一个函数仅负责一项职责 禁止硬编码：使用有意义的常量 可扩展性：采用通用化模式编写代码

Self-Check After Coding

编码后自检

Same logic exists elsewhere?
Can function be reused?
Hardcoded values present?
Function does only one thing?

是否存在重复逻辑？
函数是否可复用？
是否存在硬编码值？
函数是否仅负责一项职责？

When to Refactor

重构时机

Same code appears 2nd time
Function exceeds 20 lines
if-else nests 3+ levels
Same parameters passed to multiple functions

同一代码出现第2次重复
函数代码超过20行
if-else嵌套超过3层
多个函数传递相同参数

5. Task Classification

5. 任务分类

Classify tasks to apply appropriate PDCA level:

Classification	Content Size	PDCA Level	Action
Quick Fix	< 50 chars	None	Execute immediately
Minor Change	50-200 chars	Lite	Show summary, proceed
Feature	200-1000 chars	Standard	Check/create design doc
Major Feature	> 1000 chars	Strict	Require design, user confirmation

对任务进行分类，以应用对应的PDCA严格程度：

分类	内容规模	PDCA等级	操作
快速修复	少于50字符	无	立即执行
微小变更	50-200字符	简易版	展示总结后执行
功能开发	200-1000字符	标准版	检查/创建设计文档
重大功能开发	超过1000字符	严格版	需完成设计并获得用户确认

Classification Keywords

分类关键词

Quick Fix: fix, typo, correct, adjust, tweak Minor Change: improve, refactor, enhance, optimize, update Feature: add, create, implement, build, new feature Major Feature: redesign, migrate, architecture, overhaul, rewrite

快速修复：fix、typo、correct、adjust、tweak、修复、拼写错误、调整 微小变更：improve、refactor、enhance、optimize、update、优化、重构、增强 功能开发：add、create、implement、build、new feature、添加、创建、实现 重大功能开发：redesign、migrate、architecture、overhaul、rewrite、重设计、迁移、架构重构

6. Output Style Auto-Selection (v1.5.1)

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

When project level is detected, automatically suggest the matching output style:

Level	Suggested Style	Trigger Condition
Starter	`bkit-learning`	Level detected as Starter
Dynamic	`bkit-pdca-guide`	Level detected as Dynamic
Enterprise	`bkit-enterprise`	Level detected as Enterprise

检测到项目等级后，自动推荐匹配的输出风格：

等级	推荐风格	触发条件
入门级	`bkit-learning`	检测到项目为入门级
动态级	`bkit-pdca-guide`	检测到项目为动态级
企业级	`bkit-enterprise`	检测到项目为企业级

Auto-Selection Rules

自动选择规则

On session start: Suggest output style matching detected level

/starter init

/dynamic init

/enterprise init

: Auto-suggest style for that level

On PDCA phase transitions: Suggest
```
bkit-pdca-guide
```
if not already active
User can override with
```
/output-style
```
at any time

会话启动时：推荐与检测到的项目等级匹配的输出风格
执行
```
/starter init
```
、
```
/dynamic init
```
、
```
/enterprise init
```
时：自动推荐对应等级的风格
PDCA阶段转换时：若当前未使用
```
bkit-pdca-guide
```
则推荐使用
用户可随时通过
```
/output-style
```
命令覆盖自动选择的风格

Available Output Styles

可用输出风格

Style	Best For	Key Features
`bkit-learning`	Beginners, learning	Learning points, TODO(learner) markers, concept explanations
`bkit-pdca-guide`	PDCA workflows	Status badges, checklists, phase progress, gap analysis suggestions
`bkit-enterprise`	Architecture decisions	Tradeoff analysis, cost impact, deployment strategy, SOLID compliance

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

7. Agent Teams Auto-Suggestion (v1.5.1)

7. Agent团队自动推荐（v1.5.1）

Suggest Agent Teams when conditions are met:

满足条件时，推荐使用Agent团队模式：

Suggestion Triggers

Condition	Suggestion
Major Feature (>= 1000 chars) AND Dynamic/Enterprise level	"Agent Teams can parallelize PDCA phases. Try `/pdca team {feature}` "
Match Rate < 70% AND Dynamic/Enterprise level	"Consider Agent Teams for faster parallel Check-Act iteration"
Enterprise project init	"Your project supports 4-teammate Agent Teams mode"
Dynamic project init	"Your project supports 2-teammate Agent Teams mode"

条件	推荐内容
重大功能开发（内容≥1000字符）且项目为动态级/企业级	"Agent团队可并行处理PDCA阶段，尝试使用 `/pdca team {feature}` 命令"
匹配率＜70%且项目为动态级/企业级	"考虑使用Agent团队以加快Check-Act阶段的并行迭代"
企业级项目初始化	"你的项目支持4人Agent团队模式"
动态级项目初始化	"你的项目支持2人Agent团队模式"

Team Availability

团队可用性

Level	Available	Teammates	Roles
Starter	No	-	-
Dynamic	Yes	2	developer, qa
Enterprise	Yes	4	architect, developer, qa, reviewer

等级	是否可用	团队成员数量	角色
入门级	否	-	-
动态级	是	2	开发人员、QA测试人员
企业级	是	4	架构师、开发人员、QA测试人员、评审人员

Requirements

启用要求

Environment:
```
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```
If env var not set: Suggest setting it when team mode would be beneficial
Command:
```
/pdca team {feature}
```
to start team mode

环境变量：
```
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```
若未设置该环境变量：当团队模式有益时，建议用户设置该变量
启动命令：
```
/pdca team {feature}
```

8. Agent Memory Awareness (v1.5.1)

8. Agent记忆功能（v1.5.1）

Agent Memory is automatically active for all bkit agents. No user action required.

所有bkit Agent均自动启用Agent记忆功能，无需用户操作。

How It Works

工作原理

Agents remember project context across sessions via
```
memory: project
```
scope
Some agents (
```
starter-guide
```
,
```
pipeline-guide
```
) use
```
memory: user
```
for cross-project learning

Memory persists in

.claude/agent-memory/

(project) or

~/.claude/agent-memory/

(user)

Agent通过
```
memory: project
```
作用域跨会话记住项目上下文
部分Agent（
```
starter-guide
```
、
```
pipeline-guide
```
）使用
```
memory: user
```
作用域进行跨项目学习
记忆数据存储在
```
.claude/agent-memory/
```
（项目级）或
```
~/.claude/agent-memory/
```
（用户级）目录

Memory Scopes

记忆作用域

Scope	Agents Using	Persistence
`project`	9 agents (code-analyzer, gap-detector, pdca-iterator, etc.)	Per-project, across sessions
`user`	2 agents (starter-guide, pipeline-guide)	Global, across all projects

作用域	使用的Agent	持久化方式
`project`	9个Agent（code-analyzer、gap-detector、pdca-iterator等）	项目级，跨会话保留
`user`	2个Agent（starter-guide、pipeline-guide）	全局级，跨所有项目保留

Proactive Mention

主动提示

On session start: "Agent Memory is active — agents remember context across sessions"
When agent is invoked: Agent may reference previous session context
No configuration needed — fully automatic

会话启动时："Agent记忆功能已激活 —— Agent可跨会话记住上下文信息"
调用Agent时：Agent可能会引用之前会话的上下文
无需配置 —— 完全自动启用