code-survey
设计前对代码库按需调研（只查与当前需求相关的维度），优先查项目记忆与专家/方案资产，不足再搜代码，多维并行加速。触发："代码调研"、"了解现有代码"、"项目代码风格"、"架构调研"，或设计前置阶段。
SKILL.mdskills/code-survey/SKILL.md
GitHub代码现状调研
概述
目的：在设计前充分了解当前代码库中与需求相关的信息，确保设计与现有代码风格、架构保持一致。
功能：按需调研代码库的 13 个维度，根据需求特征自动筛选需要调研的维度，强制先使用 ki-search 查询相关项目记忆，并调用 use_skill("expert-solution-workflow") 触发资产复用，代码搜索阶段 ≥ 2 个维度时自动调用 task-dispatch 并行搜索加速。
使用场景：
- design-craft 技能执行前置信息收集阶段时
- 任何需要在设计前了解现有代码的场景
- 用户说"了解一下现有代码"、"代码风格是什么"、"这个功能的代码在哪里"时
核心原则
- 按需调研：只调研与当前需求相关的维度，不相关的跳过
- ki-search 与资产复用优先：先使用 ki-search 查询相关项目记忆 → 调用 use_skill("expert-solution-workflow") 触发资产复用（expert-lookup / solution-lookup）→ 若仓库已有代码索引则调
use_skill("index-lookup")拿模块/页面地图，缩小搜索域（无索引自动降级，不阻塞） → 代码搜索 → 语义检索兜底。禁止跳过 ki-search 直接搜代码 - 必须执行：ki-search 为必查项，即使觉得"不太可能有"，也要实际调用确认；无论是否命中，都必须触发资产复用
- 并行加速：需代码搜索的维度 ≥ 2 时，自动调用 task-dispatch 并行搜索
快速跳过判定
满足以下任一条件时，极简化或跳过本步骤：
- 上下文成熟度为「高」（用户已充分讨论过技术方案）
- 用户明确表示已熟悉项目代码
- ki-search 项目记忆中已有充分的项目架构知识
调研维度
关键：根据需求特征选择维度，只调研需求涉及的部分。 表中"需求特征"列是触发条件。
| 维度 | 调研内容 | 需求特征（命中才调研） |
|---|---|---|
| 代码风格 | 命名规范、代码组织方式、注释风格 | 首次接触该项目 |
| 代码路径 | 与需求相关的现有代码文件、模块位置 | 不清楚需求涉及的模块 |
| 架构模式 | 项目整体架构、模块划分、依赖关系 | 对项目架构不熟悉 |
| 类似功能 | 已有的类似功能实现，可参考的模式 | 不确定项目是否已有参考 |
| 技术栈 | 使用的框架、库、版本约束（可引用 dependencies/） | 首次接触该项目 |
| 数据存储 | 数据库模式、ORM 用法、迁移惯例 | 需求涉及数据模型变更 |
| 错误处理 | 异常处理惯例、错误码规范、重试策略 | 需求涉及异常/边界处理 |
| 安全惯例 | 认证方式、权限模型、输入校验模式 | 需求涉及权限或数据安全 |
| 日志与监控 | 日志框架、日志级别、监控接入方式 | 需求涉及可观测性内容 |
| API 约定 | REST/GraphQL 风格、版本策略、分页与错误响应格式 | 需求涉及新增或修改 API |
| 测试模式 | 测试框架、测试组织方式、断言风格 | 需求包含测试相关内容 |
| 配置管理 | 配置文件组织、环境变量管理、feature flag | 需求涉及配置或环境差异 |
| 部署与 CI/CD | 部署流程、CI 流水线、发布策略 | 需求涉及部署变更 |
调研执行顺序（强制）
禁止跳过 ki-search 直接搜代码。
ki-search 查询项目记忆 → 资产复用（专家/方案） → 代码搜索（并行） → 语义检索兜底
第 1 步：ki-search 查询项目记忆（必查项）
使用 ki-search 查询相关项目记忆：
- 若命中：直接复用记忆内容，跳过对应维度的代码搜索，标注来源「项目记忆」
- 若未命中：记录结果
无论命中与否，都必须进入第 2 步触发资产复用。
第 2 步：资产复用（必查项）
调用 use_skill("expert-solution-workflow") 触发资产复用查询：
- 业务模块类 →
expert-lookup：有专家 → 加载契约层辅助调研；无专家 → 记录「无专家」 - 具体技术问题类 →
solution-lookup：有方案 → 按步骤参考；无方案 → 记录「无方案」 - 将资产复用结果与第 1 步 ki-search 记忆交叉参照后用于调研
第 3 步：代码搜索（并行）
仅当第 1、2 步无法覆盖的维度需要搜索时执行。
架构/依赖调研辅助——强关联关系查询：若调研维度涉及架构模式（模块划分、依赖关系、影响面），先调用 use_skill("ki-memory-lookup") 检索相关模块的强关联关系（跨模块契约/业务耦合），作为架构依赖调研的补充输入，识别"模块间谁牵动谁"（查询失败或无可用记录，忽略继续）。
并行判定
| 需搜索维度数 | 策略 |
|---|---|
| 0-1 个 | 主 agent 直接搜索 |
| ≥ 2 个 | 调用 task-dispatch skill 并行搜索 |
task-dispatch 调度要点
task-name：code-survey-{功能简称}（如 code-survey-jwt-auth）
子任务拆分：每个需搜索的维度拆为一个子任务：
| 编号 | 子任务 | 维度 | 搜索目标 |
|------|--------|------|----------|
| V-01 | API 约定调研 | API 约定 | REST 风格、分页格式、错误响应格式 |
| V-02 | 代码路径调研 | 代码路径 | 涉及需求的相关文件位置 |
| V-03 | 数据存储调研 | 数据存储 | 数据库模式、ORM 用法 |
独立性校验：各维度搜索互不干扰（搜索目标不同、无文件冲突），可同批并行。
子 agent prompt 要点：
你是子 agent，负责代码搜索维度 V-{NN}：{维度名称}
## 调研维度
{维度名称}：{调研内容说明}
## 输出目录
产出：.codebuddy/task-dispatch/code-survey-{功能简称}/subtasks/V-{NN}/code/
- 产出文件：v{NN}-{维度}.md（调研结果，按以下格式）
报告：.codebuddy/task-dispatch/code-survey-{功能简称}/subtasks/V-{NN}/report.md
## 搜索方法
1. 使用 search_content（grep）精确定位代码（优先）
2. 使用 search_file 按文件名模式查找（优先）
3. 以上两步足以覆盖单维度搜索，不推荐嵌套 code-explorer（会增加复杂性）
4. 标注来源为「代码搜索」
## 产出格式（写入 v{NN}-{维度}.md）
### {维度名称}
- **发现**：[简述调研结果]
- **关键文件**：[涉及的文件路径列表]
- **模式与规范**：[识别到的模式/规范/惯例]
- **备注**：[其他发现]
4. 完成后写 report.md，说明搜索范围和关键发现
合并
主 agent 收集各子 agent 的 v{NN}-{维度}.md，汇总到最终 code-survey.md 中。
第 4 步：语义检索兜底
仅当前 3 步均无法覆盖时使用：使用 ki-search 兜底检索。
产出物
生成代码调研文档，必须落盘到文件系统。
落盘规范
- 存储路径：需求目录的
reference/子目录下，文件名code-survey.md - 文档要求：
- 仅记录实际调研过的维度
- 每个维度标注信息来源（项目记忆 / 资产复用（专家/方案）/ 代码搜索 / 语义检索）
- 内容简略，重点是帮助设计决策
文档模板
# 代码调研：{功能名称}
> 调研来源：项目记忆 ✓ | 资产复用（专家/方案） ✗ | 代码搜索 ✓ | 语义检索 ✗
> 调研范围：仅列出与需求相关的维度
## 1. 代码风格（如已调研）
- 命名规范：[简述]
- 代码组织：[简述]
## 2. 相关代码路径（如已调研）
- [文件路径1]：[简要说明]
## 3. 架构概览（如已调研）
- 整体架构：[简述]
## 4. 可参考的类似功能（如已调研）
- [功能/文件]：[参考价值]
## 5. 技术栈约束（如已调研，可引用 dependencies/）
- 框架：[版本]
## 6. 数据存储（如已调研）
- 数据库/ORM：[简述]
## 7. 错误处理（如已调研）
- 异常模式：[简述]
## 8. 安全惯例（如已调研）
- 认证方式：[简述]
## 9. 日志与监控（如已调研）
- 日志框架：[简述]
## 10. API 约定（如已调研）
- 风格：[REST/GraphQL]
## 11. 测试模式（如已调研）
- 框架与组织：[简述]
## 12. 配置管理（如已调研）
- 配置方式：[简述]
## 13. 部署与 CI/CD（如已调研）
- 流程：[简述]
重要：代码调研文档作为设计参考，不需要非常详细，但应包含足够的信息帮助设计决策。已知信息不重复调研，仅补充未知部分。只写与需求相关的维度，无关维度不要出现在文档中。