Skip to content

使用指南.md

Latest commit

 

History

History
223 lines (166 loc) · 5.84 KB

使用指南.md

File metadata and controls

223 lines (166 loc) · 5.84 KB
Raw

Claude ShapeUp 使用指南

简介

Claude ShapeUp 是一套 Claude Code 技能，将 Shape Up 方法论带入你的 AI 辅助开发流程。四个技能覆盖完整的功能开发周期：框架化 → 塑形 → 构建 → 交付。

安装

全局安装（所有项目可用）

cp -r skills/frame ~/.claude/skills/
cp -r skills/shape ~/.claude/skills/
cp -r skills/build ~/.claude/skills/
cp -r skills/ship ~/.claude/skills/

项目级安装（仅当前项目可用）

mkdir -p .claude/skills
cp -r skills/frame .claude/skills/
cp -r skills/shape .claude/skills/
cp -r skills/build .claude/skills/
cp -r skills/ship .claude/skills/

四个技能

技能 命令 作用 产出
框架化 /frame 将模糊想法转化为锁定的问题陈述 frame.md + 框架通过批准
塑形 /shape NNN 深度代码库分析，设计技术解决方案 package.md + 塑形通过批准
构建 /build NNN TDD 执行，山丘图追踪，范围管理 可运行的代码 + 构建摘要
交付 /ship NNN 提取 ADR，更新架构文档，归档功能 ADR + 架构文档更新

典型工作流

第一步：框架化问题

在 Claude Code 中运行：

/frame

Claude 会引导你完成：

  • 描述你想解决的问题
  • 确定受影响的用户群
  • 设定时间预算（Small Batch 1个会话 / Medium Batch 2-3个会话 / Big Batch 4-5个会话）
  • 评估商业价值

完成后，Claude 会请求框架通过批准。批准后，功能文件夹创建于 .shapeup/001-功能名-framing/。

第二步：塑形解决方案

/shape 001

Claude 会：

  • 读取 frame.md 并验证框架通过状态
  • 提取编号需求（R0、R1、R2...）
  • 深度分析你的代码库（实际文件，非假设）
  • 设计解决方案元素和功能点表
  • 运行适配检查矩阵（需求 × 解决方案）
  • 去风险：解决所有未知因素，修补兔子洞
  • 产出 package.md

完成后，Claude 会请求塑形通过批准。

第三步：构建功能

/build 001

Claude 会：

  • 加载方案包，验证塑形通过状态
  • 确定第一个切入点（核心/小型/新颖）
  • 先写测试（TDD），再实现
  • 垂直集成：UI + 后端同步推进
  • 发现并映射范围
  • 用山丘图追踪进展（上坡/下坡）
  • 容量不足时进行范围削减
  • 多会话时编写交接文档

完成后，产出 build-summary.md。

第四步：交付归档

/ship 001

Claude 会：

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

项目文件结构

运行技能后，你的项目会生成：

.shapeup/
├── 001-csv-import-framing/       # 框架化中
│   └── frame.md
├── 002-auth-refresh-shaped/      # 等待构建
│   ├── frame.md
│   └── package.md
├── 003-dashboard-building/       # 构建中
│   ├── frame.md
│   ├── package.md
│   ├── hillchart.md
│   ├── scopes/
│   │   ├── scope-import-parser.md
│   │   └── scope-preview-ui.md
│   └── handover-01.md
├── 004-search-shipped/           # 已完成
│   ├── frame.md
│   ├── package.md
│   ├── build-summary.md
│   └── decisions.md
└── index.md                      # 自动生成的仪表板

docs/
├── decisions/
│   ├── 0001-use-bulk-insert.md   # ADR
│   └── 0002-csv-parsing.md
└── architecture.md               # 累积的架构文档

时间预算说明

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

一个"会话"= 一次 Claude Code 对话。时间预算是固定的——如果工作无法适配，削减范围，而非延期。

关卡系统

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

框架通过 → 塑形通过 → 准备交付 → 完成
  • 框架通过：问题陈述已锁定，时间预算已确认
  • 塑形通过：技术解决方案可行，所有未知因素已解决
  • 准备交付：所有必须项完成，测试通过
  • 完成：ADR 已写，架构文档已更新，功能已归档

没有前一个关卡的批准，不能进入下一阶段。

涟漪检查钩子（可选）

安装 PostToolUse 钩子，当代理修改 Shape Up 文档时自动提醒对齐：

在 Claude Code 设置中添加：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/claude-shapeup/hooks/ripple-check.sh"
          }
        ]
      }
    ]
  }
}

当 frame.md 被修改时，钩子会提示："方案包还匹配吗？" 当 package.md 被修改时，钩子会提示："范围还对齐吗？"

常见问题

Q：可以跳过框架化直接塑形吗？ 不行。/shape 会验证 frame.md 中的框架通过状态。没有框架通过就无法继续。

Q：构建会话中断了怎么办？ Claude 会写交接文档 handover-NN.md。下次运行 /build NNN，Claude 会自动从交接恢复。

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

Q：技能文档在哪里？ 每个技能的 references/ 目录包含完整的 Shape Up 方法论文档（中文版）。技能会在需要时自动读取相关文档。

Q：如何更新已安装的技能？ 重新运行安装命令覆盖即可：

cp -r skills/* ~/.claude/skills/