结构化任务规划方法论：Dillinger 仓库 plan-writing 技能详解与实战验证

本文以仓库内 .agent/skills/plan-writing/SKILL.md 为核心骨架，系统讲解结构化任务规划（plan-writing）技能的任务拆解原则、规划纪律、计划文件结构与验证标准；并以 Dillinger 仓库中真实落地的 Next.js 迁移计划、任务追踪清单与 /plan 工作流为佐证，展示该框架如何在多步骤工程（功能开发、重构、修复、迁移）中落地为可执行、可验证、可追踪的计划产物。读完本文，你将掌握一套"短而具体、任务可验证、验证永远收尾"的 AI 辅助规划范式，并能直接在类似多步骤工作中复用。

技能是什么：一条面向多步骤工作的规划技能

plan-writing 是 Dillinger 仓库 .agent 目录下众多 Agent 技能（skills）之一，其元信息（frontmatter）定义如下：

---
name: plan-writing
description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
allowed-tools: Read, Glob, Grep
---

• 适用场景：实现功能、重构，以及任何多步骤工作；
• 允许的工具：仅 Read、Glob、Grep——规划阶段只做"读代码、搜文件、列目录"的信息收集，不写任何代码；
• 来源：文档首部注明 > Source: obra/superpowers，即该技能脱胎于开源 superpowers 技能体系，仓库将其吸收为本地技能之一。

技能的本质是"把一项复杂工作拆成清晰、可行动、带验证标准的小任务"的框架。Dillinger 仓库本身正处于 Angular.js 向 Next.js 14 迁移的周期（见 docs/plans/CLAUDE.md 中记录的迁移计划活动），因此该技能与仓库内大量规划文档形成了"方法论 ↔ 落地证据"的互证关系。

任务拆解四大原则

SKILL.md 规定任何计划中的任务都必须满足四条拆解原则：

1. 小而聚焦的任务（Small, Focused Tasks）

要求	说明
每个任务耗时	2–5 分钟
每个任务的产出	一个明确结果
独立性	可独立验证

仓库中的迁移计划正是如此切分：以 docs/plans/2026-01-19-nextjs-migration.md 为例，Phase 1 被拆成 1.1 初始化 Next.js 项目、1.2 安装核心依赖、1.3 配置 Tailwind 设计令牌 等互不纠缠的任务，每个任务都只产出单一文件或单一能力。

2. 明确的验证标准（Clear Verification）

规划时必须回答三个问题：

• 如何知道它做完了？（How do you know it's done?）
• 可以检查/测试什么？（What can you check/test?）
• 预期输出是什么？（What's the expected output?）

每个任务末尾都带 Verify: 检查点，例如迁移计划中：

# 任务 1.2 的验证步骤
npm ls @monaco-editor/react zustand markdown-it
# Expected: All packages listed without errors

# 任务 1.3 的验证步骤
npm run build
# Expected: Build succeeds

3. 逻辑排序（Logical Ordering）

• 识别依赖关系（Dependencies identified）；
• 尽可能并行（Parallel work where possible）；
• 标出关键路径（Critical path highlighted）；
• 铁律：Phase X: Verification 永远放在最后。

这一点在 tasks/todo.md 的依赖图中有完整呈现：

- T1: Freeze the executable ship scope ... `depends_on: []`
- T2: Add automated verification infrastructure ... `depends_on: [T1]`
- T3: Restore markdown, preview, import/export ... `depends_on: [T2]`
- T4: Finish image handling, service/OAuth consistency ... `depends_on: [T2, T3]`
- T5: Run the release gate ... `depends_on: [T3, T4]`

T5（发布门禁：测试、类型检查、Lint、构建、浏览器 UI/UX 验证）作为最后一个任务依赖前面全部工作——这正是"Verification 永远收尾"原则的直接体现。

4. 项目根目录动态命名（Dynamic Naming in Project Root）

• 计划文件以 {task-slug}.md 命名，保存到项目根目录；
• 名称由任务派生，例如 "add auth" → auth-feature.md；
• 绝不放在 .claude/、docs/ 或临时目录里。

