常见问题
按主题分组的常见问题与答案。新人可从"基础理解"读起；遇到具体场景可直接跳到对应分组。
基础理解
Spec-First 现在到底是什么？
它是面向 Claude Code、Codex 与 preview hosts 的 Node.js CLI + workflow asset package。CLI 负责安装、初始化、清理、doctor 和 task-pack 校验；宿主 runtime 提供 spec-* workflow 入口。详见 什么是 Spec-First。
不同宿主的入口一样吗？
当前产品面统一为 spec-* workflow 入口。不同宿主的差异主要在 runtime 投递形态和 preview 成熟度，而不是用户侧要记多套命令名。
当前有多少 skills 和 agents？
上游源码当前对外快照包含 35 个 source skill definitions：17 个 command-backed workflow、14 个 standalone/meta skill，另有 4 个内部 skill 不属于公开 workflow 面。当前 Codex runtime 投递 31 个 .agents/skills directories。Agents 现为 skill-local prompt 资产（skills/**/references/agents/*.md），共 26 个唯一 agent（38 个源文件）；另有 28 个 persona。主发现路径在各 Skill 详情页 的 Agent / Persona 列表；跨 skill 汇总见 Agents 参考。
Spec-First 的版本号在哪里？
版本号由 npm registry 维护，运行 spec-first --version 查看本机安装版；最新版本见 npmjs.com/package/spec-first。官网不锁定具体版本号。
安装与 Setup
我应该先运行什么？
npm install -g spec-first
spec-first doctor
spec-first init详见 安装指南。
初始化后为什么还要 setup？
spec-first init 只生成 host runtime assets。spec-runtime-setup workflow 才负责安装并验证 MCP servers、helper CLIs、项目 setup facts，以及完整 baseline 所需的 CodeGraph / Graphify provider readiness；--only 仅用于高级子集修复。
Provider evidence 是什么？
它是 CodeGraph / Graphify 这类可选 provider 产出的候选证据。当前默认事实链是 bounded direct source reads、rg、ast-grep、git diff、测试日志和用户证据；provider evidence 只能辅助定位，不能替代源码、测试或用户给出的事实。
Workflow 入口
review 入口是什么？
代码评审使用 spec-code-review 或 spec-code-review；文档/计划评审使用 spec-doc-review 或 spec-doc-review。当前 review 按对象拆分入口，不使用单一通用 review workflow。
write-tasks 是命令吗？
不是。spec-write-tasks 是 standalone task-pack handoff skill，不是 spec-first CLI 子命令，也不是 command-backed workflow。task pack 生成后可用 spec-first tasks hash 和 spec-first tasks validate 做结构校验。详见 Task Pack 与任务系统。
MCP setup 和 provider pack 有什么区别？
spec-runtime-setup 准备 host runtime、required MCP servers、helper CLI readiness 和 setup facts。Provider pack 是 setup 中可显式启用的增强证据来源，回答“是否有额外候选证据”；它不改变 source truth。
Project guidance 从哪里来？
项目规范应维护在 AGENTS.md、CLAUDE.md、docs/contracts/**、README、测试和已验证 solution docs 中；provider evidence 只提供可选定位线索。详见 Project Guidance Sources。
App 一致性审查是什么？
spec-app-consistency-audit 是移动 App 的静态优先审查入口，用于在运行时验证前比较 PRD、Figma context、本地 source、页面路由、架构、组件复用、埋点和 i18n。它不替代自动化测试、模拟器、真机或 QA。详见 App 一致性审查。
产物与边界
能不能直接修改 .claude 或 .agents 里的文件？
不建议。.claude/、.codex/、.agents/skills/ 是生成 runtime copies，会被 init 覆盖。能力变更应落在上游 skills/（含 skill-local references/agents）、templates/ 和 src/cli/。详见 产物目录与 Git 边界。
多仓 workspace 下应该在哪里写 .spec-first？
每个 child Git repo 拥有自己的 canonical .spec-first/config/ 和 repo-local source truth。父 workspace 只能写 .spec-first/workspace/*summary.json advisory summary，不能替代 child repo 的真相源。详见 三种开发模式。
.gitignore 应该怎么配？
spec-first init 当前会自动维护 .gitignore 中的 # spec-first:start / # spec-first:end managed block。不需要手写忽略规则；项目额外规则放在 block 外即可。详见 .gitignore 参考。