forge-app-review

Forge アプリのレビュー

一般的な Forge のリリース準備状況をレビューします。このスキルは幅広いアプリレビューの入り口であり、セキュリティ、コスト、デバッグに特化したスキルの代わりではありません。

対象範囲

次の場合にこのスキルを使用します。

• デプロイ前およびリリース準備状況の確認。
• 一般的なアーキテクチャと保守性のレビュー。
• マニフェスト、モジュール、リソース、関数の接続確認。
• ランタイム、依存関係、パッケージ、スクリプトの妥当性確認。
• 基本的なテスト／デプロイ準備状況と運用上の衛生状態の確認。
• より深い専門的レビューにつなげるべき、明らかなセキュリティ、コスト、信頼性上の懸念の確認。

ユーザーの主な目的が次の場合は、代わりに別のスキルを使用します。

• 詳細なセキュリティ監査、SAST、認可、シークレット、テナント分離、悪用可能性、CVSS レポート -> forge-security-review。
• コスト最適化、呼び出し、GB 秒、ストレージ／ログの容量、トリガー頻度、メモリの調整 -> forge-cost-optimizer。
• 既知の障害、エラーメッセージ、空白の UI、デプロイ／インストールの失敗、壊れたリゾルバー、見つからないアプリ、ログ／トンネルの診断 -> forge-debugger。

幅広いレビューで詳細なセキュリティ、コスト、デバッグ上の懸念が見つかった場合は、専門的なワークフローを重複して実施せず、引き継ぎの推奨事項として記載してください。

レビューのルール

• まず監査してください。ユーザーが修正を明示的に依頼しない限り、アプリのファイルを変更しないでください。
• 主張する前にコードベースを確認してください。
• 具体的なファイル／行の根拠を優先してください。
• バグ、リリースを妨げる問題、重要なリスク、検証の不足に絞って指摘してください。
• このスキルでは SAST やコスト分析ツールを実行しないでください。必要に応じて専門スキルを推奨してください。
• 推測に基づくセキュリティやコストに関する所見を、確認済みの脆弱性や削減効果として報告しないでください。

モジュールと機能に応じた振り分け

manifest.yml またはパッケージの依存関係で宣言されているモジュールを検出し、該当するレビューガイドを読み込んでください。

• Teamwork Graph / Forge Connectors:
  • アプリで graph:connector、teamwork-graph-connector が宣言されている場合、または @forge/teamwork-graph がインポートされている場合：
  • 👉 ./modules/connector-review.md に従ってレビューしてください。

---

ワークフロー

1. manifest.yml または manifest.yaml を読みます。
   • モジュール、リソース、関数、リゾルバーのバインディング、トリガー、ウェブトリガー、リモート、権限、ランタイム、メモリ設定を特定します。
   • 参照されているハンドラー／リソースが存在することを確認します。
2. package.json を読みます。
   • Forge パッケージとの適合性、スクリプト、ランタイムの前提、直接依存関係、明らかに未使用または不足しているパッケージを確認します。
3. ソースファイルを調べます。
   • バックエンド／リゾルバー：resolver.define、ハンドラーのエクスポート、製品 API の呼び出し、ストレージの使用、外部への fetch、ログ記録、エラー処理。
   • フロントエンド：UI Kit または Custom UI のリソースエントリーポイント、invoke() の使用パターン、ブリッジの使用、読み込み／エラー状態。
4. テストとプロジェクトのドキュメントがある場合は調べます。
   • 動作上のリスクを正当化できる場合に限り、テストの不足を指摘します。
5. 優先順位を付けた準備状況レポートを作成します。

確認項目

リリースを妨げる問題

• マニフェストが、存在しないハンドラー、リソースパス、またはモジュールキーを参照している。
• フロントエンドから呼び出されるリゾルバー名が、resolver.define() の名前と一致しない。
• 実際の API／fetch の使用に必要なスコープまたはエグレス権限が不足している。
• ランタイム、パッケージのバージョン、またはモジュール構文が原因で、forge lint、ビルド、デプロイ、インストールが失敗する可能性が高い。
• アプリの主要なユーザーフローを試す明確な方法がない。

アーキテクチャと保守性

• モジュールの種類が、意図する UX サーフェスに適合している。
• リゾルバーの境界が一貫しており、アプリの規模に対して過度にモノリシックではない。
• 機密性の高いロジックや特権が必要なロジックがバックエンド側に保たれている。
• UI のみで行うべきフォーマットや変換を、不要にバックエンド関数経由で実行していない。
• ユーザー向けワークフローに十分なエラー処理がある。
• コードの構成が、既存のプロジェクトスタイルに沿っている。

