tsubaki-01/tsubaki_skills/research-to-system-design

调研到系统设计

独立接收用户需求、已有研究材料和目标项目，交付贴合项目的系统设计。研究材料可以来自其他任务或外部文档，不要求先运行 parallel-research。

设计的重点是确定模块落点、关键契约和数据、核心正常流程及必要失败行为，给后续编码留下明确边界。内部 helper 和局部实现由编码阶段决定，不预设每个类或方法。设计请求到设计交付为止；分析可以在当前模式完成，不依赖原生 Plan 模式。

确定材料与落盘位置

从请求和上下文确定要解决的需求、目标项目及相关研究材料。用户指定的报告文件或目录优先；承接刚完成的研究时使用已交付的实际路径列表。

若只给了主题目录，检查其中实际报告，说明本次选用的文件。默认研究报告位于 {workspace}/.codex/{research_ROI}/research/；不要用 research_{ROI}_*.md 模式把自身旧 summary 当作原始研究报告。多个候选批次会改变设计依据时，澄清选择。

用户指定输出路径时沿用。否则从当前工作目录与主题推导 workspace、research_ROI 和 ROI，告知以下输出位置：

{workspace}/.codex/{research_ROI}/{ROI}_design_draft.md
{workspace}/.codex/{research_ROI}/{ROI}_design.md

只在需要独立总结时生成：

{workspace}/.codex/{research_ROI}/research_{ROI}_summary.md

需求或目标项目尚不明确时先澄清，不能用参考来源的架构替用户决定要做什么。

先理解项目，再取舍研究结论

读取与需求有关的项目约定、模块和调用路径，定位已有接口、数据或状态的归属、依赖方向，以及相关测试覆盖的行为。区分当前实现与计划文档中的设想。

沿核心正常流程判断这项能力如何进入现有系统。已有模块和接口可以承载需求时复用它们；新增抽象、依赖、状态或机制时，说明它解决的当前核心问题，以及已有结构为什么不足。参考项目拥有某种机制，本身不构成引入理由。

将影响设计的研究结论与本项目条件对照，保留结论的来源位置、成立条件及采用或不采用的理由。对关键契约和状态行为，回查所依赖的原材料与项目代码，不能仅凭摘要中的推荐定案。

材料的数量、重复或分歧使直接设计难以保持清晰时，才委派独立总结者。总结应提取相关共识、分歧和适用条件，保留原报告与关键证据入口；无需逐份复述，也不能把摘要变成设计者唯一可见的依据。材料清晰时直接进入设计。

形成设计草稿

按本次需求组织草稿，不套用固定章节。让编码者能够从需求追踪到项目中的落点与行为：

• 要实现的范围、已确认的约束，以及影响方案的假设或待决问题。
• 相关模块承担什么职责，能力如何接入已有接口，依赖如何流动。
• 跨模块所需的关键接口与数据约定；涉及状态或持久化时说明归属和变化时机。
• 从触发到结果的核心正常流程，以及会改变结果或后续处理的必要失败行为。
• 重要取舍及其依据，尤其是新增复杂度对应的实际需求。
• 能验证这些行为的针对性验收方式，以及有依赖关系时的实现顺序。

材料和代码能够回答的事实先查清。仍然需要用户决定、且会改变需求、契约或方案取舍的问题要明确询问，不能静默写成设计要求；不受该决定影响的部分可以继续。普通内部实现选择不升级成新的架构决策。

独立审核与定稿

草稿完成后交给独立审核 subagent，并向用户说明它负责检查项目贴合度、关键行为与新增复杂度。审核者收到已确认需求、草稿、同一组原报告路径和关键证据入口、目标项目位置及相关代码入口；如有 summary，一并提供作导航。

审核者只返回问题与建议，设计者负责修订产物。审核重点是：

• 沿核心正常流程，需求能否通过所列项目接口、数据与状态变化得到实现。
• 模块职责和依赖方向是否符合当前代码，是否把计划中的能力误当成现成接口。
• 参考结论的适用条件是否成立，新增机制是否对应当前问题，已有结构是否足以完成同一需求。
• 关键契约是否明确，验收能否判断所需行为，而不是只检查文件或章节。

解决影响这些核心问题的发现后写入最终设计；涉及未决用户选择时先澄清相关部分。修订改变了关键流程或契约时，将受影响部分交回审核，无需重复检查无关内容。若当前环境无法提供独立审核，保留草稿并说明尚缺这一步，不称为已审核定稿。

交付实际生成的文件路径、主要设计决定及仍未解决的问题。只有关键需求与核心流程已经明确、影响实施的决策已解决且独立审核完成，才将设计报告为可供后续编码使用；没有必要的 summary 不生成，也不作为完成条件。