ai/claude/docs/optimal_development_workflow.md

# 最適化された開発ワークフロー

## 概要

プロジェクト間の齟齬を防止し、Claude Codeセッションの成果を確実に反映する最適化された開発ワークフロー。

## 基本原則

### 1. 一貫性の維持
- 全プロジェクトの状態同期
- 設定とコードの整合性
- ブランチ戦略の統一

### 2. セッション成果の記録
- Claude Codeセッションの完全記録
- 変更内容の構造化保存
- 反映状況の追跡

### 3. 自動化による品質保証
- 手動プロセスの最小化
- 自動検証とエラー検出
- 一貫したコミットメッセージ

## 推奨ワークフロー

### Phase 1: セッション開始前

#### 1. 全体状況確認
```bash
cd /Users/syui/ai/ai

# 一貫性チェック
./claude/scripts/update-submodules.sh --check-consistency

# URL検証
./claude/scripts/update-submodules.sh --validate

# 最新状態に更新
./claude/scripts/update-submodules.sh --all --dry-run
```

#### 2. 作業プロジェクト選択
```bash
# プロジェクトディレクトリに移動
cd gpt  # 例: gpt プロジェクト

# ブランチ確認・切り替え
git status
git checkout claude  # または適切なブランチ
```

### Phase 2: Claude Codeセッション

#### セッション中の注意点
- **専用ブランチ使用**: mainではなくclaudeブランチで作業
- **定期的なコミット**: 大きな変更は小分けにコミット
- **明確なコミットメッセージ**: 何を変更したかを明記

#### 推奨コミット戦略
```bash
# 機能追加の場合
git commit -m "Add: 新機能名 - 簡潔な説明"

# バグ修正の場合  
git commit -m "Fix: 修正内容 - 問題の説明"

# 改善の場合
git commit -m "Improve: 改善内容 - before/afterの説明"
```

### Phase 3: セッション終了時（重要）

#### 自動セッション終了プロセス
```bash
# プロジェクトディレクトリで実行
./claude/scripts/session-end.sh --auto-sync

# または手動でサマリー指定
./claude/scripts/session-end.sh --summary="新しいMCP機能を実装。23ツールから25ツールに拡張。" --auto-sync
```

#### session-end.shの機能
1. **変更検出**: 未コミット変更の自動検出
2. **サマリー入力**: セッション成果の記録
3. **自動コミット**: 構造化されたコミットメッセージ
4. **親リポジトリ同期**: サブモジュール更新の自動反映
5. **セッション記録**: `.claude/sessions/`にMDファイル保存
6. **検証**: 一貫性チェックの自動実行

### Phase 4: 事後確認

#### 1. 結果確認
```bash
cd /Users/syui/ai/ai

# 更新が正しく反映されているか確認
git log --oneline -5

# 一貫性の最終確認
./claude/scripts/update-submodules.sh --check-consistency
```

#### 2. セッション記録確認
```bash
# 最新のセッション記録を確認
ls -la .claude/sessions/
cat .claude/sessions/gpt_2025-06-07_15-30-45.md
```

## 特殊ケースの対応

### 複数プロジェクト同時開発

#### 方法1: 順次処理（推奨）
```bash
# プロジェクト1完了
cd gpt
./claude/scripts/session-end.sh --auto-sync

# プロジェクト2開始
cd ../bot
# Claude Codeセッション...
./claude/scripts/session-end.sh --auto-sync
```

#### 方法2: 並行処理
```bash
# 各プロジェクトで作業（--auto-syncは使わない）
cd gpt
./claude/scripts/session-end.sh --summary="GPT機能拡張"

cd ../bot  
./claude/scripts/session-end.sh --summary="Bot統合改善"

# 最後に一括同期
cd ../
./claude/scripts/update-submodules.sh --all --auto
```

## 自動化ツール

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

#### 1. session-end.sh
```bash
# 基本使用
./claude/scripts/session-end.sh --auto-sync

# サマリー指定
./claude/scripts/session-end.sh --summary="作業内容" --auto-sync

# プロジェクト指定
./claude/scripts/session-end.sh --project=gpt --auto-sync
```

#### 2. update-submodules.sh
```bash
# 一貫性チェック
./claude/scripts/update-submodules.sh --check-consistency

# 全体更新
./claude/scripts/update-submodules.sh --all --auto

# URL検証
./claude/scripts/update-submodules.sh --validate
```

### 推奨エイリアス設定
```bash
# ~/.zshrc
alias daily-check="cd /Users/syui/ai/ai && ./claude/scripts/update-submodules.sh --check-consistency"
alias sync-all="cd /Users/syui/ai/ai && ./claude/scripts/update-submodules.sh --all --auto"
alias session-end="../claude/scripts/session-end.sh --auto-sync"
```

## エラー対応

### よくある問題と解決策

#### 1. 未コミット変更の衝突
```
⚠️  gpt: Has uncommitted changes
```
**解決策:**
```bash
cd gpt
./claude/scripts/session-end.sh --summary="作業内容の説明" --auto-sync
```

#### 2. ブランチ不一致
```
⚠️  bot: Branch mismatch
    Current: main
    Expected: claude
```
**解決策:**
```bash
cd bot
git checkout claude
git merge main  # 必要に応じて
```

#### 3. サブモジュールポインタ不一致
```
⚠️  card: Submodule pointer mismatch
```
**解決策:**
```bash
./claude/scripts/update-submodules.sh --module=card --auto
```

## セッション記録システム

### 自動生成される記録
- **場所**: `.claude/sessions/`
- **形式**: `{project}_{timestamp}.md`
- **内容**: セッション概要、変更詳細、コミット情報

### 記録例
```markdown
# Claude Code Session Report

**Project**: gpt  
**Date**: 2025-06-07 15:30:45  
**Summary**: MCP機能拡張。新しいツール追加とエラーハンドリング改善。

## Changes Made
 src/mcp_client.rs | 45 +++++++++++++++++++++++++++++
 src/commands.rs   | 23 +++++++++++++--
 2 files changed, 68 insertions(+), 2 deletions(-)

## Session End Status
- ✅ Changes committed
- ✅ Session logged
- ✅ Auto-sync completed
```

## ベストプラクティス

### 1. セッション設計
- **明確な目標**: 何を達成するかを最初に決める
- **適切な粒度**: 1セッション = 1つの機能や修正
- **定期的な保存**: 大きな変更は途中でコミット

### 2. 終了時のルーティン
```bash
# 必須: セッション終了スクリプト実行
./claude/scripts/session-end.sh --auto-sync

# 推奨: 最終確認
cd /Users/syui/ai/ai
./claude/scripts/update-submodules.sh --check-consistency
```

### 3. 定期メンテナンス
- **日次**: 作業開始前にconsistency check
- **週次**: 全体的な検証とクリーンアップ

このワークフローに従うことで、プロジェクト間の齟齬を防ぎ、Claude Codeセッションの成果を確実に蓄積できます。