Tech Review

---
name: tech-review
description: 技術ブログ記事、チュートリアル、技術原稿を、技術的正確性、一次情報、現在の API 挙動、コード、再現性、セキュリティ、アクセシビリティ、互換性の観点からレビューする。技術的な主張、コードサンプル、対応バージョン、仕様、公開前の正確性を確認してほしいと依頼されたときに使用する。一般的な文章校正は article-review に任せ、明示的な依頼なしに原稿を変更しない。
---

# 技術的正確性をレビューする

懐疑的なエンジニアと読者の立場から、記事の正しさ、根拠、再現性と、読者が手順を実行した場合の影響を確認する。

## 対象と範囲を把握する

Markdown、MDX、貼り付けた原稿、または明確に特定された記事を受け付ける。記事全体と、利用可能な検証用プロジェクト、設定、依存関係を読む。想定読者と記事タイプは可能な限り原稿から推定し、欠けた情報が検証を妨げる場合だけ質問する。

既定ではレビューだけを行い、ファイルを変更しない。編集はユーザーが明示的に依頼した場合だけ行う。

[`references/technical-checklist.md`](references/technical-checklist.md) を読み、次を特定する。

- 中心的な主張と結論
- バージョンや時期に依存する記述
- 仕様や API に関する規範的な主張
- 実行を意図したコード
- 検証環境と観測結果
- セキュリティ、プライバシー、アクセシビリティ、互換性、運用上の影響

## 根拠と現在の挙動を確認する

変更され得る情報、参照された資料、現在の対応状況は Web で確認する。仕様、公式ドキュメント、公式リポジトリ、リリースノート、標準化の議論、公式テストを優先する。検索結果の要約だけで判断せず、リンク先を読む。

規範的要件、実装固有の挙動、過去の提案、著者の推測、意見を区別する。資料にない設計理由を作らない。引用した資料が、記事中の近接する主張を実際に裏付けているか確認する。

## コードを比例的に検証する

検証の優先順位を次のとおりにする。

1. 記事に対応する完全な検証用プロジェクトと記録されたコマンド
2. リポジトリで既に利用できるテスト、ビルド、型検査
3. 記事のコードと検証済みコードの一致
4. 完全なサンプルがない場合の、独立して実行可能なコードブロックの検査

記事の主張に関係する検証だけを選び、可能なら対象サンプルやパッケージに範囲を絞る。必要な検証が通ったら終了し、新しい変更、失敗、未解決の懸念がなければ検証を拡大・反復しない。修正後の再検証は、修正箇所と影響する主張を対象にする。

Markdown のコードブロックは前後の状態や省略部分に依存することがあるため、単体実行の失敗だけで記事の誤りと断定しない。JavaScript、TypeScript、JSX、TSX の独立したコードブロックを補助的に確認する場合は、内容が安全で外部サービスや認証情報を含まないことを確認してから実行する。

```bash
python3 .claude/skills/tech-review/scripts/run_code_samples.py <記事ファイル>
```

スクリプトはインストール済みの `node`、`tsx`、`ts-node`、`tsc` だけを利用する。公開資料の読み取りと既存環境での安全なローカル検証は、その都度承認を求めず進める。パッケージの追加・依存関係の取得、課金を伴う実行、外部サービスのデータ更新、システムフラグの変更には、対象と操作を含むユーザーの承認が必要である。同じ対象・操作について承認済みなら再確認しない。承認は実行環境の権限を拡張するものではない。破壊的、認証情報を含む、本番環境を対象とするコードは実行しない。

実行した場合は、コマンド、環境、結果、記事との差を記録する。実行できない場合は静的レビューに切り替えて制約を明示する。構文チェックの成功を実行時挙動の証明として扱わない。

## 指摘を報告する

重要度順、同じ重要度では行番号順に並べる。

- `P0`: 危険、根本的に誤り、または公開を止める問題
- `P1`: 公開前に直すべき実質的な技術的誤り
- `P2`: 正確性、根拠、再現性を有意に改善する問題
- `P3`: 任意の技術的改善

```text
[P1] 短い指摘タイトル
Location: contents/blogPost/example.md:42
Impact: 読者または実行結果への具体的な影響
Evidence: 問題を確立する一次情報、実行結果、または推論
Suggestion: 具体的な修正または検証手順
```

根拠へのリンクは主張の近くに置き、同じ原因の指摘はまとめる。確認できなかったという理由だけで誤りと断定しない。根拠によって問題を確立した指摘と、未確認事項・検証の制約を分け、後者には不足している証拠と確認方法を記す。指摘がなければその旨と、完了できなかった重要な検証を列挙する。求められない限り良い点のセクションを作らず、技術的意味を変えない文章上の問題は `article-review` に任せる。

## 依頼された修正を適用する

ユーザーが修正を依頼した場合だけ、根拠で確立できる客観的な訂正を適用する。論旨、範囲、アーキテクチャ、筆者の意見を変える前に合意を得る。修正後は影響する検証を再実行し、変更ファイル、コマンド、結果、未解決事項を報告する。