plan-interview

计划访谈技能

安装

gh skill install pskoett/pskoett-skills plan-interview

使用 Agent Skills CLI 作为备用方案：

npx skills add pskoett/pskoett-skills/skills/plan-interview

理念

此集合中的每项技能都围绕一个核心理念构建——这是 Agent 难以自行内化的一条原则。

这项技能的理念是：“先让改动变简单，再进行改动。”

Agent 通常会直接埋头实现，不管过程有多曲折。它们很少停下来问：“先做一次准备性重构，能否让这项改动变简单而非困难？”规划阶段就是提出这个问题的时机。在探索代码库和生成计划时，要主动寻找结构上的阻碍——那些会让目标改动变得笨拙、脆弱或过于复杂的代码。发现这类问题时，计划应提出一个准备步骤：先让改动变简单，再进行改动本身。两个清晰的步骤胜过一次孤军奋战。

目的

在规划实现之前进行结构化需求访谈。通过收集明确需求而非自行假设，确保你与用户达成一致。

调用时机

用户调用 /plan-interview <task description>。

如果任务纯粹是研究或探索（而非实现），则跳过此技能。

访谈流程

阶段 1：前置访谈（探索前）

检查宿主是否提供结构化提问工具（ask_user、 AskUserQuestion 或等效工具）。使用该工具提出有针对性的问题，让用户能在下一规划步骤前作答。如果宿主没有结构化提问工具，则在聊天中直接提出相同的问题，并等待用户回复。不要仅仅因为宿主使用了不同的工具名称，就退回到普通聊天提问。遵循宿主的工具架构：如果工具每次调用只接受一个问题，就依次询问各个领域，而不要将问题合并。

必须涵盖的问题领域

继续之前，必须涵盖以下全部四个领域：

1. 技术约束

   • 性能要求
   • 兼容性需求
   • 需要遵循的现有模式
   • 对架构的理解（如果不熟悉代码库）

2. 范围边界

   • 明确不在范围内的内容
   • MVP 与完整愿景
   • 对其他工作的依赖

3. 风险承受度

   • 可接受的权衡（速度与质量）
   • 对技术债务的容忍度
   • 是否接受破坏性变更

4. 成功标准

   • 如何判断任务已完成？
   • 怎样才算“正常工作”？
   • 测试与验证要求

问题生成

• 根据任务动态生成问题，不使用固定模板
• 将相关问题按主题分组
• 每组 2–3 个问题（不得超过）
• 持续提问，直到达到可执行的具体程度（能够描述具体实现步骤）

规划深度校准

结束访谈阶段前，对任务进行分类并选择规划深度：

• 简单/琐碎（小型错误修复、孤立改动）：最简计划，最多进行 1 轮完善
• 中等（已知领域内的功能开发）：标准计划，通常进行 1–2 轮完善
• 复杂/高风险（涉及多个文件、新架构、不熟悉的代码库、迁移、身份验证、并发）：深入规划，并迭代完善，直到改进趋于平缓

如果用户有明确偏好，可让其选择 fast 或 deep 覆盖此设置。

边缘情况处理

场景	操作
需求相互矛盾	给出带理由的建议，并请求用户确认
用户调整需求方向	根据新方向重新开始访谈
会话中断	询问用户是从上次进度继续，还是重新开始

应避免的反模式

• 不要重复询问同一问题的不同说法
• 不要未经询问就做出重大假设
• 不要为简单任务过度设计计划

阶段 2：探索代码库

访谈完成后，探索代码库以了解：

• 与任务相关的现有模式
• 会受到影响的文件
• 集成点
• 潜在风险
• 结构性阻力——当前代码结构是否不利于计划中的改动？预先重构（重命名、提取、重组）是否能让实际实现更直接？如果可以，请将其作为计划中的独立第一步提出。

对于复杂或不熟悉的项目，在深入规划前简要刷新上下文：

• 如果 AGENTS.md 和 README.md 存在且相关，请重新阅读
• 在细化计划前，确定当前的架构边界和约定
• 如果会话中断或上下文发生偏移，在再次进行细化前重新刷新这些内容

知识审查（探索与规划之间）

编写计划前，明确询问：“完成此任务所需的知识，是否存在于我能够获取的某处？”

