AGENT SKILL

dev-design

个人开发者轻量设计。以问题池循环把一个需求收敛为单份 dev-design.md:需求、现状摘要、方案、契约变更、影响面、验收标准、存疑。问人与问代码是同一个循环的两个出口——代码能答的问题攒批取证(优先委托只读 SubAgent,无宿主支持时主进程只读批量取证),代码证不出的问题按设计树轮次向用户提问(一轮抛全部前沿、各带推荐答案)。不设独立现状附录,代码论断在方案、契约变更、影响面处内联 file:line 引用。Use when the user asks for 轻量设计、个人项目设计、dev-design。

License 许可
MIT
最近更新
2026-11-15
Stars
★ 9
Forks
6

01 前言 Front Matter

name
dev-design
version
2.3.2.5
description
个人开发者轻量设计。以问题池循环把一个需求收敛为单份 dev-design.md:需求、现状摘要、方案、契约变更、影响面、验收标准、存疑。问人与问代码是同一个循环的两个出口——代码能答的问题攒批取证(优先委托只读 SubAgent,无宿主支持时主进程只读批量取证),代码证不出的问题按设计树轮次向用户提问(一轮抛全部前沿、各带推荐答案)。不设独立现状附录,代码论断在方案、契约变更、影响面处内联 file:line 引用。Use when the user asks for 轻量设计、个人项目设计、dev-design。

02 资源文件 1

03 SKILL.md 正文

若输出文件已存在,仍按当前要求完整执行:先读取并评估已有成果,复用仍有效的信息和已确认答案,可局部修改或整体重写,并写回原路径。

dev-design

定位

本 skill 服务于个人开发者的轻量链路,位于需求确认与测试设计之间。

它用一份文档承担实现设计,目标不是写得更少,而是写得刚好够开发:下游 dev-test-design 要能据此设计用例,task-split 要能据此拆出任务,task-dev 要能据此写出代码和测试。

唯一的档位就是"写得刚好够开发"这一档;篇幅随需求复杂度自然浮动。

唯一成果物:dev-design.md。调用方指定了位置就写到那里;没有指定时,和用户确认存放位置。

设计总原则

  1. 问题是同一池,出口只有两个:能从代码查证的进取证队列,代码证不出、需用户拍板的进提问队列。两类问题在循环中交替产生、互相解锁,不存在"先问完代码再问人"的固定顺序。
  2. 取证按批进行,每批带问题清单:攒够一批代码问题再取证,不零散漫游。优先整批委托只读 SubAgent(带回带 file:line 的结论报告);当前环境没有 SubAgent 工具时,降级为主进程按清单只读批量取证,引用要求不变。
  3. 代码论断必须可回溯:设计正文(方案、契约变更、影响面)中每一条关于现有代码的论断都带 file:line 或等价的明确定位,写在用到它的位置,不集中堆放附录。
  4. 提问按设计树轮次:把待人拍板的决策建模成设计树,一轮抛出当前可问的全部问题(tree frontier),各带推荐答案;等用户逐题表态后,前沿外扩再开下一轮。不做"一次问一个",也不做"一次抛所有待解问题"。
  5. 验收标准写需求口径:每条可判定(验证什么、怎么验证、预期结果);工程侧用例由下游 dev-test-design 承接,本文档不展开测试设计。

具体流程

Phase 1:读需求与架构,形成初始问题池

  1. 读取已有的需求说明(调用方给出的需求原文或 requirement.md)和项目架构基线 .sdd/software_architecture.md,两者都是可选,缺失不阻断。
  2. 基于需求与架构(架构缺失时从需求文本 + 代码结构自行推断探索边界,并在现状摘要中记录"无架构基线")列出初始问题:
    • 代码问题:需求映射到哪些代码位置?现有行为、签名、调用链、测试覆盖是什么?有哪些隐藏约束与既有约定?
    • 用户问题:范围边界、方案取舍、外部依赖、验收口径中需要用户拍板的事。
  3. 初始问题池不求全——循环会持续补充;但需求直接映射到的代码位置必须进入第一批取证。

Phase 2:问题池循环(取证 ⇄ 提问)

