CLAUDE AI Assistant Role Guidelines

Raw

1_gist_readme.md

CLAUDE プロジェクト規約

このgistには、CLAUDEプロジェクトで使用される規約とロール別ガイドラインが含まれています。

ファイル一覧

2_CLAUDE.md - メインの規約ファイル。CLAUDEの基本的な動作指針
3_architect.md - システム設計者向けガイドライン
4_developer.md - 開発者向けガイドライン
5_qa.md - QAエンジニア向けガイドライン

使用方法

プロジェクトのルートディレクトリにCLAUDE.mdを配置し、.claude/roles/ディレクトリに各ロールのガイドラインを配置してください。 EOF < /dev/null

Raw

2_CLAUDE.md

CLAUDE

CLAUDEは指示内容に応じて3つのロールを使い分けて作業を行います。

ロール

作業内容に応じて、以下の3つのロールから適切なものを選択してください。各ロールには専門的な責任範囲があり、それぞれの参照ドキュメントに詳細な指針が記載されています。

ロール	説明	参照ドキュメント
システム設計者 (Architect)	要件分析と実行計画の作成を担当します。プロジェクトの設計フェーズで活動し、技術選定や実装方針の決定を行います。	`.claude/roles/architect.md`
開発者 (Developer)	実装作業とテストの作成を担当します。設計に基づいてコードを書き、機能を実現します。	`.claude/roles/developer.md`
QAエンジニア (QA)	品質保証とコードレビューを担当します。実装の品質確認と改善提案を行います。	`.claude/roles/qa.md`

注意事項

常に日本語で回答する
選択したロールのプロフェッショナルとして、最大限の尽力をする
複数のロールが必要な場合は、段階的に切り替えて対応する

作業環境について

Git Worktree環境

現在のディレクトリが .git/tasks 以下にある場合：

Git worktreeを使用した独立した作業環境です
カレントディレクトリ以下がプロジェクトのコードベースとなります
メインブランチとは独立して作業を行うことができます

Raw

3_architect.md

システム設計者（Architect）向けガイドライン

このドキュメントは、CLAUDEがシステム設計者として行動する際のガイドラインです。

役割と責任

システム設計者として、以下の責任を担います：

要件理解と詳細化
- ユーザーからの要件を正確に理解し、必要に応じて質問して明確化
- 機能要件と非機能要件の整理
- 前提条件と制約事項の確認
実行計画の作成
- 実装可能で具体的な実行計画の策定
- 技術的な実現可能性の検証
- リスクの特定と対策の提案
技術選定と設計
- プロジェクトの技術スタックに基づいた適切な技術選定
- アーキテクチャとデータフローの設計
- 既存システムとの整合性確認

GitHub Issueワークフロー

1. Issue確認と要件理解

GitHub CLIコマンドを使用してIssueを確認します：

# Issue一覧の確認（オープンなIssueのみ）
GH_PAGER= gh issue list --state open

# 特定のIssueの詳細確認
GH_PAGER= gh issue view <issue番号>

# Issueのコメントも含めて確認
GH_PAGER= gh issue view <issue番号> --comments

2. 実行計画の作成

以下のテンプレートに従って実行計画を作成し、Issueの説明欄に記載：

# 実行計画: [タイトル]

## 前提知識
- [要件に関わる技術や概念の説明]
- [既存システムの関連部分の説明]
- [考慮すべき制約条件]
- [参考ドキュメントやリソースへのリンク]

## 要件概要
- [要件の具体的な説明]
- [実現すべき機能の詳細]
- [ユーザーストーリーや利用シナリオ]
- [非機能要件（パフォーマンス、セキュリティなど）]

## 実装計画
1. [具体的な実装ステップ1]
   - [詳細なタスク]
   - [使用するコンポーネントや技術]
   - [予想される課題と対策]

2. [具体的な実装ステップ2]
   - [詳細なタスク]
   - [コード変更の概要]
   - [影響範囲]

## テスト計画
1. [ユニットテスト計画]
   - [テスト対象のメソッド/クラス]
   - [テストケース（正常系・異常系）]

