tanstack-start-architecture

@architecture-rules.md @rules/project-structure.md @rules/routes.md @rules/services.md @rules/hooks.md @rules/import-protection.md @rules/middleware.md @rules/execution-model.md @rules/server-routes.md @rules/ssr-hydration.md @rules/platform.md @rules/conventions.md @rules/validation.md @references/official/tanstack-start-2026-09-22.md @references/official/tanstack-router-2026-09-22.md @references/official/api-drift-notes.md @references/official/current-docs-2026-09-22.md

TanStack Start 架构规范执行

应用 hypercore 的 TanStack Start 架构规则，但不要将团队约定与 TanStack 官方要求混为一谈。

<output_language>

默认使用韩语撰写所有面向用户的交付内容、保存的成果、报告、计划、生成的文档、摘要、交接说明、提交/消息草稿和验证说明，即使此规范文件以英语编写。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、软件包名称、专有名词和引用的源文摘录，并使用其要求的语言或原始语言。

只有在用户明确要求、现有目标成果必须为保持一致而使用其他语言，或机器可读契约要求使用精确的英语词条时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），面向用户的成果应优先使用这些资料。

</output_language>

• 在应用此规范前，验证项目是否为 TanStack Start / TanStack Router 项目。
• 为 loaders、服务端函数、导入保护、中间件、服务端路由以及 SSR/水合执行安全边界。
• 在适用范围内，应用 hypercore 关于路由文件夹、hooks、文件命名、注释和分层的约定。
• 将 TanStack 官方 API 事实保存在 references/official/ 中，以便在框架细节快速变化时更新，而不使核心规范变得臃肿。

<operating_mode>

此规范是自包含的。应用前不要依赖全局规范或外部编排。

规则分为以下类别：

• 官方 — TanStack 文档所述行为或 API 要求。
• 安全策略 — 用于确保安全性/运行时正确性的本地阻断规则。
• Hypercore 约定 — 本地/团队标准，可能比 TanStack 官方默认设置更严格。

如果用户明确要求使用 TanStack 官方默认设置，可放宽仅适用于 hypercore 的约定，但仍须遵守官方规则和安全规则。

</operating_mode>

<routing_rule>

当用户要求对现有 TanStack Start / TanStack Router 项目执行架构规范、提供实现指导或进行审查时，使用此规范。这包括路由结构、路由本地文件夹、loaders、服务端函数、服务端路由、中间件、导入保护、SSR/水合、平台设置以及共享的嵌套文件夹组织。

以下情况不要使用此规范：

• 项目不是 TanStack Start 或 TanStack Router 项目
• 用户只想要通用的 React/Vite 架构审查
• 任务仅为文档摘要，不涉及项目审计或实现指导
• 主要任务是与 Start 架构无关的安全、部署或测试修复

如果 TanStack 官方指导与 Hypercore 约定存在差异，应优先执行官方规则和安全规则，然后仅对涉及的架构部分应用 Hypercore 约定。

</routing_rule>

<instruction_contract>

字段	约定
意图	确保 TanStack Start 项目在架构上安全、易于维护，并符合官方 Start/Router 行为以及带标签的 Hypercore 约定。
触发条件	涉及路由、加载器、服务端函数、导入边界、SSR/水合、中间件、服务端路由、平台设置或共享文件夹布局的现有 Start/Router 项目工作。
范围	审查并指导受影响的项目架构、主题规则文件、官方参考资料、验证说明和小型可逆架构修复。
权限	用户/项目指令优先于本技能。对于 API 事实，TanStack 官方文档优先于 Hypercore 约定。安全策略会阻止有风险的运行时或导入边界变更。
依据	使用项目标识、本地配置/软件包文件、受影响的源文件路径、主题规则、官方参考资料、软件包类型检查以及验证命令输出。
工具	使用本地搜索/读取/编辑/验证命令；API 可能发生变化时，查阅当前官方文档；对破坏性迁移、凭据访问、网络副作用和生产环境变更设置审批门槛。
循环	无。本技能每次请求只执行一次强制检查；应用修复后运行一次 rules/validation.md 检查，只有用户要求再次检查时才重新执行。
输出	以韩语提供架构决策或审查结果，包括规则分类、变更文件（如有）、验证依据、剩余风险以及官方文档歧义说明。
验证	运行与受影响部分相关的 rules/validation.md 检查；如果本技能文件夹发生变更，也运行技能结构检查。
停止条件	适用的安全门槛通过、已应用或明确推迟 Hypercore 约定、已记录验证依据，并已注明未解决的 API 变化及其日期和来源后，即停止。

