Tech Article Reproducibility

技術記事の品質を「読者が手元で同じことを再現できるか」の観点で測る。文体評価 (mizchi-blog-style) や論理評価とは独立した別軸。技術記事で一番大事なのは、読んだ読者が手元で再現できるかどうか という前提に立つ。

いつ使うか

• 技術記事ドラフトの公開前最終チェック
• ハンズオン記事 / チュートリアル記事
• ツール導入記事 / セットアップ記事
• 「動いた」と書いた記事の検証

使わない場面:

• 概念解説記事 (再現するものがない)
• ポエム / オピニオン記事
• 記事内で完結する小ネタ

再現性チェック観点 (10 軸)

各軸を 0〜2 点で採点、合計 20 点満点 → 10 点換算。

#	軸	0 (NG)	1 (部分的)	2 (OK)
1	環境前提の明示	OS / バージョン / 必要ツール記載なし	一部記載	全部記載 (OS, lang version, CLI ツール)
2	コードの完全性	断片のみ、import/setup 省略	主要部分のみ	コピペで動く完全形
3	コマンドの正確性	placeholder のまま (<your-token> 等が説明なし)	一部 placeholder	そのまま実行可能
4	バージョン依存の明示	言及なし	一部	「v3.x で動作」「v2 以前は X」等明示
5	設定ファイル全文掲載	抜粋のみ	主要キーのみ	動く最小構成全文
6	期待される出力の提示	なし	文章で説明	実出力 / スクショ
7	エラー時の対処	触れず	1 件触れる	主要エラー数件 + 対処
8	プロジェクト前提の明示	著者環境前提が暗黙	部分的に明示	path / repo 構造 / 既存設定が全部明示
9	リンク健全性	リンク切れ or 認証必要	一部要認証	全部 public でアクセス可
10	著者依存知識の明示	ヘルパー / dotfiles 暗黙	一部明示	全部明示 or 不要

評価ワークフロー

技術記事の評価には empirical-prompt-tuning と同じ subagent dispatch を使う。違いは subagent に「実行者」ではなく 「再現を試みる初見の読者」のロールプレイ をさせること。

1. 対象記事を確定
2. subagent dispatch (後述のテンプレ)
3. 戻ってきた評価から「再現詰まりポイント」を抽出
4. 詰まりポイントに対応する記述を記事に追加 / 修正
5. 必要なら新規 subagent で再評価

subagent dispatch テンプレ

あなたは <記事のテーマ領域> に興味があるが <技術スタック> は初めての読者です。
この記事を読んで、手元の環境で同じことを再現しようとします。

## 対象記事
<記事ファイルのパス>

## 評価観点 (再現性 10 軸)
各軸を 0〜2 点で採点。`tech-article-reproducibility` skill の判定表参照:
/Users/mz/.claude/skills/tech-article-reproducibility/SKILL.md

1. 環境前提の明示
2. コードの完全性
3. コマンドの正確性
4. バージョン依存の明示
5. 設定ファイル全文掲載
6. 期待される出力の提示
7. エラー時の対処
8. プロジェクト前提の明示
9. リンク健全性 (実際に WebFetch で確認)
10. 著者依存知識の明示

## タスク
1. 記事を読みながら「自分が手元で再現するならどこで詰まるか」を想像する
2. 各軸 0〜2 で採点 + 根拠を引用
3. 詰まりポイント Top 5 を行番号付きで列挙

## レポート構造
- 再現性スコア: X/20 (内訳テーブル)
- 詰まりポイント Top 5: <行番号> <引用> → <なぜ詰まるか>
- 不足情報: 記事に追加すべき情報のリスト
- 総評: この記事を読んで手元で再現できる確率は何 % か (主観)

スコアの読み方

• 18-20: ハンズオンとして公開可能、ほぼ追加情報不要
• 14-17: 多少のググりは必要だが再現可能、公開可
• 10-13: 再現するには記事外の情報が必要、追加修正推奨
• 9 以下: 再現困難、記事の前提を見直す or ハンズオン以外として位置付ける

落とし穴

• 評価者の前提知識が高すぎる: subagent に「初心者ロール」を明示しないと、専門家視点で「足りる」と判定する。プロンプトで「初見」を強調する
• リンク健全性を無視: 公開時点では生きてても 1 年後切れることがある。生きてる リンクのみで再現可能か別途チェック
• サンプルコードを全部 inline: 再現性が上がる代わりに記事が肥大化する。リポジトリへのリンクと併用するハイブリッドが現実的
• 再現性 ≠ 文体品質: 再現性が高くても読みにくい記事はある。mizchi-blog-style 等と併用して両軸で測る

関連

• empirical-prompt-tuning — subagent dispatch + 反復改善のメタスキル
• mizchi-blog-style — 文体軸の評価 (本スキルと独立した軸)