shipping-artifacts

成果物の作成：AI が生成したコードをレビュー可能にするドキュメント

目的

AI エージェントはコードをすばやく作成しますが、意図、つまりシステムが何をするべきか、誰に何が許可されているか、シークレットがどこにあるか、どのルールが実際に検証されているかを示す、永続的な記録を残しません。その記録がなければ、人間も監査エージェントも、コードを安全にリリースできるかどうかを判断できません。このスキルでは、レビュー可能性を取り戻すために必要な、最小限のドキュメントを定義します。

これらのドキュメントは、人間のレビュアーと次の AI コーディングエージェントという、2 種類の読者を想定しています。これらは、後続のあらゆる監査における意図された状態の側面です。セキュリティレビューやパフォーマンスレビューの質は、コードと比較できる意図の質に左右されます。

場所と名前：リポジトリの設定を優先する

このプラグインに記載されている場所、ファイル名、ドキュメント形式の規約は、すべてデフォルトです。ホストリポジトリ独自の設定を優先してください。何かを書く前に（システムドキュメント、カバレッジマップ、監査レポートを問わず）、その設定を確認します。

1. エージェント向けの指示 — AGENTS.md、CLAUDE.md、およびそれらが読み込む、または参照するもの。ドキュメントフォルダー、その中のファイル、各ファイルの管理者、日付の記録方法が記載されていることがよくあります。
2. ドキュメントの保存場所 — 既存の docs/、documentation/、または同様のフォルダー。
3. 既存の同等ドキュメント — ARCHITECTURE.md、docs/security.md、docs/env.md など、名前を問わず、以下のファイルのいずれかと同じ内容を扱うドキュメント。ファイル名ではなく、扱っている内容を基準に判断します。
4. 既存のテストカバレッジマップ — docs/test-coverage.md など、動作とそれをカバーするテストの対応関係を示すファイル。扱っている内容を基準に判断します。リポジトリのテスト方法を説明する TESTS.md や testing.md は、テスト方法のドキュメントであり、カバレッジマップではありません。
5. レポートの保存場所 — リポジトリが監査やレビューの出力をすでに保存している場所。

次に、以下のようにします。

• 確認した内容に従ってください。 リポジトリのドキュメント保存場所に書き込み、並行する新しいファイルを作るのではなく既存の同等ドキュメントを更新し、その命名規則と日付の規約を守ります。各ドキュメントに含める内容は変わりません。変わるのは保存場所と名前だけです。エージェント向けの指示に、ドキュメントの管理方法や管理者が記載されている場合は、それにも従ってください。
• リポジトリに設定がない場合に限り、プラグインのデフォルトを使ってください。 リポジトリのルートにある documentation/ にドキュメントを置き、以下のファイル名を使い、カバレッジマップは documentation/tests.md に、レポートは reports/<name>_{timestamp}.md に保存します。また、「更新日」の行は設けません（ファイルの履歴を正とします）。
• どちらに従ったかを明記してください。 出力には、書き込んだ場所とファイルをすべて記載し、それぞれがリポジトリの設定に従ったものか、プラグインのデフォルトに従ったものかを示します。
• 大文字・小文字だけが異なる名前のファイルは作成しないでください — TESTS.md の隣に tests.md を、architecture.md の隣に Architecture.md を作成する、といったケースです。Windows と macOS では同じファイルとして扱われるため、書き込みによって既存ファイルが上書きされます。それ以外の環境では2つのファイルが作成され、次回のチェックアウト時に競合します。ファイルを作成する前に、大文字・小文字を区別せずに確認してください。既存ファイルが同じ内容を扱っている場合は、それを使います。別の内容を扱っている場合（テスト方法のドキュメントであり、カバレッジマップではない TESTS.md など）は、そこには書き込まず、リポジトリ内に実際の同等ドキュメントがあればそれを使います。同等ドキュメントがない場合は、既存ファイルと名前が競合しないものを選びます。

このプラグイン全体を通じて、architecture.md や tests.md のような名前は、リポジトリがどこに、どのような名前で保存しているかを問わず、そのドキュメントを指します。

セットの構成

このセットは固定された一覧ではありません。小さなコアに、機能がある場合にのみ追加する条件付きドキュメントを組み合わせます。

