Ruby on Railsで始めるAI駆動開発×TDD実践｜Codexとハーネスエンジニアリングで作るDDDモジュラーモノリス

$ mkdir rails-aidd && cd rails-aidd
$ mkdir -p deploy/docker/local/db && touch deploy/docker/local/db/Dockerfile
$ mkdir -p deploy/docker/local/ruby && touch deploy/docker/local/ruby/Dockerfile
$ mkdir src && touch src/Gemfile src/Gemfile.lock
$ touch .env compose.yml .gitignore

FROM postgres:18.3

ENV LANG ja_JP.utf8

# PostgreSQLの日本語化で「ja_JP.utf8」を使うために必要
RUN apt-get update && \
    apt-get install -y locales && \
    rm -rf /var/lib/apt/lists/* && \
    localedef -i ja_JP -c -f UTF-8 -A /usr/share/locale/locale.alias ja_JP.UTF-8

FROM ruby:4.0.2-slim

RUN apt-get update -qq && \
    apt-get install -y --no-install-recommends \
      locales \
      build-essential \
      git \
      libpq-dev \
      libyaml-dev && \
    rm -rf /var/lib/apt/lists/*

RUN echo "ja_JP.UTF-8 UTF-8" > /etc/locale.gen && \
    locale-gen
WORKDIR /src

COPY src/Gemfile src/Gemfile.lock .

# bundlerのバージョンは固定して実行
RUN gem install bundler -v 4.0.10
RUN bundle _4.0.10_ install

COPY ./src /src

EXPOSE 3000

source 'https://rubygems.org'
gem 'rails', '8.1.3'

ENV=local
RAILS_ENV=development
TZ=Asia/Tokyo
LANG=ja_JP.UTF-8
LC_ALL=ja_JP.UTF-8
PORT=3000
DB_HOST=db
DB_USER=root
DB_PASSWORD=root

services:
  app:
    container_name: rails-app
    build:
      context: .
      dockerfile: ./deploy/docker/local/ruby/Dockerfile
    command: bash -c "rm -f tmp/pids/server.pid && bundle exec rails s -b 0.0.0.0 -p 3000"
    volumes:
      - ./src:/src
    ports:
      - "3000:3000"
    env_file:
      - .env
    tty: true
    stdin_open: true
    depends_on:
      db:
        condition: service_healthy
  db:
    container_name: rails-db
    build:
      context: .
      dockerfile: ./deploy/docker/local/db/Dockerfile
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      TZ: ${TZ}
      # ローカル環境でもパスワードを有効化する設定
      POSTGRES_INITDB_ARGS: --auth-local=scram-sha-256 --auth-host=scram-sha-256
    volumes:
      - rails-db-data:/var/lib/postgresql
    ports:
      - "5432:5432"
    env_file:
      - .env
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  rails-db-data:

.DS_Store
.env

$ docker compose build --no-cache

$ docker compose run --rm app rails new . -d postgresql \
--css=tailwind \
--skip-action-mailer \
--skip-action-mailbox \
--skip-action-text \
--skip-active-storage \
--skip-action-cable \
--skip-jbuilder \
--skip-test \
--skip-system-test

$ docker compose run --rm app rm -r .git

・・・

group :development, :test do
  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
  gem "debug", platforms: %i[ mri windows ], require: "debug/prelude"

  # Audits gems for known security defects (use config/bundler-audit.yml to ignore issues)
  gem "bundler-audit", require: false

  # Static analysis for security vulnerabilities [https://brakemanscanner.org/]
  gem "brakeman", require: false

  # Omakase Ruby styling [https://github.com/rails/rubocop-rails-omakase/]
  gem "rubocop-rails-omakase", require: false

  # ERB用のlint
  gem "erb_lint", require: false

  # テストライブラリ
  gem "rspec-rails", require: false

  # テストデータ用
  gem "factory_bot_rails", require: false
end

・・・

# テスト用
group :test do
  gem "faker"
  gem "capybara"
  gem "selenium-webdriver"
  gem "webdrivers"
  gem "shoulda-matchers", require: false
end

・・・

module Src
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 8.1

    # Please, add to the `ignore` list any other `lib` subdirectories that do
    # not contain `.rb` files, or that should not be reloaded or eager loaded.
    # Common ones are `templates`, `generators`, or `middleware`, for example.
    config.autoload_lib(ignore: %w[assets tasks])

    # Configuration for the application, engines, and railties goes here.
    #
    # These settings can be overridden in specific environments using the files
    # in config/environments, which are processed later.
    #
    # config.time_zone = "Central Time (US & Canada)"
    # config.eager_load_paths << Rails.root.join("extras")

    # Don't generate system test files.
    config.generators.system_tests = nil

    # タイムゾーン設定
    config.time_zone = ENV.fetch("TZ", "UTC")
  end
end

・・・

default: &default
  adapter: postgresql
  encoding: unicode
  # For details on connection pooling, see Rails configuration guide
  # https://guides.rubyonrails.org/configuring.html#database-pooling
  max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  # DB接続設定を追加
  host: <%= ENV.fetch("DB_HOST") { "localhost" } %>
  username: <%= ENV.fetch("DB_USER") { "postgres" } %>
  password: <%= ENV.fetch("DB_PASSWORD") { "password" } %>

・・・

production:
  primary: &primary_production
  <<: *default
  database: src_production
  # コメントアウト
  # username: src
  # password: <%= ENV["SRC_DATABASE_PASSWORD"] %>

・・・

$ docker compose build --no-cache

$ docker compose up -d

$ docker compose ps

$ docker compose exec app rails db:create

$ docker compose exec app rails g rspec:install

--require spec_helper
--color
--format documentation

・・・

module Src
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 8.1

    # Please, add to the `ignore` list any other `lib` subdirectories that do
    # not contain `.rb` files, or that should not be reloaded or eager loaded.
    # Common ones are `templates`, `generators`, or `middleware`, for example.
    config.autoload_lib(ignore: %w[assets tasks])

    # Configuration for the application, engines, and railties goes here.
    #
    # These settings can be overridden in specific environments using the files
    # in config/environments, which are processed later.
    #
    # config.time_zone = "Central Time (US & Canada)"
    # config.eager_load_paths << Rails.root.join("extras")

    # Don't generate system test files.
    config.generators.system_tests = nil

    # タイムゾーン設定
    config.time_zone = ENV.fetch("TZ", "UTC")

    # ジェネレーター設定
    config.generators do |g|
      g.test_framework :rspec
      g.fixture_replacement :factory_bot, dir: "spec/factories"
      g.view_specs false
      g.helper_specs false
      g.routing_specs false
      g.controller_specs false
      g.system_tests nil
    end
  end
end

# This file is copied to spec/ when you run 'rails generate rspec:install'
require 'spec_helper'
# RSpec実行時の環境変数「RAILS_ENV」の値が「test」になるように修正
# ENV['RAILS_ENV'] ||= 'test'
ENV['RAILS_ENV'] = 'test'

・・・

・・・

require 'rspec/rails'
# Add additional requires below this line. Rails is not loaded until this point!

# FactoryBot追加
require "factory_bot_rails"

RSpec.configure do |config|
  # Remove this line if you're not using ActiveRecord or ActiveRecord fixtures
  # fixtureの設定をコメントアウト
  # config.fixture_paths = [
  #   Rails.root.join('spec/fixtures')
  # ]

  # FactoryBotの設定を追加
  config.include FactoryBot::Syntax::Methods
・・・

$ docker compose restart app

$ docker compose exec app bundle exec rspec

・・・

require 'rspec/rails'
# Add additional requires below this line. Rails is not loaded until this point!

# FactoryBot追加
require "factory_bot_rails"

# shoulda-matchers追加
require "shoulda/matchers"

# capybara追加
require 'capybara/rspec'

・・・

RSpec.configure do |config|

〜

end

・・・

# shoulda-matchers設定追加
Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :rails
  end
end

# capybara設定
Capybara.default_driver = :selenium_chrome_headless

$ docker compose run --rm app bundle exec rubocop -A --only Layout

$ docker compose run --rm app bundle exec rubocop

$ touch src/.erb_lint.yml

linters:
  ErbSafety:
    enabled: true

  FinalNewline:
    enabled: true

  TrailingWhitespace:
    enabled: true

$ docker compose run --rm app bundle exec erb_lint app/views

$ docker compose exec app bundle exec brakeman --no-pager

$ git init
$ git add -A
$ git commit -m "init"

$ brew install lefthook

$ lefthook install

pre-commit:
  parallel: true
  commands:
    rubocop_format:
      run: docker compose run --rm app bundle exec rubocop -A --only Layout
    rubocop_lint:
      run: docker compose run --rm app bundle exec rubocop
    erb_lint:
      run: docker compose run --rm app bundle exec erb_lint app/views
    brakeman:
      run: docker compose run --rm app bundle exec brakeman --no-pager

pre-push:
  commands:
    rspec:
      run: |
        docker compose up -d
        docker compose exec -T app rails db:prepare
        docker compose exec -T app bundle exec rspec

require "active_support/core_ext/integer/time"


Rails.application.configure do


・・・


# ログ出力にリクエストIDを追加
config.log_tags = [ :request_id ]

end

/my-project
 ├── /.codex
 |    ├── config.toml  ※codexに関する設定
 |    |
 |    ├── /rules  ※sandbox外で実行できるコマンド制御の設定
 |    |    └── default.rules
 |    |
 |    ├── /agents  ※サブエージェントを利用する場合の例
 |    |    ├── orchestrator.toml  ※指揮者（全体制御）
 |    |    ├── tester.toml        ※テスター（テストコード作成・検証）
 |    |    ├── implementer.toml   ※実装者（テストコードを通すように実装）
 |    |    └── reviewer.toml      ※レビュワー（設計や品質チェック）
 |    |
 |    ├── /workflows  ※ワークフローを利用する場合の例
 |    |    └── tdd_flow.md  ※TDD（テスト駆動開発）のフロー
 |    |
 |    └── /skills  ※Agent Skillsを利用する場合
 |
 ├── AGENTS.md  ※ルートディレクトリ用（共通ルール）
 |
 ├── /src
 |    └── AGENTS.md  ※サブディレクトリ用（専用ルール）
 |
 └── /docs  ※詳細仕様にファイル分割して格納（各種AGENTS.mdから指定する）
      └── /rules
           ├── architecture.md  ※設計思想のルール定義
           ├── database.md      ※DB設計のルール定義
           ├── sub.md           ※サブディレクトリ用のルール定義
           └── testing.md       ※テスト用のルール定義
 

$ mkdir .codex && touch .codex/config.toml

model = "gpt-5.2"
model_reasoning_effort = "medium"

sandbox_mode = "workspace-write"

[projects."対象のプロジェクトのフルパス"]
trust_level = "trusted"

$ mkdir -p .codex/rules && touch .codex/rules/default.rules

# --- ディスク破壊（即禁止） ---
prefix_rule(
    pattern=["mkfs", "dd if=", "wipefs"],
    decision="forbidden",
    justification="ストレージ破壊操作"
)

# --- Git履歴破壊（即禁止） ---
prefix_rule(
    pattern=["git push --force", "git push -f", "git push --force-with-lease"],
    decision="forbidden",
    justification="履歴改変（強制push）によるリポジトリ破壊の可能性"
)

# --- GitHub CLI 危険操作 ---
prefix_rule(
    pattern=["gh repo delete"],
    decision="forbidden",
    justification="リポジトリ削除（不可逆）"
)

prefix_rule(
    pattern=["gh pr merge --admin"],
    decision="ask",
    justification="保護ルール無視の強制マージ"
)

prefix_rule(
    pattern=["gh workflow run"],
    decision="ask",
    justification="CI/CDの強制実行"
)

prefix_rule(
    pattern=["gh secret set", "gh secret delete"],
    decision="ask",
    justification="機密情報の変更"
)
# --- 危険削除（確認） ---
prefix_rule(
    pattern=["rm -rf", "sudo rm"],
    decision="ask",
    justification="不可逆削除の可能性"
)

# --- 権限昇格 ---
prefix_rule(
    pattern=["sudo"],
    decision="ask",
    justification="システム影響が大きい"
)

$ mkdir -p .codex/agents
$ touch .codex/agents/pm.toml .codex/agents/tester.toml .codex/agents/implementer.toml .codex/agents/reviewer.toml

name = "pm"
description = "全体の進行管理とタスク分解を行うプロダクトマネージャー"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたは開発全体を指揮するプロダクトマネージャーです。

役割：
- 要件を整理し、タスクに分解する
- tester → implementer → reviewer の順でタスクを割り振る
- 各エージェントのアウトプットを評価し、次の行動を決める

ルール：
- 必ずTDDサイクル（RED → GREEN → REVIEW）を守る
- 不完全な実装は次に進めない
- 問題があれば前の工程に差し戻す

出力形式：
- 次に行動するエージェント名
- 依頼内容（具体的に）
"""

name = "tester"
description = "テストコード作成と動作検証を行うTDDエンジニア"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたはTDDに従うテストエンジニアです。

役割：
- 仕様に基づいたテストコードを書く（RED）
- 実装後にテストを実行し検証する（GREEN）

ルール：
- まず失敗するテストを書く（RED）
- テストは仕様を正確に表現すること
- エッジケースも考慮する
- 実装コードは書かない

出力：
- テストコード
- テストの意図説明
"""

name = "implementer"
description = "テストを通すための実装を行うエンジニア"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたはTDDに従う実装エンジニアです。

役割：
- テストが通る最小限の実装を書く

ルール：
- テストを通すことを最優先
- 過剰な設計をしない（YAGNI）
- テストを書かない
- リファクタは必要最低限

出力：
- 実装コード
- 実装の簡単な説明
"""

name = "reviewer"
description = "仕様適合性・品質・セキュリティをレビューするエンジニア"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
あなたはコードレビュー担当です。

役割：
- 実装が仕様を満たしているか確認
- バグ・セキュリティ問題を検出
- テスト不足を指摘

観点：
- 正しさ（仕様通りか）
- セキュリティ
- 境界値・異常系
- テスト網羅性

ルール：
- 指摘は具体的に
- 再現手順を書く
- スタイル指摘は重要な場合のみ

出力：
- 指摘一覧（重要度付き）
- 修正提案
"""

$ mkdir -p .codex/workflows && touch .codex/workflows/tdd_flow.md

# TDD開発フロー

本フローは pm の指示を起点として進行するが、
各エージェントは自身の責務に従い独立して実行する。

---
1. pmが要件を整理し、タスクとして分解する
2. testerが失敗するテストを書く（RED）
3. implementerがテストを通す（GREEN）
4. testerがテスト結果を検証する
5. reviewerがレビューを行う
6. 問題があれば修正ループに戻る

---

## ルール

- REDなしで実装しない
- GREEN未達でレビューしない
- レビューNGなら再実装

$ mkdir -p .codex/skills/plan-to-issue && touch .codex/skills/plan-to-issue/SKILL.md
$ mkdir -p .codex/skills/plan-to-issue/references && touch .codex/skills/plan-to-issue/references/rules.md
$ mkdir -p .codex/skills/plan-to-issue/assets && touch .codex/skills/plan-to-issue/assets/template.md
$ mkdir -p .codex/skills/plan-to-issue/scripts && touch .codex/skills/plan-to-issue/scripts/create_issue.sh
$ chmod +x .codex/skills/plan-to-issue/scripts/create_issue.sh

---
name: plan-to-issue
description: プランモードで作成した開発計画をGitHubのIssue用のフォーマットへ変換して自動登録する
---

# plan-to-issue

## 概要
このスキルは、プランモードで作成された開発計画を読み込み、指定されたルールとテンプレートに従ってGitHub Issue用のフォーマットへ変換し、専用のスクリプトを用いてGitHubへ自動登録します。

## 参照ファイル
このスキルを実行する際は、以下のファイルを必ず読み込んで使用してください。

- **変換ルール定義**: `references/rules.md`
- 開発計画からIssueフォーマットへ変換する際のルールや抽出条件が記載されています。
- **出力フォーマット**: `assets/template.md`
- Issueの本文を作成するためのMarkdownテンプレートです。
- **実行用スクリプト**: `scripts/create_issue.sh`
- 作成したIssueデータをGitHubに登録するためのシェルスクリプトです。

## 入力
プランモードで生成された開発計画

## 出力
GitHub Issue（gh issue create により自動登録）

## 実行手順（ワークフロー）
以下のステップに従って処理を実行してください。

1. **開発計画の読み込み**
- 現在のプランモードで作成・合意された開発計画（タスク、目的、要件など）を確認します。

2. **変換ルール定義の読み込み**
- `references/rules.md` を読み込み、開発計画の内容をGitHub Issue用のフォーマットに変換するためのルールを理解します。

3. **出力フォーマットの読み込み、テンプレートの生成**
- `assets/template.md` を読み込み、開発計画の内容を変換ルールに基づいてテンプレートの構造に当てはめ、Issueの本文を生成します。

4. **Issueのタイトルを作成**
- 生成したIssueの本文の内容から、変換ルールに基づいてIssueのタイトルを作成します。

5. **GitHubのIssueを登録**
- `scripts/create_issue.sh` を利用し、作成したIssueのタイトルと本文をGitHubのIssueに登録します。

# 変換ルール定義（plan-to-issue）

このドキュメントは、プランモードで作成された開発計画をGitHub Issue用フォーマットへ変換するためのルールを定義する。

---

## 1. 基本方針

- 開発計画の内容を「1 Issue = 1目的（または1成果物）」の粒度で整理する
- 曖昧な記述は補完し、実行可能な形に正規化する
- 情報が不足している場合は、合理的に補完する（推測可）
- 冗長な説明は要約するが、重要な前提は保持する

---

## 2. フィールド対応ルール

開発計画の内容を以下のIssueテンプレートにマッピングする

### 2.1 概要（summary）
- 開発計画の「目的」「やること」を1〜3文で要約
- 実装内容ではなく「何を達成するか」を中心に記述
- 可能であれば動詞で開始する（例: 「〇〇を実装する」）

---

### 2.2 背景（background）
- なぜこの作業が必要なのかを記述
- 以下の情報を優先的に抽出
- 課題
- 現状の問題点
- ビジネス的/技術的な理由
- 明示されていない場合は、文脈から補完する

---

### 2.3 スコープ（scope）
- 対象範囲を明確化
- 含めるもの（In Scope）と含めないもの（Out of Scope）を整理
- 不明な場合は「暗黙のスコープ」を明文化する

例:
- 含む: API実装、UI変更
- 含まない: インフラ構築、リファクタリング全般

---

### 2.4 タスク（tasks）
- 実装手順をチェックリスト形式に分解
- 1タスク = 1アクション
- 粒度は「1〜3時間程度で完了できる単位」を目安に分割

#### タスク分解ルール
- 「設計」「実装」「テスト」「確認」を含める
- 抽象的な表現は禁止（例: 「いい感じに実装する」）
- 動詞で開始する（例: 「APIエンドポイントを作成する」）

#### 例
- [ ] APIのエンドポイントを定義する
- [ ] データモデルを作成する
- [ ] バリデーションを実装する
- [ ] 単体テストを追加する

---

### 2.5 受け入れ条件（acceptance_criteria）
- 完了とみなす条件を明確にする
- テスト可能・検証可能であることが必須

#### ルール
- 「〜できること」で記述
- 可能な限り具体的に書く
- 曖昧な表現は禁止（例: 「正常に動く」）

#### 例
- 正しいリクエストで200レスポンスが返ること
- 不正な入力時にバリデーションエラーが返ること
- UI上で新機能が操作できること

---

### 2.6 補足（notes）
- 以下の情報を含める
- 技術的な注意点
- 依存関係
- 未確定事項
- 将来対応

---

## 3. タイトル生成ルール

Issueタイトルは以下のルールで生成する

### フォーマット

[種別] 内容の要約

### 種別の分類
- feat: ユーザーに価値を提供する新機能
- fix: 不具合の修正
- refactor: 挙動を変えない内部改善
- docs: ドキュメントの追加・更新
- test: テストの追加・修正
- infra: インフラ・CI/CD・環境構築
- chore: 上記に当てはまらない雑務（極力使わない）

### ルール
- 30〜60文字程度に収める
- 内容が一目で分かるようにする
- summaryの内容をベースに生成する

例:
- feat: ユーザー登録APIを実装する
- fix: ログイン時の認証エラーを修正

---

## 4. Issue分割ルール

以下の場合は複数Issueに分割する

- 明確に独立した機能が複数存在する
- フロントエンドとバックエンドが分離可能
- 実装規模が大きすぎる（タスクが10個以上）

### 分割基準
- 各Issueが独立して完了可能であること
- 依存関係がある場合はnotesに記載

---

## 5. 不足情報の補完ルール

情報が不足している場合は以下に従う

- 文脈から合理的に推測する
- 推測した内容はnotesに明記する
- 重要な不確定要素は「要確認」として記載

---

## 6. 禁止事項

- 曖昧な表現（例: 適切に、いい感じに）
- 実行不可能なタスク分解
- 背景なしのIssue作成
- 受け入れ条件が検証不能な状態

---

## 7. 出力品質チェック

出力前に以下を確認する

- [ ] summaryが目的ベースになっている
- [ ] tasksが具体的で分解されている
- [ ] acceptance criteriaが検証可能である
- [ ] scopeが明確である
- [ ] タイトルが簡潔で分かりやすい

## 概要
{{summary}}

## 背景
{{background}}

## スコープ
{{scope}}

## タスク
- [ ] {{tasks}}

## 受け入れ条件
- {{acceptance_criteria}}

## 補足
{{notes}}

#!/usr/bin/env bash

set -euo pipefail

# ===============================
# Usage:
# ./create_issue.sh "タイトル" "本文"
# ===============================

TITLE="${1:-}"
BODY="${2:-}"

# タイトルと本文の入力チェック
if [[ -z "$TITLE" || -z "$BODY" ]]; then
  echo "Usage: $0 \"タイトル\" \"本文\""
  exit 1
fi

# gh コマンド存在チェック
if ! command -v gh &> /dev/null; then
  echo "gh コマンドが見つかりません"
  exit 1
fi

# GitHub認証チェック
if ! gh auth status &> /dev/null; then
  echo "GitHubにログインしていません"
  echo "gh auth login を実行してください"
  exit 1
fi

echo "Issueを作成中..."

# 一時ファイル作成
TMP_FILE=$(mktemp)

# 一時ファイルをスクリプト終了時に削除
trap 'rm -f "$TMP_FILE"' EXIT

# 本文を一時ファイルに書き込み
printf "%s" "$BODY" > "$TMP_FILE"

# Issue作成
gh issue create \
  --title "$TITLE" \
  --body-file "$TMP_FILE"

echo "Issue作成完了"

$ mkdir -p .codex/skills/auto-commit && touch .codex/skills/auto-commit/SKILL.md

$ mkdir -p .codex/skills/auto-pr && touch .codex/skills/auto-pr/SKILL.md
$ mkdir -p .codex/skills/auto-pr/assets && touch .codex/skills/auto-pr/assets/template.md
$ mkdir -p .codex/skills/auto-pr/scripts && touch .codex/skills/auto-pr/scripts/create_pr.sh
$ chmod +x .codex/skills/auto-pr/scripts/create_pr.sh

---
name: auto-pr
description: 直前のコミット内容をもとにPRタイトルと本文を生成し、GitHubのPR用フォーマットへ変換して自動登録する
---

# auto-pr

## 概要

このスキルは、直前のコミット内容をもとにPRタイトルと本文を生成し、GitHubのPR用フォーマットへ変換して自動登録します。

## 参照ファイル

このスキルを実行する際は、以下のファイルを必ず読み込んで使用してください。

- PRテンプレート: `assets/template.md`
- PR作成スクリプト: `scripts/create_pr.sh`

## 入力

直前のコミット情報

## 出力

GitHubのPR（gh pr create により自動登録）

---

## 実行手順

### 1. 直前のコミット情報と変更内容を取得する

```bash
git log -1 --pretty=format:"%h%n%s%n%b"
git show --no-color
```

- git log: 意図（タイトル・背景）
- git show: 変更内容（diff）

---

### 2. 解析して以下を生成する

- summary（概要）
- background（背景・目的）
- implementation（実装内容：箇条書き）
- test_items（テスト確認項目：チェックリスト形式）
- impact（影響範囲：箇条書き）
- future_work（未対応・今後の課題：箇条書き）

---

### 3. PR本文を生成する

`assets/template.md` を読み込み、以下ルールで置換する：

- {{summary}} → summary
- {{background}} → background
- {{implementation}} → implementation
- {{test_items}} → test_items
- {{impact}} → impact
- {{future_work}} → future_work

---

### 4. PRタイトルを生成する

フォーマット：

```text
auto: <summaryの短縮版>
```

---

### 5. PRを作成する

`scripts/create_pr.sh` を利用し、生成したPRタイトルと本文をGitHubのプルリクエストに登録します。

---

## 補足ルール

- implementation / impact / future_work は必ず箇条書きで出力する
- test_items はチェックリスト形式（- [ ]）で出力する
- diff（git show）を必ず参照し、推測のみで生成しない

## 概要
{{summary}}

## 背景・目的
{{background}}

## 実装内容
- {{implementation}}

## テスト確認項目
- [ ] {{test_items}}

## 影響範囲
- {{impact}}

## 未対応・今後の課題
- {{future_work}}

#!/usr/bin/env bash

set -euo pipefail

# ===============================
# Usage:
# ./create_pr.sh "タイトル" "本文"
# ===============================

TITLE="${1:-}"
BODY="${2:-}"

# タイトルと本文の入力チェック
if [[ -z "$TITLE" || -z "$BODY" ]]; then
  echo "Usage: $0 \"タイトル\" \"本文\""
  exit 1
fi

# gh コマンド存在チェック
if ! command -v gh &> /dev/null; then
  echo "gh コマンドが見つかりません"
  exit 1
fi

# GitHub認証チェック
if ! gh auth status &> /dev/null; then
  echo "GitHubにログインしていません"
  echo "gh auth login を実行してください"
  exit 1
fi

echo "PRを作成中..."

# 一時ファイル作成
TMP_FILE=$(mktemp)

# 一時ファイルをスクリプト終了時に削除
trap 'rm -f "$TMP_FILE"' EXIT

# 本文を一時ファイルに書き込み
printf "%s" "$BODY" > "$TMP_FILE"

# PR作成
gh pr create \
  --title "$TITLE" \
  --body-file "$TMP_FILE"

echo "PR作成完了"

/src
 └── /app
      ├── /controllers（コントローラー定義）
      |    |
      |    ├── /web
      |    |
      |    └── /api （将来的に利用する想定のAPIモード用）
      |
      ├── /models（アプリ全体の共通データ層・ActiveRecordモデル置き場）
      |
      ├── /views（Rails用のビュー）
      |
      ├── /domains（中核の業務領域・ドメイン駆動設計）
      |    |
      |    └── /[domain_name]
      |         |
      |         ├── /domain（ドメイン層）
      |         |    |
      |         |    ├── /entities（エンティティ）
      |         |    |
      |         |    ├── /value_objects（値オブジェクト）
      |         |    |
      |         |    ├── /services（ドメインサービス）
      |         |    |
      |         |    └── /repositories（リポジトリのインターフェース）
      |         |
      |         ├── /use_cases（ユースケース層）
      |         |
      |         └── /infrastructure（インフラストラクチャ層）
      |              |
      |              └── /repositories（リポジトリの実装）
      |                   |
      |                   ├── /command（書き込み）
      |                   |
      |                   └── /query（読み取り）
      |
      ├── /features（補完的な業務領域・トランザクションスクリプト）
      |    |
      |    └── /[feature_name]
      |         |
      |         └── /services（サービス層） 
      |
      ├── /resources（一般的な業務領域・アクティブレコード）
      |     ※例：user.rbやpayment_gateway.rbなどを置く
      |
      └── /shared（横断関心）

$ mkdir -p docs/rules
$ touch docs/rules/architecture.md docs/rules/database.md
$ touch docs/rules/boundaries.md docs/rules/rails.md docs/rules/testing.md
$ touch src/AGENTS.md AGENTS.md

# アーキテクチャ設計のルール定義

## 概要
本プロジェクトはRailsベースのモジュラーモノリス構成かつドメイン駆動設計（DDD）を採用し、業務の複雑さと表現力に応じて以下の3層に分離します。

- 中核の業務領域 → ドメイン駆動設計（DDD）→ domains
- 補完的な業務領域 → トランザクションスクリプト → features
- 一般的な業務領域 → アクティブレコード（単純なCRUD） → resources

---

## ディレクトリ構造の前提

```
/src
 ├── /app
 |    ├── /controllers（コントローラー定義）
 |    |    |
 |    |    ├── /web
 |    |    |
 |    |    └── /api （将来的に利用する想定のAPIモード用）
 |    |
 |    ├── /models（アプリ全体の共通データ層・ActiveRecordモデル置き場）
 |    |
 |    ├── /views（Rails用のビュー）
 |    |
 |    ├── /domains（中核の業務領域・ドメイン駆動設計）
 |    |    |
 |    |    └── /[domain_name]
 |    |         |
 |    |         ├── /domain（ドメイン層）
 |    |         |    |
 |    |         |    ├── /entities（エンティティ）
 |    |         |    |
 |    |         |    ├── /value_objects（値オブジェクト）
 |    |         |    |
 |    |         |    ├── /services（ドメインサービス）
 |    |         |    |
 |    |         |    └── /repositories（リポジトリのインターフェース）
 |    |         |
 |    |         ├── /use_cases（ユースケース層）
 |    |         |
 |    |         └── /infrastructure（インフラストラクチャ層）
 |    |              |
 |    |              └── /repositories（リポジトリの実装）
 |    |                   |
 |    |                   ├── /command（書き込み）
 |    |                   |
 |    |                   └── /query（読み込み）
 |    |
 |    ├── /features（補完的な業務領域・トランザクションスクリプト）
 |    |    |
 |    |    └── /[feature_name]
 |    |         |
 |    |         └── /services（サービス層） 
 |    |
 |    ├── /resources（一般的な業務領域・アクティブレコード）
 |    |     ※例：user.rbやpayment_gateway.rbなどを置く
 |    |
 |    └── /shared（横断関心）
 |
 └── /spec（テストコード）
```

---

## レイヤー構成の定義

### domains（中核の業務領域 / ドメイン駆動設計）

事業の本質的価値を生み出す領域

#### 特徴

- 業務ルールが複雑で変化しやすい
- 意思決定ロジックの中心
- ビジネス競争力に直結する領域
- ドメインモデルが重要になる

#### 設計原則（DDD適用）

- 集約・エンティティ / 値オブジェクト / ドメインサービスを適用する
- ビジネスルールをコードとして明示的に表現する
- 副作用を最小化する
- 可能な限り純粋ロジックとして設計する

#### 構造

- [domain_name]
  - domain（ドメイン層）
    - entities（エンティティ）
    - value_objects（値オブジェクト）
    - services（ドメインサービス）
    - repositories（リポジトリのインターフェース）
  - use_cases（ユースケース層）
  - infrastructure（インフラストラクチャ層）
    - repositories（リポジトリの実装）
      - command（書き込み）
      - query（読み取り）

#### 例

- 与信判断
- 価格最適化
- 予約枠管理
- 配送ルート最適化

---

### features（補完的な業務領域 / トランザクションスクリプト）

中核業務を支える周辺処理領域

#### 特徴

- 業務ルールは存在するが比較的単純
- 処理の流れ（手続き）が中心
- 複数処理や外部処理の調整役

#### 設計原則

- トランザクションスクリプトとしてサービス層に実装する
- ユースケース単位で記述する
- トランザクション境界はサービス層で明確に管理する
- シンプルなデータ操作に限定し、複雑なロジックは持ち込まない
- 可読性を優先し、副作用や永続化は明示的に分離する
- 複雑化・肥大化した場合はdomainsへ移行する

#### 構造

- [feature_name]
  - services（サービス層）

#### 例

- 注文後メール送信
- ポイント付与
- 在庫減算処理
- 単純な承認フロー

---

### resources（一般的な業務領域 / アクティブレコード）

業務固有性が低いデータ管理領域

#### 特徴

- CRUD中心の処理
- ビジネスルールが薄い
- データの保存・取得が主目的

#### 設計原則

- ActiveRecordベースで十分表現可能
- インフラ寄りの扱い
- 業務判断を持たない

#### 構造

- [resource_name.rb]

#### 例

- ユーザー基本情報
- マスターデータ（カテゴリ・都道府県など）
- ログ
- 設定情報

---

## shared（横断関心）

全レイヤーから参照可能な共通処理

### 例

- /utils
- /constants
- /types
- /errors
- /validators
- /formatters
- /time
- /pagenation

---

## models（データ層 / ActiveRecord集約層）

- 全てのActiveRecordのモデルはここに集約する
- データアクセスの唯一の責務を持つ
- 業務ロジックは禁止
- 各レイヤーから利用される基盤層

---

## 依存関係

### 呼び出し方向（実行フロー）

- controller → domains/use_cases または features/services または resources
- domains/use_cases → repositories → models
- features/services → models
- resources → models
- shared （全レイヤーから参照可能）

---

## 基本原則

- controller：HTTPリクエストの受け取り、ユースケースの呼び出し専用
- domains：中核の業務領域、複雑で競争優位性が高いビジネスをここに集約
- features：補完的な業務領域、単純で競争優位性を生み出さないビジネスをここに集約
- resources：一般的な業務領域、複雑だが競争優位性を生み出さずに共通の仕組みを利用するビジネスをここに集約
- shared：横断関心、各レイヤーから利用可能な共通の処理を集約
- models：データ層

---

## 設計判断基準

設計する際の分類基準は以下の通り：

- ルールやビジネスロジックが複雑になり、破綻しやすいもの → domains
- ルールが薄く、単純であり、処理フロー中心のもの → features
- 単純なCRUD処理や、共通の外部サービスを利用するもの → resources

---

## その他の重要ルール

- controllerは直接modelsを呼び出して操作しない
- controllerは必ずユースケース層を経由する
- レイヤー内部の実装詳細は外部から呼ばない

# データベース設計のルール定義

## 基本方針

- ActiveRecordを唯一のORMとして使用する
- DBは永続化の責務のみを持つ

---

## モデル設計

- 全モデルは src/app/models に集約する
- ビジネスロジックは禁止
- scopeは軽量クエリのみ許可

---

## スキーマ設計

- 破壊的変更を避ける
- NULL制約・外部キー制約を積極的に使用
- インデックスは用途ベースで設計する

---

## 禁止事項

- DBに業務ルールを持たせない
- fat model禁止

# コード配置のルール定義・境界ルール定義

## 目的

業務重要度と役割に応じてコードの配置場所を決定する。

---

## ディレクトリ構造の前提

```
/src
 ├── /app
 |    ├── /controllers（コントローラー定義）
 |    |    |
 |    |    ├── /web
 |    |    |
 |    |    └── /api （将来的に利用する想定のAPIモード用）
 |    |
 |    ├── /models（アプリ全体の共通データ層・ActiveRecordモデル置き場）
 |    |
 |    ├── /views（Rails用のビュー）
 |    |
 |    ├── /domains（中核の業務領域・ドメイン駆動設計）
 |    |    |
 |    |    └── /[domain_name]
 |    |         |
 |    |         ├── /domain（ドメイン層）
 |    |         |    |
 |    |         |    ├── /entities（エンティティ）
 |    |         |    |
 |    |         |    ├── /value_objects（値オブジェクト）
 |    |         |    |
 |    |         |    ├── /services（ドメインサービス）
 |    |         |    |
 |    |         |    └── /repositories（リポジトリのインターフェース）
 |    |         |
 |    |         ├── /use_cases（ユースケース層）
 |    |         |
 |    |         └── /infrastructure（インフラストラクチャ層）
 |    |              |
 |    |              └── /repositories（リポジトリの実装）
 |    |                   |
 |    |                   ├── /command（書き込み）
 |    |                   |
 |    |                   └── /query（読み込み）
 |    |
 |    ├── /features（補完的な業務領域・トランザクションスクリプト）
 |    |    |
 |    |    └── /[feature_name]
 |    |         |
 |    |         └── /services（サービス層） 
 |    |
 |    ├── /resources（一般的な業務領域・アクティブレコード）
 |    |     ※例：user.rbやpayment_gateway.rbなどを置く
 |    |
 |    └── /shared（横断関心）
 |
 └── /spec（テストコード）
```

---

## レイヤー定義

### app/controllers（コントローラー）

- HTTPリクエストを受け取り、レスポンスを返すための薄いレイヤー
- パラメータの受け取り・バリデーション・認証/認可の入口を担う
- ユースケース層（app/domains/*/use_cases or app/features/*/services or app/resources/*）を呼び出す
- 業務ロジックは持たない（持ってはいけない）
- レスポンス整形（JSON / HTML）は行うが、ビジネス判断は行わない

#### 依存ルール

- controllers → ユースケース（app/domains/*/use_cases or app/features/*/services or app/resources/*）
- controllers → views（HTMLの場合）

---

### app/models（データ層 / ActiveRecordモデル置き場）

- ActiveRecordベースのDBテーブルとのマッピングを担う
- スキーマ表現・リレーション・スコープなどの永続化に近い関心を持つ
- コールバックやロジックは極力最小限に抑える
- ドメイン層から直接使わず、Infrastructure層経由で利用するのが基本
- 「Fat Model」にしない（ビジネスロジックはドメインへ）

#### 依存ルール

- models ← infrastructure（repositoryなど）

---

### app/views（Rails用のビュー）

- HTMLテンプレートの描画を担う
- 表示ロジック（フォーマット・簡単な条件分岐）のみ許容
- 業務ロジックやドメイン知識は持たない
- instance変数はcontrollerから受け取る

#### 依存ルール

- views ← controllers

---

### app/domains（中核の業務領域 / ドメイン駆動設計）

- アプリケーションの最も重要なビジネスロジックを集約
- 境界づけられたコンテキスト（= domain_name）単位で分割

#### domain/entities

- 同一性（ID）を持つオブジェクト
- ビジネスルール・不変条件を保持
- 永続化手段（ActiveRecordなど）に依存しない

#### domain/value_objects

- 不変オブジェクト
- 値による等価性で比較される
- ドメインルールを内包可能（例：金額、メールアドレス）

#### domain/services

- エンティティやVOに属さないドメインロジック
- 複数のエンティティにまたがるビジネスルールを表現

#### domain/repositories

- リポジトリのインターフェース定義
- 実装部分はinfrastructure/repositoriesで行う
- コマンド・クエリ責務分離（CQRS）設計とし、command（書き込み）とquery（読み取り）に分ける

#### use_cases

- アプリケーションのユースケース単位の処理
- トランザクション境界を管理
- ドメインオブジェクトを組み合わせて処理を実行
- 外部I/F（repositoryなど）はインターフェース経由で利用

#### infrastructure/repositories

- 永続化の具体実装
- ActiveRecord（app/models）を利用してDBアクセスを行う
- ドメイン層に定義されたRepositoryインターフェースを実装
- 外部APIや他システム連携もここに含めてよい

#### 依存ルール

- domain層は他のレイヤーに依存しない
- use_casesはdomainに依存するが、infrastructureの詳細には依存しない（DI前提）
- infrastructureはdomainに依存してよい

---

### app/features（補完的な業務領域 / トランザクションスクリプト）

- ドメインとして切り出すほどではないが、機能としてまとまりがある処理
- シンプルな業務ロジックを扱う
- サービスとして実装する

#### services

- 1サービス1ユースケースとして表現
- ActiveRecord（app/models）を直接利用してよい
- 複雑化したらdomainsへ昇格させる前提

#### 位置づけ

- 軽量なユースケース層
- DDDの厳密さを求めない代わりにスピードを優先

#### 依存ルール

- features → models はOK
- features → domains は原則避ける

---

### app/resources（一般的な業務領域 / アクティブレコード）

- 単純なCRUD処理など、共通の仕組みを利用するような処理

#### 例

- ActiveRecordベースのシンプルなCRUD処理
  - 例：User、PaymentGatewayなど
- 外部サービスのような共通の仕組みを利用する単純な処理
- ビジネスルールが薄い処理

#### 役割

- ドメインに昇格しないActiveRecordベースの共通処理置き場

---

### app/shared（横断関心）

- 全レイヤーから参照可能な共通処理

#### 例

- /utils
- /constants
- /types
- /errors
- /validators
- /formatters
- /time
- /pagenation

---

### spec（テストコード）

#### 基本方針

- レイヤーごとに責務に応じたテストを行う
- 下位レイヤーほど高速・純粋、上位レイヤーほど統合的に検証する
- 「どこで何を保証するか」を明確にし、テストの重複を避ける
- ビジネスロジックは domainsで担保する（他レイヤーで重複して検証しない）

---

#### 主な分類

- controllers：インテグレーションテスト → リクエストスペック
  - HTTPリクエスト/レスポンスの検証（ステータスコード、JSON構造など）
  - 認証・認可の動作確認
  - ユースケースが正しく呼ばれていることの間接確認
  - 業務ロジックの詳細までは検証しない
  - 可能な限りモックを使わず、実際のスタックに近い形で検証する

- models：ユニットテスト → モデルスペック
  - スコープ・バリデーション・リレーションの検証
  - DBに近い振る舞い（クエリ結果など）の確認
  - コールバックは必要最小限にし、テストも最小限に留める
  - ビジネスロジックはテストしない（domainで担保）

- views：E2Eテスト → システムスペック
  - ユーザー操作を通した画面表示の検証
  - フォーム入力〜結果表示までの一連のフロー確認
  - 表示崩れや重要なUI要素の存在確認
  - 細かい文言やHTML構造には依存しすぎない
  - JavaScriptを含む挙動もここで検証

- domains：ユニットテスト
  - ビジネスルール・不変条件の検証
  - エンティティ・ValueObject・ドメインサービスの振る舞い確認
  - 外部依存（DB・API）は排除し、純粋なオブジェクトとしてテスト
  - 境界値・異常系を重点的にテストする
  - 最も網羅的かつ信頼できるテスト層

- features：インテグレーションテスト
  - Request Specを利用
  - サービス単位でのユースケース検証
  - ActiveRecordを含めた一連の処理の動作確認
  - 複雑な分岐や副作用（レコード作成・更新）を検証
  - controller経由 or 直接サービス呼び出しのどちらでもよい
  - domainに昇格すべきロジックが混ざっていないかの検知にも使う

- resources：E2Eテスト
  - API：request spec（統合テスト） / View：system spec（E2Eテスト）
    - API：クライアント視点でリクエストの連携が成立することを担保
    - View：ユーザー操作として一連の体験が成立することを担保
  - 主要なフロー（登録 → 認証 → 操作）の検証
  - 認証・認可・決済など横断的関心の動作確認
  - クライアント視点でAPIが正しく連携できることを担保
  - 成功パターンを中心に最小限のケースに絞る
  - 詳細なバリデーションや分岐ロジックは下位レイヤーで担保

---

#### 補足ポリシー

- ドメイン層は最速で実行できるテストにする（DBアクセス禁止）
- インフラ層（repositoryなど）は必要に応じて統合テストを行う
- モックは「外部境界」に限定して使用する（DB・外部APIなど）
- テストが壊れやすい構造（過度なモック、内部実装依存）を避ける
- 迷った場合は「その責務はどのレイヤーか」に立ち返って配置する

---

## ユースケース呼び出しルール

- controllerは各レイヤーに定義されたユースケースのみ呼び出す。
- 内部実装やモデルは直接呼ばない。

### 例

- domains/use_casesのユースケース
- features/servicesのユースケース
- resourcesのユースケース

---

## 配置判断基準

- HTTP処理 → controllers
- ActiveRecordモデル（永続化） → models
- 画面表示 → views
- ビジネスルール（純粋ロジック） → domains
- ユースケースの流れ制御 → features
- DBに対する単純操作（ロジックなし） → resources
- 共通処理 → shared

---

## 禁止事項

- domainsにCRUDロジックを混ぜる
- controllerに業務ロジックを書く
- レイヤー内部を直接呼び出す

# Rails実装のルール定義

モジュラーモノリス + ドメイン駆動設計（DDD）を併用する

## 1. 目的

本ドキュメントはRailsにおける実装ルールを定義する。

アーキテクチャ判断は `architecture.md` と `boundaries.md` に従い、
本書は「Railsコードの書き方・制約」に特化する。

---

## 2. 基本原則

### 2-1. controllersは薄くする

- HTTP入出力のみ担当
- 業務ロジック禁止
- 必ずユースケース層を呼び出す

#### 許可される処理

- パラメータ取得
- 認証・認可の入口処理
- ユースケースの呼び出し
- レスポンス整形

#### 禁止

- 条件分岐による業務判断
- DB操作
- ドメインロジック

---

### 2-2. modelsは永続化専用

- ActiveRecordはデータ層として扱う
- ビジネスロジック禁止
- scope・validation・associationのみ許可

#### 禁止

- 業務ルール
- 計算ロジック
- ドメイン判断

---

### 2-3. domainsは純粋な業務ロジック

- ActiveRecordに依存しない
- 不変条件を保証する
- 副作用を外に出す

#### 特徴

- エンティティ
- 値オブジェクト
- ドメインサービス

---

### 2-4. domainsのuse_caseはアプリケーション制御

- トランザクション境界を持つ
- domainを組み合わせる
- repository経由でデータアクセス

#### 禁止

- UIロジック
- ActiveRecord直接操作（原則）

---

### 2-5. featuresは軽量ユースケース

- 単純な業務フローを扱う
- ActiveRecord利用OK
- 複雑化したらdomainへ移行

---

### 2-6. resourcesはCRUD専用

- 単純なデータ操作のみ
- ビジネス判断を持たない
- マスタ・設定・ログなど

---

## 3. 依存ルール

### 基本方針

依存は一方向のみ（上位 → 下位）

---

### 3-1. controllers

- controllers → domains/[domain_name]/use_cases
- controllers → features/[feature_name]/services
- controllers → resources

#### ルール

- controllerは業務判断を持たない
- HTTP入出力のみに責務を限定する
- domains/[domain_name] / features/[feature_name] / resourcesのどれを呼ぶかの判断のみ行う

---

### 3-2. models

- models（ActiveRecordのモデルを集約） → DB永続化専用

---

### 3-3. domains（中核の業務領域）

#### domain/*

- domains/*/domain → 無依存（完全独立）
- repositories
- domains/*/domain/repositories（interface）はインターフェース定義のみ
- 実装はdomains/*/infrastructure/repositories（implementation）