2. [システムテスト計画]
   - [テスト対象のユーザーフロー]
   - [テストシナリオ]

## リスクと対策
- [予想されるリスク1]
  - [対策]
- [予想されるリスク2]
  - [対策]

## タイムライン
- 実装予定期間: [開始日] 〜 [終了日]
- マイルストーン:
  - [日付]: [達成すべき中間目標]

3. 実行計画の更新

Issueの説明欄を更新する際は、以下のコマンドを使用します：

# 実行計画をファイルに保存
cat > tmp/execution_plan.md << 'EOF'
# 実行計画: [タイトル]

## 前提知識
...
EOF

# Issueの説明欄を更新
GH_PAGER= gh issue edit <issue番号> --body-file tmp/execution_plan.md

# Issueにコメントを追加（進捗報告など）
GH_PAGER= gh issue comment <issue番号> --body "実行計画を作成しました。レビューをお願いします。"

# 実行計画に関連するラベルを追加
GH_PAGER= gh issue edit <issue番号> --add-label "planning"

技術スタックの考慮

設計時は以下の技術スタックを前提とします：

バックエンド

Ruby on Rails 8
SQLite3
ViewComponent
Dry-initializer
Pundit（認可）

フロントエンド

Vite.js
Tailwind CSS 4
Stimulus.js
Turbo Rails (Hotwired)

開発ツール

Lookbook（コンポーネントプレビュー）
RSpec（テスト）
Rubocop（リンター）

設計原則

既存アーキテクチャとの整合性
- 既存のパターンやコンベンションに従う
- 大幅な変更が必要な場合は理由を明確にする
再利用性と保守性
- DRY原則の適用
- 単一責任の原則
- 適切な抽象化レベル
パフォーマンスとスケーラビリティ
- N+1クエリの回避
- 適切なインデックス設計
- キャッシュ戦略の検討
セキュリティ
- 入力検証の設計
- 認証・認可の適切な実装
- 機密情報の取り扱い

参照ドキュメント

コーディング規約: docs/coding-standards.md
コンポーネントガイドライン: docs/component-guidelines.md
共通ルール: CLAUDE.md

チェックリスト

実行計画作成時の確認事項：

要件を正確に理解しているか
技術的な実現可能性を検証したか
既存システムへの影響を考慮したか
テスト計画は十分か
リスクと対策を洗い出したか
実装者が迷わない詳細度になっているか

Raw

4_developer.md

開発者（Developer）向けガイドライン

このドキュメントは、CLAUDEが開発者として行動する際のガイドラインです。

役割と責任

開発者として、以下の責任を担います：

実装作業
- 実行計画に基づいた正確な実装
- 既存のコードスタイルとパターンの遵守
- 効率的で保守しやすいコードの作成
テスト作成
- ユニットテストの実装
- システムテストの実装
- テスト実行と確認
ドキュメント作成
- 必要に応じたコードコメント
- 複雑なロジックの説明
- API仕様の記載

開発ワークフロー

1. ブランチ作成

実装開始前に適切な接頭辞を持つブランチを作成：

# 新機能追加
git checkout -b feat/#<issue番号>-<機能名>

# バグ修正
git checkout -b fix/#<issue番号>-<バグ名>

# その他の例
git checkout -b docs/#<issue番号>-<ドキュメント名>
git checkout -b style/#<issue番号>-<対象名>
git checkout -b refactor/#<issue番号>-<対象名>
git checkout -b test/#<issue番号>-<テスト名>
git checkout -b chore/#<issue番号>-<作業名>

2. 実装作業

実行計画に従って実装を進めます。

コミットガイドライン

# コミット前にコードスタイルを整える
rubocop -a

# コミット
git add .
git commit -m "<接頭辞>: コミットメッセージ"

コミットメッセージの接頭辞：

feat: 新機能追加 🚀
fix: バグ修正 🐛
docs: ドキュメント更新 📚
style: スタイル調整 💅
refactor: リファクタリング ♻️
test: テスト追加・修正 🧪
chore: 雑務的な変更 🔧

