Skip to content

USAGE.md

Latest commit

 

History

History
184 lines (137 loc) · 5.53 KB

USAGE.md

File metadata and controls

184 lines (137 loc) · 5.53 KB
Raw

Shape Up 技能使用指南

概述

这四个 Claude Code 技能将 Shape Up 方法论带入你的开发工作流。每个技能对应流程中的一个阶段，并通过关卡门控——你必须按顺序完成每个阶段。

/shapeup:frame → /shapeup:shape → /shapeup:build → /shapeup:ship

技能一览

命令 阶段 输入 输出 关卡
/shapeup:frame NNN 框架化 模糊的想法 frame.md 框架通过
/shapeup:shape NNN 塑形 frame.md（已批准） package.md 塑形通过
/shapeup:build NNN 构建 package.md（已批准） 可运行的代码 + 交接文档 准备交付
/shapeup:ship NNN 交付 已完成的构建 ADR + 架构文档 完成

NNN 是功能编号，例如 001、042。

快速开始

第一步：框架化问题

/shapeup:frame 001

代理会引导你完成：

  • 定义具体的问题陈述（不是解决方案）
  • 识别受影响的用户群
  • 设置时间预算（Small Batch = 1 个会话 / Medium Batch = 2-3 个会话 / Big Batch = 4-5 个会话）
  • 确定商业价值
  • 批准后输出 框架通过 状态

产出文件：.shapeup/001-<功能名>-framing/frame.md

第二步：塑形解决方案

/shapeup:shape 001

代理会：

  • 深度分析你的代码库（读取实际文件，不是假设）
  • 提取编号需求（R0、R1、R2...）
  • 设计带连接的解决方案元素
  • 构建功能点表（UI 功能点 + 代码功能点）
  • 运行适配检查矩阵（R × 解决方案）
  • 解决所有兔子洞（零 TBD）
  • 批准后输出 塑形通过 状态

产出文件：.shapeup/001-<功能名>-shaped/package.md

第三步：构建功能

/shapeup:build 001

代理会：

  • 选择核心/小型/新颖的第一个部分
  • 用 TDD 进行垂直集成（先写测试）
  • 通过实际工作发现范围
  • 用山形图追踪进展（上坡 = 未知，下坡 = 执行）
  • 容量不足时进行范围削减
  • 多会话工作时写交接文档

续接构建会话：

/shapeup:build 001

（代理自动检测交接文档并从上次停止处继续）

产出文件：

  • .shapeup/001-<功能名>-building/hillchart.md
  • .shapeup/001-<功能名>-building/scopes/
  • .shapeup/001-<功能名>-building/handover-01.md（如需多个会话）
  • .shapeup/001-<功能名>-building/build-summary.md

第四步：交付并归档

/shapeup:ship 001

代理会：

  • 提取架构决策
  • 产出 ADR 到 docs/decisions/
  • 更新 docs/architecture.md
  • 将功能文件夹重命名为 -shipped
  • 重新生成项目仪表板 .shapeup/index.md

项目文件结构

你的项目/
├── .shapeup/
│   ├── index.md                          # 自动生成的仪表板
│   ├── 001-csv-import-framing/           # 框架化中
│   │   └── frame.md
│   ├── 002-auth-refresh-shaped/          # 等待构建
│   │   ├── frame.md
│   │   └── package.md
│   ├── 003-dashboard-v2-building/        # 构建中
│   │   ├── frame.md
│   │   ├── package.md
│   │   ├── hillchart.md
│   │   ├── scopes/
│   │   │   ├── scope-data-layer.md
│   │   │   └── scope-ui.md
│   │   └── handover-01.md
│   └── 004-search-shipped/               # 已完成
│       ├── frame.md
│       ├── package.md
│       └── build-summary.md
└── docs/
    ├── architecture.md                   # 累积的架构知识
    └── decisions/
        ├── 0001-use-postgres-fts.md      # ADR
        └── 0002-defer-realtime.md

时间预算说明

类型 会话数 适用场景
Small Batch 1 个会话 小功能、修复、改进
Medium Batch 2-3 个会话 中等复杂度功能
Big Batch 4-5 个会话 大型功能、重构

时间预算是固定的。如果工作不适合，就削减范围——不要延期。

关卡说明

每个阶段都有一个关卡，需要你明确批准才能继续：

  • 框架通过：问题陈述清晰，时间预算合理，值得投入
  • 塑形通过：技术解决方案可行，所有未知因素已解决，零 TBD
  • 准备交付：所有必须项完成，测试通过，比基线更好
  • 完成：ADR 已写，架构文档已更新，功能已归档

涟漪检查钩子（可选）

项目包含一个 PostToolUse 钩子，监视 .shapeup/**/*.md 的编辑：

  • 修改 frame.md 时提示："方案包还匹配吗？"
  • 修改 package.md 时提示："范围还对齐吗？"

启用方式：在你的 Claude Code 设置中添加 hooks/ripple-check.sh。

常见问题

Q：可以跳过某个阶段吗？ 不行。每个技能在继续之前会验证前一个关卡的批准状态。

Q：构建会话中断了怎么办？ 再次运行 /shapeup:build NNN，代理会自动读取交接文档并从上次停止处继续。

Q：可以并行运行多个功能吗？ 可以。每个功能都有独立的编号文件夹，互不干扰。

Q：范围削减是什么意思？ 当容量不足时，将非必须的任务标记为可选项（~）或完全删除，确保在时间预算内交付核心价值。

Q：山形图怎么理解？

  • 上坡（▲）：还有未知因素，正在解决问题
  • 下坡（▼）：方法已验证，正在执行已知工作
  • 完成（✓）：已部署，测试通过
  • 可选项（~）：如需要可削减