エンジニアの市場価値を上げる！AIドキュメンテーションスキル実践ガイド

日常的な言葉で操作できることから、生成AIは急速に普及しました。一方で、人なら簡単に伝わることがAI相手にはうまく伝わらずに悩んだことはないでしょうか。

よくある失敗パターン

コーディングエージェントに実装を任せた場合、以下のような問題が発生することがあります。

• ビジネスルールが反映されていない
• プロジェクト全体での整合性が取れていない
• パフォーマンス要件を満たさない
  
  

実装にあたって特定の機能のアルゴリズムを指定したとしても、もちろんコーディングのすべてを細かく指示できるわけではありません。
大半のコードはAIが自律的に判断することで生成されます。しかしそうして生成されたコードは、たびたび期待している仕様とは違っています。

コンテキスト（状況・文脈）を伝える

基本的に、AIはデータから学んだパターンに基づいて回答します。
単純な言葉のみで質問をすれば、AIは極めて一般的な回答を返します。AIに目的や状況といったコンテキスト（状況・文脈）を適切に伝えることで、AIの出力範囲を絞るように調整できます。

例えば、以下のコンテキストをAIに伝えてみます。

## 背景
- B2B向けECサイトのリニューアルプロジェクト
- 現行システム：10年前のレガシーシステム（PHP5）
- 月間取引：約100万件、ピーク時は3倍

## 技術要件
- マイクロサービス化の一環として在庫管理を切り出し
- 既存のMySQLデータベースと連携必須
- API Gateway経由でフロントエンドと通信

## ビジネス要件
- リアルタイム在庫更新（遅延1秒以内）
- 複数倉庫の在庫を統合管理
- 既存の会計システムとの整合性保証

「B2B向けECサイト」というキーワードを伝えることで、AIは「B2B向けECサイトのパターン」を踏まえたコードを生成します。
また、設計時に守らなければならない制約事項や、リニューアル＝「移行への考慮」のような指向性を与えることができます。

AIに伝えるべきコンテキストはその他にも様々にありますが、特にこのような目的や制約条件といったコード外の「メタ情報」は基本的に人間が提供するしかありません。
一般に、これらの情報は要件定義書や設計書などのドキュメントとして管理していることが多いでしょう。

AIの性能を最大限に引き出すためには、こうしたドキュメントを機械が理解しやすい形で整理することが重要です。

構造化データがAIの理解を助ける

AIはプレーンテキストのような非構造化データの解釈を誤ることがあります。
人間なら文脈から推測できる曖昧な表現も、AIには正確に伝わりません。
人間にとっても解釈が難しい文章は尚更です。

画像など多様なデータ形式を解釈できることは、AIの重要な機能の一つです。
しかし正確さが求められる場合には、適切にラベリングされた構造化データが欠かせません。
一般的なドキュメントでも、見出しや箇条書きなどの記法を用いて文書構造を表現したり、強調表現によってキーワードを示す方が、AIにとって意図が伝わりやすくなります。

AI時代のドキュメンテーションスタイル

現状のAIは一度に覚えておける容量に制限があります。
そのためAIエージェントはどうしても記憶したことを忘れてしまう、あるいは記憶が溜まりすぎることで性能が低下してしまいます。こうした際、ドキュメントが外部メモリとして「思い出させる」役割に利用できることも重要です。

もちろん設計書は、従来通り人間同士の認識合わせに使える情報でもあります。
これらのドキュメントはAIに読ませるだけでなく、同時に人間がAIが生成したコードの妥当性を判断する指標としても使うことになります。

クライアントやチームメンバーといった人間同士、そしてAIとの認識共有。両方の目的を果たす「共通言語」となるドキュメントを作成・管理することが、AI時代に求められるドキュメンテーションスタイルだと言えます。

ドキュメントの種類によって、適切な記述スタイルは異なります。
目的に応じた「型」を使い分けることで、読み手にとってわかりやすく、AIにも活用しやすいドキュメントが作成できます。

適切なドキュメントフォーマットを選択する

IT業界にはよく知られたドキュメントフォーマットが多くあります。これらを積極的に使うことで一貫性のある構造的なドキュメントを作成しやすくなります。
業界標準のドキュメントフォーマットは、AIにとって解釈しやすく、編集しやすい可能性が高いとも言えます。

