scope-appropriate-architecture

与项目规模相称的架构

让每项架构决策都与项目的实际需求相匹配。并非每个项目都需要六边形架构、CQRS 或微服务。

核心原则： 先判断项目所属层级，再将所有后续模式选择限制在该层级的复杂度上限内。

---

6 个项目层级

层级	代码行数比	架构	数据库	身份验证	测试
1. 面试/带回家作业	1.0-1.3x	扁平文件，无分层	SQLite / JSON	无或基础验证	8-15 个重点测试
2. 黑客松/原型	0.8-1.0x	尽可能使用单文件	SQLite / 内存	无	无
3. 初创公司/MVP	1.0-1.5x	MVC 单体	托管 Postgres	Clerk/Supabase Auth	成功路径 + 关键测试
4. 成长阶段	1.5-2.0x	模块化单体	Postgres + Redis	身份验证服务	单元测试 + 集成测试
5. 企业级	2.0-3.0x	六边形架构/DDD	Postgres + 队列	OAuth2/SAML	完整测试金字塔
6. 开源	1.2-1.8x	精简 API 表面	可配置	可选	穷尽式公共 API 测试

代码行数比 = 总行数 / 核心业务逻辑行数。比值越高，相对于业务价值的基础设施代码就越多。

---

自动检测信号

信号	层级指标
README 包含 "take-home"、"assignment"、"interview"	层级 1
提到时间限制（例如 "4 hours"、"weekend"）	层级 1-2
文件少于 10 个，无 CI，无 Docker	层级 1-2
存在 .github/workflows/	层级 3+
package.json 包含 20 个以上依赖项	层级 3+
存在 Kubernetes/Terraform 文件	层级 4-5
存在 CONTRIBUTING.md、CODE_OF_CONDUCT.md	层级 6
包含 packages/ 或 apps/ 的单体仓库	层级 4-5

置信度较低时： 使用 AskUserQuestion 询问用户。

---

模式适用性矩阵

模式	面试	黑客松	MVP	成长阶段	企业级
仓储模式	过度设计	过度设计	临界	适用	必需
事件驱动架构	过度设计	过度设计	过度设计	选择性采用	适用
DI 容器	过度设计	过度设计	仅轻量使用	适用	必需
独立 DTO 层	过度设计	过度设计	多 1 层	2 层	所有层
微服务	绝不采用	绝不采用	绝不采用	仅在拆分时采用	适用
CQRS	过度设计	过度设计	过度设计	过度设计	有充分理由时采用
六边形架构	过度设计	过度设计	过度设计	临界	适用
DDD（限界上下文）	过度设计	过度设计	过度设计	选择性采用	适用
消息队列	过度设计	过度设计	临界	适用	必需
API 版本控制	跳过	跳过	URL 前缀	基于 Header	完整策略
错误处理	try/catch	console.log	错误边界	错误服务	RFC 9457
日志记录	console.log	无	结构化 JSON	集中式	OpenTelemetry

经验法则： 如果某个模式对检测出的层级显示为过度设计，就不要使用它。应改为建议更简单的方案。

---

按层级划分的技术速查表

选择	面试	黑客松	MVP	增长阶段	企业级
数据库	SQLite / JSON 文件	内存 / SQLite	托管 Postgres	Postgres + Redis	Postgres + 队列 + 缓存
身份验证	硬编码 / 无	无	Clerk / Supabase Auth	身份验证服务	OAuth2 / SAML / SSO
状态管理	useState	useState	Zustand / Context	Zustand + React Query	Redux / 自定义 + 缓存
CSS	内联 / Tailwind	Tailwind	Tailwind	Tailwind + 设计令牌	设计系统
API	Express 路由	单文件处理程序	Next.js API 路由	FastAPI / Express	网关 + 服务
部署	localhost	Vercel / Railway	Vercel / Railway	Docker + 托管服务	K8s / ECS
CI/CD	无	无	基础 GitHub Actions	多阶段流水线	完整流水线 + 门禁
监控	无	无	仅错误跟踪	APM + 日志	完整可观测性技术栈

---

构建还是购买决策树（第 1–3 层）

对于面试、黑客松和 MVP 层级，始终优先购买，而非自行构建：

能力	购买（使用 SaaS）	构建（仅当）
身份验证	Clerk、Supabase Auth、Auth0	身份验证本身就是核心产品
支付	Stripe	支付本身就是核心产品
电子邮件	Resend、SendGrid	电子邮件本身就是核心产品
文件存储	S3、Cloudflare R2	合规要求本地部署
搜索	Algolia、Typesense Cloud	文档超过 1,000 万份或需要自定义排名
分析	PostHog、Mixpanel	有独特的数据需求

**节省时间：**仅身份验证一项，自行构建需要 2–4 周，集成只需 2 小时。

---

升级路径

当项目发展超出当前层级时，逐步升级：

Tier 2 (Prototype) → Tier 3 (MVP)
  Add: Postgres, basic auth, error boundaries, CI

Tier 3 (MVP) → Tier 4 (Growth)
  Add: Redis cache, background jobs, monitoring, module boundaries

Tier 4 (Growth) → Tier 5 (Enterprise)
  Add: DI, bounded contexts, message queues, full observability
  Extract: First microservice (only the proven bottleneck)

**关键要点：**复杂性总是可以之后再增加，但很难轻易移除。

---

此技能的触发时机

此技能由以下流程加载：

• brainstorm 第 0 阶段（上下文发现）
• implement 第 0 步（上下文发现）
• quality-gates 的 YAGNI 检查
• 任何需要合理确定建议范围的技能

检测到的层级会作为上下文传递，以约束下游决策。

---

相关技能

• ork:brainstorm - 在第 0 阶段使用层级检测来约束创意
• ork:implement - 在第 0 步使用层级检测来约束架构
• ork:quality-gates - YAGNI 门禁引用此技能的层级矩阵
• ork:architecture-patterns - 架构验证（受层级约束）

---

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
interview-takehome.md	详细介绍第 1–2 层
startup-mvp.md	第 3 层模式与决策
enterprise.md	第 4–5 层模式与论证标准
open-source.md	第 6 层的独特考量