project-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

项目工作流

Project Workflow

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

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

Documentation-driven project development workflow, ensuring every development task is traceable and based on documentation.

Important Note: This skill assumes the project has a complete documentation structure (docs/README.md, PRD.md, SAD.md, etc.). For new projects or those lacking documentation, it is strongly recommended to first use the project-docs-setup skill to create complete documentation. If you need to formulate a new development plan, it is recommended to use the project-planning skill.

工作流程概览

Workflow Overview

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

Project Initialization: project-docs-setup (Create documentation)
      ↓
Plan Formulation: project-planning (Requirement clarification + Design + Plan)
      ↓
Development Execution: project-workflow (Execute plan + Update documentation)

前置要求

Prerequisites

项目文档

Project Documentation

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

推荐做法：

使用 project-docs-setup skill：
  /project-docs-setup
  或告诉我："创建项目文档"

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

快速模式：如果只是简单测试，Phase 0 可以创建最小化目录结构，但不包含文档内容。

This skill relies on a complete project documentation system. If the project lacks documentation:

Recommended Approach:

Use the project-docs-setup skill:
  /project-docs-setup
  or tell me: "Create project documentation"

This skill will:
- Understand project requirements through multi-round conversations
- Provide professional product and architecture analysis
- Generate complete documentation such as PRD, SAD, development guides, etc.

Quick Mode: For simple testing only, Phase 0 can create a minimal directory structure, but no documentation content will be included.

代码审查 Agent

Code Review Agent

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

代码审查功能：

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

使用方式：

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

审查流程：

调用通用型 agent 分析代码变更
agent 生成详细的审查报告
根据报告修复问题
重新运行审查直到没有重大问题

This skill uses a general-purpose agent for code quality inspection and optimization.

Code Review Features:

Code quality review (code standards, best practices)
Bug and security vulnerability detection
Performance optimization suggestions
Readability and maintainability analysis

Usage Method:

Call using Task tool:
  subagent_type="general-purpose"
  description="Code review for recent changes"
  prompt="Detailed code review prompt..."

Review Process:

Call the general-purpose agent to analyze code changes
The agent generates a detailed review report
Fix issues based on the report
Re-run the review until no major issues exist

核心流程

Core Process

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

0. Initialize documentation structure → 1. Read documentation → 2. Determine task type
   ├─ Specified plan → 3. Execute existing plan → Code review → Fix and optimize → 4. Update documentation
   └─ No plan → Prompt to use project-planning to create a plan

Phase 0: 检查文档结构

Phase 0: Check Documentation Structure

在开始执行前自动检查。

Automatically checked before execution starts.

0.1 检查必需的文档

0.1 Check Required Documentation

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

bash

undefined

Check if the project has a standard documentation structure:

bash

undefined

检查必需的目录和文件

Check required directories and files

docs/README.md # 文档索引（必需）
docs/plans/ # 计划文件目录
docs/specs/ # 规格文档

undefined

docs/README.md # Documentation index (required)
docs/plans/ # Plan file directory
docs/specs/ # Specification documents

undefined

0.2 文档缺失处理

0.2 Handling Missing Documentation

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

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

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

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

3. 询问用户选择：
   "你希望如何处理？
   a) 先创建完整文档（推荐）- 我可以帮你调用 project-docs-setup
   b) 创建最小化结构继续 - 只创建空目录，无文档内容
   c) 跳过检查继续执行 - 假设文档在其他位置"

4. 根据用户选择：
   - 选择 a：调用 project-docs-setup skill 或提示用户运行
   - 选择 b：执行 0.3 创建最小化结构
   - 选择 c：跳过 Phase 0，进入 Phase 1

If incomplete documentation structure is detected:

1. Display detection results:
   "Detected missing project documentation structure"

2. Provide suggestions:
   "It is recommended to use the project-docs-setup skill to create complete project documentation:
   - This skill will understand project requirements through multi-round conversations
   - Automatically generate complete documents such as PRD, SAD, development guides, etc.
   - Provide best practice suggestions and architecture analysis

   Execution methods:
   /project-docs-setup
   or
   Tell me: 'Create project documentation'"

3. Ask for user's choice:
   "How would you like to handle this?
   a) Create complete documentation first (recommended) - I can help you call project-docs-setup
   b) Create minimal structure to continue - Only create empty directories, no documentation content
   c) Skip check and continue execution - Assume documentation is in another location"

4. Based on user's choice:
   - Choose a: Call project-docs-setup skill or prompt user to run it
   - Choose b: Execute 0.3 to create minimal structure
   - Choose c: Skip Phase 0 and enter Phase 1

0.3 创建最小化结构（仅在用户选择时）

0.3 Create Minimal Structure (Only when user chooses)

bash

undefined

bash

undefined

只创建目录结构，不创建任何文件

Only create directory structure, no files will be created

mkdir -p docs/plans mkdir -p docs/specs mkdir -p docs/guides mkdir -p docs/modules mkdir -p docs/database mkdir -p docs/api

