timzaak/web-dev-skills/t-design

技术设计文档生成

运行时边界：${CLAUDE_PLUGIN_ROOT}/protocols/runtime-boundaries.md（判断产物写入位置或项目事实与插件默认冲突时读） 需求来源边界：${CLAUDE_PLUGIN_ROOT}/protocols/requirement-source-contract.md（区分草稿与已发布需求来源、处理两者并存裁决时读） 决策连续性和用户决策暴露：${CLAUDE_PLUGIN_ROOT}/protocols/decision-continuity-contract.md（提问、更新决策账本或处理决策暴露门禁时读） 子 agent 调用：${CLAUDE_PLUGIN_ROOT}/protocols/subagent-dispatch.md（调度设计 agent 前 read 其对应角色规范） 设计 agent 输出：${CLAUDE_PLUGIN_ROOT}/protocols/design-agent-output-contract.md（解析 subagent 返回前读） 设计生成状态：${CLAUDE_PLUGIN_ROOT}/protocols/design-state-contract.md（写入或校验 .state.json 时读）

设计生成应保持简单、当前必需、可追溯；如果需求、spec、代码或本 skill 冲突，停止并说明冲突。

决策纪律（全文只在此声明一次，各步骤直接引用）：影响目标范围、业务规则、权限/安全边界、API 契约、数据模型、迁移/兼容性、验收标准、显著成本、风险接受或测试策略的缺口，按 Decision Exposure Gate 分类。needs_user_answer 先按 Topic 查决策账本，仍未解决时用 AskUserQuestion 提问，回答前不得把问题写成风险、待确认事项或假设后继续生成；用户回答后先更新账本，再更新对应产物。

适用范围

仅在以下场景使用：

• 用户明确要求"技术设计""方案设计""架构设计""API 设计""数据模型设计"
• 用户明确执行 /t-design [方案名称]
• 已经确认这是新功能或较大能力扩展，需要正式设计文档进入 DDD 流程

不要因为用户只是问"怎么实现""大概怎么做"就自动触发本 skill。

规划测试与验收时读取 ${CLAUDE_PLUGIN_ROOT}/protocols/verification-evidence-contract.md，将受影响行为的验证入口、关键断言和承接位置写入现有设计测试章节/阶段计划；交付收尾按同一协议核对证据和待验证项。

目标

基于用户故事、PRD 草稿、已发布 PRD 基线、技术预研、用户已准备的仓库内资料和现有代码，生成可实施、可追踪、可直接进入 /t-super-run 的技术设计。/t-prd-check 是推荐的可选上游检查；未运行时，本 skill 必须自行完成关键需求来源混合验证。

设计拆分为一份主文档加按端拆分的分端设计文档；每个适用端由对应设计 subagent 生成，主会话负责编排、跨端裁决和汇总。不适用端不创建分端文档，只在主文档 §4.2 标记"不适用"及原因。

如果未传方案名称，立即终止并提示： 请提供方案名称。例如：/t-design <feature>

Input Contract

上游输入（按设计类型选择；读取顺序：先索引，再 .ai/decision / .ai/decision-log，再需求来源，最后 guides）：

• 业务功能设计：
• .ai/decision/<feature>.md — 产品立项决策简报（如存在，作为 PRD 之前的方向约束）
• .ai/decision-log/<feature>.md — 跨阶段决策账本（存在时必须读取）
• .ai/prd/<domain>/<feature>.md — /t-prd 产出的 PRD 草稿；按 feature 在 .ai/prd/ 下查找，存在时必须读取，作为当前候选需求（也兼容 .ai/prd/<feature>.md）
• docs/prd/<domain>/<feature>.md — 已发布 PRD 基线（如存在，作为正式需求基线）
• .ai/user-stories/**/*.md — draft 用户故事（如存在，作为当前候选需求）
• docs/user-stories/**/*.md — 已发布相关用户故事
• docs/prd/00-index.md、docs/user-stories/00-index.md — 索引
• 纯技术方案设计：
• .ai/tech-research/<feature>.md — 技术预研报告，可作为唯一上游需求来源
• 仅适用于不涉及业务逻辑、产品规则、用户可见流程或验收目标变动的设计

