メタドキュメント作成のススメ
メタドキュメント作成のススメ
システム開発では、設計書、ソースコード、サーバー構築手順書、業務手順書など、多様な成果物を複数の関係者やツールと協調しながら作成します。本稿では、生成AIと人間が共通の品質基準で成果物を作成できるよう、その指針となる メタドキュメント の作成と運用ワークフローについて説明しています。
メタドキュメントとは何か
メタドキュメントは成果物そのものを直接記述するのではなく、成果物を生成・レビュー・保守するためのルール、構造、品質基準をメタレベルで定めた文書群です。以下のような文書が該当します。
- インセプションデッキ
- ドキュメントスタイルガイド
- 設計書テンプレート、及び記述に関するガイドライン
- ソースコードスタイルガイド
- 命名規約
- サーバー構築手順のガイドライン
- レビュー観点チェックリスト
- リリースノート作成ガイド
- アーキテクチャ決定記録(ADR)のテンプレート
なぜメタドキュメントを作成するのか
システム開発の現場には様々な成果物が存在します。業務手順書のようにドメインエキスパート(業務の専門家)が主体となってまとめる資料や、ユーザーストーリーのようにドメインエキスパートとエンジニアが共同で作成する資料など、多様な背景を持つ人々が成果物を作成します。しかし、これらの多種多様な資料が存在する中で、責任の境界が不明確となり、成果物のレビュー基準も曖昧で属人的になりがちです。
この課題に対応するため、関係者全員が理解できる言葉でガイドラインやチェックリストをメタドキュメントとして作成し、合意することで成果物の一貫性を高めることができます。現在はAIによるレビューも活用できるようになり、メタドキュメントの運用が容易になっていることから、その作成の重要性がさらに高まっています。
メタドキュメントのワークフロー
メタドキュメントは成果物の分類毎に作成し、主にドメインエキスパートが作成、関係者間で合意した上で、メタドキュメントに基づいた成果物をエンジニアがAI支援を受けながら作成、レビューするという運用が想定されます。
メタドキュメントと成果物の関係
メタドキュメントは成果物の分類毎に作成しますが、より上位のメタドキュメントは複数の成果物の分類に跨がって適用することが想定されます。成果物のレビューの際には、複数のメタドキュメントをレビュー基準として採用することがあります。以下はメタドキュメントと成果物の関係の例です。
メタドキュメントの構成
メタドキュメントは主に以下の要素を含みます。
- メタドキュメントの目的と適用範囲
- メタドキュメントが適用される成果物が満たすべき条件とその理由
- メタドキュメントが適用された成果物の例
- 用語の定義
- メタドキュメントに対するFAQ
- メタドキュメント作成時に参考した参考文献
メタドキュメントの目的と適用範囲
メタドキュメントの目的と適用範囲では、そのメタドキュメントが対象とする成果物の種類とメタドキュメントの適用で期待する目的を記載します。
メタドキュメントが適用される成果物が満たすべき条件とその理由
メタドキュメントが適用される成果物が満たすべき条件とその理由を記載します。メタドキュメントの内容を関係者間で合意する際に注目する内容です。以下のように箇条書きで条件と理由を簡潔に記載し、それぞれの項目で矛盾がないようにします。
成果物が満たすべき条件とその理由の記載例
- ドキュメントの冒頭に、ドキュメントの目的を記載してください。読み手に対し、(読み手)が期待する内容であるかの判断を補助する役割があります。
- ドキュメントのタイトルは、なるべく他と重複しないようにプロジェクト名や目的などを含めてください。検索機能で探しやすくするためです。
- アウトライン構造を意識して記載してください。アウトライン構造とは、見出しと本文による階層的な構成のことです。構造化により、論理的で一貫性のある文章を作成しやすくなります。また、読み手は文書の全体像を把握しやすく、必要な情報にすばやくアクセスできるようになります。
- 見出しは 見出し1 から使用してください。見出しはアウトライン構造を定義するためのものであり、見た目を理由に見出しを選択することは避けてください。
メタドキュメントが適用された成果物の例
メタドキュメントを適用した成果物の具体例を記載します。これにより、メタドキュメントに基づいて成果物を作成する際のイメージが明確になります。さらに、メタドキュメントの要求事項を実際の成果物にどのように反映すべきかの理解も深まります。
用語の定義(用語集)
メタドキュメントで使用される重要な用語とその定義を記載します。これにより、用語の解釈を明確にし、成果物での用語の使用方法を統一します。組織固有の用語はもちろん、一般的な用語であっても組織独自の解釈や制約がある場合は、必ず定義に含めてください。
メタドキュメントに対するFAQ
メタドキュメントの意図は可能な限り、メタドキュメントが適用される成果物が満たすべき条件とその理由で表現するべきです。ただし、条件とその理由を包括的に記載することが難しい場合や、条件の適用に判断の迷いが生じる可能性がある場合は、FAQとして補足説明を記載します。FAQは成果物作成者からの質問と、それに対するメタドキュメント作成者の回答という形式で構成します。
成果物レビューの結果をメタドキュメントに対するフィードバックとして反映する際にも、まずはFAQとして記載することが検討されます。
メタドキュメント作成時に参考した参考文献
メタドキュメント作成時に参照した文献の一覧を記載します。これは読み手がドキュメントの内容を深く理解する際の助けとなり、また情報が古くなった場合に更新が必要な箇所を判断するための材料としても活用できます。
メタドキュメントの例
以下はメタドキュメントの例です。メタドキュメントは人とAIの両方が参照し易いようにMarkdown形式で作成することが推奨されます。
運用手順書作成に関するガイドライン
本資料はシステム運用における運用手順書作成に関するガイドラインです。本システムの運用手順書を作成する際に遵守してください。本ガイドラインを基準とすることで、手順書として一貫性を保ち、読み手が様々な手順書を参照する際の理解を促進することを目的としてください。
# ガイドライン
* 手順は `1ステップ = 1アクション` で記載してください。実施すべき手順を読み手が誤解しないようにするためです。
* 手順のまとまりごとに結果確認手順を必ず記載してください。ヒューマンエラーを早期に検知しミスに気づきやすくするためです。
* コマンドや GUI 操作はコードブロックまたは図示で明示してください。認知負荷を下げ操作ミスを防止するためです。
* 可逆操作と不可逆操作を色分けまたは警告アイコンで区別してください。不注意による重大インシデントを撲滅するためです。
* 復旧手順(ロールバック)を必ず併記してください。障害発生時の平均復旧時間を最小化するためです。
# ガイドラインを適用したドキュメントの例
{ガイドラインを適用したドキュメントの例として参照すべき資料へのリンクを箇条書きで記載します。}
# 用語集
* GUI: Graphical User Interfaceのことです。ユーザがブラウザで操作するWeb画面や専用のクライアントアプリケーションで操作する画面を指します。テキストによるコマンドを入力して行う操作は、コマンドやCUIです。
* 可逆操作: 実行しても手順書の範囲内で元に戻せる操作です。操作ミスをしてもシステム運用に影響を及ぼさずに元に戻せる操作を指します。
* 不可逆操作: 実行すると即座にシステム運用に影響を及ぼそう操作です。操作ミスをした場合は、復旧手順を実行する必要がある操作です。
# FAQ
## スクリーンショットを使用してもよいですか?
問題ありません。ただし、UIによる操作に強く依存する手順は避けてください。コマンド実行などによるテキストによる手順記載を主とし、スクリーンショットは補助資料としてください。UI変更時に手順書が陳腐化することを避けるためです。
## 例外手順や特殊ケースはどこに記載すべきでしょうか?
本文中に混在させず、末尾に `例外対応` としてまとめてください。通常手順と混在させると、作業者が混乱するためです。通常手順と同一フォーマットで記載し、検索性と再現性を担保してください。
# 参考文献
{ガイドライン作成時に参考にした文献へのリンクを箇条書きで記載します。}
メタドキュメントの活用例
メタドキュメントは対応する成果物のドラフトを作成する際やレビューの際に、AIに支援を受けるための活用します。以下は利用可能なAIツール毎の活用例です。
ChatGPTなどのチャットツールでの利用
以下のようなプロンプトで成果物をレビューします。GPTsの利用が許可されているのであれば、メタドキュメント毎にGPTsを作成することも検討されます。なお、メタドキュメントを外部ファイルとして与えることは避けてください。レビューではメタドキュメントの全体を毎回参照する必要があるため、RAGで意図しないチャンクが参照されることを避けるためです。
Custom Instructionsに記載することも検討されますが、全ての会話に適用されます。ChatGPTのProject機能を利用できるエディションであれば、Projectに対するCustom Instructionsとしてメタドキュメントの内容を指定することが検討されます。
ユーザが指定した文章について、ガイドラインの内容に基づいてレビューを行い、以下の書式で指摘事項を日本語で出力します。
# Output Format:
> 指摘対象となる元の文
* 指摘事項1
* 指摘事項2
* 指摘事項n
# ガイドライン
{メタドキュメントの内容を全て記載してください}
OpenAI Codex/Github Copilotなどのプログラミング支援ツールでの利用
多くのプログラミング支援のAIエージェントでは、ガイドラインを記載するための形式が指定されています。以下のようなファイルにメタドキュメントの内容を記載することで、ソースコードの作成や支援でAIエージェントがメタドキュメントを参考にした動作をするようになります。
- OpenAI Codex: AGENTS.md
- Github Copilot: .github/copilot-instructions.md
- Cursor: .cursor/rules
FAQ
メタドキュメント作成における本資料の位置づけは何ですか?
本資料は、メタドキュメントを作成する際のガイドラインとして機能することを意図しています。
メタドキュメントとは何ですか?
メタドキュメントは、システム開発の成果物そのものではなく、成果物を生成・レビュー・保守するためのルールや品質基準を定めた上位概念のドキュメント群です。
どのようなタイミングでメタドキュメントを更新すべきですか?
レビューで得られたフィードバックの反映時だけではなく、新しい成果物の分類が確認された場合やアーキテクチャの変更、品質基準の改定など、運用プロセスや技術スタックが変わったときに合わせて更新します。定期的な見直しも推奨されます。
メタドキュメントの責任者は誰ですか?
原則としてプロダクトオーナー(従来型のプロジェクトの場合はプロジェクトマネージャーやシステムオーナー)が責任者となり、ドメインエキスパートと関係者を巻き込んで合意形成を行います。
既存の開発ドキュメントと重複しませんか?
重複を避けるために、メタドキュメントには 参照先へのリンクのみを置き、詳細な内容は既存ドキュメントに一元化します。ガイドライン自体はあくまで 統一ルールの集合体です。しかしながら、整合性を保つことが難しいため、できる限り早くメタドキュメントを整備することが推奨されます。
スモールスタートするにはどうすれば良いですか?
まずは最も影響範囲の大きい成果物のガイドラインを最小単位で作成し、運用ワークフローを実施します。効果を確認しながら適用範囲を広げていくアプローチが推奨されます。