Menu
SpecForge 内部 steering 技能。用于存量项目、大型代码库或 wiki 过期时建立项目画像、刷新长期上下文，并为后续 work item 提供代码事实基线。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação 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 项目画像；用于新需求或 bugfix 前理解现有架构、刷新 wiki、生成后续 work item 的上下文基线。
SpecForge 测试工程主能力包。用于 sf-verify 在验证前把 requirements、tasks、UI、technical design 和 code review 风险转成可解析 TC/PW 用例、runtime runbook、auth strategy、自动化计划和可归档 evidence。
| 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 中可追溯接受。