一次性全文通读代码库：claude-mem 的 learn-codebase 技能与"主动预热"记忆策略

当你接手一个新仓库、或在一段时间后回到一个已经生疏的项目时，最贵的往往不是模型推理，而是"从零摸索上下文"的反复对话。claude-mem 在插件中内置了一个名为 learn-codebase 的技能：它要求 Agent 逐文件、全量、不跳过地读完整个代码库，把整个仓库一次性"装进"记忆系统，从而让后续每个会话都能基于完整的代码理解工作，而不是边干活边补课。本文以该技能的源文件 plugin/skills/learn-codebase/SKILL.md 为骨架，结合插件源码、安装流程、运行提示与配套文档，讲清它是什么、为什么有效、如何正确执行，以及它在 claude-mem"跨会话记忆"体系中的真实位置。

先看技能本体：一个 SKILL.md 如何定义一个"预热"动作

claude-mem 插件以"技能（skill）"的形式把高频工作流固化给 Agent，每个技能对应 plugin/skills/ 下的一个目录，内含一份带 frontmatter 的 SKILL.md。learn-codebase 就是其中之一，其完整定义只有三部分：

---
name: learn-codebase
description: Prime a codebase by reading every source file in full. Use when starting work on a new or unfamiliar project, or when the user asks to "learn the codebase", "read the codebase", "prime", or "get up to speed".
---

对照目录 plugin/skills，可以看到 how-it-works、mem-search、knowledge-agent、smart-explore、make-plan、do 等一批技能与它并列，全部遵循同一套"frontmatter 定义触发语义 + 正文给出执行规程"的格式。也就是说，learn-codebase 不是一个独立的 CLI 工具或后台进程，而是一段会被模型加载的指令契约：

• name 是该技能的标识；在 claude-mem 的会话语境里它通常以 /learn-codebase 的形式被唤起（这一点在 src/npx-cli/commands/install.ts#L2392 与 src/services/worker/http/routes/SearchRoutes.ts#L53 的提示文案中均可印证）。
• description 定义了技能的适用条件与触发短语：当你开始在一个新的或不熟悉的项目上工作，或者用户明确说了 "learn the codebase"、"read the codebase"、"prime"、"get up to speed" 这类请求时，模型应当启用本技能。

正文部分则直接下达了执行纪律——系统地、彻底地、逐文件全文通读所有源文件，无论文件有多少，并且强调这是"关键的、不可妥协的"（critical and non negotiable）。技能给出的目的表述非常直白：只有这样才能"建立起我们可以据以工作的对代码库的深度理解"（build a deep understanding of the codebase we can work off of）。

它解决什么问题：被动积累与主动预热

learn-codebase 的设计意图，只有放在 claude-mem 的记忆机制里才看得完整。根据同目录的 plugin/skills/how-it-works/SKILL.md，claude-mem 的工作方式是：Claude 每次执行 Read、Edit、Bash 都会沉淀为一条压缩后的 observation，会话结束时再做总结；在后续会话中，与当前工作相关的旧记忆会被自动注入到 prompt 里——"下一个会话从上一次会话结束的地方直接开始，无需重新解释代码库，无需重新发现决策"。

关键的时间线约束是：记忆注入从你在某个项目中的第二个会话才开始。也就是说，对一个全新项目，第一个会话扮演的是"播种（seed）"角色，工作内容被记录、被压缩，但要到下一次会话才会被自动回灌。claude-mem 官方面向用户的说明 plugin/skills/how-it-works/onboarding-explainer.md 与安装完成后的提示语（见 src/npx-cli/commands/install.ts#L2383-L2392）都把这个模型讲得很清楚：

Memory builds passively from your first prompt — observations stream in as Claude reads, edits, and runs commands.

Memory injection starts on your second session in a project.

在这样的架构下，一个陌生仓库的第一天会遇到一个现实矛盾：记忆系统本身是按需、被动、渐进式积累的，它擅长"记住发生过的事"，却无法替你"认识一个尚未发生任何事的新仓库"。learn-codebase 就是针对这个空窗期的主动手段。服务端在项目尚无任何记忆时显示的 welcome hint 明确写到了这一点（src/services/worker/http/routes/SearchRoutes.ts#L47-L60）：

This project has no memory yet. The current session will seed it; subsequent sessions will receive auto-injected context for relevant past work.

/learn-codebase is available if the user wants to front-load the entire repo into memory in a single pass (~5 minutes on a typical repo, optional). Otherwise memory builds passively as work happens.

注意其中两个关键措辞：front-load the entire repo into memory（把整个仓库一次性前载进记忆）和 in a single pass（单趟完成）。这正是 learn-codebase 与"边做边记"模式的本质区别——前者用一轮主动的全量阅读，把"代码库长什么样"这个知识整体注入会话，而不是等未来的报错和搜索来一点一点触发认知。