#### use_cases

- domains/*/use_cases → domains/*/domain
- domains/*/use_cases → domains/*/domain/repositories（interface）

#### infrastructure

- リポジトリの実装を行う
- domains/*/infrastructure/repositories（implementation） → models
- コマンド・クエリ責務分離（CQRS）設計とし、command（書き込み）とquery（読み取り）に分ける

---

### 3-3. features（補完的な業務領域）

- features/*/services → models

#### ルール

- 単純な業務フローのみ扱う
- 複雑化した場合はdomainsへ移行

---

### 3-4. resources（一般的な業務領域）

- resources → models

#### ルール

- 単純なCRUD処理
- ビジネスロジック禁止

---

### 3-5. shared（横断関心）

- shared → 全レイヤーから参照可能

---

### 3-6. 全体制約

#### domainの絶対ルール

- domainはRailsに依存しない
- domainはActiveRecordを知らない
- domainは純粋なビジネスロジックのみ

#### infrastructureルール

- infrastructure（repositories実装）はmodelsに依存する
- コマンド・クエリ責務分離（CQRS）設計とする

---

### 依存方向まとめ

#### 中核の業務領域

```
controller
↓
domains/*/domain/use_cases 
↓
domain（entities / value_objects / services / repositories（interface））
↓
infrastructure/repositories（implementation）
↓
models（ActiveRecord実装）
```

