hono-architecture（荣誉建筑）

Hono Architecture Enforcement

Overview

Enforces hypercore Hono architecture rules before code changes. Validate that the target is actually a Hono project, then apply strict rules for route composition, handlers, middleware, validation, error handling, platform entrypoints, and typed testing/RPC.

This skill is strict. Follow the rules exactly unless the user explicitly asks to prefer official Hono defaults over hypercore-specific conventions.

OPERATING MODE: This skill is self-contained. Do not block on global skills or external orchestration surfaces. If the user asks for exhaustive verification, keep verifying. Otherwise proceed directly with this skill's own validation flow.

IMPORTANT: Some rules in this skill are stricter than Hono itself. Treat those as hypercore conventions and label them clearly when reporting violations.

Trigger Examples

Positive

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

Negative

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

Boundary

• Make a tiny copy-only response text change in a Hono handler. Direct editing can be enough if no architectural boundary is affected.
• Use official Hono defaults only, not the extra hypercore conventions. This skill still applies, but relax hypercore-only strictness that exceeds the official docs.

Step 1: Project Validation

Before doing any work, confirm the target is a Hono project:

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

If none of those indicators exist, stop and route back to the normal implementation or review path instead of forcing Hono rules.

Step 2: Read Architecture Rules

Read the detailed rules before editing:

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

When the change depends on current framework behavior or you need to justify a rule from the official docs, read:

• references/official/hono-docs.md

Task-to-Rule Routing

Use the next file based on the change you are making:

• For route composition, mount order, fallback placement, or sub-app structure, read rules/routes.md
• For handler extraction, createFactory(), createHandlers(), or typed context flow, read rules/handlers.md
• For shared request boundaries, auth/logging/request-id flow, or c.set() / c.get() usage, read rules/middleware.md
• For params/query/json/form validation choices, read rules/validation.md
• For HTTPException, app.onError(), or response-shaping problems, read rules/errors.md
• For testClient(), hc<typeof app>, AppType, or larger-app inference, read rules/testing-rpc.md
• For adapters, entrypoints, bindings, env/config typing, or basePath() boundaries, read rules/platform.md

Official-Defaults Override Mode

When the user explicitly asks for official Hono defaults instead of hypercore-only conventions:

• Start from references/official/hono-docs.md first
• Apply official Hono behavior as the default decision surface
• Treat stricter hypercore rules as optional overlays and only enforce them when the user did not opt out
• In findings and final reports, label which rules are official Hono behavior and which are hypercore-only conventions

Step 3: Pre-Change Validation Checklist

Validate planned changes against these gates.

Brownfield Adoption Rule

• Do not treat every legacy deviation as a project-wide failure.
• Safety, typing, and validation issues still block immediately, especially in touched files.
• Hypercore-specific structure drift in untouched legacy code can be recorded as migration backlog.
• Any file you touch should be brought into compliance unless that would require a materially risky migration.

Gate 1: Composition and Layers

Gate 2: Route Modules

Gate 3: Handlers and Context Typing

Gate 4: Validation

Gate 5: Middleware

Gate 6: Errors and Responses

Gate 7: Testing and RPC

Gate 8: Platform Entry

Step 3.5: Auto-Remediation Policy

Auto-fix directly when the issue is local, reversible, and low-risk.

• Add missing validator middleware to a touched route
• Add typed AppType export
• Move route mounting into a single composition file
• Convert extracted untyped handlers to createFactory() / factory.createHandlers()
• Add app.onError() or improve HTTP exception translation
• Move runtime adapter imports out of handlers and route modules

Do not auto-apply broad or potentially breaking migrations without explicit justification.

• Mass route/module renames
• Whole-app layer rewrites
• Validation library swaps across the entire repository
• RPC shape changes that break existing clients
• Runtime adapter swaps

Step 4: Implementation

When changing Hono code, prefer this order:

1. Validate current structure and rule breaches.
2. Fix route composition and typing boundaries first.
3. Fix validation and middleware ordering.
4. Fix error handling and response shaping.
5. Fix testing/RPC inference regressions.
6. Run verification.

Verification Checklist

• Hono project detection confirmed
• Relevant rule files read
• Official override mode applied when the user requested official Hono defaults
• Touched files follow kebab-case naming
• Route composition is obvious and mountable
• Middleware order verified
• Validation enforced on non-trivial inputs
• Error handling policy is explicit
• testClient / hc / AppType inference still works when applicable
• Runtime adapter code stays at the edge
• Final findings distinguish official Hono rules from hypercore-only conventions