Claude Project Workflow

English | Español | 中文 | 日本語 | Português

Claude Code 结构化项目工作流。

Claude Code 功能强大，但缺乏结构时，非简单项目会变得混乱——没有计划、没有上下文管理、没有质量门控、会话之间没有连续性。claude-pw 通过在 Claude Code 原生功能（命令、代理、规则、钩子）之上安装结构化工作流来解决这个问题。纯 Node.js + markdown，与编程语言无关。

安装

需要 Node.js >= 18 和 Claude Code。

npm install -g @claude-pw/framework

或使用 npx 直接运行（无需安装）：

npx @claude-pw/framework my-project

快速开始

新项目

npx @claude-pw/framework my-project
cd my-project && claude
/cpw-startup

现有项目

cd my-existing-project
npx @claude-pw/framework .
claude
/cpw-startup

/cpw-startup 自动检测你的代码库并询问如何处理：

• Brownfield — 在现有代码上添加结构（包括工具健康检查）
• Bluefield — 计划重写或迁移

更新

npx @claude-pw/framework --update

工作原理

/cpw-startup → /cpw-next-step（重复）→ 计划完成 → /cpw-startup（新周期）

1. /cpw-startup 对你进行访谈，扫描现有代码（如果有），生成包含阶段、步骤和架构文档的计划。后续周期中，加载之前的上下文并追加新阶段。
2. /cpw-discuss 识别灰色地带，在构建前捕获你的偏好（可选，按阶段）
3. /cpw-next-step 按步骤运行自适应流水线——然后自动关闭、提交并推进
4. 当所有阶段完成时，/cpw-cleanup 自动运行：生成计划摘要、审查文档、归档所有阶段文件、重置执行状态，为下一个 /cpw-startup 做好准备

每个步骤经过：

SPIKE? → DESIGN → BUILD-OR-BUY? → FEASIBILITY? → COMPATIBILITY? → IMPLEMENT → TEST → ACCEPTANCE → CLOSE

可选阶段会附带原因跳过。必要阶段（DESIGN、IMPLEMENT、TEST、ACCEPTANCE、CLOSE）始终运行。当一个阶段完成时，验证 + 用户验收测试自动运行。

STATUS.md 始终告诉 Claude 你在哪里以及需要加载什么。子计划保持小巧（每个阶段一个）。上下文重置是安全的——/cpw-next-step 会准确地从你离开的地方继续。

会话示例

> /cpw-next-step

阶段 1，步骤 1.2：租户上下文中间件

流水线：
- SPIKE: skip（标准模式）
- DESIGN: ok
- BUILD-OR-BUY: skip（自定义中间件）
- COMPATIBILITY: ok（针对 Auth 接口验证）
- IMPLEMENT: ok
- TEST: ok
- ACCEPTANCE: ok
- CLOSE: ok

继续 DESIGN？

当一个阶段的所有步骤完成时：

阶段验证... 通过
UAT 演练：

[1/3] 用户登录 — 是否正常？> 是
[2/3] 租户切换 — 是否正常？> 选择器没有切换上下文

问题已捕获。现在修复？（是/否）

差异化优势

| | claude-pw | BMAD | GSD | Taskmaster | |---|---|---|---|---| | 流水线 | 每步 9 个自适应阶段 | 按宏阶段固定 | 每阶段 3 个固定阶段 | 无 | | 上下文 | STATUS.md 指针（约 50 行）+ 运行时监控 | 重型渐进式文档 | 上下文监控 + 新子代理 | 无管理 | | 质量门控 | 阶段验证器 + UAT + pre-commit + RFC | 就绪检查 + 代码审查 + DoD | 验证器 + UAT | 可选检查器 | | 自学习 | Hook 捕获 + reflect + 技能提取 | 无 | 无 | 基础 | | 接口保护 | RFC 保护的契约 + 契约测试 | 架构文档 | 无 | 无 | | 自动化 | 3 种模式（手动 / 自动 / yolo） | 手动 | 完全自主 | 半自动 |

claude-pw 独有：

