chuxinneko/nekocodedesktop/explore-codebase

摸清代码库

目标是能回答三个问题：这个项目做什么、代码从哪里开始跑、我要找的东西在哪一层。

按下面的顺序走。每一层都先形成结论再往下，不要一上来就逐个文件读——大项目里那样读永远读不完，而且记不住。

一、外围（5 分钟）

按这个顺序看，越往后价值越低：

1. README.md —— 项目做什么、怎么跑起来。
2. package.json / pyproject.toml / go.mod / Cargo.toml —— `scripts` 段最有用：构建、测试、启动的真实命令在这里。依赖列表说明技术栈。
3. CLAUDE.md / AGENTS.md / CONTRIBUTING.md —— 项目自己写给协作者的约定，优先级高于你的习惯。
4. 顶层目录结构：ls，只看一层。目录名通常已经说明了分层方式（按层 src/api,src/db 还是按功能 src/billing,src/auth）。

二、找入口

不要靠猜，按类型找：

• CLI：package.json 的 bin / main，或 if __name__ == "__main__"。
• 服务端：搜 listen(、createServer、app.run、路由注册处。
• 桌面/前端：index.html → 挂载点 → 根组件；Electron 看 main 字段。
• 库：src/index.* 的导出列表就是它的公开面。

找到入口后只读顶层流程：初始化了什么、注册了什么、启动了什么。遇到函数调用先记下名字，不要立刻跳进去。

三、沿一条真实路径穿一遍

选一个具体功能（用户提的那个，或 README 里的主要用例），从入口跟到结果，完整走一遍：

用户操作 → 入口 → 路由/分发 → 业务逻辑 → 数据读写 → 返回

这一遍能同时告诉你分层方式、命名习惯、错误处理风格、数据怎么流动——比读十个孤立文件有用得多。

搜索用：

• grep 找符号定义和调用点。找定义时搜 function <名字>、class <名字>、const <名字> =。
• 找某个界面文字对应的代码：直接搜那串文字（注意可能在 i18n 文件里，再用 key 反查）。
• 找某行逻辑的来历：git log -S"<代码片段>" 直接定位引入它的提交，提交信息常常解释了原因。

四、看测试

测试是最诚实的文档：它写明了模块被期望怎么调用、边界在哪。

• 找到和目标模块同名的测试文件，读两三个用例。
• 集成测试/e2e 测试给出完整的使用场景。
• 测试的 fixture 揭示了真实数据长什么样。

五、形成结论

至少能说清：

• 做什么：一句话。
• 怎么跑：安装、启动、测试的具体命令（从 scripts 里抄，不要编）。
• 分层：有哪几层，各自负责什么，目录对应关系。
• 主流程：你穿过的那条路径，按调用顺序列出关键文件。
• 约定：命名、错误处理、状态管理、测试方式。
• 没搞清的部分：明确列出来，不要用含糊的描述掩盖。

回答时引用具体的 文件:行号，让用户能跳过去验证。

注意

• 不要读 node_modules、dist、out、vendor、构建产物和 lock 文件。
• 生成的代码（含 generated、.pb.、.d.ts 等）先跳过，需要时再看。
• 大文件先用 grep -n 定位再局部读，不要整个文件读进来。
• 目录里同时存在新旧两套实现时，看 git log 的修改时间判断哪套是活的。