nakagon/dotfiles/claudemd-updater

CLAUDE.md Updater

サブモジュールやプロジェクトの CLAUDE.md を、実際のコードベースに基づいて実用的な内容に更新するスキル。

When to Use This Skill

• CLAUDE.md が古くなっている、汎用的すぎる、役に立っていない
• 新しいサブモジュールに CLAUDE.md を作成する
• プロジェクト構造やパターンが変わった後のドキュメント同期
• AI アシスタント向けガイドの品質改善

設計思想: 良い CLAUDE.md とは

原則

1. コードが真実: 実際のコードベースを探索して得た情報だけを書く
2. 重複排除: ルート CLAUDE.md や .claude/rules/ に既にある内容は書かない
3. 実用性重視: 「これを読めばすぐ作業開始できる」が基準
4. 簡潔: 200行以下を目標（長くても300行）

良い CLAUDE.md の構造（テンプレート）

# [サブモジュール名] - Claude Code ガイド
 
## 対象スコープ
-このファイルの対象範囲（他サブモジュールの文脈を持ち込まない）
 
## 技術スタック
-言語・フレームワーク・主要ライブラリとバージョン
 
## ディレクトリ構造
-主要ディレクトリとその役割（実際の構造に基づく）
 
## 開発コマンド
-サーバー起動、テスト実行、lint、マイグレーション等
-実際に動くコマンドを記載
 
## コーディング規約・パターン
-このサブモジュール固有の規約
-既存コードから読み取れるパターン
-ルート rules と重複しない内容のみ
 
## 注意事項
-破壊的操作の警告
-よくあるハマりポイント

悪い CLAUDE.md のアンチパターン

実行手順

Step 1: 現状分析

対象の CLAUDE.md を読み、以下を評価する：

1. 形式: Markdown か？ 読みやすいか？
2. 鮮度: 実際のコードベースと一致しているか？
3. 重複: ルート CLAUDE.md / .claude/rules/ と重複していないか？
4. 実用性: 作業開始時に役立つ情報があるか？
5. 不要な内容: 存在しないツール、汎用的な原則はないか？

Step 2: コードベース探索

対象サブモジュールから以下を抽出する：

探索対象:
1. pyproject.toml / package.json → 技術スタック・依存関係
2. ディレクトリ構造 → 主要ディレクトリとその役割
3. Makefile / docker-compose.yml → 開発コマンド
4. README.md → 既存ドキュメントとの整合性
5. 既存パターン → コードから読み取れる規約
6. .claude/rules/<submodule>/ → 既にルール化されている内容（重複を避ける）

重要: ファイル全体を読む必要はない。シンボル概要やディレクトリ構造で十分。

Step 3: 重複チェック

以下のファイルに既に書かれている内容は CLAUDE.md に含めない：

• CLAUDE.md（ルート） — モノレポ全体の運用ルール
• .claude/rules/global/ — 全サブモジュール共通ルール
• .claude/rules/<submodule>/ — サブモジュール固有ルール（詳細版）
• .agent/core/principles.md — 基本原則

CLAUDE.md はこれらへの「エントリーポイント」であり、内容の重複先ではない。

Step 4: ドラフト作成

テンプレートに沿って、探索結果を元にドラフトを作成する。

書くべきもの:

• 実際のコマンド（動作確認済み）
• 実際のディレクトリ構造
• このサブモジュール固有のパターン・注意点
• 他のルールファイルへの参照

書かないもの:

• 汎用的な開発フロー（Explore → Plan → Code）→ ルートに既にある
• AI の行動原則 → .claude/rules/global/ に既にある
• コミット規約 → .agent/core/principles.md に既にある
• 他のサブモジュールの情報

Step 5: ユーザーレビュー

ドラフトをユーザーに提示し、フィードバックを受けてから書き込む。

AI Assistant Instructions

このスキルが発動したら：

1. まず対象の CLAUDE.md を読む（存在しない場合は新規作成モード）
2. ルート CLAUDE.md と `.claude/rules/` を確認して重複対象を把握
3. コードベースを探索して実際の情報を収集（Serena / Glob / Grep を使用）
4. 現状の問題点を簡潔に報告
5. ドラフトを作成してユーザーに提示
6. 承認後に書き込み

Always:

• Markdown 形式で書く（XML/JSON は使わない）
• 実際のコードベースから情報を抽出する（推測しない）
• 200行以下を目標にする
• ルート/共通ルールと重複する内容は参照リンクに留める

Never:

• 汎用的な AI 原則や行動規範を含める
• 存在しないツールやワークフローを記載する
• ユーザーの承認なしに CLAUDE.md を上書きする
• ファイル全体の読み込みで情報収集する（シンボル探索を優先）