commerce-app-review

App Builder アプリをセルフレビューする

Adobe の Commerce 提出ガイドラインに照らしてローカルのアプリディレクトリをレビューし、各指摘事項を対話形式で確認します。まず必須のブロッカーを確認し、その後、推奨事項を確認します。

入力

• APP_PATH (任意) — アプリのルートへのパスです。既定値は現在の作業ディレクトリです。
• APP_TYPE (必須) — downloadable または non-downloadable です。ダウンロード可能なアプリでは、マーチャントがソースパッケージをダウンロードできます。ダウンロード不可のアプリは、Adobe Exchange からワンクリックで直接インストールされます。

手順

1. パスとアプリの種類を検証する

APP_PATH が指定されていない場合は、現在の作業ディレクトリを使用します。パスが存在し、ディレクトリであることを確認します。そうでない場合は、停止して次のメッセージを表示します。

Path not found. Please provide the path to the root of your app codebase.

APP_TYPE が指定されていない場合は、次のように質問します。

このアプリはダウンロード可能ですか、それともダウンロード不可ですか？

• ダウンロード可能 — マーチャントがソースパッケージをダウンロードし、自分でデプロイします
• ダウンロード不可 — マーチャントが Adobe Exchange からワンクリックで直接インストールします

両方が確認できるまで、先に進まないでください。

aio がインストールされているか確認します（例：command -v aio）。これは存在確認のみです。この段階では認証を試みないでください。aio が見つからない場合は、次のメモを一度だけ表示します。

Note: aio isn't installed. Walkthrough enrichment (Step 8) will use fallback knowledge unless aio is installed and authenticated before then.

どちらの場合も続行します。

2. ローカルの参照資料を読み込む

references/finding.md と references/exceptions/ 以下のすべてのファイルを読み込みます（パスはこのスキルファイルからの相対パスです）。

パターンファイルは条件に応じて読み込みます。

• references/patterns/cors-storefront-actions.md — 常に読み込む
• references/patterns/accs-rest-api-dependency.md — 常に読み込む
• references/patterns/aio-commerce-sdk.md — 常に読み込む
• references/patterns/admin-ui-sdk.md — commerce/backend-ui/1 が app.config.yaml または ext.config.yaml にある場合、または @adobe/uix-guest／@adobe/uix-core が package.json にある場合のみ

パターンファイルは、取得したガイドラインより優先されます。例外ファイルは、どちらからの指摘事項も抑制します。

ファイルが見つからない場合は、スキップして続行します。

3. ガイドラインを取得する

curl を使用して、両方のページを取得します。レンダリングされた developer.adobe.com のページには確実にアクセスできないため、GitHub の raw URL を使用してください。

• 提出ガイドライン：https://raw.githubusercontent.com/AdobeDocs/commerce-extensibility/refs/heads/main/src/pages/app-development/app-submission-guidelines.md
• Admin UI SDK チェックリスト：https://raw.githubusercontent.com/AdobeDocs/commerce-extensibility/refs/heads/main/src/pages/admin-ui-sdk/app-review-checklist.md — commerce/backend-ui/1 が app.config.yaml または ext.config.yaml にある場合、または @adobe/uix-guest／@adobe/uix-core が package.json にある場合のみ

ページにアクセスできない場合は、取得に失敗したページを記録し、もう一方のページを使って続行します。また、対象範囲が一部のみであることをユーザーに警告します。

4. アプリを読み取る

次のファイルを順番に読み取ります。

1. app.config.yaml — 拡張ポイント、アクション、入力、注釈、productDependencies
2. package.json — name、description、author、version、dependencies、scripts
3. env.dist／env.example／ルートにある任意の env.* — ドキュメント化された環境変数
4. README.md — インストール手順、イベント、API 要件
5. deploy.yaml — アプリ ID、API、ワークスペース
6. install.yaml — 拡張ポイント（Admin UI SDK が検出された場合）
7. src/ および actions/ 以下のすべての *.config.yaml
8. actions/ 以下のすべての index.js
9. web-src/src/ — UI コード、innerHTML、ルーティング
10. extension-manifest.json — Admin UI SDK が検出された場合

ファイルが存在しない場合は、その旨を記録して続行します。

5. レビュー

パターンファイルと取得したガイドラインから、すべてのチェック項目をリストアップします。その後、各項目を一つずつ黙って確認してください。項目を飛ばしてはいけません。

以下は完全に除外し、チェックしないでください。

• npm audit、npx npm-check、または npm の実行が必要なチェック
• Exchange の掲載 URL、リポジトリの公開設定、Exchange の掲載ページのスクリーンショット
• Exchange の掲載ページ、デプロイ済み環境、または外部 URL が必要なチェック

各項目について：

• Step 4 で読み込んだファイルと照合します
• 確認できた場合 → 重要度、ファイル、行番号を付けて FINDING として記録します
• references/exceptions/ の例外が該当する場合 → 対象から除外します
• APP_TYPE に該当しない場合 → スキップします

