常见问题
按主题分组的常见问题与答案。新人可从"基础理解"读起；遇到具体场景可直接跳到对应分组。
基础理解
Spec-First 现在到底是什么？
它是面向 Claude Code 与 Codex 的 Node.js CLI + workflow asset package。CLI 负责安装、初始化、清理、doctor 和 task-pack 校验；宿主 runtime 提供 /spec:* 或 $spec-* workflow 入口。详见 什么是 Spec-First。
Claude Code 和 Codex 的入口一样吗？
意图相近，但语法不同。Claude Code 使用 /spec:* commands，Codex 使用 $spec-* skills。文档中看到入口时，应先确认自己当前使用的宿主。
当前有多少 skills 和 agents？
上游源码内置 42 个 source skill definitions：21 个 command-backed workflow + 2 个 standalone/meta + 19 个 internal-only。Codex init 当前生成 25 个 .agents/skills runtime directories；Claude 和 Codex 都生成 51 个 agent profiles。
Spec-First 的版本号在哪里？
版本号由 npm registry 维护，运行 spec-first --version 查看本机安装版；最新版本见 npmjs.com/package/spec-first。官网不锁定具体版本号。
安装与 Setup
我应该先运行什么？
npm install -g spec-first
spec-first doctor
spec-first init --claude -u <name> --lang zh # 或 --codex详见 安装指南。
初始化后为什么还要 setup？
spec-first init 只生成 host runtime assets。spec-mcp-setup workflow 才负责安装并验证 MCP servers、graph providers、helper CLIs 和项目 setup facts。
Graph bootstrap 是什么？
它是在 setup ready 后运行的 readiness 编译流程，会产出 canonical graph、provider status 和 impact readiness artifacts。下游 plan/work/review workflow 可以使用这些 facts；不可用时应明确降级到 bounded direct repo reads。
Workflow 入口
review 入口是什么？
代码评审使用 /spec:code-review 或 $spec-code-review；文档/计划评审使用 /spec:doc-review 或 $spec-doc-review。不要再把 review 当成单一通用 workflow——旧的 /spec:review 已废弃。
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 与任务系统。
还需要 stage0-context 吗？
当前主路径不再使用旧的 stage0-context 作为入口。请使用 spec-mcp-setup 与 spec-graph-bootstrap。
Project Standards 是什么？
spec-standards 会把项目事实、graph evidence、shared standards 和已有代码约定编译成 .spec-first/standards/ 下的项目规范与 glue capability baseline。它默认 preview-first，不会把 observed 或 imported 候选直接当作 confirmed project policy。详见 Project Standards 指南。
App 一致性审查是什么？
spec-app-consistency-audit 是移动 App 的静态优先审查入口，用于在运行时验证前比较 PRD、Figma context、本地 source、页面路由、架构、组件复用、埋点和 i18n。它不替代自动化测试、模拟器、真机或 QA。详见 App 一致性审查。
Skill audit 是什么？
spec-skill-audit 用于维护 spec-first source skills，审查 trigger、边界、输入输出契约、治理投递、runtime drift、安全信号和改进计划。默认只写 .spec-first/audits/skill-audit/ 执行产物，不直接改 skills/ 或 generated runtime copies。
产物与边界
能不能直接修改 .claude 或 .agents 里的文件？
不建议。.claude/、.codex/、.agents/skills/ 是生成 runtime copies，会被 init/update 覆盖。能力变更应落在上游 skills/、agents/、templates/ 和 src/cli/。详见 产物目录与 Git 边界。
多仓 workspace 下应该在哪里写 .spec-first？
每个 child Git repo 拥有自己的 canonical .spec-first/config/、.spec-first/graph/、.spec-first/impact/ 和 .spec-first/providers/。父 workspace 只能写 .spec-first/workspace/*summary.json advisory summary，不能替代 child repo 的真相源。详见 三种开发模式。
.gitignore 应该怎么配？
spec-first init 从 v1.7.0 起会自动维护 .gitignore 中的 # spec-first:start / # spec-first:end managed block。不需要手写忽略规则；项目额外规则放在 block 外即可。详见 .gitignore 参考。