hono-architecture

@architecture-rules.md @rules/conventions.md @rules/project-structure.md @rules/routes.md @rules/handlers.md @rules/middleware.md @rules/validation.md @rules/database.md @rules/openapi.md @rules/errors.md @rules/testing-rpc.md @rules/platform.md @references/official/hono-docs.md @references/official/drizzle-docs.md

Hono 架构规范执行

<output_language>

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

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、包名、专有名称和引用的源文摘录所需或原有的语言。

仅当用户明确要求、现有目标产物必须保持其他语言以确保一致性，或机器可读契约要求使用精确的英语词元时，才使用其他语言。如果存在本地化模板或参考文件（例如 *.ko.md 或 *.ko.json），则优先将其用于面向用户的产物。

</output_language>

• 在进行代码更改前，强制执行 Hypercore Hono 架构规则。
• 在应用 Hono 专属检查之前，确认目标确实是 Hono 项目。
• 确保路由组合、处理程序、中间件、验证、数据库/ORM、Drizzle、OpenAPI/Swagger、平台入口点、错误处理、测试和类型化 RPC 边界保持一致。
• 报告发现时，将比 Hono 更严格的要求标注为 Hypercore 规范。

<routing_rule>

将此规范用于 Hono 应用的实现、审查、修复或架构规范执行。

不要将此规范强加给非 Hono 项目、通用 Express/Fastify 工作、未跨越架构边界的纯复制修改，或用户明确要求采用不含 Hypercore 规范的 Hono 官方默认行为的请求。

此规范是自包含的。仅为应用 Hono 规则，不要受阻于全局规范或外部编排界面。

</routing_rule>

<instruction_contract>

字段	契约
意图	确保 Hono 项目在架构上安全、类型明确、有文档记录，并符合 Hono 官方行为及带有明确标注的 Hypercore 规范。
触发条件	涉及路由、处理程序、中间件、验证、DB/ORM、Drizzle、OpenAPI、平台入口点、错误处理、测试或 RPC 的 Hono 工作。
范围	审查并指导所触及的 Hono 源代码、主题规则文件、官方参考资料、验证说明，以及小型且可逆的架构修复。
权威性	用户/项目指令优先于此规范。对于 API 事实，Hono/Drizzle 官方文档优先于 Hypercore 规范。安全、类型、验证和数据边界规则会阻止不安全的更改。
证据	使用项目指示、本地包/源文件、所触及的路径、主题规则、必要时用于核实差异的官方参考资料，以及验证命令输出。
工具	使用本地搜索/读取/编辑/验证命令；对迁移、凭据访问、生产环境副作用、运行时适配器替换及大范围重写进行把关。
循环	不使用优化循环。修复一轮后，最多允许针对第 3 步检查项及所触及检查进行两轮验证与修复；只有更改仍在所触及范围内且通过这些检查时才保留，并在验证清单通过或报告阻碍项时停止。
输出	使用韩语撰写架构发现或实现摘要，包含规则分类、（如有）已更改文件、验证证据、剩余风险，以及官方规则与 Hypercore 规范的标注。
验证	在宣布完成前，运行相关项目检查，以及所触及方面的最终清单。
停止条件	在明确项目模式、适用检查通过或报告为阻碍项，并记录验证证据后停止。

</instruction_contract>

<activation_examples>

正面示例：

• Review this Hono app structure before I add more routes.
• Refactor a Hono API so routing, middleware, and validators follow one architecture.
• Add a new Hono route and make sure testClient and AppType inference still work.
• Wire Drizzle into this Hono API without routes talking to the database directly.
• Review database, migration, and OpenAPI boundaries before adding a new persisted endpoint.
• hono-architecture 전체 수정
• Run the Hono architecture skill in full-remediation mode.

负面示例：

• Create a generic Express middleware guide.
• Review a React SPA that does not use Hono.

边界示例：

• Make a tiny copy-only response text change in a Hono handler. 如果不影响架构边界，直接编辑就足够了。

• Use official Hono defaults only, not the extra hypercore conventions. 此技能仍适用，但应放宽超出官方文档范围的 hypercore 专属严格要求。

</activation_examples>

<trigger_conditions>

调用参数

参数会改变修复范围，但不会改变核心规则。

参数	含义
missing	审查并修复请求涉及或已修改的 Hono 范围。未修改的旧代码偏差，如果仅涉及 hypercore 约定或迁移风险较高，可以作为待办事项报告。
전체 수정	全面修复模式。扫描整个检测到的 Hono 应用，并修复所有安全、局部、可逆且可验证的违规项。不要只检查已修改的文件。
full fix / fix all	与 전체 수정 相同。
공식 기본만 / official defaults only	默认采用官方 Hono 行为；将仅适用于 hypercore 的约定降级为可选发现项，除非用户还要求 전체 수정。

在 전체 수정 模式下：