echo "已创建基础目录结构。" echo "注意：目录为空，建议后续使用 project-docs-setup 补充完整文档。"

undefined

mkdir -p docs/plans mkdir -p docs/specs mkdir -p docs/guides mkdir -p docs/modules mkdir -p docs/database mkdir -p docs/api

echo "Basic directory structure created." echo "Note: Directories are empty, it is recommended to use project-docs-setup to supplement complete documentation later."

undefined

0.4 文档已存在

0.4 Documentation Exists

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

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

If documentation structure is complete, display confirmation information and skip this phase:

✓ Detected complete documentation structure
✓ Directly enter Phase 1

Phase 1: 读取项目文档

Phase 1: Read Project Documentation

每次执行前必须完成。

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

关键文档优先级：

架构设计 (SAD.md) > 需求文档 (PRD.md) > 模块文档 > 指南

Must be completed before each execution.

1. Read docs/README.md to get documentation index
2. Read task-related documents based on the index:
   - Specification documents (specs/)
   - Module documents (modules/)
   - Development guides (guides/)
3. Read AGENTS.md (if exists) to understand project conventions

Key Document Priority:

Architecture Design (SAD.md) > Requirement Document (PRD.md) > Module Documents > Guides

Phase 2: 判断任务类型

Phase 2: Determine Task Type

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

Determine whether to execute an existing plan or create a new plan based on user input.

2.1 识别任务类型

2.1 Identify Task Type

执行已有计划的标志：

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

创建新计划的标志：

用户描述功能需求："实现用户认证"、"添加 OCR 模块"
用户说"开始开发 XXX 功能"

Signs of executing existing plan:

User clearly specifies plan number: "Execute plan 001", "Continue 001-user-authentication"
User says "Execute plan", "Continue last task" and there is an ongoing plan

Signs of creating new plan:

User describes functional requirements: "Implement user authentication", "Add OCR module"
User says "Start developing XXX feature"

2.2 路由逻辑

2.2 Routing Logic

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

if user specified plan number or there is a clear ongoing plan:
    → Phase 3: Execute existing plan
else:
    → Prompt user to use project-planning to create a plan

2.3 使用示例

2.3 Usage Examples

场景 1：执行已有计划

用户："执行 plan 001"
或
用户："继续 001-user-authentication 的开发"

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

场景 2：没有计划

用户："实现用户认证功能"
或
用户："添加 API 速率限制"

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

Scenario 1: Execute existing plan

User: "Execute plan 001"
or
User: "Continue development of 001-user-authentication"

→ Route to Phase 3, read and execute the plan

Scenario 2: No plan exists

User: "Implement user authentication feature"
or
User: "Add API rate limiting"

→ Prompt user to use project-planning to create a plan first:
   "Please use the project-planning skill to create an implementation plan first.
    Execution methods: /project-planning
    or tell me: 'Help me plan this feature'"

Phase 3: 执行已有计划

Phase 3: Execute Existing Plan

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

When the user specifies a specific plan file, execute the plan directly.

3.1 读取计划

3.1 Read Plan

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

1. Locate the plan file based on the user-specified number (e.g., docs/plans/001-user-authentication.md)
2. Read the complete content of the plan file
3. Check plan status (pending/in progress/completed)

3.2 创建任务列表

3.2 Create Task List

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

1. Convert tasks in the plan to todos using TodoWrite
2. Update plan status to "in progress"

3.3 逐步执行

3.3 Execute Step by Step

对于每个任务：
  1. 标记 todo 为 in_progress
  2. 参考相关文档执行任务
  3. 运行测试/验证
  4. 标记 todo 为 completed
  5. 更新计划文件中的任务状态 [x]
  6. 在执行记录表格中添加记录

执行原则：

遵循项目 AGENTS.md 中的 CONVENTIONS 和 ANTI-PATTERNS
遵循 TDD：先写测试，再实现
每完成一个任务立即更新计划文件

For each task:
  1. Mark todo as in_progress
  2. Execute task with reference to relevant documents
  3. Run tests/verification
  4. Mark todo as completed
  5. Update task status in the plan file [x]
  6. Add record to the execution record table

Execution Principles:

Follow CONVENTIONS and ANTI-PATTERNS in the project's AGENTS.md
Follow TDD: Write tests first, then implement
Update the plan file immediately after completing each task

3.4 完成验证

3.4 Completion Verification

1. 确认所有任务完成
2. 运行完整测试套件
3. 执行代码审查
4. 修复优化循环
5. 将计划状态更新为"已完成"
6. 进入 Phase 4 更新文档

1. Confirm all tasks are completed
2. Run complete test suite
3. Execute code review
4. Fix and optimize loop
5. Update plan status to "completed"
6. Enter Phase 4 to update documentation

3.5 代码审查和修复循环

3.5 Code Review and Fix Loop

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

循环执行直到没有重大问题：
  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 轮，避免过度优化

Use general-purpose agent for code quality inspection:

