# Project Workflow

> 文档驱动的项目开发工作流。智能判断任务类型，执行已有计划或使用 project-planning 生成新计划。 **使用场景：** - 已有完整项目文档，需要执行开发任务 - 用户指定执行某个计划（如"执行 plan 001"） - 用户请求开发新功能（使用 project-planning 生成计划） **前置条件：** - 项目应该已有 docs/ 文档结构（PRD、SAD 等） - 如果是新项目，建议先使用 project-docs-setup skill 创建完整文档 - 如果需要制定计划，建议使用 project-planning skill **与其他 skill 的关系：** - project-docs-setup：创建项目文档结构 - project-planning：制定开发计划（需求澄清 + 设计讨论 + 计划编写） - project-workflow：执行开发计划 + 更新文档 - 建议流程：project-docs-setup → project-planning → project-workflow **触发方式：** - "执行 plan 001" / "继续 001-user-authentication" - "开始开发" / "执行计划" / "继续上次的任务"

- Skill: `zhucl1006/project-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhucl1006/project-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhucl1006/project-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: zhucl1006 (https://skillmd.com/u/zhucl1006)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhucl1006/project-workflow

---


# 项目工作流

文档驱动的项目开发工作流，确保每次开发任务都有据可循、可追溯。

**重要提示**：本 skill 假设项目已有完整的文档结构（docs/README.md、PRD.md、SAD.md 等）。如果是新项目或缺少文档，强烈建议先使用 **project-docs-setup** skill 创建完整文档。如果需要制定新的开发计划，建议使用 **project-planning** skill。

## 工作流程概览

```
项目初始化：project-docs-setup（创建文档）
      ↓
计划制定：project-planning（需求澄清 + 设计 + 计划）
      ↓
执行开发：project-workflow（执行计划 + 更新文档）
```

## 前置要求

### 项目文档

本 skill 依赖完整的项目文档体系。如果项目缺少文档：

**推荐做法**：
```
使用 project-docs-setup skill：
  /project-docs-setup
  或告诉我："创建项目文档"

该 skill 会：
- 通过多轮对话了解项目需求
- 提供专业的产品和架构分析
- 生成完整的 PRD、SAD、开发指南等文档
```

**快速模式**：
不提供最小化目录结构创建。如需补全文档结构，请使用 /project-docs-setup。

### 代码审查 Agent

本 skill 使用 **通用型** agent 进行代码质量检查和优化。

**代码审查功能：**
- 代码质量审查（代码规范、最佳实践）
- Bug 和安全漏洞检测
- 性能优化建议
- 可读性和可维护性分析

**使用方式：**
```
使用 Task 工具调用：
  subagent_type="general-purpose"
  description="Code review for recent changes"
  prompt="详细的代码审查提示..."
```

**审查流程：**
1. 调用通用型 agent 分析代码变更
2. agent 生成详细的审查报告
3. 根据报告修复问题
4. 重新运行审查直到没有重大问题

### Code Review Graph 基线

处理非微小代码修改、缺陷修复、代码审查、重构、公共契约变更或重要界面流程变更时，在正式实施前使用 Code Review Graph。纯文档、微小文案或不影响行为的小修正可说明理由后跳过。

- CLI 是基础路径；MCP 是优先增强路径。只有 MCP 工具已实际暴露且调用成功时，才依赖其结果，不能仅凭配置文件存在判定可用。
- 所有查询必须绑定 `git rev-parse --show-toplevel` 返回的准确仓库根目录或已验证的唯一 alias。
- 未注册仓库不得静默注册；只提供准确命令并等待用户显式操作。
- 空图、陈旧图、无法刷新或不支持的查询不得产生“低风险”完成结论。
- MCP/CLI 失败时只记录一次限制，立即降级为 `rg` 调用点、真实 diff、测试、包边界、schema、配置和仓库 harness 分析。
- 图谱用于收敛阅读和审查范围，不得替代测试、CI、类型检查、安全检查或项目专属 harness。

### 输出预算

本 skill 默认把详细执行记录写入计划文件，聊天上下文只保留必要过程信号，避免命令输出和交付说明挤占 token。

**命令输出规则：**
- 运行命令时优先使用安静模式或范围过滤，例如 `--quiet`、`-q`、限定文件路径、限定测试用例。
- 工具支持输出预算时，默认使用较小的 `max_output_tokens`；只有定位失败原因时才临时放大。
- 搜索命令必须先限定目录、文件类型或关键词；避免全仓宽泛搜索产生大量无关输出。
- 失败时只保留命令、退出状态、关键错误行、相关文件路径和下一步判断。
- 成功时只保留通过结论、命令名和必要计数；不粘贴完整日志。
- 大段日志、完整 diff、完整测试输出不直接贴进对话；需要保留时写入计划执行记录或让用户按需查看文件。

**过程反馈规则：**
- 中间过程只用 1-2 句说明当前动作和关键发现。
- 子代理或审查结果只摘录阻塞项、重要问题、验证结论和下一步，不转述完整报告。
- 能写入计划文件的细节不重复写进聊天上下文。

---

## 核心流程

```
0. 初始化文档结构 → 1. 读取文档 → 2. 判断任务类型
   ├─ 指定 plan → 3. 执行已有计划 → 代码审查 → 修复优化 → 4. 更新文档
   └─ 无 plan → 提示使用 project-planning 创建计划