• コアドキュメント — レビュー可能なアプリにはすべてこれらの構成要素があるため、必ず作成します。
• 条件付きドキュメント — アプリに実際にその機能がある場合のみ含めます。機能がない場合は、空のドキュメントを作り出すのではなく、architecture.md に「スケジュールされた処理なし — cron.md なし。」と1行だけ記載します。レビュー可能性は正直なマップによって生まれ、「Xは行わない」という情報もマップの一部です。
• ほとんどのドキュメントは、/document-app がコードからリバースエンジニアリングして作成します。例外は tests.md だけで、これは /derive-tests がほかのドキュメントから導出します。これはサブシステムの説明ではなく、検証マップです。

現在の状態について、過度に疑心暗鬼にならず、率直に記載してください。目的は正確なマップを作ることであり、問題がないと保証することではありません。各ドキュメントは短く、表や箇条書きを多用し、一般論は省きます。

コアドキュメント

各項目：既定のファイル名 · 1 行で示す目的 · 記録すべき内容 · レビュアーによる使い方。

1. architecture.md — システムの概要と、各要素がどのように連携するかを示します。

   • 記録すべき内容：プロダクトの概要と主な前提；技術スタック；認証／セッション／クレームがエンドツーエンドでどのように流れるか；信頼境界（例：サービスロールとクライアントの境界）；短い 既知のリスク／前提 リスト（各項目は一般的なチェックリストではなく、コード内で該当箇所を示す）；作成した他のすべてのドキュメントを掲載する「関連ドキュメント」インデックス。
   • レビュアーによる使い方：ルートドキュメントとして、他のすべてのドキュメントから相互参照します。

2. flows.md — 権限と副作用が実際に行使される一連のフローを示します。

   • 記録すべき内容：重要な各フローについて、実行者＋事前条件＋成功時の結果；UI → サーバー → データ → ジョブ → プロバイダー → エージェントをまたぐ手順；保護された各ステップにおける 認可チェック（どのクレーム／ロール／スコープを、どのリソースに対して使うか、想定される 拒否 ケース）；信頼境界の越境（ブラウザー→サーバー、サーバー→プロバイダー、ジョブ→アプリ、エージェント→ツール、Webhook→アプリ）；各ステップで生じる状態の変化と副作用（書き込み、キューに追加されるメール、起動されるジョブ、外部への呼び出し）。
   • レビュアーによる使い方：静的な permissions.md のマトリックスでは示せないランタイムの状態、つまり、認可が どこで、どの順序で 適用されるか、またどこで省略される可能性があるかを確認します。
   • PRD 化を防ぐルール： 権限、データの整合性、外部への副作用、金銭、プライバシー、運用上の安全性に関係しないフローは、ここに含めません。これはセキュリティ／運用マップであり、機能仕様ではありません。

3. permissions.md — 誰が何を許可されているかを示します。

   • 記録すべき内容：ロール／クレーム；スコープの導出元（トークンか DB か）；リソース × 操作 × ロールのマトリックス；行レベルセキュリティが適用されるテーブルと、コードによるチェックに依存するテーブル。
   • レビュアーによる使い方：アクセス制御の監査でコードと比較する基準となります。flows.md にはその適用状況を示し、こちらには静的な参照情報を示します。

4. variables.md — 設定とシークレットをリスクに対応付けます。

   • 記録すべき内容：名前 · 使用箇所 · スコープ（サーバー／クライアント）· ソース · ローテーション · リスクを記載した表；クライアント側にシークレットがバンドルされていないことの明示的な確認；本番稼働前チェックリスト。
   • レビュアーによる使い方：シークレット／PII 漏えいの可能性がある箇所と、インシデント対応時のローテーション計画を確認します。

