Claudeで社内APIドキュメントを自動生成する方法

要点： まずコードベースから決定的な方法でルート一覧を抽出し、そのうえでClaudeにはその端点だけを説明させます。パラメータ、レスポンス、エラーの意味づけ。そしてマージのたびにCIで再生成します。実在する一覧にモデルを縛ることが、存在しない端点をでっち上げさせない鍵です。初回の実行では、まだ公開されているとは誰も知らなかったものが出てくると考えてください。

どの開発チームにも同じ文書があります。サービス開始時に丁寧に書かれ、五週間ほどは正確で、いまでは存在しない三つの端点を説明し、その後に追加された十一を落としています。誰も信じないので誰も更新せず、さらに腐っていきます。新しく入った人はソースを読みます。その文書が防ぐはずだったことです。

この腐敗は文化ではなく構造の問題です。文書はひとつのシステムに住み、変更は別のシステムで起き、両者をつなぐのは差分に気づいた誰かだけです。これはまさに、機械的で、文脈量が多く、判断の少ない、言語モデルが得意な仕事です。ただしモデルが主張してよい範囲を縛るという条件つきで。

なぜ社内APIドキュメントは真っ先に腐るのか

社内向けは対外向けより速く腐ります。理由を名指ししておく価値があります。それぞれが自動化の形を決めるからです。

外圧がない。 対外APIのドキュメントが間違っていれば顧客が困ります。社内APIなら困るのは同僚で、その同僚は歩いてきて質問し、回避策はドキュメント修正ではなく口伝の部族知識になります。

書いた人がいなくなる。 社内サービスは一人か二人が全体像を頭に入れて書くことが多い。その人が異動すると、ドキュメントは共有理解の要約ではなく唯一の記録になります。しかも誰も保守していない、まさにその瞬間に。

ドキュメントが完了の定義に入っていない。 マージにはテストとレビューが要りますが、ドキュメント更新が要ることはまれです。設計上、常に一歩遅れます。

本当の端点数を誰も知らない。 サービスにはデバッグ用ルート、社内管理用パス、誰かが拡張したヘルスチェック、廃止予定のまま消されなかった機能の端点が溜まります。人の記憶から始まるドキュメント作業は、不完全な一覧から始まります。

最後の点が肝心で、解決策の形を変えます。目的は文章を速く書くことではありません。端点の一覧をコード自体から導き、誰も覚えていないものを文書が黙って落とせないようにすることです。

Claudeはコードベースから実際に何を生成できるのか

端点リファレンス、例、エラーの意味づけ

ルートハンドラとそれが触れる型を与えれば、モデルは記述層を安定して出力します。その端点が何のためのものか、各パラメータの意味、現実的なリクエストとレスポンスの形、そしてコードが実際に返しうるエラー。分量でいえばAPIリファレンスの大半であり、技術者が最も書きたがらない部分です。

手書きドキュメントが飛ばしがちな結合組織も得意です。どの端点がどの認証を要求するか。ページングの規約は何か。どのフィールドがどんな条件でnullになりうるか。ある操作は冪等か。いずれもコードから読み取れますが手作業でまとめるのは面倒で、これらの欠落こそが、技術的には完全で実用上は役に立たないリファレンスを生みます。

正直な限界が二つ。第一に、モデルが説明するのはコードが何をするかであって、何をすべきかではありません。実装が意図した契約と食い違っていれば、あなたが得るのはそのバグのドキュメントです。第二に、書かれていない業務文脈は知りようがありません。なぜそのフィールドがあるのか、どの利用側がその妙な挙動に依存しているのか、設定フラグのせいで本番ではそのパラメータが無視されていること。これらは今も人から来ます。

正とすべきはコードか、仕様か、両方か

多くのフレームワークは注釈や型定義からOpenAPI仕様を出力できます。その機械生成の仕様は、モデルにファイルを読ませるよりはるかに良い土台です。構成上網羅的であり、存在しないルートを幻覚できません。

なので両方を、順序を決めて使います。仕様を決定的に生成または抽出し——フレームワークの注釈から、あるいはルータ定義を解析して——それを端点とその形の正典として扱います。そのうえで関連するハンドラのコードと一緒にモデルへ渡し、説明、例、文章を求めます。モデルは肉付けをする役で、列挙はしません。

