# 现代 TypeScript 项目启动

创建一个能持续演进、又不提前膨胀为平台的紧凑项目。本指南的核心是通用工程边界：范围、模块、数据权威、配置、文档和交付。它从 Study Buddy 与 IELTS Buddy 的实践中提炼，但不会带入其学习业务、服务商、凭据、部署目标或 Agent 设计。

## 适用场景

当用户要求新建 TypeScript Web 项目、建立仓库／开发／部署约定，或进行跨模块的基础工程改造时使用。面对已有仓库，先阅读其中的 `AGENTS.md`、贡献说明、包清单、现有文档与工作区状态；项目本地规则优先。

不用于普通的局部功能或样式修改，也不得仅因本指南存在而把既有产品强行迁移到这套技术栈。

## 目标

交付当前产品实际需要的最小完整基础：

- 清晰的应用形态和可实际运行的本地开发路径；
- 一份结合当前项目实际情况编写、能约束后续 Agent 行为的根目录 `AGENTS.md`；
- 一个已初始化、忽略规则正确、能以原子本地提交交付改动的 Git 仓库；
- 不让凭据进入浏览器构建产物或日志的真实配置边界；
- 能区分决策、已实现行为和后续工作的文档；
- 与改动风险相称的验证，以及获得发布授权后可安全观测的发布设计。

以下均为按需能力，并非脚手架清单：Worker、队列、Agent 运行时、向量检索、蓝绿槽、公开 SEO 页面或额外包。只有当前有明确需求时才引入。对象存储也不为空项目预建，但产品一旦包含用户上传、运行时生成或可替换的图片／文件，就必须使用 OSS 或 S3 兼容对象存储，而不是把这些资源写入 Git 或应用服务器本地目录。

对于包含账号、业务数据、写入或外部副作用的产品，交付必须包含真实的服务端实现和实际可调用的界面链路，不能以静态页面、前端假数据、假按钮或“后端待接入”的演示替代。只有用户明确要求纯静态站点时，才可以不建立后端。性能问题先测量并在拥有该瓶颈的模块内解决；没有证据时，不新建“性能模块”、通用缓存层或优化框架。

## 通用边界

- 先写清本次要改变的用户结果、明确不做的内容，以及尚未获得授权的外部动作。参考项目是决策证据，不是可直接复制的需求清单。
- 每个模块只拥有一类清楚的知识和事实；调用方只依赖其业务操作，不了解内部表、锁、存储对象或固定调用顺序。采用渐进式架构：从当前最小的模块化单体开始，只在已出现的独立边界上演进，不新增纯转发层、重复状态或“以后可能需要”的共享模块。
- 为每条关键链路明确：谁输入、谁拥有权威数据、谁有权限写入、失败／重试／并发时发生什么、以及如何验证。浏览器缓存、页面位置、模型输出和演示数据都不是业务权威。
- 范围变化、外部发送、推送、发布、权限变更、删除数据和凭据轮换必须有明确授权；普通可逆实现选择则直接完成，不把它们变成无休止的确认点。

需要进行架构划分、增加跨层能力或审阅是否越界时，阅读[通用工程边界](engineering-boundaries.md)。

## 工作方式

