Back to Details

scope-appropriate-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scope-Appropriate Architecture

适配规模的架构

Right-size every architectural decision to the project's actual needs. Not every project needs hexagonal architecture, CQRS, or microservices.
Core principle: Detect the project tier first, then constrain all downstream pattern choices to that tier's complexity ceiling.
让每个架构决策都适配项目的实际需求。并非所有项目都需要六边形架构、CQRS或微服务。
核心原则： 先确定项目层级，再将所有后续的模式选择限制在该层级的复杂度上限内。

The 6 Project Tiers

6个项目层级

TierLOC RatioArchitectureDBAuthTests
1. Interview/Take-home1.0-1.3xFlat files, no layersSQLite / JSONNone or basic8-15 focused
2. Hackathon/Prototype0.8-1.0xSingle file if possibleSQLite / in-memoryNoneZero
3. Startup/MVP1.0-1.5xMVC monolithManaged PostgresClerk/Supabase AuthHappy path + critical
4. Growth-stage1.5-2.0xModular monolithPostgres + RedisAuth serviceUnit + integration
5. Enterprise2.0-3.0xHexagonal/DDDPostgres + queuesOAuth2/SAMLFull pyramid
6. Open Source1.2-1.8xMinimal API surfaceConfigurableOptionalExhaustive public API
LOC Ratio = total lines / core business logic lines. Higher ratio = more infrastructure code relative to business value.
层级LOC 占比架构数据库认证测试
1. 面试/带回家作业1.0-1.3x扁平文件，无分层SQLite / JSON无或基础认证8-15个聚焦型测试
2. 黑客松/原型0.8-1.0x尽可能单文件SQLite / 内存数据库无无
3. 初创公司/MVP1.0-1.5xMVC单体应用托管式PostgresClerk/Supabase Auth主路径+关键场景测试
4. 成长期1.5-2.0x模块化单体应用Postgres + Redis认证服务单元测试+集成测试
5. 企业级2.0-3.0x六边形架构/DDDPostgres + 消息队列OAuth2/SAML完整测试金字塔
6. 开源项目1.2-1.8x极简API接口可配置可选全面的公共API测试
LOC 占比 = 总代码行数 / 核心业务逻辑行数。占比越高，相对于业务价值的基础设施代码越多。

Auto-Detection Signals

自动检测信号

SignalTier Indicator
README contains "take-home", "assignment", "interview"Tier 1
Time limit mentioned (e.g., "4 hours", "weekend")Tier 1-2
< 10 files, no CI, no DockerTier 1-2
.github/workflows/
present		Tier 3+
package.json
with 20+ dependencies		Tier 3+
Kubernetes/Terraform files presentTier 4-5
CONTRIBUTING.md
, 
CODE_OF_CONDUCT.md
Tier 6
Monorepo with 
packages/
or 
apps/
Tier 4-5
When confidence is low: Ask the user with 
AskUserQuestion
.
信号层级指示
README包含"take-home"、"assignment"、"interview"层级1
提及时间限制（如"4小时"、"周末"）层级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
询问用户。

Pattern Appropriateness Matrix

模式适配矩阵

PatternInterviewHackathonMVPGrowthEnterprise
Repository patternOVERKILLOVERKILLBORDERLINEAPPROPRIATEREQUIRED
Event-driven archOVERKILLOVERKILLOVERKILLSELECTIVEAPPROPRIATE
DI containersOVERKILLOVERKILLLIGHT ONLYAPPROPRIATEREQUIRED
Separate DTO layersOVERKILLOVERKILL1 EXTRA2 LAYERSALL LAYERS
MicroservicesNEVERNEVERNEVEREXTRACT ONLYAPPROPRIATE
CQRSOVERKILLOVERKILLOVERKILLOVERKILLWHEN JUSTIFIED
Hexagonal architectureOVERKILLOVERKILLOVERKILLBORDERLINEAPPROPRIATE
DDD (bounded contexts)OVERKILLOVERKILLOVERKILLSELECTIVEAPPROPRIATE
Message queuesOVERKILLOVERKILLBORDERLINEAPPROPRIATEREQUIRED
API versioningSKIPSKIPURL prefixHeader-basedFull strategy
Error handlingtry/catchconsole.logError boundaryError serviceRFC 9457
Loggingconsole.lognoneStructured JSONCentralizedOpenTelemetry
Rule of thumb: If a pattern shows OVERKILL for the detected tier, do NOT use it. Suggest the simpler alternative instead.
模式面试项目黑客松项目MVP成长期企业级
仓储模式过度设计过度设计临界合适必需
事件驱动架构过度设计过度设计过度设计选择性使用合适
DI容器过度设计过度设计仅轻量使用合适必需
独立DTO层过度设计过度设计1层额外2层全层级
微服务绝不使用绝不使用绝不使用仅提取核心合适
CQRS过度设计过度设计过度设计过度设计合理时使用
六边形架构过度设计过度设计过度设计临界合适
DDD（限界上下文）过度设计过度设计过度设计选择性使用合适
消息队列过度设计过度设计临界合适必需
API版本控制跳过跳过URL前缀基于Header完整策略
错误处理try/catchconsole.log错误边界错误服务RFC 9457
日志console.log无结构化JSON集中式OpenTelemetry
经验法则： 如果某模式在检测到的层级中显示为过度设计，则不要使用它。建议改用更简单的替代方案。

