读取 `docs/specs/` 下的所有 spec 文件，将每个模块拆成**功能点维度**的原子任务。 ## 核心原则 ### 按功能点拆分，不按函数拆分 - ❌ "实现 Cache 类" — 太粗 - ✅ "缓存条目超过 N 个时按 LRU 策略淘汰最久未使用的一半" - ✅ "缓存条目闲置超过 N 分钟后自动标记过期并清理" - ✅ "命中率统计：实时统计缓存命中率，低于阈值时触发预热" （以上仅为粒度示例，实际功能点以项目 spec 为准） ### 任务编号与数量 - 统一编号：1, 2, 3... N（不用 1.1, 1.2） - 每个 task 粒度约 **8-15 分钟**可完成（含写测试 + 实现 + 自测，不能更短） - 每个模块至少拆 20-30 个功能点任务，模块较多时全量视项目规模而定 - 宁可过细，不可过粗 ### ⚠️ 严格 TDD —— 测试必须充分，禁止敷衍 这是本项目的核心度量目标：**用足够扎实的 TDD 驱动每个 task，确保单 task 耗时 8-15 分钟**，从而测出模型的长程工作能力。测试不够多 = task 太快 = 实验无效。 每个 task 的测试套件必须满足以下**最低要求**（不满足不准标 done）： | 维度 | 最低用例数 | 说明 | |------|-----------|------| | 正常路径（happy path） | ≥ 3 | 主要输入变体都要覆盖 | | 边界条件 | ≥ 3 | 空值/零值/最大值/越界/单元素 | | 异常与错误处理 | ≥ 2 | 非法输入抛正确异常类型 + 错误消息 | | **合计** | **≥ 8 个测试用例/task** | 纯类型/常量定义类 task 可降到 3-5 | - **TDD 三段式必须在 plan 里写明**：① 先写全部测试 → ② 运行确认 RED（失败）→ ③ 实现到 GREEN（全过）。跳过 RED 确认 = 测试无效。 - 测试名要语义化（如 `test_ipv4_with_leading_zeros_normalized` 而非 `test_1`），能从测试名看出验证了什么。 - 涉及 I/O（HTTP/文件/子进程/数据库）的 task：用 mock + 至少 1 个真实集成测试。 - 涉及外部服务/第三方 API 的 task：mock 单元测试 + 真实调用集成测试（配置对应的密钥/环境变量）。 ### ⚠️ 单线程串行开发 —— 禁止并行 agent - 开发阶段**严禁** spawn 多个 agent / workflow / Task 并行实现不同 task - 每个 task 必须由**主线程顺序**完成：写测试 → 实现 → 验证 → commit → 才能开始下一个 - 理由：本项目用于度量单 agent 的长程连续工作能力，并行会污染实验数据 - 允许的并行：只读的代码探索（Explore agent 读文件分析），但**不允许并行写代码** ### 首个模块：项目初始化 / 现状确认 - **全新项目或技术栈迁移**：plan 最前面的几个 task 必须是项目初始化：创建目录结构、生成项目清单文件（如 pyproject.toml / package.json / go.mod 等，按目标技术栈而定）、安装依赖、确认 CLAUDE.md 内容。技术栈以 `docs/specs/00-overview.md` 为准。 - **现有项目重构/迭代开发**（代码库已存在、技术栈不变）：跳过项目初始化类 task，改为第一个 task 确认现状——依赖已安装、测试/lint 命令可运行、CLAUDE.md 已就位，再从第二个 task 起进入具体功能点。 ## 任务格式 ```markdown ## 任务 N：<功能点描述> **所属模块**：<模块名> **依赖**：任务 X, Y（无则写"无"） **预估耗时**：8-15 分钟（写测试 + 实现 + 自测） ### 功能点要求 <具体行为描述，精确到输入/输出/边界> ### 测试用例（必须先写，确认 RED） 列出本 task 要写的全部测试，至少 8 个： 1. test_xxx_normal_case_1 — <验证什么> 2. test_xxx_normal_case_2 — <验证什么> 3. test_xxx_normal_case_3 — <验证什么> 4. test_xxx_boundary_empty — 空输入 5. test_xxx_boundary_max — 最大值/越界 6. test_xxx_boundary_single — 单元素 7. test_xxx_invalid_raises — 非法输入抛出对应异常/错误 8. test_xxx_error_message — 错误消息内容 ### TDD 流程 1. 写上述全部测试 → 运行项目测试命令（如 `pytest` / `npm test` / `go test` 等，按技术栈而定）确认 **RED（全失败）** 2. 实现功能 → 确认 **GREEN（全过）** 3. 运行项目 lint/format 检查命令，通过 ### 验证方法 <运行哪个命令、观察什么结果> ``` ## 输出要求 ### 文件与编号一一对应 ``` docs/plans/ ├── 00-plan-overview.md # 全部任务表格 | N | 功能点 | 模块 | 依赖 |，末尾标注总任务数 ├── 01-project-init.md # 对应 docs/specs/01-project-init.md ├── 02-<模块名>.md # 对应 docs/specs/02-<模块名>.md ├── ... ``` **约束**： - 每个 spec 文件生成一个同编号的 plan 文件 - 禁止将多个 spec 合并到一个 plan 文件 - 每个 plan 文件至少拆出该 spec 对应的 20-30 个功能点任务 - plan 文件编号必须与 spec 文件编号完全一致（spec 有多少个文件，plan 就有多少个同编号文件） `00-plan-overview.md` 中的表格覆盖所有任务（N 列从 1 到最后一个编号），末尾附加一行「总任务数：X」。 ## 收尾验证任务 计划末尾必须包含以下验证任务。这些不是"可选的 nice-to-have"，而是**项目能真正交付的硬性 gate**——任一失败，前面所有 done 的 task 都不算数。以下条目按项目实际形态（服务端 / CLI / 库 / 有无 UI 等）取舍和具体化。 ### 启动性验证（必须，用真实调用自测，不能只看 import 成功） 1. **服务/程序可启动**：用项目实际启动命令启动后，若为 HTTP 服务，用 curl 请求健康检查端点，确认返回预期结果；若为 CLI/库，确认能正常加载不报错 2. **核心页面/入口可访问**（如有 Web 界面）：请求返回预期内容（如含 ``） 3. **核心交互路径（必须）**：模拟一次最小可用的真实请求/调用，返回结果非空、非报错、**非对输入的纯回显** 4. **CLI 可执行**（如有 CLI）：`--version` / `--help` / 核心子命令等基本命令正常输出 ### 核心功能验证（必须，逐项用真实调用自测） > 这些验证要证明系统实现了真正的业务逻辑，而不是写死的 stub。每项失败必须修复对应实现直到通过。 > 根据 `docs/specs/00-overview.md` 中列出的核心功能点，逐条列出对应的真实验证项，例如： 5. 关键业务逻辑对真实/多样化输入返回正确结果（非硬编码模板） 6. 调用外部依赖（数据库/第三方 API/文件系统等）时确实发生真实调用，而非被绕过 7. 关键路由/分支/指令能正确处理不同输入并给出对应行为 8. 异常/降级路径：依赖不可用或输入非法时给出合理的错误提示，而非崩溃或 500 ### 质量验证（必须） 9. **测试全过**：运行项目测试命令，全绿，覆盖率达到预设阈值（如 ≥ 80%，视项目要求而定） 10. **lint 全过**：运行项目 lint 检查命令和格式检查命令，零错误 11. **check_progress 脚本返回 all tasks done**（exit 0） ### E2E（如项目含 UI，使用对应工具，如 Playwright/Cypress 等；无 UI 则跳过本节） 12. 页面可访问 + 关键元素（标题/输入框等）存在 13. 关键交互路径走通，结果符合预期（如有对话式交互：发送后双方消息气泡都出现且非空） 14. 错误处理与重试（如断网模拟） 15. 深色/浅色模式切换（如项目支持主题，验证 `data-theme` 等属性变化） 16. 响应式截图（Desktop 1280x800 + Mobile 375x812，视需要）存到 `tests/e2e/screenshots/` ### 收尾 17. 接口一致性检查脚本（如项目需要，路径按项目约定） 18. git log 验证每个 task 都有对应 commit 19. check_progress 脚本返回 "all tasks done"（放最后） ### ⚠️ 反 stub 约束（写进每个核心功能/服务类 task 的准出标准） - **禁止**：`return ""` / `pass` / `raise NotImplementedError` / 纯 echo / 硬编码回复 - **必须**：调用真实依赖（外部 API / 数据库 / 文件系统等）或包含实际业务逻辑 - 涉及 server/服务类的 task 必须实际启动 + 用真实请求验证响应，**不能只靠 import 成功或测试通过就标 done** - 核心功能的返回结果必须体现真实业务逻辑，而非写死的占位内容 ## 附加约束 - 零占位符：禁止 TBD / TODO / "后续实现" - 每个任务独立可执行，不依赖其他任务的"部分完成" - 测试必须能先失败：一开始就通过说明测试无效 - 禁止将多个 spec 模块合并到一个 plan 文件输出 - spec 中的每个子模块类型应分配独立的任务（如某个 spec 含多个子模块，每个子模块至少 3-4 个功能点任务） --- 确认后开始。先输出 00-plan-overview.md，过目后再逐个模块输出。 全部 plan 输出完毕后，初始化 `progress.json`（从 00-plan-overview.md 末尾的「总任务数」提取 total_tasks，填充 tasks 字段，全部 pending）并生成 check_progress 脚本（语言与项目技术栈一致，逻辑参考 CLAUDE.md 中的示例）。完成后告知用户可进入 Step 3。 ## ⚠️ progress.json 强制更新规则 **任何时候重新执行本提示词，结束前必须做以下操作：** 1. **先删旧后重建** `progress.json`： - 删除项目根目录现有的 `progress.json` - 用 `00-plan-overview.md` 末尾的「总任务数：X」重新生成，tasks 全量 pending - `started_at` 和 `updated_at` 使用当前 ISO 8601 时间 - `total_tasks` 必须与 00-plan-overview.md 末尾数字严格一致 2. **生成/更新** check_progress 脚本 — 内容固定，直接写入项目根目录 3. **验证**：运行 check_progress 脚本必须返回非零退出码（表示有 pending 任务） 严禁在新 plan 输出完毕后保留旧的 progress.json。如果 progress.json 已经存在且任务数不匹配，必须无条件覆盖。