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 の規約より優先されます。安全性、型付け、バリデーション、データ境界のルールに反する変更は認められません。
根拠	プロジェクトを示す情報、ローカルのパッケージ／ソースファイル、対象パス、トピック別ルール、仕様の乖離が重要な場合は公式リファレンス、検証コマンドの出力を使用します。
ツール	ローカルの検索／読み取り／編集／検証コマンドを使用します。マイグレーション、認証情報へのアクセス、本番環境への副作用、ランタイムアダプターの切り替え、大規模な書き換えにはゲートを設けます。
ループ	最適化ループは使用しません。修正パス後の検証・修正の反復は、Step 3 のゲートと対象範囲のチェックに対して最大 2 回までとします。変更は対象範囲内にとどまり、ゲートを通過した場合にのみ維持します。検証チェックリストに合格するか、ブロッカーを報告した時点で停止します。
出力	ルールの分類、変更したファイル（該当する場合）、検証の根拠、残るリスク、公式ルールと 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>

Step 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 .

Step 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を参照してください
• パラメーター／クエリ／JSON／フォームのバリデーション方法については、rules/validation.mdを参照してください
• データベースクライアント、リポジトリ、ORM の境界、Drizzle スキーマ、マイグレーション、トランザクション、D1、Neon、Turso/libSQL、またはDATABASE_URLについては、rules/database.mdを参照してください
• OpenAPI の生成、Swagger UI、操作メタデータ、スキーマの不整合、ドキュメント用エンドポイント、または API コントラクトの公開については、rules/openapi.mdを参照してください
• HTTPException、app.onError()、またはレスポンス整形の問題については、rules/errors.mdを参照してください
• testClient()、hc<AppType>、AppType、または大規模アプリでの型推論については、rules/testing-rpc.mdを参照してください
• アダプター、エントリーポイント、バインディング、環境／設定の型付け、またはbasePath()の境界については、rules/platform.mdを参照してください

公式デフォルトの優先モード

ユーザーが hypercore 限定の規約ではなく、公式 Hono のデフォルトを明示的に求めた場合：

• まずreferences/official/hono-docs.mdを参照してください
• 公式 Hono の動作をデフォルトの判断基準として適用してください
• より厳格な hypercore ルールは任意の追加ルールとして扱い、ユーザーがオプトアウトしていない場合にのみ適用してください
• 指摘事項と最終レポートでは、公式 Hono の動作と hypercore 限定の規約を区別して示してください

</support_file_read_order>

ステップ 3：変更前の検証チェックリスト

編集前に、予定している変更をarchitecture-rules.mdおよび関連トピックのルールファイルに照らして検証してください。

既存コードベースに関するルール：

• 変更しないレガシーなスタイルの不統一は、バックログに回せます。
• 安全性、型付け、バリデーション、永続化、OpenAPI、ランタイム境界に関する問題は、変更対象の作業を妨げます。
• 全体修正モードでは、検出された Hono アプリ全体を変更対象の範囲とします。

重要なチェック項目：

• ランタイムに依存しない Hono アプリを 1 つ設け、明確なマウントテーブルを 1 つ用意してください。根拠のある最小の構造プロファイルを選択し、依存関係の方向性を維持してください。
• 変更対象のルートモジュールからサービスを迂回して、DB／ORM／スキーマ／SDK／ランタイムアダプターの詳細を直接インポートしないでください。
• 複雑なパラメーター／クエリ／JSON／フォームデータには、ドメインロジックの前にバリデーターのミドルウェアを使用してください。
• 切り出したハンドラーの型付けは、インラインチェーンまたはcreateFactory()／createHandlers()を使って維持してください。
• 共有コンテキストを使用する場合は、ミドルウェアの順序と型付きBindings／Variablesを明示してください。
• Drizzle スキーマ、マイグレーション、クライアント、トランザクションは、データベース／サービスの境界内に保持してください。
• 公開されているドキュメント化済みルートでは、ランタイムバリデーション、DTO、OpenAPI／Swagger、RPC のレスポンス形式の整合性を保ってください。
• ランタイムアダプター／ブートストラップコードは、プラットフォームの境界に配置してください。
• ツールまたは外部コントラクトで別の形式が必要な場合を除き、ソースのフォルダー／ファイル名には kebab-case を使用してください。

指摘事項と修正の詳細については、リンク先のサポートファイルにある詳細なチェックリストを使用してください。このコアファイルに重複して記載しないでください。

ステップ 3.5：自動修正ポリシー

問題がローカルに限定され、元に戻すことができ、リスクが低い場合は、直接自動修正します。

• 変更対象の camelCase／PascalCase のソースフォルダーまたはファイルを kebab-case に変更し、インポートや参照を更新する
• 変更対象のルートに不足しているバリデーターミドルウェアを追加する
• 共有 RPC／クライアントコントラクトが依存している場合、型付きの AppType エクスポートを追加する
• ルートのマウント処理を単一の構成ファイルに移動する
• 抽出された型なしハンドラーを createFactory() ／ factory.createHandlers() に変換する
• app.onError() を追加するか、HTTP 例外の変換を改善する
• ランタイムアダプターのインポートをハンドラーやルートモジュールの外に移動する
• 変更対象のデータベース直接呼び出しを既存のサービス／リポジトリーに移動する
• 変更対象のクエリに不足しているリポジトリーラッパーを追加する
• 繰り返し使われているデータベースクライアントのインポートを、既存のデータベースクライアント境界に集約する
• リポジトリーが既に仕様を公開している場合、変更対象の公開ルートに不足している OpenAPI メタデータを追加する
• Swagger UI の公開を既存の docs/admin/dev 境界の内側に移動する

明示的な根拠がない限り、広範囲に及ぶ変更や、破壊的変更の可能性がある移行を自動適用しないでください。

• 大規模なルート／モジュール名の変更。ただし、전체 수정 モードで、すべてのインポート／参照／設定パスを更新して検証できる場合の 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>