one-way-door

一方通行の扉チェック

簡単に元に戻せる決定もあります。UI コンポーネントの変更、変数名の変更、ユーティリティ関数の置き換えは、後に影響を残しません。これらは双方向の扉です。通り抜けて、間違っていたら戻ればよいのです。

一方で、重力を生み出す決定もあります。トラフィック、ユーザー、その他のコードが依存し始めると、方針転換に多大なコストがかかります。リリース後のデータベーススキーマの移行。外部の利用者が依存する API コントラクト。権限モデル全体を形作る認証境界。これらは一方通行の扉です。

ソフトウェアで最も高くつく失敗は、バグではありません。十分に検討せずに下した、元に戻せないアーキテクチャ上の決定です。

フラグが立つもの

データモデルとデータベーススキーマ

該当するファイル：schema.prisma、schema.graphql、*.sql、migration*、models.py、models.ts、entities.py、entities.ts

データモデルは、最も元に戻しにくい決定です。データベースにレコードが作成されると、スキーマの変更には必ず移行が必要になります。カラム名を変更するとクエリが壊れます。リレーションシップを変更すると、アプリケーション全体に影響が広がります。

確認すること：

• エンティティ間のすべてのリレーションシップを整理しましたか？
• このスキーマは、N+1 問題を起こさずに必要なクエリをサポートできますか？
• 読み取り／書き込みのパターンに合わせて、適切に正規化されていますか？

インフラストラクチャとデプロイ設定

該当するファイル：docker-compose*、Dockerfile、*.tf、terraform*、pulumi*、cdk*、cloudformation*、k8s*、kubernetes*、helm*

インフラストラクチャの選択は、その上に構築するすべてのものを制約します。ECS から Kubernetes への切り替えや、Lambda からコンテナへの切り替えは、デプロイパイプライン、モニタリング、スケーリング、チームの知識に影響します。

確認すること：

• 必要な要件を満たす、最もシンプルなインフラストラクチャですか？
• このスタックに関して、チームにはどのような運用経験がありますか？
• 障害からの復旧はどのように行いますか？

認証と認可

該当するファイル：auth.{ts,js,py}、firestore.rules、storage.rules、*.rules、security.{ts,js,py,json,rules,yaml,yml}、rbac.{ts,js,py,json}、permissions.{ts,js,py,json}

これらのパターンでは、意図的に拡張子を指定しています。単に security や permissions という単語を含むだけの無関係なファイル（メモ、ドキュメント、テストなど）は、このチェックの対象になりません。

認証境界は、建物を支える壁です。セッションか JWT か、ロールベースか属性ベースか、シングルテナントかマルチテナントか。それぞれの選択が、セキュリティモデル、ユーザーエクスペリエンス、コンプライアンスの状況を形作ります。

確認すること：

• すべてのユーザー種別とアクセスパターンに対応していますか？
• トークンの更新、セッションの有効期限切れ、取り消しにどう対処しますか？
• 最初からシングルテナントとマルチテナントのどちらを想定して構築しますか？

API コントラクトとサービスインターフェース

該当するファイル：openapi*、swagger*、*.proto、*.graphql、api-schema*、routes.ts、routes.js、routes.py

公開済みの API は、利用者に対する約束です。破壊的変更には、バージョニング、非推奨化の期間、移行ガイドが必要です。サービス間の内部 API は、解消が難しい結合を生み出します。

確認すること：

• この API の利用者は誰ですか？内部サービス、外部開発者、それとも両方ですか？
• 破壊的変更をどのようにバージョニングしますか？
• 非公開にしておくべき実装の詳細を公開していませんか？

イベントシステムとメッセージバス

該当するファイル：events.ts、eventbus.ts、eventemitter.py、eventhandler.py、pubsub*、queue*、kafka*、rabbit*

イベントスキーマは、プロデューサーとコンシューマーの間のコントラクトです。複数のサービスがイベントをサブスクライブすると、その形式を変更するには、各サービスのデプロイを調整する必要があります。イベントの順序に関する前提は、アーキテクチャ上の制約になります。

確認すること：

• 必須フィールドと任意フィールドを含むイベントスキーマを定義しましたか？
• コンシューマーがイベントの処理に失敗した場合、どうなりますか？
• 順序保証が必要ですか？

CI/CD パイプライン

対象ファイル：.github/、.gitlab/、.circleci/ 内のファイル、または Jenkinsfile、.travis.yml、cloudbuild* に一致するファイル

CI/CD パイプラインは、リリースプロセスの基盤になります。チームはデプロイのワークフローを習慣として身につけます。パイプラインの構造を変更すると再トレーニングが必要になり、移行中にデプロイが失敗すれば、チーム全体の作業が滞る可能性があります。

確認する質問：

