Back to Details

refactorlib-cc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

refactorlib

refactorlib

Audit a codebase for handcrafted code that could be replaced by existing dependencies.
Projects accumulate utility code over time. Some predates a dependency that now covers the same ground; some was written before the team discovered a library API. Removing these duplications shrinks maintenance surface and leverages battle-tested implementations with better edge-case handling and security patches.
审计代码库中可被现有依赖替换的手写代码。
项目会随着时间推移积累大量工具代码。部分代码的诞生时间早于现在已覆盖相同功能的依赖；还有部分是在团队发现对应库API之前编写的。移除这些重复代码可以缩小维护范围，同时使用经过实战检验的实现，这些实现具备更完善的边缘场景处理能力和安全补丁支持。

Project context

项目上下文

  • deps: !
    bun -e "const p=JSON.parse(await Bun.file('package.json').text()); console.log(JSON.stringify({...p.dependencies,...p.devDependencies}))" 2>/dev/null
  • runtime: !
    bun --version 2>/dev/null || node --version 2>/dev/null
  • has_effect: !
    bun -e "const p=JSON.parse(await Bun.file('package.json').text()); console.log(p.dependencies?.effect || p.devDependencies?.effect ? 'yes' : 'no')" 2>/dev/null
  • has_bun: !
    bun -e "const p=JSON.parse(await Bun.file('package.json').text()); console.log(p.devDependencies?.['@types/bun'] ? 'yes' : 'no')" 2>/dev/null
  • src_dirs: !
    ls src/ 2>/dev/null | head -20
  • deps: !
    bun -e "const p=JSON.parse(await Bun.file('package.json').text()); console.log(JSON.stringify({...p.dependencies,...p.devDependencies}))" 2>/dev/null
  • runtime: !
    bun --version 2>/dev/null || node --version 2>/dev/null
  • has_effect: !
    bun -e "const p=JSON.parse(await Bun.file('package.json').text()); console.log(p.dependencies?.effect || p.devDependencies?.effect ? 'yes' : 'no')" 2>/dev/null
  • has_bun: !
    bun -e "const p=JSON.parse(await Bun.file('package.json').text()); console.log(p.devDependencies?.['@types/bun'] ? 'yes' : 'no')" 2>/dev/null
  • src_dirs: !
    ls src/ 2>/dev/null | head -20

Workflow

工作流程

Phase 1 -- Route on context

第一阶段 -- 基于上下文路由

The project context above was resolved at skill load time. Use it to decide which pattern catalogs each agent should read:
  • If has_effect == "yes": include 
    references/patterns/effect-infra.md
    in the infra agent's pattern list
  • Always: include 
    references/patterns/runtime-infra.md
    for infra agent, 
    references/patterns/general-utility.md
    and 
    references/patterns/runtime-utility.md
    for utility agent
The subagents have 
effect-usage
and 
bun
skills preloaded — no need to load companion skills in the orchestrator.
上述项目上下文会在技能加载时解析完成。用它来决定每个Agent应该读取哪些模式目录：
  • 如果 has_effect == "yes"：在基础设施Agent的模式列表中加入
    references/patterns/effect-infra.md
  • 默认规则：基础设施Agent始终包含
    references/patterns/runtime-infra.md
    ，工具Agent始终包含
    references/patterns/general-utility.md
    和
    references/patterns/runtime-utility.md
子Agent已经预先加载了
effect-usage
和
bun
技能——无需在编排器中加载配套技能。

Phase 2 -- Parallel exploration

第二阶段 -- 并行探索

Spawn two custom subagents in parallel. Each receives a short task prompt with:
  • Project dependencies (from 
    deps
    above)
  • Source directories (from 
    src_dirs
    above)
  • Pattern catalog file paths to read (from Phase 1 routing)
  • Guardrails: 
    ~/.claude/skills/refactorlib-cc/references/guardrails.md
  • Report format: 
    ~/.claude/skills/refactorlib-cc/references/report-format.md
  • The user's request (or "Full audit -- no scope restriction")
Agent({ subagent_type: "refactorlib-infra", prompt: <task prompt> })
Agent({ subagent_type: "refactorlib-utility", prompt: <task prompt> })
The agents' system prompts (from their markdown definitions) provide the methodology. Their preloaded skills (effect-usage, bun) provide deep API knowledge with progressive disclosure.
并行启动两个自定义子Agent。每个子Agent都会收到包含以下内容的简短任务提示：
  • 项目依赖（来自上述
    deps
    字段）
  • 源码目录（来自上述
    src_dirs
    字段）
  • 要读取的模式目录文件路径（来自第一阶段的路由结果）
  • 防护规则：
    ~/.claude/skills/refactorlib-cc/references/guardrails.md
  • 报告格式：
    ~/.claude/skills/refactorlib-cc/references/report-format.md
  • 用户请求（或“完整审计——无范围限制”）
Agent({ subagent_type: "refactorlib-infra", prompt: <task prompt> })
Agent({ subagent_type: "refactorlib-utility", prompt: <task prompt> })
Agent的系统提示（来自其markdown定义）提供了执行方法论。它们预加载的技能（effect-usage、bun）提供了深度的API知识，并会按需逐步披露。

