コード自記述

コードリポジトリの自記述構造を生成および維持し、Claude Code の階層的ロードメカニズムを利用して段階的なコンテキスト理解を実現します。

言語規則

• 中国語と英語の質問をサポート
• 中国語での統一された回答
• CLAUDE.md ファイルの内容は中国語を使用
• ソースファイルのヘッダーコメントは中国語を使用

トリガー条件

• ユーザーはプロジェクトに AI フレンドリーなコード記述を追加する必要がある
• ユーザーはコード変更後に記述を更新する必要がある
• ユーザーは記述の網羅率と正確性を確認する必要がある
• キーワード：「自記述」、「モジュール記述」、「CLAUDE.md 生成」、「self-describe」

核心概念

自分形アーキテクチャ

Claude Code の階層的ロードメカニズム（ファイルを検索すると、そのディレクトリの CLAUDE.md が自動的にロードされる）を利用して、3層の自記述構造を通じて AI のコード理解を向上させます。

プロジェクトルート CLAUDE.md ← グローバルビュー
    │
    ├── src/modules/auth/CLAUDE.md ← モジュールビュー
    │   ├── auth.service.ts  ← ファイルヘッダー INPUT/OUTPUT/POS
    │   ├── auth.guard.ts
    │   └── auth.controller.ts
    │
    └── src/modules/user/CLAUDE.md ← モジュールビュー
        ├── user.service.ts
        └── user.repository.ts

AI が5層目のファイルを検索すると、すでに前の4層の CLAUDE.md が自動的にロードされており、モジュール全体の理解が非常に明確になります。

三層記述体系

コード追跡アノテーションとの関係

自記述と DevDocs 追跡アノテーションは異なる次元で機能し、両者は共存し補完し合います。

実行モード

/code-self-describe                         → インテリジェント検出モード
/code-self-describe --init                  → 初期化：プロジェクトの完全な自記述構造を生成
/code-self-describe --init src/modules/auth → 指定されたモジュールを初期化
/code-self-describe --update                → 更新：コード変更に基づいて記述を更新
/code-self-describe --update src/user.ts    → 指定されたファイルとそのモジュールを更新
/code-self-describe --audit                 → 監査：記述の鮮度と正確性を確認

モード比較

インテリジェント検出フロー

プロジェクトにモジュールレベルの CLAUDE.md がすでに存在するかどうかを検出
        │
        ├── 無 → 自動的に init モードに入る
        │
        └── 有 → コード変更があるかどうかを検出
                │
                ├── 未同期の変更がある → update モードを推奨
                └── 変更なし → audit モードを推奨

Init モード

ワークフロー

1. プロジェクト構造をスキャン
   ├── 言語/フレームワークを識別 (package.json, go.mod, Cargo.toml など)
   ├── ディレクトリ構造パターンを識別 (src/, lib/, modules/ など)
   └── ビジネスモジュールの境界を識別
           │
           ▼
2. プロジェクトルート CLAUDE.md を強化
   ├── 既存の場合：モジュール記述セクションを追加（既存の内容は上書きしない）
   └── 存在しない場合：基本的な CLAUDE.md を生成
           │
           ▼
3. モジュールごとに CLAUDE.md を生成
   ├── モジュール内のファイルのインポート/エクスポート関係を分析
   ├── モジュールの役割を識別（サービス層、データ層、インターフェース層など）
   ├── CLAUDE.md を生成（地位/ロジック/制約/ビジネスドメインリスト）
   └── ユーザーが各モジュールの記述を確認
           │
           ▼
4. ファイルごとにヘッダーコメントを生成
   ├── import/依存関係を分析 → INPUT
   ├── export/公開インターフェースを分析 → OUTPUT
   ├── ディレクトリの場所とモジュールの役割に基づいて → POS
   └── ファイルのヘッダーコメントを挿入
           │
           ▼
5. 記述リストレポートを生成

モジュールレベルの CLAUDE.md テンプレート

詳細なテンプレートと例は templates/claude-md-template.md を参照してください。

# <モジュール名>

## 地位
<システムにおける役割と位置、1〜2文>

## ロジック
<モジュールは何をするか、コア機能の説明、3〜5文>

## 制約
- <使用ルール>
- <依存関係の制限>

## ビジネスドメインリスト
| ファイル/サブモジュール | 职责 |
|-------------|------|
| `xxx.ts` | <职责描述> |

ソースファイルヘッダーコメント形式

多言語の例は templates/header-comment-examples.md を参照してください。