仓库配套的 /plan 工作流 .agent/workflows/plan.md 给出了更细的命名规则：从请求中提取 2–3 个关键词、转小写、用连字符连接、不超过 30 字符，例如 "e-commerce cart" → PLAN-ecommerce-cart.md。需要说明的是，仓库实际生成的迁移计划产物归档于 docs/plans/ 目录（如 2026-01-19-nextjs-migration.md），属于仓库自身在长期迭代中的归档实践；而技能文档规定的即时规划产物命名规范以 SKILL.md 与 /plan 工作流为准。

五大规划原则：是原则，不是模板

SKILL.md 特别强调 🔴 NO fixed templates. Each plan is UNIQUE to the task.——计划必须因任务而异，禁止套用统一模板。

原则 1：保持简短（Keep It SHORT）

❌ 错误	✅ 正确
50 个任务外加子-子任务	最多 5–10 个清晰任务
列出每一个微步骤	只列可行动项
冗长的任务描述	每任务一行

规则： 计划超过一页就是太长，需要简化。

原则 2：具体而非泛化（Be SPECIFIC, Not Generic）

❌ 错误	✅ 正确
"Set up project"	"Run npx create-next-app"
"Add authentication"	"Install next-auth, create /api/auth/[...nextauth].ts"
"Style the UI"	"Add Tailwind classes to Header.tsx"

规则： 每个任务都要有清晰、可验证的产出。

迁移计划就是"具体化"的范本：它不止写"创建状态管理"，而是给出完整动作——"Create next-app/lib/types.ts（Document / UserSettings 接口与 DEFAULT_SETTINGS、DEFAULT_DOCUMENT_BODY 常量）"、"Create next-app/stores/store.ts（Zustand store，含 hydrate/persist）"。对照当前仓库 lib/types.ts 与 stores/store.ts 可以确认这些规划产出已真实落地。

原则 3：按项目类型动态组织内容（Dynamic Content Based on Project Type）

场景	计划应回答的问题
新项目（NEW PROJECT）	技术栈选什么？MVP 是什么？文件结构怎样？
新增功能（FEATURE ADDITION）	影响哪些文件？需要什么依赖？如何验证生效？
修 Bug（BUG FIX）	根因是什么？改哪个文件/哪一行？如何测试修复？

原则 4：脚本因项目而异（Scripts Are Project-Specific）

🔴 禁止复制粘贴脚本命令，必须根据项目类型选择。

项目类型	相关脚本
前端/React	ux_audit.py、accessibility_checker.py
后端/API	api_validator.py、security_scan.py
移动端	mobile_audit.py
数据库	schema_validator.py
全栈	按实际改动范围混合

错误做法：给每个计划都塞进全部脚本；正确做法：只放与本任务相关的脚本。Dillinger 仓库的技能目录里确实存在这些脚本（如 .agent/skills/api-patterns/scripts/api_validator.py、.agent/skills/frontend-design/scripts/ux_audit.py、.agent/skills/database-design/scripts/schema_validator.py），规划时按需选用。

原则 5：验证必须简单（Verification is Simple）

❌ 错误	✅ 正确
"Verify the component works correctly"	"Run npm run dev, click button, see toast"
"Test the API"	"curl localhost:3000/api/users returns 200"
"Check styles"	"Open browser, verify dark mode toggle works"

验证描述要具体到"跑什么命令、看到什么现象、得到什么返回码"。

计划结构模板（灵活，非固定）

SKILL.md 给出的最小可用骨架：

# [Task Name]

## Goal
One sentence: What are we building/fixing?

## Tasks
- [ ] Task 1: [Specific action] → Verify: [How to check]
- [ ] Task 2: [Specific action] → Verify: [How to check]
- [ ] Task 3: [Specific action] → Verify: [How to check]

## Done When
- [ ] [Main success criteria]

就这些。 除非确有必要，不要添加 phases、子章节。保持最小化，仅在真正需要时增加复杂度。

## Notes
[Any important considerations]