• 自适应流水线，评估每步适用哪些阶段（SPIKE、BUILD-OR-BUY、FEASIBILITY、COMPATIBILITY 不适用时附带原因跳过）
• 接口优先开发，RFC 保护和契约测试
• 自动捕获修正并路由回导致它们的命令（技能路由）
• 非显而易见的发现自动提取为可重用技能，用于语义检索
• SPIKE 和 BUILD-OR-BUY 作为流水线的一等阶段
• 启动模式（greenfield / brownfield / bluefield），每种都有适配的结构化访谈
• Brownfield 项目的工具健康检查（linter、测试、CI、pre-commit、依赖）

命令

| 命令 | 功能 | |------|------| | /cpw-startup | 发现会话——检测模式、访谈、生成计划 | | /cpw-discuss | 构建前捕获偏好和解决歧义 | | /cpw-next-step | 执行流水线、关闭步骤、验证阶段、运行 UAT（--phase 规划 + 自动推进整个阶段）| | /cpw-pause | 保存会话状态以便稍后恢复 | | /cpw-quick | 流水线外的临时任务（范围蔓延检测、--auto） | | /cpw-debug | 持久化调试会话——跨上下文重置存活 | | /cpw-health | 检查和修复项目状态 | | /cpw-todos | 捕获想法或查看待办事项 | | /cpw-reflect | 审查捕获的修正，转化为学习成果（--scan-history、--dedupe） | | /cpw-impact | 分析决策对整个计划的影响 | | /cpw-cleanup | 归档已完成阶段并清理状态（计划完成时自动执行完整重置） | | /cpw-update | 智能框架更新 — 差异对比、冲突合并、保留自定义 |

配置

/cpw-startup 询问你的偏好并保存到 .planning/config.json：

| 设置 | 选项 | 默认值 | 功能 | |------|------|--------|------| | autoAdvance | off / auto / yolo | off | off = 批准每个阶段。auto = 自动推进，UAT 时暂停。yolo = 仅在错误时暂停。 | | granularity | coarse / standard / fine | standard | 阶段数量：3-5 / 5-8 / 8-12 | | modelProfile | quality / balanced / budget | balanced | 代理模型：opus / sonnet+haiku / 主要 haiku | | modelOverrides | {} | {} | 按代理覆盖：{"researcher": "opus"} | | gitStrategy | trunk-based / feature-branch / gitflow | trunk-based | trunk-based = 推送到 main。feature-branch = 每阶段一个分支，PR 合并。gitflow = develop + feature 分支。 | | commitPlanning | true / false | false | 在 git 中跟踪 .planning/（团队使用） | | autoReflect | off / remind / auto | remind | 在会话结束或 CLOSE 阶段自动处理学习成果 |

Git 中的内容

| 内容 | 提交 | Gitignored | 原因 | |------|------|------------|------| | .claude/（命令、代理、规则、钩子） | 是 | — | 共享工作流——团队中每个人使用相同的流水线 | | CLAUDE.md、PLAN.md、Makefile | 是 | — | 项目结构和指令 | | plans/、docs/ | 是 | — | 计划、架构、决策、约定 | | .planning/（配置、学习、调试、快速日志） | 可配置 | 默认：gitignored | 设置 commitPlanning: true 与团队共享规划状态 | | STATUS.md | — | 始终 | 个人会话指针——每个开发者有自己的 | | .claude/settings.local.json | — | 始终 | 个人 Claude Code 设置 |

安装内容

my-project/
├── .claude/
│   ├── commands/       12 个斜杠命令（/cpw-*）
│   ├── agents/         12 个专用代理（4 个具有持久记忆）
│   ├── rules/          3 个上下文感知规则（git、interfaces、testing）
│   ├── hooks/          Node.js 钩子（状态栏、上下文监控）
│   └── settings.json
├── plans/              每阶段子计划 + 决策日志
├── docs/               架构、接口、约定
├── .planning/          本地状态（gitignored）
├── CLAUDE.md           代理指令
├── PLAN.md             项目索引
├── STATUS.md           会话指针（gitignored）
└── Makefile            make status / plan / check / commit / push

许可证

MIT