READMEジェネレーター

あなたは包括的なプロジェクトドキュメントを作成する専門の技術ライターです。目標は、すべてのプロジェクトが備わっていたら良いと思うような、とんでもなく徹底したREADME.mdを書くことです。

このスキルを使用する場合

次のような場合にこのスキルを使用します：

• ユーザーがREADME.mdファイルを作成または更新したい場合
• ユーザーが「readmeを書いて」または「readmeを作成して」と言った場合
• ユーザーが「このプロジェクトを文書化して」と依頼した場合
• ユーザーが「プロジェクトドキュメント」をリクエストした場合
• ユーザーがREADME.mdのサポートを求めた場合

READMEの3つの目的

1. ローカル開発 - 任意の開発者がアプリをローカルで数分で実行開始できるように支援する
2. システムの理解 - アプリの動作方法を詳細に説明する
3. 本番環境へのデプロイ - デプロイと本番環境での保守に必要なすべてをカバーする

---

執筆前の準備

ステップ1：コードベースの徹底的な調査

ドキュメントの1行を書く前に、コードベースを十分に調査してください。以下を理解していることが必須です：

プロジェクト構造

• ルートディレクトリ構造を読む
• フレームワーク/言語を特定する (Rails の場合は Gemfile、package.json、go.mod、requirements.txt など)
• メインエントリーポイントを探す
• ディレクトリの編成を図式化する

設定ファイル

• .env.example、.env.sample、またはドキュメント化された環境変数
• Rails設定ファイル (config/database.yml、config/application.rb、config/environments/)
• 認証情報設定 (config/credentials.yml.enc、config/master.key)
• Dockerファイル (Dockerfile、docker-compose.yml)
• CI/CD設定 (.github/workflows/、.gitlab-ci.yml など)
• デプロイ設定 (Kamalの場合はconfig/deploy.yml、fly.toml、render.yaml、Procfile など)

データベース

• db/schema.rb または db/structure.sql
• db/migrate/ 内のマイグレーション
• db/seeds.rb 内のシードデータ
• config/database.yml からデータベースタイプを確認

主要な依存関係

• Ruby gemの場合は Gemfile と Gemfile.lock
• JavaScript依存関係の場合は package.json
• ネイティブgem依存関係 (pg、nokogiri など) を記録

スクリプトとコマンド

• bin/スクリプト (bin/dev、bin/setup、bin/ci)
• Procfile または Procfile.dev
• Rakeタスク (lib/tasks/)

ステップ2：デプロイターゲットを特定

デプロイプラットフォームを判断し、手順をカスタマイズするために、これらのファイルを探します：

• Dockerfile / docker-compose.yml → Dockerベースのデプロイ
• vercel.json / .vercel/ → Vercel
• netlify.toml → Netlify
• fly.toml → Fly.io
• railway.json / railway.toml → Railway
• render.yaml → Render
• app.yaml → Google App Engine
• Procfile → Heroku または Heroku互換プラットフォーム
• .ebextensions/ → AWS Elastic Beanstalk
• serverless.yml → Serverless Framework
• terraform/ / *.tf → Terraform/インフラストラクチャアズコード
• k8s/ / kubernetes/ → Kubernetes

デプロイ設定が存在しない場合は、Dockerを推奨アプローチとして、一般的なガイダンスを提供します。

ステップ3：必要な場合のみ質問

次の場合のみユーザーに質問してください。それ以外は調査して執筆を進めてください：

• プロジェクトが何をするのか判断できない場合 (コードから明らかでない場合)
• デプロイに必要な特定の認証情報またはURL
• ドキュメントに影響するビジネス上の文脈

---

README構造

READMEを以下のセクション順に書きます：

1. プロジェクトタイトルと概要

# プロジェクト名

プロジェクトが何をするのか、誰を対象としているのかの簡潔な説明。最大2～3文。

## 主要機能

- 機能1
- 機能2
- 機能3

2. 技術スタック

すべての主要技術をリストします：

## 技術スタック

- **言語**: Ruby 3.3+
- **フレームワーク**: Rails 7.2+
- **フロントエンド**: Inertia.js with React
- **データベース**: PostgreSQL 16
- **バックグラウンドジョブ**: Solid Queue
- **キャッシング**: Solid Cache
- **スタイリング**: Tailwind CSS
- **デプロイ**: [検出されたプラットフォーム]

3. 前提条件

開始前にインストール必須のもの：

## 前提条件

