AI编码代理自动化研究：基于实验循环的代码优化实践

1. 项目概述：让AI编码代理成为你的专属研究员

如果你和我一样，每天都在和代码、配置、构建脚本打交道，那你一定遇到过这种场景：某个构建流程耗时太长，你手动调整了几个参数，效果不明显，又懒得花一整天去系统性地做A/B测试；或者一个API的响应时间总是不稳定，你凭经验改了改，但不确定是不是最优解。我们总在“差不多就行”和“没时间深究”之间徘徊。最近，我在GitHub上发现了一个名为ResearcherSkill的项目，它彻底改变了我的工作方式。简单来说，它就是一个researcher.md文件，你把它丢给Claude Code、Cursor的Codex模式，或者任何能理解长文本的AI编码代理，这个代理就会摇身一变，成为一个不知疲倦的、系统性的“研究员”。

这个“研究员”的核心工作不是写新功能，而是优化。它遵循一个严谨的科学研究循环：提出假设、设计实验、执行测试、分析结果、保留有效方案、丢弃失败尝试。想象一下，你告诉它“把npm run build的时间降下来”，然后你去睡觉。第二天早上，你会发现它已经在GitHub上创建了十几个实验分支（比如research/build-optimization-b1,research/build-optimization-b4），每个分支都代表一次不同的优化尝试（调整Webpack配置、尝试ESBuild、启用持久缓存等），并且附有详细的实验日志和性能对比数据。它自己会判断哪个方案好，哪个方案差，把好的合并回主分支，把差的直接丢弃。整个过程完全自动化，你只需要定义目标和度量标准。

2. 核心设计思路：将“自动研究”范式通用化

这个项目的灵感来源于Andrej Karpathy的autoresearch项目，那是一个专注于自动化机器学习超参数搜索的工具。ResearcherSkill的作者Krzysztof Dudek洞察到了一个更本质的模式：任何可以测量、可以迭代改进的事物，都可以套用“提出假设-实验验证”的研究循环。他的工作就是将这个循环从ML的特定语境中抽象出来，变成一个与领域无关的“元技能”。

2.1 从专用工具到通用技能的跨越

传统的autoresearch与train.py、验证集损失（val_bpb）和GPU集群紧密耦合。如果你想用它来优化你的Web服务响应时间，你需要重写大量的基础设施代码。ResearcherSkill解决了这个“最后一公里”问题。它提供的是一个协议和一套操作框架，而非一个固化的工具。这个协议定义了AI代理作为研究员应该如何思考、如何行动：

1. 发现阶段：代理首先“采访”你。它会问：“要优化什么？成功指标是什么？（例如，构建时间、测试通过率、API P99延迟）如何测量这个指标？（例如，运行time npm run build，调用基准测试脚本）”
2. 实验室搭建：代理会在你的代码库中创建一个独立的、不被Git跟踪的.lab/目录。这里是它的“实验室笔记本”，所有实验假设、原始数据、反思日志都存放在这里。代码本身则由Git管理，实验通过特性分支进行。
3. 自主实验循环：代理进入一个循环：基于当前最佳知识和.lab/中的历史记录生成一个假设（如“假设将数据库连接池大小从10增加到20可以降低P99延迟”），在一个新的Git分支上实施这个改变，运行测量命令，记录结果，并与基线进行比较。如果结果更好，则保留（keep）；如果更差或无效，则丢弃（discard）并回滚代码。
4. 策略调整与收敛检测：代理不是蛮干。它会监控实验信号：是否连续失败了5次？是否最近10次实验的指标提升都小于1%？是否反复修改了同一个文件却毫无进展？当检测到这些“停滞”信号时，它会主动改变策略，比如从“调优参数”转向“更换算法”，或者开辟一个全新的探索分支。

2.2 核心组件解析：.lab/目录与实验协议

researcher.md文件本质上是一份给AI代理的“岗位说明书”和“操作规程”。它详细描述了上述循环的每一个步骤，并提供了具体的对话示例、命令模板和决策逻辑。而.lab/目录是这个技能的大脑，其结构设计非常巧妙：

• hypotheses/: 存放每个实验的假设描述文件。
• results/: 存放每次实验运行的原始输出和解析后的指标数据。
• logs/: 存放代理的“思考过程”，即它为什么做出某个决策的推理链。
• state.json: 保存当前研究的状态，如当前最佳分数、活跃的假设方向、收敛检测信号等。

