三种开发模式

Spec-First 的项目边界按 Git 拓扑判断，不按某个 workflow 的临时 mode:* 参数判断。当前可以固定为三种模式。

模式	形态	.spec-first 权威边界	处理方式
单仓单项目	一个 Git repo 就是一个应用、SDK、CLI 或服务	当前 repo root	requirements、plan、work、review、graph facts 都以当前 repo 为边界
单仓多模块	一个 Git repo 中包含多个 app、package、service 或 Android module	同一个 repo root	不为每个 module 拆多套 .spec-first；由 plan、task pack、work 和 review 按 module 边界拆分
多仓工作区	父目录下有多个独立 child Git repos	每个 child repo 自己的 repo root	父 workspace 只做候选发现和 advisory summary；repo-local setup、graph、plan、work、review 必须落到 child repo

单仓单项目

my-app/
  .git/
  .spec-first/
  src/
  docs/

这是最稳定的基础模式。spec-mcp-setup 写 .spec-first/config/*，spec-graph-bootstrap 写 .spec-first/graph/*、.spec-first/providers/* 和 .spec-first/impact/*。后续 plan、work、review 都围绕当前 repo 读取事实和改动。

单仓多模块

platform/
  .git/
  .spec-first/
  packages/
    cli/
    core/
    web/
  services/
    api/
    worker/

这种模式仍然是一个 Git 工程。不要在每个 module 下放一套 .spec-first，否则需求、计划、graph facts 和 review evidence 会分裂。

推荐做法：

• graph providers 覆盖整个 repo，再由 plan/work/review 按 module 边界筛选上下文。
• 大计划在 implementation units 或 task pack 中标清模块边界。
• review 按变更文件和影响面分组，而不是按 .spec-first 目录拆分。

多仓工作区

workspace/
  frontend/
    .git/
    .spec-first/
  backend-api/
    .git/
    .spec-first/
  mobile-app/
    .git/
    .spec-first/

父目录不是统一 Git repo，每个 child repo 都有自己的 canonical facts。父 workspace 可以运行 setup 和 graph bootstrap 做 all-child maintenance，但父目录只写：

.spec-first/workspace/*summary.json

这些 summary 是 advisory facts，不是任何 child repo 的 canonical truth。

常用命令边界

从父 workspace 操作单个 child repo 时，显式传 --repo <child>：

bash skills/spec-mcp-setup/scripts/install-mcp.sh --repo project-a
bash skills/spec-mcp-setup/scripts/verify-tools.sh --repo project-a
bash skills/spec-graph-bootstrap/scripts/bootstrap-providers.sh --repo project-a

无 --repo 的父 workspace setup / graph bootstrap 默认走 all-child maintenance；--all-repos 是显式等价入口。

后续只读代码问题可以使用 workspace-graph-targets.v1 advisory facts 做候选 repo 发现。写文件、修复、测试、review autofix 或 commit 前，仍必须有明确 target_repo 或 per-unit/per-task target_repo。

不要这样理解

• 父目录只有一套 .spec-first 管所有 child repos。
• 父 workspace 自动选择唯一 child repo。
• 普通 plan/work/review 默认跨所有 child repos 写入或测试。
• 父 workspace 的 advisory summary 等同于 child repo 的 canonical graph truth。

阅读下一步

• 产物目录与 Git 边界：每类产物在哪写、由谁写、是否提交
• .gitignore 参考：init 自动维护 managed block 的内容
• 运行模型：CLI / runtime / control-plane 三层资产
• MCP Setup：父 workspace 下 --repo / --all-repos 用法