循环执行直到收敛。每一轮:

  1. 先处理取证队列:把当前积累的代码问题作为清单,整批取证——
    • 有 SubAgent 工具:委托一个只读 SubAgent 按清单探索,要求每条关键结论带 file:line;无法从代码确认的事实在报告中标记"待确认",不写成既定事实。
    • 无 SubAgent 工具:主进程按清单只读批量取证,引用要求相同;不偏离清单做无关漫游。
    • 取证只覆盖问题清单与本次需求相关的范围,不做无关模块全景取证。
  2. 消化取证结果:新事实可能解答旧的用户问题(从池中移除)、确认设计可行,也可能引出新问题(按能否自答分流进两个队列)。
  3. 抛出提问前沿:把提问队列按设计树整理——理清依赖,有些决策只有等另一些定了才可问;计算 frontier(所有前提已满足、现在就能问的决策),一轮全部抛出。每题给 ❓ 编号 + 题意,紧跟 ➡️ 推荐答案;推荐尽量踩在已取得的代码事实上。不逐题硬等,整轮一起抛。
  4. 逐题等用户表态:每道题必须等用户明确表态后才算定案,不默认采纳推荐;用户明确表示"你决定"时,选择最简单可行的方案并记录该决策及理由。
  5. 消化用户回答:回答可能解锁新的决策(进入下轮 frontier),也可能引出新的代码问题(回流取证队列)。

收敛判据:取证队列为空(没有待查的代码问题)且提问队列无可问决策(frontier 为空、无遗漏存疑)。某一队列暂时为空不算收敛——必须是循环稳定后两者同时为空。

用户看到的交互是树形展开的问答与穿插其间的取证汇报:顶层问题开篇,答案与取证结论交替推进,直到无可再问。

Phase 3:写入设计

按模板 references/dev-design.md 的章节结构写入真实内容,移除占位提示。

  1. 需求:目标与范围边界,含明确的不做什么。
  2. 现状摘要(可选短节):几句话给出现状核心结论——现有实现怎么满足(或不满足)本次需求、关键改造点在哪、有无架构基线;作为方案推理的起点。改动完全不涉及现有代码时可省略本节。
  3. 方案:明确选择,不能停留在"可以 A 也可以 B";备选方案写明选了哪个、为什么;基于现状与取证结论推导,其中的代码论断带 file:line。
  4. 契约变更:新增/修改的接口、数据结构、配置、错误码、CLI 参数等,逐项写全名称、位置、签名/字段、类型、调用方、错误语义、兼容策略;"位置""调用方"等现状论断带引用。下游 task-dev 直接照此实现,含糊即返工。
  5. 影响面:列出实际要改动的文件路径,逐项标注改动性质;路径必须经取证确认,不写猜测路径。
  6. 验收标准:需求侧验收口径,每条可执行、可判定(验证什么、怎么验证、预期结果),覆盖需求的全部目标。工程用例由 dev-test-design 基于本章承接,这里不展开测试设计。
  7. 存疑:仍未解决、影响实现或验证的问题;没有则省略。

Phase 4:自检

按「自检清单」逐项核对,不通过则补齐后再交付。

文档结构

# {需求名称} · dev 设计
## 1. 需求            —— 目标、范围边界、不做什么
## 2. 现状摘要        —— 可选短节:几句话现状结论(含无架构基线说明)
## 3. 方案            —— 明确方案选择与理由,代码论断内联 file:line
## 4. 契约变更        —— 逐项写全(无则省略该节)
## 5. 影响面          —— 经取证确认的文件路径
## 6. 验收标准        —— 需求侧验收口径,可执行可判定
## 7. 存疑            —— 未决问题(无则省略)

文档边界

必须写入

  • 需求目标与范围边界(含明确的不做什么);
  • 涉及现有代码时的现状结论(内联于方案、契约变更、影响面,带 file:line);
  • 选定方案及关键决策理由;
  • 契约变更(接口、数据结构、配置、错误码、CLI 参数等);
  • 影响的文件或模块;
  • 可判定的验收标准(需求口径);
  • 存疑项(如有)。

不要写入

  • 逐行代码实现或完整代码块(片段示意可以,整段实现不行);
  • 集中堆放的全量取证附录——引用写在用到它的位置;
  • 与本次需求无关的模块全景分析;
  • 从模板抄来的空章节;
  • 未经代码确认的推测性结论。