```

---

## Phase 0: 检查文档结构

**在开始执行前自动检查。**

### 0.1 检查必需的文档

检查项目是否存在标准文档结构：

```bash
# 检查必需的目录和文件
- docs/README.md           # 文档索引（必需）
- docs/plans/              # 计划文件目录
- docs/specs/              # 规格文档
```

### 0.2 文档缺失处理

如果检测到文档结构不完整：

```
1. 显示检测结果：
   "检测到项目缺少文档结构"

2. 提供建议：
   "建议使用 project-docs-setup skill 创建完整的项目文档：
   - 该 skill 会通过多轮对话了解项目需求
   - 自动生成 PRD、SAD、开发指南等完整文档
   - 提供最佳实践建议和架构分析

   运行方式：
   /project-docs-setup
   或
   告诉我：'创建项目文档'"

3. 默认行为：
   停止执行并引导使用 /project-docs-setup 生成完整文档结构。
```

### 0.3 文档已存在

如果文档结构完整，显示确认信息并跳过此阶段：

```
✓ 检测到完整的文档结构
✓ 直接进入 Phase 1
```

---

## Phase 1: 读取项目文档

**每次执行前必须完成。**

```
1. 读取 docs/README.md 获取文档索引
2. 根据索引读取任务相关的文档：
   - 规格文档 (specs/)
   - 模块文档 (modules/)
   - 开发指南 (guides/)
3. 读取 AGENTS.md（如存在）了解项目约定
```

**关键文档优先级：**
- 架构设计 (SAD.md) > 需求文档 (PRD.md) > 模块文档 > 指南

---

## Phase 2: 判断任务类型

根据用户输入判断是执行已有计划还是创建新计划。

### 2.1 识别任务类型

**执行已有计划的标志：**
- 用户明确指定 plan 编号："执行 plan 001"、"继续 001-user-authentication"
- 用户说"执行计划"、"继续上次的任务"且有进行中的计划

**创建新计划的标志：**
- 用户描述功能需求："实现用户认证"、"添加 OCR 模块"
- 用户说"开始开发 XXX 功能"

### 2.2 路由逻辑

```
if 用户指定了 plan 编号 or 有明确的进行中计划:
    → Phase 3: 执行已有计划
else:
    → 提示用户先使用 project-planning 创建计划
```

### 2.3 使用示例

**场景 1：执行已有计划**
```
用户："执行 plan 001"
或
用户："继续 001-user-authentication 的开发"

→ 路由到 Phase 3，读取并执行该计划
```

**场景 2：没有计划**
```
用户："实现用户认证功能"
或
用户："添加 API 速率限制"

→ 提示用户先使用 project-planning 创建计划：
   "请先使用 project-planning skill 创建实施计划。
    运行方式：/project-planning
    或告诉我：'帮我规划这个功能'"
