bagisto-documentation

Bagisto ドキュメント

Bagisto のドキュメントは、コードベースとは別のリポジトリにあり、対象読者ごとに分かれています。どのサイトも同じ方法で構築された VitePress サイトなので、このスキルに記載された手順は、開発者向けドキュメント、マーチャント向けユーザーガイド、今後追加されるガイドのすべてに適用できます。

ステップ 1：読者を決める

ほかのすべてはこれを基準に決まるため、書き始める前に判断してください。たまたま開いているリポジトリではなく、対象読者を基準に判断します。リポジトリにはどちらの読者向けのページも含まれる可能性があり、判断を誤ると、技術的には正確でも、訪れた読者にとって役に立たないページになってしまいます。

質問	はいの場合	読み込むファイル
読者は Bagisto 向けのパッケージ、テーマ、連携機能、API クライアントのコードを書きますか？	開発者向けドキュメント	developer-docs.md
読者はコードに触れずに、管理パネルからストアを運営しますか？	ユーザーガイド	user-guide.md

両方が必要に思える場合は、ページを 2 つに分けてください。クラス名について読むマーチャントは読み飛ばし、クリック手順について読む開発者はページを信頼しなくなります。対象読者ごとに分け、相互にリンクしてください。

新しいドキュメントリポジトリ（マーケットプレイスガイドやセルフホスティングガイドなど）ができた場合も、新しい名前のどちらかの読者を対象としています。同じ方法で判断し、同じリファレンスを使ってください。

ステップ 2：推測せずにリポジトリを探す

各サイトはBagisto アプリ内のフォルダーではなく、独立したリポジトリなので、編集する前に場所を確認してください。

find . ~ -maxdepth 6 -type d -path '*/src' -path '*doc*' 2>/dev/null | head

クローンされていない場合は、ユーザーにパスを尋ねるか、クローンを依頼してください。場所を決して作り上げず、誤って Bagisto アプリ内にページを書かないでください。アプリには src/ のドキュメントツリーがないため、そこに作成したページは気付かれないまま失われます。

執筆前に周辺ページを読む

追加先のセクションにある既存ページを 2～3 件開き、詳しさ、見出しの流れ、文体を合わせてください。記載された事実がすべて正しくても、周辺ページと読み味が異なるページは不備です。

同時に重複も確認してください。トピックがすでに一部扱われている場合は、別の情報源を作るのではなく、そのページを拡充するか、相互リンクを追加してください。同じ質問に一部ずつ答える 2 つのページは、時間が経つと内容が食い違います。

リファレンスファイル

ファイル	読み込むタイミング
developer-docs.md	コードを書く読者向けに執筆するとき — 文体、構成、コードサンプル
user-guide.md	ストアを運営する読者向けに執筆するとき — 文体、ページ構成、手順
screenshots.md	ページに画像が必要なとき — 撮影、クリーンなセットアップ、命名
publishing.md	ページを追加、移動、削除するとき — サイドバー、リダイレクト、検証
site-structure.md	ドキュメントリポジトリの構成を確認するとき — レイアウト、コマンド、サイトごとの差異
common-mistakes.md	変更を仕上げた後に監査するとき

すべてのサイトは VitePress サイトです。ページは src/ 以下、サイドバーは .vitepress/config.mts、旧 URL は .vitepress/_redirects.ts にあります。npm run docs:dev でプレビューし、npm run docs:build で合格を確認してください。サイトによってコンポーネントとリダイレクトのプレフィックスが異なるため、対象サイトについては site-structure.md を確認してください。

必ず守ること