1. 先明确首个用户任务、托管约束、数据敏感性、协作方式以及本次是否包含发布。优先使用已给上下文并检查工作区；不要虚构产品目录、样例数据或外部集成。
2. 当应用同时需要 Web 界面和服务端时，默认从一个 Next.js 模块化单体开始，让页面、服务端入口、业务服务和数据库边界保留在同一应用中。小型项目的管理后台也留在这个应用、共用同一域名和认证上下文，由有权限的账号经受保护的入口访问。只有出现独立部署、多个客户端、独立 Worker、真实跨应用复用，或独立后台的组织／安全边界已经成立时，才升级为 pnpm workspace，并按需拆出 API、后台或共享包。
3. 在通用基础设施之前先打通一条端到端用户链路。需要持久化、授权或副作用时，界面必须通过实际 API 调用服务端业务实现，写入真实的开发数据源；前端假数据仅可用于明确标识、与正式记录隔离的必要演示。服务端负责身份、授权、写入和可见副作用；路由、BFF 与按需存在的模型 Tool 只做协议适配，业务服务负责校验、事务、幂等、并发与稳定的失败语义。
4. 接口保持少且使用业务命名。优先让一个深模块完整完成一项操作，而不是新增仅改名或透传参数的层。不要为假想的客户端、供应商、性能优化或未来需求增加兼容层、功能开关、配置项、通用模块或抽象。
5. 每个经本指南新建或进行基础工程改造的项目都必须建立或审阅根目录 `AGENTS.md`，并根据实际项目写明范围与授权、禁止越界和过度设计、真实前后端交付、架构与数据权威、数据库迁移 SQL、Git 与 `.gitignore`、二进制资源、配置密钥、分支提交、验证和文档更新规则。不能只复制空泛口号；命令、目录、ORM、迁移产物和协作流程必须与仓库一致。详细要求与中文模板见 [`AGENTS.md` 项目规范](../workflow/agents-md-standard.md)。开发流程、架构、部署和设计原则分别在聚焦文档中保留唯一事实来源；链接证据与状态记录，不重复抄写。行为改动时同步更新相关文档。
6. 确认 Git CLI 可用并且项目处于 Git 仓库中；缺少 Git CLI 时按当前系统的标准方式安装／配置，只有新目录没有仓库边界时才初始化仓库。建立与实际工具链匹配的 `.gitignore`，并保留锁文件、迁移 SQL 和必要源码。二进制文件不直接进入 Git；图片／文件使用对象存储，元数据与业务数据进入 PostgreSQL，服务不得依赖个人电脑上的资源文件。禁止用本地 JSON 文件充当可变业务数据库。每项完整改动完成最小验证后，默认生成一次仅包含本任务文件的原子本地提交；推送仍需独立授权。详细规则见 [Git、资源与持久化](../workflow/git-repository-and-assets.md)和[静态资源与对象存储](../performance/static-assets.md)。
7. 保证本地开发可复现，且不覆盖开发者已有配置或数据。使用锁文件与可复现安装；本地进程应有明确就绪检查、受控端口和安全的启停行为。涉及后端代码、服务端依赖、运行时配置或 Schema 的改动，交付前必须用项目标准命令重启对应的本地／测试服务，等待真实就绪并验证受影响链路；热更新不替代最终重启。只能操作确认属于本项目的进程／容器，不能仅因为端口被占用就终止无关进程；生产重启仍属于需要明确授权的发布动作。
8. 主动确定配置所有权。默认提交模板，并在 Git 外提供真实密钥。只有项目负责人明确要求、仓库访问模型确实合适、并且已验证部署／构建／日志边界时，才允许版本化完整环境文件；不能从参考项目推断这一例外。
9. 按改动影响选择验证。检查受影响路径及其关键不变量；广泛检查只用于广泛改动。记录实际结果和限制；不得通过弱化断言、拉长超时或隐瞒失败来制造通过结果。
10. 推送、生产发布、权限变更、删除数据和轮换凭据是独立授权边界。完成本地提交或构建成功，不构成任何一项操作的授权。

## 架构与交付选择

新项目的默认推荐基线是 **Next.js + TypeScript + Tailwind CSS + shadcn/ui + PostgreSQL + Docker**。数据访问层在 **Drizzle 与 Prisma 中二选一**：需要贴近 SQL、显式控制 Schema 与迁移时优先 Drizzle；团队更看重 Schema 驱动的 Client、成熟工具链与快速建模时选择 Prisma。Redis 不是默认必装项，只有出现跨实例缓存、限流、分布式协调、队列或 Pub/Sub 等已确认需求时才引入。不要同时安装两套 ORM，也不要为了“技术栈完整”预建空的 Redis、缓存或性能模块。

选择初始拓扑、编写工程文档、加入持久化或 Worker、定义配置所有权、建立发布路径时，阅读[项目蓝图](project-blueprint.md)。其中列出可复用的决策标准和交付不变量。需要具体技术取舍时，阅读[技术选型与落地](technology-selections.md)；初始化仓库、设计 `.gitignore`、处理二进制资源或确定 JSON／SQL 边界时，阅读 [Git、资源与持久化](../workflow/git-repository-and-assets.md)；创建或审阅项目根约定时，阅读 [`AGENTS.md` 项目规范](../workflow/agents-md-standard.md)；建立或调整其他项目文档时，阅读[工程文档体系](../workflow/documentation-system.md)。

以下参考只在用户明确提出相应产品能力时才阅读：复用 Study Buddy 同款新通短信登录时，阅读[新通短信登录](../extensions/xintong-sms-identity.md)；需要内置 AI Agent 时，阅读[单 Agent 与受控工具](../extensions/agent-runtime.md)。它们都只复用协议形态与安全边界，不能复制任何现有项目的凭据、Cookie、数据库、用户资料或会员规则。

当产品确实需要 BFF、跨端共享契约、更严格的可观测性、公开 Agent API 或能力分发时，再阅读[IELTS Buddy 的扩展工程经验](../extensions/ieltsbuddy-development-experience.md)。

已有项目以锁文件支持的当前版本为准；新项目选择与 Node LTS 兼容的稳定版本并锁定。不得复制其他项目的版本号、镜像 digest、主机、域名、供应商或凭据。

面向公网的服务必须确保浏览器得不到任何秘密环境变量，内部应用端口绑定私有接口，通过 HTTPS 终止和同源 API 路由提供服务，且测试与生产的数据、配置、存储和认证上下文相互隔离。Schema 演进保持在线兼容：先扩展，再切换应用行为，最后在后续发布中收缩。不得修改已应用的迁移，也不得假设数据库回滚能安全撤销已上线的结构变化。

## 交付说明

完成时说明实际创建或修改的基础能力、本地入口、根目录 `AGENTS.md` 与其他文档位置、数据库迁移及其已提交 SQL、对象存储边界、执行过的检查及结果、本地提交哈希，以及刻意延期的事项。没有数据库或文件资源变更时如实说明，不为满足格式制造空迁移或空 OSS 服务。仅有编译成功或替身检查通过时，不得声称服务商集成、生产就绪、安全认证或用户验收已经完成。