这个设计实现了“代码”和“研究过程”的分离。Git的历史清晰记录了最终被采纳的、生产可用的代码变更。而.lab/则完整保留了探索过程中的所有试错、死胡同和灵感闪现，这些对于理解“为什么最终方案有效”至关重要，但又不需要污染主代码历史。

注意：.lab/目录应被添加到.gitignore中。它的内容可能庞大且包含中间数据，不适合纳入版本控制。研究产出的最终知识，应通过代码变更和可选的RESEARCH_SUMMARY.md来体现。

3. 实操部署：将ResearcherSkill接入你的工作流

理论很美好，但怎么用起来？以下是我在真实项目中部署和运行ResearcherSkill的完整步骤。我将以一个常见的场景为例：优化一个Next.js项目的冷启动构建时间。

3.1 环境准备与技能导入

首先，你需要一个支持“AI编码代理”的环境。目前最兼容的是：

• Cursor：在设置 -> 功能中启用Codex模式。
• Claude Code：在Claude桌面应用或支持Claude 3.5 Sonnet/Opus的IDE插件中。
• 任何能处理长上下文（>100k tokens）并执行代码/命令的AI代理。

步骤一：获取研究员技能文件

1. 访问项目的GitHub仓库：https://github.com/krzysztofdudek/ResearcherSkill。
2. 找到根目录下的researcher.md文件。你可以直接点击“Raw”按钮查看原始内容，然后全选复制。
3. 在你的项目根目录下，创建一个新文件，粘贴内容并保存为researcher.md。你也可以直接克隆仓库或下载单个文件。

步骤二：初始化AI代理会话

1. 打开你的AI代理（如Cursor），并确保它加载了你当前的项目上下文。
2. 将researcher.md文件的全部内容，作为一条消息发送给AI代理。你可以这样说：“请仔细阅读以下文档，并扮演其中定义的研究员角色。我们即将开始一个优化项目构建速度的研究。”
3. 代理在消化内容后，通常会回复确认，并表示已准备好进入“发现阶段”。

3.2 定义研究目标：与你的AI研究员对话

这是最关键的一步。研究的成败很大程度上取决于目标是否清晰、可测量。以下是我与AI研究员的一次真实对话记录：

我：“研究员你好，我希望优化我们Next.js项目的本地开发服务器冷启动时间。目前执行npm run dev后，到浏览器显示‘ready’日志，平均需要约8秒。这影响了开发体验。”

AI研究员：“明白。我将启动一个针对‘降低Next.js dev服务器冷启动时间’的研究。为了量化进展，我们需要一个一致的测量方法。请确认：

1. 测量命令：我们是否使用time npm run dev并捕获‘ready’出现的时刻？或者有更精确的内部计时？
2. 环境一致性：每次测量前，是否需要清除缓存（如.next文件夹）以确保是‘冷启动’？
3. 成功指标：目标是将平均启动时间从8秒降低到多少？比如4秒？
4. 约束条件：有哪些变更是不被允许的？例如，不能降级Next.js版本，不能禁用TypeScript检查。”

我：

