ドキュメント作成という「苦行」
500行に及ぶ複雑なロジックを書き終え、すべてが正常に動作したとします。しかし、ふとコードを見返すと、コメント一つない空っぽの関数群が並んでおり、途方に暮れる……。そんな経験はないでしょうか。ドキュメント作成は、しばしば退屈な「付随作業」と見なされがちです。しかし、3ヶ月後にコードを修正したり、同僚に引き継いだりする際にドキュメントがなければ、かつてのロジックを読み解くために多大な時間を浪費することになります。
優れたドキュメント作成能力は、プロのシニアエンジニアと、ただタスクをこなすだけのコーダーを分ける境界線です。argsやreturnsといったパラメータを手動で入力する代わりに、AIを活用してこうした反復作業を自動化してみませんか？
現在のドキュメント作成手法の整理
実装に入る前に、開発者が一般的にどのようにドキュメントを管理しているかを見てみましょう。
1. 手動での作成 (Manual)
最も伝統的な方法です。各関数のdocstringを自分で入力し、README.mdを更新します。精度は高いですが、非常に時間がかかります。スプリント（Sprint）開発では真っ先に削られがちな工程であり、結果として「技術的負債」が蓄積する原因となります。
2. 静的ドキュメント生成ツール (Sphinx, Swagger)
これらのツールはコードをスキャンし、既存のコメントを抽出してドキュメントサイトを生成します。一貫性が保たれるのが利点ですが、最大の欠点は「書かれたものしか表示できない」ことです。最初にコメントを書いていなければ、SphinxやSwaggerもコードのロジックを説明してはくれません。
3. AIの活用 (Claude API, OpenAI API)
これが現在最も効率的なアプローチです。AIはコードを読み取るだけでなく、開発者の意図を理解します。自然言語でロジックを説明し、インポートされたライブラリに基づいてインストール手順を書き、さらには実用的な使用例（usage examples）まで提案してくれます。
なぜコード生成にはClaude 3.5 Sonnetが最適なのか？
複雑なPythonプロジェクトでテストを重ねた結果、以下の3つの理由からClaude APIを推奨します。
- 高度な論理思考： Claude 3.5 Sonnetは、ネストされた複雑なロジックを説明する際の「ハルシネーション（幻覚）」が非常に少ないです。
- 巨大なコンテキストウィンドウ： 最大200,000トークンを処理できるため、複数のファイルからなるモジュール全体を読み込ませて、プロジェクトの全体像を理解させることが可能です。
- プロフェッショナルな技術文書スタイル： 出力されるテキストは簡潔で要点を得ており、Google StyleやNumpy Styleといった標準的な規約にも忠実です。
自動ドキュメント生成ツールの構築
コードファイルを自動的にスキャンし、Claude APIを使用してdocstringを追加し、READMEファイルを生成する小さなPythonスクリプトを作成します。
ステップ1：環境構築
Anthropic ConsoleでAPIキーを取得します。その後、公式ライブラリをインストールします。
pip install anthropic python-dotenvステップ2：Pathlibによるソースコードの読み込み
pathlibを使用することで、WindowsとLinuxの両方でスムーズに動作するスクリプトになります。
import os
from pathlib import Path
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
def read_source_code(file_path):
path = Path(file_path)
return path.read_text(encoding="utf-8")ステップ3：最適なプロンプト構造
AIが冗長な回答をしないよう、プロンプトを厳密に設計する必要があります。単に「ドキュメントを書いて」と頼むのではなく、具体的な制約を与えます。
def generate_documentation(code_content):
prompt = f"""
あなたはシニアソフトウェアエンジニアです。以下のソースコードを分析してください：
{code_content}
要件：
1. すべてのクラスと関数にGoogleスタイルの標準的なdocstringを追加してください。
2. 入力引数と戻り値を明確に説明してください。
3. コードのロジックは変更せず、コメントのみを補完してください。
4. 完成したコードブロック形式で回答してください。
"""
response = client.messages.create(
model="claude-3-5-sonnet-20240620",
max_tokens=4000,
messages=[{"role": "user", "content": prompt}]
)
return response.content[0].textステップ4：実行と結果の保存
スクリプトはAIによって調整された内容を新しいファイルに書き出すので、元のコードと比較しやすくなります。
def main():
target_file = "core_logic.py"
print(f"[*] 分析中: {target_file}")
raw_code = read_source_code(target_file)
documented_code = generate_documentation(raw_code)
output_path = Path(f"documented_{target_file}")
output_path.write_text(documented_code, encoding="utf-8")
print(f"[+] 成功しました！ドキュメントは {output_path} に用意されました")
if __name__ == "__main__":
main()実際の効果測定
約50個の関数を持つ社内プロジェクトにこのプロセスを適用したところ、明らかな変化が見られました。
主なメリット
- 時間の節約： 毎週2時間かかっていた作業が、わずか2分足らずで終わるようになりました。
- 一貫性の向上： プロジェクト内のすべてのdocstringが単一のフォーマットに従うため、情報の検索が非常に容易になりました。
- オンボーディングのサポート： 新しく加わったメンバーが、元の作成者に確認することなく、複雑な関数の目的を即座に理解できるようになりました。
セキュリティとコストに関する注意点
- データ管理： シークレットキーや顧客情報を含むファイルをAPIに送信しないでください。環境変数を使用し、機密データを事前にフィルタリングするようにしましょう。
- レビューは必須： AIは時として、非常に特殊なビジネスロジックを誤解することがあります。メインブランチにマージする前に、必ず内容をチェックしてください。
- コスト： Claude 3.5 Sonnetを使用した場合、1,000行のコードを処理するコストはわずか数セントです。節約できる時間を考えれば、非常に安価です。
終わりに
自動ドキュメント生成ツールの構築は難しくありません。最大のハードルは、これまでの働き方を変えることです。ドキュメントを「負担」ではなく「自動化プロセスの一部」と捉えることで、プロダクトの品質は一段上のレベルへと引き上がります。
オープンソースのリポジトリを管理している方や、アジャイルチームで働いている方は、ぜひこのスクリプトをCI/CDに組み込んでみてください。あなたのコードの丁寧さとプロフェッショナルな仕上がりに、同僚も驚くはずです！
