skills/cc-switch-dev-workflow/references/knowledge-base/platform/framework-decision-matrix.md

Platform Policy: Framework Decision Matrix

Purpose

在 Next.js 全栈 与 Hono + React SSR/TanStack 两条允许轨道之间做可重复的选择，而不是让 agent 自行随机决定。

When to Use

• 新项目初始化时
• 老项目需要明确迁移目标时
• 团队对 “Next.js 还是 Hono” 出现争议时

Inputs

• 产品是否以前端页面为主
• API 边界是否需要长期清晰分层
• SSR/边缘部署要求
• 团队是否需要复用独立服务层

Outputs

• 选定轨道
• 该轨道下保留或替代的技术组合

Primary Agent/Model

GPT-5.4 Pro xhigh

Secondary Agent/Model

Claude Opus 4.6

Required Skills

• spec-reviewing

Steps

1. 先看项目交付形态和团队协作方式。
2. 按矩阵选一条轨道，不接受双主栈并行。
3. 把选择结果写入 CLAUDE.md 和 Setup 阶段产物。

Exit Criteria

• 轨道已经确定
• 相关被替代组件已经说明清楚

Failure Recovery

• 如果出现两条轨道同时存在的设计，先回到单轨道
• 如果团队只是因为“看起来都不错”而摇摆，优先选择更有边界感的 Hono + React SSR/TanStack

Related Templates

• ../templates/claude-md-template.md

Decision Matrix

条件	选 Hono + React SSR/TanStack	选 Next.js 全栈
需要清晰前后端边界	是	否
需要独立服务层或未来拆服务	是	否
团队希望统一 TanStack Router + Query 心智	是	否
更看重单仓单应用的快速落地	否	是
页面和服务逻辑高度耦合	否	是
需要高度可控的 API 中间层	是	否

Track A: Hono + React SSR/TanStack

• 默认场景：内部工具、业务系统、需要清晰服务边界的产品
• 固定组合：Hono + React + TanStack Router + TanStack Query + Better Auth + shadcn/ui + Tailwind + Drizzle
• 优点：边界清晰，迁移和拆分成本低，适合多 agent 任务切片
• 代价：初始装配稍多，需要更强的工程纪律

Track B: Next.js Full Stack

• 默认场景：页面驱动、内容驱动、单体交付优先的应用
• 固定组合：Next.js + React + Better Auth + shadcn/ui + Tailwind + Drizzle
• 替代说明：本轨道中 Next.js App Router 替代 TanStack Router；服务层由 route handlers / server actions 替代 Hono
• 优点：统一框架、上手快、页面与服务同仓同形态
• 代价：边界容易模糊，后续抽服务时需要更多治理

Tie-Break Rule

• 如果没有明确理由支持 Next.js 全栈，默认回到 Hono + React SSR/TanStack