| 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 編集禁止範囲は、再現性改善のためでも削除・移動・改変しない。
- 対象記事を確定
- 適用判定を行い、対象外なら採点せずに対象外理由または限定評価だけを返す
- 対象記事なら subagent dispatch (後述のテンプレ)
- 戻ってきた評価から「再現詰まりポイント」を抽出
- 詰まりポイントに対応する記述を記事に追加 / 修正
- 必要なら新規 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: 再現性が上がる代わりに記事が肥大化する。リポジトリへのリンクと併用するハイブリッドが現実的
- 再現性 ≠ 文体品質: 再現性が高くても読みにくい記事はある。