自检清单

  • [ ] 只生成或更新了 dev-design.md,没有产出其它设计文档。
  • [ ] 问题池循环已收敛:无待查代码问题、无可问用户决策。
  • [ ] 方案、契约变更、影响面中关于现有代码的论断均带 file:line 或明确定位,可回溯。
  • [ ] 取证按批进行且每批有明确问题清单(SubAgent 委托或主进程只读降级均可,引用要求一致)。
  • [ ] 涉及现有代码的改动已写现状摘要;无架构基线时已在摘要中记录。
  • [ ] 提问按轮次制:一轮抛全部当前前沿、各带 ➡️ 推荐、逐题等用户表态,未默认采纳任何推荐。
  • [ ] 方案是明确选择,不存在未决的"可选方案"。
  • [ ] 契约变更逐项写全,下游可直接照此实现。
  • [ ] 验收标准可执行、可判定,覆盖需求的全部目标。
  • [ ] 影响文件路径经过取证确认,不是猜测。
  • [ ] 没有影响实现或验证的存疑项;确实存在的已明确记录并告知用户。
  • [ ] 移除了全部模板占位提示。

完成条件

  • dev-design.md 存在且通过自检;
  • 问题池循环已收敛(代码问题与用户决策均清零);
  • 不存在阻断实现的存疑;
  • 用户已确认设计方向,或成果明确标记为草案。

04 同仓库更多 Skills

pi-ixel
pi-ixel/Awesome-Agent-Workflow

task-split

基于已确认的设计与测试规格,生成单文件薄任务计划 tasks-overview.md;任务只保留目标、范围、权威设计/测试引用、依赖和状态,不复制或改写设计正文。Use when the user asks for 任务拆分、开发任务规划、有序任务计划、task split,或希望把已评审设计组织为可串行调度的 T1/T2 任务。支持两种模式:严格模式以详细设计文档、测试用例设计文档和通过的模块设计门禁结果为输入;轻量模式以 dev-design.md 与 test-design.md 两份文档为输入,由调用方说明。

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

task-dev

实现一个明确的 T[N] 任务并把它做完:按已评审设计实现与测试,两路只读语义 Review,修复与重验,代码检查,写交接记录与候选提交信息。Use when the user asks to 实现当前 Task、执行 task-dev、继续或恢复 T1/T2 开发。支持严格模式(以模块详细设计与测试用例设计为事实来源)与轻量模式(以 dev-design.md 与 test-design.md 为事实来源)。每次只处理一个 Task,不执行 git add 或 git commit,也不自行开始下一个 Task。

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

sr-design

帮助开发者创建功能/模块设计文档。用户描述系统整体要做什么,你负责研究代码仓库, 确定如何调整内部结构来实现目标,并通过逐题澄清消除所有不确定细节。 文档聚焦软件架构、功能设计与模块设计,而非代码实现细节。

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

sr-design-gate

对 SR-design.md 进行设计质量门禁,检查需求范围、架构边界、接口与数据契约、验收闭环、风险处置、图表变更表达以及文档跨章节一致性。用于 SR 设计完成后、进入 ar-split 前判断 SR 级设计是否完整,并输出通过、不通过或阻塞结论。

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

repo-init

Use when the user asks for 软件实现设计/software_architect/初始化代码仓/sdd/初始化/init/更新代码仓软件架构/更新代码仓软件实现设计.

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

module-tobe-design

基于调用方指定的正式《模块详细设计说明书.md》及模块目录下的 `.context/详细设计上下文.md`,设计模块内与本次需求相关的 TOBE 详细方案。TOBE 是唯一可以编辑正式说明书的阶段,必须按正式大纲写入需求背景、外部依赖、整体方案、模块详细方案、对外接口、数据库/表设计、受影响模块与交互、关键契约清单和附录/三方件约束。TOBE 只负责目标设计和可测试性输入,不生成测试用例,不拆分 AICoding 任务;测试用例设计交由 `$module-test-design`,编码任务拆分交由外部 AICoding 流程。详细设计上下文记录 ASIS 证据、TOBE 推导和过程,不得替代正式说明书。不得脱离 ASIS 证据凭空设计;ASIS context 缺失或不足时必须回补 ASIS 或标记阻塞。

★ 9