| name | feature-planning |
| description | 新功能开发的执行方案文档编写范式，从现状分析到方案对比再到架构设计与实施步骤。 仅当用户明确说出"使用 feature-planning"或"启动 feature-planning"时触发。 不适用于任何隐式场景。 |
新功能开发计划编写范式
编写高质量新功能执行方案文档，确保现状量化、方案对比清晰、架构设计明确、步骤可执行。
触发约束
此 skill 仅通过显式调用触发。
⛔ 不触发的场景
- 用户提到"规划功能"、"写个方案"等但未提及 feature-planning
- 用户直接说"帮我实现某个功能"（这是执行任务，不是编写文档）
- 用户未显式引用 @feature-planning
✅ 触发条件
必须同时满足：
- 用户明确说出"使用 feature-planning"或"启动 feature-planning"，或显式引用 @feature-planning
- 用户需要开发新功能并需要编写执行方案文档
与 refactor-planning 的区别
| 维度 | refactor-planning | feature-planning |
|---|
| 目标 | 现有代码改造 | 新功能开发 |
| 问题来源 | 代码痛点（耦合、边界、命名） | 用户需求 + 现状障碍 |
| 核心动作 | 先建 → 改引用 → 验证 → 删除 | 现状统计 → 方案对比 → 架构设计 → 实施步骤 |
| 文档状态 | 状态流转（issues → plan → resolved） | 一次性执行方案文档 |
| 验收标准 | 代码验证（测试通过） | 功能验收标准（覆盖率、性能） |
核心原则
原则一：现状数据驱动
不要表面总结。根据场景选择关键指标统计：
可选维度（根据需求场景选取）：
- 规模维度：文件数量、数据量、模块数量
- 时间维度：处理耗时、前置时间、开发周期
- 质量维度：覆盖率、精度、成功率（如适用）
- 成本维度：API 调用、人力投入（如适用）
核心要求：选择能说明问题规模的指标，用数据说话，不是"很多"、"不少"模糊描述。
原则二：方案对比必须量化
多方案必须对比，根据场景选择对比维度：
可选维度：
- 时间：前置时间、开发时间、维护成本
- 经济：API/服务费用、人力投入、资源消耗（如适用）
- 质量：精度、稳定性、可扩展性（如适用）
- 风险：技术复杂度、依赖不确定性
给出推荐方案 + 理由，不是列一堆选项让用户自己选。
原则三：架构关系必须可视化
新功能与现有系统的关系：
- 依赖哪些模块（复用什么）
- 不依赖哪些模块（保持隔离）
- 新增哪些文件（放在哪里）
用 ASCII 图展示耦合关系，不是文字描述。
原则四：文档自包含
文档必须自包含：
- 不引用外部文档（README、ARCHITECTURE）
- 不依赖当前对话记忆
- 不假设行号（用 grep 定位）
原则五：实施步骤可执行
每个步骤必须包含：
- 目标（一句话）
- 具体操作（不是抽象描述）
- 预估时间
- 验收标准
执行流程
Phase 1：现状数据统计
根据需求场景统计当前状态。
识别相关内容的方法：
- 从需求关键词推断目录（如"搜索增强" → search/、infra/embedding）
- 查看现有相关命令入口：
ls cli/*.py 或查看主入口文件
- 查看现有数据结构：
ls data/、ls schemas/（如有）
- 查看配置文件：
ls config/（如有）
统计方法：
- 数量统计：
find {相关目录} -type f | wc -l
- 目录结构：
ls -la {相关目录}/
- 从日志提取数据（如有）：读取最近日志文件，提取关键指标
输出具体数据，不是模糊描述。
Phase 2：问题障碍识别
分析现状后识别核心障碍。
分析流程：
Step 1: 统计现状 → 问"缺什么？"
- 数据缺失？（缺少必要字段、状态）
- 能力缺失？（现有功能不支持）
Step 2: 看架构 → 问"哪里不支持？"
- 模块边界限制？
- 依赖关系限制？
Step 3: 算成本 → 问"能不能承受？"
- 时间限制？
- 资源/预算限制？
Step 4: 看技术 → 问"能力够不够？"
- 技术栈限制？
- 外部依赖限制？
障碍类型（根据场景）：
- 数据缺失（缺少必要信息或状态）
- 架构限制（模块耦合或隔离不足）
- 成本限制（资源、时间、预算）
- 技术限制（能力边界、依赖不确定性）
明确障碍后才能设计方案。
Phase 3：方案对比与推荐
提出 2-3 个方案，进行量化对比。
方案来源：
- 用户需求本身（用户已提出方案倾向）
- 从障碍推导（每个障碍对应一个解决思路）
- 行业常见做法（同类功能的标准实现）
对比方法：
每个方案回答：
- 时间：前置时间多少？开发多久？维护成本？
- 经济：需要什么资源？费用多少？（如适用）
- 质量：效果如何？精度/稳定性/用户体验？
- 风险：技术难度？依赖不确定性？
推荐格式：
方案 A：{名称} — 推荐
时间：{具体数值}
成本：{具体数值}（如适用）
质量：{具体评估}
理由：{为什么推荐}
方案 B：{名称}
...
推荐：方案 A，理由：{一句话}
用户可调整，但必须有默认推荐。
Phase 4：设计细节讨论
针对推荐方案，讨论设计细节。
必须询问用户的问题：
- 输出位置偏好：新建文件 vs 扩展现有文件？
- 是否需要断点续传/进度追踪？
- 是否入库/入数据库？（如涉及数据）
- CLI 命令命名偏好？（如涉及命令）
询问格式：
设计细节确认：
1. 输出位置
- A：新建 {文件名}（独立，易维护）
- B：扩展 {现有文件}（复用现有结构）
推荐：A，理由：{一句话}
你的选择？
2. 断点续传
需要？不需要？
推荐：{根据场景}
你的选择？
...
讨论后给出推荐组合，用户确认后继续。
Phase 5：架构分析
分析新功能与现有系统的关系。
分析方法：
Step 1: 目录结构扫描
ls {src 或项目根} → 了解模块划分
Step 2: 导入关系追踪
grep -r "from.*{模块}" {相关目录} → 看依赖链
Step 3: 现有同类功能位置
找到类似功能的文件 → 定位新增文件位置
架构关系图格式：
┌─────────────────────────────────────┐
│ 现有系统 │
├─────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ infra/ │ │ {业务}/ │ │
│ │ (复用) │←───→│ (隔离) │ │
│ └──────────┘ └──────────┘ │
│ │ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ {新功能}/ │ ← 新增 │
│ │ (放在哪里) │ │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────┘
复用：{列出具体模块}
隔离：{列出具体模块}
新增：{列出文件位置}
输出耦合关系图。
Phase 6：文档编写
写入执行方案文档（落入项目文档目录）。
通用文档结构：
一、问题背景（现状数据 + 用户需求）
二、解决方案（方案对比 + 推荐）
三、架构设计（文件位置 + 耦合关系）
四、数据结构设计（新增文件格式，如需要）
五、CLI 命令设计（如需要）
六、实施步骤（任务清单 + 预估时间 + 依赖）
七、验收标准
八、后续功能预留
九、风险应对
十、决策记录
根据需求场景增删章节，不要生搬硬套。
Phase 7：质量检查
检查项：
- 是否有现状数据统计？
- 是否有方案对比 + 推荐？
- 是否有架构关系图？
- 是否引用外部文档？（改为自包含说明）
- 实施步骤是否可执行？（有目标、操作、时间、验收）
不符合时修正。
反模式
| 反模式 | 正确做法 |
|---|
| 表面总结"数据很多" | 统计具体数量 |
| 列一堆方案让用户选 | 给推荐方案 + 理由 |
| 文字描述架构关系 | 用 ASCII 图展示耦合 |
| 引用外部文档 | 改为自包含说明 |
| 实施步骤抽象（"编写脚本"） | 具体操作（"创建 {模块}/{文件}，预估 Xh"） |
| 缺少验收标准 | 每个功能有验收指标 |
文件命名约定
执行方案文档落入项目文档目录：
格式：{功能名}_implementation.md
示例：docs/search_implementation.md
完成检查清单
标记文档完成前确认：
