AI を活用した開発が当たり前になりつつある今、皆さんのプロジェクトではドキュメント管理をどうしていますか？
今回のプロジェクトに取り組むにあたり、「バラバラな部署から集まった開発メンバーでもドキュメントを整理しやすい形」を目指してドキュメント基盤を整備しました。

なぜドキュメント基盤が重要なのか

従来の課題

  • 開発メンバーのスキルレベルや経験がバラバラ
  • ドキュメントの置き場所や形式が統一されていない
  • プロジェクト固有のルールを理解しにくい
  • レビュー時に「このドキュメントはどこに置くべき？」という議論が頻発

目指したゴール

  • AI がプロジェクトのルールを理解できる構造
  • 誰が書いても同じ品質を保てる仕組み
  • 迷わないディレクトリ構造とガイドライン

ドキュメント基盤の全体像

1. 階層化されたディレクトリ構造

プロジェクトのドキュメントを以下のように階層化しました。

project-root/
├── docs/               # すべてのドキュメントをここに集約
│   ├── 01.チーム/      # チームのミッション・体制・ロードマップ
│   ├── 02.プロダクト/  # プロダクトの要件定義・設計・テスト
│   ├── 03.開発/        # 開発ガイドライン・環境構築
│   └── 04.調査/        # 競合調査・要求定義など（自由度高め）
└── files/              # 画像データ

この分け方により、プロジェクトの全ライフサイクル（企画・調査・設計・開発・運用）をカバーしながら、「今探している情報はどこにあるか」が直感的に分かるようにしました。
さらに、ディレクトリ名を見れば「何のためのドキュメントか」が一目で分かるため、新しいメンバーが「このドキュメントはどこに置けばいいだろう？」と悩むことがなくなるという狙いもあります。

  • 01.チーム/ → 誰が、なぜ、どこに向かうのか（プロジェクトのコンテキスト）
  • 02.プロダクト/ → 何を作るのか（成果物の仕様）
  • 03.開発/ → どう作るのか（開発プロセス）
  • 04.調査/ → なぜそう判断したのか（意思決定の根拠）

各ディレクトリがこのように明確な役割を持つことで、AI ツールも適切な場所にドキュメントを自動生成できるようになり、レビュー時の配置ミスも防げます。

2. シンプルで明確なドキュメント規約

ドキュメントの形式は、自分たちの枷になってしまうような複雑さは避け、最小限のルールに絞りました。
また、関連タスクの項目を設けて、課題管理ツールとして利用している Backlog と紐付けることで、「なぜこのドキュメントが作られたのか」という背景が追いやすくなるようにしています。

# 本ドキュメントについて

本ドキュメントは〇〇について記載している。

# コンテンツ

（実際の内容）

# 関連タスク

- [課題番号](リンク)

さらに、AI にドキュメントを書かせることを前提とした設計を重視しているため、以下の方針を採用しています。

  • 図は Mermaid で記述：基本的に PowerPoint や Excel での図作成は避け、テキストベースの Mermaid を使用
  • すべて Markdown：エンジニアライクな記法で統一し、AI が理解・生成しやすい形式に
  • テキストファースト：バイナリファイルを避け、すべてテキストで管理

これにより、AI がドキュメント全体を理解し、一貫性のある形で生成・修正できるようになります。

3. AI エディタへのルール適用

このドキュメント整理の最大の特徴は、AI エディタへのルール適用です。
Cursor Rules や CLAUDE.md といったルールファイルを通じて、Cursor や Claude Code などの AI エディタにプロジェクト固有のルールや制約を教えることができます。

本プロジェクトでは、現段階では私が使い慣れている Cursor Rules を採用しています。
将来的に Claude Code を使用する可能性もあるため、同様の内容のルールファイルを配置し、どちらにも対応できる体制にしています。
以下が実際のルールファイルの例です。

.cursor/rules/main.mdc

---
description:
globs:
alwaysApply: true
---
本レポジトリはプロジェクトのドキュメントを管理するレポジトリである。

以下のルールに従うこと。

[ルール]

  [ドキュメントルール]
    [基本ルール]
    "docsフォルダ配下"のマークダウン形式のドキュメントは
    [ドキュメント規約.md](mdc:docs/03.開発/01.ガイドライン/ドキュメント規約.md)
    に記載されているルールに従うこと。

    [対象外フォルダ]
    以下のフォルダーについては、ドキュメントルールの対象外とすること。
      - docsフォルダ配下以外
      - docs/04.調査

  [Gitワークフロールール]
    [基本方針]
    本プロジェクトのGit運用は
    [Gitワークフロー規約.md](mdc:docs/03.開発/01.ガイドライン/Gitワークフロー規約.md)
    に従うこと。

このルールファイルにより、AI がドキュメントを生成・修正する際に自動的にドキュメント規約に従うようになりました。
特に、ルールファイル自体はシンプルに保ちながら、詳細なルールは別ファイルで管理できるため、メンテナンス性が高いところがメリットです。
現在はルールを整備している最中なので簡単な内容となっていますが、プロジェクトの進行とともにチームメンバー全員で育てていきたいと考えています。

実践してみて分かったこと

まず、初期メンバー間の認識統一が図れた点が大きな成果でした。
バラバラな部署から集まったメンバーがそれぞれ異なる開発文化を持っていましたが、明確なドキュメント構造とルールを定めることで、「このプロジェクトではこうする」という共通認識を早期に形成できました。

この整備により、将来的に新メンバーが参加する際も「次に何を読めばいいか」が自明になります。
README.mdから始まり、docs/01.チーム/でプロジェクトの全体像を把握し、docs/03.開発/01.ガイドライン/で開発ルールを理解する…という流れで、スムーズに作業を開始できる体制が整いました。

そして、AI がドキュメントを自動整形してくれる点も大きなメリットです。
これまで、こういったドキュメントの整備は人力では大変でしたが、AI がドキュメント規約に従った構造で生成し、適切な場所に配置し、既存ドキュメントとの整合性も保ってくれるため、非常に楽になりました。
加えてレビューも効率化できるので、まさに一石二鳥です。

終わりに

AI エディタの登場により、これまで大変だったドキュメント整備が簡単に、そして楽しくできるようになりました。
このような基盤を最初に整えておくことで、プロジェクトが大きくなってもドキュメントが混沌とせず、AI と人間が協調して効率的に開発を進められますね。
ドキュメント規約はチーム全員が納得して守れるものにすることが重要なので、形骸化しないように定期的な振り返りを怠らず、引き続き進めていきたいと思います！