Code Survey

---
name: code-survey
description: 设计前对代码库按需调研（只查与当前需求相关的维度），优先查项目记忆与专家/方案资产，不足再搜代码，多维并行加速。触发："代码调研"、"了解现有代码"、"项目代码风格"、"架构调研"，或设计前置阶段。
---

# 代码现状调研

## 概述

**目的**：在设计前充分了解当前代码库中与需求相关的信息，确保设计与现有代码风格、架构保持一致。

**功能**：按需调研代码库的 13 个维度，根据需求特征自动筛选需要调研的维度，强制先使用 ki-search 查询相关项目记忆，并调用 use_skill("expert-solution-workflow") 触发资产复用，代码搜索阶段 ≥ 2 个维度时自动调用 `task-dispatch` 并行搜索加速。

**使用场景**：
- design-craft 技能执行前置信息收集阶段时
- 任何需要在设计前了解现有代码的场景
- 用户说"了解一下现有代码"、"代码风格是什么"、"这个功能的代码在哪里"时

## 核心原则

1. **按需调研**：只调研与当前需求相关的维度，不相关的跳过
2. **ki-search 与资产复用优先**：先使用 ki-search 查询相关项目记忆 → 调用 use_skill("expert-solution-workflow") 触发资产复用（expert-lookup / solution-lookup）→ **若仓库已有代码索引则调 `use_skill("index-lookup")` 拿模块/页面地图，缩小搜索域（无索引自动降级，不阻塞）** → 代码搜索 → 语义检索兜底。禁止跳过 ki-search 直接搜代码
3. **必须执行**：ki-search 为必查项，即使觉得"不太可能有"，也要实际调用确认；**无论是否命中，都必须触发资产复用**
4. **并行加速**：需代码搜索的维度 ≥ 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`）

**子任务拆分**：每个需搜索的维度拆为一个子任务：

```text
| 编号 | 子任务 | 维度 | 搜索目标 |
|------|--------|------|----------|
| 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`
- **文档要求**：
  - 仅记录实际调研过的维度
  - 每个维度标注信息来源（项目记忆 / 资产复用（专家/方案）/ 代码搜索 / 语义检索）
  - 内容简略，重点是帮助设计决策

### 文档模板

```markdown
# 代码调研：{功能名称}

> 调研来源：项目记忆 ✓ | 资产复用（专家/方案） ✗ | 代码搜索 ✓ | 语义检索 ✗
> 调研范围：仅列出与需求相关的维度

## 1. 代码风格（如已调研）
- 命名规范：[简述]
- 代码组织：[简述]

## 2. 相关代码路径（如已调研）
- [文件路径1]：[简要说明]

## 3. 架构概览（如已调研）
- 整体架构：[简述]

## 4. 可参考的类似功能（如已调研）
- [功能/文件]：[参考价值]

## 5. 技术栈约束（如已调研，可引用 dependencies/）
- 框架：[版本]

## 6. 数据存储（如已调研）
- 数据库/ORM：[简述]

## 7. 错误处理（如已调研）
- 异常模式：[简述]

## 8. 安全惯例（如已调研）
- 认证方式：[简述]

## 9. 日志与监控（如已调研）
- 日志框架：[简述]

## 10. API 约定（如已调研）
- 风格：[REST/GraphQL]

## 11. 测试模式（如已调研）
- 框架与组织：[简述]

## 12. 配置管理（如已调研）
- 配置方式：[简述]

## 13. 部署与 CI/CD（如已调研）
- 流程：[简述]
```

> **重要**：代码调研文档作为设计参考，不需要非常详细，但应包含足够的信息帮助设计决策。已知信息不重复调研，仅补充未知部分。**只写与需求相关的维度，无关维度不要出现在文档中。**