#### 補完的な業務領域

```
controller
↓
features/*/services
↓
models（ActiveRecord実装）
```

#### 一般的な業務領域

```
controller
↓
resources
↓
models（ActiveRecord実装）
```

#### 共通処理

sharedは例外的に全方向参照可能

---

## 4. Rails特有の制約

### ActiveRecordの扱い

- domainsからは直接参照せず、repository経由でのみアクセスする
- featuresやresourcesは直接参照可能
- modelは純粋なデータ表現

---

### repositoryの責務分離（CQRS）

- Query Repository（読み取り専用）
  - データ取得
  - キャッシュ利用可能
  - パフォーマンス最適化OK
  - domainロジック禁止

- Command Repository（書き込み専用）
  - 作成・更新・削除
  - トランザクション管理の対象
  - domainルールの反映

---

### コールバック禁止方針

- callbackに業務ロジックを書かない
- 副作用はユースケースに集約する

---

### Fat Model禁止

- modelにロジックを集約しない
- 複雑化した場合はドメインモデルへ移動

---

## 5. トランザクション管理

- ユースケース層が唯一のトランザクション境界
- featuresでは必要最小限にし、以下に該当したらdomainsへ移行する
  - 条件分岐が増える
  - 状態遷移（ステータス変更ロジック）が含まれる
  - 複数のドメインルールが絡む
  - ルール変更の影響範囲が広い
  - ビジネス判断がコード内に現れ始める
