Spec-First

产物目录与 Git 边界 ​

本页说明 Spec-First 常见产物由谁生成、谁读取、是否应提交，以及哪些目录是 generated runtime assets。重点是边界，不是把 workflow 固化成状态机。

核心原则 ​

  • 长期协作知识写入 docs/ 下的 requirements、plans、tasks 和 solutions。
  • CLI、skill、agent、template 的 source truth 位于 src/cli/、skills/、agents/ 和 templates/。
  • .claude/、.codex/ 和 .agents/skills/ 是 generated runtime assets，可由 spec-first init 重建，不应手改。
  • .spec-first/ 下多为 runtime/control-plane facts，通常不提交到 Git。
  • .spec-first/standards/ 中经团队确认需要共享的 reviewable artifacts 可以提交；scratch/raw/cache/logs 不提交。
  • 脚本负责确定性事实和格式校验，LLM 负责需求、取舍、实现和评审判断。

Workflow 文档产物 ​

路径主要生成者主要读取方Git 边界
docs/brainstorms/*-requirements.md$spec-brainstorm / /spec:brainstorm$spec-plan / /spec:plan、doc review、维护者通常提交
docs/plans/*-plan.md$spec-plan / /spec:plan$spec-work / /spec:work、spec-write-tasks、review通常提交
docs/tasks/*-tasks.mdstandalone spec-write-tasks skill$spec-work / /spec:work视团队协作需要提交
docs/solutions/**/*$spec-compound / /spec:compound后续 workflow 和维护者通常提交
CHANGELOG.md执行变更的 agent / 维护者reviewer、release、用户本仓库要求变更同步记录

Generated runtime assets ​

路径生成方式是否 source truth是否手改
.claude/commands/spec/spec-first init --claude否否
.claude/skills/spec-first init --claude否否
.claude/spec-first/workflows/spec-first init --claude否否
.claude/agents/spec-first init --claude否否
.agents/skills/spec-first init --codex否否
.codex/agents/spec-first init --codex否否
.gitignore（managed block）spec-first init --claude|--codex部分仅在 spec-first managed block 之外手改

如果这些目录漂移，修复方式是重新运行对应宿主的 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-mcp-setuphost baseline、graph provider 配置、fallback 能力和 artifact path contract
.spec-first/providers/<provider>/spec-graph-bootstrapprovider 原始日志、状态和 normalized facts
.spec-first/graph/spec-graph-bootstrapcanonical graph readiness facts 和 bootstrap report
.spec-first/impact/spec-graph-bootstrapcontext selection、impact radius、review support 的 capability envelope
.spec-first/workspace/parent workspace advisorychild repo 候选、批量 setup/bootstrap summary 和只读 graph target 建议
.spec-first/standards/spec-standards项目形态、规范候选、shared standards 导入、freshness decision 和 glue/reuse capability baseline
.spec-first/audits/skill-audit/spec-skill-auditskill audit inventory、scorecard、安全/治理/runtime drift 信号和改进计划
.spec-first/app-audit/runs/<run-id>/spec-app-consistency-auditPRD / Figma / source / route / architecture / analytics / i18n 一致性审查证据
.spec-first/workflows/verification/<slug>/verification evidencedoctor 可读取的验证证据
.spec-first/workflows/quality-gates/ai-dev-quality-gate/AI Dev Quality Gate质量门结果与失败主题

这些目录回答“当前机器事实是什么”，不是长期手工维护知识库。若 facts stale、blocked 或 degraded，下游 workflow 应说明限制，并回退到 bounded direct repo reads 或已配置 provider。

Source truth 资产 ​

路径角色修改后通常需要
src/cli/CLI 行为、命令实现、contract 校验单元/集成/smoke 测试，必要时 build
skills/source skill 定义和脚本source 文件检查、contract 测试，必要时 fresh-source eval
agents/source agent 定义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 --claude 或 spec-first init --codex 重建。
  • 父 workspace 下不确定该写哪个 repo：先回到 plan/task scope，让文档写明 target_repo 或 per-unit/per-task target_repo。

阅读下一步 ​