PDCA+ 工作流 — PactKit Docs

PactKit 的核心方法论是 PDCA 循环 —— Plan、Act、Check、Done —— 每个阶段都设有质量关卡。

真理层级

在理解工作流之前，你必须先理解治理模型：

层级	来源	角色
第 1 层	Spec（`docs/specs/*.md`）	法律
第 2 层	测试	法律的验证
第 3 层	实现代码	可变的现实

冲突解决：当 Spec 与代码冲突时，Spec 优先 —— 修改代码。代码永远不是真理的来源。

何时用哪个命令

核心循环是 Plan → Act → Done，其他命令按需插入：

你有一个任务
  │
  ├─ 模糊想法、多个功能？ ──→ /project-design
  │
  ├─ 需求不明确？ ──→ /project-clarify → /project-plan
  │
  ├─ 明确的功能或 bug？
  │   │
  │   ├─ 小修（1 个文件、逻辑明显）？ ──→ /project-hotfix
  │   │
  │   └─ 需要设计？ ──→ /project-plan → /project-act
  │       │
  │       ├─ 涉及安全？ ──→ /project-check（QA 审计）
  │       │
  │       └─ /project-done
  │           │
  │           ├─ 在 feature branch？ ──→ /project-pr
  │           └─ 准备发版？ ──→ /project-release
  │
  └─ 全自动执行？ ──→ /project-sprint（运行所有阶段）

核心循环

1. Plan（`/project-plan "你的需求"`）

Agent：System Architect

架构师分析需求并产出：

澄清 —— 对模糊需求提出结构化问题
可视化理解 —— 设计前扫描代码库结构
Spec 创建 —— 创建 docs/specs/{ID}.md，包含需求和验收标准
Board 条目 —— 添加 Story 以跟踪工作

/project-plan "给 API 接口增加限流功能"

2. Act（`/project-act STORY-001`）

Agent：Senior Developer

开发者严格按照 Spec 实现代码：

TDD 方式 —— 先写测试，再实现
Spec 合规 —— 代码必须满足所有验收标准
迭代限制 —— 最多 5 次尝试，防止无限循环
回归检查 —— 确保完整测试套件仍然通过

环境跳出：如果测试因缺少依赖（非代码问题）而失败，开发者会停止并报告，而非尝试修复 Story 范围外的问题。

3. Done（`/project-done`）

Agent：Repo Maintainer

维护者完成最终交付：

回归关卡 —— 完整测试套件必须通过
Lint 关卡 —— 栈感知 lint 检查
覆盖率检查 —— 三级阈值（≥80% 通过、50-79% 警告、<50% 阻止）
Board 卫生 —— 所有任务已勾选，Story 已归档
提交 —— 规范提交格式（feat(scope): description）
上下文更新 —— 为下次会话准备状态

补充命令

Hotfix（`/project-hotfix "修复描述"`）—— 快速修复

跳过完整 PDCA 流程，用于小的、明显的修复：

修复拼写错误
修改配置文件
调整样式或格式
修复明显的单文件 bug

/project-hotfix "修复 README 中错误的安装命令"

何时不用：如果改动涉及多个文件或需要设计决策，请使用 /project-plan + /project-act。

Hotfix 仍会创建轻量级 Spec 和 Board 条目以保持可追溯性 —— 它只是跳过了 TDD 和 Spec lint 关卡。

Check（`/project-check STORY-001`）—— QA 审计

在 Act 和 Done 之间增加质量审查层：

安全扫描 —— 8 项 OWASP 检查清单（硬编码密钥、SQL 注入、XSS、认证、限流、错误处理、依赖）
代码质量 —— 错误处理、性能、边界条件、逻辑正确性
Spec 对齐 —— 每个验收标准映射到测试覆盖
测试质量关卡 —— 检测空壳断言、缺少断言、过度 mock

输出为结构化裁定报告，按 P0-P3 严重度分级。

何时使用：

改动涉及安全敏感代码（认证、用户输入、API）
较大的改动，提交前想多一层检查
想生成正式的测试用例文档

何时跳过：纯文档改动，或 Done 自带的回归关卡已足够的小改动。

Clarify（`/project-clarify "模糊想法"`）—— 需求澄清

在规划之前发现歧义：

/project-clarify "我想给新用户加一个 demo 命令"
# → 生成 3-6 个结构化问题（范围、用户、约束、规模、边界情况）
# → 你回答
# → 输出 Clarified Brief，可直接用于 /project-plan

Plan 已内置澄清关卡（Phase 0.7），当需求模糊时会自动触发。/project-clarify 独立使用适用于你明知想法需要在规划前先理清思路的情况。

Design（`/project-design "产品愿景"`）—— 产品设计

用于全新产品或重大新功能集：

生成完整 PRD（用户画像、功能拆解、架构图、API 设计）
创建 Tailwind CSS HTML 原型
分解为多个带优先级评分的 Story
填充 Sprint Board

/project-design "一个管理 Docker 开发环境的 CLI 工具"

与 Plan 的区别：Design 在产品级别产出 N 个 Story，Plan 在功能级别产出 1 个 Story。

PR（`/project-pr`）—— 创建 Pull Request

从 Spec 和测试结果自动生成结构化 PR：

# 在 feature branch 上执行 /project-done 之后
/project-pr
# → 从 Spec 生成 PR 标题和正文
# → 推送分支，通过 gh CLI 创建 PR

Release（`/project-release`）—— 版本发布

处理完整的发布流程：

# 在 pyproject.toml 中 bump 版本后
/project-release
# → 架构快照 → Git tag → GitHub Release

Sprint（`/project-sprint "需求"`）—— 全自动执行

一条命令运行 Plan → Act → Check → Done，使用多 Agent 团队：

/project-sprint "增加 OAuth2 登录"

每个阶段作为独立子代理运行（架构师、开发者、QA、维护者）。适合需求明确、信任完整流水线的场景。

/project-sprint 需要 Claude Code 的 Team/Task 支持。建议先使用手动 Plan → Act → Done 学习工作流，熟悉后再升级到 Sprint。

Init（`/project-init`）—— 项目初始化

在新项目中运行一次，设置 PactKit 治理。创建 pactkit.yaml、架构图、Sprint Board 和治理文件。

会话上下文

PactKit 维护 docs/product/context.md —— 一个自动生成的文件，使下次会话能即时了解项目状态：

Sprint 状态（进行中、待办、已完成数量）
近期完成项
活跃分支
建议的下一步操作

此文件由 /project-plan 和 /project-done 更新。

标准文件结构

路径	用途
`docs/specs/{ID}.md`	需求规格说明书
`docs/product/sprint_board.md`	Sprint Board
`docs/product/context.md`	会话上下文
`docs/architecture/governance/lessons.md`	经验教训
`tests/`	测试文件

目录