scope-guard
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTable of Contents
目录
- Philosophy
- When to Use
- When NOT to Use
- Quick Start
- 1. Score the Feature
- 2. Check Against Backlog
- 3. Verify Branch Budget
- 4. Monitor Thresholds
- Core Workflow
- Step 1: Calculate Worthiness ()
scope-guard:worthiness-scored - Step 2: Compare Against Backlog ()
scope-guard:backlog-compared - Step 3: Check Branch Budget ()
scope-guard:budget-checked - Step 4: Document Decision ()
scope-guard:decision-documented - Anti-Overengineering Rules
- Backlog Management
- Directory Structure
- Queue Rules
- Adding to Queue
- Integration Points
- With superpowers:brainstorming
- With superpowers:writing-plans
- During superpowers:execute-plan
- Required TodoWrite Items
- Related Skills
- Module Reference
- 设计理念
- 适用场景
- 不适用场景
- 快速入门
- 1. 功能评分
- 2. 对照待办清单（Backlog）校验
- 3. 确认分支预算
- 4. 监控阈值
- 核心工作流
- 步骤1：计算价值匹配度 ()
scope-guard:worthiness-scored - 步骤2：与待办清单对比 ()
scope-guard:backlog-compared - 步骤3：检查分支预算 ()
scope-guard:budget-checked - 步骤4：记录决策结果 ()
scope-guard:decision-documented - 反过度设计规则
- 待办清单管理
- 目录结构
- 队列规则
- 加入队列
- 集成点
- 与 superpowers:brainstorming 集成
- 与 superpowers:writing-plans 集成
- 在 superpowers:execute-plan 阶段集成
- 必填待办项
- 相关技能
- 模块参考
Scope Guard
范围守卫（Scope Guard）
Prevents overengineering by both Claude and human during the brainstorm→plan→execute workflow. Forces explicit evaluation of every proposed feature against business value, opportunity cost, and branch constraints.
可在头脑风暴→规划→执行工作流中，避免Claude和人类开发人员出现过度设计问题，强制每项拟议功能都要对照业务价值、机会成本和分支约束进行明确评估。
Philosophy
设计理念
Core Belief: Not all features deserve implementation. Most ideas should be deferred to backlog until proven necessary.
Three Pillars:
- Worthiness Scoring - Quantify value vs cost before building
- Opportunity Cost - Compare against existing backlog
- Branch Discipline - Respect size thresholds
核心观点： 不是所有功能都值得实现，大部分想法应先推迟到待办清单，直到证明其必要性。
三大支柱：
- 价值匹配度评分 - 开发前量化功能价值与成本的对比
- 机会成本 - 与现有待办清单的内容做对比
- 分支规范 - 遵守分支大小阈值限制
When To Use
适用场景
- During brainstorming sessions before documenting designs
- During planning sessions before finalizing implementation plans
- When evaluating "should we add this?" decisions
- Automatically via hooks when branches approach thresholds
- When proposing new features, abstractions, or patterns
- 记录设计方案前的头脑风暴阶段
- 确定实现方案前的规划阶段
- 评估「我们是否应该添加这个功能」的决策场景
- 分支接近阈值时通过钩子自动触发
- 提出新功能、抽象层或开发模式时
When NOT To Use
不适用场景
- Bug fixes with clear, bounded scope
- Documentation-only changes
- Trivial single-file edits (< 50 lines)
- Emergency production fixes
- 范围明确、边界清晰的bug修复
- 仅涉及文档的变更
- 简单的单文件修改（< 50行）
- 生产环境紧急修复
Quick Start
快速入门
1. Score the Feature
1. 功能评分
Use the Worthiness formula:
(Business Value + Time Criticality + Risk Reduction) / (Complexity + Token Cost + Scope Drift)Verification: Run the command with flag to verify availability.
--helpSee decision-framework.md for details.
Thresholds:
- > 2.0 → Implement now
- 1.0 - 2.0 → Discuss first
- < 1.0 → Defer to backlog
使用价值匹配度计算公式：
(业务价值 + 时间紧迫性 + 风险降低收益) / (复杂度 + Token成本 + 范围偏移风险)校验： 执行带参数的命令验证功能可用性。
--help查看decision-framework.md了解详情。
阈值规则：
- > 2.0 → 立即实现
- 1.0 - 2.0 → 先讨论评估
- < 1.0 → 推迟加入待办清单
2. Check Against Backlog
2. 对照待办清单校验
Compare against :
docs/backlog/queue.md- Does it beat top queued items?
- Is there room in branch budget?
与的内容对比：
docs/backlog/queue.md- 该功能的优先级是否高于队列中排名靠前的项？
- 分支预算是否还有剩余？
3. Verify Branch Budget
3. 确认分支预算
Default: 3 major features per branch
If at capacity, must drop existing feature, split to new branch, or justify override.
默认规则：每个分支最多容纳3个主要功能
如果已达容量上限，必须移除现有功能、拆分到新分支，或提交特殊审批说明理由。
4. Monitor Thresholds
4. 监控阈值
Watch for Yellow/Red zones:
- Lines: 1000/1500/2000
- Commits: 15/25/30
- Days: 3/7/7+
See branch-management.md for monitoring.
关注黄/红区阈值：
- 代码行数： 1000（黄）/1500（橙）/2000（红）
- 提交次数： 15（黄）/25（橙）/30（红）
- 开发天数： 3（黄）/7（橙）/7+（红）
查看branch-management.md了解监控方式。
Core Workflow
核心工作流
Step 1: Calculate Worthiness (scope-guard:worthiness-scored
)
scope-guard:worthiness-scored步骤1：计算价值匹配度 (scope-guard:worthiness-scored
)
scope-guard:worthiness-scoredScore each factor (1, 2, 3, 5, 8, 13):
- Value Factors: Business Value, Time Criticality, Risk Reduction
- Cost Factors: Complexity, Token Cost, Scope Drift
Details: decision-framework.md
按照(1, 2, 3, 5, 8, 13)的分值为每个维度打分：
- 价值维度： 业务价值、时间紧迫性、风险降低收益
- 成本维度： 复杂度、Token成本、范围偏移风险
详情参考：decision-framework.md
Step 2: Compare Against Backlog (scope-guard:backlog-compared
)
scope-guard:backlog-compared步骤2：与待办清单对比 (scope-guard:backlog-compared
)
scope-guard:backlog-compared- Check for existing items
docs/backlog/queue.md - Compare Worthiness Scores
- New item must beat top queued item OR fit within branch budget
- 查看中的现有待办项
docs/backlog/queue.md - 对比价值匹配度评分
- 新项的评分必须高于队列顶部的项，或符合分支预算剩余额度
Step 3: Check Branch Budget (scope-guard:budget-checked
)
scope-guard:budget-checked步骤3：检查分支预算 (scope-guard:budget-checked
)
scope-guard:budget-checkedCount current features in branch. If at budget (default: 3), new feature requires:
- Dropping an existing feature, OR
- Splitting to new branch, OR
- Explicit override with justification
统计分支中当前的功能数量，如果已达预算上限（默认3个），新增功能需要满足以下任一条件：
- 移除一个现有功能，或
- 拆分到新分支，或
- 提交明确的审批说明
Step 4: Document Decision (scope-guard:decision-documented
)
scope-guard:decision-documented步骤4：记录决策结果 (scope-guard:decision-documented
)
scope-guard:decision-documentedRecord outcome:
- Implementing: Note Worthiness Score and budget slot
- Deferring (MANDATORY STEPS):
- Create GitHub issue immediately - See github-integration.md
- Mark complete
scope-guard:github-issue-created - Optionally add to with issue link
docs/backlog/queue.md
- Rejecting: Document why (low value, out of scope)
IMPORTANT: Deferral is NOT complete until a GitHub issue exists. This prevents context loss when branches are merged or abandoned.
记录决策结果：
- 选择实现： 标注价值匹配度评分和占用的预算额度
- 选择推迟（必填步骤）：
- 立即创建GitHub Issue - 参考github-integration.md
- 标记为已完成
scope-guard:github-issue-created - 可选：携带Issue链接添加到中
docs/backlog/queue.md
- 选择驳回： 记录驳回理由（价值低、超出范围等）
重要提示： 只有创建GitHub Issue后，推迟操作才算完成，避免分支合并或废弃后丢失上下文。
Anti-Overengineering Rules
反过度设计规则
Key Principles:
- Ask clarifying questions BEFORE proposing solutions
- No abstraction until 3rd use case
- Defer "nice to have" features
- Stay within branch budget
See anti-overengineering.md for full rules and red flags.
核心原则：
- 提出解决方案前先询问明确需求
- 没有出现3个同类使用场景前不做抽象
- 推迟「锦上添花」的功能
- 不超出分支预算
查看anti-overengineering.md获取完整规则和风险预警。
Backlog Management
待办清单管理
Directory Structure
目录结构
**Verification:** Run the command with `--help` flag to verify availability.
docs/backlog/
├── queue.md # Active ranked queue
└── archive/
├── ideas.md # Deferred feature ideas
├── optimizations.md # Deferred performance work
├── refactors.md # Deferred cleanup
└── abstractions.md # Deferred patternsVerification: Run the command with flag to verify availability.
--help**校验：** 执行带`--help`参数的命令验证功能可用性。
docs/backlog/
├── queue.md # 激活状态的优先级队列
└── archive/
├── ideas.md # 推迟的功能想法
├── optimizations.md # 推迟的性能优化工作
├── refactors.md # 推迟的代码清理工作
└── abstractions.md # 推迟的模式抽象工作校验： 执行带参数的命令验证功能可用性。
--helpQueue Rules
队列规则
- Max 10 items in active queue
- Items older than 30 days without pickup → move to archive
- Re-score monthly or when project context changes
- 激活队列最多容纳10个项
- 超过30天未被认领的项 → 移动到归档目录
- 每月或项目上下文发生变化时重新评分
Adding to Queue
加入队列
When deferring, add to :
docs/backlog/queue.mdmarkdown
| Rank | Item | Worthiness | Added | Branch/Epic | Category |
|------|------|------------|-------|-------------|----------|
| 1 | [New item description] | 1.8 | 2025-12-08 | current-branch | idea |Verification: Run the command with flag to verify availability.
--helpRe-rank by Worthiness Score after adding.
推迟功能时，添加到：
docs/backlog/queue.mdmarkdown
| 排名 | 项描述 | 价值匹配度 | 添加时间 | 分支/史诗 | 分类 |
|------|------|------------|-------|-------------|----------|
| 1 | [新项描述] | 1.8 | 2025-12-08 | current-branch | idea |校验： 执行带参数的命令验证功能可用性。
--help添加后按价值匹配度重新排序。
Integration Points
集成点
With superpowers:brainstorming
与 superpowers:brainstorming 集成
At end of brainstorming, before documenting design:
- List all proposed features/components
- Score each with Worthiness formula
- Defer items scoring < 1.0 to backlog
- Check branch budget for remaining items
Self-invoke prompt: "Before documenting this design, let me evaluate the proposed features with scope-guard."
头脑风暴结束后，记录设计方案前：
- 列出所有拟议的功能/组件
- 用价值匹配度公式给每个项打分
- 把评分<1.0的项推迟到待办清单
- 检查剩余项是否符合分支预算
自调用提示： "记录该设计前，我需要用scope-guard评估拟议功能。"
With superpowers:writing-plans
与 superpowers:writing-plans 集成
Before finalizing implementation plan:
- Verify all planned items have Worthiness > 1.0
- Compare against backlog queue
- Confirm within branch budget
- Document any deferrals
Self-invoke prompt: "Before finalizing this plan, let me verify scope with scope-guard."
确定实现方案前：
- 校验所有计划项的价值匹配度都>1.0
- 与待办队列对比
- 确认符合分支预算
- 记录所有推迟的项
自调用提示： "确定该方案前，我需要用scope-guard校验范围。"
During superpowers:execute-plan
在 superpowers:execute-plan 阶段集成
Periodically during execution:
- Run threshold check: lines, files, commits, days
- Warn if Yellow zone reached
- Require justification if Red zone reached
Self-invoke prompt: "This branch has grown significantly. Let me check scope-guard thresholds."
执行过程中定期触发：
- 执行阈值检查：代码行数、文件数、提交次数、开发天数
- 达到黄区时发出警告
- 达到红区时要求提交理由说明
自调用提示： "该分支规模增长明显，我需要检查scope-guard阈值。"
Required TodoWrite Items
必填待办项
When evaluating a feature, create these todos:
scope-guard:worthiness-scoredscope-guard:backlog-comparedscope-guard:budget-checked- (MANDATORY if deferring - blocks step 5)
scope-guard:github-issue-created scope-guard:decision-documented
Note: Step 4 () is REQUIRED when deferring items. You cannot mark complete without first completing for deferrals.
github-issue-createddecision-documentedgithub-issue-created评估功能时，创建以下待办项：
scope-guard:worthiness-scoredscope-guard:backlog-comparedscope-guard:budget-checked- （推迟项必填 - 阻塞步骤5）
scope-guard:github-issue-created scope-guard:decision-documented
注意： 推迟项必须完成步骤4（），否则不能标记为完成。
github-issue-createddecision-documentedRelated Skills
相关技能
- - Ideation workflow this guards
superpowers:brainstorming - - Planning workflow this validates
superpowers:writing-plans - - Review methodology pattern
imbue:review-core
- - 该工具守护的创意工作流
superpowers:brainstorming - - 该工具校验的规划工作流
superpowers:writing-plans - - 评审方法模式
imbue:review-core
Module Reference
模块参考
- decision-framework.md - Worthiness formula, scoring, thresholds
- github-integration.md - MANDATORY issue creation for deferrals
- anti-overengineering.md - Rules, patterns, red flags
- branch-management.md - Thresholds, monitoring, zones
- baseline-scenarios.md - Testing scenarios and validation
- decision-framework.md - 价值匹配度公式、评分规则、阈值
- github-integration.md - 推迟项必填的Issue创建规则
- anti-overengineering.md - 规则、模式、风险预警
- branch-management.md - 阈值、监控、分区规则
- baseline-scenarios.md - 测试场景和校验规则
Troubleshooting
问题排查
Common Issues
常见问题
Command not found
Ensure all dependencies are installed and in PATH
Permission errors
Check file permissions and run with appropriate privileges
Unexpected behavior
Enable verbose logging with flag
--verbose找不到命令
确保已安装所有依赖且已添加到环境变量PATH中
权限错误
检查文件权限，使用对应权限执行命令
非预期行为
添加参数开启详细日志排查
--verbose