```

---

## Phase 3: 执行已有计划

当用户指定了具体的 plan 文件时，直接执行该计划。

### 3.1 读取计划

```
1. 根据用户指定的编号定位 plan 文件（如 docs/plans/001-user-authentication.md）
2. 读取计划文件完整内容
3. 检查计划状态（待执行/进行中/已完成）
```

### 3.1.1 实施前 Code Review Graph 复核

对适用任务执行：

```bash
ROOT="$(git rev-parse --show-toplevel)"
uvx code-review-graph repos
uvx code-review-graph status --repo "$ROOT"
```

复核规则：

1. 确认当前仓库与计划中的仓库根目录一致，不得复用名称或结构相似仓库的图谱。
2. 图谱落后于当前 `HEAD`、未覆盖当前工作树、刚经历 rebase 或大批量变更时，运行：

```bash
uvx code-review-graph update --repo "$ROOT" --base HEAD --brief
```

3. MCP 实际可调用时，优先使用 impact-radius 校验候选文件/符号；跨模块行为增加 affected-flow，并使用 minimal-context 或 review-context 收敛源码。工具名称以当前环境实际暴露为准，常见名称为 `get_impact_radius_tool`、`get_affected_flows_tool`、`get_minimal_context_tool` 和 `get_review_context_tool`。
4. 图谱分析与计划中的影响模块、公共契约、持久化/配置影响或验证矩阵不一致时，先更新计划并确认范围，再修改代码。
5. 仓库未注册时不得自动注册，向用户提供：

```bash
uvx code-review-graph register "$ROOT" --alias "<unique-project-alias>"
```

6. 图谱不可用时执行一次降级说明并继续源码分析，不在工具问题上重复空转。

### 3.2 创建任务列表

```
1. 使用 TodoWrite 将计划中的任务转为 todos
2. 将计划状态更新为"进行中"
```

### 3.3 逐步执行

```
对于每个任务：
  1. 标记 todo 为 in_progress
  2. 参考相关文档执行任务
  3. 运行测试/验证
  4. 对实际变更执行图谱或降级影响复核
  5. 标记 todo 为 completed
  6. 更新计划文件中的任务状态 [x]
  7. 在执行记录表格中添加记录
```

**执行原则：**
- 遵循项目 AGENTS.md 中的 CONVENTIONS 和 ANTI-PATTERNS
- 遵循 TDD：先写测试，再实现
- 每完成一个任务立即更新计划文件
- 详细执行证据、命令、验证结果优先写入计划文件；聊天上下文只保留任务级摘要。
- 当当前线程上下文明显过大，或即将进入审查/验证等需要稳定注意力的阶段时，提示用户手动执行 Codex `/compact`；skill 不模拟压缩，也不通过 hook 主动触发压缩。如需自动压缩，应使用 Codex 配置（如 `model_auto_compact_token_limit`），而不是在 skill 中实现。

### 3.3.1 子代理任务循环（仅在平台支持子代理时启用）

```
对每个任务：
  1. Implementer：实现与测试，自查结果
  2. Spec Review：验证是否完全匹配计划/规格
     - 不通过 → 返回 Implementer 修复 → 重新 Spec Review
  3. Quality Review：工程质量与可维护性检查
     - 不通过 → 返回 Implementer 修复 → 重新 Quality Review
  4. 通过两阶段审查后标记任务完成
```

### 3.4 完成验证

```
1. 确认所有任务完成
2. 使用准确仓库根目录执行修改后分析：
   `uvx code-review-graph detect-changes --repo "$ROOT" --base HEAD --brief`
3. 将实际受影响模块、流程、测试缺口和风险与计划验证矩阵对照
4. 运行与实际风险匹配的测试、类型检查、安全检查和仓库 harness
5. 执行代码审查
6. 修复优化循环；修复后重新执行修改后分析和相关验证
7. 将计划状态更新为"已完成"
8. 进入 Phase 4 更新文档
```

**完成反馈规则：**
- 计划文件保存完整执行过程、验证命令、审查结论和执行记录。
- 对用户的完成反馈只保留简短摘要：改了什么、验证是否通过、是否仍有风险或未完成项。
- 不在最终回复重复粘贴计划文件里已有的详细过程、长日志或逐任务流水账。

### 3.5 代码审查和修复循环

使用通用型 agent 进行代码质量检查：

审查输入优先采用 MCP review-context/minimal-context 或 CLI/`rg` 降级分析收敛出的候选源码、真实 diff、受影响流程和验证证据。图谱输出必须用源码和测试交叉验证，不能直接当作审查结论。

```
循环执行直到没有重大问题：
  1. 调用通用型 agent
     使用 Task 工具：
       subagent_type="general-purpose"
       description="Code review for recent changes"
       prompt="
         请审查此功能/任务的代码变更。

         重点关注以下方面：
         1. 代码质量和最佳实践
            - 代码风格和一致性
            - 遵循项目约定（检查 AGENTS.md 如果存在）
            - SOLID 原则和设计模式

         2. Bug 和安全性
            - 潜在的 Bug 或边界情况
            - 安全漏洞（SQL 注入、XSS 等）
            - 错误处理完整性

         3. 性能
            - 性能瓶颈
            - 低效的算法或查询
            - 内存泄漏或资源管理问题

         4. 可维护性
            - 代码可读性和清晰度
            - 文档和注释（必要时）
            - 测试覆盖率

         请按严重程度分类问题：
         - 阻塞性：必须修复的关键问题（安全性、严重 Bug）
         - 重要：应该修复的重要问题（性能、代码质量）
         - 次要：改进建议（可读性、小优化）

         请为每个问题提供具体的文件路径和行号。
       "

  2. 分析审查报告
     - 代码规范问题
     - 潜在 Bug 和安全漏洞
     - 性能优化建议
     - 可维护性问题

  3. 根据严重程度分类
     - 阻塞性问题（必须修复）：安全漏洞、严重 Bug
     - 重要问题（应该修复）：性能问题、代码规范
     - 建议性优化（可选）：可读性改进、小优化

  4. 修复阻塞性和重要问题
     - 修改代码
     - 运行测试确保修复有效
     - 更新相关文档

  5. 重新运行代码审查
     - 验证问题已解决
     - 检查是否引入新问题

  6. 确认完成
     - 没有阻塞性问题
     - 重要问题已修复或有计划处理
     - 用户确认可以继续