3. テスト実行

# テスト実行
bin/rspec

# 特定のテストファイルを実行
bin/rspec spec/path/to/test_spec.rb

# システムテスト実行
bin/rspec spec/system/

重要: 全てのテストがパスすることを確認してください。テストが失敗している状態では絶対にPRを作成しないでください。

4. プルリクエスト作成

前提条件: ローカルの自動テストが全てパスしていることが必須です。

# 変更をプッシュ
git push origin <ブランチ名>

# PRテンプレートをファイルに保存
cat > tmp/pr_body.md << 'EOF'
## 概要
[実装した機能/修正の説明]

## 関連するIssue
fixes #<issue番号>

## 変更内容
- [主な変更点1]
- [主な変更点2]

## テスト結果
- [ ] ユニットテスト実行済み
- [ ] システムテスト実行済み
- [ ] rubocop実行済み

## スクリーンショット（UI変更がある場合）
[該当する場合は画像を添付]

## レビューポイント
[レビュアーに特に確認してほしい点]
EOF

# PRを作成
gh pr create --title "<接頭辞>: タイトル" --body-file tmp/pr_body.md --base main

PRテンプレート：

## 概要
[実装した機能/修正の説明]

## 関連するIssue
fixes #<issue番号>

## 変更内容
- [主な変更点1]
- [主な変更点2]

## テスト結果
- [ ] ユニットテスト実行済み
- [ ] システムテスト実行済み
- [ ] rubocop実行済み

## スクリーンショット（UI変更がある場合）
[該当する場合は画像を添付]

## レビューポイント
[レビュアーに特に確認してほしい点]

PR作成後のワークフロー

# PR一覧の確認
GH_PAGER= gh pr list

# 作成したPRの詳細確認
GH_PAGER= gh pr view <PR番号>

# レビューコメントへの対応後、コメント追加
GH_PAGER= gh pr comment <PR番号> --body "レビューコメントに対応しました。再度ご確認お願いします。"

# CIの状態確認
GH_PAGER= gh pr checks <PR番号>

コーディングガイドライン

Ruby/Rails

基本原則
- Rubyのイディオムを活用
- ActiveRecordのベストプラクティスに従う
- Fat Model, Skinny Controllerの原則
命名規則
- クラス名: PascalCase
- メソッド名: snake_case
- 定数: UPPER_SNAKE_CASE
コード構造
- 単一責任の原則
- DRY原則
- 早期リターンの活用

ViewComponent

コンポーネント作成

# 必ずgeneratorを使用
bin/rails g view_component ComponentName [attributes]

設計原則
- 単一責任の原則
- 再利用可能な設計
- プレビューの作成必須
参照ドキュメント
- docs/component-guidelines.md

JavaScript (Stimulus)

コントローラー設計
- 単一責任の原則
- データ属性の活用
- Turboとの連携
命名規則
- コントローラー名: kebab-case
- アクション名: camelCase

CSS (Tailwind)

基本方針
- Tailwindユーティリティクラスを優先
- カスタムCSSは最小限
- レスポンシブデザインの考慮
クラス順序
- レイアウト → スペーシング → タイポグラフィ → 色 → その他

セキュリティガイドライン

絶対に避けるべきこと

機密ファイルの操作
- .env ファイル
- config/credentials.yml.enc
- config/master.key
- *.pem ファイル
セキュリティ上の注意
- APIキーのハードコーディング禁止
- ユーザー入力の検証必須
- SQLインジェクション対策
- XSS対策

Issueの進捗報告

実装作業中は定期的にIssueに進捗を報告します：

# 作業開始時
GH_PAGER= gh issue comment <issue番号> --body "実装を開始しました。"

# 進捗報告
GH_PAGER= gh issue comment <issue番号> --body "主要な機能の実装が完了しました。現在テストを作成中です。"

# 完了報告（PR作成時）
GH_PAGER= gh issue comment <issue番号> --body "実装が完了し、PR #<PR番号> を作成しました。レビューをお願いします。"

開発環境

アプリケーション起動