この順序がパイプライン全体で最も重要な設計判断です。「このリポジトリのドキュメントを書いて」と言われたモデルは、存在しないのにもっともらしい端点を出します。そしてそのもっともらしさこそ、レビューで見つけにくくしている当のものです。「この十四の端点を説明し、コードが不明瞭ならそう言え」と言われたモデルは、回避しようのない事実の内側で作業しています。

現実的なパイプライン——生成、レビュー、公開、再生成

まず、メインブランチへのマージのたびにルート一覧を抽出します。フレームワークの機能、ビルド時の仕様生成器、ルータ定義を解析する小さなスクリプト。決定的でありさえすれば何でも構いません。この成果物が契約です。

前回分と差分を取ります。ほとんどのマージは関係する部分を変えないので、変わったところだけ文章を再生成すればコストとレビュー負荷が釣り合います。新しい端点、シグネチャの変更、削除されたルートは作業を生みますが、インターフェースに触れないリファクタリングは生みません。

変わった端点ごとに、仕様の該当項目、ハンドラのソース、参照している型、そして既存の説明があればそれもモデルに渡します。人が書いた記述が今も正確ならそれを残し、コードと合わなくなっていれば印をつけるよう求めてください。上書きさせてはいけません。さもないと丁寧に書かれた説明が次の実行のたびに凡庸な文章へ置き換わり、チームは書くのをやめます。

そして直接公開せず、レビューを通して公開します。パイプラインは生成物を無人でコミットするのではなく、ドキュメント用リポジトリやwikiへプルリクエストを出すべきです。安価に人を輪の中に残せますし、通読すべき文書ではなく眺めるべき差分が手に入り、まずい生成は公開された誤りではなく却下されたPRになります。文書がどこに置かれるかより、それが記憶ではなく生成によって作られていることのほうが重要です。同じ原則はClaudeでConfluenceの文書を同期するでも扱っています。

AI生成ドキュメント vs 仕様ファーストのツール vs 手書き

• 網羅性 — 仕様ファーストの圧勝。構成上すべてのルートを記録します。モデル単独は見せられたものだけ、手書きは誰かが覚えていたものだけを記録します。
• 読みやすさと有用性 — AI生成の勝ち。素のOpenAPI表示はそのフィールドが文字列だと教えます。役に立つ版は、何を入れるべきで間違えると何が起きるかを教えます。
• 端点一覧の正確さ — 仕様ファーストの勝ちで、これが最も重要です。一覧の出どころをモデルにしてはいけません。
• 最新であり続けること — 仕様ファーストとAI生成はどちらも手書きに勝ちます。自動で再生成されるからです。手書きは一度だけ正確です。
• 意図と業務文脈の記録 — 手書きの勝ち。なぜその端点があり、どの利用側がその癖に依存しているかはコードにありません。
• 導入の手間 — 短期では手書き、フレームワークが対応していれば仕様ファーストは中程度、CI連携とレビュー導線を備えた本格的なAIパイプラインが最大の投資です。

機能する組み合わせは三つ全部です。一覧は仕様ファースト、説明はAI、意図は人。そしてパイプラインは人の記述を踏み潰さず保存すること。

これが暴くもの——そしてそれこそが本当の価値である理由

この種のパイプラインの初回実行は、たいてい生成されるドキュメントより興味深いものになります。

誰も覚えていない端点。 二年前の障害対応で残ったデバッグ用ルート、一度きりの移行のために足した管理用パス、v2の公開時に廃止されるはずだったv1。どれも生きていて到達可能な露出面です。

欠落した、あるいは一貫しない認証。 どの端点がどの検査を強制しているかをまとめる作業は、まさにミドルウェアが当てられていないハンドラを浮かび上がらせます。悪意であることはまれで、たいていはルートをガードの外へ動かしたリファクタリングです。

例やフィクスチャに紛れた秘密情報。 例示リクエストを生成するモデルは見せられたものを下敷きにします。テストフィクスチャは本物らしいトークンだらけで、ときどき本物です。公開前に生成物を認証情報のパターンで走査し、見つかったものは即座に更新すべき生きた秘密として扱ってください。

書かれていない「社内限定」の前提。 「社内ネットワークからしか届かないから」安全とされる端点。それは誰かが三回のアーキテクチャ変更前にネットワーク構成について述べた判断です。

忘れられた、認証されていないかもしれない端点の一覧に対する誠実な応答は、wikiページではありません。本当に到達できるのか、何を露出しているのかを試すことであり、それがペネトレーションテストの役割です。ドキュメントは何を持っているかを教え、安全かどうかを教えるのは試験だけです。「誰も覚えていない端点が四十個見つかった」は、実施を決める理由としてかなり良いほうです。

