| name | codebase-survey |
| description | 代码侦察技能。给定一个需求描述或 spec，扫描 src/ 目录，输出与本次需求相关的现有模块、可复用资产、潜在冲突、推荐参考代码模式的结构化清单。被 spec-drafting 和 implementation-planning 调用，确保 spec 与 plan 都建立在「已理解现有代码」的基础上。也可由用户独立触发用于代码现状梳理。 |
代码侦察（Codebase Survey）
理解现有代码实现，识别新需求与现有代码的关联，输出结构化报告。
为什么需要这一步
AI 没看代码就起草 spec/plan，本质上是另一种"vibe coding"。代码侦察是显式化这个步骤，让产出可验证、可复用、可沉淀。
调用模式
支持两种深度，由调用方指定：
| 模式 | 调用方 | 关注粒度 | 阅读深度 | 输出位置 |
|---|
| light | spec-drafting（阶段零） | 模块级 | 接口 / 入口 / 注释 | spec 的「实施备注」+「关键代码参考」 |
| deep | implementation-planning（阶段二） | 文件 / 函数级 | 实现细节 / 调用链 / 设计模式 | plan 的「改动范围」+「关键代码参考」+「实施步骤」参考字段 |
用户也可以独立触发（如"帮我看下 wecardexample-app 现状"），此时默认 light 模式。
执行步骤
Step 1: 收集线索
- 从需求/spec 中提取关键词（业务名词、模块名、接口名）
- 列出潜在相关的目录（如
src/example-gateway/、src/wecardexample-app/）
Step 2: 扫码侦察（按模式）
Light 模式（阶段零用）
- 读取相关模块的
interface.go / 主入口 / service.go
- 识别已有功能的作用、输入输出、调用方
- 不深入实现细节
- 时间预算：< 5 分钟（约 5-10 个文件）
Deep 模式（阶段二用）
- 在 light 基础上深入：
- 阅读 controller / service 的具体实现
- 跟踪关键调用链（A → B → C 全路径）
- 识别已有设计模式（如 enroll-flow 的 9 步流程）
- 评估接口变更的影响范围
- 时间预算：< 20 分钟（约 15-30 个文件）
Step 3: 分析与结构化
按以下维度归类：
- 相关模块：哪些模块与本次需求相关
- 可复用资产：已有的工具函数、接口、设计模式
- 冲突 / 重叠：与现有 spec 或代码功能是否重复
- 推荐参考的代码模式：实施时应模仿哪个已有实现
- 潜在影响：本次改动可能影响哪些调用方
- 不确定项：哪些代码意图不清楚，需要人确认
Step 4: 输出报告
按调用模式选择对应输出格式（见下文）。
Step 5: 写入目标位置
- Light：合并到 spec 的对应章节
- Deep：合并到 plan 的对应章节
- 独立触发：输出到对话，由用户决定是否单独存到
docs/research/NNNN-codebase-survey.md（可选）
输出格式
Light 模式输出
### 代码侦察报告（light）：[需求标题]
**相关模块**：
| 模块路径 | 作用 | 与本需求关系 |
|---------|------|-------------|
| `src/example-gateway/` | API 网关 | 需新增示例业务 HTTP 接口 |
| `src/wecardexample-app/` | 业务应用层 | 需新增示例业务 controller |
**可复用资产**：
- `utils.GenerateUint64FromUUID()` — `src/common/utils/uuid.go` — 用于生成 biz_id
- `middleware.GetUserIdFromContext()` — `src/.../middleware/path_based.go` — 用于获取 user_id
**冲突 / 重叠**：
- 与现有 specs/<其他 STORYID> 的 X 功能可能重叠 — 建议[合并/独立/明确边界]
- 不与现有 spec 冲突
**推荐参考的代码模式**：
| 要做什么 | 参考文件 |
|---------|---------|
| Controller 9 步流程 | `controller/example-module/enroll-flow/login.go` |
| 示例通道 调用 | `common/example-vendor/providers/wechat/register.go` |
**初步影响估计**：
- 预计需要新增：N 个文件（粗估）
- 预计需要修改：M 个文件（粗估）
- 跨模块：是 / 否
- 跨仓库：是 / 否（如涉及 proto 仓）
**不确定项 / 需要人确认**：
- [ ] 现有 X 模式是否还推荐使用？
- [ ] 是否有内部约定我没扫到的？
Deep 模式输出
### 代码侦察报告（deep）：Spec NNNN
**改动文件清单**（精确到文件 + 关联 FR）：
| 操作 | 文件 | 关联 FR | 说明 |
|------|------|---------|------|
| 新增 | `src/.../online_register.go` | FR-3 | gateway 服务方法 |
| 修改 | `src/.../service.go` | FR-3 | 新增 GetExampleAppClient |
| 修改 | `src/.../config.yaml` | FR-3 | 新增 wecardexample-app 服务地址 |
**调用链分析**：
HTTP POST /api/v1/example/online-register
→ PathBasedMiddleware → HTTPTokenMiddleware（取 user_id）
→ example-gateway.OnlineRegister（透传）
→ wecardexample-app.OnlineRegister（业务逻辑）
→ example-vendor.wechat.OnlineRegister（远端调用）
→ <业务主仓库>.PrivateRecognition.OnlineRegister
**接口影响**：
- 新增公共接口：[列表]
- 修改公共接口：[列表 + 是否兼容]
- 影响的调用方：[列表]
**已有设计模式**（必须遵循）：
| 模式 | 参考实现 | 关键约束 |
|------|---------|---------|
| Controller 9 步流程 | `enroll-flow/login.go` | 配额预扣 → 失败回退；状态更新失败不回退配额 |
| 示例通道 | `wechat/register.go` | 30s 超时；TraceID 优先做 session_id |
| 日志脱敏 | `sensitive.MaskSensitiveValue` | 禁用 `%+v` 打印请求结构体 |
**影响范围风险**：
| 风险 | 概率 | 应对 |
|------|------|------|
| Proto 改动需先合并 <协议仓库> | 高 | 本地用 replace 联调，提交前去掉 |
| 鉴权路径误命中其他中间件 | 低 | 已验证不命中 |
**不确定项 / 需要人确认**：
- [ ] 错误码 100034-100037 是否有冲突？
- [ ] FRegisterType 用 Mobile 还是新增 Online？
注意事项
❌ 不要做
- 不要扫描超出需求范围的代码（避免上下文爆炸）
- 不要把侦察结果写成"我修改了什么"——这一步还没改任何代码
- 不要假设代码意图（标注「AI 推断」与「从代码读出的事实」）
- Light 模式不要进入实现细节
- Deep 模式不要扫毫无关联的模块
✅ 应该做
- 优先读
interface.go / 入口文件，按需向下深入
- 遇到不理解的代码意图，列入「不确定项」
- 标注每条发现的来源（哪个文件的哪一段）
- 优先复用已有资产，而不是建议新增
- 引用相关已有 spec / plan 作为关联背景
与其他 Skill 的关系
spec-drafting (阶段零)
└─ 调用 → codebase-survey (light)
└─ 输出合并到 spec 的「实施备注」+「关键代码参考」
implementation-planning (阶段二)
└─ 调用 → codebase-survey (deep)
└─ 输出合并到 plan 的「改动范围」+「关键代码参考」
feature-implementation (阶段三)
└─ 不调用 codebase-survey（按 plan 执行；改文件前的局部读取由 rules/20-coding-rules.md 规定）
关联资产
- 被调用方：
skills/spec-drafting/SKILL.md、skills/implementation-planning/SKILL.md
- 规则：
rules/10-spec-workflow.md 阶段零、阶段二
- 可选独立产物：
docs/research/NNNN-codebase-survey.md（仅在大型跨模块需求时使用）
