sdlc-project-research

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

项目功能能力地图

目标

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

核心产物是一张证据表：

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

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

推荐后续材料
推荐下一 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 文件。

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

• 范围决策表.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 行列一致，且工作簿必须能被重新打开。
• 不默认输出工作分解、产品结构拆解、跟踪矩阵、成熟度模型、卡点长分析、规格卡、快照、任务卡或大量表格。
• 不输出完成率、评分、权重、排期、成本、资源估算、负责人分配或绩效判断。
• 密钥和个人数据必须脱敏。