正しく進めるために——ソースコードの機密、APIキー、ITに任せる範囲

専有ソースコードを第三者のモデルへ送ることは手続きではなく実際の判断であり、その場の技術者個人の判断ではなく、意識的な答えに値します。

使っている階層に適用される条件を読んでください。商用およびAPI階層は保持と学習利用について消費者向け製品と異なるのが普通で、条件は変わるので、同僚の記憶ではなく最新のドキュメントで確認します。そのうえで範囲を決めます。アプリケーションコードを送ることには納得できても、顧客データのフィクスチャ、暗号鍵素材、顧客との守秘条項の対象となるコードを含むリポジトリからは断じて送らない、と結論する組織は多くあります。その境界を書き出してください。書かなければ、各技術者が個別に判断することになります。

仕組みの面も重要です。このパイプラインはCI上にリポジトリのトークンとモデルのAPIキーを必要とします。対象リポジトリに限定した、短命で最小権限の資格情報を使い、設定ファイルではなくCI提供元のシークレットストアに保管し、実際に担当者のいる周期で更新してください。組織全体への読み取り権限を持つ生成パイプラインは、それ自体が無視できない攻撃面です。AI+サポートはこの種のツールを最初から統制付きで構築することを支援し、管理型ITサポートは複数のチームが依存するようになったあとのID、アクセス、秘密情報のライフサイクルを引き受けます。Brocentは2007年の北京での創業以来アジアで管理型ITを提供しており、本社はシンガポール、2016年から香港オフィスを構えています。

よくある質問

専有ソースコードをAIモデルに送っても安全ですか？

階層とコード次第であり、技術者ごとの判断ではなく文書化された決定であるべきです。自社のプランについて提供元の現行条件が保持と学習利用をどう定めているかを確認し、どのリポジトリが対象になりうるかに明示的な境界を引いてください。アプリケーションのロジックと、認証情報や顧客データのフィクスチャ、顧客との守秘義務の対象コードを含むリポジトリとは、まったく別の問いです。

存在しない端点を幻覚しませんか？

列挙させれば、します。だからルート一覧は決定的な抽出——フレームワークの仕様生成か、ルータ定義の解析——から来なければならず、モデルの仕事はその一覧の項目を説明することに限定されます。こう縛れば、端点の捏造は現実的な失敗様式ではなくなります。

ドキュメントをコードと同期させ続けるには？

スケジュールや手作業ではなく、CIでマージ時に再生成を起動します。抽出した仕様の差分を取り、変わった分だけ再生成し、レビュー用にプルリクエストを出します。誰かが実行を覚えていなければならない仕組みは、一四半期のうちにずれます。

誰も記録していなかった端点が見つかったらどうしますか？

文書化ではなく振り分けから始めます。それぞれについて、まだ使われているか、どの認証を強制しているか、何を露出しているかを確かめます。死んでいるものは消し、生きているものは固め、そのうえで書きます。認証のない忘れられた端点を文書化することは、それをより分かりやすく公開するだけです。

技術者が書いた説明を上書きしませんか？

そう作った場合だけですが、それは定着を殺す失敗です。既存の説明を文脈として渡し、正確な人の記述は残し、コードと合わなくなった箇所に印をつけ、欠けている部分だけを足すよう指示してください。自分の説明が凡庸な文章に置き換わるのを見れば、技術者は書くのをやめます。

これはOpenAPI仕様の代わりになりますか？

なりません。むしろ仕様に依存します。仕様はクライアント生成やテストも駆動する、正典の機械可読な契約です。このパイプラインはその上に人間向けの層を足すもので、そこは素の仕様表示が不得意な部分です。

まずどこから

サービスをひとつ選んでください。できれば不満の声が上がっている中規模の社内サービスがよいでしょう。そのルート一覧を決定的に抽出し、既存のドキュメントと突き合わせます。たいていはこの比較そのものが、この取り組みに予算がつく瞬間になります。次に、振り分けを生き延びた端点の説明を生成し、再生成をプルリクエスト経由でCIに組み込み、他のリポジトリへ広げる前に資格情報の範囲を決めてください。初回の実行で誰も説明できない端点が出てきて、推測ではなく実際に何を露出しているのかを知りたいなら、お問い合わせください。