ECC Ruby 编码风格实战指南从 RuboCop 到 Rails 分层架构的规范落地【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本指南以 ECC 仓库中 docs/ja-JP/rules/ruby/coding-style.md 为骨架结合仓库内rules/ruby/与rules/common/规则体系展开面向在 Claude Code、Codex、OpenCode、Cursor 等 Agent 工作流中编写 Ruby / Rails 代码的开发者。读完本文你将掌握 ECC 规则体系下 Ruby 3.3 与 YJIT 的取舍原则、RuboCop 与 binstub 的落地方式、Rails 分层职责边界、错误处理规范以及如何通过 PostToolUse Hooks 和 CI 门槛把这些约定固化为自动化检查。规则文件如何生效路径匹配与分层继承docs/ja-JP/rules/ruby/coding-style.md是 ECC 规则体系中 Ruby 语言分层的核心文件。其 frontmatter 定义了该规则自动激活的文件范围paths: - **/*.rb - **/*.rake - **/Gemfile - **/*.gemspec - **/config.ru也就是说只要当前编辑或审查的对象是 Ruby 源码、Rake 任务、Gemfile、gemspec 或 Rack 配置文件该规则就会被载入。该文件开头明确声明它是对通用层规则 rules/common/coding-style.md 的 Ruby / Rails 专属扩展。ECC 采用通用层 语言层的分层规则架构见 rules/README.mdrules/common/存放与语言无关的普适原则不可变性、KISS/DRY/YAGNI、文件组织、错误处理、输入验证、命名规范、代码质量清单语言目录rules/ruby/、rules/python/、rules/golang/等则以扩展声明的格式继承并细化。关于优先级rules/README.md 明确约定当语言层规则与通用层规则冲突时语言层规则优先specific overrides general类似于 CSS 特异性或.gitignore优先级规则。例如通用层推荐不可变模式但个别语言惯用的可变写法可覆盖该默认值。Ruby 层同样遵循这一机制。标准Standards运行时版本与性能取舍目标 Ruby 3.3新 Rails 项目默认以Ruby 3.3为目标运行时除非项目已经固定了旧的受支持运行时。这一约定与 rules/ruby/testing.md、rules/ruby/patterns.md 中以 Rails 8 为默认栈的前提保持一致Rails 8 要求较新的 Ruby 运行时而 3.3 提供更成熟的性能与内存表现。YJIT 必须基于实测启用YJIT只在生产环境实测启动时间、内存占用、请求/Job 吞吐量之后才启用禁止不加测量地顺手打开。理由是 YJIT 通过把 Ruby 字节码编译为机器码换取执行速度但会以额外内存占用为代价不同负载模型下收益差异显著。正确的做法是先在 staging 或灰度环境跑基准比较启用前后的三项指标再决定是否在启动参数层如RUBYOPT--yjit或初始化配置中开启。frozen_string_literal 约定当项目采用# frozen_string_literal: true约定时新 Ruby 文件必须加上该魔法注释。它把字符串字面量标记为不可变避免意外修改共享字符串同时减少字符串对象分配与 rules/common/coding-style.md 中不可变性CRITICAL的通用原则一脉相承——通用层要求永远创建新对象、绝不原地修改既有对象Ruby 的冻结字面量正是该原则在语言层面的落点。明快的 Ruby 优于炫技的元编程优先书写清晰的 Ruby而非精巧的元编程重度 DSL 代码必须隔离在窄小、有测试覆盖的边界之后。元编程define_method、method_missing、class_eval等会把运行时行为藏起来破坏静态可读性与 IDE/Agent 的符号解析能力。如果确实需要应封装成独立模块并配齐单元测试让黑魔法的影响面可控。格式与 LintFormatting and LintingRuboCop 落地配置来源与默认起点使用项目已签入仓库的 RuboCop 配置.rubocop.yml保证团队与 CI 使用同一套规则。Rails 8 应用从rubocop-rails-omakase起步——这是 Rails 官方维护的默认风格包开箱即用、约定合理只有代码库存在真实惯例时才在其上自定义规则避免早期就陷入规则争论。命令必须走 binstub 或脚本格式化/Lint 命令放在 binstub 或脚本之后确保 CI 与本地执行完全一致。原文档给出的核心命令bundle exec rubocop bundle exec rubocop -Abundle exec rubocop只报告问题不修改文件适合 CI 门禁。bundle exec rubocop -A自动修正autocorrect可安全修复的违规项适合本地提交前跑一遍。内联禁用 cop 的纪律不内联禁用 cop如# rubocop:disable ...除非该异常是窄小的、有文档说明的并且很难在代码中干净地表达。与其到处打 disable 补丁不如在配置层面针对全仓库做有据可查的调整或重构代码本身以符合规范。Rails 风格Rails Style分层职责与目录约定先遵循约定再谈自定义在引入自定义结构之前先遵循 Rails 的命名约定与目录约定app/models、app/controllers、app/views、config/routes.rb等。这一点与 rules/ruby/patterns.md 的 Rails Way First 原则一致中小型功能先用朴素 Rails MVC Active Record 惯例当模型/控制器边界开始承担多重职责时才引入 service object、query object、form object、decorator 或 presenter。控制器只做传输层的事控制器的关注点严格限定在四件事认证authentication确认你是谁授权authorization确认你能不能做参数处理parameter handling使用 strong parameters 白名单收参响应形状response shape决定返回 JSON / HTML / redirect 及状态码业务逻辑不得泄漏进控制器。可复用的领域行为按实际复杂度放置于模型、concerns、service objects、query objects 或 form objects而不是当作默认仪式到处建目录——复杂度低就放模型复杂度高了再提取这正好呼应 rules/common/coding-style.md 的 YAGNI 原则当压力真实存在时才抽象而非投机式泛化。从源码结构看ECC 仓库在 skills/backend-patterns/SKILL.md 中给出了服务层 / 仓库层 / 中间件模式的通用实现参考并指出选择与你的复杂度匹配的模式——Ruby 层的控制器-模型二分法与之一致先薄后分层。优先 binstub 而非全局命令优先bin/rails、bin/rake及签入仓库的 binstub而非全局安装的命令。原因是 binstub 绑定项目自身的 gem 版本与加载路径杜绝本机能跑、CI 挂了的版本漂移问题。bin/rails同时支持rails的全部子命令server、generate、db:migrate等。错误处理Error Handling精确 rescue 与可观测日志rescue 特定异常避免大网兜底只 rescue 你能处理的具体异常。避免宽泛的rescue StandardError块除非块内重新抛出re-raise或者为运维人员保留足够的上下文异常对象、请求 ID、参数快照等。静默吞掉异常是 rules/common/coding-style.md 明确禁止的行为绝不静默吞掉错误——错误要么被显式处理要么被带上上下文重新抛出。用 Notifications 或 Logger别留调试器运维事件使用ActiveSupport::NotificationsRails 内置的发布/订阅观测点适合做指标、审计、跨请求追踪或应用自身的 logger。已提交的应用代码中不得遗留puts、pp、debugger。这条约束在 rules/ruby/hooks.md 中被进一步固化为 PostToolUse Hooks 警告编辑后若检测到提交代码中出现debugger、binding.irb、binding.pry、puts、pp、p调用立即向开发者告警。配套规则协同测试、安全与 Hooks 门禁编码风格不是孤立的ECC 的 Ruby 规则包rules/ruby/目录以 coding-style.md 为纲配套五份文件共同构成完整的质量闭环文件主题关键约束rules/ruby/coding-style.md编码风格版本、YJIT、RuboCop、分层、错误处理rules/ruby/patterns.md架构模式Rails Way First、PostgreSQL、Solid Queue/Sidekiq、Hotwire、认证选型rules/ruby/testing.md测试Minitest/RSpec 二选一、测试金字塔、fixtures/factory_botrules/ruby/security.md安全CSRF、strong parameters、参数化 SQL、bundle-audit/brakemanrules/ruby/hooks.mdAgent HooksPostToolUse 自动格式化、安全扫描、测试与警告测试侧协同rules/ruby/testing.md框架二选一默认 Rails 测试栈用 Minitest项目已确立 RSpec 惯例时用 RSpec同一功能区内不混用。命令也走项目本地 binstubbin/rails test bin/rails test test/models/user_test.rb bundle exec rspec bundle exec rspec spec/models/user_spec.rb覆盖率用 SimpleCov 并在 CI 中设定阈值避免用低价值测试刷分支覆盖率bug 修复先补回归测试再改生产代码。安全侧协同rules/ruby/security.md状态变更请求保持 CSRF 防护开启批量赋值前用 strong parameters 或类型化边界对象。密钥存于 Rails credentials、环境变量或密钥管理服务绝不提交明文 key、token 或复制.env值。SQL 一律走 Active Record 查询 API 与参数化语句绝不把请求、Cookie、Header、Job 或 Webhook 值插值进 SQL 字符串。依赖变更时运行bundle exec bundle-audit check --update bundle exec brakeman --no-progressbundle-audit扫描已知漏洞依赖brakeman做 Rails 静态安全分析。两者同样出现在 rules/ruby/hooks.md 的 CI 门禁建议中。Agent Hooks 侧协同rules/ruby/hooks.mdrules/ruby/hooks.md把编码风格固化为 Agent 工作流中的自动化检查点RuboCopRuby 编辑后运行bundle exec rubocop -A file或项目更安全的格式化命令Brakeman安全敏感的 Rails 变更后运行bundle exec brakeman --no-progress测试对触及的文件运行最窄匹配的bin/rails test ...或bundle exec rspec ...Bundler auditGemfile/Gemfile.lock变更且项目装有 bundler-audit 时运行bundle exec bundle-audit check --update。同时设置三类警告提交了调试代码编辑禁用了 CSRF、扩大了批量赋值或加入未参数化 SQL迁移以破坏性方式改数据却没有可回滚路径或上线方案。推荐的 CI 门槛组合为bundle exec rubocop bundle exec brakeman --no-progress bin/rails test bundle exec rspec仅使用项目实际存在的命令未经维护者批准不安装新的 Hook 依赖。落地检查清单将编码风格规则与 rules/common/coding-style.md 的质量清单结合完成 Ruby 工作时逐项核对新 Rails 项目目标运行时为 Ruby 3.3YJIT 仅在实测启动/内存/吞吐后启用新 Ruby 文件按项目约定带# frozen_string_literal: true元编程与 DSL 隔离在窄小且有测试覆盖的边界内bundle exec rubocop与bundle exec rubocop -A走 binstubCI 与本地一致控制器只做认证/授权/参数/响应形状领域逻辑按复杂度下沉到模型或服务层优先bin/rails、bin/rake避免全局命令rescue 具体异常宽泛 rescue 要么重抛、要么保留运维上下文使用ActiveSupport::Notifications或 logger无puts/pp/debugger残留依赖变更后运行bundle-audit与brakeman安全敏感变更走 Hooks 门禁参考延伸规则体系的通用层基座rules/common/coding-style.mdRuby 规则包全貌rules/ruby/coding-style、patterns、testing、security、hooks 五份文件服务 / 仓库分层与适配器模式的纵深参考技能 skills/backend-patterns/SKILL.md文档参考节明确指向该技能规则的分层架构、安装方式与优先级说明rules/README.md【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
