planning-prompts

为个人开发者提供高效的项目规划和 Claude 间元提示词能力。创建可执行计划（PLAN.md 文件本身就是提示词）、分层规划结构（Brief → Roadmap → Phase），以及多阶段的研究、规划和实现工作流。

<quick_start> 启动新项目：

# Claude creates planning structure
mkdir -p .planning/phases
# Creates: BRIEF.md, ROADMAP.md, phase plans

通过路由调用：

• “brief” / “new project” → 创建 BRIEF.md
• “roadmap” / “phases” → 创建 ROADMAP.md
• “plan phase” / “next phase” → 创建阶段 PLAN.md
• “meta-prompt” / “research then plan” → 创建提示词链

计划本身就是提示词——PLAN.md 可由 Claude 直接执行。 </quick_start>

<essential_principles>

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

规划阶段时，你写的就是将执行该阶段的提示词。

输出内容面向 Claude，而非人类： - 使用大量 XML 结构，便于解析 - 元数据块（confidence、dependencies、open_questions、assumptions） - 明确的后续步骤 - 带上下文的代码示例 - 每次执行都会生成 SUMMARY.md，方便人类快速浏览 计划必须在上下文用量约 50% 以内完成，以保持质量稳定。

质量下降曲线：

• 上下文用量 0–30%：质量最佳（全面、细致、毫无压力）
• 上下文用量 30–50%：质量良好（投入充分、压力可控）
• 上下文用量 50–70%：质量下降（转入效率模式、内容压缩）
• 上下文用量 70% 以上：质量较差（自我阉割、仓促完成）

2–3 个任务规则： 每个计划最多应包含 2–3 个任务。

示例：

• 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 路由）

参见：reference/plans.md（范围估算部分）

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

检查点类型：

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

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

参见：reference/plans.md（检查点部分）

计划是指引，而非束缚。执行期间，偏差按以下规则自动处理：

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

不搞企业流程。不设审批关卡。不制定多周时间表。 规划 -> 执行 -> 发布 -> 学习 -> 重复。

里程碑标记已发布的版本：v1.0 -> v1.1 -> v2.0

计划中绝不包含： - 团队架构、角色、RACI 矩阵 - 利益相关方管理、对齐会议 - Sprint 仪式、站会、回顾会 - 多周估算、资源分配 - 变更管理、治理流程 - 为写文档而写文档

如果听起来像企业级项目管理表演，就删掉。

</essential_principles>

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

# Check for planning structure
ls -la .planning/ 2>/dev/null
ls -la .prompts/ 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"

先展示发现，再提出接收问题。 </context_scan>

根据扫描结果，提供符合上下文的选项：

如果存在规划结构：

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. Create a meta-prompt (for Claude-to-Claude pipeline)
6. Something else

如果存在提示词结构：

Found .prompts/ directory with [N] prompt folders.
Latest: {most recent folder}

What would you like to do?
1. Create new prompt (Research/Plan/Do/Refine)
2. Run existing prompt
3. View prompt chain
4. Something else

如果未找到结构：

No planning or prompt structure found.

What would you like to do?
1. Start new project (create brief + roadmap)
2. Create a meta-prompt chain (research -> plan -> implement)
3. Jump straight to phase planning
4. Get guidance on approach

等待回复后再继续。

| 意图 | 前往 | |--------|-------| | "brief", "new project", "start project" | reference/plans.md（create-brief 部分） | | "roadmap", "phases", "structure" | reference/plans.md（create-roadmap 部分） | | "phase", "plan phase", "next phase" | reference/plans.md（plan-phase 部分） | | "meta-prompt", "prompt chain", "research then plan" | reference/meta-prompts.md | | "research prompt", "gather info" | reference/meta-prompts.md（research 部分） | | "plan prompt", "create approach" | reference/meta-prompts.md（plan 部分） | | "do prompt", "implement", "execute" | reference/meta-prompts.md（do 部分） | | "refine", "improve", "iterate" | reference/meta-prompts.md（refine 部分） | | "handoff", "pack up", "stopping" | reference/plans.md（handoff 部分） | | "resume", "continue" | reference/plans.md（resume 部分） | | "guidance", "help" | 再次显示此菜单并附上说明 |

阅读参考文档后，严格遵循其中的要求。

<project_planning_hierarchy> 项目规划层级（每个级别都基于前一级别构建）：

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)

结构：

.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
    └── 02-auth/
        ├── 02-01-RESEARCH.md   # Research prompt (if needed)
        ├── 02-01-FINDINGS.md   # Research output
        └── 02-02-PLAN.md       # Implementation prompt

