auto-research

自动研究

通过以下步骤改进目标提示词产物（SKILL.md、CLAUDE.md、子 Agent 定义、斜杠命令或通用提示词 Markdown）：

1. 检测产物类型及适用规则
2. 研究当前权威最佳实践，并行开展研究——每项主张都必须引用来源
3. 提出重写方案，并为每项改动说明理由和来源 URL
4. 验证重写内容——对于可测试的产物，采用 Karpathy 风格的自主二元断言评估循环，并进行 Git 提交/重置记录；对于不可测试的产物，执行确定性格式验证
5. 仅在最后一步确认，提供修改前后的评分表、差异和引用来源——只有用户明确回复“yes”才会最终写入

在第 1 至第 4 步之间自主运行。只在第 5 步停止。

---

阶段 0 — 读取输入并设置工作区

用户会指定目标产物（可以是路径，也可以是“我的文案撰写技能”这样的描述——需据此确定目标）。解析规则：

• 如果提供了路径，就使用该路径。
• 如果提供了技能名称，依次搜索 .claude/skills/<name>/SKILL.md（项目）和 ~/.claude/skills/<name>/SKILL.md（用户）。
• 如果用户说“这个 CLAUDE.md”或类似描述，则使用当前工作目录树中最具体的文件（项目 > 用户）。

然后：

1. 完整读取目标产物。
2. 根据 references/artifact-types.md 对其进行分类：SKILL.md / CLAUDE.md / 子 Agent / 斜杠命令 / 通用提示词。
3. 设置工作区——在目标旁边创建同级目录 .auto-research/<target-name>/。如果目标的父目录不在 git 仓库内，则在该目录运行 git init，以便在本地进行提交/重置记录。（如果用户的项目根目录已有自己的 Git 仓库，且目标位于其中，请使用现有仓库——不要初始化子仓库。）
4. 记录基线——将原始产物复制到 .auto-research/<target-name>/iteration-0/baseline.md，并记录 Git 修订版本（如果可用，运行 git rev-parse HEAD；否则记为“未跟踪”）。
5. 创建 iterations.tsv，包含以下列：iter | hypothesis | score_before | score_after | decision | git_rev | timestamp | notes。

整个工作区结构见 references/eval-loop.md。准备在阶段 4 运行评估循环时，阅读该文件。

---

阶段 1 — 提取研究主题

阅读产物并列出研究主题——即通过回答这些具体问题，可以更好地重写产物。每个主题都必须：(a) 有望在 2026 年通过网络找到权威答案；(b) 直接适用于目标中的某个部分、主张或惯例。

合格主题示例：

