产物目录与 Git 边界
本页说明 Spec-First 常见产物由谁生成、谁读取、是否应提交，以及哪些目录是 generated runtime assets。重点是边界，不是把 workflow 固化成状态机。
核心原则
- 长期协作知识写入
docs/下的 requirements、plans、tasks 和 solutions。 - CLI、skill、agent、template 的 source truth 位于
src/cli/、skills/（含 skill-localreferences/agents）和templates/。 .claude/、.codex/、.agents/skills/、.cursor/、.kiro/、.qoder/和.opencode/是 generated runtime assets，可由spec-first init重建，不应手改。.spec-first/下多为 runtime/control-plane facts 与 opt-in session advisory records，通常不提交到 Git。- 项目规范应写入
AGENTS.md、CLAUDE.md、docs/contracts/**、README、测试或docs/solutions/**，不要放进 generated runtime 目录。 - 脚本负责确定性事实和格式校验，LLM 负责需求、取舍、实现和评审判断。
Workflow 文档产物
| 路径 | 主要生成者 | 主要读取方 | Git 边界 |
|---|---|---|---|
docs/brainstorms/*-requirements.md | spec-brainstorm | spec-plan、doc review、维护者 | 通常提交 |
docs/plans/*-plan.md | spec-plan | spec-work、spec-write-tasks、review | 通常提交 |
docs/tasks/*-tasks.md | standalone spec-write-tasks skill | spec-work | 视团队协作需要提交 |
docs/solutions/**/* | spec-compound | 后续 workflow 和维护者 | 通常提交 |
CHANGELOG.md | 执行变更的 agent / 维护者 | reviewer、release、用户 | 本仓库要求变更同步记录 |
Generated runtime assets
| 路径 | 生成方式 | 是否 source truth | 是否手改 |
|---|---|---|---|
.claude/commands/spec-*.md | spec-first init（选择 Claude Code） | 否 | 否 |
.claude/commands/spec/ | legacy managed command namespace；仅用于旧资产清理或迁移证据 | 否 | 否 |
.claude/skills/ | spec-first init（选择 Claude Code） | 否 | 否 |
.claude/spec-first/workflows/ | spec-first init（选择 Claude Code） | 否 | 否 |
.claude/agents/ | spec-first init（选择 Claude Code） | 否 | 否 |
.claude/hooks/session-start | spec-first init（选择 Claude Code） | 否 | 否 |
.agents/skills/ | spec-first init（选择 Codex） | 否 | 否 |
.codex/agents/ | spec-first init（选择 Codex） | 否 | 否 |
.gitignore（managed block） | spec-first init | 部分 | 仅在 spec-first managed block 之外手改 |
如果这些目录漂移，修复方式是重新运行 spec-first init 并选择对应宿主，而不是直接编辑 runtime copy。init 会在仓库根 .gitignore 中维护一个 spec-first managed block，把 generated runtime assets 与 control-plane facts 默认排除提交；managed block 之外的规则不会被覆盖。
.spec-first/ control-plane facts
| 目录 | 写入阶段 | 主要作用 |
|---|---|---|
.spec-first/config/ | spec-runtime-setup | host baseline、required MCP、helper readiness、provider opt-in 配置和 artifact path contract |
.spec-first/providers/<provider>/ | provider pack / setup 调试 | opt-in provider 原始日志、状态和 normalized facts；不是默认 source truth |
.spec-first/workspace/ | parent workspace advisory | child repo 候选、批量 setup summary 和只读 target 建议 |
.spec-first/sessions/ | spec-first session CLI | opt-in 多 actor session advisory records，提示同一 worktree 中的并行 agent 活动 |
.spec-first/app-audit/runs/<run-id>/ | spec-app-consistency-audit | PRD / Figma / source / route / architecture / analytics / i18n 一致性审查证据 |
.spec-first/workflows/verification/<slug>/ | verification evidence | doctor 可读取的验证证据 |
.spec-first/workflows/quality-gates/ai-dev-quality-gate/ | AI Dev Quality Gate | 质量门结果与失败主题 |
这些目录回答“当前机器事实是什么”，不是长期手工维护知识库。若 facts stale、blocked 或 degraded，下游 workflow 应说明限制，并回退到 bounded direct repo reads 或已配置 provider。
Provider / Runtime 关键文件
| 文件 | 生成者 | 消费者 | 说明 |
|---|---|---|---|
.spec-first/config/runtime-capabilities.json | spec-runtime-setup | setup/downstream workflows | host ledger pointer、fallback 能力和 readiness projection |
.spec-first/config/provider-artifacts.json | spec-runtime-setup | provider pack / 维护者 | provider artifact path contract |
.spec-first/config/graph-providers.json | spec-runtime-setup | provider pack / 维护者 | required provider command argv 与 package projection；--only 仅表示子集修复 |
.codegraph/codegraph.db | CodeGraph provider | opt-in evidence consumer | CodeGraph 本地数据库，来自 @colbymchenry/codegraph@1.5.0 |
graphify-out/ | Graphify provider | opt-in evidence consumer | 当前 Graphify 项目图谱产物，来自 PyPI graphifyy@0.9.29 |
.graphify/ | Graphify provider (legacy) | opt-in evidence consumer | 旧版 spec-first 适配目录；setup 可在单独存在时迁移到 graphify-out/ |
下游 workflow 不应把 provider-local 缓存当作 source truth。Provider evidence 只能辅助定位；与当前源码、测试、日志或用户证据冲突时，采用已验证的直接事实。
是否可以删除
| 路径 | 可以删除吗 | 删除后如何重建 |
|---|---|---|
.claude/、.codex/、.agents/skills/ | 可以，但会让宿主入口失效 | 重跑 spec-first init 并选择对应宿主 |
.spec-first/config/ | 可以，但 setup facts 会丢失 | 重跑 spec-runtime-setup |
.spec-first/providers/、.codegraph/、graphify-out/、.graphify/（legacy） | 可以，但 opt-in provider evidence 会丢失 | 重新运行显式启用 provider pack 的 setup / provider 命令 |
.spec-first/workspace/ | 可以 | 在父 workspace 重跑 init/setup |
.spec-first/sessions/ | 可以 | 需要 session advisory 时重新运行 spec-first session register |
docs/brainstorms/、docs/plans/、docs/tasks/、docs/solutions/ | 不建议随意删除 | 这些是长期协作文档，删除前应 review |
Source truth 资产
| 路径 | 角色 | 修改后通常需要 |
|---|---|---|
src/cli/ | CLI 行为、命令实现、contract 校验 | 单元/集成/smoke 测试，必要时 build |
skills/ | source skill 定义和脚本 | source 文件检查、contract 测试，必要时 fresh-source eval |
skills/**/references/agents/ | skill-local agent prompt 资产 | source 文件检查、contract 测试，必要时 fresh-source eval |
templates/ | runtime 生成模板 | init / smoke / governance contract 测试 |
docs/ | 协作文档、计划、手册和长期知识 | Markdown link、内容 contract 或相关文档测试 |
tests/ | 回归和 contract 保障 | 对应测试命令 |
选择建议
- 只想记录需求：写
docs/brainstorms/。 - 需要执行前共识：写
docs/plans/。 - 计划很大、需要交接或并行执行：从 plan 派生
docs/tasks/。 - 问题已经解决且经验可复用：写
docs/solutions/。 - runtime 看起来坏了：先判断 source truth 是否正确，再用
spec-first init重建并选择对应宿主。 - 父 workspace 下不确定该写哪个 repo：先回到 plan/task scope，让文档写明
target_repo或 per-unit/per-tasktarget_repo。
阅读下一步
- .gitignore 参考：init 自动维护 managed block 的完整内容
- 运行模型：CLI / runtime / control-plane 三层资产分类
- 三种开发模式：不同 Git 拓扑下的产物边界
- 记忆与知识沉淀：长期文档如何跨会话支撑工作