⚡

项目规划技能Skill project-planning

AI辅助项目规划技能，用于生成项目愿景与范围、技术规范、开发路线图和架构决策记录等关键文档，以指导新项目的启动和开发。

架构设计 0 次安装 0 次浏览 更新于 3/2/2026

项目规划技能

生成四个基本规划文件以指导AI辅助开发。这些文件在编码会话间保持上下文一致性，防止架构漂移。

何时使用此技能

  • 用户描述项目概念并请求规划文件
  • docs/planning/中的文件显示"等待生成"状态
  • 用户使用项目描述调用/plan命令
  • 开始开发需要架构决策的新功能

输出文件

文件 位置 目的
项目愿景与范围 docs/planning/project-vision.md 什么和为什么 - 问题、解决方案、范围
技术规范 docs/planning/tech-spec.md 如何 - 架构、数据模型、APIs
开发路线图 docs/planning/roadmap.md 何时 - 分阶段实施计划
架构决策记录 docs/planning/adr/adr-001-*.md 带有理由的关键技术决策

生成过程

第1步：收集项目背景

生成前收集：

  1. 项目描述来自用户输入
  2. 技术约束来自pyproject.toml和现有代码
  3. Cookiecutter选择反映在项目结构中

第2步：按顺序生成文件

按顺序生成文件，因为后面的文件引用前面的文件：

  1. 项目愿景与范围 - 确定我们正在构建的内容和原因
  2. 架构决策记录 - 基于PVS的关键技术选择
  3. 技术实施规范 - 基于ADRs的详细操作说明
  4. 开发路线图 - 基于所有上述内容的实施计划

第3步：通过共识进行专家评审

生成每个文件后，使用zen-mcp-server共识工具获得专家评审：

使用mcp__zen__consensus与gemini-3-pro-preview进行评审：

"评审此[文件类型]是否足够开始开发。

评估：
1. 具体性：需求是否足够具体以实施？
2. 完整性：所有关键部分都填写了项目特定内容吗？
3. 可行性：时间线和技术选择是否现实？
4. 清晰度：开发者能否根据此理解要构建的内容？
5. 差距：缺少哪些关键信息？

回应：
- 准备就绪：文件足够开始工作
- 需要修订：[列出具体改进要求]

文件内容：
[粘贴文件内容]

按顺序评审每个文件：

  1. PVS → 必须准备就绪后才能生成ADR
  2. ADR → 必须准备就绪后才能生成技术规范
  3. 技术规范 → 必须准备就绪后才能生成路线图
  4. 路线图 → 必须准备就绪后才能完成

如果任何文件需要修订，纳入反馈并重新评审后再进行。

第4步：验证和交叉引用

所有文件通过评审后：

  • 确保文件正确引用彼此
  • 验证技术选择在文件间一致
  • 标记需要用户验证的任何假设
  • 如果有，运行验证脚本

文件生成指南

所有文件

  • 具体性：使用具体的技术、版本和可衡量的标准
  • 无模板：每个部分必须包含项目特定信息
  • 不超过1000字：信息密集，最少的散文
  • Markdown格式：使用标题、项目符号、表格进行结构化
  • 包括TL;DR：每个文件顶部的2-3句话摘要

项目愿景与范围（PVS）

使用模板：templates/pvs-template.md

关注点：

  • 正在解决的问题和用户影响
  • 核心能力（MVP最多3-5个）
  • 明确的范围边界（内外）
  • 可衡量的成功指标

架构决策记录（ADR）

使用模板：templates/adr-template.md

创建ADR：

  • 数据库/存储选择
  • 认证策略
  • API设计方法
  • 关键框架决策
  • 任何昂贵的逆转选择

格式：adr-001-{决策-slug}.md

技术实施规范

使用模板：templates/tech-spec-template.md

包括：

  • 完整的技术栈和版本
  • 组件架构图（ASCII）
  • 数据模型和模式
  • API端点规范
  • 安全要求
  • 错误处理方法

开发路线图

使用模板：templates/roadmap-template.md

结构为：

  • 第0阶段：基础（环境，CI/CD）
  • 第1阶段：MVP核心（基本功能）
  • 第2阶段：增强（附加功能）
  • 第3阶段：抛光（测试，文档）

每个阶段需要：

  • 清晰的交付物
  • 成功标准（可测试）
  • 估计持续时间
  • 依赖关系

从项目背景预填充

生成时纳入已知信息：

# 从pyproject.toml / cookiecutter上下文
python_version = "3.12"
project_name = "Fragrance Rater"
project_slug = "fragrance_rater"
cli_framework = "Click"
containerization = "Docker"

质量检查表

完成生成前：

  • [ ] docs/planning/中创建了所有四个文件
  • [ ] 每个文件都有TL;DR部分
  • [ ] 没有"[TODO]“或”[TBD]"占位符
  • [ ] 文件相互引用
  • [ ] 技术选择一致
  • [ ] 成功标准可衡量
  • [ ] 范围边界明确
  • [ ] 至少创建了一个ADR

模板参考

模板在templates/目录中：

  • pvs-template.md - 项目愿景与范围结构
  • adr-template.md - 架构决策记录结构
  • tech-spec-template.md - 技术规范结构
  • roadmap-template.md - 开发路线图结构

详细指南

有关每种文件类型的全面文档，请参见reference/目录：

  • reference/document-guide.md - 所有文件类型的完整指南
  • reference/prompting-patterns.md - 开发期间如何使用文件

生成后

指导用户：

  1. 审核每个文件的准确性
  2. 验证标记为[ ]的假设
  3. 如有需要，调整路线图的时间线
  4. 将文件提交到版本控制
  5. 在未来的开发会话中引用文件

示例用法

当用户说：“我想构建一个用于管理个人财务的CLI工具…”

共识评审的生成流程

  1. 生成PVS

    • 读取templates/pvs-template.md
    • 生成docs/planning/project-vision.md，具体到财务CLI
    • 评审：mcp__zen__consensus与gemini-3-pro-preview → 准备就绪或修订

  2. 生成ADR

    • 读取templates/adr-template.md
    • 生成docs/planning/adr/adr-001-database-choice.md，用于SQLite决策
    • 评审：mcp__zen__consensus与gemini-3-pro-preview → 准备就绪或修订

  3. 生成技术规范

    • 读取templates/tech-spec-template.md
    • 生成docs/planning/tech-spec.md，使用Python/Click/SQLite堆栈
    • 评审：mcp__zen__consensus与gemini-3-pro-preview → 准备就绪或修订

  4. 生成路线图

    • 读取templates/roadmap-template.md
    • 生成docs/planning/roadmap.md，分阶段实施
    • 评审：mcp__zen__consensus与gemini-3-pro-preview → 准备就绪或修订

  5. 最终验证

    • 运行scripts/validate-planning-docs.py
    • 总结创建的内容并评审结果
    • 列出开始开发的下一步

共识评审提示模板

mcp__zen__consensus与gemini-3-pro-preview：

评审此Fragrance Rater的项目愿景与范围文件。

评估标准：
1. 具体性 - 开发者可以根据这些要求实施吗？
2. 完整性 - 所有部分都填写了项目特定内容吗？
3. 可行性 - 描述的约束下现实吗？
4. 清晰度 - 成功标准和范围边界不含糊吗？
5. 差距 - 缺少哪些关键信息？

回应：
- 准备就绪：足够进行到下一个文件
- 需要修订：[具体改进示例]

文件：
[完整文件内容]

MCP服务器要求

此技能需要zen-mcp-server进行共识评审。

如果不可用，跳过第3步并进行手动评审。

配置：确保mcp__zen__consensus工具可访问。