可选输入：

• ${CLAUDE_PLUGIN_ROOT}/guides/core/environment-and-testing-guide.md — 环境与测试指南
• ${CLAUDE_PLUGIN_ROOT}/guides/backend/development.md — 后端开发规范
• ${CLAUDE_PLUGIN_ROOT}/guides/frontend/development.md — 前端开发规范
• ${CLAUDE_PLUGIN_ROOT}/guides/frontend/ui-decisions.md — 前端 UI 组件选型、交互状态与无障碍底线（frontend/extension 涉及用户可见 UI 时）
• ${CLAUDE_PLUGIN_ROOT}/guides/extension/development.md — Chrome 扩展设计时读取
• ${CLAUDE_PLUGIN_ROOT}/guides/extension/demo-testing.md — 设计包含 Chrome 扩展用户故事演示时读取
• ${CLAUDE_PLUGIN_ROOT}/guides/flutter/development.md — Flutter 开发规范（目标项目启用 Flutter 时）
• ${CLAUDE_PLUGIN_ROOT}/guides/flutter/demo-testing.md — Android Patrol 用户故事演示规范（设计要求 Flutter Demo 时）
• ${CLAUDE_PLUGIN_ROOT}/guides/shopify/development.md — Shopify App 开发规范（目标项目为 Shopify App 时）
• ${CLAUDE_PLUGIN_ROOT}/guides/shopify/testing.md — Shopify 测试边界（Shopify 设计涉及测试或用户故事演示时）
• ${CLAUDE_PLUGIN_ROOT}/guides/core/quality.md — 质量规范

Output Contract

下游产出：

• .ai/design/$ARGUMENTS.md — 设计主文档，包含：
• 目标与范围
• 用户故事/PRD/技术预研引用与完整 Decision Trace
• 跨端现状概览
• 总体设计与关键取舍、交付端范围
• 跨端契约（API 契约摘要与契约源声明）
• 分端设计摘要
• 测试与验收策略（跨端汇总）
• 风险与验证动作（汇总）
• 文件影响范围（全量汇总，/t-super-run 的唯一拆分依据）
• .ai/design/$ARGUMENTS/backend.md — 后端分端设计（适用时），包含 API 契约（唯一设计源）、数据库设计、领域逻辑、权限安全、详细设计、后端测试策略
• .ai/design/$ARGUMENTS/frontend.md — 前端分端设计（适用时），包含页面/组件/线框、状态与数据流、交互与关键状态、性能、测试与 Demo 策略
• .ai/design/$ARGUMENTS/extension.md — 扩展分端设计（适用时），包含入口、消息/存储、权限、生命周期与浏览器验证策略
• .ai/design/$ARGUMENTS/flutter.md — Flutter 分端设计（适用时），包含分层架构、状态管理、页面与导航、可测试性、测试与 Patrol Demo 策略
• .ai/design/$ARGUMENTS/shopify.md — Shopify 分端设计（适用时），覆盖 shopify-app 与 shopify-extension 两个 phase 的交付面（应用本体、admin 嵌入页、app proxy、theme app extension、customer account UI extension）；backend 端不适用时本文档的 app proxy / internal API 契约是唯一契约源
• .ai/design/$ARGUMENTS/.state.json — 设计生成状态；结构见 ${CLAUDE_PLUGIN_ROOT}/protocols/design-state-contract.md，只有 complete 可被下游消费
• .ai/decision-log/$ARGUMENTS.md — 复用上游决策；仅在产生用户决策、问题状态变化或重要 AI 决策时更新

核心约束

