SuperAPI AI 工具集

rails-principles-and-boundaries

通用与其它

查看项目

更新于 10-15 22:17

技能介绍

用途:在编写或评审 Rails 应用代码时,提供设计原则与按区域划分的边界指导,而非栈相关的 UI 选择(Hotwire + Tailwind 见 rails-stack-conventions)。风格与格式以项目配置的 linter 为准,本技能只补充非风格的行为与架构指导。

主要能力:设计原则方面,DRY 仅在重复带来真实维护成本时抽取,避免过早抽象;YAGNI 只满足当前需求;PORO 在能厘清职责时使用;优先 Rails 默认约定与文件放置;KISS 取满足验收标准与测试门槛的最简设计。注释解释“为什么”而非“是什么”,使用 TODO:、FIXME:、HACK:、NOTE:、OPTIMIZE: 等带上下文标签。结构化日志要求第一个参数为静态字符串,第二个参数为结构化字段哈希,不用字符串插值,必要时加 event: 供看板使用。

按区域规则:ActiveRecord 性能(app/models)注意循环中预加载、下推 SQL、优先 pluck/exists?/find_each;后台任务(app/workers、app/jobs)关注结构、队列、幂等与结构化错误日志;错误处理(app/services、app/lib、app/exceptions)使用带前缀码的领域异常;日志与追踪覆盖 services、workers、jobs、controllers、repositories;控制器使用强参数、瘦动作并委托服务,注意 IDOR 与 PII;仓库对象除非有原始 SQL、缓存、清晰领域边界或外部服务隔离的理由,否则不新建;RSpec 用 FactoryBot,优先 request spec,用 env: 元数据改 ENV,优先 let 而非 let!;序列化器显式 key: 映射、避免 N+1;服务对象单一职责;原始 SQL 禁止拼接用户输入,使用 sanitize_sql_array 或绑定参数,动态 ORDER BY 需白名单。

使用方式:先检测仓库实际使用的 linter(RuboCop、Standard Ruby、前端 linter 或 package.json/bin 脚本),运行项目文档或配置对应的命令,如 bundle exec rubocop、bundle exec standardrb、npm run lint,不要默认 RuboCop。let_it_be 仅在项目已依赖 test-prof 时使用。

限制:测试门槛为硬性要求,PRD → TASKS → 测试(编写、运行、失败)→ 实现,无失败测试前不写实现代码。若某路径不存在则跳过对应规则。本技能不定义风格规则,不要求引入 test-prof,除非用户主动要求。具体收费、平台与效果信息暂未提供。