Menü
SpecForge 内部 steering 技能。用于存量项目、大型代码库或 wiki 过期时建立项目画像、刷新长期上下文，并为后续 work item 提供代码事实基线。
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Basierend auf der SOC-Berufsklassifikation
| name | steering |
| description | SpecForge 内部 steering 技能。用于存量项目、大型代码库或 wiki 过期时建立项目画像、刷新长期上下文，并为后续 work item 提供代码事实基线。 |
本技能用于理解已有项目。它解决的问题不是“这次需求怎么做”，而是“这个项目现在真实长什么样”。结果写入 .specforge/wiki/，供后续 sf-intake、sf-requirements、sf-tech-design、sf-implement 和 sf-code-review 复用。
Steering 产出的 wiki 必须能作为后续任务入口：不仅写结论，还要写入口路径、关键符号 / 路由、上游下游、测试位置、运行命令和推荐检索词，避免日常 work item 重新全量读取代码。
本阶段必须读取 .specforge/core/standards/code-intelligence.md、.specforge/core/standards/wiki.md 和 .specforge/core/skills/code-intelligence/SKILL.md。
codebase-index.mjs 判断规模并展示扫描模式，让用户选择后再判断是否需要 provider。08-risks.md 或询问用户。node .specforge/core/scripts/codebase-index.mjs --json
node .specforge/core/scripts/codebase-index.mjs --write-report
node .specforge/core/scripts/wiki-hydrate.mjs --from .specforge/work/active/<work-item>/00-steering/codebase-intelligence.md --mode steering --write
node .specforge/core/scripts/wiki-quality.mjs --mode steering
维护 SpecForge 源码仓库时使用：
node core/scripts/codebase-index.mjs --json
node core/scripts/codebase-index.mjs --write-report --report /tmp/specforge-codebase-intelligence.md
node core/scripts/wiki-hydrate.mjs --from /tmp/specforge-codebase-intelligence.md --mode steering --write
node core/scripts/wiki-quality.mjs --mode steering
codebase-index.mjs 会先输出 scan_modes，再检测 code intelligence provider，并在内部运行 codebase-map.mjs 生成 bootstrap map，输出 normalized_context、wiki_seed、provider plan 和可审查 Markdown report。codebase-map.mjs 是 fallback scanner，只提供候选，不直接等于结论。重要结论必须继续读取文件、查询 provider 或由用户确认。
CodeGraph lifecycle、freshness、MCP / CLI 使用、affected tests 和 graph_facts[] 归一化细节由 .specforge/core/skills/code-intelligence/ 维护；steering 只调用它，不在阶段技能中重复维护全部 provider 规则。
| 规模 | 判断信号 | 策略 |
|---|---|---|
| small | 少量源码文件，入口清楚 | 可一次性读入口、配置、核心模块、测试和部署 |
| medium | 多模块或多技术栈，但目录边界清楚 | bootstrap map + rg；有明确模块时用 Repomix 打包模块上下文；可选图谱 provider |
| large | 源码文件很多、单体遗留、多服务、多语言或扫描被截断 | 必须优先使用图谱 / MCP / SCIP 类 provider；无 provider 且无目标模块时暂停 |
先读取 codebase-index.mjs --json 输出的 scan_modes、scan_mode_decision 和 dependency_decision。默认没有用户明确选择时，不要直接安装 provider，也不要展开全仓分析。
如果顶层 status=scan_mode_required，立即停止后续扫描，只向用户展示扫描模式、优缺点和依赖策略并等待选择。不要继续读取或解析 bootstrap.languages、bootstrap.source_roots、bootstrap.candidates，也不要启动 Explore agents。
需要给用户展示摘要时，优先使用 JSON 里的 summary 字段，不要手写脚本猜测 bootstrap 内部字段类型。
必须向用户展示这些模式，让用户自己选：
| 模式 | 适用 | 优点 | 缺点 | 依赖判断 |
|---|---|---|---|---|
baseline-lite | 小项目、快速粗看 | 快、低成本、通常不用新增依赖 | 浅，容易漏跨模块关系 | 不要求 provider |
baseline-standard | 普通存量项目首接入 | 覆盖 wiki 基线，质量和成本均衡 | 大仓库可能需要限定模块 | 默认不强制，必要时可选 Repomix / graph |
baseline-deep | 大型仓库、遗留单体、多服务 | 关系和影响面最完整 | 慢，通常要建索引 | 大型仓库必须先有 graph provider |
change-focused | 已有明确新需求 | 直接服务本次迭代，读取少 | 不建立完整全仓 wiki | 先要目标模块/业务域；graph 视影响面可选 |
bug-focused | 已有 bug、日志、复现路径 | 聚焦链路和回归验证 | 依赖错误线索 | 先要复现/报错路径；graph 视调用链可选 |
用户选择后，重新运行：
node .specforge/core/scripts/codebase-index.mjs --json --scan-mode <mode>
如果是定向模式，优先补充 --module <path> 或 --focus <domain>。
读取 codebase-index.mjs --json 输出，记录：
summaryscan_modes、scan_mode_decision、dependency_decisionstatus、selected_provider、providersnormalized_contextprovider_plan、provider_executionbootstrap.scale、bootstrap.source_files、bootstrap.languagesbootstrap.source_rootsbootstrap.manifests 和关键 package / build 配置bootstrap.candidates.entriesbootstrap.candidates.apibootstrap.candidates.databootstrap.candidates.testsbootstrap.candidates.operations如果 dependency_decision.status=install_required，不要自行展开全仓。先展示安装选择：A. 用户自己安装；B. Agent 辅助安装。用户选择自己安装时，给出当前 OS 的安装、初始化和复查命令后等待；用户选择 Agent 辅助安装时，确认授权后按当前 OS 执行安装命令，再运行 codegraph init -i、codegraph status 和 codebase-index 复查。用户也可以改选 codebase-memory-mcp / CodeGraphContext，或改选轻量/定向扫描模式。
| provider 类型 | 用法 |
|---|---|
| CodeGraph | 本地 SQLite 知识图谱 + MCP；查询 context、trace、impact、callers/callees、affected source/tests；大型项目优先 |
| codebase-memory-mcp / CodeGraphContext | 查询模块、符号、调用链、依赖、入口、影响面；大型项目优先 |
| Repomix | 只在目标模块已限定时生成 context 包；不打包全仓 |
codebase-map.mjs | bootstrap / fallback，提供粗地图和候选路径 |
rg | 在已限定范围内验证事实 |
Provider 输出只能作为证据来源，必须归一成 wiki 当前事实。
如选择 CodeGraph 或其他 graph provider，先运行：
node .specforge/core/scripts/graph-freshness.mjs --json
只有 freshness ready 或已人工读取当前文件验证后，才能把 graph facts 作为高置信证据。
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 |
这个报告是 steering 的中间证据，不是长期 wiki。它用于记录 provider、扫描范围、模块候选、入口候选、风险和 wiki 回写计划。
按模块读取最小文件集：
只记录能证明的关系：
先读取 codebase-intelligence.md 中间证据，再运行 wiki-hydrate 把 wiki_seed、bootstrap_candidates、graph_facts 和人工确认事实写入 .specforge/wiki/：
node .specforge/core/scripts/wiki-hydrate.mjs --from <codebase-intelligence.md> --mode steering --write
node .specforge/core/scripts/wiki-quality.mjs --mode steering
| 文件 | 内容 |
|---|---|
01-project-overview.md | 项目目标、主要用户、核心能力、明确边界、常见任务入口 |
03-architecture.md | 架构形态、模块/服务划分、入口、依赖、关键链路、追踪路径 |
module-<name>.md | 模块职责、入口文件、上下游、测试、推荐检索词和风险 |
api-<domain>.md | API 域、路由、鉴权、请求响应、错误约定、实现路径和调用方 |
external-interfaces.md | 对外接口总览：API、Webhook、CLI、SDK、文件导入导出、第三方调用、事件消息 |
config-env.md | 配置源、环境变量、secret、feature flag 和配置风险 |
security-auth.md | 认证、授权、权限和敏感数据边界 |
jobs-events.md | 后台任务、队列、事件、定时任务、retry / DLQ |
04-data-model.md | 当前数据权威、当前实体 / 表、迁移初始化、历史 / 未受信 SQL、数据生命周期 |
05-operations.md | 本地启动、构建、测试、部署、CI、环境变量、验证入口 |
06-decisions.md | 已确认的长期决策 |
07-glossary.md | 领域术语、缩写、系统内命名 |
08-risks.md | 技术债、未知区、冲突事实、待用户确认项 |
00-index.md | 当前 wiki 索引和摘要 |
Wiki 中每一项保持单文件、当前态。不要创建 architecture-v2.md、module-x-20260518.md 这类过程文件。
写入或刷新 wiki 后运行 node .specforge/core/scripts/wiki-quality.mjs --mode steering。FAIL 必须修复；WARN 必须补齐当前事实、source work、owner、更新时间，或在 08-risks.md 记录缺口、影响和下一步证据来源。
写入前按 .specforge/core/standards/wiki.md#最低完整度 自检。以下情况不能直接完成：
| 不完整表现 | 必须补扫 |
|---|---|
| 架构只有技术栈，没有模块边界 | source roots、manifest、入口、路由、服务目录、部署文件 |
| API 只有“有接口” | route、controller、OpenAPI、SDK、测试、调用方 |
| 数据模型只有“使用数据库” | schema、model、migration、repository、SQL、fixture、测试 |
| 模块只有目录名 | 入口、职责、上游、下游、数据读写、测试位置 |
| 运维只有启动命令 | env、构建、测试、DB 初始化、任务、部署、回滚、日志监控 |
补扫后仍无法确认的，目标 wiki 写 未确认，并在 08-risks.md 写清缺口、已扫范围和下一步证据来源。
可参考成熟工具的思想，但不要把它们的输出原样变成 SpecForge 事实：
| 工具思路 | 可借鉴点 | SpecForge 落地 |
|---|---|---|
| Aider repo map | 用 Tree-sitter / 符号 / 依赖关系在 token 预算内选上下文 | codebase-map 先给粗地图；后续按模块选文件 |
| Repomix / Gitingest | 生成 prompt-friendly 代码包和 token 分布 | 只用于小范围模块包，不用于全仓长期事实 |
| CodeGraph / CodeGraphContext / codebase-memory-mcp | 图谱、MCP、依赖、调用、影响面和文档层 | 大项目首选，结果归一到 wiki |
| RepoAgent | 自动生成和维护仓库文档 | 可借鉴“先全局结构，再增量维护”的机制 |
sf-steering 建立 wiki 基线，再 sf-intake 创建新 work item。sf-steering 可用 change-focused 模式只理解相关模块，然后把结果交给 sf-intake。sf-steering 可用 bug-focused 模式理解复现路径和调用链，然后由 sf-intake 创建 bugfix 或 issue。sf-wiki 或 sf-close 读取本技能，补齐当前事实。01-project-overview.md 和 03-architecture.md。module-<name>.md。03-architecture.md、04-data-model.md、05-operations.md、external-interfaces.md 和必要的 api-<domain>.md 达到最低完整度；不足项进入 08-risks.md。wiki-hydrate --mode steering --write 已执行，wiki_seed 中的候选已回写或记录缺口。wiki-quality.mjs --mode steering 无 FAIL；WARN 已修复或在 08-risks.md 中可追溯接受。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 项目画像；用于新需求或 bugfix 前理解现有架构、刷新 wiki、生成后续 work item 的上下文基线。
SpecForge 测试工程主能力包。用于 sf-verify 在验证前把 requirements、tasks、UI、technical design 和 code review 风险转成可解析 TC/PW 用例、runtime runbook、auth strategy、自动化计划和可归档 evidence。