spec-design
Skill0 starsChanged 9 days agoMITView on GitHub
根据用户可见口径已经闭环的 requirements.md、项目规范和本系统现有实现,为 OA、采购、审批、台账等业务规格生成与复杂度匹配的 design.md。设计以复用本系统已有能力为基线,同时完整说明复用能力的接入契约和选择规则;Java 项目使用真实类、方法、注解编写 Java 风格伪代码。requirements.md 仍存在用户可见待确认项时停止设计。
9 other projects use a version of this.
Adopted by
Most recently taken up by
- AlexanderGofman/claude-skillstheir own version, first seen Nov 16, 2026
- warrendeanlangeveldt/code-kittheir own version, first seen Nov 15, 2026
- komluk/scaffoldingtheir own version, first seen Nov 15, 2026
- cldanielhernandez/claude-skillstheir own version, first seen Aug 8, 2026
- paoloirrera/ccgraphtheir own version, first seen Aug 4, 2026
- fernandoxavier02/Pipeline-Orchestratortheir own version, first seen Jun 29, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- MagicCube/agentara★ 503same name
- komluk/scaffolding★ 16same name
- alanvaa06/forge-master★ 2same name
- warrendeanlangeveldt/code-kit★ 2same name
- fernandoxavier02/Pipeline-Orchestrator★ 1same name
- paoloirrera/ccgraph★ 1same name
- AlexanderGofman/claude-skills★ 0same name
- cldanielhernandez/claude-skills★ 0same name
- yisean/claude-spec-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- spec-clarificationSkill
- spec-implSkill
- spec-requirementsSkill
- spec-reviewSkill
- spec-tasksSkill
The file
Files
技术设计生成器
<background_information>
- 成功标准:
- 全部新增和修改源代码文件都有明确路径与职责
- 涉及后端数据变更时提供可执行的数据库 DDL
- 核心业务逻辑通过服务伪代码说明规则、分支与事务边界
- 后端复杂流程通过时序图说明调用顺序与异常路径
- 设计与项目规范(rules/)及既有模式对齐
- 文档按轻量、标准、深度三级匹配业务复杂度,不堆砌无关架构内容 </background_information>
<instructions>
## 执行步骤第 1 步:定位规格目录
- 按以下顺序确定目标规格目录:
- 若用户明确提供
spec/下的相对路径,将其作为目标路径。 - 若用户提供完整路径,确认其位于当前项目的
spec/目录下,并转换为相对路径。 - 若用户未提供路径,但当前请求明确指向
spec/下唯一的功能目录,可使用该目录,并向用户说明判断结果。 - 若存在多个候选目录或无法确定目标,不得猜测;在读取材料或写文件前先询问用户。
$1仅作为兼容写法,例如$1=platform/audit,不假设调用环境一定提供位置参数。
- 若用户明确提供
- 将最终确定的相对路径记为
<spec-path>;后续所有输入输出路径均使用spec/<spec-path>/...。 - 本阶段的唯一候选必须包含已确认的
requirements.md;如果用户只调用spec-design且无法确定唯一候选,先询问目标规格目录。
第 2 步:加载上下文
读取全部必要上下文:
spec/<spec-path>/requirements.md、spec/<spec-path>/design.md(如存在)- 读取本 Skill 目录下的
templates/design.md了解文档结构
第 3 步:检查需求完整性
- 检查
requirements.md的页面、接口、权限、流程、状态、异常和验收行为是否已经明确。 - 若文档包含会影响用户行为、页面结果、接口业务契约、权限、流程或验收结果的“待确认”“后续确认”“设计时确认”“开发时确定”等事项,停止设计并返回
spec-requirements关闭阻塞项。 - 只有数据库表、字段类型、索引、API URL、类和组件拆分、文件路径、算法、缓存和基础设施等内部实现事项可以留到设计阶段。
- 若
requirements.md包含“需求完整性结论”,必须确认其中阻塞项为“无”;旧文档没有该章节时,按上述语义逐项检查,不能默认视为完整。 - 不得在
design.md中替需求阶段选择用户可见口径,也不得把需求阻塞项转写为设计待确认项。
第 4 步:本系统探索与设计核对
关键:设计以本系统现有实现和项目规范为基线,不为寻找“更先进方案”做泛化外部调研。
- 判定设计级别:
- 轻量设计:普通 CRUD、单表表单、列表、详情、字典配置或小范围页面调整
- 标准设计:审批或状态流程、功能/数据权限、跨表事务、导入导出、较多业务校验或前后端联动
- 深度设计:外部系统集成、复杂计算、高并发、异步一致性、重大数据迁移或新增关键基础能力
- 采用满足需求的最低级别;不得仅因功能是“全新”就自动升级为深度设计
按固定优先级加载设计依据:
requirements.md和已有design.md- 项目根目录
AGENTS.md、rules/及目标模块规范 - 本系统最相近的页面、接口、DTO、Service、Mapper、Entity、权限和流程实现
- 本系统公共组件、基础服务、数据字典、工作流和数据权限能力
- 构建文件中已使用的依赖及其在本系统中的实际用法
只有 requirements.md 明确涉及外部系统、第三方库或标准协议,且仓库、项目规则和用户材料无法提供可靠契约时,才核实对应官方文档。禁止为了架构选型、最佳实践比较或技术升级进行开放式网络调研。
按设计级别核对本系统:
轻量设计:
- 找到至少一个最相近的现有业务功能,核对页面、接口、DTO、Service、Mapper、权限和流程模式
- 不做外部调研,不创建
research.md,不派发 Sub-Agent - 重点明确页面和接口、文件清单、数据库变更、校验、权限、异常和测试重点
标准设计:
- 深入核对本系统相关模块的状态流程、权限、事务、数据一致性、历史数据兼容和集成点
- 不做外部调研,不创建
research.md;关键设计取舍直接写入design.md
深度设计:
- 全面分析本系统相关模块、公共能力、调用链、性能热点、安全边界、一致性和运维风险
- 外部系统或第三方能力优先读取仓库内适配器、配置、既有调用和用户提供的契约
- 本地资料不足时,只核实需求已明确指定的官方 API、库版本或标准协议,不扩大技术选型范围
- 仅在确实引用外部官方资料时创建
spec/<spec-path>/research.md,记录来源、契约和对设计的影响
- 保留核对结论:
- 复用的现有功能及具体文件
- 与现有模式的差异及理由
- 应遵循或扩展的既有模式
- 集成点与依赖
- 已识别的风险与缓解策略
- 外部契约及其来源(仅适用时)
第 5 步:综合
写设计之前,先对本系统核对结论做设计综合。
- 读取并应用本 Skill 目录下的
rules/design-synthesis.md - 优先采用本系统已有模式;差异只在需求或现有能力无法满足时引入
- 综合结果直接融入
design.md;仅在引用外部官方资料时同步更新research.md
第 6 步:生成设计草稿
- 加载设计模板与规则:
- 读取本 Skill 目录下的
templates/design.md了解结构 - 读取本 Skill 目录下的
rules/design-principles.md了解原则
- 读取本 Skill 目录下的
- 生成设计草稿:
- 遵循本 Skill 目录下
templates/design.md的结构与裁剪说明 - 方案概述:简要说明业务目标、实现范围、排除项、复用能力以及前后端如何协作,不做与当前业务无关的通用架构论述
- 复用能力接入契约(条件必填):只要设计复用平台或公共能力,就必须写清适用场景、接入入口、关键参数/返回、选择规则、事务与调用边界、失败行为、限制和项目语言示例;不得只列能力名称或写“按需复用”
- 轻量设计必备内容:页面和接口、DTO/Entity/Mapper/Service 等文件清单、状态和流程、权限、数据库变更、核心校验、关键异常与测试重点;无关章节直接省略
- 源代码文件清单(必填):分析代码库,列出全部新增和修改文件的具体路径、主要职责和关联需求 ID。每个文件保持单一主要职责;本节直接驱动后续任务拆分
- 数据库 DDL(条件必填):涉及后端持久化结构变更时,提供适配目标数据库的可执行 DDL、字段业务含义、索引依据、历史数据处理与事务边界;纯前端或完全复用现有表时省略
- 核心服务伪代码(条件必填):存在业务判断、状态流转、数据权限、事务编排、聚合计算或跨表写入时,写明入口、校验、关键分支、事务和结果;普通单表 CRUD 省略
- Java 伪代码硬约束:仓库存在
pom.xml或目标实现为 Java 时,伪代码必须使用java代码块和 Java 风格语法,使用代码库中真实存在或本设计文件清单中明确新增的类名、方法名、DTO、Entity、Mapper、Service、异常和注解;必须展示影响行为的@Transactional、AOP/审计/权限等注解。禁止使用function、raise、begin transaction等语言无关伪代码替代 Java 设计 - 复杂流程时序(条件必填):后端复杂业务、跨服务、异步处理、审批流或外部系统集成使用 Mermaid 时序图说明正常路径和主要异常路径;简单查询和保存不画图
- 接口与页面协作(按需):只写实现所需接口、关键入参返回、权限和页面行为,不重复 DDL 或 DTO 的全部字段
- 验证重点与风险(简写):只覆盖核心正常流程、权限/数据边界、关键异常和真实风险
- 融合核对结论:明确复用的现有功能、必要差异和真实风险;只有引用外部官方资料时才在
research.md保留来源与契约 - 若加载上下文时发现已有
design.md,将其作为参考上下文并进入合并模式 - 应用设计规则:路径可落地、DDL 可执行、伪代码可实现、时序清晰、表达简洁
- 生成后写入
spec/<spec-path>/design.md,交由用户或指定评审人确认
- 遵循本 Skill 目录下
第 7 步:提交人工评审
- 不执行自动化设计评审,不调用子代理评审,也不根据内部评审结果自动修复或批准设计
- 将
spec/<spec-path>/design.md交由用户或指定评审人进行人工评审 - 在用户或指定评审人明确表示“评审通过”“确认设计”或同等含义前,不得进入任务生成阶段
- 提示人工重点检查:文件清单是否完整、DDL 是否正确、核心服务伪代码是否覆盖关键规则、复杂流程时序是否清晰,以及权限/数据边界是否遗漏
- 汇总设计中的关键决策、风险与待确认项,帮助人工评审,但不得代替人工给出“通过”结论
- 若人工提出修改意见,更新
design.md;涉及外部契约且存在research.md时同步更新后再次提交人工评审 - 若人工指出真实的需求缺口或歧义,停止定稿并回到业务需求澄清或正式需求阶段
第 8 步:人工确认后定稿
处理人工评审结果:
- 仅当用户或指定评审人明确表示“评审通过”“确认设计”或同等含义时,将设计视为定稿
- 人工确认前,
spec/<spec-path>/design.md是待审草稿;人工确认后,该文件成为正式设计文档 - 若设计引用了外部官方资料,持久化
research.md中的来源、契约和影响
关键约束
- 类型安全:
- 按项目技术栈实施强类型。
- 静态类型语言:定义显式类型/接口,避免不安全的类型转换。
- TypeScript:禁止使用
any;优先精确类型与泛型。 - 动态类型语言:在可用处提供类型标注(如 Python type hints),并在边界处校验输入。
- 清晰记录公共接口与契约,确保跨组件类型安全。
- 需求可追溯 ID:只使用 requirements.md 中定义的数字需求 ID(如 "1.1"、"1.2"、"3.1"、"3.3")。不要发明新 ID,不要使用字母标签。
- 按需裁剪:除“方案概述”和“源代码文件清单”外,其他章节按功能实际情况保留;不得为满足模板而编造后端、数据库或复杂流程。
- 复用优先:优先复用现有页面、DTO、Service、Mapper、权限和流程模式;不得为单个普通业务功能新增通用基础设施。
- 复用不等于省略设计:复用平台或公共能力时,必须检查真实实现及已有设计,完整记录接入契约、选择规则、限制和示例,使本文档能够独立指导接入。
- Java 伪代码:Java 项目必须使用 Java 风格伪代码和真实类型、方法、注解;无法确定真实名称时先继续代码库探索,不得用抽象占位语掩盖缺口。
</instructions>
输出说明
命令执行输出(区别于 design.md 正文):
- 文档:说明
spec/<spec-path>/design.md是否已生成 - 设计级别:说明采用轻量、标准或深度设计及判定依据
- 复用与差异:说明复用的现有功能和必须引入的差异
- 人工评审:明确说明当前为待人工评审或已人工确认,不得宣称自动评审通过
- 下一步动作:待审时提示人工检查并确认;已确认时提示可进入任务生成
- 外部契约:仅在核实外部官方资料并生成或更新
research.md时说明
格式:精炼的 Markdown(200 字以内)——这是命令输出,不是设计文档本身
注:设计文档本体遵循本 Skill 目录下 templates/design.md 的结构。
安全与兜底
异常场景
需求缺失:
- 停止执行:需求文档必须存在
- 提示用户:"未在
spec/<spec-path>/requirements.md找到 requirements.md" - 建议动作:"先运行
$spec-requirements <spec-path>生成需求"
项目规范缺失:
- 警告:"项目
rules/目录为空或缺失——设计可能无法对齐项目标准" - 继续:照常生成,但在输出中注明该限制
需求 ID 非法:
- 停止执行:若 requirements.md 缺少数字 ID 或使用非数字标题(例如"需求 A"),停止并要求先修复 requirements.md。
需求未闭环:
- 停止执行:若 requirements.md 仍有影响用户可见行为或验收结果的未决事项,不生成或更新
design.md。 - 建议动作:返回
$spec-requirements <spec-path>关闭阻塞项并完成人工确认。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

