---
name: development-design
description: 通用开发生命周期的「方案设计」阶段 owner；当用户明确要求设计、风险达到 L3-L4，或用户可见 L2 功能存在真实方案空间时使用，负责冻结可执行设计，不负责实现、验证或发布。
---

# Development Design

## 目标

回答“采用哪条主链路，为什么”。证据不足则返回调查。

实现前冻结验收与交付，不自行缩减用户结果。明确交付物与授权，给出 1–3 条“黄金验收”链路：目标 → 前提/真实入口 → 操作 → 响应 → 后续操作 → 结果 → 成败判定。入口、功能清单或技术调用链不能代替使用链路。标明等待成本、AI 自验证据及用户判断项；安装、测试和排障由 AI 承担。黄金验收覆盖完整标准但不替代 AI 自验；active contract 复用 IDs，按行为差异补矩阵。

验收适用性按用户行为与结果是否变化判断：没有新增 UI、只改底层或尚未发布，不构成豁免。纯内部重构且用户行为不变、规则维护或用户明确限定的源码/Review/原型交付，说明依据并提供匹配产物，不虚构产品使用链路。

稳定设计写入 `docs/designs/YYYY-MM-DD-<topic>.design.md`；局部方案可内联。大型交付的独立结果/决策须在实现前落盘；已有设计可引用，缺口和关键变更先补原文并链接历史。影响当前实现的选择先解决；分阶段须证明必要性。

有效合同形成或变化后，核对已有方案是否仍覆盖当前目标；受影响的设计、黄金验收和旧方案 Review 结论失效，补齐并复审后才能据此实现。未受影响部分继续复用，不把早期方案中的“未来扩展”当作新合同的范围决定。

## 产物分级

大型交付可按独立能力或独立审查需要拆专题设计：整体设计链接专题，专题引用上位约束并注明负责范围与适用状态，不复制全局合同。当前执行状态指向本项采用的设计和 Review 结论；拆文件不新增交付阶段。

输出设计结论与 `design-document: required | not-required`；feature/bugfix 共用产物门。

轻量设计限单 owner、无跨层合同/状态/兼容或真实分叉、局部可逆且不复用；写清问题、主链路、理由与验证。

出现以下任一情况，必须写入或更新稳定的 `docs/designs` 文档：

- L3-L4，或跨 package、runtime、projection、transport、持久化边界；
- 用户可见 L2 功能存在交互、信息架构或行为取舍；
- 改变状态 owner、生命周期、不变量、协议、兼容、迁移、fallback 或失败恢复；
- 有两个以上真实可行候选，需要记录选择与放弃理由；
- 设计会跨会话、跨批次、交给他人实现，或预计成为后续判断依据。

L0 文档修正和 lifecycle 可跳过的 L1 单路径改动无需进入；不按 diff、工时或文件数决定是否建文档。

## 计划门

进入 Implementation 前输出 `plan: required | not-required`。单批无法可信闭环时使用[开发执行 Plan 合同](../../wiki/skills/process/project-knowledge-governance/references/development-plan-contract.md)，否则不建；Plan 不是新 phase。

## 设计合同

只展开与当前任务相关的维度：

- 大型交付记录“来源/版本 → 有效要求/ID → 设计位置 → 验证”，保留原始输入与全局约束；偏离写依据，未经授权不改用户结果。替代的旧输入保留溯源，原型不能只核对外观。
- 用户或系统可观察问题；
- producer、owner、consumer、已有约束与现有能力复用证据；
- 真实分叉时的 2-4 个候选：用户价值、owner、复杂度、可逆性、验证成本及主链路；路径明显不虚构候选；
- 状态、生命周期、不变量、失败/恢复、目录/公共入口/依赖边界；
- 第三方框架/runtime/协议：冻结上游执行、线程、生命周期、资源与错误合同及产品保留职责；偏离须有必要性、官方依据、验证和退出条件；
- 删除或禁止的平行路径，兼容/迁移/fallback 的必要性与退出条件；
- 非目标与最小验证标准。

性能/成本影响选型时，沿同一代表性任务比较等待、资源和成本，区分实测、估算与未知；引用 active contract 门槛并给出昂贵分支验收路径。缺关键数据先做最小实验，不凭理论冻结结论；无相关取舍不加基准测试。

跨运行宿主、存储归属、能力目录或主要用户链路的设计，按[功能设计关](references/feature-design-gate.md)对账旧能力、用户目标和候选能力；关键入口、权限边界或验收路径未定时保持未就绪。

证据足够时冻结占优方案；仅当选择显著改变用户行为或范围且无法判断偏好时，才请求用户决定。

## 思考投入

新项目、技术栈替换或新增影响运行/部署的关键依赖，必须在搭建产品脚手架、安装正式依赖和编码前按[技术栈选型](references/technology-selection.md)形成技术决策与依据；限定问题的可丢弃验证实验可先执行。用户指定技术仍核对适用性。沿用现有栈的普通小改只说明沿用依据，不例行比较或加载该参考。

目标、事实、根因或候选不确定，或属高风险决策时，读取[自适应方案思考](references/adaptive-deliberation.md)，选最低成本方法。简单可逆的惯例路径直接结论；不机械多方案，也不凭直觉冻结复杂设计。

## 过度设计门

任何设计进入 `Design Ready` 前必须完成一次抽象审计：

1. 写出入口到结果的最小完整路径，接口和字段须服务该路径。
2. 区分单例、局部重复与跨场景不变量；抽象不高于证据。
3. 复用主链路和最窄 owner；多场景共享变化边界才扩大范围。
4. 恢复、权限、幂等完整；无消费者的基础设施不进入范围。
5. 比较错误 owner/迁移债与无消费者抽象/验证面，选择净复杂度最低的结构。

新增/改变抽象或公开闭集 variant 时必须读取[架构设计原则](references/architecture-principles.md)，写清保留、删除、延后项；未来成本未付清不得 `Design Ready`。

涉及用户可用能力（含 CLI、SDK、后台自动化与集成）或交互时，读取[功能设计关](references/feature-design-gate.md)，先呈现用户链路再展开协议；纯内部且用户行为不变时说明不适用。

跨 runtime、journal、projection、transport 或 UI 的状态型设计补普通、运行、重试、取消、中断、刷新恢复和旧数据矩阵；局部无状态方案不填。

已有实现、验证、Review 或线上现象暴露未建模行为时，读取[设计缺失的范围判定](references/design-gap-scope.md)，区分实现偏差、局部合同、能力面和系统模型缺口，选防同类复发的最小范围；不按报错位置或 diff 定范围。

## 专项路由

每个设计决策最多选择一个当前 owner：

- 通用 owner、生命周期、不变量、职责边界或抽象力度：读取[架构设计原则](references/architecture-principles.md)；
- 当前项目有领域、前端、目录、兼容、内容或发布专项合同时，只读取与本次设计决策直接相关的项目方法；不把项目方法复制进通用阶段。

专项方法仅按条件读取。

## 完成

冻结前用验收场景自审主链路、失败边界与抽象力度，关闭缺口；单路径简述结论，不虚构候选、默认委派或另建评审文档。

设计须形成统一模型，返回设计/plan、owner、主链路、验收标准、必要矩阵和非目标；standard 与正式 bugfix 设计交回总流程进入方案 Review，通过前不进入实现。本阶段的自审不替代该门。

新现象暴露模型缺口则返工设计；仅实现偏差不扩大。本阶段不编辑产品实现、验证、review、提交或发布。