reference-engine

これは、参照を最優先するすべての行動を統制するメタプロトコルです。何かを構築していて、ドメイン固有の参照プロトコルが存在しない場合、このプロトコルが参照システムになります。

構築する前に、必ず参照先を見つけてください。例外はありません。

Reference Engine：汎用の参照優先システム

概要

あらゆる分野で、何千時間にも及ぶプロフェッショナルなエンジニアリングがすでに行われています。API は設計され、スキーマは洗練され、パイプラインは実戦で検証され、パターンは堅牢なものになっています。それらを参照先として活用するのは怠慢ではなく、エンジニアリング上の知見です。

基本原則： 何かを構築する前に、既存の最良の参照先を見つけてください。そのパターンを抽出し、仮定ではなく実証済みの基盤の上に構築してください。

例外なし。回避策なし。近道なし。

最優先の指令

NO BUILDING WITHOUT A REFERENCE

取り組んでいる分野で実証済みの参照先を探していないなら、プロフェッショナルなエンジニアリングに費やされた何千時間もの成果を無視していることになります。決済 API は、汎用的な AI 生成エンドポイントではなく、Stripe の API パターンに倣うべきです。

適用時期

常に。 このプロトコルがルーターとなり、構築対象に応じて、どの参照システムを利用するかを決定します。

digraph reference_router {
    rankdir=TB;
    node [shape=box style=filled];

    task [label="Task Received" fillcolor=lightyellow shape=doublecircle];

    classify [label="Classify Task Domain" fillcolor=lightyellow];

    ui [label="UI / Frontend?\n-> ux-patterns\n-> ui-engineering\n-> design-integration" fillcolor="#e8f5e9"];
    website [label="Website Design?\n-> design-research\n-> ux-patterns" fillcolor="#e8f5e9"];
    code [label="Code / Library?\n-> github-search (external)\n-> codebase-research (internal)\n-> pattern-matching" fillcolor="#e8f5e9"];
    api [label="API Design?\n-> API References\n(this protocol)" fillcolor="#fff3e0"];
    database [label="Database / Schema?\n-> Schema References\n(this protocol)" fillcolor="#fff3e0"];
    testing [label="Testing Strategy?\n-> Testing References\n(this protocol)" fillcolor="#fff3e0"];
    devops [label="CI/CD / DevOps?\n-> DevOps References\n(this protocol)" fillcolor="#fff3e0"];
    arch [label="Architecture?\n-> system-design\n-> Architecture References\n(this protocol)" fillcolor="#fff3e0"];
    quality [label="Code Quality?\n-> quality-enforcement\n-> Quality References\n(this protocol)" fillcolor="#fff3e0"];
    perf [label="Performance?\n-> performance-tuning\n-> Perf References\n(this protocol)" fillcolor="#fff3e0"];
    security [label="Security?\n-> security-protocol\n-> Security References\n(this protocol)" fillcolor="#fff3e0"];
    other [label="Other Domain?\n-> Research + Build Reference\n(this protocol)" fillcolor="#fce4ec"];

    task -> classify;
    classify -> ui;
    classify -> website;
    classify -> code;
    classify -> api;
    classify -> database;
    classify -> testing;
    classify -> devops;
    classify -> arch;
    classify -> quality;
    classify -> perf;
    classify -> security;
    classify -> other;
}

緑色のノード = 専用プロトコルが存在するため、それを呼び出します。 オレンジ色のノード = このプロトコルの参照ライブラリを使用します。 赤色のノード = まだ参照先が存在しないため、まず調査してから構築します。

エントリープロトコル

BEFORE building anything:

1. CLASSIFY: What domain is this task in?
2. ROUTE: Does a dedicated reference protocol exist? (ux-patterns, design-research, github-search, codebase-research, etc.)
   -> YES: Invoke that protocol
   -> NO: Continue to step 3
3. SEARCH: Locate reference implementations for this domain
   - External: Use github-search for open-source repos, libraries, and patterns
   - Internal: Use codebase-research for existing conventions and similar code
   - GitHub: Search for gold-standard implementations
   - Documentation: Find official best practices (RFC specs, framework docs, cloud provider guides)
   - Industry leaders: What do Stripe, GitHub, Vercel, AWS do for this?
4. EXTRACT: Isolate the patterns that make these references excellent
5. PRESENT: Show the user your references and recommended approach
6. BUILD: Implement using the reference

Skip any step = building from assumptions instead of knowledge

参照の理念

