Trabuco

 ████████╗██████╗  █████╗ ██████╗ ██╗   ██╗ ██████╗ ██████╗
 ╚══██╔══╝██╔══██╗██╔══██╗██╔══██╗██║   ██║██╔════╝██╔═══██╗
    ██║   ██████╔╝███████║██████╔╝██║   ██║██║     ██║   ██║
    ██║   ██╔══██╗██╔══██║██╔══██╗██║   ██║██║     ██║   ██║
    ██║   ██║  ██║██║  ██║██████╔╝╚██████╔╝╚██████╗╚██████╔╝
    ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝  ╚═════╝  ╚═════╝ ╚═════╝
  

生成可用于生产环境的 Java 项目，并内置编码 Agent 所需的 AI 上下文。

即使有编码 Agent 帮忙，启动一个新的 Java 项目也很慢。你要设置 Maven 模块、连接数据库和测试，从那个“基本能用”的项目里复制样板代码，然后还得花第一个小时，从头向 Claude Code、Cursor、Copilot 或 Codex 解释每条架构规范。几个小时过去了，你还没写下一行业务逻辑。Trabuco 的存在，就是为了让你和 Agent 的上下文窗口把时间花在构建功能上，而不是折腾配置或重新讲解规范。

Trabuco 是一款命令行工具，也是一个 Claude Code 插件，可生成现代 Java 代码库的两大组成部分：完整、可用于生产环境的多模块 Maven 项目，以及 教会编码 Agent 如何在其中工作的 AI 上下文。运行 trabuco init（或在 Claude Code 中输入 /trabuco:new-project，用日常语言描述需求），回答几个提示问题（也可传入标志以实现自动化），即可获得完整配置的 Spring Boot 代码库，以及已为 Claude Code、Codex、Cursor 和 GitHub Copilot 配置好的任务专属提示词、质量规范、各 Agent 的规则文件和工作流钩子。无需下载模板，无需手动设置，也无需花费一个会话来让 Agent 熟悉项目。

生成的代码默认达到生产级别。Spring Boot 搭配 Spring Data JDBC（不会遇到 JPA 的意外问题）、Flyway 迁移、用于真实集成测试的 Testcontainers、Resilience4j 断路器、由 Spotless 强制执行的 Google Java Format、在违反分层规则时令构建失败的 ArchUnit 规则、关联 ID 跟踪、Prometheus 指标、OpenAPI + Swagger UI，以及带有净化响应的全局异常处理器。PostgreSQL、MySQL、MongoDB 或 Redis——均已通过 Docker Compose 配置。后台任务使用 JobRunr；事件驱动处理可使用 Kafka、RabbitMQ、AWS SQS 或 GCP Pub/Sub。模块布局——Model、SQLDatastore / NoSQLDatastore、Shared、API、Worker、EventConsumer——具有清晰的编译时边界，因此 API 在物理上无法导入 Worker 代码。每项设计选择都有其用意：键集分页、不使用外键约束、在模块边界使用 Immutables、仅使用构造器注入、批量写入设定上限。

除了代码，Trabuco 还搭建了一层 AI 协作能力，可供主流编码 Agent 原生加载。.ai/prompts/ 目录包含任务专属指南（add-entity、add-endpoint、add-service、add-event、add-job、add-tool），以及 JAVA_CODE_QUALITY.md——一份权威规范，涵盖架构边界、异常处理、数据存储性能（批量 I/O、键集排空循环、反规范化）和测试标准。各 Agent 的规则文件——Claude Code 使用 CLAUDE.md，Codex 使用 AGENTS.md，Cursor 使用 .cursor/rules/java.mdc，Copilot 使用 .github/instructions/java.instructions.md——将这些规范接入各工具的原生发现机制。Claude 还会获得用于提交、PR 和审查工作流的 .claude/skills/；Codex 和 Cursor 会获得钩子；Copilot 会获得设置步骤。每条架构规范都有两种体现：由生成的代码强制执行，并向将要扩展代码的 Agent 解释清楚。 Trabuco 更进一步。AI Agent 模块基于 Spring AI 提供用于构建 AI Agent 本身的生产级脚手架：工具调用、LLM 输入/输出护栏、多 Agent 编排、知识库集成、MCP 服务端点、A2A（Agent-to-Agent）协议、流式响应、Webhook 回调、基于作用域的授权、速率限制和关联 ID 跟踪——从第一次提交起即可使用，接线完毕且可测试。Trabuco 本身也是 MCP 服务：运行 trabuco mcp，编码 Agent 即可原生调用脚手架操作（init_project、add_module、design_system、suggest_architecture）。

支持迁移现有 Spring Boot 项目：使用 trabuco migrate，通过 14 个阶段的编排迁移，将基于 Maven 的 Spring Boot 仓库原地转换为符合 Trabuco 结构的多模块项目。每个阶段由一位专门负责的专家执行，并提出结构化变更；你可在提交前于审核节点批准这些变更。每个阶段都会创建 Git 标签，以便原子回滚。请从 trabuco migrate assess /path/to/repo 开始。完整指南：docs/migration-guide.md。

