t-design

Files (7)

• SKILL.md
• template-backend.md
• template-extension.md
• template-flutter.md
• template-frontend.md
• template-shopify.md
• template.md

SKILL.md (first lines)

# 技术设计文档生成

运行时边界：`${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`

From timzaak/web-dev-skills, Apache-2.0.

More from timzaak/web-dev-skills