/idea：在写代码之前，先把需求问清楚

软件开发中最昂贵的 Bug，不是运行时崩溃，而是方向错了。

你花三天实现了一个功能，发现它和现有模块严重耦合；或者需求理解偏了，实现的是客户想象中的东西，而不是他们实际需要的。这类问题在代码写完之后才暴露，改动成本是写之前的 10 倍。

/idea 是在写代码之前插入的一道闸门，它的目标是：把模糊需求变成基于代码事实的开发文档，然后才允许开始写代码。

为什么需要技能，而不是直接问 AI？

普通 AI 对话也能做需求分析，但有一个根本限制：它不知道你的代码库。它的问题是基于通用经验的，而不是你这个系统的具体结构。

比如，如果你说「我想加一个批量导入功能」，普通 AI 会问「需要支持哪些文件格式？有没有大小限制？」。这些是合理的问题，但它不会问：「你现有的 repos_create 接口扇入是 7，批量导入直接扩展这个接口，还是新建一个路由？」后者这个问题需要知道你的代码结构才能提出来。

/idea 存在的理由就是这个：它先查图谱，再追问。问题有依据，不是凭空猜测。

四个阶段

Phase 1：上下文获取

一次图谱调用，同时获取：

• 与需求最相关的 10-20 个代码实体（函数、类、模块）
• 这些实体的结构属性：扇入（被多少地方调用）、扇出（调用了多少地方）、模块归属
• 当前代码健康评分和主要问题点
• 相关的 GitHub 开源项目调研（同类功能的常见实现方式）

这个阶段的输出是「地图」：你知道这个需求落在代码库的哪个区域，这个区域目前的健康状况，以及业界的通行做法。

Phase 2：苏格拉底式追问

基于 Phase 1 的发现，生成 3-7 个追问。关键是：每个问题都有图谱数据作为依据。

真实测试案例（批量仓库导入功能）生成的问题：

• 「repos_create 扇入为 7，批量操作是扩展现有接口还是新路由？新路由保持接口一致性更好，但增加维护面。」
• 「当前 indexing 模块已有 3 个并发限制相关的配置项，批量导入的并发控制放这里还是在路由层？」
• 「健康度报告显示 upload_batch 函数复杂度较高（FS 指标），批量导入会依赖它吗？如果是，建议先重构再扩展。」

这些问题不是模板，是从你的代码库里挖出来的。不同项目、不同需求，问题完全不同。

Phase 3：技术方案

综合需求理解和代码结构，生成 2-3 个技术方案，每个方案包含：

• 实现路径（改哪些文件，怎么改）
• 影响分析（这个方案会波及哪些下游模块）
• 健康度预测（实现后代码健康评分的变化方向）
• 风险点（什么地方可能出问题）

你选择一个方案，或者让我们根据你的优先级（速度 vs 质量 vs 最小改动）推荐。

Phase 4：开发文档

基于选定方案，生成完整的开发文档。文档自动经过 5 维度审查：

维度	检查内容
需求完整性	所有原始需求点是否都有对应的实现计划
风险覆盖	识别到的风险点是否有缓解方案
测试策略	关键路径是否有对应的测试计划
接口设计	新接口是否与现有接口风格一致
向后兼容	改动是否会破坏现有调用方

审查通过的文档才输出。这份文档是后续所有开发工作的基准——改了什么、为什么改、影响哪里，都有据可查。

实际效果对比

维度	传统需求分析	/idea
耗时	半天到一天	1-2 小时
问题来源	经验假设	图谱数据
方案依据	主观判断	代码结构 + 健康度
影响评估	手工走查，容易漏	自动影响传播分析
输出质量	依赖分析师能力	5 维度自动审查

什么时候用 /idea

/idea 适合以下场景：

• 新功能开发（任何会改动现有模块结构的需求）
• 重构计划（需要理解现有依赖关系才能规划改动范围）
• 接手陌生代码库（快速理解现有结构，制定第一个任务的计划）
• 技术方案评审（在会议前用图谱数据支撑你的方案）

简单的 Bug 修复不需要 /idea，直接用 manon_search 找到相关代码修复即可。