shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringAPI key requirement unconfirmed

数据库需求开发

MiniOB 等数据库项目的需求开发全流程：五阶段只读开发计划（读代码/读需求/调研对标/写计划/评审）、经人工批准后的受限代码实现、测试失败后的根因调试，附阶段门禁脚本。

personAuthor: Seven2SeVenhubOpenAPI
downloadDownload package

数据库需求开发（database-develop）

三阶段总览

| 阶段 | 进入条件 | 允许写入 | 交付物 | |---|---|---|---| | A 规划（默认起点） | 有需求文档 | 仅计划文档 + .dbdev-notes/ | docs/development-plan.md | | B 实现 | 人工已批准计划，且有人工改过的痕迹 | 仅计划点名的文件 | 代码 + docs/implementation-report.md | | C 调试 | 有失败清单（如 docs/fails.md） | 仅缺陷相关源码 | 修复 + 复测结论 |

同一时刻只处于一个阶段。用户意图不明确时先确认阶段，不要顺手写代码。

铁律（全阶段）

  1. 不臆造：需求、特性、验收标准、来源、基准数据、性能数字，一律不编。信息不确定时，明确写成"假设"或"开放问题"，不要当事实陈述。
  2. 验收标准逐字引用：尤其查询时延和内存上限，必须原样摘录，它们是硬约束。
  3. 规划阶段只读：不修改/新建/删除项目内任何既有代码、配置、文档；不实现功能、不执行迁移、不跑任何未经授权的操作。唯一的产出文件是开发计划。
  4. 实现阶段受限：只改计划点名的文件；不 commit、不 push、不发布，除非用户明确授权。
  5. MiniOB 行为对齐 MySQL：动手前先确认该特性在 MySQL 中是否已定义；有则行为严格一致。出现异常行为或冲突时以 MySQL 为准，允许联网查证。
  6. 结论要可溯源：引用官方文档、论文或源码；估算值必须标注"粗略估算"。

开始前：确认输入

  • 需求文档：路径可为多个。缺失时先索要，不要代替用户想象需求。
  • 项目根目录：默认 MiniOB 仓库根（config.json 中 project_root，相对 Skill 目录解析）。
  • 计划输出目录：默认 <project root>/docs，不存在则创建。
  • 当前阶段：A / B / C。

阶段 A：开发计划（五个子阶段，严格按序）

| 子阶段 | 目标 | 产出（工作笔记，非最终交付） | |---|---|---| | 1 读代码 | 摸清框架、构建系统、语言与依赖；模块调用关系与数据流；关键对象/接口；既有约定、不变量、技术债 | 架构与约束摘要 | | 2 读需求 | 逐条列出特性与目的；逐字摘录验收标准；记录技术栈/兼容性/范围约束；标记歧义与缺口 | 需求摘要 + 开放问题清单 | | 3 调研对标 | ≥5 条不同技术路线的可溯源对比；从时延、吞吐、并发、大数据量维度对标本项目现状；健壮性分析；给出优化方向 | 对标分析报告 | | 4 写计划 | 依赖驱动的开发顺序；隐含需求/优化（标注"推断"）；逐特性实现方案 | 计划草稿 | | 5 评审定稿 | 自查完整性、一致性、可行性、不破坏既有架构，修正后定稿 | 最终计划文档 |

每个子阶段完成其交付物后再进入下一个——前一个的输出是后一个的输入。

子阶段的硬性要求（摘录，详见 references/planning.md）：

  • 阶段 1 不得跳过与需求相关的文件；大文件分段读全，不要只读开头。
  • 阶段 3 每条路线都要给出技术选型、核心算法、架构细节，并附真实来源；不同路线指技术方案不同，不是同一方案的参数变体。
  • 阶段 3 的优化建议必须写清：预期收益及其依据、实现成本、适用条件、风险。无公开基准支撑的收益写"粗略估算"。
  • 阶段 4 的开发顺序按依赖关系排，而不是需求文档顺序；每个排序决定都要给理由。经典反例：先做 INSERT 再补 VIEW，之后必须回头重构 INSERT 的可更新性检查（不可接受的返工）；反例之反：先落 LRU 淘汰缓存池，后续复杂查询可直接复用（应提前）。
  • 阶段 4 的隐含需求/优化必须标注「推断（非显式需求）」并引用需求文档中的依据，标记为待人工确认，不得混入强制范围。
  • 阶段 4 每个特性至少写：算法与实现路径、数据结构、要改/新增的文件、要改/新增对象的定义与接口、时间/空间复杂度及"为何是最优、不引入瓶颈与内存浪费"、如何满足阶段 2 的验收标准、阶段 3 中更优方案的出处。
  • 阶段 5 逐项核对：无自相矛盾、无严重性能瓶颈或内存浪费、与既有架构一致且不需大规模重构、推断项与开放问题均已列出待人工决策。

阶段 A 的收尾： 运行 python scripts/main.py check-plan，再运行 python scripts/main.py verify 确认未改动任何既有文件，最后报告计划文件的绝对路径与五个子阶段各产出了什么。

