Druid 项目 OpenSpec 上手指南一次完整的变更工作流周期是怎么跑完的【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid本篇以仓库中的 OPSX: Onboard 引导文档 为主体讲解 OpenSpec 在 Druid 项目中的完整工作流从预检初始化、任务选择到 proposal → specs → design → tasks 四类工件的编写、实施与归档。读完后你可以照着这条 11 个阶段的节奏在真实代码库上独立跑通第一个 OpenSpec 变更周期并能结合 openspec/ 目录下真实归档的变更如 2026-05-12-fix-grouping-sets-comma理解每个工件在 Druid 这样的 Java 大型项目中究竟长什么样。1. Onboard 的定位边做边学的完整周期引导onboard.md 是一份教学型工作流命令定义它不是让 AI 替你干活而是在你的代码库上执行真实任务的同时讲解每一步原文This is a teaching experience—youll do real work in their codebase while explaining each step。整个引导覆盖一个完整变更周期在代码库中挑选一个小的真实任务简要探索问题创建一个 change工作的容器构建四类工件proposal → specs → design → tasks实施 tasks归档已完成的变更文档预估耗时 15–20 分钟。它的核心教学法是EXPLAIN → DO → SHOW → PAUSE模式在关键节点先讲解EXPLAIN、再执行DO、展示结果SHOW、等待用户确认PAUSE。这套引导所教的就是 Druid 仓库中openspec/目录的实际运作方式——该目录下 specs/ 存放五大架构能力基线sql-parser-core、connection-pool-core、filter-chain、wall-security、monitoring-statchanges/ 存放进行中的变更changes/archive/ 已归档了十余个真实变更例如 2026-02-13-dialect-registration-mechanism、2026-05-12-fix-grouping-sets-comma。2. Preflight开始前先检查 OpenSpec 是否已初始化引导的第一步是预检Preflight执行以下命令确认 OpenSpec 已初始化openspec status --json 21 || echo NOT_INITIALIZED如果未初始化流程会明确停止并提示OpenSpec isnt set up in this project yet. Runopenspec initfirst, then come back to/opsx:onboard.这一前置检查保证后续所有openspec new change、openspec archive等命令有可操作的对象。在 Druid 仓库中初始化后的状态由 openspec/config.yaml 承载——其中声明了schema: spec-driven并通过context字段注入了项目上下文Druid 的多模块结构core、三个 Spring Boot starter、druid-wrapper、druid-demo-petclinic、Checkstyle 规则、命名规范、测试约定以及五大能力基线 spec 位于openspec/specs/、变更须通过openspec/changes/change-name/specs/capability/spec.md的 delta spec 演进这一关键约定。3. Phase 1–2欢迎与任务选择含范围护栏Phase 1Welcome向用户预告整个周期要做什么即上文的 6 步清单并声明让我们先找点事干。Phase 2Task Selection是引导中最具工程判断的一环包含三个要点3.1 代码库扫描寻找小而真实的改进点文档要求扫描代码库中适合入门的改进机会具体查找六类信号TODO/FIXME 注释—— 在代码文件中搜索TODO、FIXME、HACK、XXX缺失的错误处理—— 吞掉错误的catch块、没有 try-catch 保护的高风险操作没有测试覆盖的函数—— 将src/与测试目录交叉比对类型问题—— TypeScript 文件中的any类型: any、as any调试残留—— 非调试代码中的console.log、console.debug、debugger缺失的输入校验—— 没有校验的用户输入处理同时检查近期 git 活动辅助判断热点区域git log --oneline -10 2/dev/null || echo No git history说明上述六类信号是通用扫描清单源自该命令的通用模板其中any类型、console.log等条目面向 JavaScript/TypeScript 生态在 Druid 这类 Java 仓库中实际落地时主要信号是 TODO/FIXME、缺失测试与错误处理其余条目可视为不适用。3.2 呈现 3–4 个具体建议分析后引导会给出 3–4 个带位置、范围和工作量估算的建议例如**1. [最有希望的任务]** Location: src/path/to/file.ts:42 Scope: ~1-2 files, ~20-30 lines Why its good: [简短理由] **2. [第二个任务]** ... **4. Something else?** Tell me what youd like to work on.如果扫描无果则回退为直接询问用户I didnt find obvious quick wins in your codebase. Whats something small youve been meaning to add or fix?3.3 Scope Guardrail范围护栏如果用户挑选或描述了一个过大的任务大功能、多日工作量引导会给出软性护栏而非硬性拒绝Slice it smaller—— 把任务切得更小先做最小可用的一片Pick something else—— 换另一个更小的任务Do it anyway—— 坚持要做也可以只是会花更长时间文档明确这是soft guardrail用户坚持时可放行。这背后的教学逻辑是——学习工作流时smaller is better小任务能让你完整看到整个周期而不陷入实现细节。4. Phase 3Explore Demo——创建变更前先思考选定任务后Phase 3 先演示explore mode探索模式在提交任何方向之前花 1–2 分钟调查相关代码——读相关文件、必要时画一个 ASCII 示意图、记下注意点。产出格式为## Quick Exploration [简短分析——发现了什么、有哪些考量] ┌─────────────────────────────────────────┐ │ [Optional: ASCII diagram if helpful] │ └─────────────────────────────────────────┘文档强调explore mode/opsx:explore就是为这类先调查后实施的思考准备的任何时候都可以用。此阶段结束后有一个PAUSE节点——等待用户确认后再继续。对应到 Druid 仓库这一步思考的对象往往是 openspec/config.yaml 中rules字段约束的维度线程安全DruidDataSource is heavily concurrent、filter chain 集成、MBean 变更影响、性能基准MySqlPerf*测试的前后对比等。5. Phase 4创建 Change——工件的容器Phase 4 讲解核心概念A change in OpenSpec is a container for all the thinking and planning around a piece of work. It lives inopenspec/changes/name/and holds your artifacts—proposal, specs, design, tasks.然后用一个派生出的 kebab-case 名称创建变更openspec new change derived-name创建后的目录结构为openspec/changes/name/ ├── proposal.md ← Why were doing this空待填 ├── design.md ← How well build it空 ├── specs/ ← Detailed requirements空 └── tasks.md ← Implementation checklist空Druid 仓库中的归档变更正是这个结构的真实实例。以 2026-05-12-fix-grouping-sets-comma 为例归档后目录内包含proposal.md、design.md、specs/、tasks.md四个工件另一个更复杂的变更 2026-02-13-dialect-registration-mechanism 还额外带有多能力 delta spec。6. Phase 5–8四类工件的编写方法与模板Onboard 文档的 Phase 5 至 Phase 8 分别对应四类工件每类工件都定义了它回答什么问题和内容骨架。这里逐一继承原文档的模板并结合 Druid 仓库的 openspec/templates/ 与真实归档工件补充细节。6.1 Proposal回答 WHY 与高层 WHATProposal 是这个变更的电梯演讲——捕获为什么要做、高层面上改了什么。文档给出的草稿骨架为## Why [1-2 句话解释问题/机会] ## What Changes [要点列表哪些会不一样] ## Capabilities ### New Capabilities - capability-name: [简要描述] ### Modified Capabilities !-- 若修改既有行为 -- ## Impact - src/path/to/file.ts: [什么变化]草稿呈现后PAUSE等待用户认可然后保存openspec instructions proposal --change name --json再把内容写入openspec/changes/name/proposal.md并提示This is your why document—you can always come back and refine it as understanding evolves.在 Druid 仓库中proposal 被 openspec/config.yaml 的rules.proposal进一步约束必须说明受影响的模块core、starter 等、变更类型feature/enhancement/bug fix/refactoring、向后兼容性影响并列出受影响的公开 API。对应的 proposal 模板 比 onboard 文档的骨架更完整包含Change Type勾选 Feature/Enhancement/Bug Fix 等、Affected Modules勾选六个模块、API ChangesNew/Changed/Deprecated 三类、Impact向后兼容、性能影响、依赖等段落。真实样例——GROUPING SETS 逗号修复的 proposal 展示了这些段落如何落地Why部分直接贴了可复现的 Java 代码和错误输出GROUP BY a, GROUPING SETS(...)经 parse emit 往返后逗号丢失What Changes列出 ASTSQLGroupingSetExpr增加hasPrefixComma字段、ParserSQLSelectParser.parseGroupBy追踪逗号消耗、Output visitorSQLASTOutputVisitor按标志输出逗号三层协同变更Impact中论证了默认值true如何保持向后兼容。6.2 Specs用 WHEN/THEN 把 WHAT 写成可测试需求Specs 用精确、可测试的语言定义构建什么采用 requirement/scenario 格式。文档给出的骨架为## ADDED Requirements ### Requirement: Name 系统应该做什么 #### Scenario: Scenario name - **WHEN** 触发条件 - **THEN** 期望结果 - **AND** 附加结果如有文档特别点出This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.这种格式让需求可以直接读成测试用例。保存路径为openspec/changes/name/specs/capability/spec.md先mkdir -p创建目录。Druid 的 config.yaml 对 specs 有专门规则主 spec 位于openspec/specs/capability/spec.md且必须保持稳定基线变更只能写 delta spec重构类变更要写行为等价场景AST/test parity而非实现细节必须覆盖边界情况null 处理、空输入、并发访问涉及DruidDataSource时必须考虑线程安全。真实 delta spec 样例见 fix-grouping-sets-comma 的 spec一条GROUP BY GROUPING SETS Separator PreservationRequirement 下挂了 6 个 Scenario——逗号保留、无逗号保留、GROUPING SETS 作为唯一项不输出前导逗号、编程式构造 AST 默认走逗号形态、equals/hashCode反映分隔符差异、clone()保留标志位。每个 Scenario 都用 GIVEN/WHEN/THEN/AND 写成了可直接转写成断言的形式。6.3 Design回答 HOW——技术决策与权衡Design 捕获怎么构建技术决策、权衡、方案。文档强调For small changes, this might be brief. Thats fine—not every change needs deep design discussion.草稿骨架为## Context [当前状态的简短背景] ## Goals / Non-Goals **Goals:** - [要达成什么] **Non-Goals:** - [明确不做什么] ## Decisions ### Decision 1: [关键决策] [方案与理由]保存路径为openspec/changes/name/design.md。Druid 的 config.yamlrules.design补充了复杂变更应附类图或流程图、修改 core 时考虑 filter chain 集成、必须处理线程安全、记录新增配置项架构级变更还要包含基于MySqlPerf*基准的前后对比验证计划。design 模板 与更复杂的归档样例 2026-02-13-dialect-registration-mechanism 的 design 可以作为进阶参照。6.4 Tasks把工作拆成驱动实施阶段的 checkboxTasks 是实施清单每个 checkbox 都是 apply 阶段的一个工作单元。文档给出的骨架为## 1. [分类或文件] - [ ] 1.1 [具体任务] - [ ] 1.2 [具体任务] ## 2. Verify - [ ] 2.1 [验证步骤]要求任务小而清晰、按逻辑顺序排列呈现后PAUSE等用户确认准备实施再保存到openspec/changes/name/tasks.md。Druid 仓库的 tasks 模板 把这份清单模板化到了项目级0. Preprocessing架构变更先跑MySqlPerfTest与内存基线、1. Core Implementation、2. Monitoring MBean、3. Spring Boot Integration、4. Testing单测/并发/基准/集成/基线对比、5. Code Qualitycheckstyle、Javadoc、License 头、6. Documentation、7. Build Releasemvn clean install、mvn test、必要时更新 VERSION.java末尾附 Verification Checklist。真实样例 fix-grouping-sets-comma 的 tasks.md 展示了完成态所有任务勾选[x]并且每条测试任务都记录了实际运行的回归测试清单如 11 个 GROUPING SETS 相关测试类全绿、资源夹具回归 15/15 等——这正是每个 checkbox 成为工作单元的具体体现。7. Phase 9Apply——逐项实施并勾选实施阶段遵循固定节奏对每个任务宣布Working on task N: [描述]在代码库中实施变更自然引用 specs/designThe spec says X, so Im doing Y在 tasks.md 中标记完成- [ ]→- [x]简短状态汇报✓ Task N complete文档要求叙述保持轻量dont over-explain every line of code——教学而不说教。全部任务完成后汇报## Implementation Complete All tasks done: - [x] Task 1 - [x] Task 2 ... The change is implemented! One more step—lets archive it.8. Phase 10Archive——归档成为决策历史归档把完成的变更从openspec/changes/移到openspec/changes/archive/YYYY-MM-DD-name/openspec archive name文档对此的阐释值得注意Archived changes become your projects decision history—you can always find them later to understand why something was built a certain way.归档不是清理而是把决策记录沉淀为项目历史。Druid 仓库的 openspec/changes/archive/ 目录就是这句话的实物证据从2026-02-13-dialect-registration-mechanism到2026-05-12-fix-grouping-sets-comma十余个变更带着各自的 proposal/design/specs/tasks 按日期归档任何人翻归档都能回答这个解析行为为什么是这样设计的。归档时 delta spec 会被合入openspec/specs/下的能力基线见 specs/README.md 的 How to Evolve 三步建 change → 写 delta spec → 跑 sync 工作流合并回主 spec。9. Phase 11Recap 与命令速查Onboard 的收尾是一张周期总结表把 8 个动作与 8 个动词对齐步骤含义Explore思考问题New创建 change 容器Proposal捕获 WHYSpecs详细定义 WHATDesign决定 HOWTasks拆分成步骤Apply实施工作Archive保存记录并强调This same rhythm works for any size change—a small fix or a major feature同一节奏适用于任何规模的变更。随后是完整的命令参考表Phase 11 与快速参考两处均给出后者带参数命令作用/opsx:explore工作前/中思考问题不改代码/opsx:new name开始一个新变更逐步走工件/opsx:ff name快速推进一次性创建全部工件/opsx:continue name继续一个已有变更/opsx:apply name实施变更中的 tasks/opsx:verify name验证实施与工件一致/opsx:archive name完成后归档这些命令在仓库中都有一一对应的定义文件explore.md、new.md、ff.md、continue.md、apply.md、verify.md、archive.md另有 bulk-archive.md 与 sync.md 处理批量归档和 spec 同步。建议先读 new.md——它精确刻画了openspec new change之后显示状态 → 取第一个 ready 工件的 instructions → 停下等用户的分步节奏。10. 优雅退出中断与纯查询两种场景Onboard 文档专门设计了两种退出路径原则是never pressure the user to continue绝不给用户压力10.1 用户中途想停提示变更已保存随时可续No problem! Your change is saved at openspec/changes/name/. To pick up where we left off later: - /opsx:continue name - Resume artifact creation - /opsx:apply name - Jump to implementation (if tasks exist) The work wont be lost. Come back whenever youre ready.10.2 用户只要命令参考直接输出上文的命令速查表并退出推荐用/opsx:new开始第一个变更想快就用/opsx:ff。这两种退出设计解释了为什么 OpenSpec 的工件必须落盘到openspec/changes/name/change 目录本身就是断点任何时刻中断都不丢进度。11. Guardrails引导行为的六条护栏文档末尾的 Guardrails 定义了这条引导必须遵守的行为边界也是执行任何 OPSX 命令时应内化的准则遵循 EXPLAIN → DO → SHOW → PAUSE 模式在关键节点explore 之后、proposal 草稿之后、tasks 之后、archive 之后执行实施阶段保持轻量叙述teach without lecturing不跳阶段即使变更很小——目标是教会工作流本身在标记点暂停等待确认但不要过度暂停优雅处理退出绝不施压使用真实代码库任务不模拟、不用假例子温和调整范围引导向小任务靠拢但尊重用户选择12. 对照仓库一个已完成周期的答案卷把 onboard 的 11 个阶段映射回 Druid 仓库的既有产物可以形成一份可核验的答案卷Onboard 阶段仓库中的对应实物Preflightopenspec/config.yamlspec-drivenschema 项目上下文Task Selection真实任务如 GROUPING SETS 逗号回归来自 ODPS 方言的实际问题Create Changeopenspec/changes/name/目录骨架Proposalfix-grouping-sets-comma/proposal.mdSpecs (delta)fix-grouping-sets-comma/specs/sql-parser-core/spec.mdDesignfix-grouping-sets-comma 目录下的 design 工件 所在变更目录Tasksfix-grouping-sets-comma/tasks.md全部勾选并附回归记录Apply代码落点在 SQLGroupingSetExpr.java、SQLSelectParser.java、SQLASTOutputVisitor.java回归测试 OdpsGroupingSetsCommaTest.javaArchiveopenspec/changes/archive/2026-05-12-fix-grouping-sets-comma/ 目录整体这套工件先于代码、决策留档可查的节奏正是 openspec/specs/README.md 所述的能力演进机制的运行方式主 spec 保持稳定基线一切变化先以 delta spec 进入 change实施验证后再经 sync 合回基线。适用前提与限制本文所述命令openspec status、openspec new change、openspec instructions、openspec archive依赖 OpenSpec 命令行工具及其在项目中完成openspec init命令定义文件位于.qoder/commands/opsx/下面向 AI 编程助手的斜杠命令调用方式/opsx:xxx在纯人工操作时对应为手工创建工件目录与文件、按模板填写内容。若你只想直接上手从 openspec/templates/ 的四个模板和 openspec/changes/archive/ 的既有样例读起是最快的理解路径。【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Druid 项目 OpenSpec 上手指南：一次完整的变更工作流周期是怎么跑完的
Druid 项目 OpenSpec 上手指南一次完整的变更工作流周期是怎么跑完的【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid本篇以仓库中的 OPSX: Onboard 引导文档 为主体讲解 OpenSpec 在 Druid 项目中的完整工作流从预检初始化、任务选择到 proposal → specs → design → tasks 四类工件的编写、实施与归档。读完后你可以照着这条 11 个阶段的节奏在真实代码库上独立跑通第一个 OpenSpec 变更周期并能结合 openspec/ 目录下真实归档的变更如 2026-05-12-fix-grouping-sets-comma理解每个工件在 Druid 这样的 Java 大型项目中究竟长什么样。1. Onboard 的定位边做边学的完整周期引导onboard.md 是一份教学型工作流命令定义它不是让 AI 替你干活而是在你的代码库上执行真实任务的同时讲解每一步原文This is a teaching experience—youll do real work in their codebase while explaining each step。整个引导覆盖一个完整变更周期在代码库中挑选一个小的真实任务简要探索问题创建一个 change工作的容器构建四类工件proposal → specs → design → tasks实施 tasks归档已完成的变更文档预估耗时 15–20 分钟。它的核心教学法是EXPLAIN → DO → SHOW → PAUSE模式在关键节点先讲解EXPLAIN、再执行DO、展示结果SHOW、等待用户确认PAUSE。这套引导所教的就是 Druid 仓库中openspec/目录的实际运作方式——该目录下 specs/ 存放五大架构能力基线sql-parser-core、connection-pool-core、filter-chain、wall-security、monitoring-statchanges/ 存放进行中的变更changes/archive/ 已归档了十余个真实变更例如 2026-02-13-dialect-registration-mechanism、2026-05-12-fix-grouping-sets-comma。2. Preflight开始前先检查 OpenSpec 是否已初始化引导的第一步是预检Preflight执行以下命令确认 OpenSpec 已初始化openspec status --json 21 || echo NOT_INITIALIZED如果未初始化流程会明确停止并提示OpenSpec isnt set up in this project yet. Runopenspec initfirst, then come back to/opsx:onboard.这一前置检查保证后续所有openspec new change、openspec archive等命令有可操作的对象。在 Druid 仓库中初始化后的状态由 openspec/config.yaml 承载——其中声明了schema: spec-driven并通过context字段注入了项目上下文Druid 的多模块结构core、三个 Spring Boot starter、druid-wrapper、druid-demo-petclinic、Checkstyle 规则、命名规范、测试约定以及五大能力基线 spec 位于openspec/specs/、变更须通过openspec/changes/change-name/specs/capability/spec.md的 delta spec 演进这一关键约定。3. Phase 1–2欢迎与任务选择含范围护栏Phase 1Welcome向用户预告整个周期要做什么即上文的 6 步清单并声明让我们先找点事干。Phase 2Task Selection是引导中最具工程判断的一环包含三个要点3.1 代码库扫描寻找小而真实的改进点文档要求扫描代码库中适合入门的改进机会具体查找六类信号TODO/FIXME 注释—— 在代码文件中搜索TODO、FIXME、HACK、XXX缺失的错误处理—— 吞掉错误的catch块、没有 try-catch 保护的高风险操作没有测试覆盖的函数—— 将src/与测试目录交叉比对类型问题—— TypeScript 文件中的any类型: any、as any调试残留—— 非调试代码中的console.log、console.debug、debugger缺失的输入校验—— 没有校验的用户输入处理同时检查近期 git 活动辅助判断热点区域git log --oneline -10 2/dev/null || echo No git history说明上述六类信号是通用扫描清单源自该命令的通用模板其中any类型、console.log等条目面向 JavaScript/TypeScript 生态在 Druid 这类 Java 仓库中实际落地时主要信号是 TODO/FIXME、缺失测试与错误处理其余条目可视为不适用。3.2 呈现 3–4 个具体建议分析后引导会给出 3–4 个带位置、范围和工作量估算的建议例如**1. [最有希望的任务]** Location: src/path/to/file.ts:42 Scope: ~1-2 files, ~20-30 lines Why its good: [简短理由] **2. [第二个任务]** ... **4. Something else?** Tell me what youd like to work on.如果扫描无果则回退为直接询问用户I didnt find obvious quick wins in your codebase. Whats something small youve been meaning to add or fix?3.3 Scope Guardrail范围护栏如果用户挑选或描述了一个过大的任务大功能、多日工作量引导会给出软性护栏而非硬性拒绝Slice it smaller—— 把任务切得更小先做最小可用的一片Pick something else—— 换另一个更小的任务Do it anyway—— 坚持要做也可以只是会花更长时间文档明确这是soft guardrail用户坚持时可放行。这背后的教学逻辑是——学习工作流时smaller is better小任务能让你完整看到整个周期而不陷入实现细节。4. Phase 3Explore Demo——创建变更前先思考选定任务后Phase 3 先演示explore mode探索模式在提交任何方向之前花 1–2 分钟调查相关代码——读相关文件、必要时画一个 ASCII 示意图、记下注意点。产出格式为## Quick Exploration [简短分析——发现了什么、有哪些考量] ┌─────────────────────────────────────────┐ │ [Optional: ASCII diagram if helpful] │ └─────────────────────────────────────────┘文档强调explore mode/opsx:explore就是为这类先调查后实施的思考准备的任何时候都可以用。此阶段结束后有一个PAUSE节点——等待用户确认后再继续。对应到 Druid 仓库这一步思考的对象往往是 openspec/config.yaml 中rules字段约束的维度线程安全DruidDataSource is heavily concurrent、filter chain 集成、MBean 变更影响、性能基准MySqlPerf*测试的前后对比等。5. Phase 4创建 Change——工件的容器Phase 4 讲解核心概念A change in OpenSpec is a container for all the thinking and planning around a piece of work. It lives inopenspec/changes/name/and holds your artifacts—proposal, specs, design, tasks.然后用一个派生出的 kebab-case 名称创建变更openspec new change derived-name创建后的目录结构为openspec/changes/name/ ├── proposal.md ← Why were doing this空待填 ├── design.md ← How well build it空 ├── specs/ ← Detailed requirements空 └── tasks.md ← Implementation checklist空Druid 仓库中的归档变更正是这个结构的真实实例。以 2026-05-12-fix-grouping-sets-comma 为例归档后目录内包含proposal.md、design.md、specs/、tasks.md四个工件另一个更复杂的变更 2026-02-13-dialect-registration-mechanism 还额外带有多能力 delta spec。6. Phase 5–8四类工件的编写方法与模板Onboard 文档的 Phase 5 至 Phase 8 分别对应四类工件每类工件都定义了它回答什么问题和内容骨架。这里逐一继承原文档的模板并结合 Druid 仓库的 openspec/templates/ 与真实归档工件补充细节。6.1 Proposal回答 WHY 与高层 WHATProposal 是这个变更的电梯演讲——捕获为什么要做、高层面上改了什么。文档给出的草稿骨架为## Why [1-2 句话解释问题/机会] ## What Changes [要点列表哪些会不一样] ## Capabilities ### New Capabilities - capability-name: [简要描述] ### Modified Capabilities !-- 若修改既有行为 -- ## Impact - src/path/to/file.ts: [什么变化]草稿呈现后PAUSE等待用户认可然后保存openspec instructions proposal --change name --json再把内容写入openspec/changes/name/proposal.md并提示This is your why document—you can always come back and refine it as understanding evolves.在 Druid 仓库中proposal 被 openspec/config.yaml 的rules.proposal进一步约束必须说明受影响的模块core、starter 等、变更类型feature/enhancement/bug fix/refactoring、向后兼容性影响并列出受影响的公开 API。对应的 proposal 模板 比 onboard 文档的骨架更完整包含Change Type勾选 Feature/Enhancement/Bug Fix 等、Affected Modules勾选六个模块、API ChangesNew/Changed/Deprecated 三类、Impact向后兼容、性能影响、依赖等段落。真实样例——GROUPING SETS 逗号修复的 proposal 展示了这些段落如何落地Why部分直接贴了可复现的 Java 代码和错误输出GROUP BY a, GROUPING SETS(...)经 parse emit 往返后逗号丢失What Changes列出 ASTSQLGroupingSetExpr增加hasPrefixComma字段、ParserSQLSelectParser.parseGroupBy追踪逗号消耗、Output visitorSQLASTOutputVisitor按标志输出逗号三层协同变更Impact中论证了默认值true如何保持向后兼容。6.2 Specs用 WHEN/THEN 把 WHAT 写成可测试需求Specs 用精确、可测试的语言定义构建什么采用 requirement/scenario 格式。文档给出的骨架为## ADDED Requirements ### Requirement: Name 系统应该做什么 #### Scenario: Scenario name - **WHEN** 触发条件 - **THEN** 期望结果 - **AND** 附加结果如有文档特别点出This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.这种格式让需求可以直接读成测试用例。保存路径为openspec/changes/name/specs/capability/spec.md先mkdir -p创建目录。Druid 的 config.yaml 对 specs 有专门规则主 spec 位于openspec/specs/capability/spec.md且必须保持稳定基线变更只能写 delta spec重构类变更要写行为等价场景AST/test parity而非实现细节必须覆盖边界情况null 处理、空输入、并发访问涉及DruidDataSource时必须考虑线程安全。真实 delta spec 样例见 fix-grouping-sets-comma 的 spec一条GROUP BY GROUPING SETS Separator PreservationRequirement 下挂了 6 个 Scenario——逗号保留、无逗号保留、GROUPING SETS 作为唯一项不输出前导逗号、编程式构造 AST 默认走逗号形态、equals/hashCode反映分隔符差异、clone()保留标志位。每个 Scenario 都用 GIVEN/WHEN/THEN/AND 写成了可直接转写成断言的形式。6.3 Design回答 HOW——技术决策与权衡Design 捕获怎么构建技术决策、权衡、方案。文档强调For small changes, this might be brief. Thats fine—not every change needs deep design discussion.草稿骨架为## Context [当前状态的简短背景] ## Goals / Non-Goals **Goals:** - [要达成什么] **Non-Goals:** - [明确不做什么] ## Decisions ### Decision 1: [关键决策] [方案与理由]保存路径为openspec/changes/name/design.md。Druid 的 config.yamlrules.design补充了复杂变更应附类图或流程图、修改 core 时考虑 filter chain 集成、必须处理线程安全、记录新增配置项架构级变更还要包含基于MySqlPerf*基准的前后对比验证计划。design 模板 与更复杂的归档样例 2026-02-13-dialect-registration-mechanism 的 design 可以作为进阶参照。6.4 Tasks把工作拆成驱动实施阶段的 checkboxTasks 是实施清单每个 checkbox 都是 apply 阶段的一个工作单元。文档给出的骨架为## 1. [分类或文件] - [ ] 1.1 [具体任务] - [ ] 1.2 [具体任务] ## 2. Verify - [ ] 2.1 [验证步骤]要求任务小而清晰、按逻辑顺序排列呈现后PAUSE等用户确认准备实施再保存到openspec/changes/name/tasks.md。Druid 仓库的 tasks 模板 把这份清单模板化到了项目级0. Preprocessing架构变更先跑MySqlPerfTest与内存基线、1. Core Implementation、2. Monitoring MBean、3. Spring Boot Integration、4. Testing单测/并发/基准/集成/基线对比、5. Code Qualitycheckstyle、Javadoc、License 头、6. Documentation、7. Build Releasemvn clean install、mvn test、必要时更新 VERSION.java末尾附 Verification Checklist。真实样例 fix-grouping-sets-comma 的 tasks.md 展示了完成态所有任务勾选[x]并且每条测试任务都记录了实际运行的回归测试清单如 11 个 GROUPING SETS 相关测试类全绿、资源夹具回归 15/15 等——这正是每个 checkbox 成为工作单元的具体体现。7. Phase 9Apply——逐项实施并勾选实施阶段遵循固定节奏对每个任务宣布Working on task N: [描述]在代码库中实施变更自然引用 specs/designThe spec says X, so Im doing Y在 tasks.md 中标记完成- [ ]→- [x]简短状态汇报✓ Task N complete文档要求叙述保持轻量dont over-explain every line of code——教学而不说教。全部任务完成后汇报## Implementation Complete All tasks done: - [x] Task 1 - [x] Task 2 ... The change is implemented! One more step—lets archive it.8. Phase 10Archive——归档成为决策历史归档把完成的变更从openspec/changes/移到openspec/changes/archive/YYYY-MM-DD-name/openspec archive name文档对此的阐释值得注意Archived changes become your projects decision history—you can always find them later to understand why something was built a certain way.归档不是清理而是把决策记录沉淀为项目历史。Druid 仓库的 openspec/changes/archive/ 目录就是这句话的实物证据从2026-02-13-dialect-registration-mechanism到2026-05-12-fix-grouping-sets-comma十余个变更带着各自的 proposal/design/specs/tasks 按日期归档任何人翻归档都能回答这个解析行为为什么是这样设计的。归档时 delta spec 会被合入openspec/specs/下的能力基线见 specs/README.md 的 How to Evolve 三步建 change → 写 delta spec → 跑 sync 工作流合并回主 spec。9. Phase 11Recap 与命令速查Onboard 的收尾是一张周期总结表把 8 个动作与 8 个动词对齐步骤含义Explore思考问题New创建 change 容器Proposal捕获 WHYSpecs详细定义 WHATDesign决定 HOWTasks拆分成步骤Apply实施工作Archive保存记录并强调This same rhythm works for any size change—a small fix or a major feature同一节奏适用于任何规模的变更。随后是完整的命令参考表Phase 11 与快速参考两处均给出后者带参数命令作用/opsx:explore工作前/中思考问题不改代码/opsx:new name开始一个新变更逐步走工件/opsx:ff name快速推进一次性创建全部工件/opsx:continue name继续一个已有变更/opsx:apply name实施变更中的 tasks/opsx:verify name验证实施与工件一致/opsx:archive name完成后归档这些命令在仓库中都有一一对应的定义文件explore.md、new.md、ff.md、continue.md、apply.md、verify.md、archive.md另有 bulk-archive.md 与 sync.md 处理批量归档和 spec 同步。建议先读 new.md——它精确刻画了openspec new change之后显示状态 → 取第一个 ready 工件的 instructions → 停下等用户的分步节奏。10. 优雅退出中断与纯查询两种场景Onboard 文档专门设计了两种退出路径原则是never pressure the user to continue绝不给用户压力10.1 用户中途想停提示变更已保存随时可续No problem! Your change is saved at openspec/changes/name/. To pick up where we left off later: - /opsx:continue name - Resume artifact creation - /opsx:apply name - Jump to implementation (if tasks exist) The work wont be lost. Come back whenever youre ready.10.2 用户只要命令参考直接输出上文的命令速查表并退出推荐用/opsx:new开始第一个变更想快就用/opsx:ff。这两种退出设计解释了为什么 OpenSpec 的工件必须落盘到openspec/changes/name/change 目录本身就是断点任何时刻中断都不丢进度。11. Guardrails引导行为的六条护栏文档末尾的 Guardrails 定义了这条引导必须遵守的行为边界也是执行任何 OPSX 命令时应内化的准则遵循 EXPLAIN → DO → SHOW → PAUSE 模式在关键节点explore 之后、proposal 草稿之后、tasks 之后、archive 之后执行实施阶段保持轻量叙述teach without lecturing不跳阶段即使变更很小——目标是教会工作流本身在标记点暂停等待确认但不要过度暂停优雅处理退出绝不施压使用真实代码库任务不模拟、不用假例子温和调整范围引导向小任务靠拢但尊重用户选择12. 对照仓库一个已完成周期的答案卷把 onboard 的 11 个阶段映射回 Druid 仓库的既有产物可以形成一份可核验的答案卷Onboard 阶段仓库中的对应实物Preflightopenspec/config.yamlspec-drivenschema 项目上下文Task Selection真实任务如 GROUPING SETS 逗号回归来自 ODPS 方言的实际问题Create Changeopenspec/changes/name/目录骨架Proposalfix-grouping-sets-comma/proposal.mdSpecs (delta)fix-grouping-sets-comma/specs/sql-parser-core/spec.mdDesignfix-grouping-sets-comma 目录下的 design 工件 所在变更目录Tasksfix-grouping-sets-comma/tasks.md全部勾选并附回归记录Apply代码落点在 SQLGroupingSetExpr.java、SQLSelectParser.java、SQLASTOutputVisitor.java回归测试 OdpsGroupingSetsCommaTest.javaArchiveopenspec/changes/archive/2026-05-12-fix-grouping-sets-comma/ 目录整体这套工件先于代码、决策留档可查的节奏正是 openspec/specs/README.md 所述的能力演进机制的运行方式主 spec 保持稳定基线一切变化先以 delta spec 进入 change实施验证后再经 sync 合回基线。适用前提与限制本文所述命令openspec status、openspec new change、openspec instructions、openspec archive依赖 OpenSpec 命令行工具及其在项目中完成openspec init命令定义文件位于.qoder/commands/opsx/下面向 AI 编程助手的斜杠命令调用方式/opsx:xxx在纯人工操作时对应为手工创建工件目录与文件、按模板填写内容。若你只想直接上手从 openspec/templates/ 的四个模板和 openspec/changes/archive/ 的既有样例读起是最快的理解路径。【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
