verikt：AI编程助手架构守护者，一键生成合规代码与架构治理

1. 项目概述：当AI智能体遇上你的软件架构

最近在折腾AI编程助手（Claude Code、Cursor、Copilot这些）的朋友，估计都遇到过类似的头疼事：你让它写个用户注册的API，它生成的代码语法上挑不出毛病，但一瞅实现，好家伙，直接把数据库查询逻辑怼在了HTTP控制器里，或者把业务规则散落在各个角落。你明明有一套精心设计的六边形架构（Hexagonal）或者清晰的分层规范，但AI智能体对此一无所知，它就像个技艺高超但不懂你公司文化的空降兵，代码能跑，但和现有系统格格不入，引入了大量的“架构漂移”（Architecture Drift）。

这正是verikt这个工具要解决的核心痛点。简单来说，verikt是一个“架构即代码”的CLI工具，它让你能用声明式的方式，把你的软件架构模式、技术栈能力、团队规范一次性定义清楚。之后，无论是通过命令行快速搭建新服务，还是为AI编程助手生成精准的上下文（Context），verikt都能确保产出的代码从一开始就符合你的架构蓝图，把AI从“语法正确但结构混乱的码农”，变成真正理解你团队工程实践的“资深同事”。

它的价值在于将架构知识从文档（甚至是从资深工程师的脑子里）沉淀为可执行、可复用的资产。对于快速启动新项目、维护大型单体或微服务架构的一致性、以及最大化AI编程助手的效能，都是一个强有力的提效杠杆。无论你是Go语言的重度使用者，还是TypeScript/Node.js生态的开发者，只要你的团队苦于架构不一致和AI生成的代码不合规，verikt都值得你花时间深入了解。

2. 核心设计理念与四大支柱解析

verikt的功能围绕四个核心支柱展开，这构成了它完整的工作流闭环：从定义、创建、分析到治理。理解这四大支柱，就掌握了verikt的全部精髓。

2.1 支柱一：引导（Guide）—— 为AI注入架构灵魂

verikt guide命令是连接你的架构定义与AI编程助手（如Claude Code、Cursor）的桥梁。它的产出不是代码，而是一份高度结构化的“架构上下文指南”。

它解决了什么问题？当你打开AI编程助手的聊天窗口，通常需要手动输入一长串提示词，比如“我们项目采用六边形架构，领域模型在internal/core，用例在internal/app，适配器在internal/adapter…”。这种方式低效、易错、且难以维护。verikt guide自动化了这个过程。它会读取你项目根目录下的verikt.yml配置文件（或你指定的架构定义），生成一份包含以下内容的指南：

• 架构模式说明：清晰解释你所采用的架构（如分层、六边形、Clean Architecture）及其各层职责。
• 目录结构规范：明确每个目录应该放什么，禁止放什么。
• 能力（Capabilities）约束：例如，如果定义了使用gorm作为ORM，那么指南会说明数据库操作应放在基础设施层的仓库（Repository）中，并给出代码示例。
• 代码风格与模式：依赖注入应该怎么做，错误如何处理，日志怎么打。

如何使用？在配置好verikt.yml的项目根目录下，直接运行：

verikt guide

命令会输出一个格式优美的Markdown文档。你可以将这个文档的内容保存为AI助手的自定义指令（Custom Instructions），或者在进行复杂任务前，直接粘贴到聊天窗口。这样一来，AI助手在生成代码、回答问题时，就有了明确的“行动纲领”，大幅减少修正成本。

2.2 支柱二：组合（Compose）—— 一键生成合规服务骨架

verikt new <service-name>这是最常用、最体现生产力的命令。它根据你定义的架构和能力，快速脚手架（Scaffold）出一个完整的、生产就绪的服务初始代码库。

背后的设计逻辑：传统的go mod init或npm init只创建一个空壳。而verikt new创建的是一个“五脏俱全”的迷你应用。它基于“能力”（Capabilities）的概念进行组合。能力是模块化的功能单元，例如：

