2026年4月21日、freeCodeCampがPHPとJSON-LDで自動ナレッジグラフを構築するチュートリアルを掲載した。6つの実装ステップ、本番コード、データベースクエリを含む3,000語の技術記事だ。記事内のすべてのPHPコードはClaudeをコーディングパートナーとして書いた。そしてすべての行が公開前に人間の編集レビューを通過した。

ドラフトから公開までのプロセスが、AIでコードを書くことに対する考え方を変えた。コードが間違っていたからではない。すべての関数を編集者に対して説明するプロセスが、構築しただけでは到達できなかったレベルの理解を強制したからだ。

構築と説明の間のギャップ

shinobis.comの機能を構築するとき、ワークフローは速い。必要なものをClaudeに説明する。ClaudeがPHPを書く。テストする。動けばデプロイする。動かなければ問題を説明し、Claudeが修正する。6ヶ月で、JSON-LD自動化、コンテンツネゴシエーション、AIレーダー、ジェネレーティブアイデンティティ画像、2つの公開ツールを備えた3言語ブログを構築した。すべてバニラPHPと共有ホスティングで。

しかし構築と説明は異なるスキルだ。freeCodeCampのチュートリアルを書き始めたとき、各関数が何をするかを大まかに説明できることに気づいた。なぜそのように実装されているかは説明できなかった。なぜシステムはネストされたオブジェクトではなく@graph配列を使うのか。なぜpublisherはPersonではなくOrganizationなのか。なぜエンティティ検出はregexパターンではなくstrposを使うのか。

Claudeが実装中にそれらの決定を下していた。出力が動いたので受け入れていた。チュートリアルを書くことで、すべての決定を問い直すことを余儀なくされた。

Claudeのドラフトから削除したもの

最初のドラフトにはClaudeが提案し、最初は残した セクションが含まれていた。5つのCMSプラットフォームにおけるJSON-LDフォーマットの比較表。Schema.orgの語彙階層に関するセクション。RDFa対Microdata対JSON-LDの議論。

すべて技術的に正確。すべてチュートリアルには無関係。「自動ナレッジグラフの構築方法」というfreeCodeCampの記事を開く読者は、構造化データフォーマットの歴史の授業を必要としない。コードが必要だ。比較表はAIがスペースを埋めるために生成する種類のコンテンツだった。包括的で、よく整理されていて、不要だ。

これらのセクションを削除して800語を削減し、チュートリアルをより簡潔にした。生き残ったすべての段落は一つの質問に答えなければならなかった。これは読者がシステムを実装するのに役立つか？答えがノーなら、削除した。

Claudeが提案しなかったもので追加したもの

AI生成ドラフトになかった3つのものが最終記事に入った。

第一に、本番環境で3ヶ月後に学んだことに関するセクション。Claudeにはこのセクションを書くことができない。3ヶ月の本番データを持っていないからだ。abstractプロパティの追加がLLM処理に即座に影響を与えたという洞察、citationとrelatedLinkが知識関係を異なる方法で示すこと、publisherをOrganizationとして定義することで信頼シグナルが増加すること。これらは実際のブログでの実際の動作を実際の時間にわたって観察することから生まれた。

第二に、図表だ。記事にはパイプラインアーキテクチャ、静的JSON-LDとグラフベースJSON-LDの違い、@graphエンティティの接続、注釈付き出力を示す4つの図が含まれている。Claudeは視覚的な補助を提案しなかった。10年のUXデザインが、技術的な概念は構造を見ることができるとき、読むだけより速く理解されることを教えてくれたから追加した。

第三に、テスト方法論だ。元のドラフトは実装で終わっていた。Google Rich Results Testで出力を検証し、AIモデルでスキーマを監査するセクションを追加した。JSON-LDをChatGPTに貼り付けてスコアを求めるという推奨は、自分自身のプロセスから来た。実行して8.7を取得し、改善して9.1を得た。そのビフォーアフターはnon-commodityコンテンツだ。

編集プロセス

freeCodeCampには編集レビュアーがいる。記事はAbbeyに割り当てられた。レビューは形式的なものではなかった。技術的な主張に疑問を呈した。JSON-LDにおけるaboutとmentionsの違いについて明確化を求めた。説明が読者が持っていないかもしれない知識を前提としているセクションを指摘した。

