用 claude-mem Pathfinder 技能做重构前的代码库架构审计：从重复代码挖掘到统一架构提案

导读

pathfinder 是 claude-mem 插件技能体系中的架构审计型 Orchestrator 技能：它不写任何实现代码，而是把整个代码库映射成一组"按功能分组的 Mermaid 流程图"，跨功能对比找出被重复实现的关注点，产出一份"最简单可行"的统一架构提案，最后把每个待统一系统的实现工作以可复制的 /make-plan 提示词形式移交出去。本文将以 pathfinder 的完整工作流为主线，讲解其四阶段流程、标准产物结构、子代理汇报契约与内置反模式护栏，并结合 claude-mem 仓库自身的技能编排设计（/make-plan、/do）说明该技能如何在大型重构前定位"理想的路径"，让你读完即可在本仓库或其他代码库上复现这套审计方法。

1. 技能定位：这是"审计者"，不是"实现者"

Pathfinder 的技能元信息（frontmatter）写得很明确：当用户提出"找到理想路径 / 统一重复系统 / 重构前审计架构"时触发它，产物是"一份提案 + 每个待统一系统的 /make-plan 提示词"，绝不写实现代码。它把自身定位为 ORCHESTRATOR（编排者），承担三个固定职责：

1. 把代码库映射为按功能分组的流程图（feature-grouped flowcharts）；
2. 识别跨功能出现的重复关注点（duplicated concerns）；
3. 提出最简单的统一架构，并把每个系统的落地计划移交给 /make-plan。

这条边界与 claude-mem 的技能工程哲学一脉相承：据 CHANGELOG.md 记载，仓库在 10.4.1 版本把 /make-plan 与 /do 命令转换为 plugin/skills/ 下的一等技能，形成"make-plan（计划）→ do（执行）"的编排链。Pathfinder 恰好填补链条的最前端——它不直接调 /do，而是停在"计划提示词"这一步，让 make-plan 和 do 按自身节奏接手。正如 SKILL.md 中的 Key Principles 所强调：Handoff, don't implement（移交而非实现）。

从仓库结构看，plugin/skills/ 下已汇集 babysit、make-plan、do、mem-search、learn-codebase、pathfinder 等十余个技能（CHANGELOG 13.2.0 的 skills inventory 中明确列出 12 个技能），pathfinder 在其中属于少数"面向大型重构"的元技能，其余技能多聚焦单次会话内记忆检索或单任务执行。

2. 编排模型：发现与综合的职责分离

Pathfinder 强制一种严格的职责分工：

• 发现与提取（discovery & extraction）交给子代理：文件读取、流程追踪、grep、绘图等海量阅读工作全部下放；
• 综合（synthesis）留给主编排者：判断功能边界、选择统一策略、绘制最终统一流程图这些需要全局判断的决策，不允许委托；
• 拒绝无出处的子代理报告：如果子代理的产出缺少源码引用，主编排者必须拒绝并重新部署。

子代理汇报契约（强制项）

每份子代理响应必须包含四要素，缺一即视为不合格并重派：

1. 查阅的源（Sources consulted）——精确到文件路径与行区间；
2. 具体发现（Concrete findings）——确切的函数名、调用点、数据流；
3. 带 file:line 节点标注的 Mermaid 图——流程图节点必须能回溯到源码位置；
4. 置信度说明 + 已知缺口——诚实标注不确定区域。

这套契约与 /make-plan 的 Subagent Reporting Contract 高度同构：make-plan 同样要求子代理报告"查阅的源、具体的 API 名称/签名、可复制的片段位置、置信度与缺口"，其设计意图一致——用证据约束多 Agent 协作中常见的幻觉与断言式结论。可以推断：pathfinder 之所以把"证据"提到契约高度，是因为流程图与重复报告一旦脱离 file:line 锚点，就成了无法核验的"记忆里的架构图"，这正是它 Failure Modes 中首先要防的问题。

3. 输出产物：一份自带清单的审计目录

所有产物必须写入仓库根目录下的 PATHFINDER-<YYYY-MM-DD>/ 目录，形成一份可评审、可追溯的审计档案：

文件	内容	生产者
00-features.md	功能清单及其边界	Orchestrator（子代理提案，orchestrator 审定）
01-flowcharts/<feature>.md	每个功能一张 Mermaid 流程图	Flowchart 子代理（orchestrator 落盘）
02-duplication-report.md	跨功能重复关注点 + 证据	Orchestrator 综合两个子代理报告
03-unified-proposal.md	统一架构提案 + 一张合并 Mermaid 图	仅 Orchestrator 亲自撰写
04-handoff-prompts.md	每个待统一系统的可复制 /make-plan 提示词	Orchestrator

