プロジェクトドキュメント

ソフトウェアプロジェクトの全ドキュメントセットを作成・最新状態に保つためのスキルです。固定の構造と、AGENTS.md と MEMORY.md の間の固定の関係に従います。ユーザーがドキュメントをゼロから生成したい場合、変更後にリフレッシュしたい場合、またはファイル間で一貫性を保ちたい場合に使用してください。

対象構造

このスキルが管理するすべてのプロジェクトは、以下のレイアウトに収束する必要があります。

mi-proyecto/
├── README.md          # プロジェクトの概要、起動方法
├── AGENTS.md           # エージェント向けのルールと指示
├── MEMORY.md            # 現在有効な決定事項と破棄されたもの
├── CHANGELOG.md          # バージョン間の変更点
├── DESIGN.md             # ビジュアルデザインシステム（UIがある場合のみ）
└── docs/
    ├── architecture.md
    ├── plans/            # エージェントの計画、ファイルごとに一つ
    └── (OpenAPI + Scalar を API の /docs で提供)

プロジェクトにすでにこれらのファイルの一部が存在する場合は、まずそれらを読み込み、上書きせずにその場で更新します。ファイルがない場合は、以下の該当するテンプレートに従って作成します。

ワークフロー

既存ファイルの調査。 プロジェクトルートと docs/ をリストアップし、どのファイルがすでにあるかを確認します。既存の AGENTS.md/MEMORY.md/CHANGELOG.md/README.md/docs/architecture.md はすべて読んでください。これらは設計上短いものです。
スコープの特定。 ユーザーが特定のファイル名を挙げた場合（「CHANGELOGを更新して」など）、そこに焦点を当てますが、その変更が MEMORY.md や AGENTS.md に波及すべきかどうかも確認します（以下の伝播ルールを参照）。ユーザーが「プロジェクトをドキュメント化して」「ドキュメントを更新して」など一般的な要求をした場合は、上記の構造のすべてのファイルを確認します。
事実を収集 コードベース自体（パッケージマニフェスト、エントリポイント、スクリプト、ルート、最近のコミット）から必要な情報を入手します。推測はしません。コマンド、スタックの詳細、エンドポイントをでっち上げず、コードまたは設定ファイルを読んで検証します。
各ファイルを対応するテンプレートを使って作成または更新 します。AGENTS.md（約30～40行）と MEMORY.md（約50行）の厳格な行数制限を守ってください。これらは負荷のかかる制約であり、単なる提案ではありません。なぜなら、エージェントはセッションごとにこれらのファイルを再読み込みし、肥大化したバージョンは役に立たなくなるからです。
報告どのファイルを作成し、どのファイルを更新したか、また検証できなかった事項（例：「テストコマンドが見つからなかったので確認してください」）を報告します。

ドキュメント

README.md

人間向けに「これは何で、どうやって実行するのか」に答えます。references/readme-template.md を参照してください。実行/インストール/テストコマンドは、プロジェクトの実際のスクリプト（package.json、Makefile、pyproject.toml など）から直接取得してください。コマンド名を推測してはいけません。

AGENTS.md

このリポジトリで作業するコーディングエージェント向けの指示です。正確なセクションと順序については references/agents-template.md を参照してください。厳格な上限：合計約30～40行。すでにそれより長い場合、更新時のあなたの仕事は追加することと同じくらい トリミング することです。一時的な決定や進行中のメモのように読めるものは MEMORY.md に移動し、ここには永続的なルールのみを残します。

MEMORY.md

セッション間のメモリ：現在何が真実か、なぜ主要な決定が下されたか、何が試されて却下されたか、次は何か。references/memory-template.md を参照してください。厳格な上限：約50行。更新するときは積極的に整理してください。もはや重要ではないエントリは削除または圧縮し、ファイルが永久に肥大化しないようにします。

AGENTS.md と MEMORY.md の関係（これが核となる規則です。正確に理解してください）：

AGENTS.md には、エージェントがタスク開始時に MEMORY.md を読み、タスク終了時にそれを更新するように指示する短い「メモリ」セクションが含まれていなければなりません。以下の文言をベースとして使用し、プロジェクトがすでに別の表現をしている場合のみ適応します。