• このパイプラインは、現在のブランチ戦略をサポートしていますか？
• デプロイに失敗した場合、ロールバックの手順はどうなっていますか？
• シークレットは安全に扱われていますか？

依存関係とパッケージの設定

対象ファイル：package.json、Cargo.toml、go.mod、requirements.txt、pyproject.toml、Gemfile に一致するファイル

フレームワークや依存関係の選択は、コードベース全体に影響を及ぼします。React から Vue に、または Express から Fastify に切り替えるには、アプリケーションの大部分を書き直す必要があります。

確認する質問：

• この依存関係は積極的にメンテナンスされていますか？
• 必要な規模に対応できますか？
• 切り替えが必要になった場合、どのような移行方法がありますか？

クラウドサービスの設定

対象ファイル：firebase.json、.firebaserc、firestore.indexes* に一致するファイル

クラウドサービスの設定によって、特定のプロバイダーやアーキテクチャへの依存が生じます。Firestore のインデックスはクエリのパフォーマンスを左右します。Firebase のルールはセキュリティ境界を定義します。

確認する質問：

• このプロバイダーを長期的に利用することに抵抗はありませんか？
• 実際のクエリパターンでこれらのインデックスをテストしましたか？
• 移行が必要になった場合、どのように切り替えますか？

双方向ドア（変更しても問題ないもの）

以下の種類のファイルは、すぐに決定して後から変更しても問題ありません。

• UI コンポーネント、React／Vue／Svelte のコンポーネント、CSS、テンプレート
• ユーティリティ関数、ヘルパー、フォーマッター、バリデーター
• テストファイル、テスト基盤は自由にリファクタリングできます
• ドキュメント、README、ガイド、コメント
• ロギングとモニタリング、ログ形式、メトリクス名
• 設定ファイル、.env、機能フラグ、アプリ設定
• 静的アセット、画像、フォント、アイコン

適用される許可リスト

オプションの Claude Code フックには、パターンチェックより前に処理を終了する許可リストがあります。ファイル名に auth や security などの単語が含まれていても、テスト、フィクスチャ、モック、Markdown、ドキュメントまたは計画のテキストファイルは許可されます。

共通スキルはこのフックに依存しません。ファイルを手動で確認する場合も、同じ許可リストを適用してください。

実装方法

プロジェクト共通の指示

このルールをプロジェクトの正式な指示ファイルに追加してください。Codex では AGENTS.md、Claude Code では CLAUDE.md を使用します。一方のファイルからもう一方を読み込んでいる場合は、正式なファイルを編集してください。

### One-way door check

Before creating a file that represents an architectural decision, ask which
parts would be difficult to reverse. One-way doors include data models, service
communication patterns, authentication boundaries, tenancy models, and
infrastructure configuration. If a decision is a one-way door, ask the user and
wait for an explicit answer. Use the client's structured question tool when it
has one. Explain the trade-offs and at least two alternatives before asking
whether to proceed. Two-way doors, such as UI components, utilities, and
styling, can be changed quickly.

この手動ワークフローが、移植可能な動作の基準です。自動フックがなくても機能します。

1. 書き込む前に、一方向ドアとなるファイルを特定します。
2. 何が元に戻しにくくなるのかを説明します。
3. トレードオフを示しながら、少なくとも 2 つの代替案を提示します。
4. ユーザーに確認し、明示的な回答を待ちます。クライアントに構造化された質問ツールがある場合は、それを使用します。
5. ユーザーがその判断を承認した後に限り、書き込みます。

オプションの Claude Code による強制

Claude Code のユーザーは、書き込み前に自動でブロックするため、リポジトリの one-way-door-check フックをインストールできます。このフックと承認プロモーターはオプションの Claude Code による強制機能であり、共通の Agent Skills の動作ではありません。このアダプターは、セッション単位の保留・承認台帳を保持するため、承認済みファイルをループせずに再試行できます。

PowerShell 版の one-way-door-check.ps1 と one-way-door-approve.ps1 は、このスキルディレクトリに含まれています。フックのドキュメントには、POSIX 実装、台帳のルール、Claude Code との接続方法が記載されています。このアダプターのないクライアントでは、上記の手動ワークフローを使用する必要があります。自動的な強制機能がないことを、承認済みと見なしてはいけません。

3つの問い

後戻りできない決断をする前に、次の問いを立ててください。

1. 何にコミットするのか？ この決断によって何が制約されるのか？ 変更が難しくなるものは何か？
2. どんな代替案があるのか？ もっとシンプルな方法はあるか？ もっと後戻りしやすい方法はあるか？
3. 移行経路はどうなるのか？ これが間違いだとわかった場合、どう軌道修正するのか？

これらの問いに明確に答えられないなら、まだその扉をくぐる準備はできていません。