执行规程拆解：全量、逐文件、分页通读

learn-codebase 的正文只有三条核心指令，但每一条都对应一个容易在执行中被妥协的细节。逐条拆解如下。

1. 读 "EVERY SOURCE FILE IN FULL"——全量而非抽样

技能要求通读每一个源文件，且读全文，不能只读目录结构、README、导出符号或 grep 命中片段。这句话限制了两个层面：

• 不能按文件大小、扩展名或"看起来重不重要"来挑食；
• 不能依赖摘要型工具（如只读函数签名、只看顶层定义）来代替正文理解。

理由在技能正文里写得很清楚：全量阅读是为了建立起"可以据以工作"的深度理解。一个能独立完成后续编码任务（而非只会复述）的 Agent，需要的是对模块边界的实感、对命名惯例的体感、对隐含约束（比如某函数只能在特定生命周期里被调用）的把握——这些信息通常只存在于文件的正文细节里，抽样的读法无法覆盖。这也是为什么该技能与仓库中"搜索式"技能（如 plugin/skills/mem-search/SKILL.md 面向过去会话的检索）定位不同：检索解决"找不到"，learn-codebase 解决"从没见过"。

2. 大文件用 offset / limit 分页——完整覆盖长文件的标准姿势

代码库中必然存在数千行的长文件，单次读取通常有行数上限。技能明确给出了 Read 工具的标准分页用法：

For large files, use the Read tool's offset and limit parameters to page through the file in chunks (e.g. offset: 1, limit: 500, then offset: 501, limit: 500).

把它展开成可复制的执行序列就是：

Read  file: src/worker/core/processor.ts   offset: 1,   limit: 500   # 读 1–500 行
Read  file: src/worker/core/processor.ts   offset: 501, limit: 500   # 读 501–1000 行
Read  file: src/worker/core/processor.ts   offset: 1001, limit: 500  # 继续，直到文件末尾

这里的要点是：offset 必须接上一段的末尾继续递增，limit 保持固定块大小，直到某次读取返回的剩余行数少于一个块（或明确提示已读完）为止，才能确认该文件被完整覆盖。这一规程与仓库本体的实际做法完全一致——本仓库源文件动辄上千行（例如 src/npx-cli/commands/install.ts 超过 2500 行、CHANGELOG.md 超过 7600 行），若不靠 offset/limit 分页通读，很容易在"读了开头几百行"后误以为自己"读过这个文件"。

3. 全局覆盖的自我检查——"不管有多少文件"的清单意识

"no matter how many there are"是对执行完整度的最后一道约束：通读应当覆盖仓库中所有相关源码目录，结束时自我核对该次会话发现的全部源文件清单，确认没有因文件多、路径深或目录不起眼而被遗漏。

成本哲学：为什么"Reviewers"不该劝用户省这笔 token

learn-codebase 正文末尾有一节专门的 ## Note for Reviewers，值得单独拿出来理解，因为它代表了 claude-mem 团队对这套预热方法的一个明确判断：

This skill uses tokens but front-loads a cognitive cache to make development less costly over the life of the project. Please keep this in mind before deciding to warn the user over cost.

翻译成工程语言：全量通读确实会消耗大量 token（对大型仓库尤其明显），但它的本质是用一次性高成本换取项目生命周期内的低边际成本——通过"前载认知缓存（front-load a cognitive cache）"让后续每次会话都免于重新理解代码库的重复开销。

这笔账在 claude-mem 的记忆模型里是双重的：

• 会话内：一次完整预热后，Agent 对架构、命名、工具链的认知在当次会话的上下文缓存中持续有效，之后的每轮对话都从这份理解出发，而不是反复重新读文件、反复猜测；
• 跨会话：预热会话产生的大量 observation 被压缩沉淀，成为第二个会话起自动注入的上下文来源（参见 plugin/skills/how-it-works/SKILL.md 的"second session"机制），等于把一次性投入的 token 转化成了可持续复用的长期资产。

因此技能明确请求审查者（Reviewers）在提醒用户"太贵了"之前，先想清楚它是在为整个项目的后续开发周期做一次性预付。这也是理解该技能经济性的正确角度：它优化的是项目总成本，而不是单次会话的即时账单。

在真实链路中的位置：安装提示、欢迎提示与入门文档的交叉印证

learn-codebase 并非孤立的技能文件，它在 claude-mem 的用户触达链路中反复出现，构成一个完整的引导闭环：

