このページの目次

このページの目次

必須のプロジェクトドキュメント

すべてのプロジェクトは、AGENTS.md、README.md、DEVELOPMENT.md、CONTRIBUTING.md を維持しなければならない。重要なアーキテクチャ上の境界を持つプロジェクトでは、ARCHITECTURE.md も必須とする。出発点として、templates/ 配下のテンプレートを使用すること。

ドキュメントの役割分担は Diátaxis に基づく。README はプロジェクトを紹介し、関連するドキュメントへ読者を案内する。DEVELOPMENT.md と CONTRIBUTING.md は利用方法と参考資料、ARCHITECTURE.md は解説、AGENTS.md はエージェント向けの参考資料を担う。1 つのドキュメントが担うモードは 1 つとし、別のモードの内容が必要になったら、それを担うドキュメントへリンクすること。1 つのファイルに混ぜないこと。

AGENTS.md

すべてのプロジェクトは、リポジトリのルートに AGENTS.md を置かなければならない。

これはエージェント向けの入口である。コマンド、エンジニアリング標準、リポジトリの構成、境界、確定した言語ポリシー、プロジェクトの規約を記述する。

書き方のルール(記載内容の振り分け、セクション順、長さの上限、ネストしたファイル)は、AGENTS.md の執筆で定める。

テンプレート:project-agents.template.md

README.md

すべてのプロジェクトに README.md を含めること。

README はプロジェクトの表玄関であり、読者がまず流し読みすることを前提に書く。最初の画面で、プロジェクトが何であるか、どんな課題を解決するか、どう動かすかを示す。読者を導き、適切なドキュメントへ案内するのが README の役割であり、チュートリアル、仕様の羅列、背景の解説は詳細ドキュメントが担う。エージェント向けのルール(エンジニアリング標準、確定した言語ポリシー、プロジェクトの規約)は AGENTS.md に記述する(templates/project-agents.template.md を参照)。README には、エージェントに AGENTS.md を参照させる、コピー可能な指示文を載せる。

本文は、リポジトリのディレクトリ構成ではなく読者のタスクに沿って構成する。Why セクションは単独に設けず、次の順序に従うこと。

  • 識別ブロック:プロジェクト名、内容と対象者を一文で示すタグライン、ステータスバッジ。続けて、プロジェクトが解決する課題を平易な 1〜3 文で示す。意図的に行わないこととステータスは、読者の時間を節約できる場合に限り言及する。
  • UI、CLI 出力、生成物など見て取れる出力がある場合は、冒頭の直後にスクリーンショットまたは短い GIF を置くこと。
  • 使い始め方を示すセクションは 1 つだけ置く。開発者の関与が必要なプロジェクトは Quick Start、エンドユーザー向け製品は Usage、両方に当てはまる場合は Usage / Quick Start とする。セクションの先頭には AI 経路を置く(AGENTS.md 経由でリポジトリを AI コーディングエージェントに引き渡す、コピー可能な指示文)。続けて手動の手順を示す。前提条件(ツールチェーン、対応プラットフォーム、固定バージョン)、コピーしてすぐ実行できるコマンド、期待される結果を含めること。エンドユーザー向け製品では、最も一般的な 2〜3 の使い方を期待される出力付きの例で示す。
  • Quick Start と Learn More の間には、プロジェクトに必要な紹介セクションだけを置く。優先して示したい内容から順に並べ、各セクションに標準のタイトルと絵文字を 1 つ付ける。
    • Concepts:読者が押さえるべき少数の概念。
    • Features:何をするか、なぜ重要か、代替案との相違。
    • Performance:性能についての主張を一文で示し、それを裏付ける図表または表、計測環境、計測方法へのリンクを添える。数値による裏付けのない主張はしない。
    • Experiments:プロジェクトに実験がある場合、その内容。
  • 詳細ドキュメントへリンクする「目的 → 読むドキュメント」表。
  • 明示的に示すライセンス。