Phase 3 -- Triage and deep-dive

第三阶段 -- 分类与深度调研

Synthesize agent findings. For each candidate, classify:
VerdictMeaning
REPLACEClear duplication. Library equivalent exists, is proven compatible, and is installed.
INVESTIGATELikely replaceable but needs API verification or output comparison.
KEEPIntentionally custom. See 
references/guardrails.md
.
For REPLACE and INVESTIGATE candidates, perform these verification steps:
  1. Read the source -- understand the full implementation, not just the grep match
  2. Count callers -- 
    grep -r
    for imports to gauge blast radius
  3. Verify the API exists -- grep type declarations in 
    node_modules/*/dist/dts/
    for the replacement API. An API that looks right in docs might not exist in the installed version.
  4. Test output compatibility (for INVESTIGATE) -- run both implementations with identical input via 
    bun -e
    and compare output. This catches subtle differences in encoding, formatting, or edge-case behavior.
Only promote INVESTIGATE to REPLACE after step 4 confirms identical behavior.
整合Agent的发现结果。对每个候选替换项进行分类：
判定结果含义
REPLACE明确的重复代码。存在对应的等价库实现，已验证兼容，且已经在项目中安装。
INVESTIGATE大概率可以替换，但需要进行API验证或输出对比。
KEEP有意编写的自定义代码。参考
references/guardrails.md
说明。
对于REPLACE和INVESTIGATE类的候选项，执行以下验证步骤：
  1. 阅读源码 -- 理解完整实现，而不仅仅是grep匹配到的部分
  2. 统计调用方数量 -- 用
    grep -r
    搜索导入语句来评估影响范围
  3. 验证API真实存在 -- 在
    node_modules/*/dist/dts/
    目录下grep替换API的类型声明。文档里看起来合适的API可能在当前安装的版本中并不存在。
  4. 测试输出兼容性（针对INVESTIGATE类） -- 通过
    bun -e
    用完全相同的输入运行两份实现并对比输出。这可以发现编码、格式或边缘场景行为上的细微差异。
只有在步骤4确认行为完全一致后，才能将INVESTIGATE升级为REPLACE。

Phase 4 -- Structured output

第四阶段 -- 结构化输出

Produce the final report using this template:
undefined
使用以下模板生成最终报告：
undefined

Library Replacement Audit

Library Replacement Audit

Dependencies scanned

Dependencies scanned

  • <dep>: <what it provides>
  • <dep>: <what it provides>

Candidates

Candidates

[REPLACE] <title>

[REPLACE] <title>

  • files: <paths with line ranges>
  • callers: <N files import this>
  • current: <what the code does, 1 line>
  • replacement: <library API, 1 line>
  • effort: low | medium | high
  • gain: <lines removed, better edge-case handling, etc.>
  • verified: yes | no
  • code_before: | <snippet>
  • code_after: | <snippet>
  • files: <paths with line ranges>
  • callers: <N files import this>
  • current: <what the code does, 1 line>
  • replacement: <library API, 1 line>
  • effort: low | medium | high
  • gain: <lines removed, better edge-case handling, etc.>
  • verified: yes | no
  • code_before: | <snippet>
  • code_after: | <snippet>

[INVESTIGATE] <title>

[INVESTIGATE] <title>

  • files: <paths>
  • current: <what the code does>
  • candidate: <library API>
  • blocker: <what needs verification>
  • files: <paths>
  • current: <what the code does>
  • candidate: <library API>
  • blocker: <what needs verification>

[KEEP] <title>

[KEEP] <title>

  • files: <paths>
  • reason: <why this is intentionally custom>
  • files: <paths>
  • reason: <why this is intentionally custom>

Summary

Summary

CandidateVerdictEffortGainVerified
undefined
CandidateVerdictEffortGainVerified
undefined

False-positive guardrails

误报防护规则

See 
references/guardrails.md
. Agents are directed to read this file during exploration.
参见
references/guardrails.md
。Agent在探索过程中会被要求读取该文件。

Reference navigation

参考文档索引

QuestionLoad
Effect infrastructure patterns?
references/patterns/effect-infra.md
Bun/Node infrastructure APIs?
references/patterns/runtime-infra.md
Bun/Node utility APIs?
references/patterns/runtime-utility.md
General utility patterns?
references/patterns/general-utility.md
False-positive guardrails?
references/guardrails.md
Infra subagent?
dot_claude/agents/refactorlib-infra.md
Utility subagent?
dot_claude/agents/refactorlib-utility.md
Agent report format?
references/report-format.md
问题加载路径
Effect基础设施模式？
references/patterns/effect-infra.md
Bun/Node基础设施API？
references/patterns/runtime-infra.md
Bun/Node工具API？
references/patterns/runtime-utility.md
通用工具模式？
references/patterns/general-utility.md
误报防护规则？
references/guardrails.md
基础设施子Agent？
dot_claude/agents/refactorlib-infra.md
工具子Agent？
dot_claude/agents/refactorlib-utility.md
Agent报告格式？
references/report-format.md