軽量セキュリティシグナル

明白なシグナルのみを指摘し、詳細な検証には forge-security-review を推奨してください。

• 使用が確認できない、広範な／書き込み／管理者スコープ。
• 明らかな認可チェックがないユーザー起点のリゾルバー内での api.asApp()。
• ハードコードされた認証情報やトークンのようなリテラル。
• マニフェストのエグレスエントリーがない外部フェッチ。
• 明確な認証戦略が確認できないウェブトリガー。
• ユーザー、テナント、またはシークレットのデータを漏えいさせる可能性がある、ペイロード／リクエスト全体のログ記録。

軽量コストシグナル

明白なシグナルのみを指摘し、詳細な分析には forge-cost-optimizer を推奨してください。

• 静的データまたは製品コンテキストを返すためだけに呼び出されるリゾルバー。
• ページ読み込み時の、複数の独立した invoke() 呼び出し。
• 広範なポーリングと思われるスケジュール済みトリガー。
• 適用可能な場合にフィルターや ignoreSelf がない製品トリガー。
• ホットパスでのペイロード／API レスポンス全体のログ記録。
• 呼び出しのたびに行われるストレージへの書き込み。

軽量デバッグ可能性シグナル

準備状況の不足のみを指摘してください。障害が確認された場合は forge-debugger を使用してください。

• 非同期 UI パスでのローディング状態／エラー状態の欠落。
• 重要な障害に関するログが過剰にノイズを生んでいる、または存在しない。
• README やスクリプトに、lint／build／deploy／test の方法が記載されていない。
• forge lint 以外に、明確なローカル検証コマンドがないアプリ。

出力形式

簡潔な Markdown レポートを返してください。指摘事項は番号付きリストではなく、表にしてください。 読者が各指摘の出所となったレビューガイドまたは領域を把握できるよう、すべての指摘に Source 列を含めてください。

Source の値（該当する中で最も具体的なものを使用してください。Source はチェックリスト／モジュールまたはレビュー領域であり、単なるファイル種別ではありません）：

• manifest — モジュール固有のガイドで扱われていない、一般的な Forge マニフェストの設定、スコープ、エグレス、またはモジュールキー
• resolver — バックエンド／リゾルバーの設定とランタイムの動作
• frontend — UI Kit／Custom UI の invoke およびブリッジのパターン
• dependencies — package.json／ランタイムパッケージの適合性
• tests — 検証の不足または不十分さ
• general — 上記で扱われていない、複数領域にまたがる準備状況の衛生状態
• モジュール固有のラベル — モジュールレビューガイド（./modules/ 内）が読み込まれている場合は、そのガイドで定義されている Source ラベルを使用してください（例：connector）。証拠が manifest.yml にあるという理由だけで、これらの指摘を manifest に付け替えないでください。

Location のルール（パスのみの記載は禁止）：

• 必ず正確な path:line または path:start-end を記載してください（複数の引用も可）。
• Location セルには、シグナルの根拠となったコードの抜粋を含めてください。ファイル名だけでなく、根拠となった正確な行を記載してください。
• Markdown の表セルでは ``` のフェンスを入れ子にすると安定しないため、抜粋は HTML の <pre><code>...</code></pre> で囲んでください。
• 抜粋は簡潔にしてください（通常は15行以内）。欠落の場合（例：必須ブロックがない場合）は、最も近い包含スタンザを示し、Description に何が欠けているかを記載してください。

# Forge App Review Results

## Summary
- Readiness: Ready | Needs changes | Blocked
- Highest-risk area: <manifest | resolver wiring | permissions | dependencies | tests | operational hygiene | module-specific>
- Files inspected: <short list>
- Specialist handoffs: <none | security | cost | debugger>

## Findings

| Severity | Source | Finding | Location | Description | Doc | Fix |
|----------|--------|---------|----------|-------------|---------|-----|
| Critical \| Warning \| Info | <source> | <short title> | `path:start-end`<br><pre><code>…excerpt…</code></pre> | <why this matters / observed pattern> | <DAC or checklist anchor title + URL> | <specific remediation> |

Sort rows Critical → Warning → Info. Omit the Doc column cell only when no public/doc anchor applies; keep the column.

## Clean Areas
- <important categories checked with no issues>

## Suggested Next Step
- <apply fixes | run specialist review | deploy/lint/test command>

指摘事項がない場合は、一般的なレビューの範囲ではアプリは準備が整っているように見えると伝え、意図的に対象外とした残りの専門レビューを列挙してください。