AIにドキュメントを書かせたら、勝手にLinuxで動作確認を始めた

「このリポジトリを読んで、日本語のドキュメントにしてください」

Claudeに頼んだのは、それだけだった。

ところが返ってきたドキュメントには、コードから読み取った仕組みや起動手順だけでなく、Linux環境でGlyphaを実際に動かした結果が書かれていた。テストを通し、レンダラーをビルドし、コンテンツをアップロードし、日本語が表示できるところまで確認されていた。

ドキュメントを書いてもらうつもりだったのに、AIが先にソフトウェアを使い始めた。

この記事では、そのとき何が起きたのかを、生成されたドキュメントから確認できる事実に絞って振り返る。そして、そこから生まれた「AIエージェントは、ソフトウェアの最初の利用者になれるのか」という問いについて考えたい。

題材にしたGlypha

Glyphaは、GoとTypeScript/PixiJSで作った実験的なデジタルサイネージである。

コンテンツは、画面に出す文字や画像、時刻ごとの切り替えを定義したJSONとして作る。それをHTTP APIへ送ると、サーバーが内容を検証し、ブラウザのレンダラーが表示する。

Glyphaでは、AIエージェントがコンテンツを作成・更新することも想定している。ただし、AIに細かな操作手順を強制する設計ではない。代わりに、システム側が入力を厳密に検証する。

たとえば、文字が指定した矩形からはみ出す、存在しない画像を参照する、フォントにない文字を使う、といったコンテンツは理由つきで拒否される。失敗した入力が、それまで正常に表示されていた画面を上書きすることもない。

自分はこの考え方を「自由にさせるための制約」と捉えている。詳しい設計の話は前回の記事に譲るが、今回の実験は、図らずもその考え方をドキュメント作成側から試すものになった。

頼んだのは、日本語のドキュメントだった

GlyphaではAIによるドキュメント生成も試したかったため、開発時の文書を意図的に英語で用意していた。そこでClaudeにGitHubリポジトリのURLを渡し、次のように依頼した。

https://github.com/kuny/glypha
昨日作ったやつですが、このコードとレポジトリAIの実験も兼ねて
わざと日本人が読みにくいように英語で作っています。
まずはこのプログラムをローカルで動かす想定をしています。
このレポジトリを読んで、このコードの説明、仕組み、
動かす手順を日本語のドキュメントにしてください。

このプロンプトでは、Linuxで動かすようには指定していない。テストを実行するようにも、サンプルコンテンツをアップロードするようにも頼んでいない。

期待していたのは、英語のREADMEや設計文書、ソースコードをもとにした日本語の解説だった。

生成されたのは「説明」だけではなかった

完成した「Glypha 解説ドキュメント」は、概要、内部構造、Dockerとホスト環境での起動方法、コンテンツの作り方、環境変数、よくあるつまずきまで含む文書になっていた。

ここまでなら、詳しいリポジトリ解説の範囲ともいえる。予想外だったのは、ホストで直接動かす手順に次の記述があったことだ。

この手順はこちらの検証環境（Linux、Go 1.26.0）で実際に最後まで通し、テスト全合格・アップロード成功・/display が closed シーンを返すことを確認しています。なお Node 22 でもビルド自体は通りました。

さらに、コンテンツの説明には「いらっしゃいませ」という日本語へ差し替えて受理されたことまで記録されていた。

つまりClaudeは、ソースコードを読んでもっともらしい手順を組み立てただけではない。少なくとも生成された文書からは、Linux環境で次の結果を確認したことが分かる。

• Goのテストがすべて通った
• TypeScript/PixiJSのレンダラーをビルドできた
• Glyphaを起動し、コンテンツをアップロードできた
• GET /displayから期待したシーンを取得できた
• 日本語を含むコンテンツが検証を通った
• Node.js 22でもビルドできた

ただし、ここは慎重に区別したい。今回はClaudeの詳細な作業ログを保存していない。そのため、どの順番で何を考え、どのコマンドを実行したのかまでは断定できない。確認できるのは、生成された文書が検証環境と結果を明示していること、そして依頼したプロンプトにはLinuxでの動作確認を含めていなかったことだ。

「試した人」にしか書きにくい情報

生成された文書で印象的だったのは、正常系の手順だけではなく、利用者がつまずきそうな点が整理されていたことである。

たとえば、次のような注意がある。

• サーバーはリポジトリのルートから起動する。別の場所から起動すると、相対パスで探すフォントやビルド済みファイルが見つからない可能性がある
• 本番構成と開発構成は同じ8080番ポートを使うため、同時には起動できない
• /display が 204 No Content なら、表示の故障ではなくコンテンツがまだ公開されていない
• 画面が初期表示のままなら、アップロードの未実施だけでなく、ブラウザ側の描画失敗も確認する
• Node.js 24が指定されている一方、検証環境ではNode.js 22でもビルドできた

一方で、試していない範囲も隠していない。

こちらの検証環境では Docker デーモンが使えなかったため、方法 A は README に基づく手順で、実行確認はしていません。

