docs(workflow): 增加项目初始化到应用拆分流程

2026-08-31 13:18:52 +08:00
parent 5d7a77b8ba
commit 426b6cea2a
4 changed files with 372 additions and 1 deletions
@@ -0,0 +1,124 @@
+# 新项目初始化与应用拆分工作流
+
+## 1. 适用范围
+
+适用于空目录、新建仓库，或只有需求、原型和少量说明材料、尚未形成有效源码与构建结构的项目。目标是先建立可信项目上下文，再从已确认需求推导应用边界和实施计划。
+
+本流程不默认选择微服务、前后端框架、数据库、消息系统、云平台或最新版本。`init` 只创建 Agent 与项目知识资料；代码工程初始化属于后续实施任务。
+
+## 2. 输入与前置确认
+
+开始时收集并确认：
+
+- 项目根目录和 Git 状态；
+- 项目用途、目标用户、交付形态和预期运行环境；
+- 需求、原型、会议材料和验收要求；
+- 已确定的语言、框架、数据库、构建工具及精确版本；
+- 组织标识、包名或 npm scope 等必须提前确定的标识；
+- 允许参考的项目，以及只允许借鉴的架构、依赖、命名、测试、规范或工具范围；
+- 安全、合规、容量、可用性、交付期限和团队边界。
+
+未知信息保持为空或标记待确认，不能用流行方案自动补齐。
+
+## 3. 执行阶段
+
+### N0：确认空项目模式
+
+1. 使用 `init` 只读检查源码、构建文件、`AGENTS.md` 和 `.craftkit/`。
+2. 展示“空项目”判断、证据、项目根和允许扫描的参考材料。
+3. 到达 G0，等待用户确认模式和参考范围。
+
+### N1：建立项目上下文
+
+1. 确认项目类型、交付形态、技术选型的已决项和未决项。
+2. 如存在参考项目，分别记录当前项目输入事实、参考项目做法和建议采用项。
+3. 预览拟创建的 `AGENTS.md`、`.craftkit/project.json`、`.craftkit/README.md`、必要索引与 `.craftkit/.gitignore`。
+4. 用户确认后由 `init` 创建最小资料骨架，不提前生成空业务目录。
+5. 校验 JSON、索引链接，以及 `/local/`、`/cache/` 的忽略规则；用 `guidance` 或手工入口顺序验证一次真实规则查询。
+
+### N2：建立需求基线
+
+1. 使用 `requirements` 整理角色、场景、触发条件、主流程、异常流程、数据、权限、兼容和范围外事项。
+2. 为需求分配稳定编号，并为关键场景编写可测试验收标准。
+3. 将技术偏好与业务约束分开；只有影响目标或验收的技术条件才进入需求基线。
+4. 到达 G1，由用户确认需求、范围和暂时保留的业务待决项。
+
+### N3：形成业务能力地图
+
+按业务目标而不是技术分层拆解能力：
+
+1. 识别核心域、支撑能力、通用能力和外部系统责任。
+2. 为每项能力记录使用者、业务不变量、输入输出、关键数据、变化节奏和责任主体。
+3. 标出必须强一致、允许最终一致、可离线处理和必须人工确认的流程。
+4. 识别共享概念中的同名异义与不同上下文，避免直接建立全局统一数据模型。
+
+产物至少包括能力清单、能力关系和待确认边界。
+
+### N4：提出应用拆分候选
+
+1. 先形成最小可行边界：模块化单体、少量独立应用或其他适合交付形态的结构。
+2. 只有在业务所有权、数据、发布节奏、隔离或扩缩容需求明确时才增加独立应用。
+3. 对每个候选应用填写职责、不负责事项、调用方、数据所有权、上下游、运行和安全边界。
+4. 至少比较以下方案：维持单一应用、按主要业务能力拆分、按独立运行要求进一步拆分。
+5. 计算拆分引入的契约治理、分布式一致性、测试、部署、观测和团队协作成本。
+6. 到达 G2，由用户确认目标应用清单、保留模块和不拆分项。
+
+### N5：细化应用契约
+
+根据已批准边界按需执行：
+
+- 使用 `design-backend` 设计应用内部模块、服务、事务和错误边界。
+- 使用 `design-frontend` 设计前端应用、页面、状态和复用边界。
+- 使用 `design-api` 设计跨应用同步接口，使用 `prepare-api` 整理调用方字段映射。
+- 使用 `design-db` 明确数据所有权、表结构、索引和未来迁移边界。
+- 使用 `design-workflow` 设计跨应用状态、任务、补偿、幂等和审计。
+
+跨应用共享代码只保留稳定、无业务所有权争议的基础能力。共享数据库、跨库事务和双向同步必须显式记录风险，不能作为无说明默认方案。
+
+### N6：设计工程和运行结构
+
+在不创建代码的前提下给出建议结构：
+
+- 仓库组织：单仓、多仓或混合方式及选择依据；
+- 每个应用的源码、测试、契约和配置边界；
+- 公共库的准入条件、版本和兼容策略；
+- 本地开发、持续集成、制品、部署和环境配置方式；
+- 日志、指标、追踪、健康检查和故障隔离要求；
+- 认证授权、密钥管理和敏感数据处理边界。
+
+无法从需求确定的平台决策继续作为待确认项，不把目录草案写成已创建结构。
+
+### N7：形成建设计划
+
+使用 `plan-change` 按以下依赖顺序制定计划：
+
+1. 建立项目与契约基线；
+2. 搭建最小工程和验证链路；
+3. 优先实现能纵向验证核心场景的应用切片；
+4. 建设公共能力和外部集成；
+5. 完成跨应用契约、失败恢复和安全验证；
+6. 补齐部署、可观测性、容量和验收验证。
+
+每个批次记录输入、应用范围、产物、依赖、测试、停止条件和回退方式。到达 G3，由用户确认后续是否进入工程创建与代码实现。
+
+## 4. 新项目交付物
+
+- 已验证的 `AGENTS.md` 与 `.craftkit/` 项目资料；
+- 已确认需求基线和待确认清单；
+- 业务能力地图及能力关系；
+- 应用拆分方案、替代方案和决策依据；
+- 应用职责矩阵、契约清单、数据所有权矩阵和依赖关系；
+- 工程与运行结构建议；
+- 分阶段建设计划、验证矩阵和回退边界。
+
+## 5. 停止条件
+
+出现以下情况时暂停，不继续推导：核心业务目标冲突、数据所有权无法确定、关键外部契约未知、技术选型会实质改变交付边界、参考项目授权范围不清，或用户尚未批准对应审批门。
+
+## 6. 可直接复制的总控提示词
+
+```text
+请按《新项目初始化与应用拆分工作流》推进当前项目。先使用 init 只读判断项目模式，展示项目根、Git 状态、输入材料、参考范围和待确认项，在 G0 等待我确认。确认后保守初始化 AGENTS.md 与 .craftkit 项目资料，使用 requirements 建立需求基线，再依次完成业务能力地图、应用拆分候选、方案比较、应用职责与数据所有权矩阵、跨应用契约、工程与运行结构建议以及分阶段建设计划。
+
+全过程区分用户已确认目标、输入事实、参考项目做法、项目规则、设计建议、待确认项和待验证项。不要默认微服务、框架、数据库、云平台或最新版本；允许“不拆分”或“模块化单体”成为最终建议。只在 G0、G1、G2、G3、业务决策、权限扩大或高风险副作用处暂停。未经我另行授权，不创建业务代码，不安装依赖，不执行数据库、部署、提交或发布操作。
+```