codebase-knowledge-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Knowledge Builder

代码库知识构建器

Transform from a generalist into a codebase specialist by systematically studying a repository and producing high-quality knowledge artifacts. The process follows a strict "read first, write later" principle across four sequential phases.

通过系统性地研究仓库并生成高质量知识制品，从通用型角色转变为代码库专家。整个流程遵循严格的“先阅读、后输出”原则，分为四个连续阶段。

Prerequisites

前提条件

File read access to the target repository (cloned locally or accessible via tools)
Bash access for file counting and structure discovery
Write access to produce scratch files and final artifacts

拥有目标仓库的文件读取权限（本地克隆或可通过工具访问）
具备Bash访问权限，用于文件计数和结构探索
拥有写入权限，用于生成临时文件和最终制品

Workflow

工作流程

Reconnaissance -- Build a broad mental model of the entire repo
Deep-Dive Study -- Investigate each requested topic in isolation
Artifact Authoring -- Synthesize findings into polished knowledge artifacts
Delivery -- Package and deliver artifacts to the user

侦察阶段 —— 构建整个仓库的宏观心智模型
深入研究阶段 —— 独立调查每个请求的主题
制品创作阶段 —— 将研究结果整合为精炼的知识制品
交付阶段 —— 打包并向用户交付制品

Phase 1: Reconnaissance

阶段1：侦察

Clone the repo and build a high-level map before touching any specific topic.

Run

find . -type f -name '*.js' -o -name '*.ts' -o -name '*.py' | head -50

and

wc -l

to gauge scale.

Read the main entry point file end-to-end.
Follow the checklist in
```
references/recon-checklist.md
```
to systematically discover architecture, entry points, config systems, and key abstractions.
Save a structured summary to a scratch file (
```
recon_findings.md
```
) with: tech stack, directory map, module responsibilities, design patterns, and open questions.

Do not proceed to Phase 2 until the repo's architecture can be described in one paragraph.

在接触任何特定主题之前，先克隆仓库并构建高层级地图。

运行

find . -type f -name '*.js' -o -name '*.ts' -o -name '*.py' | head -50

和

wc -l

来评估代码规模。

完整阅读主入口文件。
按照
```
references/recon-checklist.md
```
中的清单，系统性地探索架构、入口点、配置系统和核心抽象。
将结构化总结保存到临时文件（
```
recon_findings.md
```
）中，内容包括：技术栈、目录结构、模块职责、设计模式和待解决问题。

只有当能够用一段话描述仓库架构时，才能进入阶段2。

Phase 2: Deep-Dive Study

阶段2：深入研究

For each topic the user requests, perform a focused investigation. Study each topic separately -- do not mix concerns.

Read
```
references/deep-dive-methodology.md
```
for file reading strategies, tracing patterns, and note-taking protocol.
Start from the subsystem's entry point and follow imports outward (dependency order, not alphabetical).
Trace three paths per subsystem: happy path, error path, edge cases.
After every 2-3 files, save key findings to a scratch file. Do not rely on context memory alone.
For each file, capture: purpose (one sentence), key functions, what it calls, what calls it, and gotchas.

针对用户请求的每个主题，开展聚焦式调查。单独研究每个主题——不要混合关注点。

阅读
```
references/deep-dive-methodology.md
```
，了解文件阅读策略、追踪模式和笔记记录规范。
从子系统的入口点开始，向外追踪依赖导入（按依赖顺序，而非字母顺序）。
为每个子系统追踪三条路径：正常路径、错误路径、边缘场景。
每阅读2-3个文件后，将关键发现保存到临时文件中。不要仅依赖上下文记忆。
针对每个文件，记录：用途（一句话）、核心函数、调用的对象、被哪些对象调用，以及注意事项。

Phase 3: Artifact Authoring

阶段3：制品创作

Synthesize each topic's findings into a standalone knowledge artifact.

Copy the template from
```
templates/knowledge_artifact.md
```
for each topic.
Fill every section -- Overview, Architecture, Key Components table, Data & Control Flow, Key Functions table, Configuration table, Gotchas, Extension Points, and Visual Flow diagram.
Include Mermaid diagrams: use
```
sequenceDiagram
```
for flows,
```
graph TD
```
for architecture.
Each artifact must be self-contained -- a developer reading only that artifact should understand the subsystem completely.

将每个主题的研究结果整合为独立的知识制品。

为每个主题复制
```
templates/knowledge_artifact.md
```
中的模板。
填写所有章节——概述、架构、核心组件表格、数据与控制流、核心函数表格、配置表格、注意事项、扩展点和可视化流程图。
包含Mermaid图表：使用
```
sequenceDiagram
```
展示流程，使用
```
graph TD
```
展示架构。
每个制品必须具备自包含性——仅阅读该制品的开发者应能完全理解子系统。

Phase 4: Delivery

阶段4：交付

Attach all completed Markdown artifacts to a message to the user. Include a brief summary of what each artifact covers.

将所有完成的Markdown制品附加到消息中发送给用户。简要说明每个制品涵盖的内容。

Limitations

局限性

Large monorepos (>10,000 files) may require scoping to specific directories or packages before starting reconnaissance.
Binary files, compiled assets, and vendored dependencies should be excluded from study.
Knowledge artifacts reflect the codebase at a point in time. Major refactors may invalidate sections.

大型单体仓库（超过10,000个文件）可能需要在侦察阶段前限定到特定目录或包。
二进制文件、编译资产和第三方依赖库应排除在研究范围之外。
知识制品反映的是代码库某一时刻的状态。重大重构可能导致部分内容失效。

Quality Checklist

质量检查清单

Before delivering any artifact, verify:

Check	Criteria
Completeness	Every template section is filled with codebase-specific detail, not placeholders.
Accuracy	File paths, function names, and parameter descriptions match the actual code.
Gotchas	At least 2-3 non-obvious behaviors, historical fixes, or race conditions documented.
Visuals	At least one Mermaid diagram per artifact.
Self-contained	A reader with no prior context can understand the subsystem from the artifact alone.

交付任何制品前，需验证以下内容：

检查项	标准
完整性	模板的每个章节都填充了代码库的具体细节，而非占位符。
准确性	文件路径、函数名称和参数描述与实际代码一致。
注意事项	至少记录2-3个非显而易见的行为、历史修复或竞态条件。
可视化	每个制品至少包含一个Mermaid图表。
自包含性	没有前置背景知识的读者仅通过该制品就能理解子系统。

Bundled Resources

内置资源

Resource	Path	When to Read
Recon Checklist	`references/recon-checklist.md`	At the start of Phase 1
Deep-Dive Methodology	`references/deep-dive-methodology.md`	At the start of each Phase 2 topic
Artifact Template	`templates/knowledge_artifact.md`	At the start of Phase 3 for each topic

资源	路径	阅读时机
侦察清单	`references/recon-checklist.md`	阶段1开始时
深入研究方法论	`references/deep-dive-methodology.md`	每个阶段2主题开始时
制品模板	`templates/knowledge_artifact.md`	每个阶段3主题开始时