</project_planning_hierarchy>

<meta_prompt_hierarchy> 元提示词层级（用于 Claude 到 Claude 的流水线）：

.prompts/
├── 001-auth-research/
│   ├── completed/
│   │   └── 001-auth-research.md    # Prompt (archived after run)
│   ├── auth-research.md            # Full output (XML for Claude)
│   └── SUMMARY.md                  # Executive summary (markdown for human)
├── 002-auth-plan/
│   ├── completed/
│   │   └── 002-auth-plan.md
│   ├── auth-plan.md
│   └── SUMMARY.md
├── 003-auth-implement/
│   ├── completed/
│   │   └── 003-auth-implement.md
│   └── SUMMARY.md                  # Do prompts create code elsewhere

用途类型：

• Research - 收集供规划提示词使用的信息
• Plan - 创建供实施使用的方法或路线图
• Do - 执行任务并生成产物
• Refine - 改进已有的研究或计划输出 </meta_prompt_hierarchy>

<workflow_patterns>

<research_plan_implement> 经典的三阶段工作流：

1. Research Prompt -> 收集信息，生成结构化发现
2. Plan Prompt -> 参考研究结果，制定分阶段方案
3. Do Prompt -> 参考计划，实施各个阶段

每个阶段：

• 生成供下一阶段使用的输出
• 创建 SUMMARY.md，便于人工浏览
• 完成后归档提示词
• 记录元数据（置信度、依赖项、待解决问题）

链式检测： 创建提示词时，扫描是否存在可供引用的研究或计划文件。 </research_plan_implement>

<parallel_research> 适用于包含多个独立研究领域的主题：

Layer 1 (parallel): 001-api-research, 002-db-research, 003-ui-research
Layer 2 (depends on all): 004-architecture-plan
Layer 3 (depends on 004): 005-implement

执行方式： 层内并行，层间顺序执行。 </parallel_research>

<iterative_refinement> 需要改进初始研究或计划时：

001-auth-research        -> Initial research
002-auth-research-refine -> Deeper dive on specific finding
003-auth-plan            -> Plan based on refined research

精炼提示词会保留版本历史并跟踪变更。 </iterative_refinement>

</workflow_patterns>

<output_requirements>

<summary_md> 每次执行都要生成 SUMMARY.md：

# {Topic} {Purpose} Summary

**{Substantive one-liner describing outcome}**

## Version
{v1 or "v2 (refined from v1)"}

## Key Findings
- {Most important finding or action}
- {Second key item}
- {Third key item}

## Files Created
{Only for Do prompts}
- `path/to/file.ts` - Description

## Decisions Needed
{Specific actionable decisions, or "None"}

## Blockers
{External impediments, or "None"}

## Next Step
{Concrete forward action}

---
*Confidence: {High|Medium|Low}*
*Full output: {filename.md}*

一句话总结必须言之有物：

• 好："推荐使用 jose 库和 httpOnly Cookie 实现 JWT"
• 差："研究已完成" </summary_md>

<metadata_block> 研究和计划输出中需包含：

<metadata>
  <confidence level="{high|medium|low}">
    {Why this confidence level}
  </confidence>
  <dependencies>
    {What's needed to proceed}
  </dependencies>
  <open_questions>
    {What remains uncertain}
  </open_questions>
  <assumptions>
    {What was assumed}
  </assumptions>
</metadata>

</metadata_block>

</output_requirements>

<reference_index> 所有参考文档均位于 reference/：

参考文档	内容
plans.md	项目计划：简报、路线图、阶段、检查点、范围估算、交接
meta-prompts.md	Claude 到 Claude 的流水线：research/plan/do/refine 模式、执行引擎
</reference_index>
<success_criteria>
Skill 成功条件：

• 在接收需求前运行上下文扫描
• 根据意图选择合适的工作流
• 计划本身就是可执行的提示词（而非独立内容）
• 保持层级关系（简述 -> 路线图 -> 阶段）
• 元提示词包含元数据和 SUMMARY.md
• 检测并遵循链式依赖关系
• 质量控制可防止研究遗漏
• 交接保留完整上下文，以便恢复工作
• 遵守上下文限制（剩余 10% 时自动交接）
• 记录所有工作，并注明偏差

输出结果旁注文件

最后一步，将内容写入 ~/.claude/skill-analytics/last-outcome-planning-prompts.json：

{"ts":"[UTC ISO8601]","skill":"planning-prompts","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"plans_created":[n],"prompts_generated":[n],"chains_built":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果某些阶段失败但已产出结果，请使用状态 "partial"。只有在未生成任何输出时，才使用 "error"。 </success_criteria>