"Accumulated Expertise" Principle:

Every professional implementation represents:
- Months of design iteration
- Thousands of users providing feedback
- Production incidents that drove improvements
- Security audits that uncovered vulnerabilities
- Performance tuning under real load

When you generate from scratch, you inherit NONE of this.
When you use a reference, you inherit ALL of it.

ドメイン別参照ライブラリ

API 設計の参照先

調査すべき標準的な実装：

API スタイル	参照先	調査対象
REST	Stripe API	リソースの命名、バージョニング、エラー形式、ページネーション、冪等性
REST	GitHub API v3	ハイパーメディア、条件付きリクエスト、レート制限ヘッダー
REST	Twilio API	ネストされたリソース、Webhook、ステータスコールバック
GraphQL	GitHub API v4	スキーマ設計、ページネーション（コネクション）、エラー処理
GraphQL	Shopify Storefront	クエリの複雑さの上限、バージョニング戦略
RPC/gRPC	Google Cloud APIs	Proto 設計、エラーモデル、長時間実行オペレーション
Webhook	Stripe Webhooks	イベントの種類、署名、再試行ポリシー、冪等性
リアルタイム	Discord Gateway	WebSocket のライフサイクル、ハートビート、再接続、インテント

API 参照チェックリスト：

BEFORE designing any API:

1. Resource naming: Use nouns, plural, lowercase
   Reference: Stripe -> /v1/customers, /v1/payment_intents

2. Error format: Consistent error object
   Reference: Stripe -> { error: { type, code, message, param } }

3. Pagination: Cursor-based for real-time data, offset for static
   Reference: GitHub -> Link headers + per_page + page params
   Reference: Stripe -> has_more + starting_after cursor

4. Versioning: URL path or header
   Reference: Stripe -> /v1/ prefix
   Reference: GitHub -> Accept header with version

5. Auth: API keys for server, OAuth for users
   Reference: Stripe -> Bearer token in Authorization header

6. Rate limiting: Return limits in headers
   Reference: GitHub -> X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

7. Idempotency: Idempotency keys for mutations
   Reference: Stripe -> Idempotency-Key header

8. Filtering/sorting: Consistent query parameter patterns
   Reference: Stripe -> created[gte]=timestamp, status=active

データベーススキーマの参照先

ドメイン別の参照パターン：

ドメイン	スキーマパターン	出典
ユーザーと認証	ユーザー -> ロール -> 権限（RBAC）	Auth0、Supabase の認証スキーマ
E コマース	商品 -> バリエーション -> 注文 -> 注文明細	Shopify のスキーマ、Medusa.js
マルチテナント SaaS	組織 -> メンバー -> リソース	Clerk、WorkOS のパターン
CMS	コンテンツ -> バージョン -> メディア -> タクソノミー	Strapi、Payload CMS のスキーマ
ソーシャル	ユーザー -> 投稿 -> コメント -> リアクション -> フォロー	Mastodon、Lemmy のスキーマ
メッセージング	会話 -> 参加者 -> メッセージ	Matrix プロトコル、Slack のデータモデル
スケジューリング	イベント -> 時間枠 -> 予約 -> 空き状況	Cal.com のスキーマ
アナリティクス	イベント -> セッション -> プロパティ（スター・スキーマ）	PostHog、Plausible のスキーマ
在庫管理	商品 -> 倉庫 -> 在庫 -> 移動	Odoo の在庫管理モジュール

スキーマ参照チェックリスト：

BEFORE designing any database schema:

1. Find the domain pattern above (or search GitHub for "[domain] database schema")
2. Study the reference implementation's:
   - Table relationships and foreign keys
   - Indexing strategy
   - Soft delete approach (deleted_at vs status)
   - Audit trail pattern (created_at, updated_at, created_by)
   - Multi-tenancy approach (row-level vs schema-level)
3. Standard columns for EVERY table:
   - id (UUID or ULID, not auto-increment for distributed systems)
   - created_at (timestamp with timezone)
   - updated_at (timestamp with timezone)
4. Naming convention: snake_case for tables and columns
5. Junction tables: {table_a}_{table_b} alphabetically

テスト戦略の参考資料

プロジェクトの種類別の参考フレームワーク：