阶段 B：代码实现

  1. 先读被人工调整过的计划文档，明确哪些被改、哪些不变。
  2. 由批准后的设计派生代码级实现计划：每个类/方法的签名、字段、类型、所在文件与模块、算法与数据结构。不得引入批准设计之外的架构或对象。
  3. 严格按实现计划写代码。
  4. 偏差处理：发现计划有遗漏或矛盾时，优先在既有设计内找不改变架构与接口的解法；若唯一可行解需要大规模改动（架构、接口、计划未覆盖的对象），或计划存在无法在自身范围内解决的致命矛盾——立即停止并报告（逐条说明问题、阻塞原因、考虑过的选项），不许静默绕过。
  5. 验证顺序：在 Docker 内按仓库自身构建说明构建 → 跑 CI 测试 → 逐字运行需求文档里的测试语句（不改写、不转述）→ 需要建表/铺数据时，依据需求文档的 DDL、测试语句与验收标准自造，并在报告中写明"造了什么、为什么"。
  6. 实测性能并对照验收目标（时延/内存），报告真实数字，不四舍五入凑达标。
  7. 交付条件四项全绿：编译干净、CI 全过、需求测试语句结果符合预期、实测性能达标。最终消息逐项显式报告。

细节见 references/implementation.md。

阶段 C：调试

  1. 通读失败清单，逐条分类（错误结果 / 崩溃 / 超时 / 断言失败 / OOM），定位涉及用例与源码位置，识别共享根因。
  2. 逐条根因分析：本地尽量复现，追到真正的缺陷，而不是停在症状。
  3. 修复只针对源码，不改测试用例与期望输出；若发现用例或期望输出本身有错，报告并等待确认，不得擅自修改。
  4. 改动最小化，不顺带重构无关代码。
  5. 重测：先跑原失败用例，再跑全量套件/CI；构建与测试命令只能来自仓库文档。若按文档命令无法复现报告中的错误，必须明确说明，不能汇报成功。
  6. 验收：原失败用例全部通过 且 全量干净；逐条列出根因、修复、实测复测结果。任一项未验证或仍失败，就如实说明。

细节见 references/debugging.md。

MiniOB 环境约定（高频踩坑）

  • MySQL 对齐：新增或修正行为前先查 MySQL 是否已定义该行为，一致为准。
  • 编译环境：Windows 上用 WSL 或 Docker；把源码放到 Linux 原生文件系统编译（显著更快），每次改动后同步回 Linux 工作副本。
  • cppjieba：拉取源码并内置进仓库参与编译，禁止用 CMake FetchContent（会编译失败）。
  • 构建/测试命令不得凭记忆：从 build.sh -h、docker/README.md、README.md、CONTRIBUTING.md 等仓库文档里找。本仓库已有 build.sh（init / debug / release / clean）与 docker/docker-compose.yml。

更多环境事实见 references/miniob-environment.md。

工具与配置

config.json（与本 Skill 同级）存项目默认配置，脚本不依赖任何 API Key：

  • project_root：相对 Skill 目录的仓库根，默认 ../../..（Skill 装在 <repo>/.qoder/skills/database-develop）
  • plan_output_dir / plan_filename：计划输出位置
  • notes_dir：临时工作笔记目录（默认仓库根下 .dbdev-notes，不入源码目录）
  • allowed_planning_changes / implementation_allowed_globs：各阶段允许改动的路径
  • plan_required_sections / feature_required_aspects：计划文档校验项
  • build / test_commands：从仓库文档抄录后的固定命令

scripts/main.py（纯标准库，Python 3）：

| 命令 | 用途 | |---|---| | init | 建输出目录与笔记目录、记录文件基线快照、可选按模板生成计划骨架（--scaffold-plan） | | verify | 对比基线，列出被改动/新增/删除的文件并判定是否越界（规划阶段默认用，越界退出码 1） | | check-plan | 校验计划文档章节齐全度、技术路线数量、逐特性要素覆盖、推断项与开放问题 | | report --phase implement\|debug | 生成实现/调试交付报告骨架 |

典型用法：

python scripts/main.py init --scaffold-plan
# 读完代码与需求、写完计划后
python scripts/main.py check-plan
python scripts/main.py verify

汇报格式

  • 阶段 A：计划文件的绝对路径 + 文件名；五个子阶段各自产出的摘要；待人工确认项清单。
  • 阶段 B：改了哪些文件/类/方法；编译结果；CI 结果；需求测试语句结果；实测性能 vs 验收目标。
  • 阶段 C：失败清单表（用例 / 类型 / 根因 / 修复 / 复测结果）+ 全量套件结论。

参考文件

  • references/planning.md — 五阶段开发计划的完整要求与计划文档结构
  • references/implementation.md — 代码实现的派生计划、偏差协议、验证与交付口径
  • references/debugging.md — 失败分类、根因分析、最小修复与重测验收
  • references/miniob-environment.md — MiniOB 构建、Docker、依赖与 MySQL 对齐要点
  • references/plan-template.md — 计划文档骨架（init --scaffold-plan 会复制它）
<!-- OB-S:nivl-aWmD05yCx60U6-Viw -->