これは重要な記述だと思う。「Dockerならこの手順です」と書くことと、「Dockerで実際に確認した」と書くことを分けているからだ。

後から作成を依頼したAIエージェント向けの操作ガイド「Glypha を AI エージェントで動かす」でも、同じ姿勢が見られた。JSONと画像を実際にアップロードして、HTTP 200が返り、日本語が表示された例は検証済みと明記する一方、Claude CodeやCodexとの対話そのものはその環境では試していない、と書かれている。

さらに「Glypha に Playwright を導入する（macOS / Windows WSL）」では、Linux環境で4本のテストが通り、Playwright MCPでスクリーンショットを撮れたことを記載しつつ、macOSとWSLの実機では未検証であることも明示していた。

この「どこまで確かめ、どこからは資料に基づく説明か」という境界は、技術文書の信頼性を大きく左右する。少なくとも今回の生成物は、すべてを検証済みであるかのようには扱っていなかった。

翻訳ではなく、利用体験の再構成だった

今回作られた文書は、既存の英語文書を日本語へ置き換えただけのものではない。

リポジトリ内の情報を、利用者がたどる順序に並べ直している。まず何を用意し、どこでコマンドを実行し、どの応答なら成功で、失敗したらどこを見るのか。コードの構造説明も、単なるファイル一覧ではなく、アップロードされたコンテンツが検証・保存・表示される流れとして構成されていた。

そこへ実行結果が加わったことで、文書は「コードから推測した説明」から「少なくとも一つの環境で通った利用手順」に変わった。

これは、ドキュメント生成におけるAIエージェントの役割を少し違って見せる。

文章を書く前に、対象を使ってみる。動かなければエラーを読む。動いた範囲と動かせなかった範囲を分ける。そして、その経験を利用者の手順へ戻す。

人間のテクニカルライターや開発者なら自然に行うことだが、今回Claudeも結果としてそれに近い仕事をしていた。

目的を伝え、調べ方を任せる

今回、人間が与えたのは「日本語で、コードの説明・仕組み・動かし方をまとめてほしい」という目的と成果物のイメージだった。調査の手順までは指定しなかった。

それでも、生成物には実行確認が含まれた。

ここから「AIには細かい指示が不要だ」と一般化するのは早い。リポジトリの状態、利用できる実行環境、権限、モデル、依頼の書き方によって行動は変わる。今回は作業ログも残していないため、ClaudeがなぜLinuxでの確認を選んだのか、その判断過程も分からない。

ただ、一つの協働方法は見えたように思う。

人間は、達成したい目的、成果物の読者、守るべき境界を伝える。そのうえで、リポジトリを読む、テストする、起動する、結果を比較するといった調査方法には余白を残す。AIエージェントがその余白を使える環境なら、人間が最初から全手順を設計するよりも、目的に必要な確認を自ら組み立てる可能性がある。

もちろん、任せっぱなしにはできない。今回のように、実行済みと未実行を分けて読むこと、外部公開やデータ削除のような操作には明確な制限を置くこと、重要な主張にはログやテスト結果を残すことが必要になる。

Glyphaの設計思想と、今回起きたこと

Glyphaは、AIエージェントへ自由な操作を許す一方で、受け入れてよい状態をシステム側で制限するように作った。

AIが生成したコンテンツに問題があれば、APIが具体的なエラーを返す。AIはそれを読んで修正できる。正しいものが完成するまで、現在の表示は壊れない。操作を一手ずつ教えるのではなく、越えてはいけない境界をソフトウェア側に持たせる設計である。

今回のドキュメント作成も、それに似た形になった。人間は目的を示し、詳細な探索手順は固定しなかった。その結果、Claudeは文書を書くために必要な確認まで作業範囲を広げた。

これは一度の実験であり、AIがソフトウェアを「理解した」とまでは言えない。それでも、コードを説明するだけでなく、利用者としてソフトウェアに触れ、その結果を文書へ反映したことは観察できた。

AIエージェントは、最初の利用者になれるか

新しいソフトウェアの最初の利用者は、たいてい開発者自身である。そのため、前提知識のない人がどこで迷うかを見落としやすい。

もしAIエージェントに、実装が終わった段階で「初めて使う人向けの文書を作ってほしい」と依頼し、実際に隔離環境で起動・操作・検証までさせたらどうなるだろう。

AIは、ドキュメントの執筆者であると同時に、最初の利用者、スモークテストの実行者、分かりにくい前提を見つける観察者にもなれるかもしれない。

今回分かったのは、その可能性があるというところまでだ。再現性を確かめるには、次は作業ログを保存し、人間が書いた文書との比較や、異なる環境での再実行も必要になる。

それでも、最初の依頼からは想像していなかった問いが残った。

AIエージェントを、ソフトウェアの最初の利用者として開発プロセスに組み込めるのではないか。

ドキュメントを書かせるという実験は、いつの間にか、誰に最初にソフトウェアを使ってもらうかという実験に変わっていた。

関連記事