KENTEM TechBlog

建設業のDXを実現するKENTEMの技術ブログです。

AIによるドキュメント作成のポイント

アドベントカレンダー2025 AI

この記事は、 KENTEM TechBlog アドベントカレンダー2025 15日目、12月15日の記事です。

みなさん AI は使っていますか？ 今回は AI に教育用コンテンツを作らせてみたので作成時のポイントをご紹介したいと思います。

作成時のポイント

ポイント1 - バージョン管理システムで管理する

AI に限った話ではないですが、成果物も管理用のファイルも必ずバージョン管理システムで管理しましょう。

途中でより良いやり方を思いついたり、ミスを見つけて修正する事もあるでしょう。そうした時にバージョン管理してあれば大胆な変更もできるし、変更したけど気に入らなければ元に戻せます。 AI に任せた変更も比較しながら確認できるので便利です。

ポイント2 - ドキュメントは Markdown & Mermaid で作る

Markdown は今更説明するまでも無いですね。簡単にタイトルやリストを作れたりと非常に便利なマークアップ言語で、このはてなブログだけでなく様々な媒体で対応されています。

Mermaid記法とは、テキストベースのシンプルな記述から、フローチャート、シーケンス図、ガントチャートなどの図を生成するJavaScriptライブラリです。Markdownファイル内にコードとして記述し、簡単に図を作成・修正できるため、システム開発やドキュメンテーション作成の現場で広く活用されています。

Mermaid を採用した理由

  • どの AI モデルでも高速に読み書きできる
  • テキストなので変更が容易
  • 技術ドキュメントで必要な図はカバーされている

最初は画像生成で頑張っていましたが、微妙に意図したものが作れず時間を浪費しました。

編集は Visual Studio Code

VS Code に拡張機能を入れる事で、 Markdown と Mermaid のプレビューを確認しながら編集できるので便利です。

ポイント3 - 仕様書を用意する

ドキュメントの作成なので大した仕様は無いのですが、それでも決まり事はあると思いますので用意しましょう。私が決めた仕様は以下のとおりです。

  • ディレクトリ構成
  • 命名規則（ファイルとフォルダー）
  • ドキュメント形式（Markdown & Mermaid）
  • トピック毎に作るドキュメント（資料・確認問題・問題回答）
  • 初心者向けに難しい言葉は避ける
    • 「入社歴1年目の新人を対象」といった感じに対象者を具体的に指定しましょう。
  • 情報源は公式ドキュメント（Microsoft 公式ドキュメント、MDN Web Docs など）

このあたりは AI と一緒に作れば良い感じの仕様書が作成されると思います。

ポイント4 - テンプレートを用意する

仕様書を作ることと似ていますが、テンプレートは各ドキュメントのより細かい部分になります。

はじめはテンプレートを用意せずに作業していたので選択する AI モデルやトピックによって成果物がばらばらで、必要な項目が入っていないなんてこともありました。

そのため、ある程度作ってから統一感が無いことに気づいて一斉に修正することになりました。

ポイント5 - 複数の AI モデルに作らせる

選択する AI モデルによって成果物に差がでます。これはどの AI モデルが優れているとかではなく、トピック毎に自分の求めている内容が入っていたりいなかったりという感じでした。

そのため同じドキュメントを複数の AI モデルに作らせ、それぞれの良い部分をまとめて1つのドキュメントにするのをおすすめします。

この時の指示で重要な点があります。仕様書やテンプレートに記載されている内容でも重要なことは改めて指示に入れましょう。特に以下の3点は必ず入れることをおすすめします。

  • 他のモデルが出力したドキュメントを上書きしないように出力先を指定
  • 予め用意した仕様書とテンプレートを読んで従うこと
  • 日本語で出力

統合作業は人が行う

異なる AI モデルが作成したドキュメントを1つのドキュメントに統合し、最終成果物とします。この作業も AI に任せてみました。

[AI-A が作ったドキュメント]    -> ┌─────┐
[AI-B が作ったドキュメント]    -> │ AI-D│ -> [ドキュメント]
[AI-C が作ったドキュメント]    -> └─────┘
  1. AI-A, AI-B, AI-C に同じトピックのドキュメント作成を命じる。
  2. それぞれの AI に自分が作成したドキュメントをレビューし、採点させる。
  3. AI-D はドキュメントと採点結果から1つのドキュメントに統合する。
  4. 統合されたドキュメントを人が確認する。

いくつかのトピックで試したところ、「AI-D が統合したドキュメントよりも AI-A が作ったドキュメントの方が良い」といった事がおきました。

  • 統合前のドキュメントには図や必要な内容が削られた
  • 文章が冗長になったり、重複した内容が出た

そのため、統合作業は自分で行うことになりました。

ポイント6 - プロンプトを固定する

チャットで AI 指示する文章はトピック名を変えるくらいで固定しましょう。毎回同じプロンプトで指示を出せば成果物が安定します。

GitHub Copilot を使っている場合はプロンプトファイル（.prompt.md）を使うと便利です。

まとめ

始める前は「 AI に任せれば楽勝！」とか思っていましたが、けっこう大変でした。しかし仕様書やテンプレートさえできてしまえばかなり効率化できました。

おわりに

KENTEMでは、様々な拠点でエンジニアを大募集しています！ 建設×ITにご興味頂いた方は、是非下記のリンクからご応募ください。 recruit.kentem.jp career.kentem.jp