前言

痛点一：“AI 写的代码不符合项目规范”——这是多数开发者在使用 AI 辅助编程时最常碰到的问题。

痛点二：项目规范分散在 README、Wiki、代码注释还有口头约定中，AI 无法获取完整上下文。

痛点三：生成的代码往往缺乏统一风格，需要大量手动调整才能投入生产。

根源并非 AI 能力不足，而是我们没有提供足够清晰、结构化的规范。传统项目的“规范”散落各处，AI 难以形成完整理解。

Clhoria 基于规范驱动开发理念建立，是公司级 Hono 后端模板。它把规范提高为项目的一等公民。使 AI 能深度理解并遵循这些规范，实现高效的人机协作开发。

什么是规范驱动开发

规范驱动开发改变原有方式开发层级关系——让规范主导，代码成为规范的实现。

在传统流程中。我们先写代码，再补文档，规范往往事后补充。而 SDD 的顺序是：先定义精确的规范，再基于规范生成代码。这种方式天然适配 AI 辅助开发，因为精确的规范可以直接转化为可工作的代码。

Clhoria 将 SDD 落地为六个标准阶段：

• 需求分析与技术架构设计
• 生成接口代码
• 生成测试用例
• 循环调整
• 验收通过
• 生成模块文档

每完成一个功能模块。会产出两份文档——spec.md 记录需求与架构决策，module.md 记录模块文件索引与技术要点，为后续 AI 维护提供完整上下文。

规范如何贯穿 Clhoria 的设计

代码结构即规范

Clhoria 对路由模块的文件结构有明确约定：每个功能模块必须包含 handlers。routes,index,types 四个必需文件，还有 schema、services、helpers 三个可选文件。

This is not an arbitrary directory layout;it is a deliberate specification. Handlers focus on pure business logic;怎么说呢，routes define OpenAPI。 turning code into documentation;types centralize data structures,making m instantly understandable to AI. When AI needs to add a feature。it knows exactly where to place each piece of code.

类型程序即规范

The stack uses Hono + Zod + TypeScript for end‑to‑end type inference. Zod schemas are split into two layers:

• 从 Drizzle 表定义生成基础 Schema。
• 继承 DB 层并组合成业务 Schema。

The DB layer holds field descriptions;说起来，route layer only trims or extends m. This clear separation tells AI precisely where to modify field metadata and where to compose business schemas—type constraints become enforceable specifications.

权限模型即规范

A common pitfall is storing permission identifiers in a database that can drift from code implementation. Clhoria flips this model: API route itself **is** permission identifier.

• The RESTful path combined with Casbin KeyMatch3 forms access policy .
• Add a new endpoint → no extra DB record needed;Casbin policies auto‑match via wildcards.
• If a route is removed,its permission disappears automatically—no orphan records.

The same principle applies to menus and dictionaries: menus are generated from Refine resources at compile time;dictionaries map TypeScript enums to PostgreSQL enums. A single source of truth guarantees full‑stack synchronization,and TypeScript compiler flags any missing updates.

为 AI 协作调整的开发体验

毫秒级热重载与资源管理

The Vite‑based dev environment traditionally leaks long‑lived resources on hot module replacement . Clhoria introduces a singleton manager that tracks se resources and automatically disposes of m when a module is unloaded.

A monitoring plugin exposes .getActiveResourcesInfo,capturing pre‑ and post‑HMR resource snapshots. A sliding‑window algorithm detects sustained growth and only alerts when thresholds are truly breached。eliminating false positives.

编译时性能调整

A frequent performance trap with Zod‑openapi: defining schemas inside request handlers causes re‑creation on every call. Clhoria ships a Vite plugin that lifts such inline schema definitions to top level during compilation,ensuring y are instantiated once per module—a transparent boost for high‑frequency endpoints.

自动路由发现

The Vite helper /index.ts,registers it via HMR,and code runs instantly. This dramatically lowers integration friction for AI‑generated modules.

公司级能力

• 与传统方案的差异

  The key difference lies in **活的规格** versus static templates:

  • Cloharia’s CLAUDE.md: 详细描述项目架构、编码约定、文件组织方式。AI 读取此文件后不是机械填充模板，而是基于对规格的深度理解生成符合风格的实现。
  • Schemaless updates: 当规格更新。AI 在后续生成时自然遵循新规，无需回溯修改旧代码。
  • Codeless documentation: OpenAPI + Zod 实现“代码即文档”，类型安全保证文档永但是期。
  • M秒级热更新: 传统方案需数秒重新启动器；老实说，Clhoria 的 HMR 在毫秒内完成，无缝切换。

  快速开始

  1. github.com/zhe-qi/clho…
  2. git clone https://github.com/zhe-qi/clho.git cd clho pnpm install cp .env.example .env pnpm dev 打开浏览器访问
  3. github.com/zhe-qi/refi…

  写在最终

  S​pecification‑Driven Development 并非新概念，但在 AI 时代它焕发了第二春。当规格足够精确且完整时AI 能从“勉强能用”跃升为“真正好用”。

  Cloharia 正是这一理念的落地实现。如果你正在探索 AI 辅助开发常用方法。或需要一个现代化公司级后端起点，请立即尝试并加入我们的社区交流。