セクション見出しには、標準的で短く、読者がすぐ分かる名前を使う。Quick Start、Usage、Concepts、Features、Performance、Experiments、Learn More、License が基本のセットである。各見出しの先頭には、意味のぶれない絵文字を 1 つ付ける。使い始め方を示すセクションには 🚀、概念には 💡、機能には ✨、性能には ⚡、実験には 🧪、詳しく学ぶセクションには 📚、ライセンスには 📄 を使う。絵文字は少なく統一し、プロジェクトタイトルと本文の文章には使わないこと。

長い補助的内容(プラットフォーム固有のセットアップ、環境変数表、拡張例、トラブルシューティング)は <details> ブロックに折りたたむ。<summary> は内容を数語で示し、Markdown が正しく描画されるよう直後に空行を 1 つ入れること。重要な部分は決して折りたたまない。冒頭、使い始め方のコマンド、ライセンスは常に展開しておくこと。

読みやすさを保つこと。段落は 1〜3 文とし、箇条書きの各項目には 1 つの内容だけを記載する。コピー可能なコマンドはコードブロックに入れる。列挙は長い文章ではなく、リストか表で示す。詳細ドキュメントと内容が重複しないよう、そちらへ誘導する。チュートリアル、参考資料、解説は詳細ドキュメントのモードであり、README のモードではない。ただし、README を「ドキュメントを参照」の一行だけに縮めてはならない。README だけで入口として機能しなければならない。長さが数画面を超えるようになったら目次を付けること。

古い README は無いより悪い。読者を誤った方向へ導いてしまうからである。セットアップ、使い方、スコープが変わる変更では、README も同じ変更の中で更新すること。開発が停滞または停止した場合は、冒頭で明示すること。

確定したプロダクト/UI の言語ポリシー(言語ポリシーを参照)はエージェント向けである。AGENTS.md に記録し、README には記載しないこと。

テンプレート:README.template.md

DEVELOPMENT.md

すべてのプロジェクトに DEVELOPMENT.md を含めること。

開発ワークフローを手順に沿って説明し、その後にコマンドと設定の参考資料を置くこと。

次の内容を記載すること。

  • 開発ワークフロー
  • ツールチェーン
  • よく使う mise タスク
  • コーディング規約
  • テストワークフロー
  • ローカル環境のセットアップ
  • 検証ワークフロー
  • 必要に応じたデプロイワークフロー

人間と AI エージェントの双方が、開発の進め方を理解できるようにすること。

テンプレート:DEVELOPMENT.template.md

CONTRIBUTING.md

すべてのプロジェクトに CONTRIBUTING.md を含めること。

このドキュメントは、変更を送ってからマージされるまでの手順を順に示す。背景解説の長文は書かないこと。

次の内容を文書化すること。

  • コントリビューションにあたっての要件
  • 必要に応じた Issue のワークフロー
  • プルリクエストのワークフロー
  • レビュー要件
  • 必須の検証
  • コミット規約

すべてのプルリクエストの説明文には、次の内容を明確に含めること。

  • 変更の目的
  • 変更の影響
  • 関連する文脈や背景
  • 潜在的なリスクや懸念
  • 実施したテストまたは検証

GitHub のプルリクエストテンプレートは、これらの要件との同期を保つこと。

テンプレート:CONTRIBUTING.template.md

ARCHITECTURE.md

重要なアーキテクチャ上の境界を持つプロジェクトでは、ARCHITECTURE.md を維持すること。

内容は短く実用的に保つ。簡潔な概要、大まかなコード構成(モジュール名だけを示し、個別ファイルにはリンクしない)、アーキテクチャの不変条件を記載する。

この文書の役割は、境界を設けた理由を説明してアーキテクチャの意図しない崩れを防ぐことであり、網羅的なリファレンスや抽象的な理論書にすることではない。

不変条件と ADR の運用は、アーキテクチャガバナンスで定める。

テンプレート:ARCHITECTURE.template.md