プロジェクトの種類	テストアプローチ	ツール
React/Vue/Svelte	コンポーネント -> 統合 -> E2E	Testing Library + Vitest + Playwright
API/バックエンド	単体 -> 統合 -> コントラクト -> E2E	Jest/Vitest + Supertest + Pact
CLI ツール	単体 -> 統合 -> スナップショット	Jest + mock-stdin + スナップショットテスト
ライブラリ/パッケージ	単体 -> プロパティベース -> 互換性	Vitest + fast-check + マトリックス CI
モバイル	コンポーネント -> 画面 -> E2E	Detox（RN）、XCTest（iOS）、Espresso（Android）
データパイプライン	単体 -> 統合 -> データ品質	Great Expectations、dbt tests
インフラストラクチャ	計画 -> 適用 -> 検証	Terratest、kitchen-terraform

テストの参考チェックリスト：

BEFORE writing tests:

1. Identify project type -> select testing approach above
2. Test pyramid for this project:
   - Unit tests: 70% (fast, isolated, mock dependencies)
   - Integration tests: 20% (real dependencies, test interactions)
   - E2E tests: 10% (user flows, critical paths only)
3. What to test:
   - Happy path (minimum viable test)
   - Edge cases from spec (empty, null, max, concurrent)
   - Error paths (invalid input, network failure, timeout)
   - Security paths (injection, auth bypass, privilege escalation)
4. What NOT to test:
   - Framework internals (React renders correctly)
   - Third-party library behavior (axios sends requests)
   - Implementation details (internal state shape)
5. Test naming: describe("[unit]", () => it("should [behavior] when [condition]"))
6. Test data: Use factories/fixtures, not inline magic values

CI/CD パイプラインの参考資料

プラットフォーム別の参考パイプライン：