## メモリ
- 開始時は `MEMORY.md` を読み、プロジェクトの状態と下された決定事項を把握する。
- タスク終了時はそれを更新する：現在の状態、重要な決定事項（理由を含む）、避けるべきエラー。
- 簡潔に保つ（最大約50行）：もはや貢献しないものは要約または削除する。
- 何かが恒久的なルールになった場合は、メモリに残さず `AGENTS.md` に移動することを提案する。
- 機密データ（キー、トークン、個人データ）は決して保存しない。

AGENTS.md の「制限」セクションには ✅ 常に: 各タスク終了時に MEMORY.md を更新すること。 を含める必要があります。
伝播ルール: MEMORY.md は 今のところ 真実であるものを保持します。現在の状態、理由を含む決定事項、学んだ教訓、次のステップなどです。AGENTS.md は常に真実であるもの、すなわち恒久的なルール、規約、スタック、制限を保持します。MEMORY.md 内の何かが一回限りの決定でなくなり、恒久的なルールになった場合（例：「Xを使用しないことにした」が「絶対にXを使用しない」に変わった場合）、それを AGENTS.md に昇格させ、MEMORY.md から削除します。どちらかのファイルを更新するときは、常にこの昇格が発生すべきかどうかを確認します。
どちらのファイルにも機密情報、トークン、個人データを決して書き込まないでください。

CHANGELOG.md

「バージョン間で何が変わったか」に答えます。Keep a Changelog の規則に従います（各バージョンの下に Added/Changed/Fixed/Removed を新しい順に配置し、進行中の作業用に先頭に Unreleased セクションを置きます）。references/changelog-template.md を参照してください。更新時は、作業が行われるたびに Unreleased の下にエントリを追加し、ユーザーがリリースを示した場合にのみ、新しい日付付きのバージョンセクションを作成します。

DESIGN.md

「どのように見え、UIはどのように構築されるべきか」に答えます。ビジュアルデザインシステムで、UIを生成するエージェントが読みます。docs/ ではなくプロジェクトルートに配置され、AGENTS.md の隣にあります。オープンな Google Stitch DESIGN.md フォーマット（仕様: github.com/google-labs-code/design.md、現在 alpha）に従います。各ブロックのテンプレートと説明については references/design-template.md を参照してください。

ユーザーインターフェースがあるプロジェクトのみ（Web、モバイル、デスクトップ）。プロジェクトがUIのない純粋なAPI/CLI/ライブラリである場合は、これを作成せず、報告書でその旨を伝えます。
2層構造: 機械可読なトークン（colors、typography、rounded、spacing、components）を含むYAMLフロントマター（これらが規範的な値です）と、理由を説明するMarkdown本文。トークンは何を示し、散文は いつ、なぜ を示し、16進数コードを繰り返す代わりにトークンを名前で参照します。
セクションの順序は固定: Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts。これらの見出しは、ツールが名前で一致させるため、英語のまま正確に記述し（エイリアスとして Brand & Style、Layout & Spacing、Elevation も許容されます）、散文はプロジェクトの言語で記述します。セクションは省略できますが、並べ替えることはできません。見出しの重複はエラーです。追加のセクション（例：Iconography & Imagery、Motion、Accessibility）は許可されています。常に Do's and Don'ts の後に配置します。
値はコードから取得し、決して発明しないでください: Tailwindの設定、CSS変数（:root、globals.css）、UIライブラリのテーマファイル、読み込まれたフォント、Figma/DTCGトークンのエクスポート。プロジェクトにUIがあるが定義されたビジュアルアイデンティティがない場合は、値を提案し、報告書で「提案、確認してください」とフラグを立てます。
DESIGN.md がすでに存在する場合は、それを読み込み、その場で更新します。決して黙って上書きしないでください。色、フォント、スペーシングが変更されたときは、トークンをコードと同期させてください。
厳格な行数制限はありません（docs/architecture.md のようなリファレンスドキュメントです）が、各セクションは焦点を絞ってください：3～6個の箇条書きか短い段落。
検証: Nodeが利用可能な場合は、npx @google/design.md lint DESIGN.md を実行し、エラー（broken-ref）と妥当な警告（missing-primary、contrast-ratio、section-order）を修正します。それ以外の場合はユーザーにコマンドを伝えます。
AGENTS.md が存在し、DESIGN.md に言及していない場合は、ユーザーに（自分で適用せずに）UIエージェントがUIを生成する前に読むように、1行のポインターを追加することを提案します。AGENTS.md の約30～40行の制限に注意してください。

