reference-engine

这是管辖所有“参考优先”行为的元协议。如果你正在构建某个项目，但没有适用于该领域的专用参考协议，那么本协议就是你的参考系统。

构建之前，必须先找到参考。绝无例外。

参考引擎：通用参考优先系统

概述

每个领域都已积累了数千小时的专业工程实践。API 经过设计，架构经过完善，流水线经过实战检验，模式经过打磨。将它们作为参考并非偷懒，而是工程智慧。

核心原则： 在构建任何东西之前，先找到最佳的现有参考。提取其中的模式。以经过验证的基础为起点，而不是凭空假设。

绝无例外。没有变通办法。没有捷径。

首要指令

NO BUILDING WITHOUT A REFERENCE

如果你没有在正在处理的领域中搜索经过验证的参考，那你就是在无视数千小时的专业工程实践。支付 API 应借鉴 Stripe 的 API 模式，而不是采用通用的 AI 生成端点。

何时使用

始终使用。 本协议是路由器。它根据要构建的内容，决定应启用哪套参考系统。

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

数据库架构参考

按领域划分的参考模式：

领域	架构模式	来源
用户与身份验证	Users -> Roles -> Permissions（RBAC）	Auth0、Supabase 身份验证架构
电子商务	Products -> Variants -> Orders -> LineItems	Shopify 架构、Medusa.js
多租户 SaaS	Organizations -> Members -> Resources	Clerk、WorkOS 模式
CMS	Content -> Versions -> Media -> Taxonomies	Strapi、Payload CMS 架构
社交	Users -> Posts -> Comments -> Reactions -> Follows	Mastodon、Lemmy 架构
消息传递	Conversations -> Participants -> Messages	Matrix 协议、Slack 数据模型
排程	Events -> Slots -> Bookings -> Availability	Cal.com 架构
分析	Events -> Sessions -> Properties（星型架构）	PostHog、Plausible 架构
库存	Products -> Warehouses -> Stock -> Movements	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 测试
基础设施	计划 -> 应用 -> 验证	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 示例	审计跟踪、时态查询
CQRS	Axon Framework 示例	大规模读写分离
仓储模式	Spring Data、TypeORM	数据访问抽象
中间件模式	Express、Koa、Hono	请求流水线、横切关注点
插件系统	Vite、ESLint、Webpack	可扩展性、钩子
队列/工作器	BullMQ、Celery	后台任务、异步处理
发布/订阅	Redis Streams、NATS	事件驱动通信
速率限制	Upstash ratelimit	API 保护、公平使用
功能标志	Unleash、LaunchDarkly SDK	渐进式发布、A/B 测试
缓存	Redis 模式、SWR	性能、过期后重新验证

代码模式参考清单：

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	单体 + 托管数据库	Rails、Django、Next.js 全栈
小型团队	模块化单体	Shopify 的方法（组件）、Laravel 模块
成长阶段	单体 -> 提取服务	Segment 的 centrifuge 模式
大规模	微服务 + 事件总线	Netflix OSS、Uber 的领域导向架构
无服务器	函数 + 托管服务	SST（sst.dev）模式、Vercel 的架构
边缘	边缘计算 + CDN	Cloudflare Workers 模式、Deno Deploy

安全参考

按关注点划分的参考实现：

关注点	来源	关键模式
身份验证	Auth.js (NextAuth)	会话策略、提供程序模式、CSRF 防护
授权	CASL, Casbin	ABAC/RBAC 策略、权限检查
输入验证	Zod, Valibot	在边界处进行架构验证
速率限制	Upstash ratelimit	滑动窗口、令牌桶
CORS	Express CORS 中间件	来源白名单、凭据处理
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 文档	清晰的示例、语言选项卡、可直接复制粘贴
README	优秀的 GitHub README	徽章、快速入门、功能列表、贡献指南
架构	arc42, C4 model	决策记录、上下文图
操作手册	PagerDuty 操作手册	事件响应、升级处理
更新日志	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 — 网站设计参考
• 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)