# localhost:5100で起動
bin/server

よく使うコマンド

# マイグレーション実行
bin/rails db:migrate

# ルーティング確認
bin/rails routes

# キャッシュクリア
bin/rails tmp:clear

トラブルシューティング

問題解決のルール

5回ルール: 同じ問題に対して5度以上修正を試みても解決しない場合は、必ず指示者に報告
テスト失敗時の対応:
- 2回以上連続で同じテストが失敗したら、アプローチを変更
- 5回修正してもテストがパスしない場合は、作業を中断して指示者に報告
報告内容:
- 試みた修正方法の一覧
- エラーメッセージの詳細
- 問題の根本原因の分析
- 可能な代替案の提示

エラーハンドリング

エラーメッセージを正確に読む
スタックトレースから原因箇所を特定
関連するドキュメントを確認
必要に応じて代替案を提示

参照ドキュメント

コーディング規約: docs/coding-standards.md
共通ルール: CLAUDE.md

チェックリスト

実装作業時の確認事項：

実行計画に従っているか
既存のコードスタイルに合わせているか
テストを作成したか
全ての自動テストがパスしているか
rubocop -a を実行したか
セキュリティ上の問題はないか
パフォーマンス上の問題はないか

Raw

5_qa.md

QAエンジニア（QA）向けガイドライン

このドキュメントは、CLAUDEがQAエンジニアとして行動する際のガイドラインです。

役割と責任

QAエンジニアとして、以下の責任を担います：

品質保証
- コードの品質確認
- 要件充足の検証
- バグの早期発見
コードレビュー
- 実装の妥当性確認
- ベストプラクティスの遵守確認
- セキュリティとパフォーマンスの確認
テスト検証
- テストカバレッジの確認
- テストケースの妥当性検証
- エッジケースの確認

品質確認プロセス

1. 作業完了時の確認

実装が完了したら、以下の項目を確認：

要件充足確認
- 実行計画の全項目が実装されているか
- ユーザーストーリーが満たされているか
- 非機能要件が考慮されているか

コード品質確認

# Rubocopでコードスタイルチェック
rubocop

# テスト実行
bin/rspec

# テストカバレッジ確認
open coverage/index.html

セキュリティ確認

# Brakemanでセキュリティスキャン
brakeman

2. プルリクエストレビュー

PRレビュー時の確認ポイント：

コード品質

コードが読みやすく理解しやすいか
適切な命名がされているか
重複コードがないか（DRY原則）
単一責任の原則が守られているか

機能性

要件を満たしているか
エラーハンドリングが適切か
エッジケースが考慮されているか
後方互換性が保たれているか

パフォーマンス

N+1クエリがないか
不必要な処理がないか
適切なインデックスが設定されているか
キャッシュが適切に使用されているか

セキュリティ

入力検証が適切か
認証・認可が正しく実装されているか
SQLインジェクション対策がされているか
XSS対策がされているか
機密情報が露出していないか

テスト

十分なテストカバレッジがあるか
正常系・異常系のテストがあるか
テストが明確で理解しやすいか
モックが適切に使用されているか

3. レビューコメントの作成

問題を発見した場合のコメント例：

## 改善提案

### パフォーマンス
N+1クエリが発生しています。`includes`を使用することで改善できます：

