三种开发模式

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

模式	形态	.spec-first 权威边界	处理方式
单仓单项目	一个 Git repo 就是一个应用、SDK、CLI 或服务	当前 repo root	requirements、plan、work、review 和 runtime setup 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、plan、work、review 必须落到 child repo

单仓单项目

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

这是最稳定的基础模式。spec-runtime-setup 写 .spec-first/config/*，并在完整 setup 中准备 CodeGraph / Graphify baseline。后续 plan、work、review 都围绕当前 repo 读取事实和改动；provider evidence 不可用时回到 bounded direct source reads，但 setup readiness 必须单独标注未完成。

单仓多模块

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

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

推荐做法：

• provider evidence 覆盖整个 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 做 all-child maintenance，但父目录只写：

.spec-first/workspace/*summary.json

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

常用命令边界

从父 workspace 操作单个 child repo 时，显式传 --repo <child>；要批量处理所有 child repos 时显式传 --all-repos：

spec-runtime-setup --repo project-a

spec-runtime-setup --all-repos

无 --repo 的父 workspace setup 默认走 all-child maintenance；--all-repos 是显式等价入口。CLI spec-first init 在父 workspace 下使用交互式目标选择来初始化全部 child 或单个 child。

后续只读代码问题可以使用 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 truth。

阅读下一步

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