1. 测量命令：我们使用rm -rf .next && time (npm run dev > /dev/null 2>&1 & sleep 12 && pkill -f \"next\")这个脚本。它会清理缓存，启动dev服务器，等待12秒（足够启动），然后杀死进程。time命令会输出实际消耗的时间。我们将使用这个时间。
2. 是的，每次实验前必须清除.next缓存。
3. 成功指标：首要目标是将测量时间从~8秒降低到5秒以下。其次，我们也关注优化方案是否会显著增加热重载时间或构建产物大小。
4. 约束：必须保持Next.js版本在^14.x；不能破坏现有的页面路由和API路由功能；不能引入新的重大安全依赖。

AI研究员：“目标清晰。我将创建研究目录.lab/并初始化状态。基线测量将在主分支的当前状态下进行。随后我将生成第一个优化假设。我们开始吧。”

3.3 观察自主研究过程

发出开始指令后，你就可以最小化窗口了。研究员会开始它的工作。通过Git历史和.lab/目录，你可以回溯整个过程：

1. 创建实验分支：你会看到类似research/dev-startup-optimization-b0的分支被创建。b0通常是基线测试分支。
2. 执行与记录：在该分支上，代理会运行我们定义的测量脚本，将结果（例如8.2s）记录到.lab/results/b0.json。
3. 生成假设：代理查看项目结构（next.config.js,package.json,tsconfig.json等），结合已知的Next.js优化知识，在.lab/logs/b1_thinking.md中写下它的思考：“假设一：当前next.config.js中未启用swcMinify。启用SWC压缩器可能比默认的Terser更快。假设二：package.json中dev脚本是next dev，尝试添加--turbo标志以启用Turbopack（实验性）进行对比。”
4. 实施与验证：它会创建分支b1，修改next.config.js，提交，运行测量，记录结果（比如7.1s）。因为比基线好，状态标记为keep。然后创建分支b2尝试--turbo，结果可能失败或性能差异不大，标记为discard。
5. 迭代与策略调整：它可能会继续探索更多假设：调整webpack配置中的cache设置、检查node_modules是否被符号链接、尝试不同的tsc编译策略等。如果连续多个关于Webpack的假设都收效甚微，它的日志会显示：“检测到平台期。策略将从‘Webpack配置调优’转向‘依赖分析与捆绑策略’。” 然后开始研究是否有些大型库可以动态导入。

第二天早上，你可能会在主分支看到一个合并请求（Pull Request），标题是“优化: 启用SWcMinify并配置持久缓存，dev冷启动时间从8.2s降至5.8s”。而.lab/目录里则躺着十几次失败的实验记录，告诉你为什么没选“启用Turbopack”或“升级Babel插件”。

4. 高级应用场景与参数调优

ResearcherSkill的能力远不止优化构建时间。它的本质是“基于度量的自动迭代”。任何能转化为“输入→变更→可测量输出”闭环的场景，都可以应用。

4.1 场景扩展：解决不同领域的问题

1. API性能优化：

   • 目标：降低某个GraphQL接口的P99延迟。
   • 测量：使用像autocannon或wrk的压力测试工具，针对该接口运行脚本，提取P99延迟值。
   • 研究过程：代理可能会尝试：调整数据库查询（添加索引、重写查询语句）、实现DataLoader批处理、调整API路由的缓存头、甚至重构部分解析逻辑。

2. 提示词工程：

   • 目标：让一个总结文本的AI提示词输出格式错误率低于2%。
   • 测量：准备一个包含100个样本的测试集。运行一个脚本，用候选提示词处理每个样本，与标准答案比对，计算格式正确的百分比。
   • 研究过程：代理会系统性地修改提示词的结构、措辞、示例（few-shot）的数量和内容、输出格式描述，寻找最优组合。

3. 文档解析准确率：

   • 目标：提升一个从PDF提取表格信息的解析器的匹配率。
   • 测量：使用一组标注好的PDF文件，运行解析器，计算提取字段的F1分数。
   • 研究过程：代理可能调整正则表达式参数、尝试不同的PDF解析库（如pdf.jsvspdfplumber）、后处理清洗逻辑等。

4.2 收敛检测与策略参数调优

researcher.md中内置的收敛检测逻辑是防止无效计算的关键。你可以根据任务复杂度调整这些参数。这些通常在研究开始时的对话中，由研究员询问或由你主动提出：

• MAX_CONSECUTIVE_FAILURES: 连续失败多少次后强制改变策略？默认可能是5。对于探索性强的任务，可以设为8-10；对于目标明确的任务，可以设为3。
• PLATEAU_THRESHOLD: 指标在多少次实验内提升小于多少百分比视为平台期？例如(last 10 experiments, improvement < 1%)。
• MAX_BRANCH_DEPTH: 一个研究方向（分支）最多探索多少个子假设？防止在一条死胡同里走得太深。
• EXPLORATION_VS_EXPLOITATION: 你可以指示研究员：“前期可以多做一些高风险、高回报的探索性实验；后期接近目标时，专注于对现有最佳方案的微调。”

实操心得：对于你不熟悉的领域，初期可以设置更宽松的收敛条件，让代理进行更广泛的探索。当你对问题空间有了一定了解后，再收紧参数，进行针对性优化。研究员在.lab/state.json中会维护这些信号，并在日志中明确告知何时及为何触发策略转换。

5. 常见问题与故障排查实录

在实际使用中，你可能会遇到一些预期之外的情况。以下是我和社区成员遇到的一些典型问题及解决方法。

5.1 研究员“卡住”或行为异常

问题现象：代理不断重复类似的、明显无效的修改，或者提出的假设完全偏离了方向。

• 检查.lab/state.json：首先查看状态文件。可能收敛检测信号未被正确触发，或者状态已损坏。
• 审查最近实验日志：查看.lab/logs/下最近几个实验的*_thinking.md文件。看看代理的推理链条在哪里出现了逻辑错误。有时是它对代码库的理解有偏差。
• 干预与引导：直接中断当前会话，并给代理新的指令：“查看你在实验b7中的思考日志。你认为‘移除所有React.memo’的假设是基于什么理由？这与我们保持性能的总体目标是否矛盾？请修正你的理解，并基于当前最佳方案（b4）重新规划后续实验。” 研究员能够读取这些日志并调整方向。
• 重置实验室：在极端情况下，可以删除.lab/目录（研究历史会丢失，但Git代码变更已保存），然后重新开始发现阶段。这相当于给研究员一次“重启”。

5.2 测量结果不稳定或不可靠

问题现象：同样的代码，两次测量结果波动很大，导致研究员无法正确判断实验成败。

• 优化测量脚本：确保测量环境尽可能干净。关闭不必要的后台程序，进行多次测量取平均值（如运行3次取中位数）。在脚本中加入资源监控（如/usr/bin/time -v），看看是否有时是CPU或I/O的竞争导致波动。
• 定义更鲁棒的指标：不要只看单一数值。例如，对于API延迟，可以定义指标为“（P50延迟 * 0.3 + P99延迟 * 0.7）”，给予尾部延迟更高权重，这样的指标更稳定且更能反映真实体验。
• 设置显著性阈值：在发现阶段就告诉研究员：“只有当年改善超过5%（或绝对时间减少0.5秒）时，才视为一次成功的实验。” 这可以过滤掉噪声。

5.3 与现有CI/CD流程的集成冲突

问题现象：研究员创建的大量实验分支触发了CI流水线，造成了资源浪费。

• 利用GitHub分支保护规则：为匹配research/*模式的分支创建规则，禁止自动触发CI构建。或者，在CI配置文件中（如.github/workflows/ci.yml）中，添加条件跳过对研究分支的构建：if: contains(github.ref, 'refs/heads/research/') == false。
• 让研究员在本地运行：指示研究员所有测量命令必须在本地执行，避免依赖CI环境。这要求你的本地环境能够复现关键的测试和构建。
• 使用轻量级验证：对于需要CI验证的步骤（如单元测试），可以指示研究员在提交前，先在本地运行一个核心测试子集，快速反馈。

5.4 处理没有明确数值指标的任务

问题现象：你想优化代码可读性、API设计或文档结构，但这些没有直接的“数字”可以测量。

• 定义定性评分准则：与研究员共同制定一个评分表。例如，对于“代码可读性”：
  • 函数长度：超过50行扣1分。
  • 注释覆盖率：关键逻辑无注释扣1分。
  • 命名一致性：发现不一致的命名扣0.5分。
  • 圈复杂度：使用工具（如eslint-complexity）计算，值高于阈值扣分。
• 人工评审介入：设置一个混合流程。研究员生成多个候选方案（代码片段），然后由你在发现阶段提供一个“评审脚本”。这个脚本会向你展示两个方案的diff，并询问你“哪个更可读？”。虽然不能全自动，但将方案生成和对比工作交给了AI，你只做最终裁决，效率依然大幅提升。

我个人最大的体会是，ResearcherSkill不是一个“魔法黑箱”，而是一个“力量倍增器”。它不会替代你的专业判断，而是将你从繁琐、重复的试错劳动中解放出来，让你专注于定义问题、制定标准和做更高层次的决策。它迫使你更严谨地思考“什么是好”，这个过程本身就能带来深刻的洞察。最让我惊喜的不是它找到了某个特定优化，而是在.lab/logs里看到的那些它尝试过并放弃的路径——那些你自己永远没耐心去系统性排除的“可能性”，让你对问题的理解变得前所未有的清晰。