ある日、自分の記事に裏切られた
数年前に自分が書いた記事を、後輩に紹介したことがある。「これ読めば環境構築できるよ」と。
数時間後、後輩から連絡が来た。「手順通りにやったんですが、エラーになります」。
見てみると、記事中で使っていたライブラリがメジャーバージョンアップしていて、APIが変わっていた。コード例はコピペしても動かない。記事の内容そのものは間違っていない。ただ、書いた時点では正しかっただけだ。
私は6年ほどフルスタックエンジニアとしてやってきて、個人ブログでTypeScriptやWordPressについての記事を書いてきた。そして気づいたことがある。技術記事というのは、生鮮食品に近い。公開した瞬間がいちばん新鮮で、そこからゆっくり腐っていく。しかも、見た目では腐っていることがわからない。
「正しかった記事」が一番タチが悪い
嘘が書いてある記事なら、まだいい。読めばどこか怪しいと気づける。
タチが悪いのは、かつて完全に正しかった記事だ。丁寧に書かれていて、スクリーンショットもあって、はてブもたくさんついている。信頼するに足る見た目をしている。でもNext.jsのバージョンが2つ上がった今、そのコードは動かない。
読者は動かない原因が「自分の環境のせい」だと思い込み、数時間を溶かす。私自身、何度もやられた。そして申し訳ないことに、加害者側にもなっていた。冒頭の後輩の件がそれだ。
書き手を責めたいわけではない。記事を書いた後も永遠にメンテナンスし続けるのは、無償の個人活動としては現実的に無理がある。問題は個人の怠慢ではなく、**「記事の鮮度を保つ仕組みがどこにもない」**という構造のほうにある。
行政システムの現場で学んだ「動く証明」の重さ
私は自治体向けのシステム開発に関わってきた。この世界では「たぶん動きます」は通用しない。納品のたびに動作確認のエビデンスを揃え、検収を通す。動くことを、テストと記録で証明して初めて話が前に進む。
技術的リテラシーが異なるステークホルダーに説明するときも同じだった。「コードがきれいです」は伝わらないが、「この操作をすると、この結果になります。毎回、必ず」は伝わる。動くという事実は、最強のドキュメントなのだ。
ある日ふと思った。この考え方、技術記事に持ち込めないだろうか。
記事の文章がどれだけ丁寧かではなく、「この記事のコード例は、今日時点のCIでテストが通っています」と機械的に証明されていたら。読者は安心してコピペできるし、書き手は「腐ったら気づける」ようになる。
だから、記事にCIを付けた
その発想で、私は個人プロジェクトとして「記事のコード例が今も動くことをCIで証明する」仕組みを作りはじめた。
やっていることは単純だ。
- 記事のフロントマターに、対応するテストコードのパスとテストコマンドを書く
- GitHub Actionsが定期的にそのテストを実行する
- 結果を記事側に書き戻し、読者に「鮮度スコア」として表示する
記事側のフロントマターは、たとえばこんな具合だ。
tested_path: tests/articles/nextjs-app-router.test.ts
test_command: pnpm vitest run
verified_status: passing
last_verified: 2026-07-18
CIはこの tested_path と test_command を読んでテストを実行し、結果を書き戻す。読者から見える記事には、この結果がバッジとして表示される。
テストが落ちれば、記事には「このコード例は現在動作しない可能性があります」と表示される。書き手には修正のシグナルが飛ぶ。記事が自分で「腐りました」と申告してくれるわけだ。
作ってみて実感したのは、これは技術の問題というより文化の問題だということだった。私たちはコードには当たり前にCIを付けるのに、コードについて書いた文章は書きっぱなしにしてきた。コードとドキュメントを別物として扱ってきたツケが、「動かない記事の山」として積み上がっている。
きれいごとだけでは、終わらなかった
とはいえ、作ってみて痛感した限界も正直に書いておきたい。
まず、テストを書くコストは重い。記事を書くだけでも大変なのに、そのコード例のテストまで書くのか、という話だ。すべての書き手にこれを求めるのは非現実的で、だからこそ「仕組み側で書き手の負担を最小化する」設計が要る。フロントマターに2行足すだけで済むようにしたのは、そのためだ。
次に、CIが通ることと記事が正しいことは、イコールではない。検証できるのはあくまでコードだけで、「この設定画面のスクショが古い」「説明文中のバージョン表記が古い」といった劣化は検出できない。鮮度スコアが緑でも、文章は腐っていることがある。これは今のところ、書き手の良心に頼るしかない。
そして、環境の再現性という深い沼がある。CI上のNodeのバージョン、OSの差異、依存パッケージのロックをどこまで固定するか。厳密にやるほど「読者の手元の環境」から乖離していく。「CIでは通るのに私の環境では動かない」が起きたら本末転倒だ。
それでも、と思う。完璧な検証は無理でも、何も検証しないよりは圧倒的にマシだ。テストカバレッジ100%が無理だからといって、テストを1行も書かない理由にはならないのと同じで。
記事は「書き捨て」から「育てる資産」へ
レガシーコード改善の名著『Working Effectively with Legacy Code』には、「テストのないコードはレガシーコードだ」という有名な定義がある。
これを借りるなら、こう言えると思う。
「検証の仕組みがない技術記事は、公開した瞬間からレガシー記事である」
もちろん、すべての記事にテストを付けるべきだとは思わない。考察やポエムに鮮度はないし、この記事自体もそうだ。でも「手順を示す記事」「コード例が主役の記事」については、書きっぱなしにしない選択肢があっていい。
小さくできることはある。記事に「動作確認した日付とバージョン」を明記する。コード例をGistやリポジトリに置いて、更新可能な状態にしておく。それだけでも、読者が溶かす時間はずいぶん減る。
私たちが記事を書くのは、未来の誰かの時間を節約するためだ。だとしたら、その記事が未来でも動くかどうかに、もう少しだけ責任を持ってもいい。
自分の記事に裏切られたあの日から、私はそう考えるようになった。
記事のコード例をCIで検証する仕組みは、plainmark としてオープンソースで開発中です。WordPressテーマ+プラグインのモノレポで、記事のフロントマターに書いたテストをGitHub Actionsが定期実行し、結果を「鮮度スコア」として読者に表示します。同じ問題意識を持っている方がいたら、ぜひコメントやIssueで教えてください。
