Sdlc Project Research

---
name: sdlc-project-research
description: 仅在用户明确要求基于仓库证据生成项目功能能力地图、能力盘点或持久研究包时使用；不要用于普通代码探索、repo onboarding、Git 历史问答或只读解释。
metadata:
  version: "1.0"
  updated: "2026-07-26"
---

# 项目功能能力地图

## 目标

读取一个已有代码项目、配置、文档、`local/` 材料和 git 记录，整理出一份轻量的项目功能能力地图，帮助后续做进展管理、项目汇报、绩效材料和需求范围判断。默认在当前响应中返回结果；只有用户明确要求持久研究包时才创建目录或文件。

核心产物是一张证据表：

```text
项目目标
-> 一级能力域
-> 二级功能组或模块
-> 三级功能点
-> 证据路径
-> 当前状态
-> 下一步
```

在 SDLC manager 协调中，能力地图也是后续 SDLC artifact 的证据入口。需要时可为每个三级功能点追加：

```text
推荐后续材料
推荐下一 skill
traceability seed
handoff 风险
```

这些字段只是路由建议，不代表已经完成 PRD、SRS、SPEC 或 dev handoff。

`sdlc-project-research` 在 SDLC manager 协调中专注于项目功能能力地图和证据入口，不再承载旧产品工程研究包。

当研究用于重建、替换或迁移时，按 `../sdlc-router/references/sdlc-operating-model.md` 把能力地图作为范围决策表的证据输入。不要一次性写完整未来 PRD/SRS/RTM；只把旧能力标成保留、舍弃、改造或存疑，并路由到首波需求包、规格或 handoff。

能力地图要同时覆盖两类内容：

- 当前已经在代码、配置、测试、脚本、文档或运行结果中形成的能力。
- 从 `local/` 材料、roadmap、forward plan、PRD、issue/commit 历史和 git 演进线中能谨慎推断出的后续 L1 / L2 / L3 能力。

后续能力不能写成已完成；只能按证据强度标为 `已规划`、`待验证` 或带 `[推断]` 的条目。

## 边界

这个 skill 只回答：

- 这个项目是做什么的。
- 项目有哪些主要能力域。
- 每个能力域下面有哪些功能组或模块。
- 每个功能组或模块下面有哪些可观察的功能点。
- 每个功能点有哪些代码、文档、配置、测试或命令证据。
- 每个功能点当前处于什么简单状态。
- 每个二级模块下一步最该补什么。
- 从 git 记录和 local 材料看，后续还应该补哪些 L1 / L2 / L3。

默认不输出：

- 产品结构拆解。
- 工作分解。
- 跟踪矩阵。
- 长篇卡点清单。
- 交付成熟度或成熟度等级。
- 详细功能规格卡。
- 部署和运维检查报告。
- 目标变化日志。
- 增量快照。
- 大量表格文件；但用户明确要求 Excel / XLSX / 表格阅读版时，可以额外输出一个 `项目能力表.xlsx`。
- 完成率、权重、评分、排期、负责人、资源估算、成本估算或绩效判断。
- 默认不输出范围决策表；只有用户要重建、替换、迁移，或下游明确需要 scope gate 时才输出范围决策表。

如果用户要把能力地图转成正式需求、规格或研发任务，只在响应中推荐相应 Skill，不自动调用或模仿下游流程。对于 explicit-control Skill，给出精确的 `$codex-next:<skill-name>` 调用并停止等待。打分、汇报话术或绩效评价应作为能力地图完成后的独立请求。

## 安全

- 默认只读扫描。
- 只运行不会破坏项目的命令，例如列文件、读文档、查配置、看入口、跑明确安全的 smoke/test 命令。
- 不删除文件、不改配置、不跑迁移、不重置 Git、不清数据库、不部署，除非用户在这个 skill 之外明确要求。
- 不把原始 token、密钥、密码、私有 URL 或个人数据写进产物；只记录变量名和脱敏示例。
- 如果为了证明证据运行了命令，在相关备注里简短记录命令和结果。

## 输出与持久化

- 默认直接在当前响应中返回简体中文结果，不创建目录、Markdown、CSV 或 XLSX 文件。
- 只有用户明确要求保存、导出或生成持久研究包时，才新建输出目录，优先使用 `./local/项目能力地图-YYYYMMDD/`；如果目录已存在，追加短后缀，避免覆盖旧结果，除非用户明确要求覆盖。
- 持久研究包使用中文文件名：
  - `项目能力摘要.md`
  - `项目功能能力地图.md`
  - `项目能力表.csv`
- 当用户同时要求持久研究包并明确提到 `XLSX`、`Excel`、`工作簿`、`表格阅读版`、`方便阅读的 Excel 版`、`完全汉化 XLSX` 或类似要求时，额外生成：
  - `项目能力表.xlsx`