- modelでは管理しない

---

## 6. 例外ルール

### 許可される例

- modelのバリデーション
- scopeによるクエリ
- 軽量なフォーマット処理（表示用途）

---

### 禁止される例

- 金額計算などの業務ロジック
- 状態遷移の判断
- 複雑な条件分岐

---

## 7. 設計判断基準

実装前に必ず判断する：

### 7-1. Q1: 複雑な業務ルールがあるか？

→ domains

### 7-2. Q2: 複雑な業務ルールはなく、処理フロー中心か？

→ features

### 7-3. Q3: 単純なCRUD処理や、外部サービスなどの共通処理か？

→ resource

### 7-4. Q4: 各レイヤーで共通利用するものか？

→ shared

---

## 8. エージェントルール

- 実装前に必ず配置先を決める
- controllerから設計を始めない
- domains または features または resource から設計を始める
- 判断に迷った場合は `boundaries.md` を参照すること

---

## 9. 禁止事項

- controllersへのロジック追加
- model肥大化
- domainsでの直接のActiveRecord使用
- featuresの無制限増殖
- ルールを無視した直書き実装

# テストのルール定義

## 1. 基本方針

### 責務とテストの一致

- テストの責務境界をコード構造と一致させる
- 各レイヤーの責務 ＝ テストの責務
- 「どこで何を保証するか」を明確にする
- 同一ロジックの重複検証は禁止