• “Anthropic 当前建议的 SKILL.md description 字段结构是什么？目前的字符数限制是多少？”
• “2026 年，CLAUDE.md 的长度和内容选择有哪些最佳实践？”
• “目前支持哪些 .claude/agents/*.md 前置元数据字段？应如何指定 tools？”
• “官方 skill-creator 技能建议如何在 SKILL.md 正文和参考文件之间采用渐进式披露？”
• “2026 年，哪个 <tool> 前置元数据字段取代了 <old-tool>？”（仅当目标中使用的内容可能已弃用时才提问）

反面示例：

• “这个技能好吗？”——过于笼统，无法进行研究
• “Karpathy 对 autoresearch 有什么看法？”——与目标重写没有直接关系

阅读 references/research-strategies.md，了解各产物类型对应的主题检查清单和来源权威性排序。

本阶段输出：将 research_topics 列表（5–12 个主题）保存到 .auto-research/<target-name>/research_topics.md。

---

Phase 2 — 并行调研

针对每个主题，使用 Agent 工具启动一个并行子 Agent（通用型，模型：sonnet）。每个子 Agent 必须：

1. 使用 WebSearch 查询该主题（当前年份为 2026）。
2. 使用 WebFetch 获取最权威的结果——参见 references/research-strategies.md 中的来源权威性排名。
3. 返回结构化的调研结果：

### Topic: <topic>
**Verdict:** <1–3 sentence answer>
**Evidence:**
- Quote: "..." — <URL>
- Quote: "..." — <URL>
**Confidence:** high | medium | low
**Implications for rewrite:** <1–2 sentences>

在一条消息中并行启动所有主题 Agent（在单个响应中多次调用 Agent 工具）。等待所有 Agent 完成。如果任何 Agent 返回“低置信度”或未找到来源，则将该主题标记为不确定，并将其从改写中删除，或提出一个有针对性的澄清调研问题。

将汇总的调研结果保存到 .auto-research/<target-name>/findings.md。

---

Phase 3 — 提出改写方案（草稿）

根据调研结果，生成改写后的内容，并保存到 .auto-research/<target-name>/iteration-1/proposal.md。

规则：

• 每项实质性改动都必须能追溯到 findings.md 中至少一条引文。
• 除非有引文支持的最佳实践另有建议，否则保留项目特有的内容（德语文案、自定义工作流、示例）。
• 遵守 references/artifact-types.md 中的格式限制（行数上限、frontmatter 规则等）。
• 不得悄然编造没有证据支持的新章节。

随后在 .auto-research/<target-name>/iteration-1/rationale.md 中生成理由说明块。每项改动的格式如下：

### Change: <one-line summary>
**Old:** <quoted excerpt>
**New:** <quoted excerpt>
**Why:** <1–2 sentences>
**Source:** <URL>

---

Phase 4 — 验证／评估循环

根据内容类型决定验证策略。在 references/artifact-types.md 中查阅规则——该文件中的表格按类型说明是运行自主 Karpathy 评估循环，还是仅进行格式验证。

4a. 格式验证（始终运行）

在运行任何评估循环之前，执行确定性检查：

• SKILL.md：frontmatter 中包含 name 和 description；description ≤ 1024 个字符；正文 ≤ 500 行；引用最多嵌套一层。
• CLAUDE.md：总计 ≤ 200 行（200–250 行时警告，但不判失败）；导入最多嵌套一层；不得包含 Windows 反斜杠路径。
• 子 Agent（.claude/agents/*.md）：frontmatter 有效（包含 name、description，以及可选的 tools、model）；description 使用第三人称，并采用“use when …”模式。
• 斜杠命令（.claude/commands/*.md）：frontmatter 可选；长度合理（< 200 行）；用途明确且单一。
• 通用提示词 MD：仅检查行数和标题结构是否合理。

如果格式验证失败，修复改写方案并重新验证，然后再继续。不得在方案格式不正确时进入下一步。

4b. 自主评估循环（仅适用于符合条件的类型）

符合条件的类型见 references/artifact-types.md：SKILL.md（始终适用）；具有可衡量输出的通用提示词（用户提供了测试输入时适用）。

运行 references/eval-loop.md 中记录的循环。该参考文件包含完整的操作手册：

• 如何使用二元断言生成 evals.json
• 自主执行指令块（“Be aspy, do not stop, keep looping…”）
• 每轮流程：提出假设 → 修改 → 在 N 个测试提示词上运行技能 → 评分 → 保留（git commit）或还原（git reset）→ 记录
• 迭代次数上限：默认 10 次，最多 15 次（超过后质量通常会下降——参见 eval-loop.md）
• 确定性评分器为 scripts/score_evals.py

该循环会自主运行——循环过程中不得暂停并向用户提问。可以推送通知，但不得提问。

4c. 跳过评估的分支

如果内容类型属于跳过评估的类型（CLAUDE.md、子 Agent、斜杠命令、没有测试输入的通用提示词），则评分为“format-validation-only: PASS/FAIL”。不得编造评估分数。

---

阶段 5 — 最终确认关卡（唯一的停止点）

只有到这一步，技能才会停止并询问用户。请阅读 references/confirmation-gate.md，了解确切的报告格式。

生成一份确认报告，其中包含：

1. 产物 — 路径、类型、修改前后的总行数
2. 得分 — 如果运行了评测循环，则填写评测通过率（修改前后）；否则填写“仅格式验证”
3. 迭代 — 来自 iterations.tsv 的表格
4. 来源 — findings.md 中引用的所有 URL，去重后列出
5. 差异 — 基线版本与最终提案之间的统一差异（若内容较长，截取至约 150 行；完整差异保存在 .auto-research/<target-name>/final.diff 中）

然后只问一个问题：“将这些更改应用到 ？（yes / no / iterate-with-feedback）”。

• yes → 用最终提案覆盖目标文件。工作区中的 git 历史已记录迭代过程；请将最终提交信息复制到 .auto-research/<target-name>/RESULT.md。
• no → 保持目标文件不变。工作区保留，供检查。
• iterate-with-feedback → 将用户的自由文本反馈作为新约束，返回阶段 3 并添加该约束，再进行一次迭代，然后重新进入阶段 5。

不要无限循环——如果用户连续三次选择“iterate”且未选择“yes”，请明确指出这一点，并询问是否中止。

---

工具与模型指南

• 阶段 2（研究）：使用 general-purpose 子 Agent，模型为 sonnet，并行运行。
• 阶段 3（改写）：主 Agent（Opus）执行。按顺序进行一次处理——综合分析需要完整上下文。
• 阶段 4（评测循环）：主 Agent 驱动循环；启动 general-purpose sonnet 子 Agent，在每个测试提示词上执行目标技能（可在一次迭代中并行处理各提示词）。评分器为确定性的 Python 脚本。
• 绝不要让评测循环修改评分脚本（scripts/score_evals.py）或 evals.json——这些是锁定的事实依据，相当于 Karpathy 的 prepare.py。

---

此技能刻意不做的事

• 它不会从头创建新技能。请使用 skill-creator 技能。此技能用于改进现有产物。
• 它不会运行 Anthropic 完整的评测／基准测试／打包流水线。skill-creator 已负责这些，而且可以与此技能组合使用。
• 它不会在不通知的情况下覆盖目标文件。阶段 5 是强制步骤。
• 它不会改写研究主题全部被判定为“低置信度”的目标——请明确说明这一点，并询问是否在缺乏有力证据的情况下继续。