产物按阶段编号 00→04 本身就是工作流的时序映射：先描述现状（00/01/02），再设计目标态（03），最后输出执行交接物（04）。

4. 四阶段流程详解

Phase 0：功能发现（永远最先做）

部署一个 "Feature Discovery" 子代理，任务是：

1. 遍历源码树（排除构建产物），阅读顶层 README / CLAUDE.md；
2. 依据目录结构、import 图和命名习惯提出功能边界划分建议；
3. 返回扁平的功能清单，每项含：名称、入口点（file:line）、核心文件、简要用途。

关键纪律：Orchestrator 必须先评审并批准边界，写入 00-features.md，然后才能进入扇出（fan out）阶段。SKILL.md 明确警告：Do NOT fan out until feature boundaries are approved——跳过边界评审直接扇出，边界一错，Phase 1 的所有流程图全部作废。

这一点与仓库自身的领域复杂度直接相关：claude-mem 的 src/ 下有 services/worker（59 个文件）、services/context、services/transcripts、services/sync、worker 相关代码等多个纵深子系统，一个"按目录粗略分块"的错误边界会立刻导致 Phase 1 子代理拿到互相重叠的阅读范围，重复劳动与遗漏并存。

Phase 1：逐功能流程图（扇出阶段）

每个功能部署一个 "Flowchart" 子代理，并行执行。每个子代理只拿到自己功能的边界范围，必须完成：

1. 追踪该功能从入口到终态的主成功路径（happy path）；
2. 识别副作用（side effect）：数据库写入、HTTP 调用、文件 I/O、进程派生；
3. 记录错误与回退分支，但不允许其占据图面主体；
4. 产出 Mermaid flowchart TD 图，每个节点标注 Name<br/>file:line；
5. 在底部列出外部依赖（该功能调用的其他功能）。

Orchestrator 负责把图写入 01-flowcharts/<feature>.md。凡缺失 file:line 节点标注的图，一律打回。Mermaid flowchart TD 的节点格式类似：

flowchart TD
    A[Capture Hook<br/>src/services/transcripts/watcher.ts:120]
    B[Write Observation<br/>src/services/sqlite/observations.ts:45]
    A --> B

（以上为 skill 所要求的节点标注风格示意，实际节点以你仓库内真实调用的 file:line 为准。）

Phase 2：重复性挖掘（双路并行）

并行部署两个子代理，分别从"内部"与"跨功能"两个维度挖掘：

"功能内重复（Within-Feature Duplication）"子代理：在每个功能内部寻找重复的代码/逻辑模式，只报告值得合并的重复，忽略琐碎复制。

"跨功能重复（Cross-Feature Duplication）"子代理：横向比对各功能的流程图，寻找出现在多个位置的关注点。SKILL.md 给出了极具启发性的例子清单（这些与 claude-mem 这类多 Agent 记忆系统高度相关）：

• 多条 capture 路径（multiple capture paths）；
• 并行的 queue 实现（parallel queue implementations）；
• 重复的存储/迁移代码（duplicated storage/migration code）；
• 重复的 agent 脚手架（repeated agent scaffolding）；
• 并行的解析层（parallel parsing layers）。

对每处重复，报告四件事：(a) 关注点是什么；(b) 每个出现位置（file:line）；(c) 它们为什么发生了分化（divergence 的成因）；(d) 这种分化是合理的特化（legitimate specialization）还是偶然漂移（accidental）。

Orchestrator 综合两份报告写入 02-duplication-report.md。铁律：每条重复主张必须引用 ≥2 处 file:line 位置。

Phase 3：统一提案（仅 Orchestrator）

这是全流程中**唯一明确"不得委托综合"**的阶段。针对 Phase 2 中所有"非合理特化"的重复，逐一回答：

1. 提出最简单的统一设计——"一个路径、一个存储、一个处理器"（one path, one store, one handler——看适用情况取舍）；
2. 命名被合并后的组件及其单一入口点；
3. 说明每个旧调用点会变成什么；
4. 明确列出会损失的能力，并判断这种损失是否可以接受。

文档末尾必须以一张合并的 Mermaid 流程图收尾，展示统一后的目标系统；凡能确定（新或既有）的节点仍须标注目标 file:line。

提案内部必须拒绝的反模式

SKILL.md 列举了四条，这是整个 skill 中最锋利的部分：

• 为了"灵活性"添加新的抽象层（Adding a new abstraction layer "for flexibility"）——对应 Key Principles 中的 prefer deletion over abstraction（删除优于抽象）；
• 用 feature flag 同时保留新旧两条路径（Keeping both old paths behind a feature flag）；
• 在 switch 语句就够用时引入 registry/factory（Introducing a registry/factory when a switch statement suffices）；
• "以防万一"保留分化行为（Preserving divergent behavior "just in case"）。

