MacoTasu アーキテクチャレビュー
このスキルの守備範囲
見るのは「壊れないか / 壊れたことを知れるか / 止められるか」。事業形態に依存しない、 分散システムとして動かし続けるための性質を扱う。
隣接するスキルとの境界:
- 公式
pr-review-toolkit（コードの書き方）とは重ならない。特にsilent-failure-hunterが「エラーを握り潰していないか」を見るのに対し、 こちらは「再実行されても壊れないか」を見る。視点が違うので両方必要。 saas-review（テナント境界・課金・監査ログ・退会時の削除など、マルチテナントで課金して 継続提供するという事業形態に固有の性質）とも重ならない。SaaS のバックエンドを変更する PR では、両方を読む価値がある。
使い方
- レビュー対象の差分を取る（
git diff、gh pr diff <N>など）。 - 差分が触っている面から下表の該当軸を選ぶ。外部 API 呼び出し・非同期ジョブ・キュー・ マイグレーション・API の型変更のいずれも無ければ、このスキルは不要。
checklists/*.mdの各項目の 「どう検出するか」を実際に実行する。読んで想像せず、 grep する・ファイルを開く・コマンドを走らせる。- 検出できた事実だけを指摘する。確認できなかった項目は「未確認」と明示する。
軸
| 軸 | ファイル | 差分にこれがあれば読む |
|---|---|---|---|
| 外部連携とトランザクション整合 | checklists/external-integration-consistency.md | メール送信 / 決済 / 通知 / 送信する webhook / 非同期ジョブ / キュー |
| API・スキーマの後方互換と移行 | checklists/api-compatibility.md | レスポンス型変更 / DB マイグレーション / 送信する webhook |
| 観測性と障害時の運用 | checklists/observability-operations.md | 外部API呼び出し / 非同期ジョブ / 新機能の投入 |
項目の書式
- 観点: 何を見るか
- なぜ危険か: 守らなかった時に実際に起きる事故
- どう検出するか: 見るファイル・grep・実行コマンド（エージェントが実行できる形で書く）
- よくある間違った実装: 実際に踏まれるパターン
「どう検出するか」が書けない項目は、レビューで実行できない＝ポエムなので採用しない。
backlog（未収録の軸）
サービス境界と依存方向 / キャッシュ戦略と無効化 / スケール時のボトルネック / 障害の隔離（サーキットブレーカ・バルクヘッド）/ 秘密情報と設定の管理。