• 将所有 Hono 应用文件、路由模块、处理程序、中间件、验证模式、OpenAPI 文件、数据库／仓库边界、测试／RPC 接口和运行时入口纳入范围。
• 扫描已检测到的 Hono 源代码树中的文件夹和文件名。除框架／工具要求的名称（如 package.json、tsconfig.json、drizzle.config.ts、锁文件、生成的声明文件和明确配置的迁移产物）外，文件夹和文件名必须采用 kebab-case。
• 如果能在同一次更改中安全更新导入、测试路径、路由引用和配置引用，则将 camelCase 或 PascalCase 文件夹／文件重命名为 kebab-case。
• 在整个应用中应用 Step 3.5 列出的所有低风险自动修复，而不只处理已修改的文件。
• 对于无法在同一次运行中安全完成的高风险更改，应留下明确的阻塞项／待办事项，并注明文件路径和未通过的规则。不要默默忽略。

</trigger_conditions>

第 1 步：项目验证

开始任何工作前，确认目标是 Hono 项目：

rg -n '"hono"|@hono/' package.json
rg -n "from 'hono'|from \"hono\"" src app .
rg -n "new Hono\\(|createFactory\\(|testClient\\(|hc<|OpenAPIHono|swaggerUI" src app .

如果这些标志都不存在，请停止，并转回常规实现或审查流程，而不要强行套用 Hono 规则。

如果工作范围涉及数据库，还要检查数据库标志：

rg -n '"drizzle-orm"|drizzle-kit|DATABASE_URL|D1Database|@neondatabase|@libsql|pg|postgres' package.json drizzle.config.ts src app .
rg -n "from 'drizzle-orm|from \"drizzle-orm|db\\.|transaction\\(|migrate\\(|schema|repositories?" src app .

如果已启用 전체 수정 模式，请在编辑前进行全面发现：

rg --files src app routes 2>/dev/null
rg -n "new Hono\\(|app\\.route\\(|basePath\\(|validator\\(|zValidator\\(|standardValidator\\(|OpenAPIHono|swaggerUI|testClient\\(|hc<|drizzle-orm|DATABASE_URL|D1Database|@neondatabase|@libsql" src app .

第 2 步：阅读架构规则

<support_file_read_order>

编辑前，请阅读详细规则：

• architecture-rules.md
• rules/project-structure.md
• rules/conventions.md
• rules/routes.md
• rules/handlers.md
• rules/middleware.md
• rules/validation.md
• rules/database.md
• rules/openapi.md
• rules/errors.md
• rules/testing-rpc.md
• rules/platform.md

如果更改依赖当前框架行为，或需要引用官方文档为某项规则提供依据，请阅读：

• references/official/hono-docs.md
• references/official/drizzle-docs.md

### 任务到规则的路由

根据你要进行的更改，阅读相应文件：

• 对于项目配置文件、文件夹归属、依赖方向、单体仓库或结构迁移，请阅读 rules/project-structure.md
• 对于路由组合、挂载顺序、回退位置或子应用结构，请阅读 rules/routes.md
• 对于处理器提取、createFactory()、createHandlers() 或类型化上下文流，请阅读 rules/handlers.md
• 对于共享请求边界、身份验证／日志记录／请求 ID 流，或 c.set()／c.get() 的用法，请阅读 rules/middleware.md
• 对于 params／query／json／form 的验证选择，请阅读 rules/validation.md
• 对于数据库客户端、存储库、ORM 边界、Drizzle schema、迁移、事务、D1、Neon、Turso/libSQL 或 DATABASE_URL，请阅读 rules/database.md
• 对于 OpenAPI 生成、Swagger UI、操作元数据、schema 漂移、文档端点或 API 契约发布，请阅读 rules/openapi.md
• 对于 HTTPException、app.onError() 或响应格式问题，请阅读 rules/errors.md
• 对于 testClient()、hc<AppType>、AppType 或大型应用的类型推断，请阅读 rules/testing-rpc.md
• 对于适配器、入口点、绑定、环境／配置类型或 basePath() 边界，请阅读 rules/platform.md

官方默认行为覆盖模式

当用户明确要求使用官方 Hono 默认行为，而不是仅限 hypercore 的约定时：

• 首先从 references/official/hono-docs.md 开始
• 将官方 Hono 行为作为默认决策依据
• 将更严格的 hypercore 规则视为可选叠加规则，仅在用户未选择退出时强制执行
• 在问题发现和最终报告中，标明哪些规则属于官方 Hono 行为，哪些属于仅限 hypercore 的约定

</support_file_read_order>

步骤 3：更改前验证清单

编辑前，根据 architecture-rules.md 和相关主题规则文件验证计划中的更改。

棕地规则：

• 未触及的旧有风格偏差可列入待办事项。
• 安全性、类型、验证、持久化、OpenAPI 和运行时边界问题仍会阻止已触及的工作。
• 在 전체 수정 模式下，整个检测到的 Hono 应用都属于触及范围。

关键门槛：

