snailuu/smart-plan

Smart Plan - 智能计划生成技能

触发条件

本技能需要用户手动调用 /smart-plan，或在以下关键词出现时触发：

• "制定计划"、"写计划"、"规划方案"
• "plan"、"制定方案"、"实现计划"

如需在 plan 模式下自动生效，需在项目 CLAUDE.md 或全局配置中引用本技能的规则。

核心问题

Plan 模式下 Claude 生成的计划内容过长（数百行），单次 Write 调用超出模型输出 token 限制，导致内容截断和写入失败。

解决策略（按优先级）

策略一：分块写入（默认策略，适用于所有计划）

默认使用分块写入，从根本上避免单次写入过长的问题。短计划（≤50 行）允许单次 Write 写入。

策略二：精简格式（最佳实践，非强制）

鼓励紧凑表达，但不以牺牲计划质量为代价。复杂任务允许详细计划。

策略三：延迟细节

完整代码示例、API 签名等延迟到实现阶段，计划中只写意图和关键决策点。

分块写入规范（核心）

基本原则

• 为避免单次输出过长导致截断，建议每次写入不超过 50 行（经验值，可根据实际情况上调至 80 行）
• 第一块用 Write 创建文件，后续块全部用 Edit 追加
• 按逻辑章节切分，每块是一个完整的章节

分块流程

第 1 块 (Write)：计划标题 + 分析 + 方案概述
第 2 块 (Edit)：步骤 1-N（按实际步骤数分组，每块不超过 50 行）
第 3 块 (Edit)：风险 + 验证
...按需继续

具体写法见下方"端到端示例"章节。

Edit 追加写法：占位符锚点

第一块 Write 时预留占位符，后续 Edit 直接替换对应占位符为实际内容。

占位符格式统一使用 <!-- SECTION_NAME -->，保证在文件中唯一且不会被误匹配。

示例——替换 <!-- STEPS --> 占位符：

Edit 工具调用参数：

old_string:
<!-- STEPS -->

new_string:
## 步骤

### 1. 修改认证中间件 - `src/middleware/auth.ts`
- 从 session 迁移到 JWT
- 添加 token 校验和刷新逻辑

### 2. 更新用户模型 - `src/models/user.ts`
- 添加 password hash 字段
- 添加 refresh token 字段

注意：old_string 和 new_string 传入的是多行字面文本，不要使用 \n 转义。

避免使用"文件最后一行"作为 old_string，因为最后一行可能是空行或重复内容（如 ---），导致匹配失败。

计划格式建议

推荐模板

# 计划：[任务简述]

## 分析

- 问题：[简要描述]
- 影响范围：[涉及的文件/模块]
- 关键约束：[技术限制或业务规则]

## 方案

[概括选定方案及理由，复杂场景可列出备选方案对比]

## 步骤

### 1. [动作] - [目标文件/模块]
- 做什么：[描述]
- 关键点：[注意事项]
- 依赖：[前置条件，如有]

### 2. [动作] - [目标文件/模块]
...

## 风险

- [风险1]：[应对措施]

## 验证

- [ ] [验证项]

精简建议（非强制）

以下是让计划更紧凑的技巧，但如果任务确实复杂，保留必要细节比强行压缩更重要：

代码引用代替代码粘贴

# 冗余写法
创建函数：
function validateUser(user: User): boolean {
  if (!user.email) return false
  ...
}

# 推荐写法
- 创建 `validateUser()`，参考 `src/utils/validate.ts:15` 的校验模式

一句话概括代替段落

# 冗余写法
我们需要修改认证中间件。当前使用 session 认证，但新需求要求支持多端登录...

# 推荐写法
- 认证中间件从 session 迁移到 JWT（支持多端 + 无状态）

合并同类步骤

# 拆分过细
### 3. 创建 UserService
### 4. 创建 UserRepository
### 5. 创建 UserController

# 推荐合并
### 3. 创建用户模块（Service / Repository / Controller）
- 参考 `src/modules/product/` 的结构

执行流程

1. 探索分析 → 正常进行代码探索和需求分析
2. 组织内容 → 按推荐模板组织为逻辑章节
3. 评估分块 → ≤50 行单次写入，>50 行按占位符方案分块
4. 写入 → Write 骨架 + Edit 替换占位符，连续执行
5. 自检 → 每块 ≤50 行？Edit 的 old_string 精确匹配？

注意事项

• 分块写入是解决写入失败的技术手段，不是限制计划内容的理由
• 复杂任务的详细计划比简略计划更有价值，用分块写入支撑即可
• 计划是执行指南，保留足够的决策信息，省略实现层面的代码细节
• 如果任务本身过于庞大，建议拆分为子任务：
  • 每个子任务写独立的计划章节（同一文件内用 ## 子任务 1: xxx 分隔）
  • 先写总体方案和子任务拆分，再逐块补充每个子任务的步骤
• 计划写入 plan 模式指定的文件路径（由 Claude Code 自动管理），无需自行决定文件位置

端到端示例

假设任务："给项目添加用户认证功能"，预估计划约 90 行。

第 1 块 Write（约 25 行）——骨架 + 占位符

# 计划：添加用户认证功能

## 分析

- 问题：项目缺少用户认证，所有 API 无鉴权
- 影响范围：`src/middleware/`、`src/routes/`、`src/models/`
- 关键约束：需兼容现有未认证的公开 API

## 方案

采用 JWT + refresh token 方案（无状态，支持多端）

<!-- STEPS -->

<!-- RISKS -->

第 2 块 Edit——替换 <!-- STEPS --> 为步骤详情

old_string: "<!-- STEPS -->"
new_string: (步骤 1-4 的完整内容，约 40 行)

第 3 块 Edit——替换 <!-- RISKS --> 为风险和验证

old_string: "<!-- RISKS -->"
new_string: (风险评估 + 验证清单，约 20 行)

三块写入完成，总计约 85 行，每块均在 50 行安全线以内。