.gitignore 参考

本页说明把 spec-first 安装到业务项目里之后，哪些产物会自动进入 .gitignore、哪些产物按团队协作策略提交、哪些必须提交。

spec-first init 会在目标项目的 .gitignore 中自动维护一个 # spec-first:start / # spec-first:end managed block。交互式 init 会在写入前展示预览并等待确认；自动化场景使用 -y 明确确认写入。

核心原则

类别	是否提交	理由
.claude/ .codex/ .agents/skills/ .cursor/skills/ .kiro/skills/ .qoder/skills/ .opencode/skills/ 等 generated runtime	不提交	由 spec-first init 重建，不是 source truth
.spec-first/config/ .spec-first/providers/ .spec-first/workspace/ .spec-first/sessions/	不提交	当前机器 readiness/control-plane facts
AGENTS.md CLAUDE.md	提交	宿主入口文档，团队需要
docs/brainstorms/ docs/plans/ docs/tasks/ docs/solutions/ docs/ideation/	提交	长期协作文档

init 默认写入的 managed block

spec-first init 默认在仓库根 .gitignore 中写入：

# spec-first:start
# spec-first generated runtime assets
.claude/commands/spec/
.claude/commands/spec-*.md
.claude/skills/spec-*/
.claude/skills/using-spec-first/
.claude/skills/graphify/
.claude/spec-first/
.claude/agents/spec-*
.claude/hooks/session-start
.claude/hooks/spec-plan-guard
.claude/hooks/prd-prewrite-guard
.claude/hooks/prd-readiness-guard
.claude/tasks/
.claude/worktrees/
.codex/commands/spec/
.codex/commands/spec-*.md
.codex/skills/spec-*/
.codex/skills/using-spec-first/
.codex/skills/graphify/
.codex/spec-first/
.codex/agents/spec-*
.codex/hooks/session-start
.codex/hooks/session-start.cmd
.codex/hooks.json
.agents/skills/spec-*/
.agents/skills/source-command-spec-*/
.agents/skills/using-spec-first/
.agents/skills/graphify/
.cursor/skills/spec-*/
.cursor/skills/using-spec-first/
.cursor/spec-first/
.cursor/mcp.json
.cursor/rules/spec-first.mdc
.kiro/commands/spec/
.kiro/commands/spec-*.md
.kiro/skills/spec-*/
.kiro/skills/using-spec-first/
.kiro/skills/graphify/
.kiro/agents/spec-*
.kiro/spec-first/
.kiro/settings/
.kiro/steering/spec-first.md
.qoder/commands/spec/
.qoder/commands/spec-*.md
.qoder/skills/spec-*/
.qoder/skills/using-spec-first/
.qoder/skills/graphify/
.qoder/agents/spec-*
.qoder/spec-first/
.qoder/hooks/session-start
.qoder/hooks/prd-prewrite-guard
.qoder/hooks/prd-readiness-guard
.qoder/rules/spec-first.md
.qoder/settings.local.json
.opencode/commands/spec/
.opencode/commands/spec-*.md
.opencode/skills/spec-*/
.opencode/skills/using-spec-first/
.opencode/skills/graphify/
.opencode/agents/spec-*
.opencode/spec-first/
.context/spec-first/