• http-api：提供HTTP服务器框架（如Gin、Echo for Go；Express、Fastify for TS）。
• postgres/mysql：集成数据库客户端及连接池配置。
• health：生成就绪/存活健康检查端点。
• observability：集成日志（如Zap、Logrus）、指标（如Prometheus）和分布式追踪（如OpenTelemetry）的初始化代码。
• docker：生成优化的Dockerfile和.dockerignore。
• graceful-shutdown：实现优雅关闭逻辑，处理未完成的请求。

实操命令深度解读：项目简介中给出了两个例子：

1. 交互式向导模式：verikt new my-service这是对新用户最友好的方式。命令行会以问答形式引导你：

   • 选择架构模式（如 hexagonal, layered, flat）。
   • 从能力矩阵中勾选所需能力（平台类、通信类、数据存储类等）。
   • 输入Go模块路径或NPM包名。 这个过程能让你直观地了解verikt的所有选项，非常适合初次体验。

2. 非交互式模式：verikt new my-api --arch hexagonal --cap platform,bootstrap,http-api,postgres,uuid,health,docker --module github.com/myorg/my-api --no-wizard这是为自动化、脚本化场景设计的。所有参数通过命令行标志指定，非常适合集成到内部工具链或CI/CD流程中。参数解析：

   • --arch hexagonal：指定使用六边形架构。
   • --cap platform,bootstrap,...：这是一个能力列表，用逗号分隔。它定义了新服务将具备的所有功能。
   • --module：设置Go模块名，这对于Go项目的依赖管理至关重要。
   • --no-wizard：明确禁用交互式向导，直接执行。

生成物是什么？运行后，你会得到一个名为my-api的目录，里面已经包含了：

• 符合指定架构的完整目录结构（如cmd/,internal/core/,internal/app/,internal/adapter/）。
• 所有选中能力的初始化代码和配置已经正确放置在了对应的架构层中。例如，数据库仓库接口在领域层定义，具体实现在基础设施层；HTTP路由在接口适配器层，并调用了应用层的用例服务。
• go.mod/package.json文件已初始化，并引入了必要的依赖。
• 一个基础的main.go或index.ts，其中依赖注入、服务器启动、优雅关闭、健康检查路由等样板代码已经全部串联好。 这意味着，你生成的服务不是一堆散落的零件，而是一辆已经组装好、加满油、钥匙插上的车，你只需要专注实现业务逻辑即可。

2.3 支柱三：分析（Analyze）—— 透视现有代码的架构健康度

verikt analyze [path]命令用于“诊断”现有项目。它能扫描代码库，识别出实际使用的架构模式，并与verikt支持的模式进行比对。

使用场景与价值：

• 接手遗留项目：快速理解一个陌生代码库的大致结构。
• 审计架构一致性：检查团队实际编码是否偏离了既定的架构设计文档。
• 为迁移做准备：如果你计划将一个老旧项目重构为新的架构，analyze可以给出当前状态的基线报告。

输出示例：运行verikt analyze ./my-old-service，它可能会输出：

Analyzing ./my-old-service... Detected patterns: - Layered Architecture (Medium confidence): Found clear separation of `controllers/`, `services/`, `models/`, `repositories/`. - Potential Anemic Domain Model (Weak confidence): Business logic appears concentrated in service classes. No verikt.yml configuration found. To enforce this pattern, run `verikt init`.

这个报告能让你快速抓住代码库的结构特点和质量线索。

2.4 支柱四：强制（Enforce）—— 守护架构规范的守门员

verikt check [path]命令是架构的“守门员”。它根据verikt.yml中定义的规则，对代码进行静态检查，确保没有违反架构约定的“反模式”（Anti-patterns）。

核心特性：11种反模式检测器这是verikt的硬核功能。它内置了11种常见的架构坏味道检测器，例如：

• 层间引用违规：比如基础设施层的代码直接引用了领域层的内部结构（本应通过接口）。
• 循环依赖：在模块或包之间检测循环导入。
• 上帝对象：识别过于庞大、职责过多的类或结构体。
• 基础设施逻辑泄露：业务逻辑中直接包含了SQL语句或HTTP客户端细节。

