developer-summary

开发者摘要

根据 Sherpy 规划材料生成面向开发者的摘要文档。为开发者提供快速入门概览，说明正在构建的内容、关键交付成果和里程碑路线图。

用法

/developer-summary [base-directory]

如果未提供目录，则通过查找当前目录中的 requirements/business-requirements.yaml 自动检测。

如果未找到，请提示用户：“规划材料位于哪里？”

等待用户提供路径后再继续。

必需材料

此技能会根据标准 Sherpy 文件夹结构自动发现以下文件：

文件	位置	用途
business-requirements.yaml	requirements/	项目概览和交付成果
technical-requirements.yaml	requirements/	技术背景和架构
milestones.yaml	implementation/	里程碑顺序和估算
timeline.yaml	delivery/	时间线估算和日期

流程

第 1 步：确定基础目录并扫描必需材料

如果未提供目录参数，请检查当前目录中是否存在 requirements/business-requirements.yaml。

• 如果找到，则将当前目录用作 base_directory
• 如果未找到，则提示：“规划材料位于哪里？”并等待用户回复

确定 base_directory 后，在标准位置扫描必需文件。显示状态：

## Developer Summary — Dependency Check

Scanning for required artifacts...

 ✓  requirements/business-requirements.yaml
 ✓  requirements/technical-requirements.yaml
 ✓  implementation/milestones.yaml
 ✗  delivery/timeline.yaml

3 of 4 required files found.

图例： ✓ 已找到 · ✗ 缺失

第 2 步：处理缺失文件

如果缺少任何必需文件，请询问：

“缺少必需文件：timeline.yaml

选项：

1. 使用部分数据继续 — 根据可用信息生成摘要（缺失的部分将标记为 [Not Available]）
2. 退出 — 先补齐缺失材料（运行 /delivery-timeline 以生成 timeline.yaml）

你想怎么做？”

等待用户回复：

• 如果用户选择 1（继续）：使用可用数据继续，并清楚标记缺失的部分
• 如果用户选择 2（退出）：显示需要运行的技能，然后正常退出

第 3 步：加载并解析材料

读取所有可用文件并提取：

从 business-requirements.yaml 中提取：

• 项目名称和描述
• 核心功能和能力
• 关键交付成果

从 technical-requirements.yaml 中提取：

• 技术栈
• 架构模式
• 关键技术组件

从 milestones.yaml 中提取：

• 里程碑顺序（m0、m1、m2 等）
• 里程碑名称和描述
• 里程碑之间的依赖关系
• 每个里程碑的预计时长

从 timeline.yaml（如果可用）中提取：

• 项目总时长
• 目标完成日期
• 时间线倒排计划

第 4 步：生成开发者摘要

创建 summaries/developer-summary.md。

输出文档包括：标题（时间戳、项目名称）、Overview（3–5 句话的综合概述）、Deliverables（按类别分组）、Milestones & Timeline（M0、M1……及其时长、依赖关系、关键交付成果）和 Summary（里程碑总数、预计时长、目标完成时间）。

完整的文档规范（包括章节结构和格式规则）请参阅 references/output-spec.md。

完整示例请参阅 references/example.md。

第 5 步：妥善处理缺失数据

缺少必需文件时，插入清晰的占位内容：

## Milestones & Timeline

[Not Available - `milestones.yaml` not found. Run `/implementation-planner` to generate milestones.]

部分数据缺失时，则使用：

## Summary

**Total Milestones:** 4
**Estimated Total Duration:** 6 weeks (estimated from milestones)
**Target Completion:** [Not Available - run `/delivery-timeline` to set production deploy date]

第 6 步：确认

生成摘要后，显示：

## Developer Summary Generated ✓

**Location:** summaries/developer-summary.md
**Size:** [file size]

Summary includes:
  ✓ Project overview
  ✓ Deliverables breakdown
  ✓ Milestone roadmap
  [Missing data: timeline completion date - run /delivery-timeline]

The summary is ready for developer onboarding and reference.

交付成果提取逻辑

识别交付物

解析以下来源，构建交付物列表：

来自 business-requirements.yaml：

• functional_requirements → 面向用户的功能
• features 或 capabilities → 高级功能
• scope.in_scope → 明确纳入范围的项目

来自 technical-requirements.yaml：

• architecture.components → 技术组件
• technology_stack → 基础设施项目（数据库、API、服务）
• data_model.entities → 领域实体/模型
• apis.endpoints → API 端点（如有列出）
• integration_points → 外部集成

分类规则

根据类型将交付物归入逻辑类别：

