Rundeck 仓库的 AI Agent 协作规范：构建验证、代码标准与产物归档的完整工作流-北京尧图网络

运维任务调度后端【免费下载链接】rundeckEnable Self-Service Operations: Give specific users access to your existing tools, services, and scripts项目地址https://gitcode.com/gh_mirrors/ru/rundeck点击查看免费下载本文档讲解 Rundeck当前仓库中为 AI Agent 协作而设计的工程约定覆盖「完成前必须本地构建验证」「回复前双重检查代码标准」「提交必须经用户确认」三大行为模式以及 plans / reports / tmp / handoff 四类中间产物的归档路径与命名规范。读完本文你可以掌握如何在 Rundeck 仓库中规范、可验证地完成一次 Agent 驱动的代码改动并了解这些约定与仓库内 Gradle 构建体系、CodeNarc 复杂度检查、Spotless 格式化配置之间的实际对应关系。一、约定文档的定位Agent 如何在该仓库中工作.claude/docs/agent-conventions.md是整个 Rundeck 仓库 AI 配置体系详见 .claude/README.md中定义「代理行为模式」的核心文档。它从行为层面约束 Agent而不是像 CLAUDE.md 那样充当每轮会话启动时加载的索引手册也不是像.claude/rules/*.md那样按文件类型自动加载的强制规则。该文档锚定了三个层面的约定行为模式Behavior Patterns任务完成的判定标准产物管理Saving ArtifactsAgent 工作过程中生成的文件应该放哪里、如何命名验证义务Verification构建命令、耗时预期与 CI 职责边界。二、完成前必须构建验证./gradlew build -x check约定文档的第一条铁律是NEVERconsider a task complete without running verification —— 不运行验证绝不认为任务已完成。具体验证命令为./gradlew build -x check该命令的语义与 .claude/docs/build-commands.md 中的 Build Verification 章节一致是编译代码并构建产物但不运行测试套件与代码质量检查。具体跳过的是完整测试套件./gradlew test其耗时可能超过 1 小时代码质量检查SpotlessspotlessCheck、CodeNarccodenarcComplexity等。而完整测试由 CI 负责运行Agent 不需要在本地等待数小时。仓库文档给出的耗时预期是build -x check典型耗时4–8 分钟全量测试套件1 小时以上。这意味着 Agent 需要在「本地快速验证可编译、可构建」与「CI 承担深度验证」之间做出明确分工。2.1 构建验证之外的常用命令速查.claude/docs/build-commands.md 提供了与验证约定配套的完整命令集可供 Agent 和开发者共同使用用途命令完整构建含测试与质量检查./gradlew build构建但不跑测试./gradlew build -x test快速构建验证推荐给 Agent./gradlew build -x check开发模式运行./gradlew bootRun清理构建产物./gradlew clean检查代码格式./gradlew spotlessCheck自动修复代码格式./gradlew spotlessApply运行后端全部测试./gradlew test运行单个测试类./gradlew test --tests com.example.MySpec运行指定模块测试./gradlew :rundeckapp:testAPI 功能测试./gradlew :functional-test:apiTestSelenium 端到端测试./gradlew :functional-test:seleniumTest其中:functional-test:apiTest与:functional-test:seleniumTest对应仓库中独立的functional-test/模块该目录下存放着 238 个 Groovy 测试源文件functional-test/src/test/groovy/org/是 Rundeck 面向 API 与 UI 的端到端验证主战场。2.2 常见环境问题与处理.claude/docs/build-commands.md 的 Troubleshooting 章节给出了两个 Agent 在本地验证时最可能遇到的环境问题问题一构建报 Cannot find Java 17。此时需要显式指定 JDK 17 作为JAVA_HOMEexport JAVA_HOME$(/usr/libexec/java_home -v 17) ./gradlew build -x check问题二前端构建失败对应rundeckapp/grails-spa/packages/ui-trellis的 Vue/TS 工程。处理方式是清理依赖后重装rm -rf node_modules package-lock.json npm install问题三Gradle Daemon 异常。停止守护进程并清理缓存./gradlew --stop rm -rf ~/.gradle/caches三、双重检查代码标准格式化、静态编译与复杂度约定的第二条行为模式是Double-Check Code Standards—— 在给出任何回复之前先验证改动符合项目标准若不匹配则重新开始并修复。所谓「项目标准」在仓库中有明确的可执行载体3.1 格式化标准Spotless Ratchet 渐进式强制.claude/docs/code-formatting.md 说明 Rundeck 使用 Spotless 作为代码格式化工具其配置采用ratchet棘轮模式只对origin/main之后被修改的文件强制执行格式化避免一次全量格式化冲击历史代码。对于少数需要保留原样的代码块可用// spotless:off/// spotless:on显式排除。Agent 的标准动作是写完代码后运行./gradlew spotlessCheck检查若失败运行./gradlew spotlessApply自动修复提交格式化后的代码。3.2 Groovy 编译模式CompileStatic与GrailsCompileStatic.claude/docs/development-guidelines.md 与 CLAUDE.md 共同规定所有 Groovy 类必须使用CompileStaticGrails 组件Controller、Service 等使用GrailsCompileStatic只有确实需要动态类型的特定方法才允许CompileDynamic。同时Groovy 会自动生成属性 getter/setter开发者与 Agent 不应显式实现它们除非有自定义逻辑包装其他实现时应使用Delegate。这些约定在仓库源码中有大量实例例如rundeckapp/src/main/groovy/下的 369 个 Groovy 源文件以及core/src/main/java/下的 Java 实现均遵循上述标准。3.3 圈复杂度阈值CodeNarc 的确定性检查.claude/rules/complexity.md 定义了 Agent 专属的复杂度约束新增或修改的方法/函数圈复杂度必须 ≤ 25。它的可执行依据在 config/codenarc/rules.groovy 中ruleset { CyclomaticComplexity { maxMethodComplexity 25 } }即整个仓库的 CodeNarc 规则集仅包含这一项确定性复杂度检查阈值 25且定位为「informative-only」仅提示不阻塞构建与 PR。检查方式后端./gradlew codenarcComplexity报告输出在build/reports/codenarc/complexity.html前端ui-trellis 的 TS/Vuenpm run lint在共享的eslint/base.js中启用complexity规则。该规则还强调不得重构既有的历史违规项legacy baseline 单独跟踪也不得以历史违规为由阻塞工作。3.4 安全与最小改动原则CLAUDE.md 的 Code Conventions 还补充了 Agent 必须遵守的底线避免命令注入、XSS、SQL 注入使用参数化查询并转义用户输入只做被直接要求或明确必要的改动不擅自加功能、重构或「改进」无关内容。四、提交必须经用户确认约定文档第三条行为模式Commit Only with Confirmation—— 未经用户确认绝不提交任何更改。这一约定与仓库的 PR 协作规范CLAUDE.md 中的 Git PR Conventions配套PR 标题推荐使用[RUN-XXXX] Description格式PR 正文必须使用仓库的.github/pull_request_template.md模板并填写每个章节变更类型、解决方案、备选方案、上下文、发布说明。即 Agent 的职责边界是「产出并验证代码、向用户汇报」而提交与 PR 动作始终在用户确认之后执行。五、产物归档规范plans / reports / tmp / handoff约定文档用一张表规定了 Agent 产生的所有中间文件的落盘位置类型归档路径计划与实现方案Plans implementation proposals.claude/artifacts/plans/调查与分析报告Investigation analysis reports.claude/artifacts/reports/临时/草稿文件Temporary / scratch files.claude/artifacts/tmp/交接给其他 Agent 的备注Handoff notes.claude/artifacts/handoff/命名规范要求使用kebab-case 描述当天日期例如plan-runner-refactor-2026-04-02.md5.1 归档规范与 AI 配置体系的关系这套 artifacts 目录设计与 .claude/CONTRIBUTING.md 描述的目录结构一致.claude/下分为docs/人工撰写的参考文档、rules/按 glob 自动加载的规则、skills/工作流技能、artifacts/Agent 生成产物。归档规范保证plans让「为什么这么做」有据可查便于评审与回溯reports沉淀调查结论供其他 Agent 与开发者复用tmp隔离一次性文件避免污染主干handoff在多个 Agent 接力时传递上下文配合 skills 的onboard-contributor、backport-pr等工作流形成完整闭环。5.2 产物与技能的协同.claude/CONTRIBUTING.md 对 skill 的约束每个 skill 放在.claude/skills/skill-name/SKILL.md单文件不超过 500 行、单一职责、必须包含验证方式与产物归档规范相互呼应Agent 执行create-code、create-test、create-plugin、cve-remediation等技能时产生的计划、报告与交接文档最终都应进入上述四个 artifacts 目录从而让整个协作过程可审计、可复现。六、把约定落地一次规范的 Agent 改动流程综合 CLAUDE.md 的 Critical Rules 与本文档约定一次完整的 Agent 改动闭环如下读索引会话启动时加载 CLAUDE.md定位相关 docs / rules / skills按技能执行通过 Skill 工具调用create-code、create-test等技能生成代码与测试遵守代码标准Groovy 使用CompileStatic/GrailsCompileStatic不写显式 getter/setter新代码圈复杂度 ≤ 25本地构建验证运行./gradlew build -x check4–8 分钟通过后才可声明完成格式与复杂度复查./gradlew spotlessCheck失败则spotlessApply必要时./gradlew codenarcComplexity归档中间产物计划写入.claude/artifacts/plans/、报告写入.claude/artifacts/reports/使用 kebab-case 日期命名提交前确认向用户汇报验证结果获得确认后才执行 git 提交与 PR 创建PR 正文遵循.github/pull_request_template.md。这套流程的关键价值在于Agent 的输出质量通过「构建可编译格式可检查复杂度可度量产物可追溯提交可确认」五个环节被显式约束而不是依赖模糊的「尽力而为」。七、关键要点速查完成判据本地./gradlew build -x check通过4–8 分钟全量测试交给 CI1 小时以上。代码标准CompileStatic/GrailsCompileStatic属性访问交给 Groovy 自动生成新增方法圈复杂度 ≤ 25见 config/codenarc/rules.groovy。格式工具Spotlessratchet 自origin/main起增量检查spotlessApply自动修复。提交边界未经用户确认绝不提交PR 正文使用.github/pull_request_template.md。产物路径plans →.claude/artifacts/plans/reports →.claude/artifacts/reports/tmp →.claude/artifacts/tmp/handoff →.claude/artifacts/handoff/。命名规范kebab-case 描述当天日期例如plan-runner-refactor-2026-04-02.md。若要在仓库中实践这些约定可继续阅读 .claude/docs/build-commands.md命令全集、.claude/docs/development-guidelines.md代码标准与 .claude/CONTRIBUTING.mdAI 配置自身的扩展规范。赞分享运维任务调度后端【免费下载链接】rundeckEnable Self-Service Operations: Give specific users access to your existing tools, services, and scripts项目地址https://gitcode.com/gh_mirrors/ru/rundeck点击查看免费下载相关推荐TinyUSB 仓库的 Agent 协作开发手册从编码规范到构建验证与 PR 自动化的完整工作流TinyUSB 仓库的 Agent 协作开发手册从编码规范到构建验证与 PR 自动化的完整工作流 TinyUSB 是一个面向嵌入式系统的开源跨平台 USB 协嵌入式驱动开发通信物联网VoltAgent 仓库开发指南从 AI Agent 协作规范到 Monorepo 验证工作流VoltAgent 仓库开发指南从 AI Agent 协作规范到 Monorepo 验证工作流 VoltAgent 是一个开源的 TypeScript AI人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Ktor 仓库 Agent 协作指南测试、构建、格式化与 ABI 验证的完整工作流Ktor 仓库 Agent 协作指南测试、构建、格式化与 ABI 验证的完整工作流本篇技术指南面向在 JetBrains Ktor 仓库 gh_mirro后端Web框架微服务上一篇如何让停更的老 Mac 装上最新 macOSOpenCore Legacy Patcher 完整免费上手下一篇3步把 amis 接入现有 React 项目用 JSON 配置生成整页创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Rundeck 仓库的 AI Agent 协作规范：构建验证、代码标准与产物归档的完整工作流

相关推荐

wasm-bindgen 类型通信机制深度解析：WasmDescribe trait 与描述符（Descriptor）管线

MuPDF C 多线程渲染实战：主线程读页 + 每页一线程并行输出 PNG

CMake 环境变量 CMAKE_POLICY_VERSION_MINIMUM 详解：为新构建树注入策略版本下限

更多资讯

DeepSeek Harness桌面端发布：从命令行到GUI的迁移与插件生态全解析

商城产品详情页HTML开发实战：从静态骨架到高性能交互

DeepSeek Harness桌面端实战：API Key配置、插件体系与Skill部署全指南

从玩具到生产级：个人RAG知识库的版本治理、父子分块与混合检索实战

Python sum函数参数解析：源码中的关键字参数陷阱与TypeError根源

SpringBoot智慧医疗管理系统：从架构设计到答辩实战全攻略

今日更新

Multisim仿真NE555 PWM控制器：从搭电路到调占空比全流程

S32K312 AUTOSAR BSW开发实战：从配置踩坑到烧录交付

双目视觉三维人脸重建：从视差图到点云粗配准全流程解析

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？