集成到CI/CD：这是enforce支柱最具威力的用法。你可以在拉取请求（PR）的CI流水线中加入如下命令：

verikt check . --diff origin/main

--diff参数是关键。它让verikt只检查当前分支与main分支（或任何目标分支）的差异部分。这样做的优点是：

1. 快速反馈：只扫描改动的文件，检查速度极快。
2. 精准拦截：确保新的提交不会引入架构违规，防止技术债务的滋生。
3. 教育作用：当PR检查失败时，给出的具体错误信息（如“第XX行：领域模型User不应直接导入gorm库”）能即时教育开发者，强化团队对架构的理解。

3. 多语言支持与能力矩阵深度剖析

verikt并非一个单语言玩具，它对Go和TypeScript/Node.js提供了深度支持，但支持的程度和哲学有所不同。

3.1 Go语言支持：全面且深入

Go是verikt的“一等公民”，支持最为成熟。

• 架构模式：支持4种主流模式。
  1. Layered (分层)：经典的表现层、业务逻辑层、数据访问层。
  2. Hexagonal (六边形/端口与适配器)：将核心业务逻辑与外部依赖（数据库、UI、第三方服务）解耦，通过端口（接口）和适配器进行通信。这是目前云原生和领域驱动设计（DDD）中非常推崇的模式，verikt对其支持也最完善。
  3. Clean Architecture：与六边形架构思想同源，更强调依赖规则（依赖指向内部，核心业务不依赖外部）。
  4. Flat (扁平)：适用于小型服务或脚本，结构简单，所有代码在一个或少数几个包内。
• 能力矩阵：63种能力，分属10个类别。这是其强大之处。类别包括：
  • Platform：基础运行时能力，如配置管理、生命周期管理。
  • Bootstrap：应用启动引导。
  • Communication：HTTP API (Gin, Echo, Fiber)、gRPC、消息队列等。
  • Data：数据库（Postgres, MySQL, SQLite）、ORM（GORM, sqlx）、缓存（Redis）。
  • Observability：日志、指标、链路追踪。
  • Resilience：健康检查、优雅关闭、断路器。
  • Security：认证、授权、密钥管理。
  • Testing：单元测试、集成测试的脚手架。
  • Deployment：Dockerfile、Kubernetes manifests。
  • Code Quality：预提交钩子、lint配置。 你可以像搭积木一样，通过--cap参数组合这些能力，verikt会帮你处理好所有依赖注入和初始化顺序。

3.2 TypeScript/Node.js支持：灵活且实用

对TS/Node.js的支持正在积极发展中，目前聚焦于Web API场景。

• 架构模式：支持2种。
  1. Hexagonal：端口与适配器模式，适用于中大型后端应用。
  2. Flat：适用于Serverless Function、轻量级API或快速原型。
• HTTP框架选择：这是一个亮点。verikt不绑定某个特定框架，而是让你在创建项目时选择：
  • Express：最流行、生态最广。
  • Fastify：高性能、低开销，自带验证和序列化。
  • Hono：超轻量级，为边缘计算（如Cloudflare Workers）优化。 选择后，verikt会生成对应框架的样板代码、路由结构和中间件配置。
• 能力：目前提供39种能力，覆盖了数据库（Prisma, TypeORM, Drizzle）、API文档（Swagger/OpenAPI）、测试（Jest）、容器化等核心后端需求。

实操心得：框架与能力的选择对于新项目，我个人的建议是：

• Go项目：如果团队追求清晰的结构和长期维护性，首选Hexagonal架构。它能有效隔离变化，让核心业务逻辑保持纯净。能力选择上，platform,bootstrap,http-api,health,observability几乎是必选，它们构成了现代微服务的基石。
• TS/Node.js项目：如果部署在边缘环境或追求极致冷启动速度，选Hono+Flat。如果是传统的容器化部署，且需要丰富的插件生态，Fastify是一个性能与功能俱佳的平衡选择。Express则适用于团队熟悉度最高、无需额外学习成本的场景。

