1. 项目概述当AI智能体遇上你的软件架构最近在折腾AI编程助手Claude Code、Cursor、Copilot这些的朋友估计都遇到过类似的头疼事你让它写个用户注册的API它生成的代码语法上挑不出毛病但一瞅实现好家伙直接把数据库查询逻辑怼在了HTTP控制器里或者把业务规则散落在各个角落。你明明有一套精心设计的六边形架构Hexagonal或者清晰的分层规范但AI智能体对此一无所知它就像个技艺高超但不懂你公司文化的空降兵代码能跑但和现有系统格格不入引入了大量的“架构漂移”Architecture Drift。这正是verikt这个工具要解决的核心痛点。简单来说verikt是一个“架构即代码”的CLI工具它让你能用声明式的方式把你的软件架构模式、技术栈能力、团队规范一次性定义清楚。之后无论是通过命令行快速搭建新服务还是为AI编程助手生成精准的上下文Contextverikt都能确保产出的代码从一开始就符合你的架构蓝图把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 GoExpress、Fastify for TS。postgres/mysql集成数据库客户端及连接池配置。health生成就绪/存活健康检查端点。observability集成日志如Zap、Logrus、指标如Prometheus和分布式追踪如OpenTelemetry的初始化代码。docker生成优化的Dockerfile和.dockerignore。graceful-shutdown实现优雅关闭逻辑处理未完成的请求。实操命令深度解读项目简介中给出了两个例子交互式向导模式verikt new my-service这是对新用户最友好的方式。命令行会以问答形式引导你选择架构模式如 hexagonal, layered, flat。从能力矩阵中勾选所需能力平台类、通信类、数据存储类等。输入Go模块路径或NPM包名。 这个过程能让你直观地了解verikt的所有选项非常适合初次体验。非交互式模式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分支或任何目标分支的差异部分。这样做的优点是快速反馈只扫描改动的文件检查速度极快。精准拦截确保新的提交不会引入架构违规防止技术债务的滋生。教育作用当PR检查失败时给出的具体错误信息如“第XX行领域模型User不应直接导入gorm库”能即时教育开发者强化团队对架构的理解。3. 多语言支持与能力矩阵深度剖析verikt并非一个单语言玩具它对Go和TypeScript/Node.js提供了深度支持但支持的程度和哲学有所不同。3.1 Go语言支持全面且深入Go是verikt的“一等公民”支持最为成熟。架构模式支持4种主流模式。Layered (分层)经典的表现层、业务逻辑层、数据访问层。Hexagonal (六边形/端口与适配器)将核心业务逻辑与外部依赖数据库、UI、第三方服务解耦通过端口接口和适配器进行通信。这是目前云原生和领域驱动设计DDD中非常推崇的模式verikt对其支持也最完善。Clean Architecture与六边形架构思想同源更强调依赖规则依赖指向内部核心业务不依赖外部。Flat (扁平)适用于小型服务或脚本结构简单所有代码在一个或少数几个包内。能力矩阵63种能力分属10个类别。这是其强大之处。类别包括Platform基础运行时能力如配置管理、生命周期管理。Bootstrap应用启动引导。CommunicationHTTP API (Gin, Echo, Fiber)、gRPC、消息队列等。Data数据库Postgres, MySQL, SQLite、ORMGORM, sqlx、缓存Redis。Observability日志、指标、链路追踪。Resilience健康检查、优雅关闭、断路器。Security认证、授权、密钥管理。Testing单元测试、集成测试的脚手架。DeploymentDockerfile、Kubernetes manifests。Code Quality预提交钩子、lint配置。 你可以像搭积木一样通过--cap参数组合这些能力verikt会帮你处理好所有依赖注入和初始化顺序。3.2 TypeScript/Node.js支持灵活且实用对TS/Node.js的支持正在积极发展中目前聚焦于Web API场景。架构模式支持2种。Hexagonal端口与适配器模式适用于中大型后端应用。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项目如果部署在边缘环境或追求极致冷启动速度选HonoFlat。如果是传统的容器化部署且需要丰富的插件生态Fastify是一个性能与功能俱佳的平衡选择。Express则适用于团队熟悉度最高、无需额外学习成本的场景。4. 从零开始实战创建一个Go六边形架构微服务让我们通过一个完整的例子感受verikt的工作流。目标创建一个名为user-service的用户管理微服务采用六边形架构具备HTTP API、PostgreSQL数据库、UUID主键、健康检查、指标暴露和Docker支持。4.1 第一步安装与初始化首先通过Homebrew安装macOS/Linuxbrew install diktahq/tap/verikt安装完成后创建一个新目录并进入开始我们的项目创建。我们使用交互式向导这对初学者最友好verikt new user-service接下来CLI会启动一个交互式会话选择架构使用上下键选择hexagonal回车。选择能力这是一个多选界面。你会看到一个分类的能力列表。我们按空格键选中以下能力platform(基础平台)bootstrap(启动引导)http-api(HTTP API接下来会让我们选择框架比如gin)postgres(PostgreSQL数据库)uuid(UUID主键生成)health(健康检查)observability(可观测性包含日志和指标)docker(Dockerfile) 选中后回车继续。输入Go模块路径例如github.com/your-org/user-service。确认向导会显示你的所有选择确认无误后开始生成项目。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助手“添加一个根据邮箱查找用户的功能”时它会知道首先在internal/core/user.go中为User实体添加必要的字段和方法。在internal/core/中更新或创建UserRepository接口添加FindByEmail方法。在internal/app/user_service.go中实现这个用例逻辑。最后在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/veriktlatest 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 对现有项目进行改造步骤在现有项目根目录运行verikt analyze .了解当前结构。运行verikt init它会交互式地引导你根据现有代码选择最接近的架构模式和能力生成一个verikt.yml文件。注意这是一个“近似”配置需要你手动审核调整。使用verikt check .检查现有代码与目标架构的偏差。这可以作为重构的任务清单。逐步重构代码使其通过verikt check。这是一个渐进式的过程而非一蹴而就。5.6 关于许可证Elastic License 2.0verikt采用 Elastic License 2.0 (ELv2)。这是一个源码可用的许可证核心条款是你可以自由使用、修改和分发但不能将其作为托管服务提供给他人即不能将verikt本身作为SaaS服务的一部分对外运营。对于绝大多数公司内部使用、或集成到自己交付给客户的软件中ELv2 是允许的。在决定用于商业产品前建议法务团队进行最终审查。verikt的出现标志着一个趋势AI时代的软件工程工具正从“代码生成”向“上下文与约束管理”演进。它不再仅仅是替你写代码而是替你管理并传递那些让代码变得可维护、可协作的“非功能性知识”——架构。将verikt融入你的开发流程尤其是与AI编程助手深度结合相当于为你的团队聘请了一位永不疲倦的架构守护者确保在开发速度飙升的同时代码基底依然坚实、清晰。