# 已有项目初始化与应用拆分工作流

## 1. 适用范围

适用于已经存在源码、构建文件、模块、接口、数据库对象、任务或部署配置的项目。目标是在保护现有工作区的前提下建立可信项目上下文，识别真实运行与依赖边界，再形成可渐进实施、可回滚的应用拆分方案。

已有目录或模块名称不能直接视为正确应用边界；代码引用也不等于业务所有权。静态源码只能证明当前实现，运行拓扑、流量、数据规模和生产行为仍需配置、日志、部署资料或用户确认支持。

## 2. 输入与保护措施

开始时记录：

- 当前分支、HEAD、staged、unstaged 和 untracked 状态；
- 适用的 `AGENTS.md`、`.craftkit/`、项目说明和贡献规范；
- 构建清单、锁文件、源码根、模块、测试和自动化配置；
- 数据库、消息、缓存、文件、定时任务和外部系统的非秘密元数据；
- 制品、部署单元、环境配置入口和运行依赖；
- 已知问题、迁移限制、兼容窗口和不能变更的范围。

不得读取或记录凭据、完整连接串和生产敏感数据。不能为了扫描而构建、启动、迁移或连接外部环境。

## 3. 执行阶段

### E0：确认成熟项目模式

1. 使用 `init` 只读探测有效源码、构建文件、现有项目资料和代表性入口。
2. 展示“成熟项目”判断、项目根、工作区状态和拟扫描范围。
3. 多仓或多根目录时，先确认本次拆分主体及关联仓库只读范围。
4. 到达 G0，等待用户确认模式、范围和可使用的运行资料。

### E1：保守初始化项目资料

1. 完整读取现有 `AGENTS.md` 与 `.craftkit/`，禁止覆盖未知用户章节。
2. 从构建和锁文件提取语言、框架、精确版本、模块和依赖证据。
3. 读取少量代表性的入口、接口、服务、数据访问和测试文件；多种风格并存时不按数量自动裁决。
4. 展示当前项目事实、冲突、疑似历史结构和待确认项。
5. 用户确认后由 `init` 保守合并项目资料，并验证 JSON、索引和忽略规则。
6. 使用 `guidance` 或手工入口顺序验证一项真实项目规则。

### E2：建立现状基线

从源码和可用运行资料分别建立视图：

- 构建视图：模块、依赖方向、公共库和循环依赖；
- 调用视图：入口、同步调用、异步消息、批处理和人工步骤；
- 数据视图：表、文件、缓存、主数据、写入方和共享访问；
- 部署视图：制品、进程、配置、扩缩容、故障域和发布方式；
- 组织视图：维护团队、变更频率、审批和支持责任；
- 质量视图：测试边界、发布验证、已知风险和观测能力。

每项结论注明证据来源和置信度。无法验证的生产拓扑与流量必须标为待验证。

### E3：建立目标需求基线

1. 使用 `requirements` 区分当前行为、目标行为、必须保持的兼容和范围外事项。
2. 明确拆分动因，例如独立发布、团队自治、容量、故障隔离、安全边界或技术替换。
3. 为拆分目标设置可测指标，例如依赖减少、发布独立性、故障影响范围或迁移窗口，而不是只写“解耦”。
4. 记录必须继续兼容的调用方、数据格式、作业、报表和运维流程。
5. 到达 G1，由用户确认目标、约束、验收和允许改变的边界。

### E4：识别候选边界与阻塞耦合

1. 从业务能力和数据所有权出发提出候选边界，再映射当前模块，而不是按目录直接切分。
2. 为每个候选应用列出入口、核心职责、不负责事项、依赖、数据、任务和部署现状。
3. 识别阻塞拆分的耦合：共享写库、跨模块事务、循环调用、共享会话、共享缓存键、文件约定、定时任务、硬编码配置和公共类中的业务逻辑。
4. 区分必须拆除的耦合、迁移期允许的兼容桥和可以长期保留的公共基础能力。
5. 对证据不足的动态调用、反射、配置路由和外部任务安排专项验证。

### E5：设计目标应用和过渡架构

至少比较以下方案：

- 保持现状，仅加强模块边界；
- 模块化单体并清理依赖；
- 抽取少量高收益独立应用；
- 按多个业务能力逐步形成独立应用。