```

**代码审查原则：**
- 阻塞性问题必须在此阶段解决
- 重要问题应该尽量解决
- 建议性优化可以记录到技术债务，后续处理
- 每次修复后重新运行代码审查
- 最多迭代 3-5 轮，避免过度优化
- 审查前如上下文已明显过大，先提示用户手动执行 `/compact`，压缩后再继续审查。
- 审查结论回传时优先列阻塞项、重要问题、验证结论和下一步，不转述完整审查报告。

---

## Phase 4: 更新文档

任务完成后，更新受影响的文档。

**必须检查并更新的文档：**

| 变更类型 | 需更新的文档 |
|----------|-------------|
| 新增模块 | docs/modules/{module}.md, docs/specs/SAD.md |
| API 变更 | docs/api/*.md |
| 数据库变更 | docs/database/SCHEMA.md |
| 新增功能 | docs/specs/PRD.md |
| 架构调整 | docs/specs/SAD.md, AGENTS.md |

**更新 AGENTS.md：**
- 如有新的约定或反模式，添加到对应章节
- 更新 CHANGELOG 记录变更

---

## 异常处理

| 场景 | 处理方式 |
|------|----------|
| 无 docs/ 目录 | 停止执行并引导 project-docs-setup |
| 无 docs/plans/ 目录 | 停止执行并引导 project-docs-setup |
| 无计划文件 | 提示用户使用 project-planning 创建计划 |
| 代码审查 agent 执行失败 | 检查错误信息，尝试重新执行或跳过代码审查 |
| 代码审查发现阻塞性问题 | 必须修复后才能继续，记录到执行记录 |
| 代码审查迭代超过 5 轮 | 与用户讨论是否继续优化；如上下文过大，提示用户先执行 `/compact` |
| MCP 已配置但工具未暴露或调用失败 | 记录一次限制，继续 CLI 基线；不宣称 MCP 可用 |
| Code Review Graph 仓库未注册 | 提供准确 `register` 命令，不自动注册；立即走降级影响分析 |
| 图谱为空、陈旧且无法刷新 | 不采用其低风险/token-savings 结论；使用源码、测试、schema、包边界和 harness |
| `detect-changes` 执行失败或不支持 | 记录失败证据，使用 `git diff`、`rg` 调用点和风险匹配验证替代 |
| 计划执行中断 | 恢复时读取计划文件，从未完成任务继续 |
| 任务执行失败 | 记录失败原因到执行记录，询问用户处理方式 |
| 需求变更 | 更新计划文件，标记原任务状态，添加新任务 |

---

## 附录

### 计划文件命名规范

```
docs/plans/
├── 001-user-authentication.md
├── 002-llm-service-integration.md
├── 003-ocr-module.md
└── ...
```

**命名规则：**
- 格式：`001-feature-name.md`（3位数字编号 + 功能名称）
- 编号从 001 开始，递增
- 功能名称使用小写字母和连字符，简洁明确

### 使用 project-planning 制定计划

当没有计划文件时，使用 project-planning skill 创建计划：

**调用 project-planning：**
```
使用 Skill 工具调用：skill="project-planning"
或告诉用户："/project-planning" 或 "帮我规划这个功能"
```

**project-planning 会自动：**
1. 判断需求清晰度
2. 选择合适的模式（Brainstorming 或 Writing Plans）
3. 产出计划文档（包含设计和实施，根据复杂度决定详细程度）
4. 保存到 `docs/plans/001-feature-name.md`

**完成后：**
- 计划文件会保存到 `docs/plans/001-feature-name.md`（使用3位数字编号）
- 返回 project-workflow，使用 Phase 3 执行该计划

**详细信息：**
- 参考 project-planning skill 文档
- 支持需求澄清、设计讨论、详细计划编写