docs/architecture.md

「これはどのように構築されているか」に答えます。コンポーネント、データフロー、主要な設計上の決定とその理由、注目すべき制約。references/architecture-template.md を参照してください。これは、セッションごとに再読み込みされるものではなくリファレンスドキュメントであるため、他のドキュメントよりも長くなる可能性がある唯一のドキュメントですが、それでも長い散文よりも図と短いセクションを優先します。主要なコンポーネント/データフロービューには、役立つ場合にmermaidダイアグラムを使用します。

docs/plans/

エージェントが重要でないタスク（マルチステップ実装計画、移行計画、リファクタリング計画）の計画を生成する場合、それをチャットに残すだけでなく、ここに独自のファイルとして保存します。ディレクトリが存在しない場合は作成します。ファイル名は YYYY-MM-DD-short-slug.md（例：2026-10-03-add-payment-webhook.md）とし、時系列でソートされるようにします。各計画ファイルは自己完結型である必要があります：目標、アプローチ、ステップ、未解決の質問。完了した古い計画は削除しないでください。これらは履歴記録です。プロジェクトが「完了」マーカーを希望する場合は、ファイルを削除する代わりにファイルの先頭に1行のステータスノートを追加します。

APIドキュメント — OpenAPI + Scalar

これらは静的Markdownファイルではありません。APIから動的に提供され、通常は Scalar のAPIリファレンスレンダラーがOpenAPI仕様を読み取って /docs または /reference ルートで提供されます。APIドキュメントのセットアップまたは更新を求められた場合：

プロジェクトがすでにOpenAPI仕様を生成しているかどうかを確認します（フレームワークのデコレータ/アノテーション、openapi.yaml/openapi.json ファイル、または依存関係にすでにある仕様生成ライブラリ）。
仕様は存在するがScalarから提供されていない場合は、プロジェクトのフレームワーク向けのScalarミドルウェア/ハンドラを設定し（Scalarにはほとんどの一般的なバックエンドフレームワーク向けの公式統合があります。このエコシステムは急速に動くため、想定せずに現在のパッケージ名/APIを確認してください）、/docs にマウントします。
仕様がまだ存在しない場合は、既存のルート/ハンドラから生成します（ほとんどのフレームワークには、手書きのYAMLよりもそれを優先して、ルート定義/タイプからOpenAPIを導出するライブラリがあります）。その後にScalarを配線します。
フレームワークがコードから導出できる場合は、巨大な静的OpenAPI YAMLを手作業でメンテナンスしないでください。それはすぐに同期が取れなくなります。コードファーストの生成を優先します。
設定が完了したら、README.md に /docs URLを記載し、人間がどこで見つけられるかを把握できるようにします。

終了前のチェックリスト

AGENTS.md が約40行以下であり、MEMORY.md を指す「メモリ」セクションがある
MEMORY.md が約50行以下であり、AGENTS.md に属する恒久的なものが取り残されていない
README.md のコマンドが実際のプロジェクト設定に対して検証され、仮定されていない
CHANGELOG.md が Unreleased セクションを含むKeep a Changelog形式に従っている
DESIGN.md（プロジェクトにUIがある場合のみ）がプロジェクトルートにあり、そのトークンが実際のコードと一致し、セクションが正規の順序に従い、npx @google/design.md lint DESIGN.md がエラーを報告しない
docs/architecture.md が古いものではなく現在の構造を反映している
新しいエージェント計画が日付付きのファイル名で docs/plans/ の下に保存されている
どのドキュメントにも機密情報（キー、トークン、個人データ）が書き込まれていない

プロジェクトドキュメント管理