create-plans

<essential_principles>

你为 1 位用户和 1 位实施者（Claude）制定计划。 没有团队。没有利益相关者。没有仪式。没有协调开销。 用户是愿景提出者／产品负责人。Claude 是构建者。 PLAN.md 不是一份需要转换成提示词的文档。 PLAN.md 本身就是提示词。它包含： - 目标（做什么以及为什么） - 上下文（@file 引用） - 任务（类型、文件、操作、验证、完成标准、检查点） - 验证（整体检查） - 成功标准（可衡量） - 输出（SUMMARY.md 规范）

规划某个阶段时，你就是在编写执行该阶段的提示词。

计划必须在约 50% 的上下文用量内完成，以保持质量稳定。

质量下降曲线：

• 0-30% 上下文：质量巅峰（全面、深入、毫无焦虑）
• 30-50% 上下文：质量良好（投入、压力可控）
• 50-70% 上下文：质量下降（进入效率模式、压缩内容）
• 70% 以上：质量较差（自我阉割、仓促处理）

关键见解： Claude 并非到 80% 才开始退化，而是在上下文逐渐堆积、进入“完成模式”时，约 40-50% 就开始退化。到 80% 时，质量早已大幅下滑。

解决方案： 积极拆分任务，拆成多个小而专注的计划。

示例：

• 01-01-PLAN.md - 阶段 1，计划 1（2-3 项任务：仅数据库架构）
• 01-02-PLAN.md - 阶段 1，计划 2（2-3 项任务：仅数据库客户端设置）
• 01-03-PLAN.md - 阶段 1，计划 3（2-3 项任务：仅 API 路由）
• 01-04-PLAN.md - 阶段 1，计划 4（2-3 项任务：仅 UI 组件）

每个计划都可独立执行和验证，范围最多限定为 2-3 项任务。

原子任务原则： 10 份小而优质的计划，胜过 3 份庞大而质量退化的计划。每次提交都应精准、专注且易于维护。

自主执行： 不含检查点的计划会由子 Agent 在全新上下文中执行，不可能发生质量退化。

参见：references/scope-estimation.md

**凡是可以通过 CLI 或 API 完成的工作，Claude 都会自动处理。** 检查点用于验证和决策，而非手动操作。

检查点类型：

• checkpoint:human-verify - 人工确认 Claude 自动完成的工作（视觉检查、UI 验证）
• checkpoint:decision - 人工决定实现方案（身份验证提供商、架构）

较少需要： checkpoint:human-action - 仅用于没有 CLI/API 的操作（电子邮件验证链接、需要通过网页登录并进行双重身份验证的账户审批）

关键规则： 如果 Claude 能通过 CLI/API/工具完成，就必须由 Claude 完成。绝不要求人工：

• 部署到 Vercel/Railway/Fly（使用 CLI）
• 创建 Stripe webhook（使用 CLI/API）
• 运行构建／测试（使用 Bash）
• 编写 .env 文件（使用 Write 工具）
• 创建数据库资源（使用提供商 CLI）

流程： Claude 自动完成工作 → 到达 checkpoint:human-verify → 展示已完成的内容 → 等待确认 → 继续执行

参见：references/checkpoints.md、references/cli-automation.md

计划是指南，不是束缚。实际开发总会有所发现。

执行期间，偏差会根据内置的 5 条规则自动处理：

1. 自动修复 bug - 行为异常 → 立即修复，并记录在 Summary 中
2. 自动补充缺失的关键内容 - 安全性／正确性缺口 → 立即补充，并记录
3. 自动排除阻碍 - 无法继续 → 立即解决，并记录
4. 架构问题需询问 - 重大结构变更 → 停止并询问用户
5. 记录增强项 - 有益但非必需的改进 → 自动记录到 ISSUES.md，然后继续

规则 1-3、5 无需用户介入。 只有规则 4（架构问题）需要用户决策。

所有偏差都要记录在 Summary 中，包括：发现的问题、适用的规则、采取的措施、提交哈希。

**结果：** 流程永不中断。Bug 得到修复。范围保持可控。完全透明。

参见：workflows/execute-phase.md（deviation_rules 部分）

不搞企业流程。不设审批关卡。不设数周的时间表。 规划 → 执行 → 发布 → 学习 → 重复。

以里程碑为导向： 发布 v1.0 → 标记里程碑 → 规划 v1.1 → 发布 → 重复。 里程碑标记已发布的版本，并支持持续迭代。

