コード説明エージェント
ソースファイルを読み、LLMに説明を求め、Markdownドキュメントを返すエージェントを構築します。
「コード説明エージェント」はCoddyKit上の無料AI Agentsレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはAI Agents学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 AI Agentsコースには全4レッスンが含まれています。
このレッスンの一部はまだ翻訳されておらず、英語で表示されています。
プロジェクトの目標
ソースファイル（Python、JSなど）を受け取り、Markdownのドキュメント（目的、主要な関数、使用例）を返すエージェントを構築します。
役立つ理由
コードからドキュメントを生成することは、LLMのユースケースの中でも特に信頼性の高いものです。コードは構造化され、タスクの範囲が明確で、出力は人間が読むため、多少の誤りは許容できます。
アーキテクチャ
- ソースファイルを読み込む
- 必要に応じてクラスや関数単位に分割する
- 各チャンクについて、LLMに説明を求める
- Markdownドキュメントにまとめる
Step 1: Read the File
import sys
with open('example.py', 'w') as f:
f.write('print("hello")\n')
path = sys.argv[1] if len(sys.argv) > 1 else 'example.py'
with open(path) as f:
code = f.read()
print(f'Read {len(code)} characters from {path}')Step 2: Prompt for Documentation
from openai import OpenAI
oai = OpenAI()
prompt = f'''
You are a senior engineer writing developer-friendly docs.
Given this source file, produce a Markdown document with:
# {path}
## Purpose
(One paragraph)
## Public API
(Each function/class with one-line description)
## Usage Example
(One short, runnable snippet)
Source:
```
{code}
```
'''
response = oai.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': prompt}],
temperature=0.2,
)
print(response.choices[0].message.content)長いファイルを処理する
ファイルが長すぎる場合は、関数単位に分割し、それぞれを個別に説明します：
import ast
tree = ast.parse(code)
functions = [node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)]
for func in functions:
snippet = ast.unparse(func)
explain(snippet)ステップ3：出力をまとめる
複数チャンクを処理する場合は、関数ごとの説明を1つのドキュメントにつなぎ合わせます：
docs = []
for func_name, snippet in functions:
explanation = explain(snippet)
docs.append(f'### {func_name}\n\n{explanation}\n')
full_doc = '\n'.join(docs)
open('docs.md', 'w').write(full_doc)プロジェクト全体の概要を追加する
関数ごとの説明が終わったら、LLMに全体像の概要を求めます：
summary_prompt = 'Summarise the purpose of this package in 3 sentences, given these function docs:\n\n' + full_doc
summary = ask(summary_prompt)複数言語への対応
同じプロンプトをJS、Go、Rustなどにも使用できます。より良い結果を得るには、プロンプトに言語名を追加します：
prompt = f'You are documenting {language} code. ...'差分ベースのドキュメント生成
段階的に更新する場合は、変更されたファイルだけを再処理します：
import subprocess
changed = subprocess.check_output(['git', 'diff', '--name-only', 'HEAD~1']).decode().splitlines()
for path in changed:
if path.endswith('.py'):
regenerate_doc(path)ツールを使って例を実行する
LLMが生成した使用例が実際に動くことを検証します。エージェントにPython REPLツールを渡します：
def run_python(code):
try:
exec(code, {})
return {'stdout': 'ok', 'stderr': ''}
except Exception as e:
return {'stdout': '', 'stderr': str(e)}
tools = [{'name': 'run_python', 'description': 'Execute a Python snippet and return stdout/stderr', 'parameters': {'code': 'str'}}]
broken_example = 'print(1/0)'
result = run_python(broken_example)
if result['stderr']:
print('Example failed:', result['stderr'])
fixed_example = 'print(1)'
result = run_python(fixed_example)
print('Self-corrected result:', result)
else:
print('Example ran fine:', result)
エージェントがハルシネーションを起こした場合
モデルが関数や引数を作り出してしまうことがあります。対策は次のとおりです：
- ファイルの内容だけを提供する（モデルの記憶に頼らない）
- Temperatureを0にする
- 検証ステップを設ける（例を実行する、スニペットをlintする）
プロダクト化する
これをCLIとしてラップします：
# pip install -e .
# docgen src/myproject/agent.py
# Outputs docs.mdツールからCIへ
CIに組み込みます。すべてのPRで、変更されたファイルのドキュメントを再生成してコミットし直します。これで、リポジトリのドキュメントが常に最新の状態になります。
ファイル全体を読む理由
関数シグネチャだけでなく、ソースファイル全体をLLMに渡すのはなぜでしょうか？
まとめ
コードをドキュメントに変換する30行のエージェントです。ツールと検証機能で簡単に拡張できます。RAGの次に取り組む2つ目のプロジェクトとして最適です。
よくある質問
「コード説明エージェント」レッスンは無料ですか？
はい。「コード説明エージェント」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、AI Agentsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 AI Agentsコースには全4レッスンが含まれています。
「コード説明エージェント」で何を学びますか？
ソースファイルを読み、LLMに説明を求め、Markdownドキュメントを返すエージェントを構築します。 ブラウザで直接実行するハンズオンコードでAI Agentsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
AI Agentsを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのAI Agentsは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。
「コード説明エージェント」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このAI Agentsレッスンでコードを書いて実行できますか？
はい。すべてのAI Agentsレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。