.gitignore 参考

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

从 v1.7.0 起，spec-first init --claude|--codex 会在目标项目的 .gitignore 中自动维护一个 # spec-first:start / # spec-first:end managed block。init --dry-run 可以预览这次写入但不修改文件系统。

核心原则

类别	是否提交	理由
.claude/ .codex/ .agents/skills/ 等 generated runtime	不提交	由 spec-first init 重建，不是 source truth
.spec-first/config/ .spec-first/graph/ .spec-first/providers/ .spec-first/impact/ .spec-first/workspace/	不提交	当前机器 readiness/control-plane facts
.spec-first/standards/ 中 confirmed baseline	可提交	项目级规范源，团队需要复用
.spec-first/standards/work/、tmp/、cache/、raw/	不提交	派生/临时
AGENTS.md CLAUDE.md	提交	宿主入口文档，团队需要
docs/brainstorms/ docs/plans/ docs/tasks/ docs/solutions/ docs/ideation/	提交	长期协作文档
.serena/	不提交	本地代码索引器状态

init 默认写入的 managed block

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

# spec-first:start
# spec-first generated runtime assets
.claude/commands/spec/
.claude/skills/
.claude/spec-first/
.claude/agents/
.claude/tasks/
.claude/worktrees/
.codex/commands/spec/
.codex/spec-first/
.codex/agents/
.agents/skills/
.context/spec-first/

# spec-first local setup, graph readiness, and workflow runtime artifacts
.spec-first-graph/
.spec-first/*.local.yaml
.spec-first/config.local.yaml
.spec-first/config/*.json
.spec-first/audits/
.spec-first/app-audit/
.spec-first/graph/
.spec-first/providers/
.spec-first/impact/
.spec-first/workflows/
.spec-first/workspace/
.spec-first/standards/work/
.spec-first/standards/tmp/
.spec-first/standards/cache/
.spec-first/standards/raw/
.spec-first/standards/graph-query-raw/
.spec-first/standards/**/*.log
.spec-first/standards/repo-profile.patch.yaml

# local project tooling used by spec-first workflows
.serena/
# 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/
    spec-first/state.json

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

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

  .spec-first/                       # control-plane（默认忽略）
    config/                          # mcp-setup 写入
    providers/                       # graph-bootstrap 写入
    graph/                           # canonical graph readiness
    impact/                          # capability envelope
    standards/                       # 规范 baseline（部分可提交）
    workspace/                       # parent workspace advisory

  .serena/                           # 本地代码索引器状态（忽略）

  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/。

Standards baseline 全部本地化

如果团队明确决定 standards baseline 只保留在本地，不进 Git，可以把 .spec-first/standards/ 整目录忽略：

.spec-first/standards/

但默认推荐：confirmed standards 应该提交，team 复用。

多仓工作区的特殊处理

spec-first init 不会递归处理多仓 workspace 里的所有 child repo。它只维护当前运行目录的 .gitignore。

场景	推荐做法
你在 child repo 内	在该 child 运行 spec-first init，自动维护本 child 的 .gitignore
你在父 workspace 内	父 workspace 只承载 advisory summary（.spec-first/workspace/）；正式 init 应在每个 child 内单独运行

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

幂等更新

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

与 init 行为相关命令

命令	作用于 .gitignore
spec-first init --claude|--codex	写入或更新 managed block
spec-first init --dry-run	预览写入，不修改文件系统
spec-first clean --claude|--codex	不修改 .gitignore（保守，避免误删用户规则）

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

阅读下一步

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