Phase 4：逐系统交接提示词

为提案中每个待统一系统写一段可直接运行的 /make-plan 提示词，写入 04-handoff-prompts.md。每段提示词必须：

1. 指明目标统一组件及其单一入口点；
2. 列出需要重写的确切调用点（来自 Phase 2 证据）；
3. 引用 01-flowcharts/ 中的相关流程图文件；
4. 附上针对该系统的反模式护栏。

格式上要求每段一个 fenced code block，方便用户直接从审计目录复制进 /make-plan。这一点衔接了 make-plan 的输入契约——它要求任务被框架为"从文档/示例复制而非迁移现有代码"，因此 pathfinder 提供精确调用点 + 流程图引用 + 反模式护栏，恰好让 /make-plan 的开局就有据可依，而不是从模糊目标重新考古。

5. 关键原则：把"证据"当作唯一通行证

Pathfinder 的五条 Key Principles 直接构成它的价值观体系：

原则	含义
Evidence over intuition	每个图节点与每条重复主张都引用 file:line，杜绝"凭印象画架构"
Current state before ideal state	Phase 0–2 描述"现状是什么"（IS）；Phase 3 才描述"应该是什么"（SHOULD BE）——现状审计与目标设计严格分阶段
Simplest unification wins	删除 > 抽象；一条路径 > 可配置的多路径
Specialization is not duplication	服务于不同信任模型（trust model）或不同数据源（data source）的两个组件，即使代码长得像，也是合法特化而非重复
Handoff, don't implement	Pathfinder 止步于计划提示词；/make-plan 与 /do 负责后续

其中"Specialization is not duplication"与"Simplest unification wins"互为张力：前者防止过度合并，后者防止过度设计，两者的裁决标准都落到信任模型与数据源是否真的不同，而非代码表面相似度。这解释了为什么仓库大量并行的 worker/sync/transcript 代码不能靠视觉相似度一刀切——是否合并取决于它们在信任边界与数据流上是否真正重合。

6. 失败模式清单：把这个 skill 当作"带护栏的流程"

SKILL.md 在结尾给出四个必须主动预防的失败模式，它们同时也是评审人检查 pathfinder 输出的四个审查点：

1. 凭记忆而非源码画流程图——处置：以"必须带 grep 证据"重新部署子代理；
2. 提议统一本属合理特化的组件——处置：重新审视信任/数据源层面的分歧；
3. 交接提示词缺少具体调用点——处置：用 Phase 2 证据重写；
4. 跳过 Phase 0 边界评审——处置：边界没批准就扇出，会浪费整个 Phase 1。

这四条失败模式与本仓库的工程实践是呼应的：claude-mem 的测试目录（如 tests/worker/、tests/services/sync/）中大量针对 worker 生命周期、同步矩阵的用例，说明该项目本身长期在管理多进程、多同步路径的复杂度；一份 pathfinder 审计若产出了不锚定 file:line 的流程图或把合法特化误判为重复，其危害会直接传导到后续 /make-plan 与 /do 的实现阶段。

7. 把它跑起来：在本仓库上复现一次审计

如果你希望在本仓库（或任何基于 claude-mem 技能体系的代码库）实际运行该技能，可以直接向 Agent 提出此类需求："在重构前对代码库做架构审计，找出重复实现的系统并给出统一方案"——它会自动触发 pathfinder 并依下述轨迹工作：

1. Phase 0：通读仓库根目录 README.md、CLAUDE.md 与 src/ 树，产出功能边界清单 00-features.md；
2. Phase 1：为 services/worker、services/sync、services/context、services/transcripts 等功能分别并行产出带 file:line 标注的 Mermaid 流程图；
3. Phase 2：两份报告（功能内 / 跨功能）并行挖掘，汇总成带 ≥2 处 file:line 证据的重复报告；
4. Phase 3：orchestrator 亲自撰写统一架构提案与合并流程图，并用"单一入口 + 删除优于抽象"约束自身；
5. Phase 4：把每段可复制的 /make-plan 提示词写入 04-handoff-prompts.md，由用户取出后粘贴进 plugin/skills/make-plan/SKILL.md 描述的 make-plan 技能生成分阶段实现计划，最终交给 plugin/skills/do/SKILL.md 的 do 技能去执行。

整个过程产出的 PATHFINDER-<YYYY-MM-DD>/ 目录即是完整审计档案，也是 make-plan/do 的输入依据——这正是 claude-mem 技能链在"发现 → 规划 → 执行"上的完整闭环设计。