codebase-research

代码库研究

概述

在现有项目中编写新代码之前，先了解项目中已有的内容。代码库本身是最权威的参考，能说明应如何构建代码。每个项目都会逐渐形成约定、模式和隐含标准，新代码必须遵守这些规范。

核心原则： 编码前先搜索当前代码库。查找相似的文件、函数和模式。严格遵循现有约定。当已有实现方式时，绝不另辟蹊径。

没有例外。没有变通办法。没有捷径。

首要指令

NO NEW CODE WITHOUT UNDERSTANDING THE EXISTING CODE FIRST

如果你没有搜索当前代码库中是否已有相同模式的实现，就有可能导致代码不一致。没有找到相似内容？记录你搜索过的内容。然后再开始构建，并有意识地确立约定。

不要找借口：

• 不要“先开始编码，之后再检查约定”
• 不要假设你偏好的模式就是项目采用的模式
• 如果项目已经使用了同等功能的库，就不要引入新库
• 不要创建与现有结构相矛盾的新文件结构
• 如果项目已经始终如一地采用另一种方式，那么“我知道怎样做最好”并不重要

适用场景

必须使用：

• 为现有代码库添加新功能
• 创建新文件、组件、模块或服务
• 实现可能已在项目其他位置存在的模式
• 为现有功能编写测试
• 添加错误处理、日志记录或验证逻辑

尤其有用的场景：

• 项目已建立架构模式（MVC、六边形架构等）
• 已有与你需要创建的内容相似的文件
• 代码库包含自定义实用工具、辅助函数或共享模块
• 项目采用特定的命名约定或代码组织规则
• 已有测试能够展示预期的测试方式

入门流程

digraph codebase_research_gate {
    rankdir=TB;
    start [label="Task: Write new code\nin existing project", shape=doublecircle];
    search [label="SEARCH\ncurrent codebase for\nsimilar implementations", shape=box];
    found [label="Similar patterns found?", shape=diamond];
    analyze [label="ANALYZE\nConventions, structure,\nnaming, error handling", shape=box];
    template [label="Use as template?\n(follow the pattern)", shape=diamond];
    follow [label="FOLLOW\nMatch the existing pattern\nexactly", shape=box style=filled fillcolor=lightgreen];
    adapt [label="ADAPT\nUse the convention\nwith modifications", shape=box style=filled fillcolor=lightyellow];
    establish [label="ESTABLISH\nNo precedent exists;\ncreate a deliberate\nnew convention", shape=box];
    document [label="Document search results\nand decision rationale", shape=box];

    start -> search;
    search -> found;
    found -> analyze [label="yes"];
    found -> document [label="no"];
    document -> establish;
    analyze -> template;
    template -> follow [label="yes - close match"];
    template -> adapt [label="partially - same idea\ndifferent details"];
}

在现有项目中编写新代码之前：

1. 搜索——在代码库中查找相似的文件、函数、模式和约定
2. 分析——研究现有代码如何处理相同的问题
3. 匹配——让新代码遵循既定约定
4. 然后才——开始编写

搜索方法

搜索内容

准备创建新内容时，搜索代码库中的以下各项：

搜索目标	原因	方法
相似文件	找到可遵循的模板	使用 Glob 搜索名称或目录相似的文件
相似函数	匹配函数签名和模式	使用 Grep 搜索执行类似工作的函数
导入和依赖项	使用项目已有的内容	使用 Grep 搜索导入语句，找出已采用的库
错误处理	遵循项目的错误处理模式	使用 Grep 搜索 try/catch、Result 类型和错误类
命名约定	使用相同的大小写格式和术语	阅读相邻文件，检查使用的是 camelCase、snake_case 还是 kebab-case
文件组织	将新文件放在合适的位置	列出目录结构，查找相似代码的位置
测试模式	按照项目现有的方式编写测试	查找相似模块的测试文件，并匹配其结构
配置模式	遵循现有的配置方式	搜索 .env 用法、配置文件和常量

搜索技巧

结构化搜索顺序——按照以下顺序操作，以确保全面覆盖：

1. DIRECTORY SCAN: List files in the relevant directories
   -> Understand the project's file organization

2. SIMILAR FILE SEARCH: Glob for files with similar names or purposes
   -> Find the closest existing template for what you need to build

3. PATTERN GREP: Search for specific patterns you plan to use
   -> Confirm the project's approach to that pattern

4. IMPORT ANALYSIS: Check what libraries and utilities are already imported
   -> Use existing dependencies rather than introducing new ones

5. TEST FILE REVIEW: Find tests for similar functionality
   -> Match the testing approach, assertion style, and setup patterns

编写新代码前的最低要求： 至少检查代码库中的 2 个相似文件。

约定匹配

一致性原则

代码库中的做法是什么，你就照着做。个人偏好无关紧要。项目一致性高于个人意见。

维度	完全保持一致
命名	变量名、函数名、文件名、类名
结构	文件布局、目录组织、模块边界
模式	项目处理状态、错误、异步和验证的方式
风格	格式、注释风格、文档编写方式
依赖项	使用项目现有的库，而非替代方案
测试	测试框架、断言库、设置/清理方式
错误处理	抛出还是返回、错误类型、错误消息

常见的约定线索

LOOK FOR these indicators of established conventions:

- Linter/formatter config (.eslintrc, .prettierrc, rustfmt.toml, etc.)
  -> These are explicit rules. Follow them exactly.

- Shared utility files (utils/, helpers/, lib/, common/)
  -> These are the project's building blocks. Use them.

- Base classes or interfaces (BaseController, AbstractService)
  -> These define the inheritance/composition pattern. Extend them.

- Barrel files (index.ts, __init__.py, mod.rs)
  -> These define the export pattern. Add to them.

- Test helpers (test/helpers/, fixtures/, factories/)
  -> These are the testing infrastructure. Build on them.

分析清单

在代码库中找到类似代码时，请从中总结以下问题的答案：

1. FILE PLACEMENT: Where does this type of file live?
   -> Same directory? Nested by feature? Grouped by type?

2. FILE NAMING: What naming pattern does the file follow?
   -> ComponentName.tsx? component-name.ts? component_name.py?

3. EXPORTS: How are things exported?
   -> Default export? Named exports? Re-exported from barrel?

4. FUNCTION SIGNATURES: What do similar function signatures look like?
   -> Parameter ordering, return types, async vs sync

5. ERROR HANDLING: How does this part of the codebase handle errors?
   -> Try/catch? Result types? Error callbacks? Thrown exceptions?

6. LOGGING: Does the project have a logging pattern?
   -> Logger instance? Console methods? Structured logging?

7. VALIDATION: How does the project validate input?
   -> Zod? Joi? Manual checks? Type guards?

8. STATE MANAGEMENT: How is state handled?
   -> Redux? Zustand? Context? Signals? Local state?

9. TESTING APPROACH: What do tests for similar code look like?
   -> Unit tests? Integration? What assertion library?

10. DOCUMENTATION: Are there JSDoc comments, docstrings, or inline docs?
    -> Match the existing documentation density and style.

没有先例时

有时你确实在构建代码库中从未实现过的内容。这种情况下：

1. 确认不存在 -- 至少用 3 种不同方式搜索，确保没有先例
2. 检查相邻项目 -- 如果这是一个单体仓库，请检查同级软件包
3. 查阅外部来源 -- 使用 godmode:github-search 查找公开仓库中的模式
4. 有意确立约定 -- 创建新约定时，使其符合现有代码库的精神
5. 记录决策 -- 说明引入新模式的原因

与其他技能的集成

意图探索期间

当 godmode:intent-discovery 探索项目情况时：

1. 搜索代码库，查找与拟议功能相关的现有实现
2. 报告约定，指出新功能必须遵循的规范
3. 找出可复用代码 -- 已能解决部分问题的实用工具、组件和服务

实现期间

设计获批后编写代码时：

1. 找到模板文件 -- 找出与要创建的文件最相近的现有文件
2. 复制结构 -- 完全遵循模板的组织方式
3. 替换具体内容 -- 保留模式，同时替换领域细节
4. 验证一致性 -- 将新文件与模板进行比较，找出偏差

认知陷阱

合理化说辞	事实
“我的做法比项目现有的更简洁”	项目整体的一致性比局部完美更重要。两种模式不如一种足够好的模式。
“我会重构现有代码，让它符合我的风格”	重构是独立的任务。现在先遵循现有风格。若有必要，之后再提议重构。
“项目没有这方面的模式”	你彻底搜索过了吗？检查 3 个以上相似文件。如果确实没有先例，就有意确立一种模式。
“我不需要检查——这是一个新模块”	新模块仍属于现有项目，必须遵循项目约定。
“现有模式已经过时了”	过时但一致，胜过现代但不一致。应提议迁移，而不是另起一套。
“检查约定会拖慢我的速度”	编写无法通过审查或导致不一致的代码，会更拖慢进度。
“这只是一个小型实用函数”	小型实用函数最容易被重复使用。模式一旦用错，就会影响所有依赖它的内容。

约束

禁止的操作：

• 未搜索代码库中的类似实现就编写新代码
• 项目已使用等效库时引入新库
• 创建与现有组织结构相矛盾的文件结构
• 使用不同于项目既定规范的命名约定
• 跳过测试模式匹配（“我会按自己的方式编写测试”）

必须执行的操作：

• 编写新代码前，至少搜索代码库中的 2 个类似文件
• 完全遵循周边代码的命名约定
• 使用现有共享实用工具和辅助函数，而不是创建重复项
• 遵循项目既定的测试模式
• 代码库中没有先例时，记录调研结果

快速参考

SEARCH -> ANALYZE -> MATCH -> BUILD

Search: Find 2+ similar files, grep for patterns, check imports
Analyze: Extract conventions for naming, structure, error handling, testing
Match: Align your new code with every convention you found
Build: Write code that looks like it belongs in the project

集成

调用时机：

• godmode:intent-discovery —— 在“调查项目概况”阶段搜索代码库
• godmode:reference-engine —— 为内部代码模式调研路由至此
• godmode:task-planning —— 在每项实现任务开始前核实规范
• godmode:quality-enforcement —— 根据代码库模式检查一致性

互补技能：

• godmode:github-search —— 搜索外部仓库、GitHub 和软件包注册表，查找可研究或采用的开源实现、库和模式
• godmode:pattern-matching —— 在代码库中进行更深入的模式分析
• godmode:specification-first —— 将代码库规范融入正式规格
• godmode:project-bootstrap —— 启动新项目时使用（没有现有代码库可供调研）