• 若存在 .ai/decision/<feature>.md，设计必须尊重其中目标用户、Scope Direction、D0/D1 产品决策和 Handoff；不得用技术方案静默改变立项结论
• 若存在 .ai/decision-log/<feature>.md，必须逐项承接影响设计的 Active Decision；不得重复询问 Resolved Question，也不得使用 Superseded Decision
• 纯技术方案没有 PRD/用户故事时，以 .ai/tech-research/<feature>.md 中的技术目标、约束和影响范围为准；必须在主文档中声明"纯技术方案设计，不涉及业务逻辑变动"，并引用对应技术预研报告；执行流程与质量门禁以 ${CLAUDE_PLUGIN_ROOT}/guides/ 为准
• 只引用用户故事，不粘贴完整故事正文或整段 Gherkin
• 优先复用现有实现，不凭空设计新架构
• 默认不搜索额外资料；人类在进入 /t-design 前应已准备好相关资料。只有在人类明确要求补充外部依据时，才可将外部资料作为附加参考
• API 契约的单一设计源是 backend 分端文档；frontend/extension/flutter 分端文档只声明依赖的接口与字段，不得复制或另立契约；后端不适用时以现有 OpenAPI/SDK 或接口为契约源。Shopify 项目默认不启用 backend 端：shopify.md 的 app proxy / internal API 接口清单承担契约源，此时不存在独立 backend 分端文档
• 主文档不承载 API 字段表、数据库表结构和页面线框等分端细节；细节只活在对应分端文档，主文档保留摘要与链接
• 数据库设计遵循"尽量简洁、当前必需、避免过度审计设计"
• 现状依据及 MODIFY/DELETE 路径必须真实存在；CREATE 路径可以尚不存在，但父目录必须真实存在，并给出相邻实现或项目规范作为命名依据；例外是 skill 根目录（.claude/skills/、.agents/skills/、skills/）下的 CREATE 路径，新 skill 目录允许随交付创建
• 分端文档由对应设计 subagent 生成；主会话不得绕过 subagent 代写分端设计，除非该端不适用

工作流程

1. 验证参数和输出位置

• 校验 $ARGUMENTS 非空；文件名仅允许中文、英文、数字、空格、下划线、连字符
• 如果 .ai/design/$ARGUMENTS.md 或 .ai/design/$ARGUMENTS/ 下任一分端文档已存在，先询问是否覆盖。用户确认后先重新判定适用端，删除上一轮存在但本轮不适用的分端文档，再按输出协议写入 in_progress 状态

2. 收集最小必要输入

如果当前上下文不足，使用 AskUserQuestion 只补齐以下内容；用户已在对话或参数里给出的信息不重复提问。提问遵循决策纪律（先查账本）：

• 功能目标或问题陈述
• 人类已准备好的相关资料路径或名称
• 需要覆盖的范围边界
• 交付端范围（仅当无法从需求来源、现有代码或 Decision Log 判断时）

D2 工程取舍由设计阶段明确选择并写入 Design；符合 Decision Continuity Contract 的 Entry Gate 时才回写决策账本。

3. 搜索需求来源

只搜索真实目录：

• docs/user-stories/**/*.md
• .ai/user-stories/**/*.md
• .ai/prd/**/*.md
• docs/prd/**/*.md
• .ai/tech-research/**/*.md
• docs/design/**/*.md、.ai/design/**/*.md（如果存在相关先例）

优先做法：先从索引定位候选文档，再对候选文档做 Grep，最后 Read 真正相关的少量文件。

无论索引是否收录草稿，都要按 $ARGUMENTS 在 .ai/prd/ 下查找同名 PRD（包括 <domain>/$ARGUMENTS.md 和 $ARGUMENTS.md）；找到后必须读取，并与相关 docs/prd/ 已发布基线核对。若找到多个同名草稿且无法确定对应领域，先按决策纪律确认，不得自行选取其中一份。

业务功能设计至少提取：用户故事 ID/标题/优先级/来源文件、场景概述或验收目标摘要、PRD 草稿中的当前候选业务边界/规则/非功能要求、已发布 PRD 基线及草稿相对基线的差异、draft 用户故事相对已发布故事的新增或变更场景、Decision Log 中影响设计的 Active Decisions / 已解决问题 / 本阶段到期的 Deferred Questions。草稿与正式来源的并存裁决按需求来源边界协议执行；冲突无法确认覆盖关系时停止并提示修正草稿，必要时运行 /t-prd-check [feature]。