对于每个重要的实现步骤，判断所需知识来自哪里：

• 代码库——现有模式、约定或示例代码。可在探索过程中找到。
• 提示词/上下文——用户在访谈中提供的要求、约束或领域知识。
• 训练数据——模型可靠掌握的通用编程知识、广泛使用的库或标准模式。
• 无法获取——上述来源中都没有相关知识。Agent 只能靠猜测。

如果某个步骤所需的知识“无法获取”：

1. 停止并说明问题。 不要用听起来很肯定的猜测来填补空缺。
2. 请用户提供缺失的知识、指向相关文档，或确认可以尽力而为。
3. 如果用户提供了参考资料（文档 URL、API 规范、示例），请在规划该步骤前加载。
4. 如果无法填补空缺，请在计划的“开放问题”部分将该步骤标记为受阻。

这项审查可避免 Agent 最常见的失误：在根本没有相关知识时仍自信地继续，产出看似合理却错误的结果。

阶段 3：生成计划

将计划写入 docs/plans/plan-NNN-<slug>.md，其中 NNN 为顺序编号。

采用 先起草，再细化 的工作流程。在仍能发现实质性改进时，继续专注于计划本身。对于非简单任务，规划所需的 token 通常远少于实现所需的 token。

先起草，再细化

1. 根据访谈和探索结果起草计划。
2. 在征求批准前，进行多轮迭代细化（轮数取决于任务复杂度）。
3. 将细化后的计划提交用户审阅。

迭代式计划细化循环（用户审阅前）

根据任务复杂度进行 1..N 轮细化。每轮执行以下步骤：

1. 以全新视角开始（必须）： 修改前，以“全新视角”重新阅读访谈回答、约束、成功标准和当前计划草稿。
2. 检查矛盾、遗漏的边缘情况、集成风险，以及含糊的实现步骤。
3. 在明确有助于用户时，改进架构、执行顺序和可靠性。
4. 强化测试与验证计划（适用时包括单元测试和集成/e2e 测试，以及有用的诊断/日志记录）。
5. 确认功能得到保留：
   • 不要过度简化
   • 除非用户明确同意缩小范围，否则不要删除已商定的功能或能力
6. 简要记录每轮总结：改动了什么，以及原因。

满足以下任一条件时停止迭代：

• 连续两轮没有带来实质性改进
• 改动仅涉及措辞/风格，不影响执行质量
• 任务简单，计划已具备可执行性
• 用户要求停止并继续执行

可选：多方案综合（“集各家之所长”）

如果用户提供了多个相互竞争的方案（来自不同模型或之前的迭代）：

• 将它们与当前方案进行客观比较
• 提取最佳创意、权衡和风险缓解措施
• 将它们合并为一个保留已达成一致范围的规范方案
• 用户要求输出修订内容时，优先以 git-diff 风格的变更展示对现有方案的修改

用于优化循环和多方案综合的可复用提示词模板位于 references/iterative-plan-refinement-prompts.md。

必需元素

每个方案都 MUST 包含：

## Success Criteria
[Clear definition of done from interview]

## Risk Assessment
[What could go wrong + mitigations]

## Affected Files/Areas
[Which parts of codebase will be touched]

## Test Strategy
[Unit tests, integration tests, and e2e tests/scripts where applicable; include key scenarios, failure modes, and fixtures/mocks]

## Validation and Diagnostics
[How to verify the feature works after implementation; include detailed logging/diagnostics expectations in tests/scripts when useful for debugging]

## Knowledge Map
[For each major step, where does the required knowledge live?]
| Step | Knowledge Source | Confidence |
|------|-----------------|------------|
| Step 1 | Codebase (existing pattern in src/auth/) | High |
| Step 2 | Training data (standard OAuth2 flow) | High |
| Step 3 | Nowhere — need user to provide API spec | Blocked |

## Open Questions
[Uncertainties to resolve during implementation]
- [ ] Question 1 - [Blocks implementation / Can proceed]
- [ ] Question 2 - [Blocks implementation / Can proceed]

## Implementation Checklist
- [ ] Step 1
- [ ] Step 2
...

可选元素

视情况纳入：