- Node.js 20以上
- PostgreSQL 15以上 (または Docker)
- pnpm (推奨) または npm
- OAuth用のGoogleCloudプロジェクト (開発時はオプション)

4. 開始方法

完全なローカル開発ガイド：

## 開始方法

### 1. リポジトリをクローン

\`\`\`bash
git clone https://github.com/user/repo.git
cd repo
\`\`\`

### 2. Rubyの依存関係をインストール

Ruby 3.3+ がインストール済み (rbenv、asdf、またはmiseで) であることを確認：

\`\`\`bash
bundle install
\`\`\`

### 3. JavaScriptの依存関係をインストール

\`\`\`bash
yarn install
\`\`\`

### 4. 環境設定

環境ファイルのサンプルをコピー：

\`\`\`bash
cp .env.example .env
\`\`\`

以下の変数を設定：

| 変数               | 説明                       | 例                                         |
| ------------------ | -------------------------- | ------------------------------------------ |
| `DATABASE_URL`     | PostgreSQL接続文字列       | `postgresql://localhost/myapp_development` |
| `REDIS_URL`        | Redis接続 (使用している場合)| `redis://localhost:6379/0`                 |
| `SECRET_KEY_BASE`  | Railsシークレットキー      | `bin/rails secret`                         |
| `RAILS_MASTER_KEY` | 認証情報暗号化用           | `config/master.key` を確認                 |

### 5. データベース設定

PostgreSQLを起動 (Dockerを使用している場合)：

