深入解析地图
这页面向已经跑通过 doctor、init 和第一个 workflow 的读者。它不再重复安装步骤，而是解释 spec-first 为什么这样设计、哪些边界不能混用、哪些证据可以信、哪些判断必须留给 LLM 与人。
核心结论很简单：
Scripts prepare facts. LLM decides.
Source assets generate runtime mirrors.
Workflow artifacts carry evidence forward.阅读路径
| 你想弄清楚 | 推荐先读 | 关键判断 |
|---|---|---|
| spec-first 的底层设计观 | AI Coding Harness | 它不是 prompt collection，而是把 AI coding 放进可治理的工程闭环 |
| CLI、init、runtime 之间的关系 | 运行时治理 | package CLI 负责确定性维护；宿主 workflow 入口由 init 投递 |
| 需求、计划、执行、评审如何衔接 | 工作流系统 | 主链路按当前缺口进入，不是固定状态机 |
| artifact、handoff、verification 为什么重要 | 契约与质量门禁 | 产物必须携带来源、freshness、限制和验证证据 |
| provider、隐私、外部工具能不能当事实源 | 安全与证据边界 | provider evidence 是候选线索，源码/测试/日志仍是确认依据 |
AI Coding Harness
spec-first 把 AI coding 拆成六层 harness，而不是把所有规则塞进一个超级 prompt：
| Harness 层 | 关注点 | 在 spec-first 中的落点 |
|---|---|---|
| Context Harness | 给 AI 正确上下文，不给无限上下文 | bounded direct reads、project guidance、summary-first handoff |
| Execution Harness | 把执行变成可跟踪流程 | spec-plan、task pack、spec-work |
| Evidence Harness | 结论必须能回到证据 | source refs、git diff、测试日志、review findings |
| Evaluation Harness | 记录有没有真的变好 | verification profile、content audit、release gates |
| Governance Harness | 权限、边界、降级和安全 | source/runtime gate、dispatch boundary、provider degraded mode |
| Knowledge Harness | 把经验沉淀给下一轮 | docs/solutions/、compound、compound-refresh |
这也是官网叙事应避免的误区：spec-first 的卖点不是“更多 agent”，而是 agent 的输入、边界、产物和复用路径更可靠。
运行时与 CLI
spec-first package CLI 与宿主 workflow 入口不是同一层：
| 层 | 负责什么 | 典型入口 |
|---|---|---|
| Package CLI | 安装后可直接运行的确定性维护命令 | spec-first doctor、init、update、clean、tasks validate、session |
| Source assets | package 内维护的 skill、agent、template、contract 和 CLI source | skills/（含 skill-local references/agents）、templates/、src/cli/ |
| Runtime mirrors | init 投递到项目内、供宿主加载的副本 | .claude/、.codex/、.agents/skills/ |
| Host workflows | Claude Code / Codex / preview hosts 会话内使用的公开入口 | spec-* |
关键边界：
- 不手改
.claude/、.codex/、.agents/skills/来“修 workflow 行为”；应改 source，再重新init。 spec-first update是 package CLI，不是宿主 workflow；它会升级全局 npm CLI，并尝试重新运行init刷新 runtime。doctor和runtime-setup准备运行事实，不替代需求、架构、review 判断。- 当前产品面统一使用
spec-*；不同宿主的 runtime 投递形态不同，workflow contract 应保持一致。
工作流系统
主链路可以从当前缺口进入：
Codebase -> Spec -> Plan -> Tasks -> Code -> Review -> Knowledge| 当前缺口 | 入口 | 产物或结果 |
|---|---|---|
| 想法多、方向不明 | spec-ideate | 候选方向、取舍理由 |
| WHAT 不清楚 | spec-brainstorm / spec-prd | requirements / PRD-grade change delta |
| HOW 不清楚 | spec-plan | implementation units、风险、验证 |
| 大计划需要可交接 | spec-write-tasks | task pack、dependencies、stop_if、test_focus |
| 已经能执行 | spec-work / spec-debug / spec-optimize | scoped diff、测试/日志/浏览器证据 |
| 需要质量判断 | spec-code-review / spec-doc-review | structured findings、residual risks |
| 问题已解决 | spec-compound / spec-compound-refresh | 可复用 solution docs |
不要把 workflow 误解为强状态机。小改可以直接从 work 或 review 进入；复杂改动才需要从 ideate、brainstorm 或 plan 起步。入口治理的目标是把任务送到当前最缺的层，而不是让每次对话跑完整流程。
契约与质量
spec-first 的产物不是“写给人看的日志”，而是下一步 workflow 可消费的 handoff：
| 契约对象 | 必须回答 |
|---|---|
| Workflow contract | 输入是什么、输出是什么、谁消费、失败时如何降级 |
| Artifact summary | 这份产物说了什么、依据是什么、限制是什么、是否 fresh |
| Task pack | 从哪个 plan 派生、hash 是否匹配、文件边界和 stop_if 是什么 |
| Verification profile | 这次改动应跑哪些检查、哪些通过、哪些未跑以及原因 |
| Review finding | 严重级别、证据、影响面、修复建议和剩余风险 |
质量门禁的重点是防止 fake completion：不能因为 LLM 觉得“应该没问题”就宣称完成。完成声明应回到 source reads、diff、测试、构建、截图、日志或用户提供的证据。
安全与证据边界
外部工具和 provider 只提供候选证据：
- CodeGraph / Graphify / MCP tools 可以帮助定位关系和影响面，但不拥有最终语义权威。
- provider unavailable、stale、blocked 或 degraded 时，应显式说明并回到 direct source reads。
- Slack、session history、release notes 是背景证据，不是当前代码事实。
- 隐私和密钥边界由脚本、deny rules、redaction 和人工判断共同守住；不要把原始敏感数据写入 durable docs。
官网文档在表达 provider 能力时应保持克制：可以说“辅助定位”“候选 evidence”“提高输入质量”，不要说“自动证明”“完整理解代码库”或“替代 review”。
与现有指南的关系
这页是阅读地图，不替代操作指南：
- 首次接入项目：读 安装指南 和 快速开始。
- 想看命令面：读 CLI Reference。
- 想深入 source/runtime 投递：读 运行时治理。
- 想深入 workflow 分工：读 工作流系统。
- 想深入 handoff、verification、质量门禁和安全证据：读 契约与质量门禁。
- 想按 workflow 做事：读 Workflow 命令总览。
- 想判断提交边界：读 产物目录与 Git 边界。
- 想排查失败：读 Troubleshooting。
编辑维护原则
后续官网同步时，把结构化生成产物、源码事实和发布记录当作 输入材料，不要直接变成官网页面。官网文档需要承担运营编辑职责：
- 先按读者任务组织信息，再映射内部模块。
- 只保留可验证、可解释、对使用决策有帮助的内容。
- 保持 source/runtime、script/LLM、provider/source truth 三组边界清晰。
- 对用户可见变化同步
CHANGELOG.md，并跑内容审计和构建检查。