# 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`](../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`