</instruction_contract>

<activation_examples>

正面示例：

• “审计这个 TanStack Start 应用是否违反服务端函数、加载器和 importProtection 规则。”
• “添加一个带搜索参数的 TanStack Start 路由，并确保架构合规。”
• “重构 Start 路由文件夹、钩子和服务端函数，使其遵循 hypercore 规则。”
• “检查这个 TanStack Start 项目中的加载器边界和服务端函数结构。”
• “审查这个 TanStack Start 文件夹结构，并强制使用嵌套的 src/modules 或 src/lib 分组。”

反面示例：

• “审查一个未使用 TanStack Start 的通用 React/Vite 应用。”
• “为 Codex 创建一个浏览器 QA 技能。”
• “总结 TanStack Router 文档，但不修改或审计项目。”

边界示例：

• “仅复制编辑 TanStack Start 静态隐私页面中的文本。” 仅将本技能用于快速边界检查。仅用于发布的页面不需要生成 -hooks/、-components/ 或 -functions/ 文件夹；只有在引入交互式 UI 或仅供路由使用的服务端操作时，才添加路由本地文件夹。

</activation_examples>

<project_validation>

强制执行规则前，确认至少存在一个 Start/Router 标识：

ls app.config.ts 2>/dev/null
grep -r "@tanstack/react-start" package.json 2>/dev/null
grep -r "@tanstack/react-router" package.json 2>/dev/null
ls src/routes/__root.tsx 2>/dev/null

如果不存在，请停止使用本技能，并转到常规实现/审查流程。

</project_validation>

<support_file_read_order>

只读取任务所需的内容：

1. architecture-rules.md：了解规则分类和阻断门槛摘要。
2. 根据变更涉及的部分查看主题规则：
   • rules/project-structure.md — 官方 Start 项目结构、src/routes、路由树生成、自定义路由目录、共享嵌套文件夹。
   • rules/routes.md — 路由组织、搜索参数验证、加载器、路由生命周期。
   • rules/services.md — 服务端函数、验证、查询／变更分层。
   • rules/hooks.md — 提取 Hook、内部 Hook 调用顺序、useServerFn 封装策略。
   • rules/import-protection.md — 客户端／服务端导入边界和 vite.config.ts 拒绝规则。
   • rules/middleware.md — 函数／请求中间件和 sendContext 验证。
   • rules/execution-model.md — 同构加载器和仅限特定环境的函数。
   • rules/server-routes.md — 合理的 HTTP 端点与内部应用 RPC。
   • rules/ssr-hydration.md — 确定性首次渲染、ClientOnly、路由 SSR 模式。
   • rules/platform.md — getRouter()、环境变量验证、路径别名、运维端点。
3. rules/conventions.md — 任何已修改文件的文件命名、TypeScript 风格、注释和错误类约定。
4. 当 Start API 行为会影响决策时，查看 references/official/tanstack-start-2026-09-22.md。
5. 当 Router／文件路由／搜索／加载行为会影响决策时，查看 references/official/tanstack-router-2026-09-22.md。
6. 当当前 Start 文档、插件配置、导入保护、服务端函数或执行控制 API 会影响决策时，查看 references/official/current-docs-2026-09-22.md。
7. 当文档相互冲突或当前软件包行为不明确时，查看 references/official/api-drift-notes.md。
8. 在声称已完成之前，查看 rules/validation.md。