• 未采纳的备选方案：仅用于重大的架构决策
• 决策树：仅在存在多种有效方案时使用
• 可视化图表：有助于理解时使用 ASCII 或 Mermaid

约束

• 不提供时间估算——描述需要做什么，而不是需要多长时间
• 不限制篇幅——方案的详略应与任务复杂度相匹配
• 不得悄悄缩减范围——不要为了让方案“更简洁”而删掉已达成一致的功能
• 简单工作不要过度迭代——使用上文的规划深度校准
• 必需元素之外的结构不作限制

阶段 4：批准后

用户批准方案后：

1. 立即自动开始实施（无需单独确认“继续”）。如果 intent-framed-agent 已启用，则直接进入忠实的 Intent Frame，并复用方案批准结果。仅当该框架引入了实质性变更或尚未解决的决策时，才再次询问。
2. 使用检查清单项目填充 TodoWrite（如果 TodoWrite 不可用，则通过输出中的结构化注释跟踪进度）
3. 在自然的阶段节点（重大决策）检查进度是否符合方案

快速模式

如果用户希望快速规划，则采用 起草 + 优化：

1. 执行针对任务的代码库搜索
2. 生成方案草稿
3. 进行简短访谈以优化方案
4. 恰好进行一轮全新视角优化（保留功能、精简步骤，并补充测试／验证覆盖）

恢复支持

如果 docs/plans/ 中存在未完成的方案：

AskUserQuestion: "I found an existing partial plan. Would you like to:"
- "Continue the interview"
- "Resume plan drafting/refinement"
- "Review current plan and finalize"
- "Start fresh with a new plan"

如果要恢复优化，先总结当前方案状态和最近的优化变更，然后继续进行全新视角优化循环。

与其他技能的互操作性

此技能的输入

• 来自用户： 任务描述、要求以及对访谈问题的回答。
• 来自代码库： 探索时发现的现有模式、架构和约定。
• 来自上下文浏览交接文件（恢复时）： 如果上一个会话因上下文漂移而退出，.context-surfing/ 中的交接文件会提供重新进入的起点以及重新规划的剩余工作。

此技能的输出

• 方案文件（docs/plans/plan-NNN-<slug>.md）——作为意图框架的上下文，供 intent-framed-agent 使用；也作为 wave anchor 的一部分，供 context-surfing 使用。发生漂移并退出时，会逐字复制到交接文件中。
• 规划深度分类——用于确定要启用多少项技能（参见 README 中的流水线深度表）。

流水线位置

1. plan-interview（需求与方案生成——你当前所在的位置）
2. intent-framed-agent（执行约定 + 范围漂移监控）
3. context-surfing（可选的上下文质量监控，用于大型、长时间运行或明确对上下文敏感的执行）
4. verify-gate（机器验证：编译 + 测试 + lint）
5. simplify-and-harden（完成后的质量／安全检查）
6. self-improvement（捕捉重复出现的模式并形成持久规则）

示例

User: /plan-interview Add OAuth authentication to the API

Claude: I'll help you plan the OAuth authentication feature. Let me gather
        requirements first.

[AskUserQuestion - Scope batch]
1. Which OAuth providers need to be supported (Google, GitHub, etc.)?
2. Is this replacing existing auth or adding alongside it?

[Copilot guidance: ask the same two questions in chat and wait for responses]

User: Google and GitHub. Adding alongside existing JWT auth.

[AskUserQuestion - Technical batch]
1. Should OAuth tokens be stored in the existing session table or separately?
2. Any specific callback URL constraints from your hosting setup?

User: Separate table. We're on Vercel so callback URLs need to be configured per environment.

[AskUserQuestion - Risk/Success batch]
1. What's the acceptable degradation if an OAuth provider is down?
2. How should we handle users who already exist with the same email?

User: Fall back to standard login. Link accounts by email if user confirms.

Claude: [Explores codebase for auth patterns, session handling, database schema]

Claude: [Writes docs/plans/plan-003-oauth-authentication.md]

        Plan created. The main decision point is whether to use Passport.js
        or implement OAuth flows directly - I've documented both approaches
        with tradeoffs. Ready to review?

User: Looks good, go with Passport.js

Claude: [Auto-starts implementation with TodoWrite tracking]