例えばRESTful APIを実装する際には、OpenAPI Specificationのような広く採用されているフォーマットを利用しましょう。OpenAPI Specificationは、RESTful APIのパス、パラメーター、認証スキームなどのAPIインタフェースを言語に依存しない標準的な形式で記述するための仕様です。

こうした仕様に従うことで、ドキュメントとコードをより明確に紐づいた形でAIに解釈・実装してもらうことが可能です。

インフラの領域であれば、IaC（Infrastructure as Code）ツールを利用すれば、AIはアーキテクチャ図の画像1枚よりもずっと具体的にインフラ構成を認識できるはずです。

このように内容に見合った、そしてAIにとって読み取りやすい適切なドキュメントフォーマットを選定することが重要です。

設計ドキュメントの基本構造

ITプロジェクトでは、プロジェクト計画書、要件定義書、設計書と、段階的にドキュメント作成を行います。
スコープが定まらないまま設計を開始すると、実現困難な設計になりがちです。
こうしたプロジェクト管理フローのプラクティスを意識することも良いドキュメントを作成するために重要です。

まず課題やスコープを「プロジェクト計画書」にまとめ、次にユースケースや制約条件を「要件定義書」に整理し、最後に技術的決定を「設計書」として書き出します。
「仕様駆動開発」と呼ばれるAIコーディング手法でも、同様の順番でドキュメントを作成します。

テクニカルライティングの技法

AIは曖昧な表現を誤解しやすいため、テクニカルライティングの技法が重要です。

• 数値は具体的に：「しばらく待つ」→「5秒間待機する」
• 主語を明確に：「処理される」→「システムが処理する」
• 条件を明示：「場合によって」→「管理者権限を持つ場合」
  
  

プロジェクト内で用語を統一する「ユビキタス言語」も有用です。「在庫」「引当」「有効在庫」などの業務用語を明文化すれば、認識のずれを防げます。

ここまで、AIの弱点を補うドキュメントの重要性と、その具体的な記述法を見てきました。では日々の業務でこれらを実践するには、どのような習慣を身につければ良いのでしょうか。

日常的に情報を作り出す習慣

日々の業務に追われる中で、質の高いドキュメントを作成するための時間をしっかり取るのは難しいものです。

しかし、いまは多くのドキュメンテーションツールに、AIで要約してドキュメントを生成してくれる機能や、質問に対して複数のドキュメントを参照して回答してくれる機能があります。

つまり、最終的な体裁はAIに任せ、個々のドキュメントに完璧さを求める必要はありません。AIツールで活用することを前提として、美しいドキュメントというよりも「AIに読ませると有用そうなデータ」を日々の業務の中で作成する習慣をつけると良いでしょう。

暗黙知を「見える化」

企業やプロジェクトには、明文化されていない独自のルールや慣習が存在します。これらの情報を積極的に明文化することも大切です。

## プロジェクト固有ルール

### 命名規則
- データベーステーブル：snake_case（例：user_profiles）
- APIエンドポイント：kebab-case（例：/api/user-profiles）
- フロントエンドコンポーネント：PascalCase（例：UserProfile）

### レビュープロセス
- PR(プルリクエスト)は2名以上のApprove(承認)が必要
- 金曜日の午後はデプロイ禁止
- hotfixは例外的に1名のApprove(承認)で可

AIからは明示的に共有されなければ気づくことができない内容が多いはずです。
ドキュメントの形で存在することで、AIははじめてその情報を認識できるようになります。

AIが理解できる引き継ぎドキュメントを残す

これからの引き継ぎにおいて、AIに理解できる形式でドキュメントを残すことが重要です。

• 環境構築手順：コンテナやIaC（Infrastructure as Code）を利用して構築
• トラブルシューティング：エラーメッセージと対処法をFAQ形式で記載
• プロジェクト構造：ディレクトリ構成とその役割を図解
• 技術的意思決定：ADR（Architecture Decision Records）形式で記録
  
  

これらのドキュメントがあれば、この情報を後任者はAIから教えてもらうことができ、オンボーディング資料は必要ありません。
前項で説明した「暗黙知の文書化」は、実際の開発業務には使えなくとも、引き継ぎの際に有用になる情報も含まれるでしょう。

更にAIを活用することで、ドキュメント作成の効率を向上させることができます。

AIによるドキュメント生成のテクニック

まず重要なのは、ドキュメントの目的やターゲットを明確に伝えることです。
例えば「新規メンバー向けの環境構築手順書」と「経営層向けの技術選定レポート」では全く異なります。
元となる情報が同じであっても、AIが生成する内容の詳細度や専門用語の使い方が大きく変わります。

