rails-agent-skills

Rails Agent 技能

此技能通过为每项任务安排一系列原子技能，协调严谨的 Rails 开发。它定义了要运行哪些步骤、以何种顺序运行，以及如何验证每一步。

核心原则： 提供原子化、针对特定任务的指引，通过 TDD 和符合惯例的模式，让 AI 编码助手成为可靠的 Rails 协作者。

激活原子技能

要激活某项原子技能，请从技能包中读取对应的 Markdown 文件，并将其中的指引作为该步骤的实际提示词来执行。如果技能文件不可用，请使用下方技能目录中的内联备用指引，不要因此完全停止；在输出中注明任何缺失内容，并尽力遵循符合惯例的 Rails 做法。

强制门槛

1. 先了解上下文（预检）

1. 未先运行 load-context，不得执行任何实现或审查操作。
2. 生成任何输出之前，先与宿主应用的架构、路由和既定模式保持同步。

2. 测试是实现的门槛

1. 在为目标行为编写测试之前，不得编写实现代码。
2. 开始实现之前，必须通过 bundle exec rspec <spec_file> 执行测试。
3. 测试必须因正确原因失败（缺少功能，而非语法错误），之后才能继续。

核心流程

1. 初始化上下文（关键）： 激活 load-context。确认已加载架构、路由和模式后，再进行其他步骤。
2. 发现： 从目录中找出与当前任务匹配的原子技能。
3. 执行循环：
   • 规划： 激活 plan-tests。输出：待编写测试用例列表及其描述。
   • 执行： 激活 write-tests。运行 bundle exec rspec <spec_file> — 确认输出显示红灯（因正确原因失败）。然后激活 implement。运行 bundle exec rspec <spec_file> — 确认测试通过。然后激活 apply-code-conventions。
   • 润色： 激活 write-yard-docs 和 code-review。
4. 验证： 每项原子技能完成后，在进行下一步之前，核对其声明的 Output Style 检查清单。如果某一步出现意外失败，请在重试前重新运行 load-context。

示例：添加带测试的服务对象

Step 1 — load-context
  Input:  project root directory
  Action: Read schema.rb, routes.rb, and existing service objects
  Output: Confirmed patterns (e.g., services inherit ApplicationService, use call)

Step 2 — plan-tests
  Input:  "Create an OrderFulfillmentService"
  Output: [
    "returns success when inventory is available",
    "returns failure when inventory is insufficient",
    "enqueues FulfillmentJob on success"
  ]

Step 3 — write-tests
  Input:  test plan above
  Output: spec/services/order_fulfillment_service_spec.rb (written, not passing)
  Validate: bundle exec rspec spec/services/order_fulfillment_service_spec.rb
            → Expect: 3 examples, 3 failures (NameError or similar — feature missing)

Step 4 — implement
  Input:  failing spec
  Output: app/services/order_fulfillment_service.rb
  Validate: bundle exec rspec spec/services/order_fulfillment_service_spec.rb
            → Expect: 3 examples, 0 failures

Step 5 — apply-code-conventions + write-yard-docs + code-review
  Output: Linted file with YARD docs and review comments resolved

技能目录

类别	技能	后备指导（文件不可用时）
上下文	load-context	阅读 schema.rb、routes.rb 和一个示例服务/模型；手动记录约定
测试	plan-tests	编写代码前，先将预期行为列为 RSpec it 描述
测试	write-tests	使用 described_class、let、expect、have_received 等惯用写法编写 RSpec 示例
测试	test-service、triage-bug	遵循标准 RSpec 单元测试模式；使用测试替身隔离依赖项
DDD	define-domain-language、model-domain、review-domain-boundaries	应用标准 DDD 术语；按限界上下文分组
质量	code-review、security-check、apply-code-conventions、refactor-code	直接应用 Rails 最佳实践、Brakeman 检查结果和 RuboCop 规则
API/基础设施	implement-graphql、integrate-api-client、implement-background-job、review-migration	遵循 graphql-ruby 约定、ActiveJob 模式和强迁移规则
引擎	create-engine、test-engine、release-engine、document-engine	使用 rails plugin new --mountable；将规范隔离在引擎根目录下的 spec/ 中
模式	create-service-object、write-yard-docs	继承 ApplicationService，公开 .call，并使用 @param/@return YARD 标签编写文档
设置	setup-environment	验证 Ruby 版本、运行 bundle install 和 bin/rails db:setup

全部 28 个本地原子技能和 9 个角色的完整列表定义在项目根目录的 directory.json 中。此代码库还依赖 igmarin/ruby-core-skills，以获取 15 个额外的核心技能（流程、代码质量、编排、DDD 和 Ruby 模式）。

集成

• directory.json（项目根目录）：全部 28 个本地原子技能和 9 个角色的规范注册表，包含名称、文件路径和元数据。这是发现技能的事实来源。
• docs/reference/skill-catalog.md：人类可读的参考文档，包含每项技能的使用说明；directory.json 不可用时，可用于手动查找。
• skill-router：编排层，将传入任务映射到正确的原子技能序列；激活此入口技能时会自动调用。

核心依赖项

此代码库依赖 igmarin/ruby-core-skills，以获取基础 DDD 和 Ruby 模式技能。与 ruby-core-skills 一同安装此插件时，会自动检测并提供以下 15 项核心技能：

DDD 技能（3 项）：

• define-domain-language — 领域术语词汇表
• review-domain-boundaries — 审查限界上下文和语言渗漏
• model-domain — 将 DDD 映射到 Rails（模型、服务、值对象）

Ruby 模式技能（4 项）：

• create-service-object — .call 模式、响应契约、YARD
• integrate-api-client — 外部 API 的分层架构
• implement-calculator-pattern — 基于变体的计算器
• write-yard-docs — 使用 YARD 编写内联文档

流程技能（5 项）：

• tdd-process — TDD 规范和工作流
• refactor-process — 在保留行为的前提下重构
• review-process — 系统化代码审查
• security-review-process — 安全审计工作流
• test-planning-process — 测试规划与选择

代码质量技能（2 项）：

• triage-bug — Bug 诊断与复现
• respond-to-review — 回复审查反馈

编排技能（1 项）：

• skill-router — 路由到正确的专用技能

---