跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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/**/*.md
  • docs/prd/**/*.md
  • .ai/tech-research/**/*.md
  • docs/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 记录交付端范
阅读完整来源 ↗