rails-agent-skills

Rails Agent Skills

このスキルは、各タスクに対してアトミックスキルを順序立てて実行することで、規律ある Rails 開発を調整します。何を、どの順序で実行し、各ステップをどのように検証するかを定義します。

中核原則: アトミックでタスク固有の指示により、TDD と慣用的なパターンを通じて AI コーディングアシスタントを信頼できる Rails の協働者に変えます。

アトミックスキルの有効化

アトミックスキルを有効化するには、スキルバンドルから対応する Markdown ファイルを読み込み、そのステップの実効プロンプトとしてその指示に従います。スキルファイルが利用できない場合は、完全に停止するのではなく、以下のスキルカタログにあるインラインのフォールバックガイダンスを使用してください。出力に不足があれば記録し、ベストエフォートで慣用的な Rails の規約に従って進めてください。

HARD-GATES

1. コンテキストファースト（事前確認）

1. 最初に load-context を実行せずに、いかなる実装やレビューのアクションも行わないでください。
2. 何らかの出力を生成する前に、ホストアプリケーションのスキーマ、ルート、確立されたパターンと同期してください。

2. テストが実装をゲートする

1. 対象の振る舞いに対するテストが存在するまで、実装コードを書くことはできません。
2. 実装を始める前に、テストを bundle exec rspec <spec_file> で実行する必要があります。
3. 先に進む前に、テストが正しい理由（機能の欠如であり、構文エラーではない）で失敗する必要があります。

中核プロセス

1. コンテキストの初期化（CRITICAL）: 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 の example を書きます
テスト	test-service、triage-bug	標準的な RSpec の単体テストパターンに従い、double で依存関係を分離します
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 のパターン、strong-migration のルールに従います
エンジン	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 で定義されています。このリポジトリはさらに、15 個の追加コアスキル（Process、Code Quality、Orchestration、DDD、Ruby パターン）のために igmarin/ruby-core-skills に依存しています。

統合

• directory.json（プロジェクトルート）: 28 個のローカルアトミックスキルと 9 個のペルソナすべての正規レジストリ — 名前、ファイルパス、メタデータ。これはスキル検出の信頼できる唯一の情報源です。
• docs/reference/skill-catalog.md: 各スキルの使用上の注意を記載した人間が読めるリファレンス。directory.json が利用できない場合の手動検索に便利です。
• skill-router: 受信したタスクを正しいアトミックスキルのシーケンスにマッピングするオーケストレーション層。このエントリポイントスキルが有効化されると自動的に呼び出されます。

コア依存関係

このリポジトリは、基盤となる DDD および Ruby パターンのスキルのために igmarin/ruby-core-skills に依存しています。このプラグインが 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 — バグの診断と再現
• respond-to-review — レビューフィードバックへの対応

オーケストレーションスキル（1）:

• skill-router — 正しい専門スキルにルーティングします

---