• 1 人の読者に向けて書いてください。 手順 1 で決めた対象読者によって、用語、説明する内容、前提とする知識が決まります。これが、ドキュメントページの良し悪しを左右するルールです。
• 公開済みの URL は決して壊さないでください。 ファイル名の変更、別セクションへの移動、スラッグの変更、ページの分割や削除など、ページの URL が変わる可能性がある場合は、.vitepress/_redirects.ts に古い URL をコンテンツの新しい場所へ転送するエントリーが必要です。また、古い URL を指していた既存のリダイレクトもすべて転送先を変更してください。リンクは誰も更新してくれません。publishing.md を参照してください。
• その URL を維持しているページは、先にその URL をリダイレクトでカバーしない限り、決して削除しないでください。 レガシーパスを解決可能な状態に保つためだけに存在するページもあります。不要に見えても、重要な役割を担っています。
• ナビゲーションはサイドバーのみです。 .vitepress/config.mts の sidebar 配列にないページへは、URL を直接入力しないとアクセスできません。ページの追加と同じ変更でエントリーも追加してください。
• ファイル名はすべてケバブケースにしてください。 ページも画像も、小文字とハイフンのみを使い、スペース、キャメルケース、アンダースコアは使いません。古いファイルはこのルールができる前のものです。周囲のファイルではなくルールに従い、作業中に関係のないファイルの名前を変更しないでください。
• 既存ページを読む前に実装を確認してください。 更新するページの説明は、機能の移動、名称変更、削除により、すでに古くなっている可能性があります。コード、設定ファイル、言語ファイル、稼働中の管理画面から確認を始め、古い文章は情報源ではなく仮説として扱ってください。
• 記憶ではなくコードベースに照らして記述を検証してください。 自信たっぷりの誤った記述は、信じられてしまうため、ページがないよりも悪い結果を招きます。ページに記載するコマンド、パス、設定キー、クラス、メソッド、ルート、ラベル、動作はすべて、このセッションでファイルを読んだりコマンドを実行したりして確認してください。ファイルを開き、コマンドを実行し、文字列を確認してください。
• コードサンプルには Pint を適用してください。 PHP サンプルは、プロジェクトの pint.json（laravel プリセット）が整形する形式に完全に合わせてください。=> の前後にはスペースを 1 つ入れ、末尾にカンマを付け、インポートを並べ替え、列を揃えるためのスペースは入れず、本番用の Bagisto コードのように記述します。目視で判断せず、抜き出したサンプルに Pint を実行してください。手順は developer-docs.md に記載されています。
• 順序のある操作は番号付きの手順にしてください。 読者が複数の作業を順番に行う必要がある場合は、目的を示す見出しの下に、各手順で 1 つの操作を記載した番号付きリストを作成してください。「X に移動し、Y をクリックして、Z を入力して保存する」のように複数の操作をつなげた文章は、マーチャント向けの不備であり、開発者向けの文章としても好ましくありません。順序が関係しない選択肢、特性、前提条件には箇条書きを使ってください。
• リリースをまたいでドキュメントを 1 つにまとめてください。 バージョン別のページツリー、「2.5 ベータ」というラベル、「現在の開発バージョン」という表現は使いません。現行リリースは Bagisto 2.5 と呼びます。リリースによって動作や利用可否が異なる場合に限り、現行の動作を記載した段落内でリリース名を明記してください。これにより、次のリリース後もページを正確に保てます。developer-docs.md の「Versions」セクションを参照してください。
• AI 用語は実装に基づいて使ってください。 「Generative AI」はコンテンツを生成する機能に使います。ページや見出しでは「Generative AI (Magic AI)」と表記し、「Magic AI」単独の表記は管理画面独自のラベルとパッケージに限ります。「Agentic AI」は、エージェントがツールを通じて操作する機能（WebMCP、スキルを使うコーディングエージェント）に使います。コードで実現されていない自律性を主張してはいけません。Magic AI は管理者の操作なしに何も適用しません。両方のリファレンスファイルにある AI のセクションを参照してください。
• ユーザーガイドはマーチャントの利用の流れに沿って構成し、Configure は管理者自身が見る Configuration 画面に沿って構成してください。 マーケットプレイスガイドには 3 種類の読者がいます。設定ページは古いページではなく、config('core') ツリーを起点にしてください。それぞれの詳細は user-guide.md の該当セクションを参照してください。開発者向けドキュメントのナビゲーションは、ユーザーからの依頼がない限り再編成しません。
• 最後に第三者の視点で監査してください。 編集後は、執筆者ではないレビュアーの視点で結果を検証してください。すべての記述をコードと照合し、すべてのサンプルに Pint を適用し、すべてのリンクと画像が解決されることを確認し、サイドバーと llms.txt の整合性を確かめてから、ビルドを実行し、最後に common-mistakes.md を確認してください。書いただけで検証していない変更は、確認済みではありません。
• llms.txt と llms-full.txt は手動で作成します。 自動生成するものはありません。ページの追加、移動、削除に伴い、これらのファイルも編集してください。
• ビルドは必須の確認工程です。 npm run docs:build は、書き込むリダイレクトをそれぞれ報告します。ビルドしていない変更は、確認済みではありません。 必須のサブスキル： 変更完了と判断する前に、bagisto-change-verification を使用してください。