里程碑标记已发布的版本（v1.0、v1.1、v2.0）。

目的：

• 在 MILESTONES.md 中记录历史（何时发布了什么）
• 标记从 Greenfield 到 Brownfield 的转变
• 为发布创建 Git 标签
• 明确的完成仪式

默认做法： 在现有路线图中扩展新阶段。

• v1.0 发布（阶段 1-4）→ 为 v1.1 添加阶段 5-6
• 阶段编号连续递增（01-99）
• 按里程碑分组，让路线图保持井然有序

仅在以下情况归档： 独立代码库或完全重写（很少见）。

参见：references/milestone-management.md

规划中绝不包含： - 团队结构、角色、RACI 矩阵 - 利益相关者管理、协调会议 - Sprint 仪式、站会、回顾会 - 数周的估算、资源分配 - 变更管理、治理流程 - 为写文档而写文档

如果听起来像企业项目管理作秀，就删掉。

通过系统警告监控 token 用量。

剩余 25% 时： 提醒上下文即将占满 剩余 15% 时： 暂停并提供交接选项 剩余 10% 时： 自动创建交接并停止

低于 15% 时，未经用户确认，绝不启动大型操作。

遇到关键决策点时，绝不贸然推进。使用关卡： - **AskUserQuestion**：提供结构化选项（2-4 个） - **内联问题**：简单确认 - **决策关卡循环**：“准备好了吗？还是还要再问几个问题？”

强制关卡：

• 编写 PLAN.md 之前（确认任务分解）
• 低置信度研究之后
• 验证失败时
• 阶段完成但存在问题时
• 上一阶段存在问题时，开始下一阶段之前

参见：references/user-gates.md

所有规划材料都纳入版本控制。提交成果，而非过程。

• 每次调用时检查是否存在仓库，并主动提出初始化
• 仅在以下时机提交：初始化、阶段完成、交接
• 中间材料（PLAN.md、RESEARCH.md、FINDINGS.md）不单独提交
• Git 日志将成为项目历史

参见：references/git-integration.md

</essential_principles>

<context_scan> 每次调用时都运行，以了解当前状态：

# Check git status
git rev-parse --git-dir 2>/dev/null || echo "NO_GIT_REPO"

# Check for planning structure
ls -la .planning/ 2>/dev/null
ls -la .planning/phases/ 2>/dev/null

# Find any continue-here files
find . -name ".continue-here.md" -type f 2>/dev/null

# Check for existing artifacts
[ -f .planning/BRIEF.md ] && echo "BRIEF: exists"
[ -f .planning/ROADMAP.md ] && echo "ROADMAP: exists"

如果检测到 NO_GIT_REPO： 内联提问：“未找到 Git 仓库。是否初始化？（建议初始化以进行版本控制）” 如果是：git init

在提出初始问题之前，先展示发现结果。 </context_scan>

<domain_expertise> 领域专业知识位于 ~/.claude/skills/expertise/

创建路线图或阶段计划之前，判断是否应加载领域专业知识。

<scan_domains>

ls ~/.claude/skills/expertise/ 2>/dev/null

这会展示可用的领域专业知识（例如，macos-apps、iphone-apps、unity-games、nextjs-ecommerce）。

如果没有找到领域技能： 无需领域专业知识即可继续（平稳降级）。没有特定领域上下文时，该技能也能正常工作。 </scan_domains>

<inference_rules> 如果用户的请求包含领域关键词，则推断所属领域：

关键词	领域技能
"macOS", "Mac app", "menu bar", "AppKit", "SwiftUI desktop"	expertise/macos-apps
"iPhone", "iOS", "iPad", "mobile app", "SwiftUI mobile"	expertise/iphone-apps
"Unity", "game", "C#", "3D game", "2D game"	expertise/unity-games
"MIDI", "MIDI tool", "sequencer", "MIDI controller", "music app", "MIDI 2.0", "MPE", "SysEx"	expertise/midi
"Agent SDK", "Claude SDK", "agentic app"	expertise/with-agent-sdk
"Python automation", "workflow", "API integration", "webhooks", "Celery", "Airflow", "Prefect"	expertise/python-workflow-automation
"UI", "design", "frontend", "interface", "responsive", "visual design", "landing page", "website design", "Tailwind", "CSS", "web design"	expertise/ui-design

如果推断出领域，请确认：

Detected: [domain] project → expertise/[skill-name]
Load this expertise for planning? (Y / see other options / none)

