社内の開発ドキュメントやREADMEに貼るサンプルコードに、「TODO(developer): ここを書き換えてください」というコメントを入れていないでしょうか。
この書き方は長年、技術文書の定石でした。しかし生成AIを使ったコーディング支援ツールやAIエージェント（人の指示をもとに自律的にコードを生成・実行する仕組み）がコードを読み書きする時代になり、事情が変わってきています。社内ドキュメントの整備やAPIサンプルの提供を担当するエンジニア、DevRel（開発者向け情報発信）担当者に向けて、TODOコメントを残すべきか、別の書き方に切り替えるべきかの判断材料を整理します。
なぜこの判断が必要になるのか
TODOコメント付きのサンプルコードは、人間の読者であれば「ここは自分の環境の値に差し替える場所」だと直感的にわかります。
# TODO(developer): Uncomment and set your instance
# instance_id = "your-instance-id"
client = storage.Client(instance_id)このコードは、コピー&ペーストしてそのまま実行するとinstance_idが未定義でエラーになります。技術文書の世界ではこれを「copy-paste-completable（コピペ後に手直しが必要な）パターン」と呼びます。
問題は、このサンプルをAIコーディングアシスタントやAIエージェントに読み込ませたときです。AIはコメントアウトされた行をそのまま再現したり、instance_idの値を推測で埋めてしまったりすることがあります。後者は、存在しないリソースIDや架空のAPIキーを生成する「ハルシネーション」の一種です。結果として、人間が生成済みコードを手作業でデバッグする羽目になります。
Claude CodeやGitHub Copilot、CursorのようなAIコーディングツールを日常的に使っているなら、この挙動は見覚えがあるはずです。社内Wikiやドキュメントサイトのコード例をAIに読ませて雛形を作らせたとき、TODOコメントごと出力されて困った経験があれば、まさにこの問題に該当します。
判断軸を整理する
TODOコメントを維持するか、別の書き方に切り替えるかは、以下の軸で検討できます。
初回実行の成功率という軸がまず重要です。サンプルコードをそのまま実行したときに、文法エラーで落ちるのか、認証エラーのような分かりやすい失敗で止まるのかには大きな差があります。前者は「どこを直せばいいか」が読者にもAIにも伝わりません。後者なら「APIキーが未設定」という明確な手がかりが残ります。
入力値の宣言方法も軸になります。TODOコメントは入力値をコメントの中に隠してしまいます。これに対して、関数の引数や環境変数として明示する書き方であれば、入力と処理ロジックが分離されます。
CI/CD（継続的インテグレーション・継続的デリバリー）での検証可否も見逃せません。TODOコメントが残ったコードは、コメントアウトを解除する前処理スクリプトを書かないとテストできません。これは地味にCIパイプラインの保守コストを押し上げます。
AIエージェントへの耐性が4つ目の軸です。エージェントがこのサンプルを読み込んで新しいコードを生成するとき、壊れたスタブをそのまま複製してしまうのか、クリーンな関数として再利用できるのかを確認する必要があります。
選択肢の比較
TODOコメント方式に代わる書き方として、主に2つのパターンが提案されています。ひとつは「copy-paste-callable（コピペしてそのまま呼び出せる）」、もうひとつは「copy-paste-runnable（コピペしてそのまま実行できる）」です。前者は明示的な引数を持つ関数として提供し、後者は安全なフォールバック値を持つスタンドアロンスクリプトとして提供します。
| 観点 | TODOコメント方式 | copy-paste-callable | copy-paste-runnable |
|---|---|---|---|
| 初回実行 | 構文・スコープエラーで停止 | 関数呼び出し時にAPI認証エラーで明示的に停止 | 環境変数未設定でも安全なデフォルトで動作 |
| 入力値の扱い | コメント内に隠蔽 | 関数の引数として明示 | 環境変数として宣言 |
| CIでのテスト | 前処理でコメント解除が必要 | 標準的な単体テストで検証可能 | 標準的な単体テストで検証可能 |
| AIエージェントでの再利用 | 壊れたスタブを複製しやすい | クリーンな関数として再利用されやすい | スクリプト全体が動作確認済みとして扱われやすい |
ケース別の推奨
関数スコープのAPIサンプルを書く場合は、copy-paste-callableを選びます。KMSキーやリソースURIのように環境ごとに値が変わる入力は、関数の引数として宣言し、docstring（関数の説明文）で用途を明記します。これにより、環境依存の値とサンプルのビジネスロジックが分離されます。
トップレベルで動くスクリプトやJupyterノートブックを書く場合は、copy-paste-runnableが向いています。関数の引数で受け渡す仕組みがないため、環境変数とフォールバック用のデフォルト値をトップレベルで初期化する形にします。
Terraformやリクエストオプション、SQLのような宣言的設定ファイルを書く場合は、引数も環境変数も使えません。この場合は、実在する公開の読み取り専用リソースを参照するか、予測可能なリテラル値をそのまま例示するのが現実的です。
あえてTODOコメントを見送るべきでない条件
すべての状況でTODO方式を全廃すべきとは限りません。社内限定のプレイブックや、前提として対象読者の環境知識が揃っているランブック（運用手順書）であれば、簡潔なTODOコメントのほうが読みやすい場合もあります。
ただし、その場合でも社外公開のドキュメントやAI学習データとして再利用される可能性があるコードには適用しないほうが安全です。公開APIのサンプル集やOSSのREADMEは、人間だけでなくAIツールが大量に読み込む対象になるため、TODO方式のコストが顕在化しやすい領域です。
手を動かして確認する方法
自社のサンプルコードがこの問題を抱えているか確認するには、次の手順が実践的です。
- 社内ドキュメントやREADMEから代表的なコードサンプルを1つ選ぶ
- そのままコピーして新規ファイルに貼り付け、実行してみる
- エラーが「構文エラー」なのか「認証エラーのような明確な失敗」なのかを確認する
- 同じサンプルをAIコーディングツールに読み込ませ、関連コードを生成させてTODO行がそのまま複製されないか見る
- CIのテストコードに、前処理でコメントアウトを解除するロジックが含まれていないか
grep等で確認する
まとめ
TODOコメントは長年の慣習ですが、AIエージェントがコードを読み書きする前提では弱点が目立ちやすくなっています。
判断の軸は、初回実行の成功率、入力値の宣言方法、CIでの検証可否、AIエージェントへの耐性の4つです。関数サンプルならcopy-paste-callable、スクリプトならcopy-paste-runnable、宣言的設定なら実在する公開リソースの参照、という使い分けが現実的な落とし所になります。
まずは自社の代表的なサンプルを1つ選び、コピペ直後に何が起きるかを確認してみてください。そこから着手すれば、優先的に直すべき箇所が見えてきます。