| 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 或类似要求时，额外生成：
- CSV 默认使用中文表头，便于直接给人阅读和导入表格工具。
- XLSX 默认使用完全中文工作表名、中文表头、中文说明和中文状态；代码路径、命令、API、配置键等真实标识保留原文。
- 代码路径、命令、包名、API 名、配置键、代码标识符、skill 名和文件扩展名保持原文，不强行翻译。
- 需要给自动化脚本消费时，用户可以另行要求英文文件名或英文表头；默认不要主动输出英文版。
状态标签
每个三级功能点只选一个主状态：
| 状态 | 含义 |
|---|
已规划 | 有目标或计划，但没有找到具体设计或代码证据。 |
已设计 | 已有结构、接口、数据模型、模板、路由或方案，但没有看到完整实现。 |
已开发 | 已有对应代码或配置。 |
可运行 | 能启动、执行或产出可观察结果。 |
待验证 | 看起来已经实现，但还需要联调、测试、稳定性或真实使用确认。 |
已废弃/重构 | 证据显示该功能点已经废弃、替换或不再按原路径推进。 |
未发现证据 | 资料中提到或按项目目标应有，但没有找到支撑证据。 |
不要使用成熟度等级、百分比或“完成了多少”的表达。
工作流程
- 确认目标项目根目录，默认使用当前目录。
- 确认输出模式：默认在响应中返回；只有用户明确要求持久研究包时才确认并新建输出目录。
- 只扫描足够支撑能力地图的证据：README、文档、依赖清单、入口文件、路由、接口、模型、服务、页面组件、提示词、工作流、配置、测试、示例、部署文件和近期生成物。
- 读取
local/ 下与项目事实、PRD、forward plan、phase gate、roadmap、handoff、status 或验收报告相关的材料；local/ 常被 .gitignore 忽略，不能只看 git status。
- 查看近期和关键 git 记录，例如
git log --oneline --decorate --max-count 50、与业务能力相关的 merge/commit 标题，以及必要时的 git show --stat；只把能解释能力演进的提交写进证据。
- 写一句项目目标。优先使用仓库里明确写出的目标；如果是推断，标记
[推断] 并说明来源。
- 按业务能力识别一级能力域，不要机械照搬
frontend、backend、scripts 这类目录名。一般控制在 3-8 个。
- 在每个一级能力域下识别二级功能组或模块。一般每个一级能力域控制在 3-8 个。
- 在每个二级功能组或模块下识别三级功能点。一般每个二级模块控制在 2-8 个。三级功能点必须是可观察功能，不要写抽象概念。
- 把当前能力和后续能力放进同一张表，但必须用状态区分：
- 代码、测试、配置或可运行命令已经支撑的功能点，按证据选择
已开发 或 可运行。
- 设计文档、接口契约、DDL、模板、roadmap 已经定义但未见完整实现的功能点，标为
已设计 或 已规划。
- 已有 adapter、smoke 脚本或配置入口，但缺真实联调、live provider、真实数据库或稳定使用证据的功能点，标为
待验证。
- 仅根据 git 演进线、目录结构或相邻材料推断的后续项，在证据或备注中标记
[推断]。
- 为每个三级功能点附证据：
- 尽量使用具体路径，必要时带行号。
- 只有推断没有直接证据时，标记
[推断] 并写明推断来源。
- 找不到证据时，标记
[未知] 或状态 未发现证据。
- 为每个三级功能点选择一个主状态。
- 为每个二级模块写一句下一步建议。平铺 CSV 时，同一个二级模块的下一步可以在多行重复。
- 默认在响应中返回项目摘要、能力地图和可读的扁平能力表，不写文件。
- 只有用户明确要求持久研究包时，才写这 3 个产物：
项目能力摘要.md项目功能能力地图.md项目能力表.csv
- 如果是重建、替换或迁移场景，用户又明确要求持久化范围材料，才追加一张范围决策表草案或明确说明为什么暂不生成：
- 保留：旧能力进入新系统。
- 舍弃：旧能力明确不进入本轮或新系统。
- 改造：旧能力保留目标但实现、流程、口径或体验变化。
- 存疑：需要用户确认，使用
Q-001 记录。
- 如果用户明确要求持久研究包和 XLSX / Excel / 工作簿 / 表格阅读版，用同一份 CSV 数据额外生成
项目能力表.xlsx，不要让 XLSX 与 CSV 内容漂移。
- 最后输出简短交付摘要：一级/二级/三级数量、主要证据缺口和 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 行列一致，且工作簿必须能被重新打开。
- 不默认输出工作分解、产品结构拆解、跟踪矩阵、成熟度模型、卡点长分析、规格卡、快照、任务卡或大量表格。
- 不输出完成率、评分、权重、排期、成本、资源估算、负责人分配或绩效判断。
- 密钥和个人数据必须脱敏。