# spec-first local setup and workflow runtime artifacts
.spec-first/*.local.yaml
.spec-first/config.local.yaml
.spec-first/config/*.json
.spec-first/audits/
.spec-first/governance/
.spec-first/app-audit/
.spec-first/workflows/
.spec-first/workspace/
.spec-first/sessions/

# provider local artifacts
.codegraph/
.graphify/
graphify-out/
# spec-first:end

不要手改 managed block 内部内容。 你想要的额外规则放在 block 外部即可，下次 init 仍会幂等更新 block 内规则，不会触碰用户自定义部分。

安装后的典型产物树

<repo>/
  AGENTS.md                          # Codex 入口文档，提交
  CLAUDE.md                          # Claude Code 入口文档，提交
  .gitignore                         # 提交（含 spec-first managed block）

  .claude/                           # Claude runtime（generated，忽略）
    commands/spec/
    skills/
    spec-first/workflows/
    agents/
    hooks/session-start
    spec-first/state.json

  .codex/                            # Codex runtime（generated，忽略）
    agents/
    spec-first/state.json

  .agents/skills/                    # Codex workflow skills（generated，忽略）

  .cursor/                           # Cursor generated-runtime preview（忽略）
    skills/
    spec-first/
    mcp.json

  .kiro/                             # Kiro preview runtime（generated，忽略）
    skills/
    agents/
    spec-first/
    settings/

  .qoder/                            # Qoder preview runtime（generated，忽略）
    commands/spec/
    skills/
    agents/
    spec-first/
    settings.local.json

  .opencode/                         # OpenCode runtime（generated，忽略）
    commands/spec/
    skills/
    agents/
    spec-first/

  .spec-first/                       # control-plane（默认忽略）
    config/                          # runtime-setup 写入
    providers/                       # optional provider evidence
    workspace/                       # parent workspace advisory
    sessions/                        # opt-in 多 actor session advisory

  .codegraph/                        # CodeGraph provider-native database（忽略）
  graphify-out/                      # Graphify provider-native 当前输出（忽略）
  .graphify/                         # legacy Graphify 适配目录（忽略）
    cost.json                        # Graphify cost output（managed block 忽略）
    .graphify_python                 # provider hook 本地解释器路径（managed block 忽略）


  docs/                              # 协作文档（提交）
    ideation/*-ideation.md
    brainstorms/*-requirements.md
    plans/*-plan.md
    tasks/*-tasks.md
    solutions/**

简化变体

不使用 .agents/ 自定义内容

如果项目没有自定义的 .agents/plugins/ 等内容，可以把 .agents/skills/ 简化为：

.agents/

但是注意：如果项目同时使用 .agents/plugins/ 等承载团队自定义资产，不要忽略整个 .agents/，只忽略 .agents/skills/。

多仓工作区的特殊处理

spec-first init 在父 workspace 下会尝试发现 child Git repos：默认刷新父级 host runtime assets，并为 child repos 执行项目级初始化，同时在父目录写 advisory summary。写代码、测试、review autofix 或 commit 前，仍必须让 plan/task scope 明确 target_repo。

场景	推荐做法
你在 child repo 内	在该 child 运行 spec-first init，自动维护本 child 的 .gitignore
你在父 workspace 内	运行交互式 spec-first init，在引导中选择全部 child repos 或某一个 child
你只想处理一个 child	在父 workspace 的交互式目标选择里选该 child，或直接进入 child repo 后运行 spec-first init
你要非交互初始化	使用 spec-first init -y 处理当前 cwd 的默认目标；需要 dry-run 或自定义目标选择时使用 programmatic init-plan API

详细多仓边界见 三种开发模式。

幂等更新

init 多次运行时不会破坏 managed block 之外的用户规则；它只会在 # spec-first:start 与 # spec-first:end 之间幂等替换内容。如果你升级 spec-first 后看到 init 输出 "🧹 update .gitignore spec-first managed block"，那是正常的版本同步。

与 init 行为相关命令

命令	作用于 .gitignore
spec-first init	写入或更新 managed block
spec-first init	交互式预览写入计划，确认后写入
spec-first clean --claude / spec-first clean --codex / spec-first clean --cursor / spec-first clean --kiro / spec-first clean --qoder	不修改 .gitignore（保守，避免误删用户规则）

如果运行了 clean 后觉得 managed block 也想清理，可以手动删除 # spec-first:start 到 # spec-first:end 之间的内容，下次再次 init 时它会被重新写入。

阅读下一步

• 产物目录与 Git 边界：每类产物的提交策略详解
• 运行模型：CLI / runtime / control-plane 三层资产分类
• 安装指南：第一次 spec-first init 的完整流程