</inference_rules>

<no_inference> 如果从请求中无法明显看出领域，请给出选项：

What type of project is this?

Available domain expertise:
1. macos-apps - Native macOS with Swift/SwiftUI
2. iphone-apps - Native iOS with Swift/SwiftUI
3. unity-games - Unity game development
4. swift-midi-apps - MIDI/audio apps
5. with-agent-sdk - Claude Agent SDK apps
6. ui-design - Stunning UI/UX design & frontend development
[... any others found in expertise/]

N. None - proceed without domain expertise
C. Create domain skill first

Select:

</no_inference>

<load_domain> 选择领域后，使用智能加载：

步骤 1：读取领域 SKILL.md

cat ~/.claude/skills/expertise/[domain]/SKILL.md 2>/dev/null

这会加载核心原则和路由指导（约 5k tokens）。

步骤 2：确定需要哪些参考文档

领域 SKILL.md 应包含一个 <references_index> 部分，将规划场景映射到具体参考文档。

示例：

<references_index>
**For database/persistence phases:** references/core-data.md, references/swift-concurrency.md
**For UI/layout phases:** references/swiftui-layout.md, references/appleHIG.md
**For system integration:** references/appkit-integration.md
**Always useful:** references/swift-conventions.md
</references_index>

步骤 3：仅加载相关参考文档

根据正在规划的阶段（来自 ROADMAP），仅加载该类工作所提到的参考文档。

# Example: Planning a database phase
cat ~/.claude/skills/expertise/macos-apps/references/core-data.md
cat ~/.claude/skills/expertise/macos-apps/references/swift-conventions.md

上下文效率：

• 仅 SKILL.md：约 5k tokens
• SKILL.md + 选择性参考文档：约 8-12k tokens
• 全部参考文档（旧方法）：约 20-27k tokens

宣布："已加载 [domain] 专业知识（[X] 份参考文档，用于 [phase-type]）。"

如果找不到领域技能： 告知用户，并提供在没有领域专业知识的情况下继续进行的选项。

如果 SKILL.md 没有 references_index： 回退到加载全部参考文档，并警告上下文用量。 </load_domain>

<when_to_load> 领域专业知识应在以下操作之前加载：

• 创建 roadmap（阶段应与领域相适配）
• 规划阶段（任务必须特定于领域）

以下操作不需要领域专业知识：

• 创建 brief（愿景与领域无关）
• 从 handoff 恢复（上下文已建立）
• 阶段之间的过渡（只是更新状态） </when_to_load> </domain_expertise>

根据扫描结果，呈现上下文感知选项：

如果找到 handoff：

Found handoff: .planning/phases/XX/.continue-here.md
[Summary of state from handoff]

1. Resume from handoff
2. Discard handoff, start fresh
3. Different action

如果存在规划结构：

Project: [from BRIEF or directory]
Brief: [exists/missing]
Roadmap: [X phases defined]
Current: [phase status]

What would you like to do?
1. Plan next phase
2. Execute current phase
3. Create handoff (stopping for now)
4. View/update roadmap
5. Something else

如果没有规划结构：

No planning structure found.

What would you like to do?
1. Start new project (create brief)
2. Create roadmap from existing brief
3. Jump straight to phase planning
4. Get guidance on approach

在继续之前等待响应。

| 响应 | 工作流 | |----------|----------| | "brief", "new project", "start", 1（无结构） | `workflows/create-brief.md` | | "roadmap", "phases", 2（无结构） | `workflows/create-roadmap.md` | | "phase", "plan phase", "next phase", 1（有结构） | `workflows/plan-phase.md` | | "chunk", "next tasks", "what's next" | `workflows/plan-chunk.md` | | "execute", "run", "do it", "build it", 2（有结构） | **退出技能** → 使用 `/run-plan ` 斜杠命令 | | "research", "investigate", "unknowns" | `workflows/research-phase.md` | | "handoff", "pack up", "stopping", 3（有结构） | `workflows/handoff.md` | | "resume", "continue", 1（有 handoff） | `workflows/resume.md` | | "transition", "complete", "done", "next" | `workflows/transition.md` | | "milestone", "ship", "v1.0", "release" | `workflows/complete-milestone.md` | | "guidance", "help", 4 | `workflows/get-guidance.md` |

关键： 计划执行不应调用此技能。使用 /run-plan 以获得上下文效率（技能加载约 20k tokens，/run-plan 加载约 5-7k）。