Loop until no major issues exist:
  1. Call general-purpose agent
     Using Task tool:
       subagent_type="general-purpose"
       description="Code review for recent changes"
       prompt="
         Please review the code changes for this feature/task.

         Focus on the following aspects:
         1. Code quality and best practices
            - Code style and consistency
            - Follow project conventions (check AGENTS.md if exists)
            - SOLID principles and design patterns

         2. Bugs and security
            - Potential bugs or edge cases
            - Security vulnerabilities (SQL injection, XSS, etc.)
            - Completeness of error handling

         3. Performance
            - Performance bottlenecks
            - Inefficient algorithms or queries
            - Memory leaks or resource management issues

         4. Maintainability
            - Code readability and clarity
            - Documentation and comments (when necessary)
            - Test coverage

         Please classify issues by severity:
         - Blocking: Critical issues that must be fixed (security, severe bugs)
         - Important: Important issues that should be fixed (performance, code quality)
         - Minor: Improvement suggestions (readability, small optimizations)

         Please provide specific file paths and line numbers for each issue.
       "

  2. Analyze review report
     - Code standard issues
     - Potential bugs and security vulnerabilities
     - Performance optimization suggestions
     - Maintainability issues

  3. Classify by severity
     - Blocking issues (must fix): Security vulnerabilities, severe bugs
     - Important issues (should fix): Performance issues, code standards
     - Suggested optimizations (optional): Readability improvements, small optimizations

  4. Fix blocking and important issues
     - Modify code
     - Run tests to ensure fixes are effective
     - Update relevant documentation

  5. Re-run code review
     - Verify issues are resolved
     - Check for new issues introduced

  6. Confirm completion
     - No blocking issues
     - Important issues are fixed or have a plan for handling
     - User confirms to continue

Code Review Principles:

Blocking issues must be resolved in this phase
Important issues should be resolved as much as possible
Suggested optimizations can be recorded as technical debt and handled later
Re-run code review after each fix
Maximum 3-5 iterations to avoid over-optimization

Phase 4: 更新文档

Phase 4: Update Documentation

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

必须检查并更新的文档：

变更类型	需更新的文档
新增模块	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 记录变更

After task completion, update affected documentation.

Documents that must be checked and updated:

Change Type	Documents to Update
New module added	docs/modules/{module}.md, docs/specs/SAD.md
API changes	docs/api/*.md
Database changes	docs/database/SCHEMA.md
New feature added	docs/specs/PRD.md
Architecture adjustment	docs/specs/SAD.md, AGENTS.md

Update AGENTS.md:

If there are new conventions or anti-patterns, add to corresponding sections
Update CHANGELOG to record changes

异常处理

Exception Handling

场景	处理方式
无 docs/ 目录	自动创建文档结构（Phase 0）
无 docs/plans/ 目录	自动创建 docs/plans/ 目录
无计划文件	提示用户使用 project-planning 创建计划
代码审查 agent 执行失败	检查错误信息，尝试重新执行或跳过代码审查
代码审查发现阻塞性问题	必须修复后才能继续，记录到执行记录
代码审查迭代超过 5 轮	与用户讨论，决定是否继续优化或接受当前状态
计划执行中断	恢复时读取计划文件，从未完成任务继续
任务执行失败	记录失败原因到执行记录，询问用户处理方式
需求变更	更新计划文件，标记原任务状态，添加新任务

Scenario	Handling Method
No docs/ directory	Automatically create documentation structure (Phase 0)
No docs/plans/ directory	Automatically create docs/plans/ directory
No plan file	Prompt user to use project-planning to create a plan
Code review agent execution failed	Check error message, try re-execution or skip code review
Blocking issues found in code review	Must fix before continuing, record in execution record
Code review iterations exceed 5 rounds	Discuss with user, decide whether to continue optimization or accept current status
Plan execution interrupted	Read plan file when resuming, continue from uncompleted tasks
Task execution failed	Record failure reason in execution record, ask user for handling method
Requirement change	Update plan file, mark original task status, add new tasks

附录

Appendix

计划文件命名规范

Plan File Naming Convention

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

命名规则：

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

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

Naming Rules:

Format:
```
001-feature-name.md
```
(3-digit number + feature name)
Numbering starts from 001 and increments
Feature name uses lowercase letters and hyphens, concise and clear

使用 project-planning 制定计划

Use project-planning to Formulate Plans

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

调用 project-planning：

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

project-planning 会自动：

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

完成后：

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

详细信息：

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

When no plan file exists, use the project-planning skill to create a plan:

Call project-planning:

Call using Skill tool: skill="project-planning"
or tell user: "/project-planning" or "Help me plan this feature"

project-planning will automatically:

Determine requirement clarity
Select appropriate mode (Brainstorming or Writing Plans)
Produce plan documentation (includes design and implementation, detail level depends on complexity)
Save to
```
docs/plans/001-feature-name.md
```

After completion:

Plan file will be saved to
```
docs/plans/001-feature-name.md
```
(using 3-digit numbering)
Return to project-workflow, execute the plan using Phase 3

Detailed Information:

Refer to project-planning skill documentation
Supports requirement clarification, design discussion, detailed plan writing