tech-article-reproducibility

技術記事の再現性

「読者が自分のマシンで同じことを再現できるか」という観点から、技術記事の品質を測定します。これは、文章スタイルの評価（mizchi-blog-style）や論理性の評価とは独立した軸です。前提となる考え方は、技術記事で最も重要なのは、読者が自分のマシンで再現できるかどうかです。

使用する場面

• 技術記事のドラフトを公開する前の最終チェック
• ハンズオン記事／チュートリアル記事
• ツール紹介記事／セットアップ記事
• 「動作した」と主張する記事の検証

使用しない場面：

• 概念を解説する記事（再現するものがない）
• 詩／意見記事
• 完結した短い小ネタ

再現性のチェック軸（10項目）

各項目を0〜2点で評価し、合計20点満点から10点満点に換算します。

#	項目	0（NG）	1（部分的）	2（OK）
1	環境の前提条件が記載されている	OS／バージョン／必要なツールの記載がない	一部のみ記載	すべて記載（OS、言語のバージョン、CLI ツール）
2	コードの完全性	断片のみで、インポートやセットアップが省略されている	主要部分のみ	コピー＆ペーストして実行できる完全な形式
3	コマンドの正確性	プレースホルダーが説明なしでそのまま残っている（<your-token> など）	一部にプレースホルダーがある	そのまま実行できる
4	バージョン依存関係が記載されている	記載がない	部分的に記載	例：「v3.x で動作する」「v2 以前では X のように動作する」と明記されている
5	設定ファイル全体が含まれている	抜粋のみ	主要なキーのみ	動作する最小限の設定ファイル全体
6	期待される出力が示されている	なし	文章で説明	実際の出力／スクリーンショット
7	エラーへの対処	記載がない	1つのケースに触れている	主要なエラーを複数取り上げ、対処方法も説明している
8	プロジェクトの前提条件が記載されている	執筆者の環境に関する前提が暗黙のまま	部分的に記載	パス／リポジトリの構成／既存の設定がすべて記載されている
9	リンクの有効性	リンク切れ、または認証が必要	一部に認証が必要なリンクがある	すべて一般公開され、アクセス可能
10	執筆者固有の知識が明示されている	ヘルパー／dotfiles が暗黙に前提とされている	部分的に記載	すべて明記されている、または不要

評価のワークフロー

技術記事を評価する際は、empirical-prompt-tuning と同じサブエージェントのディスパッチ方法を使います。異なるのは、サブエージェントが「実行者」ではなく、**「初めて読む読者として作業の再現を試みる人」**の役割を担うことです。

1. 対象の記事を確定する
2. サブエージェントをディスパッチする（以下のテンプレートを使用）
3. 返された評価から「再現時につまずく点」を抽出する
4. その点に対処するため、記事に文章を追加／修正する
5. 必要に応じて、新しいサブエージェントで再評価する

サブエージェントのディスパッチテンプレート

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以下：再現が困難です。記事の前提を見直すか、ハンズオン記事以外の形式として位置付けてください

注意点

• 評価者の背景知識が高すぎる：サブエージェントに「初心者の役割」を明示しないと、専門家の視点から「情報は十分」と判断してしまいます。プロンプトでは「初めて読む読者」であることを強調してください
• リンクの有効性を見落とす：公開時に有効なリンクも、1年後には切れている場合があります。有効なリンクだけを使って再現できるか、別途確認してください
• サンプルコードをすべて記事内に載せる：再現性は上がりますが、記事が長くなります。コードを記事内に載せつつ、リポジトリへのリンクも含めるハイブリッドな方法が現実的です
• 再現性 ≠ 文章の品質：再現性が高くても、読みづらい記事はあり得ます。mizchi-blog-style などと組み合わせ、両方の軸を測定してください

関連項目

• empirical-prompt-tuning — サブエージェントのディスパッチと反復的な改善のためのメタスキル
• mizchi-blog-style — 文章スタイル軸での評価（このスキルとは独立）