---

### テストピラミッド

- E2E（web / api）：少量
- Integration（domains / features / resources）：中量
- Unit（domains）：最大（最も厚くする）
- requests（コントローラーのHTTPテスト）やE2Eは「壊れていないことの確認」に留める

---

### ビジネスロジックの責務

ビジネスロジックは性質ごとに責務を分離し、適切なレイヤーに集約する。

#### domains

- ビジネスの不変ルール（ドメイン知識そのもの）を担当する
- 例：計算ロジック、状態遷移の正当性、制約条件
- システムの「正しさの核」を担う

#### features

- ユースケース単位のビジネスフローおよび軽い判断ロジックを担当する
- 例：複数ドメインをまたぐ処理順序、条件分岐による処理選択
- ドメインルールそのものは持たず、オーケストレーションとアプリケーション判断を担う
- ドメインを利用しない範囲のユースケースを担当する

#### resources

- 単純CRUDなどの標準的なリソース操作を担当する
- ビジネス判断ロジックは持たず、処理の流れの確認に留める

#### 配置判断ルール

- 判断や分岐を伴う場合は features に配置する
- 判断を伴わない単純なCRUDは resources に配置する
- 複雑なビジネスルールが含まれる場合は domains に配置する

#### controllers / models

- ビジネスロジックは持たない
- controllers は I/O のみ
- models は永続化とデータ構造の表現のみに限定する

