docs: 增加多应用单仓库判断 (#13)

ila
2026-08-10 19:01:10 +08:00
parent a443c20678
commit 5c187a1d1c
+35
@@ -54,6 +54,39 @@ Agent 在提出方案前只读检查:
- 不把密码、令牌、Cookie、私钥、个人数据或生产数据带入工单、Wiki和镜像。
- 页面删除、重命名、历史清理和事实来源切换必须单独确认。
## 多应用单仓库判断
一个 Git 仓库可以包含多个技术栈不同、能够独立构建和发布的应用或终端。技术栈不同本身不是拆仓理由;先把每个子项目和交付单元记录到 Project-Profile,再根据实际协作边界判断。
### 适合继续单仓库
- 多个应用共同完成一条产品或业务链路;
- 由同一团队维护,仓库权限基本一致;
- 接口变更需要在一个工单中同步修改或验证多端;
- 共享契约、业务规则和任务归档放在一起更容易保持一致;
- 仓库体积、测试时间和工具性能尚未明显影响开发;
- 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。
### 可以考虑拆仓
- 长期由不同团队独立负责并需要不同访问权限;
- 发布周期、版本策略和验收负责人已经完全独立;
- 某个应用被多个产品复用或需要单独对外提供;
- 仓库体积、检出、索引或测试耗时已经持续影响效率;
- 共享接口已经版本化、兼容周期明确,并有跨仓契约测试;
- 跨应用任务很少,拆仓后的协调成本低于继续共仓。
不满足这些条件时,优先保持单仓库并完善边界,不为了目录整洁或技术栈不同而拆仓。
### 保持单仓库时的最小规则
- 根目录 `AGENTS.md` 只放共同流程、安全和跨项目规则,技术栈专用规则写入子目录 `AGENTS.md`。
- 每个交付单元拥有自己的构建、测试、版本和发布方式,不强制统一版本。
- 单元任务必须声明只影响哪个子项目、是否跨子项目、是否修改共享接口,以及各端需要执行的验证。
- 共享接口或契约只能指定一个事实来源;其他文档引用它,不复制一个“差不多”的版本。
- 跨子项目契约变更在同一工单中更新事实来源,并验证所有受影响端。
- 拆仓属于事实来源、任务和发布边界变化,必须另建工单、确认迁移和回退方案后实施。
## 增量接入顺序
### 1. 确认差异方案
@@ -143,6 +176,8 @@ Agent 在提出方案前只读检查:
## 最小验收清单
- [ ] 已盘点规则、文档、任务、Git 历史和未提交改动。
- [ ] 已识别所有子项目和独立交付单元。
- [ ] 跨子项目共享契约已经指定唯一事实来源。
- [ ] 已明确复用、改写、冲突和暂不处理内容。
- [ ] 已保留项目专用规则、历史和无关改动。
- [ ] 未复制 DevHarness 历史归档或模板项目事实。