// INPUT: UserRepository (データアクセス), ValidatorService (検証)
// OUTPUT: createUser(), getUser(), updateUser() (ユーザー CRUD 操作)
// POS: ユーザーモジュールのコアサービス層、ユーザービジネスロジックを処理

コメントはファイルの先頭に配置する必要があり（import ステートメントの前）、AI がファイルのロードをヘッダーから開始するためです。

Update モード

ワークフロー

1. 変更範囲を検出
   ├── `git diff --name-only`（前回のコミットと比較）
   ├── またはユーザーが指定したファイル/ディレクトリ
   └── 影響を受けるモジュールを識別
           │
           ▼
2. 変更の影響を分析
   ├── ファイルレベル：INPUT/OUTPUT が変化したかどうか
   ├── モジュールレベル：モジュールの役割が変化したかどうか
   └── モジュール間：モジュール間の依存関係が変化したかどうか
           │
           ▼
3. ソースファイルのヘッダーコメントを更新
   ├── 変更されたファイルの INPUT/OUTPUT/POS を更新
   └── 手動で追加された追加のコメントを保持
           │
           ▼
4. モジュール CLAUDE.md を更新
   ├── ビジネスドメインリストを更新（ファイルの追加/削除）
   ├── ロジック記述を更新（モジュールの役割の変化など）
   └── 制約を更新（新しい依存関係ルールなど）
           │
           ▼
5. 更新を上位に伝播
   ├── サブモジュールの変更 → 親モジュールの CLAUDE.md を更新
   └── プロジェクトルート CLAUDE.md まで

更新伝播ルール

詳細なルールは templates/update-rules.md を参照してください。

• パブリックインターフェースが変更された場合にのみ上位に伝播（内部リファクタリングはトリガーしない）
• 自動/手動コンテンツを区別するためにマーク（<!-- auto-generated --> は自動生成された部分をマーク）
• 手動で記述された記述は変更しない

Audit モード

監査内容

1. すべての CLAUDE.md とソースファイルのヘッダーコメントをスキャン
2. 実際のコード状態と比較
3. 監査レポートを生成：
   ├── 記述が欠落しているモジュール/ファイル
   ├── 古い記述（コードが変更されたが記述が更新されていない）
   ├── 不正確な記述（INPUT/OUTPUT が実際と一致しない）
   └── 記述の網羅率統計

監査レポート形式（ターミナル出力）

📊 コード自記述監査レポート

網羅率:
  モジュールレベル CLAUDE.md: 8/12 (67%)
  ファイルヘッダーコメント:     45/62 (73%)

⚠️  記述の欠落:
  - src/modules/payment/CLAUDE.md (欠落)
  - src/services/cache.ts (ヘッダーコメントなし)

🔄 古い記述:
  - src/modules/user/CLAUDE.md (user.service.ts に deleteUser メソッドが追加されました)
  - src/auth/auth.guard.ts (INPUT に RoleService 依存関係がありません)

制約

生成制約

• [ ] CLAUDE.md ファイル名は大文字を使用する必要がある（Claude Code の規約）
• [ ] 既存のプロジェクトルート CLAUDE.md を上書きしない（追加またはマージ）
• [ ] モジュールレベルの CLAUDE.md は実際のコード分析に基づいて生成する必要がある
• [ ] ヘッダーコメントは実際の import/export 分析に基づいて生成する必要がある
• [ ] 空のディレクトリまたは構成ディレクトリに対して CLAUDE.md を生成しない
• [ ] サードパーティの依存関係ディレクトリに対して記述を生成しない（node_modules, vendor など）

更新制約

• [ ] 実際に変更されたファイルのみを更新する
• [ ] 手動で記述された記述内容は変更しない（マークで区別）
• [ ] 上位への伝播はパブリックインターフェースが変更された場合にのみトリガーされる
• [ ] 更新前に既存の記述を読み取る必要がある

監査制約

• [ ] 監査モードではファイルを変更しない
• [ ] 網羅率統計を生成する必要がある
• [ ] 古い記述の具体的な理由を明記する必要がある

範囲制約

• [ ] 隠しディレクトリを無視する（.git, .vscode, .idea など）
• [ ] ビルド成果物を無視する（dist/, build/, pycache/ など）
• [ ] 依存関係ディレクトリを無視する（node_modules/, vendor/, Pods/ など）
• [ ] テストディレクトリの CLAUDE.md 生成を無視する（テストファイルはヘッダーコメントを生成）
• [ ] パラメータでスキャン範囲を指定可能

Skill 連携

参考資料

• claude-md-template.md - モジュールレベルの CLAUDE.md テンプレート
• header-comment-examples.md - 多言語ヘッダーコメントの例
• update-rules.md - 階層更新伝播ルール