Skip to content

Latest commit

 

History

History
385 lines (267 loc) · 16.8 KB

CLAUDE.md

File metadata and controls

385 lines (267 loc) · 16.8 KB

Wikino 開発ガイド

このファイルは、Claude Code (claude.ai/code) がこのリポジトリで作業する際のガイダンスを提供します。

プロジェクト概要

WikinoはWikiアプリケーションです。 ユーザーは「スペース」と呼ばれる場所にページを作成し、ページ間をリンクで繋げることができます。

モノレポ構造

このリポジトリは、Go 版と Rails 版の 2 つのサブプロジェクトをモノレポとして管理しています：

/workspace/
├── go/                  # Go版の実装（段階的に機能を移行中）
├── rails/               # Rails版の実装（既存の本番システム）
├── caddy/               # リバースプロキシ設定
├── .github/             # 共通のCI/CD設定
├── Dockerfile.dev       # 統合開発コンテナのDockerfile
├── docker-compose.yml   # Docker Compose設定
├── mise.toml            # 開発ツールバージョン管理（Go, Ruby）
└── CLAUDE.md            # このファイル（プロジェクト全体のガイド）

各サブプロジェクトには独自の CLAUDE.md ファイルがあり、それぞれの技術スタック、開発環境、コーディング規約などが記載されています：

  • Go 版: go/CLAUDE.md - Go 版固有の開発ガイド
  • Rails 版: rails/CLAUDE.md - Rails 版固有の開発ガイド

Rails から Go への移行について

現在、既存の Rails 実装の Wikino を Go で段階的に再実装するプロジェクトが進行中です。

移行の基本方針

  • 既存 DB をそのまま使用: Rails 側で管理されている PostgreSQL データベースを共有
  • 段階的移行: Rails と Go が同一の DB とセッションストアを共有し、段階的に機能を移行
  • データマイグレーション不要: DB スキーマは既存のものを使用し、データ移行は行わない
  • 共通インフラの継続利用: PostgreSQL などの共通インフラは Go 版移行後も継続して使用

Rails 側のソースコード

Rails 版のソースコードは /workspace/rails/ 配下に格納されています：

/workspace/rails/
├── app/controllers/     # コントローラー
├── app/records/         # ActiveRecordモデル
├── app/use_cases/       # ユースケース（ビジネスロジック）
├── app/views/           # ビューテンプレート
├── config/routes.rb     # ルーティング定義
└── db/structure.sql     # DBスキーマ

Go 版を実装する際は、Rails 版のコードを参考にすることで既存の仕様を理解できます。

共通インフラ

データベース（PostgreSQL）

  • バージョン: PostgreSQL 18.1
  • 共有方針: Rails 版と Go 版で同一のデータベースを共有
  • 開発環境: Docker Compose で管理（ポート: 4204）
  • データベース名:
    • 開発: wikino_development
    • テスト: wikino_test

セッションストア（PostgreSQL）

  • ストレージ: PostgreSQL の sessions テーブルを使用
  • Rails 版: ActiveRecord SessionStore を使用
    • 各リクエストで updated_at カラムを自動更新
    • セッションの有効期限: 30 日
  • Go 版: 同じ sessions テーブルを共有
    • 認証ミドルウェアで updated_at カラムを更新
    • Rails 版と完全に互換性のあるセッション管理を実現
  • セッションクリーンアップ: 毎日 19:00 に rake session:sweep タスクが実行され、30 日以上前のセッションを自動削除
  • 共有方針: Rails 版と Go 版で同一のセッションストアを共有（段階的移行を実現）

開発環境のセットアップ

前提条件

  • Docker 及び Docker Compose がインストール済み

セットアップ手順

  1. リポジトリのクローン
git clone git@github.com:wikinoapp/wikino.git
cd wikino
  1. Docker Compose の起動
docker compose up
  1. 各サブプロジェクトのセットアップ

各サブプロジェクトの詳細なセットアップ手順は、それぞれの CLAUDE.md ファイルを参照してください：

  • Go 版: go/docs/development-guide.mdの「環境変数の設定」セクション
  • Rails 版: rails/CLAUDE.mdの「開発環境のセットアップ」セクション

環境変数の設定

各サブプロジェクトで.envファイルを作成し、必要な環境変数を設定します。詳細は各サブプロジェクトの CLAUDE.md を参照してください。

ドキュメント

仕様書

各機能の仕様は docs/specs/ ディレクトリで管理しています。システムの現在の状態を理解するには、まず仕様書を参照してください。

サブプロジェクト

各サブプロジェクトの詳細なドキュメントは以下を参照してください：

  • Go 版: @go/CLAUDE.md - Go 版の技術スタック、プロジェクト構造、コーディング規約、テスト戦略など
  • Rails 版: @rails/CLAUDE.md - Rails 版の技術スタック、プロジェクト構造、コーディング規約、テスト戦略など

