AIで技術ブログを書く方法：調査・コード検証・人のレビュー

技術ブログにコードが3つ載っていても、1つも実行されていなければ、読者はコピーした直後にエラーへぶつかります。問題は文章の見栄えではなく、事実とコードがゲートを通っていないことです。

AIの下書きは整って見えても、バージョン、コマンド引数、出力形式を推測していることがあります。package.jsonで"type": "module"を宣言しているのに、例ではそのままrequireを使う。あるいはGitHub Actionsについて「毎月2,000分」とだけ書き、特定プランのプライベートリポジトリに対する包含枠だと説明しない、といったケースです。

技術ブログは、テーマをモデルに渡して文章を整えるだけでは完成しません。先に資料と実行可能な証拠をそろえ、AIに説明を整理させ、最後に人が事実、コード、表現を確認します。以下では、各工程にゲートと担当を置き、事実の正確さ、コードの実行可能性、結論の再現性を保つ流れを示します。

AIに書かせる前に資料を調査する

先に調査する内容と、AIに下書きさせられる内容

AIで技術記事を書くときは、外部から取得すべき事実と、モデルに整理させられる部分を最初に分けます。

判断しやすいように、資料を3種類に分けます。

バージョン、変更されたAPIフィールド、公式ドキュメントの制限、価格や上限、セキュリティ設定は先に調査します。誤ると、読者の手順が失敗したり、想定外の費用が発生したりします。たとえば、現在のNext.jsドキュメントではturbopack設定キーを使いますが、13.0.0〜15.2.xではexperimental.turboが使われていました。対象バージョンを示さずに「Turbopackを設定する」と書くと、互換性のない設定をコピーさせるおそれがあります。

一般概念、フレームワークの使い方、ベストプラクティス、よくある失敗はAIに下書きさせられますが、人の確認が必要です。たとえばReact hooksの説明はもっともらしく書けても、ルールの数、命名、バージョン差は公式ドキュメントと照合します。

構成整理、文章の調整、書式の統一はAIに任せやすい作業です。技術説明を読みやすく直したり、関連する段落をまとめたりするだけなら、通常は新たな調査を必要としません。

3種類を比較すると、次のようになります。

調査区分	代表的な内容	ゲートの強さ	適用する工程
先に調査	バージョン、APIフィールド、価格や上限、セキュリティ設定	高：公式ドキュメントから取得し、[VERIFY]を付ける	構成作成時に準備し、執筆日に再確認
AIで下書き＋確認	一般概念、フレームワーク、ベストプラクティス	中：AIの下書きを公式ドキュメントと照合	本文作成時に書き、レビュー時に確認
AIで整理	構成、文章、書式	低：通常は追加調査なし	下書き工程

判断ツリーは次のとおりです。

内容Xに出会う
  ↓
バージョン、API、価格、セキュリティに関係するか？
  ├─ はい → 公式ドキュメントから取得し、[VERIFY]を付け、執筆日に再確認
  └─ いいえ → 技術ルールやベストプラクティスに関係するか？
      ├─ はい → AIで下書きし、レビュー時に公式ドキュメントと照合
      └─ いいえ → AIで説明を整理

調査結果を執筆入力へ渡す方法

調査後は、執筆工程がそのまま参照できる形で結果を入力へ残します。

research.mdから、highと評価した公式ドキュメントなどの高信頼ソースを抜き出します。Google Search Centralの有用なコンテンツに関するガイダンス、GitHub ActionsのNode.js CI例、Astro Content Collectionsの公式ドキュメントなどです。

変わりやすい事実には[VERIFY]を付けます。たとえば「プライベートリポジトリ向けGitHub Actions包含枠はアカウントプランで変わる [VERIFY]」「対象Nodeバージョンが現在もサポートされているか [VERIFY]」と記録します。

ソースカード、コマンド出力、確認結果を、outline inputのsource_cardsとrisk_notesへ入れます。

{
  "source_cards": [
    {
      "url": "https://developers.google.com/search/docs/fundamentals/creating-helpful-content",
      "type": "official/docs",
      "confidence": "high",
      "usable_info": "大規模な自動生成に頼るのではなく、独自情報と十分な説明を提供する"
    }
  ],
  "risk_notes": [
    {
      "fact": "GitHub Actionsの包含枠",
      "status": "[VERIFY]",
      "check_date": "2026-06-24",
      "source": "https://docs.github.com/en/billing/managing-billing-for-github-actions"
    }
  ]
}