#### 上位レイヤーの責務

- 上位レイヤーは下位レイヤーの正しさに依存する
- ビジネスルールそのものは domains または features に集約する

### ActiveRecordの位置づけ

- models は永続化モデル（ORM）でありドメインではない
- ビジネスロジックは持たない
- データ構造の表現のみに限定する

---

## 2. specのディレクトリ構成

Railsのテストフレームワークとして「RSpec」を利用するが、`/spec`のテストとしては責務ベースでディレクトリを分離し、ドメイン駆動設計およびモジュラーモノリスの境界と一致させる。

### 基本方針

- レイヤー（unit / integration / requests / e2e）で大分類する
- その中で責務（domains / features / resourcesなど）を分割する
- ドメイン単位での分離を最優先する
- テストの配置はコードの責務境界と一致させる

---

### ディレクトリ構成

```
/spec
 ├── /unit（ユニットテスト）
 |    |
 |    ├── /models
 |    |
 |    ├── /domains
 |    |    |
 |    |    └── /domain_name
 |    |         |
 |    |         ├── /domain
 |    |         |    |
 |    |         |    ├── /entities
 |    |         |    |
 |    |         |    ├── /value_objects
 |    |         |    |
 |    |         |    └── /services
 |    |         |
 |    |         └── /use_cases
 |    |
 |    └── /shared
 |
 |
 ├── /integration（インテグレーションテスト）
 |    |
 |    ├── /domains
 |    |    |
 |    |    └── /domain_name
 |    |         |
 |    |         └── /use_cases
 |    | 
 |    ├── /features
 |    |    |
 |    |    └── /[feature_name]
 |    |         |
 |    |         └── /services（サービス層） 
 |    |
 |    | 
 |    └── /resources
 |
 |
 ├── /requests（コントローラーのHTTPのテスト）
 |    |
 |    ├── /web
 |    |
 |    └── /api（将来的にAPIモードを利用する際に使う想定）
 |
 |
 └── /e2e（E2Eテスト）
      |
      ├── /web
      |
      └── /api（将来的にAPIモードを利用する際に使う想定）
```