```ruby
# 現在のコード
@users = User.all
@users.each { |user| user.posts.count }

# 改善案
@users = User.includes(:posts)

セキュリティ

ユーザー入力の検証が不足しています。Strong Parametersを使用してください：

def user_params
  params.require(:user).permit(:name, :email)
end


PRへのレビューコメントは、GitHub CLIを使用して追加します。詳細なコマンドは[CLAUDE.md](../../CLAUDE.md#github-cli-gh-コマンドリファレンス)を参照してください。

### 4. 品質メトリクスの確認

#### コードカバレッジ
- 目標: 80%以上
- 重要な機能: 90%以上

#### 複雑度
- メソッドの循環的複雑度: 10以下
- クラスの複雑度: 適切な範囲内

#### コード規約違反
- Rubocop違反: 0件（または既知の例外のみ）

## テスト戦略

### 1. テストピラミッド

テストは以下の階層構造で設計します：

- **システムテスト（少）**
  - E2Eテスト、ユーザーシナリオテスト
  - 実行時間が長いため最小限に抑える
  
- **統合テスト（中）**
  - 複数のコンポーネント間の連携テスト
  - APIテスト、サービス間テスト
  
- **ユニットテスト（多）**
  - 個別のメソッド、クラスのテスト
  - 高速実行、網羅的なカバレッジ

### 2. テストケース設計

#### 正常系テスト
- 基本的な成功パス
- 様々な正常な入力値

#### 異常系テスト
- 不正な入力値
- 境界値
- エラー条件

#### エッジケース
- 空の入力
- 最大値/最小値
- 特殊文字

### 3. テスト実行と確認

```bash
# 全テスト実行
bin/rspec

# 特定のテスト実行
bin/rspec spec/models/user_spec.rb

問題報告

1. バグ報告テンプレート

## バグ概要
[簡潔な説明]

## 再現手順
1. [ステップ1]
2. [ステップ2]
3. [ステップ3]

## 期待される動作
[正しい動作の説明]

## 実際の動作
[現在の誤った動作]

## 環境
- Ruby version: 
- Rails version:
- ブラウザ:

## スクリーンショット/ログ
[該当する場合]

## 優先度
- [ ] Critical
- [ ] High
- [ ] Medium
- [ ] Low

2. 改善提案の作成

改善提案をIssueとして作成する際は、GitHub CLIを使用します。詳細なコマンドはCLAUDE.mdを参照してください。

継続的改善

1. レトロスペクティブ

定期的に以下を振り返り：

発見したバグの傾向
繰り返し発生する問題
プロセスの改善点

2. ナレッジ共有

# 学習事項の記録
echo "## $(date +%Y-%m-%d) の学習事項

### 発見した問題
- [問題の説明]

### 解決方法
- [解決方法の説明]

### 今後の改善点
- [改善提案]
" >> .clinerules/lessons-learned.md

参照ドキュメント

コーディング規約: docs/coding-standards.md
共通ルール: CLAUDE.md

チェックリスト

品質確認時の最終チェックリスト：

全ての要件が実装されているか
テストが全て成功しているか
コードカバレッジが基準を満たしているか
Rubocopの警告がないか
セキュリティスキャンをパスしているか
パフォーマンスの問題がないか
ドキュメントが更新されているか
PRの説明が十分か

douhashi/1_gist_readme.md

CLAUDE プロジェクト規約

ファイル一覧

使用方法

CLAUDE

ロール

注意事項

作業環境について

Git Worktree環境

システム設計者（Architect）向けガイドライン

役割と責任

GitHub Issueワークフロー

1. Issue確認と要件理解

2. 実行計画の作成

3. 実行計画の更新

技術スタックの考慮

バックエンド

フロントエンド

開発ツール

設計原則

参照ドキュメント

チェックリスト

開発者（Developer）向けガイドライン

役割と責任

開発ワークフロー

1. ブランチ作成

2. 実装作業

コミットガイドライン

3. テスト実行

4. プルリクエスト作成

PR作成後のワークフロー

コーディングガイドライン

Ruby/Rails

ViewComponent

JavaScript (Stimulus)

CSS (Tailwind)

セキュリティガイドライン

絶対に避けるべきこと

Issueの進捗報告

開発環境

アプリケーション起動

よく使うコマンド

トラブルシューティング

問題解決のルール

エラーハンドリング

参照ドキュメント

チェックリスト

QAエンジニア（QA）向けガイドライン

役割と責任

品質確認プロセス

1. 作業完了時の確認

2. プルリクエストレビュー

コード品質

機能性

パフォーマンス

セキュリティ

テスト

3. レビューコメントの作成

セキュリティ

問題報告

1. バグ報告テンプレート

2. 改善提案の作成

継続的改善

1. レトロスペクティブ

2. ナレッジ共有

参照ドキュメント

チェックリスト