t-design
Generate technical design documents including API design, database schema, and implementation details for a feature.
timzaak · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add timzaak/web-dev-skills --skill t-design技能说明
name: t-design description: Generate technical design documents including API design, database schema, and implementation details for a feature. argument-hint: "[方案名称]" allowed-tools:
- AskUserQuestion
- Read
- Glob
- Grep
- Task
- Agent
- Write
- Bash
技术设计文档生成
运行时边界:${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。
目标
基于用户故事、PRD 草稿、已发布 PRD 基线、技术预研、用户已准备的仓库内资料和现有代码,生成可实施、可追踪、可用于 /t-task 的技术设计。/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— PRD 草稿(如存在,作为当前候选需求)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/flutter/development.md— Flutter 开发规范(目标项目启用 Flutter 时)${CLAUDE_PLUGIN_ROOT}/guides/flutter/demo-testing.md— Android Patrol 用户故事演示规范(设计要求 Flutter Demo 时)${CLAUDE_PLUGIN_ROOT}/guides/core/quality.md— 质量规范
Output Contract
下游产出:
.ai/design/$ARGUMENTS.md— 设计主文档,包含:- 目标与范围
- 用户故事/PRD/技术预研引用与完整 Decision Trace
- 跨端现状概览
- 总体设计与关键取舍、交付端范围
- 跨端契约(API 契约摘要与契约源声明)
- 分端设计摘要
- 测试与验收策略(跨端汇总)
- 风险与验证动作(汇总)
- 文件影响范围(全量汇总,
/t-task的唯一拆分依据)
.ai/design/$ARGUMENTS/backend.md— 后端分端设计(适用时),包含 API 契约(唯一设计源)、数据库设计、领域逻辑、权限安全、详细设计、后端测试策略.ai/design/$ARGUMENTS/frontend.md— 前端分端设计(适用时),包含页面/组件/线框、状态与数据流、交互与关键状态、性能、测试与 Demo 策略.ai/design/$ARGUMENTS/flutter.md— Flutter 分端设计(适用时),包含分层架构、状态管理、页面与导航、可测试性、测试与 Patrol Demo 策略.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/flutter 分端文档只声明依赖的接口与字段,不得复制或另立契约;后端不适用时以现有 OpenAPI/SDK 或接口为契约源
- 主文档不承载 API 字段表、数据库表结构和页面线框等分端细节;细节只活在对应分端文档,主文档保留摘要与链接
- 数据库设计遵循"尽量简洁、当前必需、避免过度审计设计"
- 现状依据及 MODIFY/DELETE 路径必须真实存在;CREATE 路径可以尚不存在,但父目录必须真实存在,并给出相邻实现或项目规范作为命名依据
- 分端文档由对应设计 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/**/*.mddocs/prd/**/*.md.ai/tech-research/**/*.mddocs/design/**/*.md、.ai/design/**/*.md(如果存在相关先例)
优先做法:先从索引定位候选文档,再对候选文档做 Grep,最后 Read 真正相关的少量文件。
业务功能设计至少提取:用户故事 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 / flutter 哪些端适用:依据需求来源中的交付端描述、
${CLAUDE_PLUGIN_ROOT}/protocols/task-phase-execution.md的 phase 结构、现有代码结构(如frontend/、Flutter 工程是否存在)和 Decision Log。判定结果影响拆分方向且无法确定时,使用AskUserQuestion确认 - 契约归属:backend 适用时,API 契约由 backend 分端设计产出,backend 设计必须先行;backend 不适用时,契约源为现有实现分析中确认的现有接口/OpenAPI/SDK,frontend/flutter 可直接并行生成
- 在主文档 §4.2 记录交付端范