- CSV 默认使用中文表头，便于直接给人阅读和导入表格工具。
- XLSX 默认使用完全中文工作表名、中文表头、中文说明和中文状态；代码路径、命令、API、配置键等真实标识保留原文。
- 代码路径、命令、包名、API 名、配置键、代码标识符、skill 名和文件扩展名保持原文，不强行翻译。
- 需要给自动化脚本消费时，用户可以另行要求英文文件名或英文表头；默认不要主动输出英文版。

## 状态标签

每个三级功能点只选一个主状态：

| 状态 | 含义 |
|---|---|
| `已规划` | 有目标或计划，但没有找到具体设计或代码证据。 |
| `已设计` | 已有结构、接口、数据模型、模板、路由或方案，但没有看到完整实现。 |
| `已开发` | 已有对应代码或配置。 |
| `可运行` | 能启动、执行或产出可观察结果。 |
| `待验证` | 看起来已经实现，但还需要联调、测试、稳定性或真实使用确认。 |
| `已废弃/重构` | 证据显示该功能点已经废弃、替换或不再按原路径推进。 |
| `未发现证据` | 资料中提到或按项目目标应有，但没有找到支撑证据。 |

不要使用成熟度等级、百分比或“完成了多少”的表达。

## 工作流程

1. 确认目标项目根目录，默认使用当前目录。
2. 确认输出模式：默认在响应中返回；只有用户明确要求持久研究包时才确认并新建输出目录。
3. 只扫描足够支撑能力地图的证据：README、文档、依赖清单、入口文件、路由、接口、模型、服务、页面组件、提示词、工作流、配置、测试、示例、部署文件和近期生成物。
4. 读取 `local/` 下与项目事实、PRD、forward plan、phase gate、roadmap、handoff、status 或验收报告相关的材料；`local/` 常被 `.gitignore` 忽略，不能只看 `git status`。
5. 查看近期和关键 git 记录，例如 `git log --oneline --decorate --max-count 50`、与业务能力相关的 merge/commit 标题，以及必要时的 `git show --stat`；只把能解释能力演进的提交写进证据。
6. 写一句项目目标。优先使用仓库里明确写出的目标；如果是推断，标记 `[推断]` 并说明来源。
7. 按业务能力识别一级能力域，不要机械照搬 `frontend`、`backend`、`scripts` 这类目录名。一般控制在 3-8 个。
8. 在每个一级能力域下识别二级功能组或模块。一般每个一级能力域控制在 3-8 个。
9. 在每个二级功能组或模块下识别三级功能点。一般每个二级模块控制在 2-8 个。三级功能点必须是可观察功能，不要写抽象概念。
10. 把当前能力和后续能力放进同一张表，但必须用状态区分：
   - 代码、测试、配置或可运行命令已经支撑的功能点，按证据选择 `已开发` 或 `可运行`。
   - 设计文档、接口契约、DDL、模板、roadmap 已经定义但未见完整实现的功能点，标为 `已设计` 或 `已规划`。
   - 已有 adapter、smoke 脚本或配置入口，但缺真实联调、live provider、真实数据库或稳定使用证据的功能点，标为 `待验证`。
   - 仅根据 git 演进线、目录结构或相邻材料推断的后续项，在证据或备注中标记 `[推断]`。
11. 为每个三级功能点附证据：
   - 尽量使用具体路径，必要时带行号。
   - 只有推断没有直接证据时，标记 `[推断]` 并写明推断来源。
   - 找不到证据时，标记 `[未知]` 或状态 `未发现证据`。
12. 为每个三级功能点选择一个主状态。
13. 为每个二级模块写一句下一步建议。平铺 CSV 时，同一个二级模块的下一步可以在多行重复。
14. 默认在响应中返回项目摘要、能力地图和可读的扁平能力表，不写文件。
15. 只有用户明确要求持久研究包时，才写这 3 个产物：
    - `项目能力摘要.md`
    - `项目功能能力地图.md`
    - `项目能力表.csv`
16. 如果是重建、替换或迁移场景，用户又明确要求持久化范围材料，才追加一张范围决策表草案或明确说明为什么暂不生成：
   - 保留：旧能力进入新系统。
   - 舍弃：旧能力明确不进入本轮或新系统。
   - 改造：旧能力保留目标但实现、流程、口径或体验变化。
   - 存疑：需要用户确认，使用 `Q-001` 记录。
17. 如果用户明确要求持久研究包和 XLSX / Excel / 工作簿 / 表格阅读版，用同一份 CSV 数据额外生成 `项目能力表.xlsx`，不要让 XLSX 与 CSV 内容漂移。
18. 最后输出简短交付摘要：一级/二级/三级数量、主要证据缺口和 3 句可用于汇报的中文表达；只有实际写盘时才列出产物路径和工作簿结构。

## 默认响应

- 项目目标和核心能力域摘要。
- 可读的一级/二级/三级能力地图。
- 可复制的扁平能力表。
- 证据缺口、后续方向和 3 句汇报表达。

## 持久化产物（仅用户明确要求时）