レビュー時に参照するガイドライン

コードレビュー時に参照するガイドラインドキュメントの一覧です。変更されたファイルの種類に応じて、該当するガイドラインをチェックしてください。

共通ガイドライン

  • @CLAUDE.md - プロジェクト全体のガイド
    • コミットメッセージのガイドライン
    • コメントのガイドライン
    • Pull Requestのガイドライン

Go版ガイドライン

  • @go/CLAUDE.md - Go版の開発ガイド（技術スタック、プロジェクト構造、開発コマンド）
  • @go/docs/architecture-guide.md - アーキテクチャガイド
    • 3層アーキテクチャの依存関係ルール
    • Usecase、Repository、Workerの使い分け
    • ドメインID型
  • @go/docs/coding-guide.md - コーディング規約
    • コメントのガイドライン
    • ログ出力（log/slog）
  • @go/docs/testing-guide.md - テストガイド
    • テスト戦略、TestMainパターン
    • テストヘルパー
  • @go/docs/development-guide.md - 開発環境ガイド
    • 環境変数、DBマイグレーション、golangci-lint
  • @go/docs/handler-guide.md - HTTPハンドラーガイドライン
    • ディレクトリ構造
    • 標準ファイル名（9種類のみ）
    • 依存性注入
  • @go/docs/validation-guide.md - バリデーションガイド
    • バリデーションの分類
    • 状態バリデーションの配置基準
  • @go/docs/i18n-guide.md - 国際化ガイド
    • 翻訳ファイルの追加手順
    • 命名規則
  • @go/docs/security-guide.md - セキュリティガイドライン
    • CSRF対策
    • XSS対策
    • SQLインジェクション対策
    • 認証・認可
  • @go/docs/templ-guide.md - templテンプレートガイド
    • ファイル配置
    • 命名規則
    • コンポーネント化

Rails版ガイドライン

  • @rails/CLAUDE.md - Rails版の開発ガイド
    • プロジェクト構造（app/ディレクトリの構成と責務）
    • クラス設計と依存関係
    • コーディング規約（Ruby、ActiveRecord、マイグレーション、型定義、RSpec、I18n、JavaScript/TypeScript）
    • サービスクラスのルール
    • セキュリティガイドライン
  • @rails/docs/architecture-guide.md - アーキテクチャガイド
    • クラス間の依存関係ルール
    • サービスクラスのルール（使い分け、トランザクション処理）
  • @rails/docs/testing-guide.md - テストガイド
    • RSpec のコーディング規約
    • システムテストの待機処理
  • @rails/docs/security-guide.md - セキュリティガイドライン
    • CSRF対策
    • XSS対策
    • SQLインジェクション対策
    • 認証・Strong Parameters

開発ワークフロー

実装時のガイドライン

既存コードとの一貫性:

実装を行う前に、コードベース内に類似の処理がないか確認してください。 類似処理が存在する場合は、そのパターンに従って実装することで、コードベース全体の一貫性を保ちます。

  • 確認すべき点:

    • 同様の機能を持つハンドラー、ユースケース、リポジトリの実装パターン
    • エラーハンドリングの方法
    • ログ出力のフォーマット
    • バリデーションの実装方法
    • テストの書き方

  • 類似処理が見つかった場合: そのパターンを踏襲して実装する

  • 類似処理が見つからない場合: 各サブプロジェクトのガイドラインに従って新しいパターンを作成する

コミット前のチェック

各サブプロジェクトで実装を行った場合は、コミット前に以下を確認してください：

  • コードフォーマット
  • リント
  • テスト

Go 版の具体的なコマンドは go/CLAUDE.md の「コミット前に実行するコマンド」セクションを参照してください。 Rails 版の具体的なコマンドは rails/CLAUDE.md の「コミット前に実行するコマンド」セクションを参照してください。

Markdown ファイルのフォーマット:

docs/ 配下のドキュメント（作業計画書、レビュードキュメント、仕様書など）を作成・編集した場合は、コミット前に Oxfmt でフォーマットを実行してください：

make -C /workspace fmt

修正後のコミット

重要: バグ修正や機能実装を行った場合でも、Claude Code が自動的にコミットを作成しないでください。

  • 修正が完了したら、コミット前のチェック（フォーマット、リント、テスト）を実行して CI が通ることを確認
  • コミットは /commit コマンドで行う: ユーザーが差分を確認し、適切な粒度でコミットできるようにする
  • コミットメッセージはコミットメッセージのガイドラインに従って日本語で記述

コミットメッセージのガイドライン

コミットメッセージは日本語で記述してください。

フォーマット:

<タイトル>（1行、簡潔に変更内容を要約）

<本文>（任意、変更の詳細や理由を説明）

良い例:

パスワードリセット機能を実装