FINDING を記録する前に、実際のファイルで確認してください。具体的なファイルと行番号を示せない場合は、指摘しないでください。

パッケージの不足を指摘する前に、推移的な依存関係としてではなく、ソースファイルで直接インポートされていることを確認してください。

すべての項目を確認した後、FINDING をすべて集め、コードを割り当てます：MUST-<n> および NICE-<n>。コードを割り当てる前に、関連性の高い FINDING をまとめてください。

各 FINDING について、以下を記録します。

• SEVERITY — MUST または NICE
• DESCRIPTION — 具体的で実行可能な内容を、一文で記述します
• FILE_PATH — 該当ファイルへの絶対パス。全般的な問題の場合は空にします。Markdown リンクとして表示します：relative/path
• LINE_NUMBER — 該当する行番号。全般的な問題の場合は 0
• CATEGORY — 次のうち 1 つ以上：security · documentation · code · dependencies · other

6. FINDING の一覧をそのまま表示する

簡潔な FINDING の一覧を表示します。まだ補足情報は追加しません。 次の形式を使用します。

Found N MUST-have issue(s) and M NICE-to-have recommendation(s).

**MUST — blockers**
- MUST-1: <one-line description> (`<FILE_PATH>`, line <LINE_NUMBER>)
- MUST-2: …

**NICE — recommendations**
- NICE-1: <one-line description> (`<FILE_PATH>`, line <LINE_NUMBER>)
- NICE-2: …

グループに該当項目がない場合は、グループ見出しを省略します。FILE_PATH が空の場合は、ファイルへの参照を省略します。

一覧の後に、次を表示します。

各 FINDING の説明を順に確認するには walkthrough と入力してください · 特定の FINDING の詳細を確認するには MUST-n または NICE-n と入力してください · または、何でも質問してください。

その後、ユーザーの応答を待ちます。

7. ユーザーへの応答

• 「walkthrough」（または同様の意図）→ Step 8 に進みます
• FINDING のコード（例：「MUST-2」、「NICE-1」）→ その FINDING の詳細を追加して提示し、操作案内を再度表示して待ちます
• その他 → 回答し、操作案内を再度表示して待ちます

ユーザーがセッションを終了するか、すべての FINDING の確認が完了するまで繰り返します。

8. ウォークスルーモード

すべての FINDING を順番に確認します。まず MUST、その後 NICE の順です。開始する前に、IMS トークンを取得します（以下を参照）。

• グループに該当項目がない場合は、その旨を伝えて次に進みます。
• 各 FINDING について、コード順に次を行います。
  1. 番号付きの見出しを表示します（例：--- MUST issue [n/N] ---）
  2. FINDING の詳細を追加して表示します
  3. 次を表示します：この FINDING の対応を一緒に進めるには "resolve it" · 次に進むには "next" · または、何でも質問してください
  4. ユーザーの応答を待ちます

最後の FINDING の後に、解決済みの FINDING 数（例：「X of N+M findings resolved」）を含む、短く励ましとなるメッセージで締めくくり、開発者の幸運を祈ります。

---

IMS トークンの取得

セッションごとに 1 回、初めて詳細情報が必要になったときに実行します。

IMS_TOKEN=$(aio auth login --bare 2>/dev/null)

• $IMS_TOKEN が空でない場合 → ドキュメントエージェントを使って詳細情報を追加します。
• 空の場合 → ユーザーに警告します。最適な体験のために aio login を実行して再起動するよう案内し、詳細情報を追加せずに続けるか、停止するかを尋ねます。

FINDING の詳細情報を追加する

1. IMS トークンを利用できる場合は、ドキュメントエージェントに問い合わせます。

curl -s -X POST https://commerce-docs-prod-endpoint-d0ctgyebe7bec8e6.a02.azurefd.net/api/query \
  -H "Authorization: Bearer $IMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "<topic derived from the finding>", "count": 5}'

カテゴリーに基づいて index を選択します。

• security、deployment、code → app-builder-docs
• documentation、dependencies → commerce-extensibility-docs
• それ以外 → index を省略

2. FILE_PATH と LINE_NUMBER が示す実際のファイルを読みます。一般的な例ではなく、開発者のコードに即した具体的な修正前・修正後の例を作成します。

3. references/finding.md の形式を使用して、詳細を追加した FINDING を作成します。

エージェントから結果が返されない場合は、App Builder / Commerce の知識を使用して続行します。

失敗時の対応

• パスが見つからない → 停止して報告し、先に進まない
• ガイドラインのページにアクセスできない → 失敗したページを明記し、もう一方のページで続行する。カバー範囲が部分的であることを警告する
• aio がインストールされていない、または認証されていない → ユーザーに警告し、aio login を実行するよう案内する。補足情報なしで続行するか、停止するかを尋ねる
• ドキュメントエージェントから結果が返されない → App Builder / Commerce のナレッジに切り替える。停止しない