# ADR-2026-03-21 Stack Whitelist And Exception Process

## Purpose
记录 v1 默认技术栈白名单，以及何时允许偏离。

## When to Use
- 新项目选型
- 老项目迁移
- 团队想引入白名单外技术时

## Inputs
- 项目目标
- 性能与兼容要求
- 现有遗留约束

## Outputs
- 选型决策
- 例外审批结果

## Primary Agent/Model
项目 owner + `GPT-5.4 Pro xhigh`

## Secondary Agent/Model
`Claude Opus 4.6`

## Required Skills
- 无

## Steps
1. 先看是否能落到白名单轨道。
2. 如不能，写出偏离理由和范围。
3. 审批通过后更新模板与执行说明。

## Exit Criteria
- 项目主链路已落到一个明确轨道

## Failure Recovery
- 若白名单外技术已被引入但没有审批，视为待回退问题

## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)

## Status
Accepted

## Context
- 团队需要避免 agent 在语言、框架、路由、鉴权和 ORM 上随机选型。
- 同时要保留少量例外接口，处理遗留系统和特殊约束。

## Decision
- 默认语言：`TypeScript`
- 默认 UI：`React`
- 默认优先轨道：`Hono + React SSR/TanStack`
- 允许替代轨道：`Next.js 全栈`
- 默认基础组件、样式、鉴权、数据访问和 ORM：`shadcn/ui`, `Tailwind`, `Better Auth`, `TanStack Query`, `Drizzle`
- 禁止 `Python`、`PHP` 作为应用主链路默认语言
- 例外必须由项目 owner 与技术负责人批准，并写 ADR、更新 `CLAUDE.md`、更新相关 playbook 和模板

## Consequences
- agent 在主链路上的自由度下降，但一致性和生成质量上升
- 例外变成显式治理动作，而不是隐性扩散

## Revisit When
- 团队默认栈发生正式变更
- 某个白名单组件长期无法满足主流项目需求