如果没有找到足够的用户故事或 PRD：

• 优先检查 .ai/tech-research/$ARGUMENTS.md；存在且足以支撑纯技术方案时继续生成，并在需求来源中标记 PRD/用户故事不适用
• 不存在或技术预研不足、且缺失影响方案判断时，按决策纪律要求用户补齐目标、范围或来源后再继续
• 纯技术方案设计至少提取：技术目标、当前约束、选定技术路线、依赖或版本变化、影响范围、风险和不涉及业务逻辑变动的边界声明

4. 分析现有实现

分析真实代码结构，不要假设，输出：现有实现入口（后端、前端、扩展、Flutter 各自适用部分的现状）、可复用模块、需要修改的边界、与当前架构或约束冲突的点。代码分析复杂时用 Task 启动 Explore agent，要求返回现有实现位置、可复用点、受影响模块和具体文件路径。

5. 确定交付端范围与契约归属

• 判定 backend / frontend / extension / flutter / shopify 哪些端适用：依据需求来源中的交付端描述、${CLAUDE_PLUGIN_ROOT}/protocols/task-phase-execution.md 的 phase 结构、现有代码结构（如 frontend/、扩展 WXT 工程、Flutter 工程、shopify.app.toml 与 extensions/ 是否存在）和 Decision Log。判定结果影响拆分方向且无法确定时，使用 AskUserQuestion 确认
• 契约归属：backend 适用时，API 契约由 backend 分端设计产出，backend 设计必须先行；backend 不适用时，契约源为现有实现分析中确认的现有接口/OpenAPI/SDK，frontend/extension/flutter 可直接并行生成；Shopify 项目（shopify.app.toml 存在且无独立后端工程）契约源为 shopify 分端设计，同样可与其他客户端端并行
• 在主文档 §4.2 记录交付端范围和判定依据
• 需求要求交付 skill 时：skill 文件路径写入主文档 §8；skill 的设计内容（触发场景、能力边界、行为验证）写入其服务或操作交付端的分端文档，独立于任何端时写入主文档。skill 交付不新增交付端、不创建独立分端文档，规划规则见 ${CLAUDE_PLUGIN_ROOT}/protocols/task-phase-execution.md 的 Skill Deliverables。skill 根目录按项目既有 skill 目录；项目尚无 skill 目录时按目标运行时选择（Claude Code 为 .claude/skills/，open agent skills 约定为 .agents/skills/），无法判定时按决策纪律确认

6. 分端生成设计（subagent 编排）

按适用端调度设计 agent，subagent_type 映射：

调度顺序：backend 适用 → 先调度 backend-design，成功后再调度 frontend-design / extension-design / flutter-design；backend 不适用 → 可并行调度（shopify-design 同样作为契约源时与其他客户端端并行，主会话在合并阶段以 shopify.md 的契约清单做跨端比对）。同批次同角色复用按 ${CLAUDE_PLUGIN_ROOT}/protocols/subagent-dispatch.md 执行。

design_stack 与映射表中的端一致，传入对应 guide/模板路径；extension 使用 ${CLAUDE_PLUGIN_ROOT}/agents/extension-design.md。同一任务 Web 与扩展两端均适用时分别调度和输出，不合并分端设计。

每次调度前必须：

• 按 subagent-dispatch 协议 Read 对应 agents/<role>.md 全文并注入为子 agent prompt 的角色指令段
• 在 prompt 中提供最小上下文：方案名、design_stack 与输出路径、需求来源文件路径清单与关键摘要、Decision Log 路径及影响本端的 Active Decision 摘要、现有实现分析结论（本端相关部分）、契约源（backend 适用时传 .ai/design/$ARGUMENTS/backend.md 路径及 design_result.contract_summary；否则传现有接口清单）、分端模板路径与对应 guide 路径、${CLAUDE_PLUGIN_ROOT}/protocols/design-agent-output-contract.md
• 不复制 guide、protocol 或 agent 文档中的长篇规则

处理子 agent 返回：