安装

# Recommended: use via npx (no install needed)
claude mcp add trabuco -- npx -y trabuco-mcp

# Or install the CLI globally
npm install -g trabuco-mcp                                       # via npm
go install github.com/arianlopezc/Trabuco/cmd/trabuco@latest     # via Go
curl -sSL https://raw.githubusercontent.com/arianlopezc/Trabuco/main/scripts/install.sh | bash  # via shell

有关各 Agent 的 MCP 配置（Cursor、Copilot、Codex）、离线 tarball 和二进制文件备用方案，请参阅 docs/manual.md#installation。

快速开始

# Interactive — Trabuco asks what you need
trabuco init

# Or all flags
trabuco init --name=myapp --group-id=com.company.myapp \
  --modules=Model,SQLDatastore,Shared,API --database=postgresql

cd myapp
mvn clean install
cd API && mvn spring-boot:run

你的 API 运行在 http://localhost:8080。有关 Worker、EventConsumer、AIAgent 和 CI 示例，请参阅 docs/manual.md#quick-start。

Claude Code 插件

Trabuco 已发布到 Anthropic 的社区插件市场。在 Claude Code 中：

/plugin marketplace add anthropics/claude-plugins-community
/plugin install trabuco@claude-community

你也可以在 claude.com/plugins 浏览目录，或直接固定到此仓库（例如获取尚未发布的变更）：先运行 /plugin marketplace add arianlopezc/Trabuco，再运行 /plugin install trabuco@trabuco-marketplace。

该插件包含 8 个技能（/trabuco:new-project、/trabuco:design-system、/trabuco:add-module、/trabuco:extend、/trabuco:migrate、/trabuco:doctor、/trabuco:suggest、/trabuco:sync）、17 个专业子 Agent（架构师、AI Agent 专家、迁移编排器、14 位迁移阶段专家），以及一个包含 25 个工具的 MCP 服务。完整插件文档：plugin/README.md。

该插件要求 PATH 中存在 trabuco CLI——请先安装（也可以之后安装；SessionStart hook 会检测缺少的二进制文件，并告知助手具体操作）。

亮点

• 多模块 Maven — 在 Model、SQLDatastore/NoSQLDatastore、Shared、API、Worker、EventConsumer、AIAgent 之间建立清晰的编译时边界。
• Spring Boot + Java — 使用 Spring Data JDBC（不使用 JPA）、Flyway 迁移，默认启用虚拟线程，并使用 Testcontainers 进行真实集成测试。
• OIDC 资源服务器脚手架（为 API/AIAgent 自动生成） — Spring Security 双 SecurityFilterChain、JWT 验证、映射到 scope 的权限、RFC 7807 ProblemDetail 处理器，以及 RSA 签名的端到端测试。默认停用 — 设置 trabuco.auth.enabled=true 并配置 OIDC_ISSUER_URI，即可验证来自 Keycloak / Auth0 / Okta / Cognito / 通用 OIDC 的令牌。没有 CLI 标志，也不会生成半安装状态的项目。完整指南：docs/auth.md。
• 生产级可观测性 — RFC 7807 Problem Details、OpenTelemetry 自动插桩、Prometheus 指标、关联 ID、健康探针。
• AI Agent 模块 — Spring AI，支持工具、大模型防护栏、MCP 服务、A2A 协议、多 Agent 编排、知识库、Webhook。OIDC 链可与旧版 ApiKeyAuthFilter 共存（由独立属性控制），以便逐步迁移。
• AI 协作层 — .ai/prompts/ 任务指南、JAVA_CODE_QUALITY.md 规范，以及适用于 Claude Code / Codex / Cursor / GitHub Copilot 的各 Agent 规则文件。
• 迁移现有代码库 — trabuco migrate 运行包含 14 个阶段的编排流程，每个阶段均设有审批关卡，并支持原子回滚。
• 了解模块需求的 CI — --ci github 会生成包含模块所需确切 Docker 服务的工作流。
• 与新版本保持同步 — trabuco sync --apply 会增量添加较新 CLI 版本中新增的 AI 工具文件。

完整功能列表请参阅 docs/manual.md#features。

文档

• docs/manual.md — 完整的 CLI 参考（安装、模块、MCP 服务、代码质量、配置选项及所有标志）。
• docs/migration-guide.md — 迁移现有 Spring Boot 项目的指南。
• docs/README.md — 完整的文档索引，包含设计背景（理念、模式方案、适用与不适用场景、限制）。
• plugin/README.md — Claude Code 插件：技能、子 Agent、钩子、MCP 服务。

要求

• Java（Trabuco 会自动检测已安装的版本）
• Maven
• Docker（用于 Testcontainers 和本地开发）

贡献

欢迎提交问题和拉取请求。

许可证

MIT — 随你使用。

---

使用 Trabuco 构建。 现在，去打造一些令人惊叹的东西吧。