agentleFS
HACK-WUHACK-WU/skills/skills/code-survey/SKILL.md

code-survey

Skill2 starsChanged 52 days agoMITView on GitHub

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

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

代码现状调研

概述

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

功能:按需调研代码库的 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)

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

| 编号 | 子任务 | 维度 | 搜索目标 |
|------|--------|------|----------|
| 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(如已调研)
- 流程:[简述]

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.