contentful-custom-app-enhancement

Contentful カスタムアプリの改善

バグ報告、サポートメモ、機能リクエストを、既存の Contentful カスタムアプリに対する小規模でレビューしやすい改善にするために、このスキルを使用します。

ユーザーのアプリリポジトリとワークフローをデフォルトとします。ユーザーから提示がない限り、特定のリポジトリ規約、公開プロセス、レビュー方針を前提としないでください。

比較対象となる Contentful Marketplace の公開アプリ、または Contentful の公開アプリリポジトリ（https://github.com/contentful/apps）にある例が存在する場合は、リリースや配布のワークフローは引き継がず、App Framework のパターンや UX の洗練度を高めるためのベストプラクティスとして活用します。

入力

以下を受け付けます。

• バグ報告
• 顧客や編集者からのフィードバック
• サポートチケットや課題へのリンク
• スクリーンショットや画面録画
• 既知のカスタムアプリに対する直接の変更リクエスト
• App Framework の動作に関する不完全なメモ

元の資料が不完全な場合、リスクが低ければ、ローカルのコードと提示されたコンテキストをもとに作業を続けます。不足している情報によってユーザー向けの動作、データの書き込み、認証、デプロイ方法が変わる可能性がある場合は、要点を絞った質問をしてください。

ワークフロー

1. リクエストのコンテキストを把握する

以下を特定します。

• 元のリクエストと影響を受けるユーザー
• 現在のアプリの動作と期待される動作
• 影響を受ける Contentful の場所とワークフロー
• space、environment、content type、field、locale、role に関する前提
• 外部サービスや認証情報への依存関係
• ローカルで確認できる証拠と、まだ不足している証拠

確認済みの事実と前提を分けてください。

2. 既存のアプリを調査する

編集する前に、以下を行います。

• リポジトリの状態を確認し、ユーザーの変更を上書きしない
• package.json、スクリプト、ロックファイル、フレームワークの規約を調べる
• 関連するアプリの場所と SDK の使用箇所を特定する
• 既存のテストと近くにあるコンポーネントを確認する
• 存在する場合は、アプリの定義、インストールパラメーター、デプロイに関するメモを特定する
• アプリが App SDK、React Apps Toolkit、Forma 36、contentful-management、App Actions、Functions、外部バックエンドのいずれを使用しているか確認する

再利用可能なチェックリストについては、 改善チェックリストを使用してください。

3. 変更が小規模で対応できるか判断する

以下を満たす見込みがある場合は、実装を進めます。

• 1 つのアプリに範囲を限定できる
• 短い PR で説明できる
• ローカルまたはサンドボックスで検証できる
• 大規模なプロダクト再設計を伴わずにレビューできる
• リスクの高い移行やシークレットの取り扱いの変更なしに実装できる

以下が必要な場合は、一旦保留して確認してください。

• 本番データの変更
• 新しい外部認証モデル
• 大規模なコンテンツモデルの再設計
• 複数アプリ間の連携
• 新しいバックエンドインフラストラクチャ
• 利用できない Function 機能やプラン機能
• 編集者の操作が曖昧な場合

4. 必要最小限の有用な変更を計画する

編集する前に、以下を含む簡潔な計画を作成します。

• 変更する可能性が高いファイルやアプリの場所
• データの読み取り／書き込みの動作
• UI とバリデーションの更新
• 実施するテストや手動検証
• リスクとロールバック方法

既存のフローを置き換えるよりも、改善することを優先してください。

5. 既存のアプリのスタイルに合わせて実装する

• 現在のフレームワーク、ルーティング、フック、コンポーネント、パッケージマネージャーを再利用します。
• TypeScript の型を正確に保ち、広範な any 型は避けます。
• アプリが別のデザインシステムを意図的に使用している場合を除き、Contentful のウェブアプリ UI には Forma 36 を使用します。
• エディターの信頼を損なわないようにします。該当する場合は、読み込み中、空、エラー、権限、破壊的な操作の状態を表示します。
• 設定 UI では、インストール時に保存される値とインスタンスのスコープに保存される値を明確に示します。
• シークレットではないパラメーターは、スペースのメンバーが読み取れるものとして扱います。
• ランタイムの場所でインストールパラメーターが必要な場合は、sdk.parameters.installation を優先します。アプリの設定を取得するだけの目的で、サイドバー、フィールドエディター、エントリーエディター、ページ、ダイアログ、ホーム、マウント時のエフェクト、レンダリングパス、クリックハンドラーに CMA アプリインストールの読み取りを追加したり、残したりしないでください。
• トークンや非公開の認証情報をクライアントコードで公開しないでください。
• 変更範囲を絞り、無関係なフォーマット変更、依存関係の変更、リファクタリングは避けます。

6. 改善を検証する

利用可能な中で最も適切な検証を実行します。

• 対象を絞ったユニットテストまたはコンポーネントテスト
• 型チェック
• lint またはフォーマッターのチェック
• 本番ビルド
• ローカル開発サーバーのスモークテスト
• 非本番環境のスペースでの Contentful ウェブアプリの手動フロー
• インストールパラメーターへのアクセスに変更を加えた場合は、appInstallation.getForOrganization、 appInstallation.get、getForOrganization を grep または ripgrep で検索し、ランタイム設定の読み取りに sdk.parameters.installation が使われていることを確認します。CMA アプリインストールの呼び出しが 残る場合は、その理由を記録します。
• サーバー側の動作に変更を加えた場合は、App Action、Function、またはバックエンドエンドポイントのテスト

検証にエージェントが持っていない認証情報やアクセス権が必要な場合は、ユーザーが確認する必要のある項目を具体的に説明します。

7. レビュー可能な成果物を準備する

ユーザーがコミットまたは PR を希望する場合：

• リポジトリの規約がわかっている場合は、それに沿って目的を絞ったブランチを作成します。
• コミットは小さく、一般的な規約に従うものにします。
• 無関係なローカルファイルをステージングしないでください。
• PR の下書きには、依頼の背景、実装の概要、検証内容、未解決の質問を含めます。

ユーザーが修正のみを依頼した場合は、最後に以下を記載します。

• 背景
• 評価
• 実装の概要
• 検証
• 残るリスクまたは今後の対応

ガードレール

• より適切な回答がプロダクトの要件確認である場合、無理にコードを変更しないでください。
• 曖昧な報告ひとつに過剰適合せず、不確かな点を明示してください。
• ユーザーから依頼されない限り、書き換えにまで範囲を広げないでください。
• ユーザーが明言していない限り、アプリの利用者に公開や配布の要件があると想定しないでください。
• 最新の公式ドキュメントで確認すべき Contentful のプラン機能、SDK の動作、API の制限を、記憶だけに基づいて断定しないでください。

関連スキル

• contentful-custom-app-from-scratch - 新しいカスタムアプリの設計と構築。
• contentful-api - REST API と GraphQL API の具体例。
• contentful-migration - コンテンツモデルの移行スクリプト。
• contentful-guide - Contentful の概念と API のルーティング。