• API 端点 - REST/GraphQL 端点、Webhook
• 领域处理器 - 业务逻辑处理器、命令处理器
• UI 组件 - 页面、视图、组件（如适用）
• 数据模型 - 实体、架构、数据库表
• 基础设施 - 数据库、消息队列、身份验证系统
• 集成 - 外部服务连接
• 后台任务 - 定时任务、工作进程
• 配置 - 环境设置、部署配置

根据需求中实际存在的内容，选择最相关的类别。不要强行套用不适用的类别。

概述生成逻辑

撰写概述段落

综合多个来源的信息，撰写简洁、信息丰富的概述：

需要包含的要素（按顺序）：

1. 是什么 - 正在构建的系统/功能（1 句话）
2. 为什么 - 它解决的问题或提供的价值（1 句话）
3. 如何实现（高层次） - 实现方式或关键能力（1 句话，可选）

使用的来源字段：

• business-requirements.yaml：
  • description 或 overview
  • business_goals.primary_goal
  • success_criteria
• technical-requirements.yaml：
  • solution_overview
  • architecture.approach

模板：

“[System Name] 是一个 [type of system]，用于 [primary function]。它通过 [solution approach] 解决 [problem]，从而实现 [key benefit/outcome]。该系统将 [key technical approach or differentiator]。”

示例：

“Sherpy CLI 是一款用于 AI 辅助软件开发的结构化规划工具。它通过开展引导式访谈并生成包含任务级细节的全面实施计划，解决需求偏移和规划缺漏问题。该系统在整个规划过程中贯彻任务拆分、TDD 要求和风格锚点等最佳实践。”

保持简洁

• 最多 5 句话
• 概述中不要使用项目符号
• 关注业务价值，而非实现细节
• 除非术语属于特定领域且确有必要，否则避免使用行话

里程碑路线图逻辑

提取里程碑信息

对于 milestones.yaml 中的每个里程碑，提取：

必需字段：

• id - 里程碑标识符（m0、m1 等）
• name - 里程碑标题
• description - 里程碑交付的内容
• estimated_duration - 预计耗时
• dependencies - 必须先完成的里程碑

格式要求：

• 按顺序显示里程碑（m0 → m1 → m2...）
• 清晰显示依赖关系
• 从描述的第一行或最重要的成功标准中突出显示“关键交付物”

提取示例：

# From milestones.yaml:
milestones:
  - id: m1
    name: API Foundation
    description: |
      Build core REST API with authentication and authorization.
      Includes user management endpoints and JWT token handling.
    dependencies: [m0]
    estimated_duration: 2 weeks
    success_criteria:
      - All auth endpoints functional
      - JWT tokens properly validated

呈现效果：

### M1: API Foundation
**Duration:** 2 weeks
**Dependencies:** M0
**Key Deliverable:** Core REST API with authentication and authorization

时间线计算

如果存在 timeline.yaml：

• 使用 total_duration 字段
• 使用 production_deploy_date 作为目标完成日期
• 显示计算出的项目日期

如果只有 milestones.yaml：

• 汇总所有 estimated_duration 值
• 转换为合适的单位（天/周）
• 注明这是未计入 QA/PR 时间的估算

如果两者都不存在：

• 标记为“TBD”，并指示运行相应的技能

错误处理

未找到文件

如果预期位置不存在必需文件：

• 检查其他常见位置（将根目录作为备用位置）
• 显示清晰的错误信息，并注明尝试过的确切路径
• 建议使用可生成该文件的 Sherpy 技能

YAML 无效

如果文件存在但无法解析：

• 显示解析错误
• 如果可以获取，显示文件路径和行号
• 建议检查文件格式或重新生成文件

缺少必填字段

如果文件缺少预期字段：

• 使用合理的默认值，或标记为「[未指定]」
• 使用现有数据继续生成摘要
• 在确认输出中注明缺少的字段

输出位置

始终输出到：{base_directory}/summaries/developer-summary.md

如果目录不存在，则创建该目录：

mkdir -p {base_directory}/summaries

与 Sherpy Flow 集成

此技能设计为在 /sherpy-flow 中作为 第 10 步调用。由 sherpy-flow 调用时，它会接收 base_directory 作为参数。它应当：

• 在所有规划产物完成后运行
• 从 base_directory 中有组织的文件夹结构自动发现文件
• 如果可选文件（如时间线）缺失，不要失败
• 在所有文件都存在时，无需用户交互即可生成摘要

示例

请参阅 references/example.md，了解完整的开发者摘要示例。

相关技能

• /executive-summary - 为利益相关者生成执行摘要
• /sherpy-flow - 完整的规划工作流（最后包含此技能）
• /implementation-planner - 生成此技能使用的 milestones.yaml
• /delivery-timeline - 生成此技能使用的 timeline.yaml