# Architecture Review

> 外部サービスとの連携・非同期処理・スキーマ変更を含む差分を、システムの整合性と運用性の 観点でレビューするスキル。 DB トランザクションと外部副作用の二重書き込み(outbox パターン)、部分失敗の後始末、 リトライに対する冪等性、順序保証への暗黙の依存、外部障害と自サービスの可用性結合、 API とスキーマの後方互換(expand/contract・マイグレーションのロック・ロールバック可能性)、 観測性と障害時の運用(タイムアウト・相関ID・kill switch) を見る。 メール送信 / 決済 / 通知 / 検索インデックス更新 / 自社が送信する webhook / メッセージキュー / 非同期ジョブ / DB マイグレーション / API のレスポンス型変更 に触れる変更をレビューするとき、 および設計時に穴を洗い出すときに使う。 事業形態に依存しないので、SaaS でなくても適用できる。 コードの書き方(命名・型設計・テスト網羅・エラーハンドリングの握り潰し)は対象外。

- Skill: `macotasu/architecture-review` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add macotasu/architecture-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/macotasu/architecture-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: MacoTasu (https://skillmd.com/u/macotasu)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/macotasu/architecture-review

---


# アーキテクチャレビュー

## このスキルの守備範囲

見るのは「**壊れないか / 壊れたことを知れるか / 止められるか**」。事業形態に依存しない、
分散システムとして動かし続けるための性質を扱う。

隣接するスキルとの境界:

- 公式 `pr-review-toolkit`（コードの書き方）とは重ならない。特に
  `silent-failure-hunter` が「エラーを握り潰していないか」を見るのに対し、
  こちらは「**再実行されても壊れないか**」を見る。視点が違うので両方必要。
- `saas-review`（テナント境界・課金・監査ログ・退会時の削除など、マルチテナントで課金して
  継続提供するという事業形態に固有の性質）とも重ならない。SaaS のバックエンドを変更する
  PR では、両方を読む価値がある。

## 使い方

1. レビュー対象の差分を取る（`git diff`、`gh pr diff <N>` など）。
2. 差分が触っている面から下表の該当軸を選ぶ。外部 API 呼び出し・非同期ジョブ・キュー・
   マイグレーション・API の型変更のいずれも無ければ、このスキルは不要。
3. `checklists/*.md` の各項目の **「どう検出するか」を実際に実行する**。読んで想像せず、
   grep する・ファイルを開く・コマンドを走らせる。
4. 検出できた事実だけを指摘する。確認できなかった項目は「未確認」と明示する。

## 軸

| 軸 | ファイル | 差分にこれがあれば読む |
|---|---|---|---|
| 外部連携とトランザクション整合 | `checklists/external-integration-consistency.md` | メール送信 / 決済 / 通知 / 送信する webhook / 非同期ジョブ / キュー |
| API・スキーマの後方互換と移行 | `checklists/api-compatibility.md` | レスポンス型変更 / DB マイグレーション / 送信する webhook |
| 観測性と障害時の運用 | `checklists/observability-operations.md` | 外部API呼び出し / 非同期ジョブ / 新機能の投入 |


## 項目の書式

- **観点**: 何を見るか
- **なぜ危険か**: 守らなかった時に実際に起きる事故
- **どう検出するか**: 見るファイル・grep・実行コマンド（**エージェントが実行できる形で書く**）
- **よくある間違った実装**: 実際に踏まれるパターン

「どう検出するか」が書けない項目は、レビューで実行できない＝ポエムなので採用しない。

## backlog（未収録の軸）

サービス境界と依存方向 / キャッシュ戦略と無効化 / スケール時のボトルネック /
障害の隔離（サーキットブレーカ・バルクヘッド）/ 秘密情報と設定の管理。