项目工作流

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

重要提示：本 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、限定文件路径、限定测试用例。
• 工具支持输出预算时，默认使用较小的 maxoutputtokens；只有定位失败原因时才临时放大。
• 搜索命令必须先限定目录、文件类型或关键词；避免全仓宽泛搜索产生大量无关输出。
• 失败时只保留命令、退出状态、关键错误行、相关文件路径和下一步判断。
• 成功时只保留通过结论、命令名和必要计数；不粘贴完整日志。
• 大段日志、完整 diff、完整测试输出不直接贴进对话；需要保留时写入计划执行记录或让用户按需查看文件。

过程反馈规则：

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

核心流程

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

Phase 0: 检查文档结构

在开始执行前自动检查。

0.1 检查必需的文档

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

# 检查必需的目录和文件
- 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 复核

对适用任务执行：

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

复核规则：

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

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

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

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

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

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 配置（如 modelautocompacttokenlimit），而不是在 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: 更新文档

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

必须检查并更新的文档：

更新 AGENTS.md：

• 如有新的约定或反模式，添加到对应章节
• 更新 CHANGELOG 记录变更

异常处理

附录

计划文件命名规范

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 文档
• 支持需求澄清、设计讨论、详细计划编写