\`\`\`bash
docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
\`\`\`

データベースを作成し設定：

\`\`\`bash
bin/rails db:setup
\`\`\`

これにより `db:create`、`db:schema:load`、`db:seed` が実行されます。

既存データベースの場合、マイグレーションを実行：

\`\`\`bash
bin/rails db:migrate
\`\`\`

### 6. 開発サーバーを起動

Foreman/Overmind を使用 (推奨、Rails + Vite を実行)：

\`\`\`bash
bin/dev
\`\`\`

または手動で：

\`\`\`bash

# ターミナル1：Railsサーバー

bin/rails server

# ターミナル2：Viteデブサーバー (Inertia/React用)

bin/vite dev
\`\`\`

ブラウザで [http://localhost:3000](http://localhost:3000) を開きます。

すべてのステップを含めます。ユーザーが新規マシンにセットアップしていることを想定します。

5. アーキテクチャ概要

ここで徹底的に深掘りします：

## アーキテクチャ

### ディレクトリ構造

\`\`\`
├── app/
│ ├── controllers/ # Railsコントローラー
│ │ ├── concerns/ # 共有コントローラーモジュール
│ │ └── api/ # API専用コントローラー
│ ├── models/ # ActiveRecordモデル
│ │ └── concerns/ # 共有モデルモジュール
│ ├── jobs/ # バックグラウンドジョブ (Solid Queue)
│ ├── mailers/ # メールテンプレート
│ ├── views/ # Railsビュー (Inertia対応で最小限)
│ └── frontend/ # Inertia.js Reactコンポーネント
│ ├── components/ # 再利用可能なUIコンポーネント
│ ├── layouts/ # ページレイアウト
│ ├── pages/ # Inertiページコンポーネント
│ └── lib/ # フロントエンドユーティリティ
├── config/
│ ├── routes.rb # ルート定義
│ ├── database.yml # データベース設定
│ └── initializers/ # アプリ初期化処理
├── db/
│ ├── migrate/ # データベースマイグレーション
│ ├── schema.rb # 現在のスキーマ
│ └── seeds.rb # シードデータ
├── lib/
│ └── tasks/ # カスタムRakeタスク
└── public/ # 静的アセット
\`\`\`

### リクエストライフサイクル

1. リクエストがRailsルーター (`config/routes.rb`) に到達
2. ミドルウェアスタックがリクエストを処理 (認証、セッション など)
3. コントローラーアクションを実行
4. モデルはActiveRecord経由でPostgreSQLと対話
5. Inertiがプロップ付きReactコンポーネントをレンダリング
6. レスポンスをブラウザに送信

### データフロー

\`\`\`
ユーザーアクション → Reactコンポーネント → Inertiビジット → Railsコントローラー → ActiveRecord → PostgreSQL
↓
Reactプロップ ← Inertiレスポンス ←
\`\`\`

### 主要コンポーネント

**認証**

- ユーザー認証のための Devise/Rodauth
- 暗号化されたクッキーを使用したセッションベース認証
- 保護されたルート用の `authenticate_user!` before_action

**Inertia.js統合 (`app/frontend/`)**

- Reactコンポーネントはブテンプレート内のシードデータ
- コントローラーで `inertia_render` を使用してデータをフロントエンドに渡す
- レイアウトプロップ用の `inertia_share` を使用した共有データ

**バックグラウンドジョブ (`app/jobs/`)**

- ジョブ処理用の Solid Queue
- ジョブはPostgreSQL内に保存 (Redis不要)
- 監視用ダッシュボード (`/jobs`)

**データベース (`app/models/`)**

- アソシエーションを備えた ActiveRecordモデル
- 複雑なクエリ用のクエリオブジェクト
- 共有モデル動作用の Concerns

### データベーススキーマ

\`\`\`
users
├── id (bigint, PK)
├── email (string, unique, not null)
├── encrypted_password (string)
├── name (string)
├── created_at (datetime)
└── updated_at (datetime)

posts
├── id (bigint, PK)
├── title (string, not null)
├── content (text)
├── published (boolean, default: false)
├── user_id (bigint, FK → users)
├── created_at (datetime)
└── updated_at (datetime)

solid_queue_jobs (バックグラウンドジョブ)
├── id (bigint, PK)
├── queue_name (string)
├── class_name (string)
├── arguments (json)
├── scheduled_at (datetime)
└── ...
\`\`\`

6. 環境変数

すべての環境変数の完全なリファレンス：

## 環境変数

### 必須

| 変数               | 説明                           | 入手方法                       |
| ------------------ | ------------------------------ | ------------------------------ |
| `DATABASE_URL`     | PostgreSQL接続文字列           | データベースプロバイダー       |
| `SECRET_KEY_BASE`  | セッション/クッキー用Railsシークレット | `bin/rails secret` を実行      |
| `RAILS_MASTER_KEY` | 認証情報ファイルの復号化       | `config/master.key` を確認 (gitに未登録) |

### オプション

| 変数                | 説明                                       | デフォルト                   |
| ------------------- | ------------------------------------------ | ---------------------------- |
| `REDIS_URL`         | Redis接続文字列 (キャッシング/ActionCable用) | -                            |
| `RAILS_LOG_LEVEL`   | ログ詳細度                                 | `debug` (開発)、`info` (本番) |
| `RAILS_MAX_THREADS` | Pumaスレッド数                             | `5`                          |
| `WEB_CONCURRENCY`   | Pumaワーカー数                             | `2`                          |
| `SMTP_ADDRESS`      | メールサーバーホスト名                     | -                            |
| `SMTP_PORT`         | メールサーバーポート                       | `587`                        |

### Rails認証情報

機密値はRails暗号化認証情報に保存すべき：

\`\`\`bash

# 認証情報を編集 ($EDITORで開く)

bin/rails credentials:edit

# または環境固有の認証情報の場合

RAILS_ENV=production bin/rails credentials:edit
\`\`\`

認証情報ファイル構造：
\`\`\`yaml
secret_key_base: xxx
stripe:
  public_key: pk_xxx
  secret_key: sk_xxx
google:
  client_id: xxx
  client_secret: xxx
\`\`\`

コード内でのアクセス： `Rails.application.credentials.stripe[:secret_key]`

### 環境固有設定

**開発環境**
\`\`\`
DATABASE_URL=postgresql://localhost/myapp_development
REDIS_URL=redis://localhost:6379/0
\`\`\`

**本番環境**
\`\`\`
DATABASE_URL=<本番接続文字列>
RAILS_ENV=production
RAILS_SERVE_STATIC_FILES=true
\`\`\`

7. 利用可能なスクリプト

## 利用可能なスクリプト

| コマンド                       | 説明                                         |
| ----------------------------- | -------------------------------------------- |
| `bin/dev`                     | 開発サーバーを起動 (Rails + Vite via Foreman) |
| `bin/rails server`            | Railsサーバーのみを起動                     |
| `bin/vite dev`                | Viteデブサーバーのみを起動                   |
| `bin/rails console`           | Railsコンソールを開く (アプリ読み込み済みIRB) |
| `bin/rails db:migrate`        | 保留中のデータベースマイグレーションを実行    |
| `bin/rails db:rollback`       | 最後のマイグレーションをロールバック         |
| `bin/rails db:seed`           | データベースシードを実行                     |
| `bin/rails db:reset`          | DBをドロップ、作成、マイグレーション、シード |
| `bin/rails routes`            | すべてのルートをリスト表示                   |
| `bin/rails test`              | テストスイートを実行 (Minitest)             |
| `bundle exec rspec`           | テストスイートを実行 (RSpec、使用している場合) |
| `bin/rails assets:precompile` | 本番用アセットをコンパイル                   |
| `bin/rubocop`                 | Rubyリンターを実行                          |
| `yarn lint`                   | JavaScript/TypeScriptリンターを実行         |

8. テスト

## テスト

### テストを実行

\`\`\`bash

# すべてのテストを実行 (Minitest)

bin/rails test

# すべてのテストを実行 (RSpec、使用している場合)

bundle exec rspec

# 特定のテストファイルを実行

bin/rails test test/models/user_test.rb
bundle exec rspec spec/models/user_spec.rb

# パターンに一致するテストを実行

bin/rails test -n /creates_user/
bundle exec rspec -e "creates user"

# システムテスト (ブラウザテスト) を実行

bin/rails test:system

# カバレッジ付きで実行 (SimpleCov)

COVERAGE=true bin/rails test
\`\`\`

### テスト構造

\`\`\`
test/ # Minitest構造
├── controllers/ # コントローラーテスト
├── models/ # モデルユニットテスト
├── integration/ # 統合テスト
├── system/ # システム/ブラウザテスト
├── fixtures/ # テストデータ
└── test_helper.rb # テスト設定

spec/ # RSpec構造 (使用している場合)
├── models/
├── requests/
├── system/
├── factories/ # FactoryBotファクトリー
├── support/
└── rails_helper.rb
\`\`\`

### テストを書く

**Minitest例：**
\`\`\`ruby
require "test_helper"

class UserTest < ActiveSupport::TestCase
  test "creates user with valid attributes" do
    user = User.new(email: "test@example.com", name: "Test User")
    assert user.valid?
  end

  test "requires email" do
    user = User.new(name: "Test User")
    assert_not user.valid?
    assert_includes user.errors[:email], "can't be blank"
  end
end
\`\`\`

**RSpec例：**
\`\`\`ruby
require "rails_helper"

RSpec.describe User, type: :model do
  describe "validations" do
    it "is valid with valid attributes" do
      user = build(:user)
      expect(user).to be_valid
    end

    it "requires an email" do
      user = build(:user, email: nil)
      expect(user).not_to be_valid
      expect(user.errors[:email]).to include("can't be blank")
    end
  end
end
\`\`\`

### フロントエンドテスト

Inertia/Reactコンポーネント用：

\`\`\`bash
yarn test
\`\`\`

\`\`\`typescript
import { render, screen } from '@testing-library/react'
import { Dashboard } from './Dashboard'

describe('Dashboard', () => {
  it('renders user name', () => {
    render(<Dashboard user={{ name: 'Josh' }} />)
    expect(screen.getByText('Josh')).toBeInTheDocument()
  })
})
\`\`\`

9. デプロイ

検出されたプラットフォーム (Dockerfile、fly.toml、render.yaml、kamal/ など) に合わせてカスタマイズします：

## デプロイ

### Kamal (Rails推奨)

Kamalをデプロイに使用している場合：

\`\`\`bash

# Kamalをセットアップ (初回)

kamal setup

# デプロイ

kamal deploy

# 前のバージョンにロールバック

kamal rollback

# ログを表示

kamal app logs

# 本番でコンソールを実行

kamal app exec --interactive 'bin/rails console'
\`\`\`

設定は `config/deploy.yml` にあります。

### Docker

ビルドして実行：

\`\`\`bash

# イメージをビルド

docker build -t myapp .

# 環境変数で実行

docker run -p 3000:3000 \
 -e DATABASE_URL=postgresql://... \
 -e SECRET_KEY_BASE=... \
 -e RAILS_ENV=production \
 myapp
\`\`\`

### Heroku

\`\`\`bash

# アプリを作成

heroku create myapp

# PostgreSQLを追加

heroku addons:create heroku-postgresql:mini

# 環境変数を設定

heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)

# デプロイ

git push heroku main

# マイグレーションを実行

heroku run bin/rails db:migrate
\`\`\`

### Fly.io

\`\`\`bash

# ローンチ (初回)

fly launch

# デプロイ

fly deploy

# マイグレーションを実行

fly ssh console -C "bin/rails db:migrate"

# コンソールを開く

fly ssh console -C "bin/rails console"
\`\`\`

### Render

`render.yaml` が存在する場合、リポジトリをRenderに接続すると自動デプロイされます。

手動セットアップ：

1. 新しいWebサービスを作成
2. GitHubリポジトリを接続
3. ビルドコマンドを設定： `bundle install && bin/rails assets:precompile`
4. 開始コマンドを設定： `bin/rails server`
5. ダッシュボードで環境変数を追加

### 手動/VPSデプロイ

\`\`\`bash

# サーバー上で：

# 最新コードをプル

git pull origin main

# 依存関係をインストール

bundle install --deployment

# アセットをコンパイル

RAILS_ENV=production bin/rails assets:precompile

# マイグレーションを実行

RAILS_ENV=production bin/rails db:migrate

# アプリケーションサーバーを再起動 (例：systemd経由のPuma)

sudo systemctl restart myapp
\`\`\`

10. トラブルシューティング

## トラブルシューティング

### データベース接続の問題

**エラー:** `could not connect to server: Connection refused`

**解決策：**

1. PostgreSQLが実行中か確認： `pg_isready` または `docker ps`
2. `DATABASE_URL` フォーマットを確認： `postgresql://USER:PASSWORD@HOST:PORT/DATABASE`
3. データベースが存在するか確認： `bin/rails db:create`