• 使用一个与运行时无关的 Hono 应用和一张清晰的挂载表；选择有充分理由的最精简结构配置文件，并保持依赖方向。
• 已触及的路由模块不得绕过服务，直接导入 DB／ORM／schema／SDK／运行时适配器细节。
• 非简单的 params／query／json／form 数据必须在领域逻辑前经过验证器中间件。
• 提取出的处理器必须通过内联链式调用或 createFactory()／createHandlers() 保留类型信息。
• 使用共享上下文时，必须明确中间件顺序以及类型化的 Bindings／Variables。
• Drizzle schemas、迁移、客户端和事务必须处于数据库／服务边界之后。
• 公开且有文档记录的路由必须保持运行时验证、DTO、OpenAPI／Swagger 与 RPC 响应格式一致。
• 运行时适配器／引导代码必须位于平台边界。
• 源码文件夹／文件应使用 kebab-case，除非工具或外部契约另有要求。

如需查看问题发现和修复的详细信息，请使用链接支持文件中的详细清单；不要在此核心文件中重复这些内容。

步骤 3.5：自动修复策略

当问题局部、可逆且风险较低时，直接自动修复。

• 将涉及的 camelCase/PascalCase 源代码文件夹或文件重命名为 kebab-case，并更新导入和引用
• 为涉及的路由添加缺失的验证器中间件
• 当共享 RPC/客户端契约依赖 AppType 时，添加带类型的 AppType 导出
• 将路由挂载移至单一组合文件
• 将提取出的无类型处理程序转换为 createFactory() / factory.createHandlers()
• 添加 app.onError() 或改进 HTTP 异常转换
• 将运行时适配器导入移出处理程序和路由模块
• 将涉及的直接数据库调用移至现有服务/存储库
• 为涉及的查询添加缺失的存储库封装
• 将重复的数据库客户端导入集中到现有数据库客户端边界
• 当仓库已发布规范时，为涉及的公共路由添加缺失的 OpenAPI 元数据
• 将 Swagger UI 的暴露移至现有的文档/管理/开发环境边界内

没有明确理由时，不要自动应用范围过广或可能造成破坏的迁移。

• 批量重命名路由/模块；但在 전체 수정 模式下，仅限 kebab-case 重命名，且所有导入/引用/配置路径都能更新并验证
• 重写整个应用的分层结构
• 在整个仓库中替换验证库
• 破坏现有客户端的 RPC 结构变更
• 替换运行时适配器
• 替换数据库提供程序、ORM、方言或 Drizzle 驱动
• 生成、编辑、应用或删除生产环境迁移
• 重命名架构中的表/列/索引
• 在没有受影响工作流测试的情况下重写事务边界
• 在整个应用中切换 OpenAPI 生成器（@hono/zod-openapi 与 hono-openapi）

步骤 4：实施

更改 Hono 代码时，优先按以下顺序进行：

1. 验证当前结构和规则违规情况。在 전체 수정 模式下，编辑前先盘点检测到的整个 Hono 应用。
2. 在安全的情况下，先将文件夹/文件名称修正为 kebab-case，因为后续导入和测试依赖稳定路径。
3. 优先修正路由组合和类型边界。
4. 修正涉及持久化行为的数据库/存储库/连接边界；在 전체 수정 模式下则检查整个应用。
5. 修正验证和中间件顺序。
6. 修正涉及的公共路由的 OpenAPI/Swagger 契约偏差；在 전체 수정 模式下则检查所有已记录/公共路由。
7. 修正错误处理和响应构造。
8. 修正测试/RPC 推断回归问题。
9. 运行验证。

<validation_checklist>

验证清单

• 已确认 Hono 项目检测结果
• 已阅读相关规则文件
• 用户要求使用 Hono 官方默认设置时，已应用官方覆盖模式
• 涉及的文件和文件夹均遵循 kebab-case 命名
• 在 전체 수정 模式下，已扫描检测到的整个 Hono 源代码树，检查 kebab-case 违规情况
• 路由组合清晰且可挂载
• 项目配置、文件夹归属和依赖方向均有仓库证据支持
• 已验证中间件顺序
• 已对非简单输入实施验证
• 涉及的路由不会直接导入 DB/ORM 客户端、Drizzle 架构表或迁移辅助工具
• 数据库客户端生命周期已集中管理，并适用于相应运行时
• 架构和迁移路径与配置的 ORM/drizzle 设置一致
• 受影响的多步骤写入已明确使用事务
• 已更新涉及的、具有文档记录的路由的 OpenAPI/Swagger 文档
• Swagger UI 的暴露经过明确规划，且适用于相应环境
• 错误处理策略明确
• 适用时，testClient / hc / AppType 推断仍可正常工作
• API DTO、OpenAPI 架构和 RPC 响应结构不会意外暴露原始 ORM 行
• 运行时适配器代码留在边界层
• 最终发现的问题已区分 Hono 官方规则与仅适用于 hypercore 的约定

</validation_checklist>