tech-article-reproducibility

name	tech-article-reproducibility
description	技術記事の再現性 (読者が手元で再現できるか) を評価するスキル。subagent に「初見の読者として手元で再現を試みる」シミュレーションをさせ、足りない情報をリストアップさせる。記事ドラフトの最終チェック、または公開後フィードバック前の事前検証で使う。

Tech Article Reproducibility

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

いつ使うか

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

使わない場面:

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

適用判定

評価前に、対象記事が「読者が手元で同じ操作・検証・表示を再現する記事」かを判定する。

• 対象: セットアップ、ハンズオン、トラブルシュート、移行手順、ベンチマーク、検証結果など、読者が同じ操作や確認を再実行できる記事
• 対象外: 概念解説、意見、用語整理、記事内の短い例だけで完結する小ネタなど、手元で再現する中心作業がない記事
• 限定評価: 概念記事内に短いコード例や iframe などがある場合、記事全体は対象外と明示したうえで、その再現部分だけを限定評価する

対象外の場合は 20 点満点の採点を強行しない。レポートでは「対象外」または「限定評価」と明記し、必要なら不足情報だけを短く返す。限定評価の範囲は、記事内の実行可能なコード、表示デモ、検証手順に限る。一般的な参考リンクや概念説明は、再現対象ではなく補助情報として扱う。

適用判定は採点表より優先する。対象外の記事では 10 軸採点を省略する。限定評価では「限定評価」と評価範囲を先に示し、必要な軸だけを補助的に使う。限定評価を 20 点満点の総合点に換算しない。

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

各軸を 0〜2 点で採点、合計 20 点満点。

#	軸	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 不要

採点時の特殊ケース

中間点 (1) の判定は以下の指針で一貫させる。

• 軸 5 (設定ファイル全文掲載): 記事の主題が CLI コマンド操作中心で設定ファイル編集が主題でない場合、関連する dotfile (~/.zshrc 等) への追記行を全文掲載していれば 2 点。claude mcp add のような CLI が設定を生成する方式は、確認コマンド (claude mcp list 等) が併記されていれば 2 点、無ければ 1 点。フォーマッター、linter、ビルド、ベンチマークの記事では、主設定だけでなく ignore ファイル、package scripts、hook 設定も再現結果に影響する場合は設定として扱う。本文で影響しないと説明されていれば採点対象から外してよい
• 軸 7 (エラー時の対処): 記事の主題自体がエラー対処である場合、派生エラーや別原因ケースへの言及数で採点する (0 件 = 0、1 件 = 1、2 件以上 = 2)。主題エラー自体の対処が書かれているだけでは 2 点とはしない
• 軸 1 (環境前提の明示): OS 名のみ = 0、OS + メジャーバージョン + 主要ツール 1 つ = 1、OS マイナーバージョン + 言語 / CLI ツールの具体バージョン全て = 2
• 軸 2 (コードの完全性): 検証記事・ベンチマーク記事では、比較スクリプト、対象ファイル抽出手順、集計手順、復元手順も「コード」に含める。コマンド中心記事では、主コマンドだけでなく接続先指定、設定生成、確認コマンドまで含めて完全性を判定する
• 軸 3 (コマンドの正確性): CLI が設定を生成する記事では、実際に必要な引数、接続先、確認コマンドが欠けている場合は 2 点にしない。placeholder がなくても、読者が同じ状態に到達できないコマンドは 0 または 1 点に倒す
• 軸 9 (リンク健全性): 全リンクが public に到達可能なら 2 点。到達確認できないリンクが一部あるが、リンク切れや認証必須とは断定できない場合は 1 点。確認手段が全く使えない、または主要リンクが未検証の場合は 0 (未検証) とする。確認済みのリンク切れ、認証必須、private リンクが主要情報源に含まれる場合は 0 点

判断に迷ったら常に 低い方 を選ぶ。再現性評価は厳しめに倒すのが本 skill の主旨。

採点根拠は記事内で観測できる記述、コード、コマンド、スクリーンショット、公開リンクに限定する。評価者の一般知識や外部ドキュメントで不足を補って 2 点にしない。外部ドキュメントを確認した場合も、それは「記事外情報が必要」という不足として扱う。

評価ワークフロー

評価は subagent への dispatch で行う。subagent には「実行者」ではなく 「再現を試みる初見の読者」のロールプレイ をさせる。

dispatch は呼び出し側 agent が行い、1 回の評価につき subagent は 1 つとする。dispatch された subagent は下記テンプレを実行し、さらに別の subagent を起動しない。修正後の再評価 (手順 6) は、新しい評価として別の subagent を dispatch する。

評価だけを依頼された場合、または dispatch された subagent として動いている場合は、レポートを返して止める。記事の修正は呼び出し側 agent の責務であり、評価結果を受けて修正まで求められている場合だけ行う。