この引き継ぎがあれば、執筆工程で調査全体をやり直す必要はありません。印を付けた変動情報だけを再確認できます。

コード例は見た目ではなく実行で確認する

コード検証の4つの場面

技術記事のコードは正しそうに見えても、実際のプロジェクトで失敗することがあります。読者がコピーしてエラーになれば、記事への信頼は失われます。

コード検証は4つの場面に分けられます。

ローカル実行は、npm install、git clone、設定変更、小さなスクリプトを対象にします。実際にローカルで実行し、出力を保存します。

CIテストは、GitHub Actions上のnpm ci、npm run build、npm testのようなビルド、テスト、環境依存を対象にします。CIを使うと環境を繰り返し再現できます。

バージョン確認は、.nvmrc、package.json、API endpointの変更など、Node、依存関係、APIのバージョンを対象にします。バージョンを記録し、必要な差を説明します。環境整合性では、開発、本番、CIの環境変数、Dockerイメージ、OSの違いを確認します。どの環境で実行したかを示し、別環境の結果をそのまま適用させないことが重要です。

4つの場面は次のとおりです。

検証場面	代表的な内容	検証方法	必要な証拠
ローカル実行	インストール、設定ファイル	ローカルで実行	コマンド出力またはスクリーンショット
CIテスト	ビルド、テスト	GitHub ActionsなどのCI	CIログまたはビルド結果
バージョン確認	Node、依存関係のバージョン	バージョン確認コマンド	node --versionの出力とバージョン説明
環境整合性	環境変数、Docker	複数環境でのテスト、または対象環境の明記	環境情報と適用条件

コードの実行証跡を残す方法

すべてのコード例には実行証跡が必要です。「成功した」と書くだけでは証拠になりません。以下のコマンドと出力は記録形式の例であり、そのまま使える実測結果ではありません。対象プロジェクトの実際のバージョンとログに置き換えてください。

Node.js CIの記録例です。

# ローカル環境：macOS + Node 18.20.0 LTS
$ node --version
v18.20.0

# CI環境：GitHub Actions
$ npm ci
added 245 packages in 12s

$ npm run build
✓ Built in 1.23s

$ npm test
✓ 12 tests passed

正しい例では、出力テキストまたはスクリーンショット、バージョン、確認すべき結果を残します。

誤った例では、出力を示さず「成功した」とだけ書きます。

コードはbashやtypescriptなどの言語指定付きfenced code blockに入れます。長い出力は折りたたむか、重要な行だけを表示します。複数工程のコマンドでは、ローカル、CI、Dockerのどこで実行したかを示します。バージョン確認ではnode --versionまたはnpm --versionの出力を残します。

例：

# 実行環境：macOS + Node 18.20.0
$ npm install
added 124 packages in 8s

$ node --version
v18.20.0

ビルド出力が長い場合は、重要な部分だけを示します。

$ npm run build
✓ Built in 1.23s
  ├─ dist/index.html
  ├─ dist/assets/index.js
  └─ dist/assets/index.css

GitHubのCreating and highlighting code blocksには、fenced code blockとシンタックスハイライトが説明されています。技術記事では、コードを文章に見せかけず、コピーと確認ができる形を保ちます。

人のレビューでは事実、コード、構成を確認する

事実確認：バージョン、引数、価格を出典までたどる

人のレビューは文章の言い換えだけではありません。事実、コード、構成の3層を確認します。表現だけを直すと、誤ったバージョン、存在しない引数、コードと一致しない結論を見逃します。

事実確認の中心は追跡可能性です。バージョン、APIフィールド、コマンド引数、設定値、価格や上限、公開日を、公式ドキュメントまたは実行記録と照合します。

確認表：

項目	確認方法	失敗の兆候	適切な証拠
バージョン	公式リリースまたはドキュメントと照合	バージョンが存在しない、機能説明が誤っている	公式リンクとnode --version出力
コマンド引数	公式CLIドキュメントと照合	引数が存在しない、形式が誤っている	公式リンクと実行出力
APIフィールド	公式APIドキュメントと照合	フィールドがない、型が違う	公式リンクと実際のリクエスト例
価格・上限	公式料金ページと照合	価格が違う、公開・非公開などの条件がない	公式リンクと適用条件
公開日	公式告知またはブログと照合	日付が違う、出来事が存在しない	公式告知リンク