- internal/handler/password_reset/にハンドラーを追加
- internal/usecase/reset_password.goにビジネスロジックを実装
- Resend APIを使用したメール送信機能を追加
- Cloudflare TurnstileによるBot対策を実装

ユーザー認証のバグを修正

セッションタイムアウト後にリダイレクトが正しく動作しない
問題を修正。

悪い例:

  • ❌ Update handler （英語、内容が不明確）
  • ❌ fix （何を修正したか不明）
  • ❌ WIP （作業中のコミットは避ける）

原則:

  • タイトルは変更内容を簡潔に表現する
  • 必要に応じて本文で詳細を説明する
  • 関連する Issue やPR がある場合は参照を含める

コメントのガイドライン

このガイドラインは Go 版と Rails 版の両方に適用されます。

良いコメント：

  • コードの意図や理由を説明する（「なぜこうしたか」）
  • 将来の開発者が理解できる、文脈に依存しない内容
  • 複雑なロジックや、一見不自然に見える実装の背景を説明する

避けるべきコメント：

  • ❌ 実装の変遷を説明するコメント（「以前は〜だった」「〜は削除した」など）
  • ❌ 過去との比較（「別途インストール不要になった」「〜を統合したため不要」など）
  • ❌ 自明なことの説明（コードを読めばわかること）
  • ❌ やり取りの文脈に依存するコメント（PR レビューのコメントは PR に書く）

原則：

  • コメントはコードの「なぜ」を説明し、「何を」はコードに語らせる
  • git の履歴に残る情報（過去の実装、変更の経緯）はコメントに書かない
  • レビューコメントや議論の文脈に依存する内容は書かない

詳細な例については、各サブプロジェクトの CLAUDE.md を参照してください：

  • Go 版: go/docs/coding-guide.md の「コメントのガイドライン」セクション
  • Rails 版: rails/CLAUDE.md の「コメントのガイドライン」セクション

Pull Request のガイドライン

Pull Request を作成する際は、以下のルールを遵守してください：

サイズの制限

  • 変更ファイル数: 20 ファイル以下
  • 実装コードの行数: 300 行以下を目安（追加・削除行の合計）
  • テストコードの行数: 制限なし（必要な分だけ追加して OK）

実装とテストのセット化

  • 必須: 実装コードとそのテストコードは同じ PR に含める
  • 新機能や修正を行う場合は、必ず対応するテストを追加・更新する
  • テストがない実装は原則としてマージしない
  • テストは品質保証のために必要な分だけ書く: 行数を気にせず、正常系・異常系・境界値などを網羅する

PR を小さく保つ理由

  • レビュアーの負担を軽減し、レビューの質を向上させる
  • バグの混入リスクを最小化する
  • 問題が発生した場合のロールバックを容易にする
  • CI/CD パイプラインの実行時間を短縮する

大きな変更が必要な場合

機能が大きくなる場合は、以下のように分割してください：

  1. 段階的な実装: 機能を複数のステップに分割し、それぞれ独立した PR として作成
  2. リファクタリングの分離: リファクタリングと新機能追加を別々の PR に分ける

例外

以下の場合は制限を超えることが許容されます：

  • 自動生成されたファイル（マイグレーション、スキーマなど）
  • 広範囲に影響する命名変更やリファクタリング
  • ただし、これらの場合でも可能な限り分割を検討してください

重要な原則

品質優先: 上記の行数制限はあくまで目安です。以下の点を優先してください：

  • テストの完全性: 実装にはテストを必ず含める。行数制限のためにテストを省略しない
  • コードの完全性: 機能を中途半端な状態で分割しない。動作する最小単位で PR を作成する
  • 可読性: 無理に行数を減らすためにコードの可読性を犠牲にしない

行数制限を超えても、以下を満たしていれば問題ありません：

  • 実装コードとテストコードの両方が含まれている
  • コードレビューが可能な範囲（目安: 1 ファイルあたり 500 行以下）
  • PR の目的が明確で、1 つの機能や修正に集中している

判断基準: 「行数を守ること」よりも「きちんと実装すること」を優先してください。

CI/CD

このモノレポの CI/CD 設定は.github/workflows/ディレクトリに配置されています：

  • go-ci.yml: Go 版の CI（lint、test、build）
  • fmt-ci.yml: フォーマットチェック（Oxfmt）
  • rails-ci.yml: Rails 版の CI（zeitwerk、sorbet、standard、erb_lint、eslint、rspec）

各 CI は対応するファイルが変更されたときに実行されます。

トラブルシューティング

データベース接続エラー

  • PostgreSQL コンテナが起動しているか確認: docker compose ps
  • ポートが正しいか確認: 開発環境は 4204

その他の問題

各サブプロジェクト固有の問題については、それぞれの CLAUDE.md の「トラブルシューティング」セクションを参照してください。