プラットフォーム	ソース	主なパターン
GitHub Actions	github/starter-workflows	マトリックスビルド、キャッシュ、アーティファクトのアップロード
GitHub Actions	Vercel's Next.js workflow	プレビューデプロイ、環境保護
GitLab CI	gitlab-org/gitlab	マルチステージ、DAG パイプライン、インクルード
CircleCI	circleci/circleci-docs	Orbs、ワークスペースの永続化
AWS	aws-actions/*	OIDC 認証、CodeBuild、ECS デプロイ
GCP	google-github-actions/*	Workload Identity、Cloud Run デプロイ

CI/CD の参考チェックリスト：

BEFORE setting up CI/CD:

1. Standard pipeline stages:
   Install -> Lint -> Type Check -> Test -> Build -> Deploy

2. Caching strategy:
   - Node: cache node_modules with package-lock.json hash
   - Python: cache .venv with requirements.txt hash
   - Go: cache go/pkg/mod with go.sum hash
   - Rust: cache target/ with Cargo.lock hash

3. Required checks before merge:
   - All tests pass
   - Linting passes
   - Type checking passes
   - Build succeeds
   - Security audit passes (npm audit, pip audit)

4. Deployment strategy:
   - Preview deploys for PRs (Vercel, Netlify, or custom)
   - Staging auto-deploy from main
   - Production manual approval or tag-based

5. Secrets management:
   - Use platform secret stores (GitHub Secrets, Vault)
   - Never echo secrets in logs
   - Rotate on compromise

コードパターンの参考資料

言語/フレームワーク別の参考実装：

パターン	ソース	使用する場面
エラー処理（TS）	Effect-TS, neverthrow	型付きエラー、Result パターン
エラー処理（Go）	標準ライブラリ	errors.Is/As、ラッピング、センチネルエラー
エラー処理（Rust）	thiserror + anyhow	カスタムエラー型 + コンテキスト
ステートマシン	XState, Robot	複雑な UI 状態、ワークフロー
イベントソーシング	EventStoreDB examples	監査証跡、時間軸クエリ
CQRS	Axon Framework examples	大規模環境での読み取り/書き込みの分離
リポジトリパターン	Spring Data, TypeORM	データアクセスの抽象化
ミドルウェアパターン	Express, Koa, Hono	リクエストパイプライン、横断的関心事
プラグインシステム	Vite, ESLint, Webpack	拡張性、フック
キュー/ワーカー	BullMQ, Celery	バックグラウンドジョブ、非同期処理
Pub/Sub	Redis Streams, NATS	イベント駆動型通信
レート制限	Upstash ratelimit	API の保護、公平な利用
フィーチャーフラグ	Unleash, LaunchDarkly SDK	段階的なロールアウト、A/B テスト
キャッシュ	Redis patterns, SWR	パフォーマンス、stale-while-revalidate

コードパターンの参考チェックリスト：

BEFORE implementing a pattern:

1. Identify the pattern needed from the table above
2. Search GitHub for the reference implementation
3. Study HOW it implements the pattern:
   - What's the public API? (how do consumers use it?)
   - What's the internal structure? (how is it organized?)
   - How does it handle errors?
   - How does it handle edge cases?
4. Extract the minimal pattern for your use case
5. Implement following the reference structure

アーキテクチャの参考資料

規模別の参考アーキテクチャ：

規模	アーキテクチャ	ソース
個人/MVP	モノリス + マネージド DB	Rails、Django、Next.js full-stack
小規模チーム	モジュラーモノリス	Shopify's approach (components)、Laravel modules
成長段階	モノリス -> サービスの抽出	Segment's centrifuge pattern
大規模	マイクロサービス + イベントバス	Netflix OSS、Uber's domain-oriented
サーバーレス	関数 + マネージドサービス	SST (sst.dev) patterns、Vercel's architecture
エッジ	エッジコンピューティング + CDN	Cloudflare Workers patterns、Deno Deploy

セキュリティに関するリファレンス

懸念事項別の実装例：

懸念事項	ソース	主なパターン
認証	Auth.js (NextAuth)	セッション戦略、プロバイダーパターン、CSRF 保護
認可	CASL, Casbin	ABAC/RBAC ポリシー、権限チェック
入力検証	Zod, Valibot	境界でのスキーマ検証
レート制限	Upstash ratelimit	スライディングウィンドウ、トークンバケット
CORS	Express CORS middleware	許可リストによるオリジン制限、認証情報の処理
CSP	Helmet.js	Content-Security-Policy ヘッダー
シークレット	1Password CLI, Vault	シークレットのローテーション、ゼロトラストアクセス
暗号化	libsodium, Web Crypto	エンベロープ暗号化、鍵導出

DevOps / インフラストラクチャに関するリファレンス

プロバイダー別の参照パターン：

プロバイダー	ソース	対象
AWS	aws-samples/*	VPC、ECS、Lambda、RDS、S3 のパターン
GCP	GoogleCloudPlatform/*	Cloud Run、GKE、Pub/Sub、Firestore
Azure	Azure-Samples/*	App Service、Functions、Cosmos DB
Kubernetes	kubernetes/examples	デプロイメント、サービス、イングレス、HPA
Terraform	hashicorp/terraform-provider-*	モジュールのパターン、状態管理
Docker	docker/awesome-compose	複数サービスの Compose パターン
監視	grafana/grafana	ダッシュボードのテンプレート、アラートルール

ドキュメントに関するリファレンス

ドキュメントの種類	ソース	調査するポイント
API ドキュメント	Stripe docs	明確な例、言語切り替えタブ、すぐにコピーして使える形式
README	ベスト・オブ・ブリードの GitHub README	バッジ、クイックスタート、機能一覧、コントリビューション
アーキテクチャ	arc42, C4 model	意思決定記録、コンテキスト図
ランブック	PagerDuty runbooks	インシデント対応、エスカレーション
変更履歴	Keep a Changelog	バージョン管理、分類

調査プロセス

上記の特定のリファレンスライブラリで対象領域をカバーできない場合：

1. GitHub Search:
   - "[domain] [language] example" (e.g., "payment processing typescript example")
   - "[domain] boilerplate" or "[domain] starter"
   - Sort by stars, filter to recently updated

2. Official Documentation:
   - Framework guides (Next.js docs, Django docs, Rails guides)
   - Cloud provider best practices (AWS Well-Architected, GCP Architecture Center)
   - RFC specifications (for protocols, standards)

3. Industry Leaders:
   - What does Stripe do for payments?
   - What does GitHub do for API design?
   - What does Vercel do for deployment?
   - What does Cloudflare do for edge computing?

4. Open Source Implementations:
   - Search for mature, well-maintained projects in the same domain
   - Examine how they structure their code
   - Cherry-pick patterns from 3+ implementations

複数のリファレンスから良い要素を選び出す

最良の結果は、複数のソースからリファレンスを組み合わせることで得られます。

Example: Building a SaaS billing system

Reference 1 (Stripe API patterns):
  -> Take: Resource naming, error format, idempotency
  -> Take: Webhook event structure and signing

Reference 2 (Lago open-source billing):
  -> Take: Usage-based metering data model
  -> Take: Invoice generation pipeline

Reference 3 (Supabase auth schema):
  -> Take: Multi-tenant organization structure
  -> Take: Row-level security patterns

Reference 4 (Cal.com):
  -> Take: Subscription lifecycle state machine
  -> Take: Webhook delivery with retry logic

Result: A billing system built on patterns from 4 production-tested systems,
each designed by teams who spent months on exactly these problems.

リファレンスの品質基準

すべてのリファレンスが同等というわけではありません。以下の基準で評価してください。

基準	重要度	確認事項
本番環境での利用実績	高	実際の組織が本番環境に導入していますか？
コミュニティの規模	高	スター数、コントリビューター数、ダウンロード数
メンテナンス状況	高	最近のコミット、問題報告への迅速な対応
ドキュメント	中	パターンが文書化され、説明されていますか？
テストカバレッジ	中	リファレンスに十分なテストがありますか？
セキュリティ監査	中	セキュリティレビューを通過していますか？
シンプルさ	中	パターンは最小限で明確ですか？
移植性	低	パターンをほかのスタックに適用できますか？

認知の落とし穴

正当化	真実
「これを構築する方法は分かっています」	分かっているのは、あるバージョンの構築方法です。リファレンスを使えば、最良のバージョンを実現できます。
「これはリファレンスを使うほど複雑ではありません」	簡単なことでも、やり方を間違えると問題が積み重なります。スキーマのパターンが悪いと、すべてのクエリに永続的な影響が及びます。
「リファレンスは後で確認します」	まず調査してください。初期に行う構造上の判断ほど、後から覆すのが困難です。
「ユーザーから調査を依頼されていません」	ユーザーが求めているのは品質です。品質を実現する方法がリファレンスです。
「これに該当するリファレンスはありません」	必ずリファレンスはあります。隣接する分野、類似するパターン、類似システムを探してください。
「リファレンスを使うと時間がかかります」	間違ったものを構築するほうが、さらに時間がかかります。
「リファレンスより良いものを作れます」	それを証明してください。まずリファレンスを示し、そのうえで改善案を提案してください。
「AI は優れたパターンを生成できます」	AI が生成するのは、もっともらしいパターンです。もっともらしいからといって、本番環境で検証済みとは限りません。

ガードレール

禁止事項：

• Stripe／GitHub／Twilio のパターンを調査せずに API 設計を作成すること
• ドメイン固有の参考資料を見つけずにデータベーススキーマを作成すること
• スターターワークフローを確認せずに CI/CD を設定すること
• 認証ライブラリのパターンを調査せずにセキュリティを実装すること
• テスト戦略の参考資料なしにテストを作成すること
• 参考アーキテクチャを調査せずにアーキテクチャを選択すること

必須事項：

• 構築を始める前に、少なくとも 2 つの参考実装を見つけること
• 複雑なシステムでは、3 つ以上のソースからチェリーピックすること
• 参考資料とアプローチをユーザーに提示すること
• 特定の参考資料から特定のパターンを選んだ理由を説明すること
• より優れた参考資料を見つけたら、参考資料を更新すること

統合

このプロトコルはルーターです。他のプロトコルを呼び出します：

• godmode:ux-patterns — UI／UX の参考資料
• godmode:design-research — Web サイトデザインの参考資料
• godmode:github-search — 外部コードとライブラリの調査（GitHub、パッケージレジストリ、オープンソースのエコシステム）
• godmode:codebase-research — 内部コードベースのパターン照合（規約、類似ファイル、既存の実装）
• godmode:system-design — アーキテクチャ決定の参考資料
• godmode:quality-enforcement — 品質基準の参考資料
• godmode:security-protocol — セキュリティパターンの参考資料
• godmode:performance-tuning — パフォーマンスの参考資料
• godmode:project-bootstrap — プロジェクト構成の参考資料

呼び出し元：

• godmode:intent-discovery — 「何が存在するか？」のフェーズ中
• godmode:specification-first — 実証済みのパターンを仕様に反映するため
• godmode:task-planning — 計画を現実に即したものにするため

階層：

reference-engine (this protocol - the universal router)
+-- ux-patterns (UI/UX domain)
+-- design-research (website design domain)
+-- github-search (external code research domain)
+-- codebase-research (internal code pattern domain)
+-- system-design (structural design domain)
+-- quality-enforcement (quality domain)
+-- security-protocol (security domain)
+-- performance-tuning (performance domain)
+-- project-bootstrap (structure domain)
+-- [this protocol's built-in libraries] (API, DB, testing, CI/CD, DevOps, docs)