---

### 設計意図

#### unit

- models / domains / shared を明確に分離する
- domainsについてはドメインロジックの純粋性を保証する層とする
- domains配下はDDD構造そのものを反映し、純粋なビジネスロジックのみを対象とする

#### integration

- 複数コンポーネントの結合を検証する層
- ドメイン単体などではなく、ユースケースなどの「流れ」を保証する
- featuresは業務機能単位の統合境界として扱う
- HTTPは使用しない（Request Specは禁止）
- サービス・ユースケースを直接呼び出して検証する

#### requests

- HTTP境界の検証に限定する
- Rails controllerの責務確認を目的とする
- ビジネスロジックは一切持たず、入出力の正当性のみを保証する

#### e2e

- ユーザー視点の最終保証レイヤー
- UI / APIを含めた全体フローを確認する
- カバレッジよりも主要シナリオの成立を重視し、最小限に保つ

---

### 命名ルール

- domain_name / feature_name はアプリケーションの業務ドメイン用語を使用する
- 実装クラス名ではなく「業務単位」でディレクトリを切る
- ディレクトリ構造とモジュール境界は一致させることを前提とする

### 補足ルール

- 同一責務のテストは必ず1箇所に集約する
- unit / integration / e2e 間で同じ検証を重複させない
- domains配下が最も安定した設計境界となることを前提とする

---

## 3. レイヤー別テスト定義

### domains（中核の業務領域のレイヤー）

**方針**: 最も重要なテスト層。全ビジネスルールを保証

**ルール**
- ドメインモデルはUnitテスト（純粋ロジック）
- ドメイン内のユースケース（純粋なドメインサービス）はIntegrationテスト
- ドメインオブジェクト間の連携のみを対象とする
- 外部I/O（DB・API）を含まない範囲に限定する
- Rails依存禁止
- 外部依存禁止（純粋オブジェクト）

**必須**
- 境界値テスト
- 異常系テスト
- 不変条件の検証
- 1テスト1ルール

**禁止**
- ActiveRecord使用
- FactoryBot使用

---

### features（補完的な業務領域のレイヤー）

**方針**: ユースケースの流れを検証、ドメインを使うような複雑性はない機能の動作確認

**ルール**
- Integrationテスト
- DB使用可
- サービス単位で検証

**必須**
- 1ユースケースにつき
  - 正常系1つ
  - 主要な失敗系のみ

**禁止**
- 複雑な検証
- 分岐網羅
- 過剰なモック

---

### resources（一般的な業務領域のレイヤー）

**方針**: 単純なCRUD処理などを検証

**ルール**
- APIは Request Spec（統合テスト）、Viewは System Spec（E2Eテスト） を使用する
- 1つのリソースにつき「代表的な正常系フロー」を中心に検証する
- CRUDは個別に網羅するのではなく、「一連の操作の流れの中で確認する」
- 認証・認可・決済などの横断的関心を含めて検証する
- テストはクライアント（API）またはユーザー（View）視点で記述する
- ビジネス判断を持たないことを前提とする
- 判断が発生した時点で features へ移動する

**必須**
- 登録 → 認証 → 操作 などの主要フローが成立すること
- 認証・認可が正しく機能すること（未認証・権限違いの最低限の確認）
- リソースの作成・更新・削除のうち、少なくとも1つはフロー内で通すこと
- 正常系のエンドツーエンド動作が通ること

**禁止**
- バリデーションの網羅的テストを書くこと
- 分岐ロジック（条件ごとの挙動）を細かく検証すること
- すべてのCRUDパターンをE2Eで個別にテストすること
- 失敗ケースを過剰に書くこと（詳細は下位レイヤーで担保）
- テストケースを増やしすぎること（フロー単位で最小限に抑える）

---

### models（永続化レイヤー）

**方針**: DB構造と永続化のみ保証

**ルール**
- Model Specを使用
- DB前提

**検証対象**
- validation
- association
- scope
- simple callback（最小限）

**必須**
- DBとの整合性
- クエリ結果の正しさ

**禁止**
- ビジネスロジック
- 複雑ロジック
- ドメイン知識

---

### controllers

**方針**: I/Oのみ検証

**ルール**
- Request Specを使用
- HTTPステータス
- JSON構造
- 認証・認可

**必須**
- レスポンススキーマのみ検証

**禁止**
- ビジネスロジックの結果検証
- DB状態の詳細検証

---

### views（UI）

**方針**: ユーザー体験のみ確認

**ルール**
- System Spec（E2E）を使用
- 主要フローのみ

**必須**
- 文言完全一致に依存しない
- HTML構造に依存しすぎない

---

## 4. 横断ルール

### ４.1 責務ごとのテスト配置

| 検証対象 | 配置場所 |
|----------|----------|
| 複雑なビジネスルール | domains |
| ビジネスフロー（ユースケース） | features |
| 単純なCRUD・リソース操作 | resources |
| DB構造・バリデーション | models |
| API入出力（HTTP境界） | controllers（request spec） |
| UI体験（ユーザー操作） | views（system spec） |

- 同一内容の重複テストは禁止

---

### ４.2 モック使用ルール

**許可**
- 外部API
- 時刻
- UUID
- メール送信

**禁止**
- domainオブジェクト
- ActiveRecord
- 自作クラス同士

**原則**
- モックは外部境界のみに限定

---

### ４.3 テストデータ（FactoryBot）

| レイヤー | 使用可否 |
|----------|----------|
| domains | 原則禁止（例外的に可） |
| features | 可 |
| models | 可 |
| resources | 可 |
| controllers | 可 |

**ルール**
- 最小構成で生成
- traitで意図明示
- letのネスト禁止
- domainsでは可能な限りPORO（Plain Old Ruby Object）でテストする

---

### ４.4 トランザクション

- 各テストは独立
- テスト間依存禁止
- DBは毎回ロールバック

---

### ４.5 命名ルール

- 業務用語で記述
- 条件と結果を明確にする

```ruby
describe "create order" do
  context "when stock is enough" do
    it "creates order"
  end

  context "when stock is insufficient" do
    it "raises error"
  end
end

```

---

## ５. TDD・推奨フロー

### TDDルール

- Red → Green → Refactor
- テストなし実装禁止

### 推奨フロー

- domain → use_case → controller
- domainから開始する
- controllerから始めない

## 6. アンチパターンと対策

| アンチパターン | 対策 |
|----------|----------|
| features肥大化 | domainへ移動 |
| controllerにロジック | requestを薄く |
| domainが薄い | ロジックを集約 |
| fat model | domainへ移動 |
| FactoryBot乱用 | trait整理 |

---

## 7. 追加推奨・レビュー観点

### 推奨

- カバレッジよりも重要なユースケース・分岐の網羅性を重視する
- テストは「仕様として意味があるか」を基準に設計する（カバレッジは補助指標）

### レビュー観点

- 責務とテスト対象が一致しているか
- domainに寄せるべきロジックが適切に切り出されているか
- テストが冗長・重複していないか
- ActiveRecordに過剰なビジネスロジックが混入していないか
- 重要な分岐・例外系が落ちていないか

## まとめ

- 複雑なビジネスロジックは可能な限りdomainに集約する
- modelsは永続化を主責務とし、必要最小限のロジックのみ持つ
- テストは責務ごとに分離する
- 上位は薄く、下位は厚くする
- 配置に迷った場合は「ビジネス判断があるか」で判断する

# Rails専用のルール定義

## 概要

このディレクトリ（src）はRails実装の「実行領域」であり、
設計判断はすべて docs/rules 側に集約されている。

src内では設計判断を行わず、既存ルールを適用するのみとする。

---

## Railsの設計思想（重要）

本プロジェクトはRailsの思想である 
**「設計より規約（Convention over Configuration）」を強く採用する。**

そのため以下を前提とする：