对推荐方案逐项说明业务收益、数据和事务变化、接口成本、部署与观测成本、团队影响、迁移风险和不采用其他方案的理由。应用拆分清单必须包含职责、不负责事项、契约、数据所有权、运行和安全边界。

过渡架构应明确：

- 旧入口与新入口的流量切换方式；
- 同步接口、事件、批处理或文件交换的适用范围；
- 数据迁移、复制、校验、回放和最终切换责任；
- 迁移期读写权威、兼容适配层和弃用条件；
- 跨边界事务的幂等、补偿、重试和对账方式；
- 发生失败时回到旧路径的条件和数据处置方法。

到达 G2，由用户确认目标边界、过渡架构和明确不拆分的部分。

### E6：细化专项设计

根据批准方案按需执行：

- `design-backend`：目标应用内部模块、服务、事务、异常和观测边界；
- `design-frontend`：前端应用、路由、状态、共享组件和渐进切换边界；
- `design-api`、`prepare-api`：新旧接口、适配层、版本、字段映射和弃用计划；
- `design-db`：数据所有权、结构、双读双写风险、迁移、校验和回滚；
- `design-workflow`：跨应用状态、任务、超时、撤回、补偿和审计。

所有专项设计必须映射回现有调用方和测试，不得只描述目标结构。

### E7：制定渐进迁移计划

使用 `plan-change` 将迁移拆为可独立验证的批次。通常按以下顺序评估，但不得机械套用：

1. 增加观测、契约测试和现状回归基线；
2. 收紧原系统内部模块边界并消除高风险循环依赖；
3. 建立目标应用骨架和兼容适配层；
4. 迁移低风险读取或旁路能力；
5. 迁移写入、任务和数据权威；
6. 分批切换调用方和流量；
7. 完成对账、稳定观察、旧路径下线和资料更新。

每个批次必须记录：前置条件、涉及应用、代码与数据范围、兼容方式、验证、观测窗口、停止条件、回滚步骤和不可逆点。未经额外授权，不执行数据库迁移、环境部署或流量切换。

### E8：形成交付基线

汇总并冻结本轮已批准的：现状事实、目标应用边界、决策记录、专项契约、迁移批次、验证矩阵、风险台账和待确认项。需要后续任务接续时使用 `handoff` 生成交接材料，不把未验证运行行为写成已完成结论。

## 4. 已有项目交付物

- 保守合并并验证的 `AGENTS.md` 与 `.craftkit/` 项目资料；
- 当前模块、调用、数据、部署、组织和质量视图；
- 拆分目标、兼容范围和可测验收指标；
- 候选应用、阻塞耦合和目标应用职责矩阵；
- 目标架构、过渡架构、数据权威和契约清单；
- 分批迁移、验证、观测、停止和回滚计划；
- 未验证运行事实、外部协调项和不可逆操作清单。

## 5. 停止条件

遇到以下情况时暂停：无法区分既有改动与本次产物、关键调用或数据写入方未知、生产运行资料与源码冲突、迁移需要未授权的外部系统访问、存在无法回滚的数据变更、关键调用方未纳入范围，或用户尚未批准对应审批门。

## 6. 可直接复制的总控提示词

```text
请按《已有项目初始化与应用拆分工作流》推进当前项目。先保护现有工作区，使用 init 只读判断成熟项目模式，展示项目根、分支、已有改动、拟扫描范围和运行资料边界，在 G0 等待我确认。确认后保守合并 AGENTS.md 与 .craftkit 项目资料，建立构建、调用、数据、部署、组织和质量现状视图，再使用 requirements 确认拆分动因、兼容范围和可测目标。

基于真实业务能力、调用链、数据写入方和部署单元提出候选应用，识别共享写库、跨模块事务、循环调用、共享会话、缓存、文件和任务耦合。比较保持现状、模块化单体、抽取少量应用和多应用渐进拆分方案，形成目标架构、过渡架构、数据权威、契约、迁移批次、验证、观测、停止和回滚计划。全过程区分源码事实、运行事实、用户确认、项目规则、设计建议和待验证项；不把目录名称直接视为业务边界。只在 G0、G1、G2、G3、业务决策、权限扩大或高风险副作用处暂停。未经我另行授权，不修改业务代码，不连接外部环境，不迁移数据，不部署，不提交，不推送。
```