利益:
- AI を使用して対象読者とソースに基づいて README、ドキュメントストリング、および変更ログのドラフトを作成する機能
- ドキュメント内の「何を/どのように」と「なぜ」のレイヤーを分離し、人間として「なぜ」を追加する能力
- インストール手順を個人的に実行して検証し、ドキュメントをコード変更の一部にする
ソフトウェアの中で最も無視されがちですが、最も長く存続する部分はドキュメントです。コードは数か月経っても読み取ることができます。それを書いた人は去り、文脈は忘れられ、書かれたことだけが残ります。優れた README (プロジェクトとは何か、そのインストールと実行方法を説明する入門文書)、説明的なコード コメント、および最新の API ドキュメント (インターフェイスの使用方法を説明するリファレンス) は、チームの速度を直接決定します。 AI はドキュメントから「書く疲れ」を大幅に軽減します。しかし、これには落とし穴があります。AI はコードから動作を推論できますが、なぜそのようになっているのかは分からないことがよくあります。
この単元では、AI を使用して README、コード コメント、docstring (関数/クラスごとに記述されたコメント ブロック)、API ドキュメント、および変更ログを作成する方法を学びます。そして、文書の最も価値のある部分である「理由」を人間がどのように保存するか。
「何を」と「なぜ」の区別
ドキュメントには 2 つの層があります。 1 つ目は、「この関数はリストを並べ替える」、「このコマンドを実行してインストールする」という内容/方法です。これらはコードと構造から抽出できます。ここではAIが優れています。 2 番目に、理由: 「なぜこのサービスを同期ではなく非同期にしたのか」、「なぜこの制限値が 30 秒なのか」、「なぜ他のライブラリではなくこのライブラリを選択したのか」。これらはコードには書かれていません。それは設計上の決定、制約、過去の苦痛の産物です。
AI には「なぜ」がわかりません。せいぜい、合理的な推測を生み出す程度ですが、理由が間違っていることは、まったく理由がないより悪いため、これは危険です。そのため、役割分担は明確です。AI が「何を/どのように」を草案し、あなたが「なぜ」を追加します。最も価値のあるコメントは、コードでは言えないことを述べたコメントです。
ヒント: コード自体が明確に示していることをコメントで繰り返さないでください (i = i + 1 // i を 1 増やすなど)。 AI は、このような冗長なコメントを生成することがあります。それらを排除し、「なぜ」のコメントにエネルギーを注ぎましょう。
ステップバイステップ: AI を使用したドキュメントの生成
- 対象読者を指定します。 「始めたばかりの開発者」、「この API を使用する外部チーム」、「将来の私」 - 聴衆が言語と深さのトーンを設定します。
- ソースを与えてください。関連するコード、既存の README、使用例をプロンプトに追加します。出典のない文書は捏造への誘いです。
- 面付け構造。 README の標準セクション (目的、インストール、使用法、構成、貢献)、docstring のプロジェクト形式。
- 「なぜ」スペースにマークを付けます。 AI に、根拠がわからない決定を「ここで『なぜ』メモが必要か」としてマークするよう依頼します。次に、それらの空白を埋めます。
- 確認する。実際にインストール手順を実行します。サンプルコードを試してください。機能しない README は、まったく README がないよりも悪いです。
ミニケース3個
ケース 1 — README によりオンボーディングが加速されました。オープンソース ツールの README がありませんでした。新しい投稿者は、インストールに平均 2 時間苦労しました。チームはインストール スクリプトと package.json を AI に渡し、構造化された README の草案を作成し、クリーン マシン上で手順自体を実行し、不足している 2 つの依存関係を追加しました。後続の投稿者のインストール時間は平均 25 分に短縮されました。
ケース 2 — でっち上げられた「なぜ」の罠。開発者は AI にタイムアウト値 (timeout=30) の横にコメントを求めました。 AI は、「高いネットワーク遅延を許容するため」という合理的ではあるが間違った正当化を書きました。本当の理由は、ダウンストリーム サービスの契約上の 30 秒制限でした。この誤解により、後続の開発者が必要以上に値を大きくしてしまい、事件が発生しました。教訓: コード所有者は正当性を検証する必要があります。
ケース 3 — Docstring 標準が自動化されました。 40 個の関数を備えた補助モジュールには docstring がありませんでした。 AI にはプロジェクト形式 (Google スタイル) が与えられ、各関数のパラメーター、戻り値、例外の説明が生成されました。開発者はこれらをレビューし、いくつかの間違った型宣言を修正しました。 40 の機能の文書化は、約半日から 1 時間に短縮されました。
4 つのコピー可能なテンプレート
構造化された README ドラフト:
対象読者: {{例:新しい寄稿者}}。以下のファイルに基づいて README の下書きを作成します。セクション: 目的、機能、要件、インストール、操作、構成、テスト、貢献。実際のファイルからインストール/実行コマンドを抽出します。フィッティング。不明な箇所には「[VERIFY]」を付けてください。出典: {{package.json / スクリプト / サンプルコード}}
ドキュメント文字列/API リファレンス:
これらの関数に docstring を {{プロジェクト スタイル: Google/NumPy/JSDoc}} 形式で記述します: 短い概要、パラメーター (型 + 意味)、戻り値、スローされる例外、1 つの短い例。コードに明確に記載されていることを繰り返さないでください。 「なぜ」を必要とする設計上の決定には「[WHY NECESSARY]」とマークを付けてください。捏造された理由を書かないでください。{{code}}
「なぜ」コメントのスペースを削除します。
このコードでは、次の開発者は「なぜそうなるのか?」と尋ねるかもしれません。 (魔法の数字、異常な決定、回避策)。それぞれに「SKELETON」というコメントを付けますが、根拠は空白のままにします。理由を記入します。{{code}}
変更履歴/PR ステートメント:
以下の差分から {{変更ログ エントリ / PR の説明}} を書き込みます。形式: 変更内容 (ユーザー言語)、理由 (問題: {{...}})、重大な変更 (ある場合)、テスト済みか。対象読者に合わせて専門用語を調整します。{{diff}}
弱いプロンプト / 強いプロンプト
弱者: 「このプロジェクトの README を書いてください。」
Strong: 「対象読者: 初めてこのリポジトリをクローンする開発者。添付された package.json、docker-compose.yml、scripts/ フォルダーに基づいて、目的、要件、インストール、操作、テスト、貢献セクションを含むドラフト README を作成します。これらのファイルからコマンドを抽出します。コマンドを作成しないでください。不明な点は [VERIFY] でマークしてください。」
強力なバージョンでは、聴衆、ソース、構造、そして「作ってマークする」ルールが提供されます。そのため、ドキュメントは実際のファイルに基づいており、検証する場所が明確に表示されます。
文書の種類
AIはうまくやる
人間が追加/検証する
README のインストール
ステップの概要
手順を実行して確認する
ドキュメント文字列/API
構造体、パラメータ、型
正しいタイプと「理由」
コードコメント
「あいつがやっていること」まとめ
「なぜそうなるのか」という正当化
変更履歴/PR
初稿
影響力と精度
アーキテクチャ上の決定 (ADR)
スケルトン
本当の決断と妥協
ドキュメントにはメンテナンスが必要です
文書の最も危険な側面は、それが虚偽であるにもかかわらず真実のように見える場合です。コードが変更され、ドキュメントが更新されていない場合、読者を積極的に誤解させます。 AI により更新が簡単になります。diff を発行して、「この変更はドキュメントのどの部分に影響しますか?」と尋ねます。あなたは尋ねるかもしれません。しかし、これは最新性を保証するプロセスです。ドキュメントの更新をコード変更の一部にします (PR の承認基準)。 AIは加速します。チームは規律を築きます。
注意: README でインストール手順を確認せずに公開しないでください。 「おそらく機能する」ドキュメントは、新しい開発者の初日を台無しにし、信頼を損なう可能性があります。クリーンな環境で自分で手順を実行します。
よくある間違い
- AI に適合する「理由」を取得する。誤った正当化は、正当化がないより悪いです。コード所有者は設計理由を記述する必要があります。
- インストール手順を検証していません。機能しない README は信頼を破壊します。
- コードを繰り返す不要なコメント。それはノイズを生み出し、本当の「なぜ」の解釈を曖昧にしてしまいます。
- 対象者を特定しない。誰に向けて書かれたのか不明瞭な文書は、初心者にとっても専門家にとっても役に立ちません。
- 更新をプロセスから分離します。ドキュメントがコードで更新されていない場合、すぐに誤解を招くものになります。
要約すると
AI は、クイック ドラフト README、ドキュメント文字列、API リファレンス、変更履歴、PR 説明などのドキュメントにかかる機械的な負担の多くを軽減します。しかし、最も価値のある層である「なぜ」を知ることができず、それをでっち上げるのは危険です。分業は明確です。AI が「何を/どのように」を生成し、ユーザーが「なぜ」を追加します。対象読者を指定し、リソースを提供し、構造を強制し、適合する場所にマークを付けて、各インストール手順を自分で実行して検証します。ドキュメントをコード変更の不可欠な部分にします。
アプリケーションタスク
ドキュメントが不足しているか古いモジュールまたは小規模プロジェクトを選択してください。まず、「構造化された README ドラフト」 (または docstring) テンプレートを使用して AI からアウトラインを生成します。情報源と対象読者を必ず明記してください。次に、AI が [VERIFY] または [WHY NEEDED] とマークした各ポイントを確認します。実際にセットアップ手順を実行し、自分の知識を使って設計の「理由」を記入します。修正する必要があるステップの数と追加した「理由」の数に注目してください。
チェックリスト
- [ ] ドキュメントでは、「何を/どのように」層と「なぜ」層を区別します。
- [ ] 「なぜ」は AI に作成させるのではなく、自分で追加します。
- [ ] プロンプトに対象読者と実際のソース ファイルを与えます。
- [ ] AIがマークした[VERIFY]ポイントを自ら実行して検証します。
- [ ] コードを繰り返す不要なコメントを削除します。
- [ ] コード変更の一部としてドキュメントの更新を行っています。