CLAUDE.md

このドキュメントはClaude Code向けのプロジェクトガイドラインです。

⚠️ 重要: モジュール詳細を CLAUDE.md に書かないこと

• モジュールの実装詳細・関数シグネチャ・Issue 履歴は 必ず docs/module-reference.md に記載する（CLAUDE.md には書かない）
• CLAUDE.md は brief overview のみ。各 module 説明は 1 行 100 文字以内 を厳守
• Issue #N で…追加 のような履歴 narrative を CLAUDE.md に append しない。履歴は git log / CHANGELOG / PR description で辿る
• docs/module-reference.md も append-only で肥大化させない（既存行の更新を優先する）
• 違反すると CI でブロックされる（## 品質担保 の CLAUDE.md size check 参照）

プロジェクト概要

基本情報

• プロジェクト名: CommandMate
• 説明: Git worktree管理とClaude CLI/tmuxセッション統合ツール
• リポジトリ: https://github.com/Kewton/CommandMate

技術スタック

ブランチ構成

ブランチ戦略

main (本番) ← PRマージのみ
  │
develop (受け入れ・動作確認)
  │
feature/*, fix/*, hotfix/* (作業ブランチ)

命名規則

恒久 worktree（クリーンアップ対象外）

次の worktree とブランチは常駐用。「worktree を片付けて」と頼まれても削除・ブランチ削除しない。

標準マージフロー

通常フロー

feature/* ──PR──> develop ──PR──> main
fix/*     ──PR──> develop ──PR──> main
hotfix/*  ──PR──> main (緊急時のみ)

PRルール

1. PRタイトル: <type>: <description> 形式
   • 例: feat: add dark mode toggle
   • 例: fix: resolve login error
2. PRラベル: 種類に応じたラベルを付与
   • feature, bug, documentation, refactor
3. レビュー: 1名以上の承認（main向けPR。運用ルールで、branch protection では強制していない）
4. CI/CD: 全チェックパス必須

コミットメッセージ規約

<type>(<scope>): <subject>

<body>

<footer>

コーディング規約

TypeScript

• 厳格な型定義を使用（strict: true）
• any 型の使用は最小限に
• 明示的な戻り値の型定義を推奨

React/Next.js

• 関数コンポーネントを使用
• 必要なときだけ 'use client' を明示（既定はサーバー側）

ファイル構成

主要なものだけ載せる。ここに無いものは ls で見る。トップレベルの増減時のみ更新する。

bin/commandmate.js   # CLIエントリポイント（shebang付き）
src/
├── app/             # Next.js App Router（api/ はAPIルート、画面は各ディレクトリ）
├── cli/             # CLI本体（program.ts が commander 設定、index.ts は起動のみ）
│   ├── commands/    # サブコマンド（一覧は `commandmate --help`。補助ファイルも同居）
│   ├── utils/       # 依存チェック、環境設定、デーモン管理
│   ├── config/      # 依存関係定義・CLIツールID・定数
│   ├── docs/        # CLI埋め込みドキュメント
│   └── types/       # CLI共通型定義（ExitCode enum）
├── components/      # UIコンポーネント（機能別ディレクトリ + ui/ 汎用プリミティブ）
├── config/          # 設定（ステータス色、編集可能拡張子など）
├── contexts/        # React Context
├── hooks/           # カスタムフック
├── lib/             # ユーティリティ・ビジネスロジック
│   ├── cli-tools/   # CLIツール抽象化層
│   ├── db/          # データベース
│   ├── detection/   # ステータス検出・プロンプト検出
│   ├── git/         # Git操作・worktree管理・クローン
│   ├── polling/     # ポーリング・Auto-Yes
│   ├── security/    # 認証・IP制限・パス検証・サニタイズ
│   ├── session/     # セッション管理・実行エンジン
│   ├── tmux/        # tmuxセッション管理・トランスポート
│   ├── ws-server.ts # WebSocketサーバ
│   └── logger.ts    # 構造化ロギング基盤
└── types/           # 型定義

tests/
├── unit/            # 単体テスト
├── integration/     # 結合テスト
├── e2e/             # Playwright E2E（*.spec.ts）
├── helpers/         # テスト共通ヘルパー（型ガード、loggerモック等）
├── fixtures/        # テスト用データ
├── scripts/         # スクリプト用テスト
└── setup.ts         # Vitest共通セットアップ

モジュール一覧

各モジュールの責務・関数シグネチャ・Issue 履歴は docs/module-reference.md を参照。

重要: モジュール詳細を CLAUDE.md に記述しないこと。詳細・Issue 履歴は必ず docs/module-reference.md に書く。

品質担保

必須チェック（CI/CD）

検証ゲートの正は .commandmate/verify.yaml。CI の全ジョブは .github/workflows/ci-pr.yml を見る。

• サイズ guard（CI で hard-fail）:
  • CLAUDE.md は 35,000 bytes 以下（node scripts/check-claudemd-size.mjs）。超過したら詳細を docs/module-reference.md へ移す
  • .claude/commands/orchestrate.md は 118,000 bytes 以下

推奨チェック

• Integration Test: npm run test:integration
• E2E Test: npm run test:e2e

禁止事項

ブランチ操作

1. mainへの直push禁止
   • 全ての変更はPRを通じて行う
   • git push origin main は拒否される
   • Git Hook（pre-push）で強制: ローカル環境でmainブランチへの直接pushをブロック
2. force push禁止
   • git push --force は原則禁止
   • 例外: 自分のfeatureブランチのみ許可

Git Hook設定

.git/hooks/pre-push でmainブランチへの直接pushを防止。クローン後に手動設定が必要（リポジトリには含まれない。手順は docs/release-guide.md）。--no-verifyで回避可能なためチームルールとしての遵守が重要。

コード

1. console.logの本番残留禁止
   • デバッグ用のログは削除すること
2. 未使用importの残留禁止
   • ESLintで検出・除去

例外対応

• 緊急時はhotfix/*ブランチを使用
• チーム責任者の承認を得てからマージ

開発コマンド

# 開発サーバー起動
npm run dev

# ビルド
npm run build          # Next.jsビルド
npm run build:cli      # CLIモジュールビルド
npm run build:server   # サーバーモジュールビルド
npm run build:all      # 全ビルド（Next.js + CLI + server）

# テスト
npm test              # 全テスト
npm run test:unit     # 単体テスト
npm run test:integration  # 結合テスト
npm run test:e2e      # E2Eテスト

# リント
npm run lint

# データベース
npm run db:init       # DB初期化
npm run db:reset      # DBリセット

CLIコマンド（グローバルインストール後）

サブコマンドの一覧は commandmate --help。起動・停止・--issue による並列サーバーは cli-setup-guide.md、その他の詳細と終了コードは cli-operations-guide.md（remote は webapp-guide.md も）を参照。踏むと事故になる規則だけをここに残す。

• 送り先: send / wait / respond / capture / reply は --instance <id> 単独で指定する（例: commandmate send <worktree-id> "メッセージ" --instance codex）。--agent は roster 外のアドホック起動用
• --model: send の新規起動時のみ有効（claude/antigravity）。稼働中のセッションへ指定すると 400
• wait: --timeout <秒> 超過は exit 124。--on-prompt human でプロンプト検出後も待機継続。wait に --agent は無い。--verify は完了検知後に検証ゲートを実行し、不合格 exit 20 / 作業証跡ゼロ exit 21
• verify: commandmate verify <worktree-id> [--gates lint,unit] [--json]。合格 0 / 不合格 20 / 作業証跡ゼロ 21（.commandmate/verify.yaml）
• auto-yes: commandmate auto-yes <worktree-id> --enable --duration 3h。duration は 1h〜24h（1 時間刻み。既定 1h）。--disable で無効化
• instances: roster の追加は commandmate instances <worktree-id> add --agent codex。roster 外 ID のアドホック起動は commandmate send <worktree-id> "メッセージ" --agent codex --instance codex-3 --register（--agent 必須）
• roles: ロールは起動時に固定。roles edit / roles default / set-role は稼働中に効かない（止めて送り直す）。send --role は条件で、不一致・不明は未送信 exit 32（設定は保存済み）
• update: 非対話環境で --yes が無いと exit 2（commandmate update --yes）。--check は変更しない
• remote: --provider cloudflare は公開 Tunnel のため --yes が必須（非対話環境も）。--provider tailscale は承認不要

Claude Code コマンド・エージェント

本プロジェクトではClaude Code用のスラッシュコマンドとサブエージェントを整備しています。

利用可能なコマンド

利用可能なエージェント

利用可能なスキル

最近の実装機能

実装機能一覧 - Issue別の概要・主要変更ファイル・設計書リンク

関連ドキュメント

• README.md - プロジェクト概要
• アーキテクチャ - システム設計
• 移行ガイド - MyCodeBranchDesk からの移行手順
• リリースガイド - バージョン管理とリリース手順
• クイックスタートガイド - 5分で始める開発フロー
• コマンド利用ガイド - コマンドの詳細
• エージェント利用ガイド - エージェントの詳細
• ワークフロー例 - 実践的な使用例
• ステータスインジケーター - サイドバー機能詳細
• 実装機能一覧 - Issue別の実装履歴
• Jev による Issue 棚卸し - 優先度・担当モデルの下書き（API と注意点）