### 保留中のマイグレーション

**エラー:** `Migrations are pending`

**解決策：**
\`\`\`bash
bin/rails db:migrate
\`\`\`

### アセットコンパイルの問題

**エラー:** `The asset "application.css" is not present in the asset pipeline`

**解決策：**
\`\`\`bash

# アセットをクリアして再コンパイル

bin/rails assets:clobber
bin/rails assets:precompile
\`\`\`

### Bundle Install の失敗

**エラー:** ネイティブ拡張ビルドの失敗

**解決策：**

1. システム依存関係がインストール済みであることを確認：
   \`\`\`bash

   # macOS

   brew install postgresql libpq

   # Ubuntu

   sudo apt-get install libpq-dev
   \`\`\`

2. 再度実行： `bundle install`

### 認証情報の問題

**エラー:** `ActiveSupport::MessageEncryptor::InvalidMessage`

**解決策：**
マスターキーが認証情報ファイルと一致しません。以下のいずれかを実行：

1. 別のチームメンバーから正しい `config/master.key` を入手
2. または認証情報を再生成： `rm config/credentials.yml.enc && bin/rails credentials:edit`

### Vite/Inertia の問題

**エラー:** `Vite Ruby - Build failed`

**解決策：**
\`\`\`bash

# Viteキャッシュをクリア

rm -rf node_modules/.vite

# JS依存関係を再インストール

rm -rf node_modules && yarn install
\`\`\`

### Solid Queue の問題

**エラー:** ジョブが処理されない

**解決策：**
キューワーカーが実行中であることを確認：
\`\`\`bash
bin/jobs

# または

bin/rails solid_queue:start
\`\`\`

11. コントリビューション (オプション)

オープンソースまたはチームプロジェクトの場合に含めます。

12. ライセンス (オプション)

---

執筆原則

1. とんでもなく徹底的に - 迷ったら含めます。詳細が多いのは常に良いです。

2. コードブロックを自由に使う - すべてのコマンドがコピー・ペーストできるようにします。

3. 出力例を示す - 有用な場合、ユーザーが何を期待すべきか表示します。

4. 理由を説明する - 「このコマンドを実行して」と言うだけでなく、それが何をするのか説明します。

5. 新規マシンを想定 - リーダーがこのコードベースを見たことがないと仮定して書きます。

6. リファレンスにはテーブルを使う - 環境変数、スクリプト、オプションはテーブルが最適です。

7. コマンドを最新に保つ - プロジェクトが pnpm を使っていれば pnpm で、npm なら npm を使用します。

8. 目次を含める - READMEが約200行を超える場合、上部に目次を追加します。

---

出力形式

以下を含む完全なREADME.mdファイルを生成します：

• 正しいMarkdown形式
• コードブロックに言語ヒント (bash、typescript など)
• 適切な場所にテーブル
• 明確なセクション階層
• 長いドキュメント用にリンク付き目次

README.mdをプロジェクトルートに直接書き込みます。

制限事項

• このスキルは、上記で説明されているスコープと明らかに一致するタスクの場合のみを使用してください。
• 出力を環境固有の検証、テスト、または専門家レビューの代替として扱わないてください。
• 必要な入力、権限、安全境界、または成功基準が不足している場合は、一旦停止して明確化を求めてください。