5. tests.md — 文書化されたルールのうち、実際にチェックされているもの、提案にとどまるもの、何もチェックされていないものを示す検証マップです。

   • マップが誤ってすべて問題なしと読まれないよう、明確に分けた 3 つのセクションに記録すべき内容：
     • 既存のカバレッジ — 現時点で リポジトリにあるテスト。各テストを固定するルールに結び付け、希望的な一覧ではなく実態を反映します。
     • 提案するテスト — まだ作成されていない推奨ケース。テストの種類（自動化されたユニット／インテグレーション · ガード付きライブテスト · 手動レビュー）を明記します。
     • ギャップ — 検証が一切ない文書化済みルール。越境によって生じるリスクを基準に順位付けします。
   • 各行には、ユースケース → ルール → 期待される動作（拒否／否定ケースを含む）→ 根拠の出典（ドキュメント＋コード）→ 状態（既存／提案／なし）を記載します。また、リポジトリのゲートで必須となるチェックも記載します。ゲートポリシーにリポジトリが定める条件（例：ローカルコマンドと人による承認）、または条件が定められていない場合は、main へのマージを制限する CI チェックを示します。
   • レビュアーによる使い方：「文書化済み ＝ 実装済み」を運用可能な形で確認します。他のドキュメントが主張する各ルールが、現時点でテストによって固定されているか、提案にとどまるか、未検証かを示します。
   • /document-app ではなく /derive-tests によって作成されます。サブシステムから直接読み取るのではなく、他のドキュメントと既存のテストスイートから導出されるためです。

条件付きドキュメント（該当する機能がある場合のみ含める）

6. emails.md — システムが送信するすべての通知。アプリがトランザクションメールまたは自動メールを送信する場合のみ含めます。

   • 記載必須：キュー → プロセッサー → プロバイダーの経路、テンプレートとテンプレートが受け取る変数、再試行／バックオフの動作、送信に失敗した場合の確認先。
   • レビューでの用途：検証されていないテンプレート入力と、PII の露出範囲を見つけるため。

7. cron.md — すべてのスケジュール済み処理と、安全な運用方法。スケジュール済みジョブまたはバックグラウンドジョブが存在する場合のみ含めます。

   • 記載必須：ジョブ → スケジュール → 関数 → シークレット → 制限 → 再試行の一覧表、各ジョブが冪等性を保つ方法、内部呼び出しの認証方法、直近の実行履歴の確認先。
   • レビューでの用途：偽装可能なトリガーと、制限のないバックグラウンドジョブを見つけるため。

8. seo.md — シングルページアプリが SEO とソーシャルプレビューを処理する方法。一般公開、インデックス登録可能、またはボット向けのルートが存在する場合のみ含めます。

   • 記載必須：プレビュー方式（静的メタデータ／プリレンダリング／エッジ HTML）、ルート → SEO の必要性 → 公開データのみ、の一覧表、動的メタデータのサニタイズ方法、ボットと人間の振り分け方法。
   • レビューでの用途：公開データのみという要件への違反や、ボット向けルートでのメタデータへのインジェクションを見つけるため。

9. automation.md — 組み込みエージェントやその他の自動化経路。アプリに AI エージェント、LLM ワークフロー、ツール呼び出し、Webhook、または外部自動化が組み込まれている場合のみ含めます。

   • 自動化／エージェントごとに記載必須：トリガー＋所有者＋自動実行か承認後のみの実行か、読み取り可能な入力と呼び出し可能なツール／APIの正確な一覧（ツールの範囲そのものが厳格なガードレールです）、制御方針がどこにあるか（プロンプト）とプロンプト以外の厳格なガードレール、アプリに返す出力契約（スキーマ、検証、失敗時の処理）、アプリが所有する副作用とエージェントが提示する提案の区別、および制御手段（承認ゲート、監査／タイムラインのログ記録、レート制限、再試行、キルスイッチ）。
   • レビューでの用途：隠れた自動化経路を可視化し、エージェントが提案する内容とアプリが強制する内容の境界を明確にするため。これは、現代の AI 構築アプリで最もリスクの高い領域です。

注意事項

• 作成した各ドキュメントへの参照を、architecture.md の「関連ドキュメント」セクション（またはリポジトリに既存のドキュメント索引）に追加し、ドキュメント群を見つけやすい状態に保ちます。
• 該当しない条件付きドキュメントは作成せず、内容を創作する代わりに、その旨を1行で記載します。
• これらのドキュメントには例や完成済みテンプレートを含めないでください。記述するのは一般的な手法ではなく、このシステムです。
• エージェントの実行コンテキストファイル（リポジトリの構成上標準となる AGENTS.md または CLAUDE.md）は別の成果物です。これは、これらのドキュメントから導き出される指示であり、システムのドキュメントではありません。引き継ぎの段階で /ship-check がこの構成に従って作成します。ここでは作成しません。
• tests.md は /derive-tests が作成し、残りのドキュメントは /document-app が作成します。
• リポジトリの日付表記規則に従います。規則がない場合は、「更新日」の行を含めないでください。ファイルの履歴が正確な情報源です。