呼び出し側が追加の要件チェックリストやレポート構造を渡した場合は、そちらを優先して満たす。ただし、この skill の中核制約である「状態変更コマンドを実行しない」「対象外や限定評価を 20 点満点に換算しない」「未検証リンクをリンク切れと断定しない」は、呼び出し側の出力形式より優先する。

記事を修正する場合は、記事リポジトリの制約を先に確認する。フロントマター、textlint-disable / textlint-enable コメント、画像パス、AI 編集禁止範囲は、再現性改善のためでも削除・移動・改変しない。

1. 対象記事を確定
2. 適用判定を行い、対象外なら採点せずに対象外理由または限定評価だけを返す
3. 対象記事なら subagent dispatch (後述のテンプレ)
4. 戻ってきた評価から「再現詰まりポイント」を抽出
5. 詰まりポイントに対応する記述を記事に追加 / 修正
6. 必要なら新規 subagent で再評価

subagent dispatch テンプレ

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

<技術スタック> は記事の主題ツールや主題フレームワークを具体名で埋める。未指定の場合は、記事の主題技術は初見、一般的な shell / editor / browser 操作は可能な読者として扱う。

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

## 技術スタックの扱い
記事タイトル、フロントマター、見出し、コードブロックの言語、import / package manager / 設定ファイル名から主題技術を推定する。推定できない場合は「主題技術は不明」と明記し、該当する環境前提・バージョン依存・プロジェクト前提の点数を低く倒す。

## 実行制限
このテンプレを受け取った agent は、dispatch 済みの評価者として扱う。さらに別の subagent を起動しない。リンク到達性確認は任意であり、軸 9 の判定に必要で、利用可能な Web 確認手段がある場合だけ行う。確認する場合も HTTP 到達性と public アクセス可否の確認に限る。この記事リポジトリでは `npx markdown-link-check <記事ファイル> --config markdown-link-check.config.json` を優先して使う。対象は評価対象ファイル 1 つに限り、`npm run link:check` は実行しない。GUI ブラウザ操作、ログイン、フォーム送信、ファイル作成、インストール、ビルド、ベンチマーク、公開、削除は行わない。403、timeout、ネットワーク制約、ツール不足、または時間制約で確認しない場合は「未検証」と書き、リンク切れとは断定しない。

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

1. 環境前提の明示
2. コードの完全性
3. コマンドの正確性
4. バージョン依存の明示
5. 設定ファイル全文掲載
6. 期待される出力の提示
7. エラー時の対処
8. プロジェクト前提の明示
9. リンク健全性 (`markdown-link-check`、WebFetch、または利用可能な Web 確認手段で確認)
10. 著者依存知識の明示

## タスク
1. 記事が再現性評価の対象かを判定する。対象外なら 20 点満点採点を省略し、対象外理由または限定評価だけを返す
2. 対象記事の場合、記事を読みながら「自分が手元で再現するならどこで詰まるか」を想像する
3. 記事内のインストール、変更、削除、生成、ベンチマークなどのコマンドは実行しない。リンク到達性確認だけは例外として行ってよい
4. 各軸 0〜2 で採点 + 根拠を引用
5. 詰まりポイント Top 5 を行番号付きで列挙。行番号は `nl -ba` などで確認する

## レポート構造
- 再現性スコア: 対象記事は X/20 (内訳テーブル)。対象外または限定評価の場合は「対象外」または「限定評価: <評価範囲>」と書き、20 点満点に換算しない
- 詰まりポイント Top 5: <行番号> <引用または要約> → <なぜ詰まるか>
- 不足情報: 記事に追加すべき情報のリスト
- 総評: この記事を読んで手元で再現できる確率は何 % か (主観)

レポート作成時の裁量ガイド

subagent が迷いやすい箇所の既定値。明記しておくことで評価のブレを抑える。

• 詰まりポイントの引用: 厳密引用ではなく要約 + 行番号で可。記事が短く詰まりどころが 5 件未満なら「Top N (5 件未満の理由)」の形で列挙
• 詰まりポイントの並び順: 初見読者が遭遇する影響度の高い順 (重篤度 > 出現順)
• 不足情報リストの並び順: 記事内の出現順に近い順
• 再現確率 (%): 単一値または幅 (例: 40-50%) どちらでも可。算出式は設けない (主観評価)
• 軸 9 のリンク確認: HTTP 到達性 + public アクセス可否まで確認すれば 2 点判定に足りる。コンテンツ検証 (stars 数・README 実在など) は不要、やるなら加点材料ではなく参考情報として補足する
• リンク確認できない環境: markdown-link-check や WebFetch が使えない場合は、利用可能な Web 確認手段で代替する。Web 確認手段が使えない、ネットワーク制約で確認できない、または短時間で確認が終わらない場合は再試行を続けない。軸 9 は 0 (未検証) とし、レポートに「リンク到達性は未検証」と明記する。未検証を「リンク切れ」とは書かない

スコアの読み方

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

落とし穴

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