誤った例：

package.jsonで"type": "module"を宣言しているのに、サンプルではCommonJSのrequireを直接使い、.cjsへの変更やモジュール境界を説明していません。

別の誤った例：

「GitHub Actionsは毎月2,000分だけ無料」と書き、標準GitHub-hosted runnerは公開リポジトリで無料であること、プライベートリポジトリの包含分数はアカウントプランで変わることを示していません。

より正確な表現：

「Node 18はES modulesとCommonJSの両方をサポートします。.mjs、.cjs、package.jsonのtypeによってファイルの解釈が変わります。この実行記録ではNode 18.20.0を使い、node --versionの出力を保存しました（出典：Node.js公式ドキュメント）。」

「2026年7月26日時点で、標準GitHub-hosted runnerは公開リポジトリで無料です。プライベートリポジトリにはアカウントプラン別の包含分数があり、たとえばGitHub Freeは2,000分、GitHub Proは3,000分です（出典：GitHub Actions billing）。」

コード確認：実行可能性、出力の一致、環境の明記

コード確認では、コマンドが動くか、出力が本文を支えるか、環境が明記されているかを調べます。

項目	確認方法	失敗の兆候	適切な証拠
実行可能なコマンド	ローカルまたはCIで実行	エラー、依存関係不足	実行ログまたはスクリーンショット
出力との一致	出力と本文を比較	出力が説明と矛盾	本文と記録した出力が一致
環境の明記	環境説明を確認	NodeバージョンやOSがない	Node 18.20.0 + macOS
依存バージョン	package.jsonを確認	依存バージョンが本文と不一致	package.jsonまたはバージョン出力

誤った例：

本文は「ビルドで3ファイル生成」と書いているのに、npm run buildの実出力には5ファイルあります。

「ローカルで動作」と書いているのに、サンプルはDockerへ依存し、その条件がありません。

適切な例：

本文とログが一致しています。「npm run buildでindex.html、index.js、index.cssの3ファイルを生成しました。」

環境も明確です。「macOS + Node 18.20.0で確認しました。LinuxまたはWindowsではパスの調整が必要な場合があります。」

構成と文体の確認：H2/H3、内部リンク、AIらしい残り

構成と文体では、H2/H3が承認済みの構成と一致するか、内部リンクが計画どおりか、空疎なAI表現が残っていないかを確認します。

項目	確認方法	失敗の兆候	適切な結果
H2/H3の整合性	outline.mdと比較	見出しの欠落または想定外の追加	構成を変えた理由を記録
内部リンク	リンク計画と比較	リンクがない、アンカーが不正確	説明的なアンカーで配置
AIらしい表現	anti-ai-words.jsonと比較	空疎な主張、曖昧な出典	具体的な事実に変えるか削除

サイトのanti-ai-words.jsonには避けたい表現が分類されています。空疎な主張、曖昧な帰属、過剰な約束を見つけたら、置き換えるか削除します。

誤った例は、時代背景だけを語る導入です。

「この記事では包括的に解説します」のような中身のない約束も避けます。

よりよい導入は問題から始めます。「AIで技術記事を書くときは、どの事実を外部から取得すべきかを最初に判断します。」

約束も確認可能にします。「この工程では、調査、検証、レビューにそれぞれゲートを置きます。」

公開前QAで工程を閉じる

公開前QAチェックリスト

下書きが終わっても公開可能とは限りません。公開前QAは最後のゲートで、調査マーク、コード証跡、事実の出典、構成、内部リンク、AI表現、画像を順番に確認します。

項目	確認方法	合格条件	失敗時の対応
調査マークの解消	[VERIFY]を検索	未解決マークがない	調査へ戻って確認
コード例の検証	実行ログと照合	すべての例に証拠がある	コード検証へ戻る
事実の追跡	ソースカードと照合	重要な事実に出典または条件がある	出典を追加するか断言を削除
構成の整合性	outline.mdと照合	H2/H3が一致、または変更理由がある	構成記録を更新するか理由を残す
内部リンクの配置	リンク計画と照合	リンクとアンカーが正しい	リンクを追加するか計画を修正
AI表現の除去	anti-ai-words.jsonと照合	空疎な表現がない	書き直すか削除
画像の存在	画像一覧とMarkdownパスを照合	参照画像がすべて存在し処理済み	画像を追加するかパスを修正