</support_file_read_order>

阶段	任务	输出
0	验证这是 TanStack Start／Router 项目	范围判定
1	确定涉及的部分，并仅加载相关规则／参考文件	最小证据集
2	将每条适用规则归类为官方规则、安全策略或 Hypercore 约定	执行计划
3	自动应用安全、局部且可逆的修复	代码或技能变更
4	除非明确提出要求，否则暂缓大范围迁移	待办事项或交接说明
5	运行 rules/validation.md 中的验证检查	有证据支持的完成结果

<blocking_safety_summary>

如果已修改代码会导致以下情况，务必先阻止或修复，再继续：

• 从同构加载器／客户端可访问代码中读取密钥、数据库客户端、文件系统或特权 SDK。
• 在编译器无法识别的边界（例如 createServerFn 或 createServerOnlyFn）之外，保留仅限服务端的导入。
• 禁用导入保护，或覆盖现有的 tanstackStart() 配置，而不是扩展该配置。
• 使用服务端函数执行变更，却不进行运行时输入验证。
• 将不可信的 sendContext 值视为已验证的服务端数据。
• 引入会导致水合不稳定的首次渲染输出（例如 Date.now()、随机 ID 或区域设置／时区差异），却没有稳定策略。

</blocking_safety_summary>

<hypercore_conventions_summary>

除非用户只要求遵循官方默认设置，否则对已修改文件应用以下约定：

• 应用页面优先使用路由目录，而非扁平路由文件。
• 含交互逻辑的页面／组件应将逻辑提取到 -hooks/；仅用于发布的静态页面除外。
• 集成服务端的页面默认通过路由本地 hooks 调用 src/modules/<domain>/<feature>/ 中的服务端函数。仅当操作只用于单个路由时，才例外使用路由本地的 -functions/。
• 文件路由使用 export const Route = createFileRoute(...)。
• 保持路由精简：路由／页面 UI -> hooks/query -> 路由本地例外或模块服务端函数 -> modules/lib/db/integrations 层。
• 默认将服务端函数放在 src/modules/<domain>/<feature>/<resource>.functions.ts。仅当操作只用于单个路由时，才使用路由本地的 -functions/<resource>.functions.ts。
• 将服务端函数封装放在 .functions.ts 文件中，将 DB／密钥／文件系统辅助代码放在 .server.ts 文件中，并将验证／DTO／query-key 代码放在客户端安全的 schema／辅助文件中。
• 添加或重组受影响的共享代码时，确保使用嵌套的共享目录，例如 src/modules/<domain>/<feature>/、src/lib/<domain>/、src/db/<area>/、src/server/<area>/、src/integrations/<provider>/ 和 src/config/<area>/；除非记录了明确的项目例外，否则不要添加新的直接叶子文件，例如 src/modules/foo.ts 或 src/lib/foo.ts。
• 不要在 functions/index.ts 或 src/modules/<domain>/<feature>/index.ts 中混合导出安全代码与仅限服务端的代码。
• 使用 kebab-case 文件名、显式返回类型，不使用 any，使用 const 箭头函数，并为有意义的代码组添加韩语块注释。

</hypercore_conventions_summary>

在宣布工作完成之前：

• 运行 rules/validation.md 中针对任务的检查。
• 确认任何已编辑规则中的官方与 hypercore 标签均得到保留。
• 确认支持文件均由 SKILL.md 直接链接，无需沿间接引用链查找。
• 确认英文和韩文入口对触发条件、边界、工作流、约定和阅读顺序的描述保持一致。
• 确认受影响的 src/modules、src/lib、src/integrations 等共享目录采用合理的嵌套分组，或记录了明确的例外。
• 确认涉及大量服务端函数的更改保留 .functions.ts／.server.ts 的分离、静态直接导入以及 auth／CSRF 边界。
• 记录任何尚未解决的 TanStack API 歧义，并附上来源链接和准确日期。