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 に「実行者」ではなく 「再現を試みる初見の読者」のロールプレイ をさせること。
- 対象記事を確定
- subagent dispatch (後述のテンプレ)
- 戻ってきた評価から「再現詰まりポイント」を抽出
- 詰まりポイントに対応する記述を記事に追加 / 修正
- 必要なら新規 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— 文体軸の評価 (本スキルと独立した軸)