状態の意味：

合格：公開へ進めます。

保留：出典または主張の再確認が必要です。

失敗：調査、検証、執筆の担当工程へ戻します。

各項目を個別に確認し、問題を見つけた時点で状態を付けます。すべて通過してからタスクを「公開可能」に更新します。

失敗項目を担当工程へ戻す方法

QAで失敗した項目は、問題を担当する工程へ戻します。飛ばしてはいけません。

事実の誤りは調査へ戻し、公式ソースを追加するか、支えられない主張を削除し、変わりやすい事実を再確認します。

コードの誤りは検証へ戻し、コマンドを再実行して出力を保存し、サンプルと環境説明を更新します。

構成の不一致は、構成記録を更新するか、どのH2/H3をなぜ変更したかを明記します。

内部リンクがなければ、リンク計画とサイト在庫を見直し、実在する記事へ説明的なアンカーでリンクします。

AI表現が残っていれば編集へ戻し、警告語を具体的な事実へ変えます。単純置換でも曖昧な場合は文全体を書き直します。

例：

QAでGitHub Actionsの包含枠に公開・非公開条件がないと判明
  ↓
失敗として記録
  ↓
調査工程へ戻す
  ↓
公式の料金情報を追加し、適用条件を明記
  ↓
QAを再実行

戻り先を決める目的は責任の追跡です。最後のレビュー担当が、説明のない変更を引き受けないようにします。

記事が事実から離れた7つの兆候

7つの兆候

事実からのずれは少しずつ積み重なります。公開前に見つけるため、次の兆候を確認します。

兆候1：出典のない断言。「最新バージョン」「公式推奨」「ベストプラクティス」と書きながら、対応する資料がありません。たとえば、あるTurbopack設定キーがすべてのNext.jsバージョンで使えると書き、各バージョンの公式資料を示していない状態です。

兆候2：未実行のコード。実出力やログがなく、「成功した」とだけ書いています。

兆候3：バージョンや引数の分類が誤っている。バージョン自体は存在しても、リリース系列やサポート状態が違う場合があります。コマンド引数やAPI endpointも変わります。Node 20.1.0をLTSと書くのが例で、このリリースはCurrentでした。

兆候4：環境が一致しない。記録した環境と、実際にその挙動を確認した環境が違います。

兆候5：結論を再現できない。性能向上を主張しながら、方法、データセット、再現手順がありません。

兆候6：内部リンクが壊れている。/posts/ai/ai-xxxへリンクしていますが、そのルートが存在しません。

兆候7：曖昧なAI表現が証拠不足を隠している。「包括的な解説」のような表現が、出典や具体的な結果の代わりになっています。

例：

兆候	誤った例	問題
出典なし	「このTurbopackキーはすべてのNext.jsバージョンで使える」	対象バージョンの公式資料がない
未実行コード	「npm installを実行すると成功する」	実行証跡がない
バージョン誤り	「Node 20.1.0 LTS」	20.1.0はCurrentで、LTSではない
環境不一致	古い環境を記録し、別環境だけで確認した挙動へ依存	バージョンと検証環境が一致しない
再現不能な結論	「性能が大幅に改善した」	方法とデータがない
壊れた内部リンク	/posts/ai/ai-xxxへのリンク	ルートが存在しない
AI表現	「AIライティングを包括的に解説」	曖昧な約束

兆候を見つけたら[VERIFY]を付け、担当工程へ戻します。

出典のない断言は調査へ戻し、一次情報を付けるか削除します。未実行コードは検証へ戻します。誤ったバージョンは公式リリースと照合します。環境不一致は実際の条件を明記するか断言を削除します。再現不能な結論は方法、データ、手順を追加するか削除します。壊れた内部リンクは実在するルートに直します。曖昧な表現は具体的な事実に置き換えるか削除します。

重要なのはすぐに戻すことです。修正を先送りすると、小さな不確実性が追跡できない記事へ積み上がります。

完全な実験環境がなくても正直に書く

3つの正直な書き方

有料サービス、複雑なクラスタ、特定OS、特定ハードウェアなど、完全な環境を用意できない場合があります。その不足を埋めるために実行証跡を作ってはいけません。次の3つの方法を使います。