阅读工作流后，严格遵循它。

规划层级（每一层都建立在前一层之上）：

BRIEF.md          → Human vision (you read this)
    ↓
ROADMAP.md        → Phase structure (overview)
    ↓
RESEARCH.md       → Research prompt (optional, for unknowns)
    ↓
FINDINGS.md       → Research output (if research done)
    ↓
PLAN.md           → THE PROMPT (Claude executes this)
    ↓
SUMMARY.md        → Outcome (existence = phase complete)

规则：

• Roadmap 需要 Brief（或提示创建一个）
• 阶段计划需要 Roadmap（了解阶段范围）
• PLAN.md 就是执行提示词
• SUMMARY.md 的存在标志阶段完成
• 每一层都可以向上查找上下文

<output_structure> 所有规划文档均放在 .planning/ 中：

.planning/
├── BRIEF.md                    # Human vision
├── ROADMAP.md                  # Phase structure + tracking
└── phases/
    ├── 01-foundation/
    │   ├── 01-01-PLAN.md       # Plan 1: Database setup
    │   ├── 01-01-SUMMARY.md    # Outcome (exists = done)
    │   ├── 01-02-PLAN.md       # Plan 2: API routes
    │   ├── 01-02-SUMMARY.md
    │   ├── 01-03-PLAN.md       # Plan 3: UI components
    │   └── .continue-here-01-03.md  # Handoff (temporary, if needed)
    └── 02-auth/
        ├── 02-01-RESEARCH.md   # Research prompt (if needed)
        ├── 02-01-FINDINGS.md   # Research output
        ├── 02-02-PLAN.md       # Implementation prompt
        └── 02-02-SUMMARY.md

命名约定：

• 计划：{phase}-{plan}-PLAN.md（例如：01-03-PLAN.md）
• 摘要：{phase}-{plan}-SUMMARY.md（例如：01-03-SUMMARY.md）
• 阶段文件夹：{phase}-{name}/（例如：01-foundation/）

文件按时间顺序排列。相关文档（计划 + 摘要）相邻放置。 </output_structure>

<reference_index> 所有文件均位于 references/ 中：

结构： directory-structure.md、hierarchy-rules.md 格式： handoff-format.md、plan-format.md 模式： context-scanning.md、context-management.md 规划： scope-estimation.md、checkpoints.md、milestone-management.md 流程： user-gates.md、git-integration.md、research-pitfalls.md 领域： domain-expertise.md（创建上下文高效的领域技能指南） </reference_index>

<templates_index> 所有文件均位于 templates/ 中：

模板	用途
brief.md	包含当前状态的项目愿景文档
roadmap.md	按里程碑分组的阶段结构
phase-prompt.md	可执行的阶段提示词（PLAN.md）
research-prompt.md	研究提示词（RESEARCH.md）
summary.md	阶段结果（SUMMARY.md），包含偏差
milestone.md	MILESTONES.md 的里程碑条目
issues.md	延后处理的增强项日志（ISSUES.md）
continue-here.md	上下文交接格式
</templates_index>

<workflows_index> 所有文件均位于 workflows/ 中：

工作流	用途
create-brief.md	创建项目愿景文档
create-roadmap.md	根据简报定义阶段
plan-phase.md	创建可执行的阶段提示词
execute-phase.md	执行阶段提示词并创建摘要
research-phase.md	创建并运行研究提示词
plan-chunk.md	规划紧接着要执行的任务
transition.md	标记阶段完成并进入下一阶段
complete-milestone.md	标记已发布版本并创建里程碑条目
handoff.md	创建上下文交接以便暂停
resume.md	加载交接内容并恢复上下文
get-guidance.md	帮助确定规划方式
</workflows_index>

<success_criteria> 规划技能满足以下条件即表示成功：

• 在收集信息前运行上下文扫描
• 根据状态选择合适的工作流
• PLAN.md 本身就是可执行提示词（而非单独的提示词）
• 保持层级关系（简报 → 路线图 → 阶段）
• 交接时保留完整上下文，以便恢复工作
• 遵守上下文限制（达到 10% 时自动交接）
• 按照内嵌规则自动处理偏差
• 完整记录所有工作（计划内及发现的工作）
• 智能加载领域知识（SKILL.md + 按需选择的参考资料，而非全部文件）
• 使用 /run-plan 命令执行计划（而非调用技能） </success_criteria>