Technology Quick-Reference by Tier

各层级技术速查

ChoiceInterviewHackathonMVPGrowthEnterprise
DatabaseSQLite / JSON fileIn-memory / SQLiteManaged PostgresPostgres + RedisPostgres + queues + cache
AuthHardcoded / noneNoneClerk / Supabase AuthAuth serviceOAuth2 / SAML / SSO
State mgmtuseStateuseStateZustand / ContextZustand + React QueryRedux / custom + cache
CSSInline / TailwindTailwindTailwindTailwind + design tokensDesign system
APIExpress routesSingle file handlerNext.js API routesFastAPI / ExpressGateway + services
DeploymentlocalhostVercel / RailwayVercel / RailwayDocker + managedK8s / ECS
CI/CDNoneNoneGitHub Actions basicMulti-stage pipelineFull pipeline + gates
MonitoringNoneNoneError tracking onlyAPM + logsFull observability stack
选择面试项目黑客松项目MVP成长期企业级
数据库SQLite / JSON文件内存数据库 / SQLite托管式PostgresPostgres + RedisPostgres + 消息队列 + 缓存
认证硬编码 / 无无Clerk / Supabase Auth认证服务OAuth2 / SAML / SSO
状态管理useStateuseStateZustand / ContextZustand + React QueryRedux / 自定义+缓存
CSS内联 / TailwindTailwindTailwindTailwind + 设计令牌设计系统
APIExpress路由单文件处理器Next.js API路由FastAPI / Express网关+服务
部署localhostVercel / RailwayVercel / RailwayDocker + 托管服务K8s / ECS
CI/CD无无GitHub Actions基础版多阶段流水线完整流水线+ gates
监控无无仅错误追踪APM + 日志完整可观测性栈

Build vs Buy Decision Tree (Tiers 1-3)

自研vs采购决策树（层级1-3）

For Interview, Hackathon, and MVP tiers, always prefer buying over building:
CapabilityBUY (use SaaS)BUILD (only if)
AuthClerk, Supabase Auth, Auth0Core product IS auth
PaymentsStripeCore product IS payments
EmailResend, SendGridCore product IS email
File storageS3, Cloudflare R2Compliance requires on-prem
SearchAlgolia, Typesense Cloud> 10M docs or custom ranking
AnalyticsPostHog, MixpanelUnique data requirements
Time savings: Auth alone is 2-4 weeks build vs 2 hours integrate.
对于面试、黑客松和MVP层级，始终优先采购而非自研：
能力采购（使用SaaS）自研（仅当）
认证Clerk, Supabase Auth, Auth0核心产品就是认证
支付Stripe核心产品就是支付
邮件Resend, SendGrid核心产品就是邮件
文件存储S3, Cloudflare R2合规要求本地部署
搜索Algolia, Typesense Cloud超过10M文档或自定义排序
分析PostHog, Mixpanel独特的数据需求
时间节省： 仅认证一项，自研需2-4周，集成仅需2小时。

Upgrade Path

升级路径

When a project grows beyond its current tier, upgrade incrementally:
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)
Key insight: You can always add complexity later. You cannot easily remove it.
当项目成长超出当前层级时，逐步升级：
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)
核心见解： 你总能在后续添加复杂度，但很难轻易移除它。

When This Skill Activates

该技能的激活场景

This skill is loaded by:
  • brainstorm
    Phase 0 (context discovery)
  • implement
    Step 0 (context discovery)
  • quality-gates
    YAGNI check
  • Any skill that needs to right-size a recommendation
The detected tier is passed as context to constrain downstream decisions.
此技能在以下场景加载：
  • brainstorm
    阶段0（上下文发现）
  • implement
    步骤0（上下文发现）
  • quality-gates
    YAGNI检查
  • 任何需要适配规模的推荐的技能
检测到的层级会作为上下文传递，以限制后续决策。

Related Skills

相关技能

  • ork:brainstorm
    - Uses tier detection in Phase 0 to constrain ideas
  • ork:implement
    - Uses tier detection in Step 0 to constrain architecture
  • ork:quality-gates
    - YAGNI gate references this skill's tier matrix
  • ork:architecture-patterns
    - Architecture validation (constrained by tier)
  • ork:brainstorm
    - 在阶段0使用层级检测来限制想法
  • ork:implement
    - 在步骤0使用层级检测来限制架构
  • ork:quality-gates
    - YAGNI检查参考此技能的层级矩阵
  • ork:architecture-patterns
    - 架构验证（受层级限制）

References

参考资料

Load on demand with 
Read("${CLAUDE_SKILL_DIR}/references/<file>")
:
FileContent
interview-takehome.md
Tiers 1-2 in detail
startup-mvp.md
Tier 3 patterns and decisions
enterprise.md
Tiers 4-5 patterns and justification criteria
open-source.md
Tier 6 unique considerations
使用
Read("${CLAUDE_SKILL_DIR}/references/<file>")
按需加载：
文件内容
interview-takehome.md
层级1-2的详细内容
startup-mvp.md
层级3的模式和决策
enterprise.md
层级4-5的模式和判断标准
open-source.md
层级6的独特考量