4. 从零开始实战：创建一个Go六边形架构微服务

让我们通过一个完整的例子，感受verikt的工作流。目标：创建一个名为user-service的用户管理微服务，采用六边形架构，具备HTTP API、PostgreSQL数据库、UUID主键、健康检查、指标暴露和Docker支持。

4.1 第一步：安装与初始化

首先，通过Homebrew安装（macOS/Linux）：

brew install diktahq/tap/verikt

安装完成后，创建一个新目录并进入，开始我们的项目创建。我们使用交互式向导，这对初学者最友好：

verikt new user-service

接下来，CLI会启动一个交互式会话：

1. 选择架构：使用上下键选择hexagonal，回车。
2. 选择能力：这是一个多选界面。你会看到一个分类的能力列表。我们按空格键选中以下能力：
   • platform(基础平台)
   • bootstrap(启动引导)
   • http-api(HTTP API，接下来会让我们选择框架，比如gin)
   • postgres(PostgreSQL数据库)
   • uuid(UUID主键生成)
   • health(健康检查)
   • observability(可观测性，包含日志和指标)
   • docker(Dockerfile) 选中后回车继续。
3. 输入Go模块路径：例如github.com/your-org/user-service。
4. 确认：向导会显示你的所有选择，确认无误后，开始生成项目。

4.2 第二步：解读生成的项目结构

生成完成后，进入user-service目录，你会看到如下结构（简化版）：

user-service/ ├── cmd/ │ └── server/ │ └── main.go # 应用入口，依赖注入和服务器启动逻辑已完备 ├── internal/ │ ├── core/ # 领域层（核心业务逻辑和实体） │ │ └── user.go # User领域实体（纯结构体+方法） │ ├── app/ # 应用层（用例/服务层） │ │ └── user_service.go # UserService，实现业务用例，依赖core中的接口 │ └── adapter/ # 适配器层（接口实现和外部交互） │ ├── http/ # HTTP适配器（如Gin handler） │ │ └── user_handler.go │ ├── repository/ # 数据持久化适配器 │ │ └── postgres/ │ │ └── user_repo.go # 实现core层定义的Repository接口 │ └── config/ # 配置读取适配器 ├── pkg/ # 可公开的库代码（可选） ├── go.mod # Go模块定义，依赖已添加 ├── Dockerfile # 多阶段构建的优化Dockerfile ├── .dockerignore └── verikt.yml # 项目的架构定义文件

关键点解读：

• main.go文件已经非常丰满：它读取配置、初始化日志器和指标收集器、创建数据库连接池、实例化所有仓库和服务、注册HTTP路由、并设置了优雅关闭钩子。你几乎不需要修改这个文件。
• internal/core/user.go里定义的是纯粹的领域模型，不导入任何外部库（如gorm、json）。它可能包含像Validate()、ChangeEmail()这样的业务方法。
• internal/adapter/repository/postgres/user_repo.go实现了core中定义的UserRepository接口。这里才引入gorm库，进行具体的数据库操作。这完美体现了依赖倒置原则。
• verikt.yml文件是这个项目的“宪法”，记录了所选的架构和能力。未来运行verikt guide或verikt check都基于此文件。

4.3 第三步：生成AI助手指南并开发

现在，让我们为AI助手生成上下文指南：

verikt guide > ARCHITECTURE_GUIDE.md

打开ARCHITECTURE_GUIDE.md，你会得到一份详细的开发指南。将其内容复制到你的Claude Code或Cursor的“自定义指令”中。之后，当你让AI助手“添加一个根据邮箱查找用户的功能”时，它会知道：

1. 首先在internal/core/user.go中为User实体添加必要的字段和方法。
2. 在internal/core/中更新或创建UserRepository接口，添加FindByEmail方法。
3. 在internal/app/user_service.go中实现这个用例逻辑。
4. 最后在internal/adapter/repository/postgres/user_repo.go中实现接口的FindByEmail方法。 AI生成的代码会直接放在正确的层级，大大减少了后续调整的工作量。

