tech-article-reproducibility

技术文章可复现性

从“读者能否在自己的机器上复现相同结果？”的角度衡量技术文章的质量。这是一个独立于行文风格评估（mizchi-blog-style）和逻辑评估的维度。核心前提：技术文章最重要的是读者能否在自己的机器上复现内容。

适用场景

• 技术文章草稿发布前的最终检查
• 实操类文章／教程类文章
• 工具介绍类文章／环境配置类文章
• 验证声称“已成功运行”的文章

不适用场景：

• 概念讲解类文章（没有需要复现的内容）
• 诗歌／观点文章
• 内容独立、篇幅很短的小贴士

可复现性检查维度（10 项）

每项按 0–2 分计分，总分 20 分 → 换算为 10 分制。

#	维度	0（不合格）	1（部分达标）	2（合格）
1	说明环境前提	未列出操作系统／版本／必需工具	部分列出	全部列出（操作系统、语言版本、命令行工具）
2	代码完整性	只有代码片段，省略导入／设置	只有主要部分	完整、可复制粘贴并运行
3	命令准确性	保留占位符（如 <your-token>）且未作说明	部分命令含占位符	可直接运行
4	说明版本依赖	未提及	部分说明	明确说明，例如“适用于 v3.x”“v2 及更早版本的行为是 X”
5	提供完整配置文件	仅提供节选	仅提供主要键	提供完整的最小可运行配置
6	展示预期输出	无	用文字说明	实际输出／截图
7	说明错误处理方式	未提及	涉及一种情况	列出几种主要错误及其处理方式
8	说明项目前提	隐含依赖作者环境的假设	部分说明	说明路径／仓库结构／现有配置
9	链接可用性	链接失效或需要身份验证	部分链接需要身份验证	所有链接均可公开访问
10	说明作者特有知识	隐含依赖辅助工具／dotfiles	部分说明	完整说明，或无需此类知识

评估流程

评估技术文章时，使用与 empirical-prompt-tuning 相同的子 Agent 调度方式。不同之处在于，子 Agent 扮演的是**“首次尝试复现内容的读者”**，而非“执行者”。

1. 确定目标文章
2. 调度子 Agent（使用下方模板）
3. 从评估结果中提取“复现卡点”
4. 在文章中添加／修正文案，解决这些卡点
5. 如有需要，换一个新的子 Agent 重新评估

子 Agent 调度模板

You are a reader interested in <the article's subject area> but new to <the tech stack>.
You are going to read this article and try to reproduce the same thing in your local environment.

## Target article
<path to the article file>

## Evaluation axes (10 reproducibility axes)
Score each axis 0–2. Refer to the rubric in the `tech-article-reproducibility` skill:
/Users/mz/.claude/skills/tech-article-reproducibility/SKILL.md

1. Environment prerequisites stated
2. Code completeness
3. Command accuracy
4. Version dependency stated
5. Full config files included
6. Expected output shown
7. Handling of errors
8. Project prerequisites stated
9. Link health (actually verify with WebFetch)
10. Author-specific knowledge stated

## Tasks
1. While reading the article, imagine "where would I get stuck if I reproduced this on my own machine?"
2. Score each axis 0–2 with quoted evidence
3. List the top 5 sticking points with line numbers

## Report structure
- Reproducibility score: X/20 (breakdown table)
- Top 5 sticking points: <line number> <quote> → <why it sticks>
- Missing information: list of things that should be added to the article
- Overall verdict: what percentage chance (subjective) do you have of reproducing this after reading the article

如何解读评分

• 18-20：可作为实操类文章发布；几乎不需要补充信息
• 14-17：需要查找一些资料，但能够复现；可以发布
• 10-13：需要文章之外的信息才能复现；建议修改
• 9 分或以下：难以复现；重新考虑文章的前提，或将其定位为非实操类内容

注意事项

• 评估者的背景知识过于丰富：如果没有明确要求子 Agent 扮演“初学者”，它就会从专家的角度判断信息是否“足够”。请在提示词中强调“首次阅读者”
• 忽略链接可用性：发布时有效的链接，一年后可能失效。应单独检查是否仅凭当前可访问的链接就能完成复现
• 内联所有示例代码：虽然能提高可复现性，但会让文章变得臃肿。将内联代码与仓库链接结合起来的混合方式更为实际
• 可复现性 ≠ 行文质量：文章可能高度可复现，却难以阅读。可结合 mizchi-blog-style 等工具，从两个维度进行评估

相关内容

• empirical-prompt-tuning — 用于子 Agent 调度与迭代改进的元技能
• mizchi-blog-style — 从行文风格维度进行评估（与此技能相互独立）