1つ目は、前提と制約を明記することです。確認したバージョンを示し、他のバージョンとの差を説明します。無料枠だけを使った場合もその範囲を明記します。例：「サンプルはNode 18.20.0でのみ確認しました。他のバージョンでは差が出る可能性があります（Node.js公式ドキュメント参照）。」

2つ目は、代替の検証方法を提供することです。最小再現、Mockデータ、公式issueなどを示します。例：「利用できるKubernetesクラスタがないため、ここでは最小再現だけを示します。実クラスタでの検証は別途必要です。」

3つ目は、未検証であることを認めることです。「現在の環境では、この性能結論を再現していません」と書くか、断言を削除します。

比較：

場面	不正確な書き方	正直な書き方
バージョン差	「すべてのバージョンで使える」	「Node 18.20.0で確認。他バージョンでは差が出る可能性がある（Node.js公式資料参照）」
環境差	「ローカルで成功した」	「macOS + Node 18.20.0で確認。Linux、Windows、別Nodeバージョンでは調整が必要な場合がある」
有料サービス	「無料で使える」	「検証は無料枠のみ。付加機能の挙動は異なる場合がある（公式料金ページ参照）」
未検証の断言	「性能が大幅に改善した」	「現在の環境では性能結論を再現していないため、確定結果として扱わない」

適切な例：

「Cloudflare Workersの無料枠で確認しました。現在は1日100,000リクエストが含まれます。付加機能の条件は異なる場合があるため、公式料金ページを確認してください。」

「Kubernetesクラスタを用意できなかったため、最小再現だけを示します。Podのリソース制限やネットワーク設定を含む実クラスタでの確認が必要です。」

「大規模プロジェクトの測定結果がないため、Turbopackのビルド性能について断定しません。自分のプロジェクトで基準値と比較値を記録してください。」

不適切な例：

「Cloudflare Workersは無料です。」上限がありません。

「すべての環境で動きます。」環境が示されていません。

「性能が大幅に改善します。」方法とデータがありません。

Google Search Centralは、有用で信頼でき、ユーザーを第一に考えたコンテンツで、独自情報、十分な説明、有用な分析を勧めています。制約を正直に書くことは基準を下げることではありません。確認済みの範囲と、読者側で検証が必要な範囲を分ける行為です。

公開できる場合と書き直す場合

公開判断ツリー

判断基準は文字数や見た目ではなく、調査、検証、レビュー、QAの4工程が通過したかどうかです。

調査では、高信頼ソースがそろい、変わりやすい事実に印が付いていればコード検証へ進みます。主要ソースがなければ、先に調査します。

コード検証では、すべてのコード例が実行できればレビューへ進みます。失敗した例は修正または削除します。検証できない場合は制約を明記するか削除します。

人のレビューでは、事実を追跡できればQAへ進みます。出典がなければ追加または削除します。理由を記録した構成変更は進められますが、説明のない構成ずれは計画へ戻します。

公開前QAでは、全項目が通過すれば次へ進めます。保留項目は再確認し、失敗項目は担当工程へ戻します。

調査が十分で、変動情報を再確認し、コード例に実行証跡があり、人のレビューで事実と構成を確認し、空疎なAI表現を削除し、QAが通過した記事だけが公開工程へ進めます。

出典、実行記録、内部リンク、表現の修正が不足している場合は補作業が必要です。

主要なバージョン、引数、価格などの事実が誤っている場合、中心結論を再現できない場合、合意した目的から構成が外れ理由もない場合は、書き直します。

各工程にゲートを置き、失敗を公開工程へ持ち越さず、原因となった工程へ戻します。

戻す優先順位：

事実の誤りを最初に修正または削除します。次に、読者がコピーする可能性のあるコードの誤りを直します。構成ずれと内部リンク不足は優先度が低くても、公開前に解決します。

関連記事

まずAIへプロジェクトの文脈を渡したい場合は、CLAUDE.mdでAIのコーディングを正確にする方法を参照してください。執筆やレビューを再利用可能な工程へ分ける場合は、Claude Code Skillでワークフローをまとめる方法が参考になります。

一般的なコンテンツ制作者向けには、AIライティングのワークフローもあります。そちらは効率を中心に扱い、このページは技術的な事実、実行証跡、公開ゲートを中心に扱います。目的に応じて組み合わせられます。