Menú
为存量项目或大型代码库建立 SpecForge 项目画像；用于新需求或 bugfix 前理解现有架构、刷新 wiki、生成后续 work item 的上下文基线。
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
SpecForge requirements 主能力包。用于把 brief、brainstorm、PRD、research、gap report、wiki 当前事实和用户确认转成可测试、可追踪、可交给 UI / technical design / tasking / verification 的 REQ / AC / NFR / 边界 / handoff 行为契约。
生成或更新 SpecForge 工作项的需求规格；用于活跃工作项的 ready artifact 为 requirements，或需要把产品需求文档 / 简报转成可测试行为、边界、用户故事、验收标准和影响面标记时。
SpecForge 内部需求技能。用于为 work item 生成清晰、可测试的功能需求、非功能需求、范围边界、不在范围内和验收标准。
SpecForge 跨阶段代码智能能力包。用于任何阶段需要 Wiki-first 定位现有代码范围、选择 CodeGraph / MCP / SCIP / Repomix / rg、检查 provider freshness、归一 graph_facts、分析影响面 / affected tests 或生成 Wiki 回写候选时必读；不要只在 sf-steering 中使用。
SpecForge 测试工程主能力包。用于 sf-verify 在验证前把 requirements、tasks、UI、technical design 和 code review 风险转成可解析 TC/PW 用例、runtime runbook、auth strategy、自动化计划和可归档 evidence。
SpecForge 本地代码审查主能力包。用于 sf-code-review 执行 code_review gate 前，对照 approved spec、tasks、implementation report、changed-files、真实 git diff 和验证证据审查实现是否可批准；每次使用前读取本入口，并按风险读取 references。
| name | sf-steering |
| description | 为存量项目或大型代码库建立 SpecForge 项目画像；用于新需求或 bugfix 前理解现有架构、刷新 wiki、生成后续 work item 的上下文基线。 |
执行任何 node .specforge/... 命令或读取 .specforge/... 文件前，必须先定位宿主项目根：项目根是“包含 .specforge/ 目录的业务项目目录”，不是 .specforge/ 目录本身。若当前目录是 .specforge/ 或其任意子目录，先 cd .. 回到宿主项目根；若当前目录是 frontend/、backend/ 等子目录，也先向上回到包含 .specforge/ 的项目根，除非该子目录就是独立仓库根。禁止从 .specforge/ 内执行 node .specforge/core/scripts/...，否则会形成 .specforge/.specforge/... 的错误路径。
sf-steering 用来理解存量项目。它不写业务代码，也不创建普通需求产物；它先建立可复用的项目画像，并把稳定事实回写到 .specforge/wiki/*.md。后续 sf-intake、sf-requirements、sf-tech-design、sf-implement 才能基于这些事实做新需求、bugfix 或重构。
Steering 的产出必须能降低后续 token 成本：wiki 不只写“项目是什么”，还要写“下次从哪里开始查”。架构、模块、API、数据和运维文件都要尽量包含入口路径、关键符号 / 路由、上游下游、测试位置、运行命令和推荐检索词。
.specforge/wiki/03-architecture.md 仍是空模板。node .specforge/core/scripts/doctor.mjs
node .specforge/core/scripts/codebase-index.mjs --json
Steering 需要代码智能时，先读取跨阶段能力包：
.specforge/core/skills/code-intelligence/SKILL.md
正式建立项目画像时，先生成可审查的中间证据报告：
node .specforge/core/scripts/codebase-index.mjs --write-report
有 active work item 时，默认写入：
.specforge/work/active/<work-item>/00-steering/codebase-intelligence.md
没有 active work item 时，默认写入：
.specforge/work/inbox/codebase-intelligence.md
wiki 写入或刷新完成后运行：
node .specforge/core/scripts/wiki-hydrate.mjs --from <codebase-intelligence.md> --mode steering --write
node .specforge/core/scripts/wiki-quality.mjs --mode steering
FAIL 必须修复；WARN 必须补齐当前事实、source work、owner、更新时间，或在 08-risks.md 写明缺口、影响和下一步证据来源。
读取内部阶段说明：
.specforge/skills/sf-steering/stages/steering/SKILL.md
codebase-index.mjs 会检测 code intelligence provider，并在内部运行 codebase-map.mjs 生成 bootstrap map，还会输出 normalized_context、wiki_seed 和 provider 执行 / 查询计划。codebase-map.mjs 只是 fallback scanner，不等于符号级理解。结论必须来自代码、配置、测试、CI、现有文档、provider 查询结果或用户确认。CodeGraph 安装、接入、freshness、query、affected tests 和 graph_facts[] 归一化细节统一以 .specforge/core/skills/code-intelligence/ 为准。
按代码规模和用户目标选择模式：
| 模式 | 适用场景 | 处理方式 |
|---|---|---|
baseline-lite | 小项目，代码量少，模块清晰 | 读取入口、配置、主要模块、测试和部署文件，直接更新核心 wiki |
baseline-standard | 中型项目或普通存量项目首接入 | codebase-index + rg，必要时用 Repomix 打包目标模块，再更新项目概览、架构、数据、运行、风险 |
baseline-deep | 大型项目、单体遗留系统、多服务仓库 | 必须优先使用图谱 / MCP / SCIP 类 provider；无 provider 且无目标模块时暂停 |
change-focused | 用户已有明确新需求 | 只理解相关模块和上下游，输出“本次变更上下文基线”，再路由 sf-intake |
bug-focused | 用户已有异常或 bug | 先理解复现路径、调用链、相关模块、日志和测试，再路由 sf-intake 或 sf-discovery |
不要把大型仓库直接打包进上下文。采用 provider 优先策略：
codebase-index.mjs --json，先读取 scan_modes、scan_mode_decision、dependency_decision 和 bootstrap.scale。
status=scan_mode_required，立即停止后续扫描，只展示扫描模式并等待用户选择。bootstrap.languages、bootstrap.source_roots 或启动 Explore agents。summary 字段。rg + 关键文件阅读足够。rg；有明确模块时可用 Repomix 生成模块上下文包，不打包全仓。baseline-lite、baseline-standard、baseline-deep、change-focused 或 bug-focused。baseline-deep 后，再让用户选择自己安装 provider、Agent 辅助安装、改选 provider 或改选扫描模式。成熟开源工具的做法可以作为参考：Aider 的 repo map、Repomix/Gitingest 的代码打包、CodeGraph / CodeGraphContext / codebase-memory-mcp 的图谱与 MCP 检索、RepoAgent 的文档生成。但在 SpecForge 中，外部工具输出只能作为证据来源，最终必须改写成 .specforge/wiki/*.md 的当前事实。
sf-steering 不再内置全部 CodeGraph 细节。检测到 codegraph CLI、用户明确启用 CodeGraph，或扫描模式需要 graph provider 时，按顺序读取：
.specforge/core/skills/code-intelligence/references/workflow-playbook.md.specforge/core/skills/code-intelligence/references/provider-and-freshness.md.specforge/core/skills/code-intelligence/references/graph-facts-contract.md.specforge/core/skills/code-intelligence/references/wiki-and-output-contract.mdSteering 只负责项目画像和 Wiki 回写；provider 的安装 / 接入 / 初始化 / 同步 / query / affected tests 规则由 code-intelligence 能力包统一维护。
先读取 codebase-intelligence.md 报告，再用 wiki-hydrate --mode steering --write 把其中的 wiki_seed 和已验证当前事实归一写入 wiki。不要把 provider 原始输出、Repomix 包或报告全文直接复制进 wiki。
根据实际发现更新这些文件；不需要的文件保持不动：
| 文件 | 写入内容 |
|---|---|
.specforge/wiki/01-project-overview.md | 项目目标、主要用户、核心能力、边界、常见任务入口 |
.specforge/wiki/03-architecture.md | 架构形态、服务/模块划分、入口、关键依赖、主要追踪路径 |
.specforge/wiki/module-<name>.md | 单个模块职责、入口、依赖、关键文件、测试位置、推荐检索词 |
.specforge/wiki/api-<domain>.md | API 域、路由、请求响应、鉴权、错误约定、实现路径和调用方 |
.specforge/wiki/external-interfaces.md | 对外接口总览：API、Webhook、CLI、SDK、文件导入导出、第三方调用、事件消息 |
.specforge/wiki/config-env.md | 配置源、环境变量、secret、feature flag 和配置风险 |
.specforge/wiki/security-auth.md | 认证、授权、权限和敏感数据边界 |
.specforge/wiki/jobs-events.md | 后台任务、队列、事件、定时任务、retry / DLQ |
.specforge/wiki/04-data-model.md | 当前数据权威、当前实体 / 表、迁移初始化、历史 / 未受信 SQL、数据生命周期 |
.specforge/wiki/05-operations.md | 本地启动、构建、测试、部署、CI、环境变量、验证入口 |
.specforge/wiki/06-decisions.md | 已确认的架构或产品决策 |
.specforge/wiki/07-glossary.md | 领域术语、缩写、系统内命名 |
.specforge/wiki/08-risks.md | 技术债、风险点、未知区、需用户确认项 |
.specforge/wiki/00-index.md | 当前 wiki 索引和摘要 |
Wiki 只保留当前事实。不要按日期、版本或 work item 复制多份同类文档。
存量项目画像不能只写“这是一个前后端项目”这类概述。写入前必须按 .specforge/core/standards/wiki.md#最低完整度 自检。
重点补扫：
| 不完整表现 | 必须补扫 |
|---|---|
| 架构只有技术栈，没有模块边界 | source roots、package / build 配置、入口、路由、服务目录、部署文件 |
| API 只有“有接口” | route / controller / OpenAPI / SDK / test / caller，先更新 external-interfaces.md，必要时创建 api-<domain>.md |
| 数据模型只有“使用数据库” | schema / model / migration / repository / runtime config / fixture / test，先确认当前数据权威；历史 SQL 只能进入历史 / 未受信 SQL 章节 |
| 模块只有目录名 | 入口、职责、上游、下游、数据读写、测试位置，必要时创建 module-<name>.md |
| 运维只有启动命令 | env、构建、测试、DB 初始化、任务、部署、回滚、日志监控 |
如果补扫后仍无法确认，不要略过：在目标 wiki 写 未确认，并在 08-risks.md 记录“缺口 / 已扫范围 / 下一步证据来源”。
.specforge/core/standards/code-intelligence.md：provider 优先级、规模策略和大型项目停止条件。.specforge/core/standards/wiki.md：wiki 单文件当前态、事实回写和未知项记录。.specforge/core/standards/workflow.md：上下文加载、暂停条件和下一步路由。完成后输出：
wiki-quality.mjs 结果和剩余缺口。sf-intake；如果用户只是要求项目画像，则停在这里。codebase-index.mjs 显示 scan_mode_required，且用户尚未选择扫描模式。dependency_decision.status=install_required，且用户尚未选择自己安装、Agent 辅助安装、改选模式或指定目标范围。.specforge/wiki/ 至少包含当前项目概览和架构概览。03-architecture.md、04-data-model.md、05-operations.md、external-interfaces.md 和必要的 api-<domain>.md / module-<name>.md 达到最低完整度；缺口进入 08-risks.md。sf-intake 能引用 wiki 判断影响面，不必重新理解全仓库。08-risks.md 或在输出中列为待确认，不混入当前事实。wiki-hydrate --mode steering --write 已执行，wiki_seed 已回写或记录缺口。wiki-quality.mjs --mode steering 无 FAIL；WARN 已修复或在 08-risks.md 中记录 owner、影响和下一步证据来源。