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
- 参考文档references/dev-design.md2.1 KB
03 SKILL.md 正文
若输出文件已存在,仍按当前要求完整执行:先读取并评估已有成果,复用仍有效的信息和已确认答案,可局部修改或整体重写,并写回原路径。
dev-design
定位
本 skill 服务于个人开发者的轻量链路,位于需求确认与测试设计之间。
它用一份文档承担实现设计,目标不是写得更少,而是写得刚好够开发:下游 dev-test-design 要能据此设计用例,task-split 要能据此拆出任务,task-dev 要能据此写出代码和测试。
唯一的档位就是"写得刚好够开发"这一档;篇幅随需求复杂度自然浮动。
唯一成果物:dev-design.md。调用方指定了位置就写到那里;没有指定时,和用户确认存放位置。
设计总原则
- 问题是同一池,出口只有两个:能从代码查证的进取证队列,代码证不出、需用户拍板的进提问队列。两类问题在循环中交替产生、互相解锁,不存在"先问完代码再问人"的固定顺序。
- 取证按批进行,每批带问题清单:攒够一批代码问题再取证,不零散漫游。优先整批委托只读 SubAgent(带回带
file:line的结论报告);当前环境没有 SubAgent 工具时,降级为主进程按清单只读批量取证,引用要求不变。 - 代码论断必须可回溯:设计正文(方案、契约变更、影响面)中每一条关于现有代码的论断都带
file:line或等价的明确定位,写在用到它的位置,不集中堆放附录。 - 提问按设计树轮次:把待人拍板的决策建模成设计树,一轮抛出当前可问的全部问题(tree frontier),各带推荐答案;等用户逐题表态后,前沿外扩再开下一轮。不做"一次问一个",也不做"一次抛所有待解问题"。
- 验收标准写需求口径:每条可判定(验证什么、怎么验证、预期结果);工程侧用例由下游
dev-test-design承接,本文档不展开测试设计。
具体流程
Phase 1:读需求与架构,形成初始问题池
- 读取已有的需求说明(调用方给出的需求原文或
requirement.md)和项目架构基线.sdd/software_architecture.md,两者都是可选,缺失不阻断。 - 基于需求与架构(架构缺失时从需求文本 + 代码结构自行推断探索边界,并在现状摘要中记录"无架构基线")列出初始问题:
- 代码问题:需求映射到哪些代码位置?现有行为、签名、调用链、测试覆盖是什么?有哪些隐藏约束与既有约定?
- 用户问题:范围边界、方案取舍、外部依赖、验收口径中需要用户拍板的事。
- 初始问题池不求全——循环会持续补充;但需求直接映射到的代码位置必须进入第一批取证。
Phase 2:问题池循环(取证 ⇄ 提问)
循环执行直到收敛。每一轮:
- 先处理取证队列:把当前积累的代码问题作为清单,整批取证——
- 有 SubAgent 工具:委托一个只读 SubAgent 按清单探索,要求每条关键结论带
file:line;无法从代码确认的事实在报告中标记"待确认",不写成既定事实。 - 无 SubAgent 工具:主进程按清单只读批量取证,引用要求相同;不偏离清单做无关漫游。
- 取证只覆盖问题清单与本次需求相关的范围,不做无关模块全景取证。
- 有 SubAgent 工具:委托一个只读 SubAgent 按清单探索,要求每条关键结论带
- 消化取证结果:新事实可能解答旧的用户问题(从池中移除)、确认设计可行,也可能引出新问题(按能否自答分流进两个队列)。
- 抛出提问前沿:把提问队列按设计树整理——理清依赖,有些决策只有等另一些定了才可问;计算 frontier(所有前提已满足、现在就能问的决策),一轮全部抛出。每题给
❓ 编号 + 题意,紧跟➡️ 推荐答案;推荐尽量踩在已取得的代码事实上。不逐题硬等,整轮一起抛。 - 逐题等用户表态:每道题必须等用户明确表态后才算定案,不默认采纳推荐;用户明确表示"你决定"时,选择最简单可行的方案并记录该决策及理由。
- 消化用户回答:回答可能解锁新的决策(进入下轮 frontier),也可能引出新的代码问题(回流取证队列)。
收敛判据:取证队列为空(没有待查的代码问题)且提问队列无可问决策(frontier 为空、无遗漏存疑)。某一队列暂时为空不算收敛——必须是循环稳定后两者同时为空。
用户看到的交互是树形展开的问答与穿插其间的取证汇报:顶层问题开篇,答案与取证结论交替推进,直到无可再问。
Phase 3:写入设计
按模板 references/dev-design.md 的章节结构写入真实内容,移除占位提示。
- 需求:目标与范围边界,含明确的不做什么。
- 现状摘要(可选短节):几句话给出现状核心结论——现有实现怎么满足(或不满足)本次需求、关键改造点在哪、有无架构基线;作为方案推理的起点。改动完全不涉及现有代码时可省略本节。
- 方案:明确选择,不能停留在"可以 A 也可以 B";备选方案写明选了哪个、为什么;基于现状与取证结论推导,其中的代码论断带
file:line。 - 契约变更:新增/修改的接口、数据结构、配置、错误码、CLI 参数等,逐项写全名称、位置、签名/字段、类型、调用方、错误语义、兼容策略;"位置""调用方"等现状论断带引用。下游
task-dev直接照此实现,含糊即返工。 - 影响面:列出实际要改动的文件路径,逐项标注改动性质;路径必须经取证确认,不写猜测路径。
- 验收标准:需求侧验收口径,每条可执行、可判定(验证什么、怎么验证、预期结果),覆盖需求的全部目标。工程用例由
dev-test-design基于本章承接,这里不展开测试设计。 - 存疑:仍未解决、影响实现或验证的问题;没有则省略。
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
task-split
基于已确认的设计与测试规格,生成单文件薄任务计划 tasks-overview.md;任务只保留目标、范围、权威设计/测试引用、依赖和状态,不复制或改写设计正文。Use when the user asks for 任务拆分、开发任务规划、有序任务计划、task split,或希望把已评审设计组织为可串行调度的 T1/T2 任务。支持两种模式:严格模式以详细设计文档、测试用例设计文档和通过的模块设计门禁结果为输入;轻量模式以 dev-design.md 与 test-design.md 两份文档为输入,由调用方说明。
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。
sr-design
帮助开发者创建功能/模块设计文档。用户描述系统整体要做什么,你负责研究代码仓库, 确定如何调整内部结构来实现目标,并通过逐题澄清消除所有不确定细节。 文档聚焦软件架构、功能设计与模块设计,而非代码实现细节。
sr-design-gate
对 SR-design.md 进行设计质量门禁,检查需求范围、架构边界、接口与数据契约、验收闭环、风险处置、图表变更表达以及文档跨章节一致性。用于 SR 设计完成后、进入 ar-split 前判断 SR 级设计是否完整,并输出通过、不通过或阻塞结论。
repo-init
Use when the user asks for 软件实现设计/software_architect/初始化代码仓/sdd/初始化/init/更新代码仓软件架构/更新代码仓软件实现设计.
module-tobe-design
基于调用方指定的正式《模块详细设计说明书.md》及模块目录下的 `.context/详细设计上下文.md`,设计模块内与本次需求相关的 TOBE 详细方案。TOBE 是唯一可以编辑正式说明书的阶段,必须按正式大纲写入需求背景、外部依赖、整体方案、模块详细方案、对外接口、数据库/表设计、受影响模块与交互、关键契约清单和附录/三方件约束。TOBE 只负责目标设计和可测试性输入,不生成测试用例,不拆分 AICoding 任务;测试用例设计交由 `$module-test-design`,编码任务拆分交由外部 AICoding 流程。详细设计上下文记录 ASIS 证据、TOBE 推导和过程,不得替代正式说明书。不得脱离 ASIS 证据凭空设计;ASIS context 缺失或不足时必须回补 ASIS 或标记阻塞。