4.4 第四步：在CI中实施架构守护

项目根目录下已经生成了.github/workflows/verikt-check.yml示例（如果选择了相关能力）。你可以将其集成到你的GitHub Actions中。其核心步骤就是：

- name: Enforce Architecture run: | go install github.com/diktahq/verikt@latest verikt check . --diff ${{ github.base_ref }}

这样，每次提PR时，verikt都会自动检查改动代码是否符合六边形架构规范，比如是否在core层引入了数据库依赖，从而在源头保障代码质量。

5. 常见问题、排查技巧与进阶思考

5.1 安装与初始化问题

• 问题：通过安装脚本安装后，运行verikt提示“command not found”。
• 排查：安装脚本通常会将二进制文件放入~/.verikt/bin，并提示你将其加入PATH。检查你的 shell 配置文件（如~/.bashrc,~/.zshrc）是否添加了类似export PATH=$PATH:~/.verikt/bin的行，并执行source命令或重启终端。
• 建议：使用Homebrew安装管理最方便，无需手动处理PATH。

5.2 能力依赖冲突

• 问题：创建项目时，选择了postgres和sqlite两个数据库能力，生成代码出现混乱。
• 技巧：verikt的某些能力是互斥或需要特定配置的。虽然CLI可能不会严格阻止，但最佳实践是一个服务主要使用一种数据库。仔细阅读verikt.dev上的能力矩阵文档，了解能力之间的兼容性。对于数据存储，通常只需选择一个。

5.3 生成的代码需要大量修改？

• 认知调整：verikt生成的不是最终业务代码，而是符合架构的生产级脚手架。它的价值在于建立了正确的分层、依赖关系和基础设施集成。你需要填充的是核心的业务实体（core/）和具体的业务逻辑（app/）。这恰恰是AI助手擅长、而脚手架工具难以通用的部分。不要期望它生成具体的业务CRUD，那是你和AI助手在既定框架下要完成的工作。

5.4 如何管理团队内的verikt.yml？

• 方案：将verikt.yml视为重要的项目资产，纳入版本控制。对于大型组织，可以考虑创建一个内部的“架构模板”仓库，里面存放针对不同业务场景（如“标准REST API微服务”、“事件驱动处理器”）预定义的verikt.yml文件。新项目可以直接复制并使用，确保全公司架构风格的统一。

5.5 对现有项目进行改造

• 步骤：
  1. 在现有项目根目录运行verikt analyze .，了解当前结构。
  2. 运行verikt init，它会交互式地引导你根据现有代码选择最接近的架构模式和能力，生成一个verikt.yml文件。注意：这是一个“近似”配置，需要你手动审核调整。
  3. 使用verikt check .检查现有代码与目标架构的偏差。这可以作为重构的任务清单。
  4. 逐步重构代码，使其通过verikt check。这是一个渐进式的过程，而非一蹴而就。

5.6 关于许可证（Elastic License 2.0）

verikt采用 Elastic License 2.0 (ELv2)。这是一个源码可用的许可证，核心条款是：你可以自由使用、修改和分发，但不能将其作为托管服务提供给他人（即不能将verikt本身作为SaaS服务的一部分对外运营）。对于绝大多数公司内部使用、或集成到自己交付给客户的软件中，ELv2 是允许的。在决定用于商业产品前，建议法务团队进行最终审查。

verikt的出现，标志着一个趋势：AI时代的软件工程工具，正从“代码生成”向“上下文与约束管理”演进。它不再仅仅是替你写代码，而是替你管理并传递那些让代码变得可维护、可协作的“非功能性知识”——架构。将verikt融入你的开发流程，尤其是与AI编程助手深度结合，相当于为你的团队聘请了一位永不疲倦的架构守护者，确保在开发速度飙升的同时，代码基底依然坚实、清晰。