仓库中的迁移计划对这一骨架做了贴合实际扩展：Goal 是单句目标（"Migrate Dillinger from Angular.js to Next.js 14 with App Router, maintaining 100% functional parity."），并附加了 Architecture（单页编辑器 + Zustand + Monaco + markdown-it + Next.js API routes + localStorage 持久化）与 Tech Stack（Next.js 14、TypeScript、Tailwind CSS、Zustand、Monaco Editor、markdown-it、Lucide React）两行上下文；每个任务内部采用统一的 **Files:**（列出将创建/修改的文件）→ **Step 1/2/3...**（具体命令与代码）→ **Verify**（检查命令与预期输出）→ **Commit**（git 提交信息）结构，例如任务 1.1 使用：

npx create-next-app@latest next-app --typescript --tailwind --eslint --app --src-dir=false --import-alias="@/*" --use-npm

最佳实践速查（Best Practices: Quick Reference）

1. 从目标开始——要构建/修复什么？
2. 最多 10 个任务——超过则拆成多个计划；
3. 每个任务可验证——有明确的"完成"标准；
4. 项目专属——不做复制粘贴模板；
5. 随进度更新——完成一项就勾选 [x]。

何时使用（When to Use）

• 从零开始的新项目；
• 新增功能；
• 修复复杂 Bug；
• 跨多文件的重构。

仓库实战：方法论如何落地成可追踪产物

迁移计划的"目标—任务—验证"三段式

docs/plans/2026-01-19-nextjs-migration.md 完整复刻了技能的骨架：单句 Goal 定义了"100% 功能对等"的总目标；5 个 Phase（Project Setup → State Management → Markdown Rendering → Monaco Editor → UI Components）各自包含 2–5 个任务；每个任务都携带真实可运行的 npm/git 命令、完整代码清单与 npm run build 级别的验证点。后续的 docs/plans/2026-01-19-nextjs-migration-phase2.md（GitHub/Dropbox 云端集成，OAuth token 存 HTTP-only cookie，API routes 统一代理云端通信）与 docs/plans/2026-01-19-phase3-design.md 等文档延续同一范式，形成可回溯的规划链条。

验证收尾与发布门禁

tasks/todo.md 是"Verification 永远最后"的活样本：任务链末尾的 T5 定义了一个完整的发布门禁——npm run verify（依次执行 npm run lint、npm run typecheck、npm run test:unit、npm run build 与基于生产服务器的 playwright test）。该清单还记录了具体验证证据，例如 PDF 导出修复在 tests/routes/export-pdf.route.test.ts 增加路由级回归测试，并通过本地 POST http://127.0.0.1:3015/api/export/pdf 冒烟验证返回有效单页 PDF；托管端最终以 HTTP/2 200、Content-Type: application/pdf 收尾。这说明"验证"不是计划末尾的一句口号，而是被测试资产（tests/ 目录下的组件、hooks、lib、routes 测试）与执行记录双重支撑的工程环节。

/plan 工作流：规划模式的调用入口

仓库用 .agent/workflows/plan.md 定义了 /plan 命令，将本技能包装成可调用的工作流模式，其关键规则包括：

1. 不写代码——该命令只生成计划文件；
2. 交给 project-planner Agent（见 .agent/agents/project-planner.md），而非原生 Plan 子代理；
3. 苏格拉底式提问门（Socratic Gate）——规划前先澄清需求；
4. 动态命名——计划文件按任务关键词命名，例如 /plan e-commerce site with cart → PLAN-ecommerce-cart.md；
5. 规划完成后给出固定格式的反馈（[OK] Plan created: ...）与下一步建议（Review → /create 开始实现，或手动修改计划）。

这一工作流把"规划技能"进一步封装成了团队/仓库内人人可调用的标准命令，规划产物最终经由 docs/reports/2026-03-10-refactor-finish-report.html 之类的报告形成闭环。

小结

plan-writing 技能的核心价值可以浓缩为三句话：计划要短到一页以内、具体到命令级别；任务要小到 2–5 分钟可完成、且每条都有可验证的完成标准；验证永远作为最后一个阶段收尾。Dillinger 仓库的迁移计划、任务追踪清单与 /plan 工作流，共同证明这套框架不是纸面方法论，而是能够产出真实代码、测试与部署记录的可执行工程范式。对任何需要在多步骤工作中保持节奏、依赖清晰、结果可证的团队或 AI Agent 而言，这套技能都值得直接借鉴。