• 安装完成后：src/npx-cli/commands/install.ts#L2392 把 /learn-codebase 作为"可选下一步"展示给用户："/learn-codebase ingests a whole repo up front (~5 min)"，并与 /how-it-works 并排给出，帮助新用户第一时间知道存在主动预热这条路径；
• 项目尚无记忆时：src/services/worker/http/routes/SearchRoutes.ts#L47-L60 的 welcome hint 模板在告知"本会话将播种记忆、注入自第二会话开始"的同时，提示 /learn-codebase 可在单趟内前载整个仓库（典型仓库约 5 分钟），并说明"否则记忆会随工作被动积累"——并且该提示在第一条 observation 落地后即消失，避免长期打扰；
• 入门材料中：plans/hackathon/02-claude-mem-cheatsheet.md#L127 将 learn-codebase 归入插件技能清单（与 mem-search、timeline-report、knowledge-agent、how-it-works、make-plan/do 并列），plans/hackathon/03-claude-mem-tutorial.md#L119 则补充说明这些技能是"CLI 形态、文本进文本出"的小型助手，因此易于被包装进各种界面与自动化流程；同篇教程第 130 行还再次把它作为时间线的提速手段推荐——"timeline 从项目的第二个会话才开始，（也可以运行 /learn-codebase 单趟前载一个仓库）"。

仓库层面的佐证：技能分发、版本记录与占位测试

如果你希望确认 learn-codebase 在项目里是"真实存在、被持续维护"的一等公民，而不只是一个示例文件，仓库提供了三处证据：

1. 目录结构与分发事实：技能正文确实位于插件分发包内 plugin/skills/learn-codebase/SKILL.md，与 plugin/skills/mem-search/SKILL.md、plugin/skills/how-it-works/SKILL.md 等同级共处 plugin/skills/ 之下，说明它随插件整体分发而非临时生成的产物；
2. 版本记录：CHANGELOG.md#L1079-L1081 中，v13.2.0 的技能清单明确把插件带到 12 个技能并逐一列出，learn-codebase 在其中；后续版本（如 CHANGELOG.md#L1050-L1054 记录的 design-is、weekly-digests、oh-my-issues 等新技能）仍在持续扩充这个目录；
3. 占位与内容被测试守护：tests/utils/skill-docs-placement.test.ts#L7-L47 以测试的形式锁定了 plugin/skills/*/SKILL.md 的位置与内容约定——例如要求 smart-explore/SKILL.md 包含语言支持说明、要求 mem-search/SKILL.md 不得混入 tree-sitter 语法文档。这说明技能文档的落位与内容边界是项目有意维护的规范（对应 issue #1651），learn-codebase 同样受这套目录纪律约束。

实战清单：什么时候跑、跑完得到什么

综合技能定义、运行提示与配套文档，可以把 learn-codebase 的正确用法收敛成一张可执行的清单：

适合触发的时机

• 开始在一个新的或不熟悉的项目上工作；
• 用户明确要求 "learn the codebase"、"read the codebase"、"prime"、"get up to speed"；
• 项目有大量未定型的架构决策、跨模块耦合或历史包袱，指望"走一步看一步"会很浪费会话轮次；
• 想让 claude-mem 的跨会话记忆在一个空内存项目上快速建立基线，而不是等待被动积累。注意触发词区分：面向"过去会话发生了什么"的检索，应使用 plugin/skills/mem-search/SKILL.md 或 /knowledge-agent，learn-codebase 面向的是"当前仓库本身长什么样"。

执行时不可妥协的三件事

1. 覆盖全部源文件（no matter how many there are），不按文件大小或扩展名抽样；
2. 每个文件读全文（in full），不以目录清单、符号列表或片段命中代替；
3. 对超过单次读取上限的文件，按 offset: 1, limit: 500 → offset: 501, limit: 500 … 的节奏连续分页，直到该文件被完整读完（详见 plugin/skills/learn-codebase/SKILL.md#L13-L15）。

预期产出与成本预期

• 在一次约 5 分钟量级（典型仓库，见 src/services/worker/http/routes/SearchRoutes.ts#L53）的全量通读后，Agent 获得对仓库整体结构的深度认知；该会话产生的全部阅读行为会经由 hook 链路沉淀为 observation（hook 在每次 Read/Edit 后触发的事实可参见 src/services/worker/http/routes/SearchRoutes.ts#L40-L44 的注释），并作为第二会话起自动注入的记忆基础；
• 成本是一次性的高 token 消耗，换来的是项目生命周期内更低的重复理解成本——这正是 plugin/skills/learn-codebase/SKILL.md#L17-L21 里 Note for Reviewers 想要传达的核心权衡。

一句话总结：learn-codebase 是 claude-mem"主动记忆"策略的起点——它用一次认真的、逐文件的全量通读，为 Agent 建立可长期依赖的代码库认知，并把这份认知经由 claude-mem 的 observation 与注入机制，变成未来每一个会话都能免费复用的上下文资产。