# SPEC-CODEMAP-AUTO-UPDATE-001: CODEMAP自動更新システム仕様書

**最終更新**: 2025年8月9日
**担当**: Claude Code実装チーム
**優先度**: 高（B20開発作業指示書準拠）

---

## 🎯 概要

Git コミット発生時にCODEMAP.yamlを自動的に更新し、プロジェクトドキュメントとコードベースの同期を維持するシステム。

### ビジネス価値
- **ドキュメント同期精度向上**: 手動更新による同期ずれ防止
- **開発者負担軽減**: CODEMAP更新作業の自動化
- **プロジェクト品質向上**: 継続的な情報精度確保

## 🔧 機能要件

### REQ-1: 基本自動更新機能

**REQ-1.1: メタデータ自動更新**
- `last_updated`: コミット日時の自動設定
- `commit`: 最新コミットハッシュの自動設定
- `version`: セマンティックバージョン自動インクリメント

**REQ-1.2: 実装状況自動検出**
- 変更ファイルからの実装完了ステータス推定
- アーキテクチャ層別の変更検出
- 循環インポート対策完了などの自動ステータス更新

### REQ-2: 安全性・信頼性機能

**REQ-2.1: バックアップ・ロールバック**
- 更新前のCODEMAP.yamlバックアップ作成
- 更新失敗時の自動ロールバック
- 破損検出とリカバリ機能

**REQ-2.2: 検証・整合性チェック**
- YAML構文検証
- 必須フィールド存在確認
- 構造整合性チェック

### REQ-3: Git統合機能

**REQ-3.1: Post-Commitフック統合**
- 既存post-commitフックとの協調動作
- フック実行失敗時の適切なエラーハンドリング
- パフォーマンス最適化（軽量実行）

**REQ-3.2: Git情報取得**
- 最新コミット情報の取得
- 変更ファイル一覧の取得
- ブランチ情報とマージ状況の検出

## 🏗 技術仕様

### アーキテクチャ設計

#### ドメイン層
```python
# エンティティ
class CodeMapEntity:
    """CODEMAPの構造とメタデータを表現"""

class CommitInformation:
    """コミット情報のドメインエンティティ"""

# ドメインサービス
class DocumentSynchronizationService:
    """ドキュメント同期ビジネスロジック"""

class CommitAnalysisService:
    """コミット分析ビジネスロジック"""
```

#### アプリケーション層
```python
# ユースケース
class CodeMapAutoUpdateUseCase:
    """CODEMAP自動更新の統括ユースケース"""

class GitCommitAnalysisUseCase:
    """Git情報分析ユースケース"""
```

#### インフラストラクチャ層
```python
# リポジトリ
class YamlCodeMapRepository:
    """CODEMAP.yaml読み書きリポジトリ"""

# アダプター
class GitInformationAdapter:
    """Git情報取得アダプター"""

class PostCommitHookService:
    """Post-commitフック統合サービス"""
```

### データ仕様

#### CODEMAP更新対象フィールド
```yaml
project_structure:
  last_updated: "2025-08-09T15:30:00+09:00"  # ISO 8601形式
  commit: "a1b2c3d4e5f6"  # 最新コミットハッシュ（短縮形）
  version: "2.1.0"  # セマンティックバージョン

circular_import_solutions:
  resolved_issues:
    - status: "✅ 完了"  # 自動ステータス更新
      commit: "a1b2c3d4e5f6"  # 該当コミット
```

## 🚀 実装計画

### フェーズ1: ドメイン・コア機能実装
- CODEMAPエンティティとドメインサービス
- コミット分析ロジック
- 基本的なYAML更新機能

### フェーズ2: インフラ・統合機能実装
- Gitアダプターとリポジトリ実装
- Post-commitフック統合
- エラーハンドリングとバックアップ

### フェーズ3: 品質保証・運用準備
- テストスイート完成
- ドキュメント整備
- 運用監視機能

## 🧪 テスト要件

### 単体テスト
- ドメインサービスのロジックテスト
- リポジトリの読み書きテスト
- Git情報取得の正確性テスト

### 統合テスト
- Post-commitフックとの統合テスト
- CODEMAP更新の端to端テスト
- エラー・障害シナリオテスト

### 運用テスト
- パフォーマンステスト（コミット時間への影響）
- 信頼性テスト（連続コミット時の動作）
- セキュリティテスト（権限・ファイルアクセス）

## 📈 成功指標

### 機能指標
- CODEMAP同期率: 100%（手動更新不要）
- 更新実行時間: <500ms（コミット時間への影響最小化）
- エラー発生率: <1%（高い信頼性）

### 品質指標
- コードカバレッジ: >95%
- テスト実行時間: <30秒
- ドキュメント整合性: 100%

## 🔒 セキュリティ考慮事項

### ファイルアクセス制御
- CODEMAP.yamlへの適切な書き込み権限
- バックアップファイルの安全な管理
- 一時ファイルの適切な削除

### エラー情報の取り扱い
- 機密情報を含むエラーメッセージの制御
- ログ出力での情報漏洩防止
- デバッグ情報の適切なレベル設定

## 📚 運用要件

### 監視・ログ
- CODEMAP更新成功/失敗の記録
- パフォーマンスメトリクスの収集
- 異常検知とアラート機能

### 保守性
- 設定による機能のオン/オフ切り替え
- 更新ルールのカスタマイズ機能
- トラブルシューティング用診断機能

---

## 🎯 実装ガイドライン

### B20準拠要件
1. **3コミット開発サイクル**: 仕様書→テスト→実装の段階的開発
2. **DDD層分離**: ドメイン純粋性とレイヤー依存方向の厳守
3. **品質ゲート統合**: 既存アーキテクチャリンターとの連携

### コーディング規約
- **統合インポート管理**: `scripts.`プレフィックス必須
- **共通コンポーネント活用**: `shared_utilities.console`使用
- **テスト仕様書連携**: `@pytest.mark.spec("SPEC-CODEMAP-AUTO-UPDATE-001")`

この仕様書に基づき、段階的実装を開始します。