すべての編集コメントが、コードに戻って検証することを強制した。動くかどうかの検証ではない。なぜ動くかを説明できるかどうかの検証だ。違いがある。関数を実行して正しい出力を見ることは、コードが機能的であることを証明する。別の人にその関数がなぜそのように構造化されているかを説明することは、理解していることを証明する。

Abbeyの質問の3つが、自分の実装について気づいていなかったことを発見させてくれた。json_encodeのフラグ（JSON_UNESCAPED_SLASHESとJSON_UNESCAPED_UNICODE）はClaudeが入れたからコードにあった。疑問に思ったことはなかった。Abbeyがなぜ重要かと聞いたとき、それらなしで何が起こるかテストした。アクセント付きのスペイン語タイトルがJSON-LDブロック全体をサイレントに壊した。スラッシュ付きのURLが読めない文字列にエスケープされた。それらのフラグは装飾ではなかった。3言語ブログの実際のバグを防いでいた。

AIを使うこととコードを理解することの境界線

Claudeの出力をfreeCodeCampの投稿フォームに貼り付けて承認を待つバージョンのこの話がある。そのバージョンは拒否される。コードが間違っているからではなく、説明が浅いからだ。AI生成チュートリアルには特有のテクスチャがある。個人的な洞察なし、本番データなし、著者がサンドボックスの外でコードを実行したことがあるという証拠なしで、予測可能なパターンに整理された正確な情報だ。

公開されたバージョンが異なるのは、AIにできない仕事をしたからだ。3ヶ月間本番でシステムを運用した。異なるAIモデルがスキーマにどう反応したか観察した。実際のフィードバックに基づいて変更した。技術的に正しいが編集的に間違っているセクションを削除した。プロンプティングからではなく経験から来たセクションを追加した。

AIを使ってコードを書くことは、コードを理解することと同じではない。しかしAIを使ってコードを書き、その後すべての行を人間の編集者に説明することを強制されることは、他のどの方法よりも速くそのギャップを埋める。編集プロセスはフィルターではなかった。学習の加速装置だった。

公開後に変わったこと

記事は4月21日から公開されている。3つの測定可能なことが起きた。

第一に、freeCodeCampからのバックリンク。技術出版空間で最も高いドメインオーソリティの一つだ。ドメインレーティング3.2のブログにとって、freeCodeCampからの一つのdofollowリンクは小さなサイトからの数十のリンクよりも価値がある。

第二に、驚いたコメント。「ソースコードを共有できますか？」と聞かれた。ソースコード全体がチュートリアルにステップバイステップである。しかし読者はプロジェクトにドロップできる一つのファイルを求めていた。

第三に、これが最も重要だ。AIを使ってコードを書くデザイナーとして自分を考えるのをやめた。AIでソフトウェアを構築し、構築されたものを理解する人として考え始めた。この区別は意味論的ではない。何をデプロイする意思があるか、デプロイ前に何を疑問視するか、自分の仕事をどう説明するかを変える。

AIで公開したい人に伝えたいこと

AIの出力を提出するな。AIの出力に対する自分の理解を提出せよ。違いがすべてだ。

すべての関数を読め。構文エラーをチェックするためではない。それが表す決定を説明できるかどうかをチェックするためだ。関数がなぜpreg_matchではなくstrposを使うのか説明できないなら、そのコードについてチュートリアルを公開するのに十分な理解がない。

AIが包括的であるために追加するセクションを削除せよ。AIは完全性がデフォルトモードなのでスペースを埋める。読者に役立たないものをすべて切るのがあなたの仕事だ。

自分だけが追加できるものを追加せよ。本番データ。ビフォーアフターの数字。下した決定とその理由。発見したミス。AIは経験を製造できない。チュートリアルに経験が含まれていないなら、それは実際のデータで同じチュートリアルを書く次の人に追い越されるコモディティコンテンツだ。

そして編集者を見つけよ。AI編集者ではない。まだ答えられない質問をしてくれる人間だ。その質問が学びの場だ。

チュートリアルはfreeCodeCampで公開中: How to Build an Automatic Knowledge Graph for Your Blog with PHP and JSON-LD