• 只读取 task_completion.status 和 design_result；其他顶层返回结构不符合输出契约
• needs_user_answer 非空 → 按决策纪律处理，然后重新调度该端
• task_completion.status=partial 或 design_result.self_check 未通过 → 不进入合并；修复输入后重新调度，无法恢复时把生成状态写为 failed
• task_completion.status=failed → 终止该端并把生成状态写为 failed；不得写入该端成功状态
• frontend/extension/flutter 的 design_result.contract_dependencies 必须按输出协议逐项对比 backend 的 design_result.contract_summary；operation、method/path、字段子集或调用方冲突时重新调度客户端设计，属于产品语义冲突时使用 AskUserQuestion 裁决。backend 不适用而 shopify 充当契约源时，其他客户端端与 shopify.md 的接口清单按同一规则比对
• 每个端成功后更新 completed_stacks；全部适用端 task_completion.status=success 后进入合并

7. 合并生成主文档

使用 template.md 生成 .ai/design/$ARGUMENTS.md，内容来自前序步骤与各分端文档返回：

• 目标、范围、需求来源与完整 Decision Trace（主会话编写；分端文档只保留本端 DEC 子集）
• 跨端现状概览、总体设计与关键取舍、交付端范围
• 跨端契约摘要（来自 backend design_result.contract_summary 或现有接口）与契约源声明
• 分端设计摘要（来自各端 task_completion.summary，每端 3-5 行）
• 测试与验收策略跨端汇总（来自各分端文档测试章节）
• 风险与验证动作汇总
• §8 文件影响范围：逐行合并各分端文档的文件影响表，标注来源分端（取值 backend/frontend/extension/flutter/shopify/web-demo/extension-demo/flutter-demo/跨端；设计要求用户故事演示时，Web Playwright 资产标 web-demo、扩展 Playwright 资产标 extension-demo、Patrol 资产标 flutter-demo，供 /t-super-run 识别 demo 交付端；shopify 分端的资产按归属 phase 在说明列标注 shopify-app / shopify-extension；skill 交付物按其服务或操作的交付端取值，独立于任何端时标 跨端，说明列注明 skill 根目录）；此表是 /t-super-run 的唯一拆分依据，必须覆盖全部适用端

不适用章节保留并标记"不适用"及原因。写入后对所有实际生成的文档运行：

python ${CLAUDE_PLUGIN_ROOT}/scripts/check-decision-closure.py ".ai/design/$ARGUMENTS.md" ".ai/design/$ARGUMENTS/backend.md" ".ai/design/$ARGUMENTS/frontend.md" ".ai/design/$ARGUMENTS/extension.md" ".ai/design/$ARGUMENTS/flutter.md" ".ai/design/$ARGUMENTS/shopify.md"

命中项按 Decision Exposure Gate 分类处理；重新扫描通过前不得交付设计。随后运行 python ${CLAUDE_PLUGIN_ROOT}/scripts/check-design.py ".ai/design/$ARGUMENTS.md" 做确定性结构校验（章节、模板占位符、适用端文档、契约 operation、文件影响汇总和路径操作）。两项扫描全部通过后，才把 .state.json 写为 complete。

高风险、跨端或长文档设计在完成前额外调度一个无原会话背景的通用只读 agent，只提供全部设计文档和以下问题：实现入口、契约唯一来源、失败/权限/兼容路径、测试入口、文件影响范围。若读者无法从文档稳定回答或发现矛盾，修正文档并重新执行两项扫描；简单设计跳过时在收尾说明。

8. 分端设计验收

逐项按对应 agents/*-design.md 的"着重点"和质量清单验收。额外拒绝：

• 涉及的 API 缺少 operation ID、字段语义或具体契约源；Shopify 无接口场景按设计输出协议校验不适用声明
• frontend/extension/flutter/shopify 复制 API 字段定义，或客户端状态方案偏离对应 guide（shopify 端为 app proxy 验签与顾客识别语义偏离 ${CLAUDE_PLUGIN_ROOT}/guides/shopify/development.md）

9. 收尾输出