plan

/plan —— 感知架构的规划

内容

进入结构化规划模式，在制定实现计划前先考虑项目的架构模式。此命令不会直接开始编写代码，而是要求先停下来，认真完成以下事项：

• 识别项目当前的架构（或推荐一种架构）
• 将任务映射到受影响的层、模块和边界
• 制定步骤清晰、带编号的实现计划
• 反复完善计划，直到方案稳妥后再编写代码

计划是持续演进的文档——如果实现过程中出现问题，请停下来重新规划，而不是继续采用有缺陷的方案。

适用场景

• 需要 3 个或更多实现步骤的非简单任务
• 涉及架构决策的任务（新模块、横切关注点、新限界上下文）
• 涉及多个层的功能（API、应用、领域、基础设施）
• 可能影响多个使用方的重构
• 用户提出“规划”“仔细考虑”“设计这个”或“我该如何着手”等要求时

以下情况跳过规划： 单文件变更、简单 Bug 修复、拼写错误修正、配置微调。

用法

第 1 步：理解任务

检查 docs/specs/ 中是否有涵盖此任务的已批准规格说明——如果有，它就是事实依据：将其验收标准映射到计划步骤，然后跳到第 2 步。如果该功能值得编写规格说明（无法用一句话描述清楚），但目前没有规格说明，请先建议使用 /spec，而不是基于假设进行规划。 否则，提出有针对性的问题，明确用户想要构建什么。 不要假设用户未说明的需求。

第 2 步：检测架构

使用 architecture-advisor 技能确定项目架构：

• 检查现有架构标志（文件夹结构、项目引用、模式）
• 如果尚未确立架构，则运行架构问卷
• 加载相应的架构专用技能（vertical-slice、clean-architecture、ddd）

第 3 步：映射受影响的区域

识别任务涉及的每个层、模块和边界：

• 哪些项目或文件夹会新增或修改文件？
• 是否涉及横切关注点（身份验证、缓存、验证、日志记录）？
• 哪些现有代码会受到影响？使用 find_references 和 find_callers MCP 工具评估影响范围。
• 是否需要数据库迁移？

第 4 步：制定计划

按以下结构输出带编号的计划：

## Plan: [Task Title]

**Architecture:** [Detected architecture]
**Affected layers:** [List]
**Estimated steps:** [Count]

### Steps
1. [Step] -- [Which file/layer] -- [Why this order]
2. ...

### Open Questions
- [Anything that needs user input before proceeding]

### Risks
- [Potential issues and mitigations]

第 5 步：反复完善

展示计划并询问：“这个计划看起来合适吗？还是需要调整什么？” 反复修订，直到用户确认。只有确认后才能开始实现。

示例

User: /plan Add a product catalog feature with search and filtering

Claude: Let me analyze your project structure first...

## Plan: Product Catalog Feature

**Architecture:** Vertical Slice Architecture
**Affected layers:** Features/, Infrastructure/Persistence/, Tests/
**Estimated steps:** 6

### Steps
1. Create Product entity + EF config -- Domain layer -- Foundation for everything else
2. Add migration -- Infrastructure -- Schema must exist before features
3. Scaffold GetProducts feature (with filtering) -- Features/Products/ -- Read path first
4. Scaffold CreateProduct feature -- Features/Products/ -- Write path
5. Add integration tests -- Tests/Features/Products/ -- Verify both features
6. Wire up OpenAPI metadata -- Features/Products/ -- Documentation

### Open Questions
- Should search be full-text (PostgreSQL tsvector) or simple LIKE?
- Do products need categories/tags for filtering?

Does this plan look right, or should I adjust anything?

相关

• /spec —— 对于无法用一句话描述清楚的功能，先编写规格说明
• /scaffold —— 计划获批后生成文件
• /verify —— 实现计划后运行验证