- 明示的な設計よりも、規約（Rails標準・docs/rules）を優先する
- 個別判断やカスタム設計は原則として禁止する
- 「設計を考えること」自体をsrcでは行わない

---

## 規約と設計の関係

本プロジェクトにおける「規約」とは以下を指す：

- Railsのフレームワーク規約
- `docs/rules/*` に定義されたプロジェクト規約

これらは実質的に**設計そのものの代替物**であり、
srcはそれを機械的に適用するだけの層である。

---

## ルール参照構造

すべての実装は以下のルールに従う：

- `docs/rules/architecture.md`（設計思想）
- `docs/rules/boundaries.md`（配置判断）
- `docs/rules/rails.md`（Rails実装ルール）
- `docs/rules/database.md`（データ制約）
- `docs/rules/testing.md`（テスト方針）

---

## src配下の責務

srcは「実装のみを行う領域」であり、
以下の責務に限定される：

- MVC構造の具体的実装
- モジュラーモノリス構造のコード配置
- `docs/rules/rails.md` に従った実装

---

## 実装ルール（重要）

srcでは以下を行ってはならない：

- ルールの解釈や再定義
- 設計判断
- 技術選定の追加判断

実装は常に docs/rules を唯一の判断基準として適用すること。

---

## このディレクトリの役割

- Railsコードの実装専用領域
- MVC構造の具体的なコード表現
- モジュラーモノリス構造の物理実装

---

## 禁止事項

- src配下に設計判断を書くこと
- domains / features / resourcesの定義を再説明すること
- database設計方針を記述すること
- テスト戦略を記述すること
- docs側のルールを上書きすること

---

## エージェントの振る舞い

- 判断はすべて docs/rules に従う
- srcは「適用のみ」を行う
- 迷った場合は `docs/rules/boundaries.md` を最優先で参照する
- 「どう設計するか」は考えない
- 「どの規約に従うか」だけを選択する
- 規約が曖昧な場合のみ docs/rules 側に遷移する

---

## 補足（重要）

srcは「設計を実装する場所」ではなく 
**「規約をコードに写像する機械である」**

---

## 実装後の必須チェック（重要）

コード修正・追加が一段落した場合、エージェントは必ず以下のコマンドを順番に実行し、
警告・エラーが存在しない状態を維持すること。

### コマンド一覧

#### 1. フォーマット修正（レイアウトのみ自動修正）

`docker compose run --rm app bundle exec rubocop -A --only Layout`

---

#### 2. 静的コード解析（Rubocop）

`docker compose run --rm app bundle exec rubocop`

---

#### 3. ビューLint（ビュー変更時のみ）

※ app/views に変更があった場合のみ実行

`docker compose run --rm app bundle exec erb_lint app/views`

---

#### 4. 脆弱性チェック（Brakeman）

`docker compose run --rm app bundle exec brakeman --no-pager`

---

#### 5. テスト実行（RSpec）

`docker compose exec -T app bundle exec rspec`

---

### 実行ルール

- 上記は「実装完了後に必ず順番に実行する」
- エラー・警告がある状態で完了としてはならない
- フォーマット（Layout）のみ自動修正を許可する（rubocop -A --only Layout）
- 上記以外の rubocop の自動修正（-A）は使用してはならない
- rubocop の指摘は自動修正に依存せず、必ずコード側で修正する
- テストが失敗している状態で終了してはならない
- すべてのチェックが通過するまで修正と再実行を繰り返す

---

### 位置づけ

これらのチェックは「設計判断」ではなく、
**規約の適用結果を検証する工程**である。

したがって src の責務に含まれる。

$ mkdir -p .github/workflows && touch .github/workflows/ci.yml

name: CI

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  # 変更ファイル判定（全体トリガー）
  changes:
    runs-on: ubuntu-latest

    outputs:
      app: ${{ steps.filter.outputs.app }}

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: 差分チェック
        uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            app:
              - 'src/**/*.rb'
              - 'src/**/*.erb'
              - 'src/Gemfile*'

  # 静的コード解析・脆弱性チェック
  lint:
    needs: changes
    if: needs.changes.outputs.app == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: 環境変数ファイルをリネーム
        run: cp ./.env.example ./.env

      - name: Dockerコンテナのビルド
        run: docker compose build

      # 静的コード解析
      - name: Rubocop
        run: docker compose run --rm app bundle exec rubocop

      # ビュー用の静的コード解析
      - name: ERB Lint
        run: docker compose run --rm app bundle exec erb_lint app/views

      # Railsの脆弱性チェック
      - name: Brakeman
        run: docker compose run --rm app bundle exec brakeman --no-pager

  # テスト
  test:
    needs: changes
    if: needs.changes.outputs.app == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: 環境変数ファイルをリネーム
        run: cp ./.env.example ./.env

      - name: Dockerコンテナのビルド
        run: docker compose build

      - name: Dockerコンテナの起動
        run: docker compose up -d

      - name: DB接続待機処理
        run: docker compose exec app bash -c "until pg_isready -h db -U ${DB_USER}; do sleep 1; done"

      - name: DB作成とマイグレーションの実行
        run: docker compose run --rm app bundle exec rails db:prepare

      - name: テストの実行（RSpec）
        run: docker compose exec -T app bundle exec rspec

$ git add -A
$ git commit -m "add harness"

# 追加機能の仕様

## 名言ドメインの仕様

### 1. エンティティ「Quote」

名言ドメインのエンティティ

属性：
- id：Quoteの識別子（主キー / bigint）
- quote_text：値オブジェクト「QuoteText」
  - 値オブジェクトはバリデーションの責務を持つ

---
### 2. 値オブジェクト「QuoteText」

名言の本文を表す値オブジェクト

制約：
- 使用可能文字：
- 全角ひらがな
- 全角カタカナ
- 漢字
- 長音「ー」
- 「。」（句点）
- 「、」（読点）
- 使用不可文字：
- 英数字
- スペース
- 記号（括弧・!・?など含む）
- 正規表現でバリデーションする

正規表現の例：
```
/\A[ぁ-んァ-ヶ一-龥ー。、]+\z/
```
---

### 3. ドメインサービス「QuoteSelector」

「今日の一言」を決定するドメインサービス

役割：
- 日付と名言マスタから1件のQuoteを選定する

選定ロジック：
- 対象日付の「年内日数（day_of_year）」を取得
- quotes数で割った余りを算出
- そのindexのQuoteを返す

例：
```
index = date.yday % quotes.count
```

不変条件：
- 同じ日付 → 必ず同じ結果
- quotesが同じなら結果は完全に決定論的
- うるう年は考慮しない（ydayをそのまま使用）

例外：
- quotesが0件の場合はエラーとして例外を返す


### 4. ユースケースの処理フロー

1. quote_historiesに今日の日付があるか確認
2. あればそれを返す
3. なければ：
  - QuoteSelectorで選定
  - quote_historiesに保存
  - 返却

---

## データベースの仕様
### 1. 名言マスタテーブル「quotes」

| カラム | 型 | 説明 |
| --- | --- | --- | 
| id | bigint | PK |
| text | string | 名言本文 |
| created_at | datetime | |
| updated_at | datetime | |


### 2. 名言履歴テーブル「quote_histories」

| カラム | 型 | 説明 |
| --- | --- | --- | 
| id | bigint | PK |
| date | date | 対象日（UTC日付）、ユニークキーとする |
| quote_id | bigint | 名言マスタのid |
| created_at | datetime | |
| updated_at | datetime | |

---

### 3. 名言マスタの登録値

| id | 名言 |
| --- | --- |
| 1 | 必死に生きる生涯は光を放つ |
| 2 | 我事において後悔せず |
| 3 | 天は人の上に人を造らず人の下に人を造らず |
| 4 | 成功は失敗の積み重ね |
| 5 | 小さなことの積み重ねが遠くへ行く道 |
| 6 | いい作品はいい人生から生まれる |
| 7 | 映画は自分の手でつくるもの |
| 8 | 遠回りは無駄ではない |
| 9 | 人を相手にせず天を相手にせよ |
| 10 | 人は成功するために努力する |

---

## UIの仕様

- トップページ中央に1件表示
- 表示例：`本日の一言：〇〇〇〇〇`
- レスポンシブデザインであること
- CSSにはTailwindCSSを利用する
- 全体的なデザインは落ち着きがあっていい感じにしたい

「今日の一言」をトップページの中央にいい感じに表示させるだけの簡単なアプリを作りたいです。
現在の仕様は以下になるので、これをまとめた上で、確認点があれば質問して下さい。

$ docker compose exec app rails db:prepare
$ docker compose down
$ docker compose up -d

$ docker compose down

$ docker compose up -d db

$ docker build --no-cache -t rails-aidd-app:1.0.0 -f src/Dockerfile src

$ docker run -d \
-p 80:80 \
-e RAILS_MASTER_KEY={src/config/master.keyの中身の値} \
-e DB_HOST=host.docker.internal \
-e DB_USER=root \
-e DB_PASSWORD=root \
rails-aidd-app:1.0.0