- `项目能力摘要.md`：项目目标、核心能力域、当前已形成能力、从 git / local 看出的后续能力方向、主要缺口和一句汇报表达。
- `项目功能能力地图.md`：可读的一级/二级/三级能力地图表、按一级能力域汇总说明、后续 L2 / L3 方向、缺口摘要和 3 句汇报表达。
- `项目能力表.csv`：可导入表格工具的平铺能力表，默认表头：

```csv
一级能力域,二级功能组或模块,三级功能点,功能说明,证据路径,当前状态,下一步,备注
```

默认不要创建很多 CSV 文件。

重建、替换或迁移场景可额外输出：

- `范围决策表.md`：旧能力、证据、决策、新 `REQ`、验证方式和备注。它是气闸材料，不是完整 PRD/SRS。

## 可选 XLSX 阅读版（仅持久研究包）

当用户明确要求 XLSX / Excel / 工作簿 / 表格阅读版时，额外输出 `项目能力表.xlsx`。XLSX 是 CSV 的阅读层，不是独立事实源。

默认工作表：

- `阅读说明`：项目名、文件用途、证据来源、后续项标记规则、验证命令和注意事项。
- `状态汇总`：L3 总数、L1 数、L2 数、各状态数量，以及状态标签说明。
- `能力表`：与 `项目能力表.csv` 同内容、同表头、同顺序。
- `L1-L2索引`：按 L1 / L2 聚合 L3 数量和 L2 下一步，便于快速浏览。

格式要求：

- 完全汉化：工作表名、标题、表头、说明、状态说明和备注都用简体中文。
- 首行冻结、开启筛选、自动换行、列宽适合长路径阅读。
- 状态列使用稳定色块，但不要增加评分、完成率、权重或排期字段。
- 如果工作簿使用公式，必须按 spreadsheet / xlsx skill 规则重新计算并确认没有公式错误；如果只是静态表，至少用 `openpyxl` 重新打开检查工作表、行数和表头。
- 默认新建文件，不直接覆盖旧 XLSX，除非用户明确要求。

## 参考文件 / 何时读取

- `references/methodology.md`：当用户问为什么这么设计，或需要检查产物是否又变重时读取。
- `references/project-summary-template.md`：组织项目摘要或持久摘要文件时读取。
- `references/capability-map-template.md`：组织能力地图或持久地图文件时读取。
- `references/csv-output-schema.md`：用户明确要求持久 CSV 时读取。
- `references/xlsx-output-schema.md`：用户明确要求持久 XLSX / Excel / 工作簿 / 表格阅读版时读取。

## SDLC 下游路由

完成项目能力地图后，只在用户需要进入下一阶段时路由：

下表只用于推荐，不自动调用任何 Skill。遇到 explicit-control Skill 时，返回精确 `$codex-next:<skill-name>` 调用并停止等待。

| 后续需求 | 推荐 skill |
|---|---|
| 业务需求、用户需求或产品范围 | `$codex-next:sdlc-requirements-workflow`, `sdlc-prd-workflow` |
| 软件行为要求、验收条件、字段/权限/状态 | `sdlc-srs-workflow` |
| UI/API/Data/Admin/Permission/Directory 规格切片 | `sdlc-spec-slice-writer` |
| 质量、安全、性能、可用性、隐私或合规约束 | `sdlc-nfr-spec` |
| 能力、需求、规格、任务、测试之间的追踪 | `sdlc-requirements-traceability` |
| 已具备规格后的研发任务包 | `sdlc-dev-handoff-planning` |
| 旧系统重建、替换或迁移范围收口 | 范围决策表 -> `$codex-next:sdlc-requirements-workflow` 或首波 `sdlc-dev-handoff-planning` |

如果用户只需要中文项目能力地图，不要额外生成 SDLC 材料。

## 验收标准

- 默认响应使用简体中文且不创建文件。
- 输出包含项目目标，以及一级/二级/三级能力行。
- 一级是能力域，二级是功能组或模块，三级是可观察功能点。
- 三级功能点尽量引用具体证据路径。
- 没有直接证据的内容必须标记 `[推断]` 或 `[未知]`，不能当事实写。
- 后续 L1 / L2 / L3 必须来自 `local/`、roadmap、forward plan、PRD、git 记录或明确推断来源，不能凭空补齐。
- 每个三级功能点只使用允许的中文状态标签。
- 只有用户明确要求持久研究包时，产物才限于 `项目能力摘要.md`、`项目功能能力地图.md`、`项目能力表.csv`；同时明确要求 XLSX 时可额外生成 `项目能力表.xlsx`。
- 如果输出 XLSX，`能力表` 工作表必须与 CSV 行列一致，且工作簿必须能被重新打开。
- 不默认输出工作分解、产品结构拆解、跟踪矩阵、成熟度模型、卡点长分析、规格卡、快照、任务卡或大量表格。
- 不输出完成率、评分、权重、排期、成本、资源估算、负责人分配或绩效判断。
- 密钥和个人数据必须脱敏。