特に自分が詳しくない分野では、整理してもらう前にDeepResearchを使って広範に調査をしてもらっておくアプローチが効果的です。
「マイクロサービスのモニタリング手法について調査して」などと依頼してまず情報を集めさせます。
その後、ドキュメントの目的を指定したり、プロジェクトの要件に合わせて設計するよう指示することで、知識不足を補いつつ質の高い文書が作成できます。

AIレビューによる品質向上

ドキュメントの品質を上げるにはAIレビューが有効です。多くのドキュメントで人間のレビューは必要ですが、少なくともAIに1次レビューをさせることでその手間を省くことができます。

AIにレビューをさせる際は、参考元や根拠も示すように促しましょう。生成ドキュメントに参照先が記載されるため、人間がレビューする際に信憑性を確認することできます。
またAIは論拠を示そうと情報検索するため、情報の精度が向上しやすくなります。
AIにレビューと改善を繰り返させるアプローチも効果的です。生成されたドキュメントに対してレビューを依頼した上で、その内容に沿って改訂させます。

大きな問題が見つからなくなるまでこのプロセスを繰り返させることにより、ドキュメントの品質が向上します。利用しているAIエージェントにサブエージェント機能があれば、それぞれのサブエージェントにそれぞれのロールを割り振ることでより効果的に改善できます。

ドキュメントが自然に生成されていく業務フローづくり

たとえAIを使ったとしても、質の高いドキュメントにはやはりコストがかかります。
積極的に自動化ツールを利用して効率化しましょう。代表的な例が、議事録作成の自動化です。

まず、AI文字起こしツールを用いてオンラインミーティングの内容をテキストに書き起こします。そのテキストを更にAIに渡し、議決事項やネクストアクションなどを整理してもらいます。

これにより議事録作成のコストを削減しつつ、ミーティングの内容を活用可能なデータセットとして蓄積できます。
ミーティングの内容をAIに質問したり、課題の対応を検討してもらうこともできます。参加できなかったメンバーへの説明も不要になります。

チームのAI活用を促進するためには、このようなドキュメント生成が自然に行われるワークフローの検討、そして自動化ツールの活用が欠かせません。

「コンテキストエンジニアリング」という新しい概念が注目されています。
「バイブコーディング」という言葉を提唱したアンドレイ・カーパシーが、X上で共有したことで広まりました。
https://x.com/karpathy/status/1937902205765607626

これは、AIに適切なコンテキストを提供し、意図通りの出力を得るための技術です。
プロンプトエンジニアリングが単一の指示の最適化だとすれば、コンテキストエンジニアリングはプロジェクト全体のコンテキストをAIと共有する、より包括的なアプローチを表しています。

プロジェクトにおいてAIを生産性高く活用するためには、こうしたコンテキストエンジニアリングのスキルが重要です。
コンテキストを適切に伝える手段においては、本記事で解説してきたドキュメンテーションスキルが不可欠となります。

プロジェクトにおいて必要なコンテキストを設計し、そのコンテキストとなるドキュメントをAIと共有できる形で作成・運用できること。この能力が、AI時代における競争力の源泉となります。

AI時代において、エンジニアの価値は「AIが生成できないもの」にシフトしつつあります。
それはコンテキストを理解し、意図を明確化し、構造的に情報を伝えることであり、多くはドキュメントの形で表現されることになります。

高いドキュメンテーションスキルにより、AIツールをより高い生産性で活用できるエンジニアこそが、これからの時代に求められる人材だと言えるでしょう。

ギークスジョブでは、ITフリーランス専任のキャリアアドバイザーがマンツーマンでサポートいたします。
今後のキャリアアップなどをお考えの方は、まずはギークスジョブにご相談ください。

フリーランスになりたいという方も、よりご自分にあった案件をお探しの方も、ぜひ一度ご登録ください。

▽ 無料登録（エントリー）はこちら
https://geechs-job.com/entry

まだフリーランスになることに迷いがある方へは、独立のご相談から承ります。
これまでのご経歴やキャリアの目標をお伺いしながら、お一人おひとりに寄り添ったキャリアプランのご提案をいたします。

▽ 独立相談会への無料エントリーはこちら
東京：https://geechs-job.com/event/details/1
大阪：https://geechs-job.com/event/details/2
福岡：https://geechs-job.com/event/details/3
名古屋：https://geechs-job.com/event/details/189