sync-project-docs は何をしますか?
Claude Codeのプロジェクトレベルコンテキストファイルを監査・更新します。CLAUDE.md、スキル、メモリについては自律的に実行し、設定については明示的なユーザー認可が必要なため提案として提示します。
フェーズ1 — 状況把握
プロジェクトがgitを使用している場合:
git log --oneline -20
git status --short
次に、git diff HEAD~5 -- <以下に挙げる主要ファイル> を実行して、最近のインフラストラクチャの変更を確認します。
gitリポジトリがない場合は、ディレクトリ構造と主要ファイルを直接読み取ります。
以下のうち、存在するものを確認します:
| 確認項目 | 例 |
|---|---|
| パッケージ/依存関係設定 | package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, requirements.txt, Gemfile |
| コマンド | Makefile, justfile, scripts/, package.json scripts, taskfile.yml |
| インフラストラクチャ | docker-compose.yml, fly.toml, render.yaml, Procfile, vercel.json, k8s/ |
| アプリ設定 | config.*, settings.*, config/, application.yml |
| envテンプレート | .env.example, .env.template, .env.sample |
目標:完了した作業、進行中の作業、および変更された主要ファイルを把握すること。
フェーズ2 — CLAUDE.mdの監査と更新
すべてのプロジェクトレベル指示ファイルを確認します:
ls CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md .claude/rules/ 2>/dev/null
CLAUDE.mdが存在しない場合:sub-skills/init/SKILL.mdにある init スキルを呼び出し、その後続行します。
CLAUDE.mdが存在する場合、それを読み込み、各セクションをフェーズ1の情報源と照合します:
コマンド — 実際のコマンドソースと比較します。変更されたコマンドは修正し、有用な新しいコマンドを追加し、削除されたものは削除します。
アーキテクチャ/構造 — 説明されているモジュールと主要ファイルを、ディスク上に実際に存在するものと比較します。新しい追加があった場合は追加し、削除または名前変更されたものは削除します。
設定/env変数 — 実際の設定ファイルと比較します。新しいランタイム関連の設定を追加し、古くなったものは削除または修正します。
制約とハマりどころ — 文書化された制約が最近の作業で解決されたかどうかを確認します。
envテンプレート:設定に必要なすべての変数がリストされているか確認します。変数が欠けていると、新しいセットアップが失敗します。
@import参照:@path/to/file の行をスキャンし、インポートされた各ファイルがまだ存在するか確認します。インポートが見つからないと、コンテキストの読み込みが静かに失敗します。
サイズ:ファイルが200行を超えている場合、フラグを立てます — それを超えると遵守率が低下し、コンテキストコストが増加します。詳細を .claude/rules/ のトピックファイルに移動することを提案します。
.claude/rules/:このディレクトリが存在する場合、パススコープのルールファイルが現在のコードベースと一致しないコマンド、モジュール名、またはファイルパスを参照していないか確認します。古くなったものは修正するかフラグを立てます。
CLAUDE.local.md:これが存在する場合、CLAUDE.mdと同じようにチェックします。これはgitignoredされた個人用補足ファイルであり、同様に古くなる可能性があります。
外科的に作業します:古くなったものは更新し、正確な内容はそのままにします。将来のClaudeセッションによって読み込まれます。
フェーズ3 — プロジェクトスキルの監査
ls .claude/skills/ 2>/dev/null
各スキルを読みます。2つのカテゴリがあります:
インフラストラクチャ結合型スキル(実行、デプロイ、マイグレーション、CI、統合)は、具体的なもの(コマンド、サービス、ポート、env変数、ファイルパス)を参照します。それぞれをフェーズ1の情報と照合します:
- 参照されているコマンドはまだ存在しますか?
- サービス名、ポート、URLはまだ一致していますか?
- env変数は設定にまだ存在しますか?
- ファイルパスとモジュール名はまだ有効ですか?
小さな不一致は直接修正します。実行/起動スキルを大幅に作り直す必要がある場合(新しい起動手順、主要なサービスの変更)、最初に質問します:
「実行スキルが大幅に古くなっているようです。/run-skill-generator でゼロから再生成しますか(カスタムのハマりどころは失われる可能性があります)、それとも古いセクションを手動で書き換えますか?」
実行スキルが存在せず、起動が簡単でない場合:利用可能であれば /run-skill-generator を提案し、そうでなければ /run をフォールバックとして提案します。
プロセス/ワークフロースキル(PRテンプレート、コミットスタイル):gitログが説明されたプロセスの変更を示唆する場合のみチェックし、それ以外はそのままにします。
フェーズ4 — メモリ
メモリパスはgitリポジトリのルート(またはリポジトリ外の場合は pwd)から派生します:
REPO=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
echo "$HOME/.claude/projects/$(echo "$REPO" | sed 's|/|-|g')/memory/"
メモリが存在する場合:consolidate-memory を呼び出します。
存在しない場合:作成する前に質問します —
「プロジェクトメモリはまだありません。自動メモリはすでにオンになっているので、Claudeは時間の経過とともに構築していきますが、今このコードベースの主要な情報をシードして、次のセッションがすぐに軌道に乗るようにしますか?」
「はい」の場合:将来のセッションが導出に時間を無駄にするような、自明でない事実をシードします:
- 驚くべき制約(並行処理モデル、バージョン固定、予期しないデフォルト)
- 現在進行中の作業とその理由
- コードに組み込まれた自明でない決定
MEMORY.md を、1行に1エントリの簡潔なインデックスとして作成します。詳細なメモは別のトピックファイル(例:architecture.md、constraints.md)に保存します — MEMORY.md はセッションコンテキストウィンドウに収まるよう200行未満に保ちます。
フェーズ5 — 設定
.claude/settings.json を確認し、存在しなくなったスクリプトやコマンドを参照する古いフックがないかチェックします。
頻繁に使用され、プロンプトなしで許可しても安全な読み取り専用コマンド(テストランナー、リンター、ヘルスチェック、git log、git diff)を特定します。
settings.jsonには書き込まず、提案として提示します。以下を参照します:
update-config:権限、env変数の追加、またはフックの修正を行うfewer-permission-prompts:実際のトランザクション履歴から権限を発見する
フェーズ6 — コンパクト化
すべての調査結果がディスクに保存されました。まとめる前に、ユーザーに /compact コマンドを実行して新しい状態から開始するよう促します。
サマリー
変更のサマリーを出力します:
## プロジェクト同期完了
**CLAUDE.md**: <変更内容、または「変更不要」>
**スキル**: <更新内容、または「正確」>
**メモリ**: <統合 / シード / 「変更なし」>
**設定提案**: <提案する許可、または「追加なし」>
**Git状態**: <未コミットファイル + 進行中の作業、1文>
変更を確認するには `git diff` を実行してください。