テンプレートリポの最新をプロジェクトに取り込む。「テンプレートの最新を取り込んで」「テンプレートを同期して」「スキルを更新して」 「テンプレートをアップデートして」などのリクエストで使用する。
インストールする前に、エージェントに与えられる指示の中身を確認できます。
ファイルを3カテゴリに分けて扱う:
保護カテゴリを設けている理由: テンプレリポ側の docs/ 配下（docs/templates/ 以外）にはスタブ／プレースホルダーのひな形が置かれている。これを無条件で上書きすると、プロジェクトが自動生成・手動編集した設計書・API仕様書・要件定義がテンプレートのスタブで破壊される。過去の事故（PR #59）ではこれで openapi.yaml / api-spec.md / architecture.md / db-design.md 等が空スタブ化した。
| ファイル | 理由 |
|---|---|
CLAUDE.md（ルート） | プロジェクト固有設定 |
.claude/settings.json | プロジェクト固有権限設定 |
.claude/settings.local.json | プロジェクト固有権限設定 |
mkdocs.yml | プロジェクト固有ナビゲーション |
README.md | プロジェクト固有の説明 |
spec-map.yml | プロジェクト固有のSpec管理 |
CHANGELOG.md | プロジェクト固有の変更履歴 |
.github/workflows/ci.yml | generate-ci.pyで生成済み |
.github/demo-screenshots/ | テンプレートリポ固有のデモ画像 |
以下のパスは、プロジェクトが init-spec / draft-spec / spec-all / implement-spec 等のスキルで生成・編集する成果物。テンプレ側に同名ファイル（スタブ）があっても、ローカルに既に存在する場合は上書きしない。ローカルに無ければ新規作成のみ許可する。
| パスパターン | 内容 |
|---|---|
docs/** （ただし docs/templates/** を除く） | プロジェクトの要件定義・設計書・API仕様・テスト仕様・品質ゲート・ホームページ・CSS等 |
domains/**（ただし domains/_template/** を除く） | ドメイン別の実装計画・ドキュメント |
interfaces/**（ただし interfaces/_template/** を除く） | リポ間連携インターフェース定義 |
tasks/**（ただし tasks/.gitkeep を除く） | 作業状態・セッション履歴・lessons |
impl-plans/** | 実装プラン（作業中の一時ファイル） |
DESIGN_INTENT.md | auto-review 用の設計意図メモ |
判定の優先順位: 除外 > 保護 > 同期。除外パスは同期対象にしない。保護パスはローカルに存在すれば同期対象にしない。それ以外のテンプレ側ファイルは全て同期（上書き）する。
docs/templates/ は同期対象。 テンプレート定義そのもののSingle Source of Truthなので、上書きで最新化する。
保護リストにないファイル（.claude/**, ci-templates/**, docs/templates/** 等）はスキップしてはいけない。
判断に迷ったら保護側に倒す。プロジェクト固有コンテンツを誤って上書きする方が、テンプレ更新が遅れるよりも被害が大きい。
.claude/CLAUDE.mdの「テンプレートリポ」からURLを取得する（URLが未設定の場合はユーザーに確認）。
OWNER_REPO=$(echo "<URL>" | sed -E 's#.+[:/]([^/]+/[^/]+?)(\.git)?$#\1#')
git remote add template "https://github.com/${OWNER_REPO}.git" 2>/dev/null \
|| git remote set-url template "https://github.com/${OWNER_REPO}.git"
git fetch template main
テンプレートの全ファイルを3カテゴリに分類する:
git ls-tree -r --name-only template/main | sort > /tmp/tpl_files.txt
git ls-tree -r --name-only HEAD | sort > /tmp/local_files.txt
comm -23 /tmp/tpl_files.txt /tmp/local_files.txt
comm -12 /tmp/tpl_files.txt /tmp/local_files.txt | while read f; do
t_hash=$(git rev-parse template/main:"$f" 2>/dev/null)
l_hash=$(git rev-parse HEAD:"$f" 2>/dev/null)
[ "$t_hash" != "$l_hash" ] && echo "$f"
done
この検出を省略してはいけない。 ローカルにあってテンプレートにないファイルのうち、 テンプレートのインフラ系パスに該当するものを検出する:
comm -13 /tmp/tpl_files.txt /tmp/local_files.txt | grep -E \
'^\.(claude|github)/|^ci-templates/|^docs/templates/|^domains/(_template|\.gitkeep)|^interfaces/(_template|\.gitkeep)|^tasks/(lessons|session-state|todo|\.gitkeep)|^logs/context/'
検出されたファイルは以下のいずれかに分類する:
2a・2bの結果を以下のルールで分類する:
判定用シェル例:
is_excluded() {
case "$1" in
CLAUDE.md|.claude/settings.json|.claude/settings.local.json) return 0 ;;
mkdocs.yml|README.md|spec-map.yml|CHANGELOG.md) return 0 ;;
.github/workflows/ci.yml) return 0 ;;
.github/demo-screenshots/*) return 0 ;;
esac
return 1
}
is_protected() {
case "$1" in
docs/templates/*) return 1 ;; # templates/ 配下は除外（同期対象）
docs/*) return 0 ;;
domains/_template/*) return 1 ;;
domains/*) return 0 ;;
interfaces/_template/*) return 1 ;;
interfaces/*) return 0 ;;
tasks/.gitkeep) return 1 ;;
tasks/*) return 0 ;;
impl-plans/*) return 0 ;;
DESIGN_INTENT.md) return 0 ;;
esac
return 1
}
テンプレートとの差分:
【追加】N件
追加: .claude/agents/coder/AGENT.md
...
【更新】N件
更新: .claude/skills/init-spec/SKILL.md
更新: docs/api/openapi.yaml
...
【構造変更】N件
移動: .claude/skills/skill-auditor/agents/*.md → .claude/agents/*/AGENT.md
削除: docs/templates/phase2/screen-design.md（テンプレートで廃止）
置換: domains/.gitkeep → domains/_template/CLAUDE.md
...
【保護スキップ】N件（ローカルに既存のため上書きしない）
保護: docs/api/openapi.yaml — プロジェクト固有（保護リスト）
保護: docs/design/architecture.md — プロジェクト固有（保護リスト）
保護: docs/requirements/overview.md — プロジェクト固有（保護リスト）
...
【除外】N件（スキップ）
除外: CLAUDE.md — プロジェクト固有
除外: mkdocs.yml — プロジェクト固有
...
取り込みますか？
# 追加 + 更新を一括処理
for f in <同期対象の全ファイル>; do
mkdir -p "$(dirname "$f")"
git show template/main:"$f" > "$f"
done
# 移動・リネーム・削除・.gitkeep置換で不要になったファイルを削除
for f in <削除対象>; do
rm -f "$f"
done
上書き後、テンプレートURLの <your-org> をプロジェクトの実際の値に戻す。
適用後に必ず全件検証を行う。
同期対象ファイル（除外・保護スキップ以外）がテンプレートと一致することを確認する。保護パスでスキップしたファイルは「元のローカル内容が保持されている」だけ確認（テンプレとの差分は当然発生するので DIFF として数えない）:
cat /tmp/tpl_files.txt | while read f; do
# 除外リストはスキップ
case "$f" in
CLAUDE.md|.claude/settings.json|.claude/settings.local.json|mkdocs.yml|README.md|spec-map.yml|CHANGELOG.md) continue ;;
.github/workflows/ci.yml|.github/demo-screenshots/*) continue ;;
esac
[ "$f" = ".claude/CLAUDE.md" ] && continue
[ "$f" = ".claude/skills/sync-template/SKILL.md" ] && continue
# 保護リスト該当で、ローカルに元々存在したファイルはスキップ（上書きしない想定）
if is_protected "$f" && [ -f "$f" ] && grep -qxF "$f" /tmp/local_files.txt; then
continue
fi
if [ -f "$f" ]; then
tpl=$(git show template/main:"$f" | md5)
cur=$(cat "$f" | md5)
[ "$tpl" != "$cur" ] && echo "DIFF: $f"
else
echo "MISSING: $f"
fi
done
MISSING または DIFF が1件でもあれば、原因を調査して修正する。 検証をパスするまでコミットしない。
保護パスの検証: 保護スキップしたファイルは、同期前後で md5 が変わらないことを別途確認する:
# 同期前に /tmp/local_hashes.txt を作っておく（手順1の直後推奨）
# md5 `cat "$f"` > /tmp/local_hashes.txt …など
# 同期後、保護スキップ対象が変わっていないことを確認
ci-templates/ が更新されました。
.github/workflows/ への反映が必要です。
「CI設定をci-templates/の最新版に合わせて更新して」と指示してください。
git remote remove template 2>/dev/null || true
git add -A
git commit -m "chore: sync template to latest"
.claude/rules/ はテンプレートに存在するファイルのみ上書き。プロジェクト固有で追加したルールファイルは削除しない.claude/CLAUDE.md は上書きOKだが、テンプレートURLのプレースホルダーは復元すること.github/workflows/ci.yml は直接上書きしない。generate-ci.py の再実行をユーザーに促すまだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
既存プロジェクトに新しいリポジトリを追加する。Workspaceにリポを追加した後、 CLAUDE.md・設計書・ドメイン構成を差分更新する。 「モバイルリポを追加した」「新しいリポを取り込んで」「リポを追加したので設計書を更新して」 「Workspaceにリポを足した」などのリクエストで使用する。 init-spec の移行モードではファイル存在チェックしか行わないため、 既存ドキュメントの内容を新リポに合わせて拡張するにはこのスキルを使う。
既存プロジェクトをサブエージェントで並列分析し、 精度の高い overview.md を生成する。init-spec の前処理として使う。 「既存プロジェクトを分析して」「コードベースを理解して設計書を作って」 「overview.mdを作って」などのリクエストで使用する。 ファイル数が200を超えるプロジェクトで特に有効。 200以下の場合は単一エージェントで全体を読む方が精度が高いため、 init-spec をそのまま実行することを提案する。
デザインの差し替え。ロジックは一切触らず見た目（HTML/CSS/テンプレート）だけを更新する。 「このデザインに差し替えて」「UIをFigmaの通りに変えて」「見た目だけ変えて」 「デザインを更新して」「CSSだけ直して」などのリクエストで使用する。 ロジック変更を伴う場合はrevise-specを使う。
ブラウザで画面を確認する。agent-browser CLI を使って画面のスクリーンショット撮影、 アクセシビリティツリー取得、フォーム操作、画面遷移などを行う。 「画面見て」「ブラウザ確認して」「スクショ撮って」「現状把握して」「画面開いて」 「ログインして確認して」「画面の状態を教えて」「UIを確認して」などのリクエストで使用する。 E2Eテストの作成・実行には gen-tests（Playwright）を使うこと。本スキルはテスト実行ではなく 「AIの目」としてブラウザを操作し、画面状態を把握するためのもの。
ClaudeDesign（claude.ai/design）とClaude Codeの連携。DesignSyncツールで デザインプロジェクトからプロトタイプHTML等を取得（インポート）、または ローカルのコンポーネントをデザインシステムプロジェクトへ同期（プッシュ）する。 「ClaudeDesignからデザインを取得して」「claude.ai/design のURLを取り込んで」 「デザインプロジェクトに同期して」「デザインシステムをプッシュして」 などのリクエスト、または claude.ai/design のURLが渡されたときに使用する。 取得したデザインのコード実装への適用は apply-design を使う。
詳細設計書の一括生成。2つのモードを自動判定する: (A) コード分析モード: 既存コードから詳細設計書を逆生成する（init-spec + spec-all 完了後） (B) 設計書ファーストモード: 要件定義書から詳細設計書を新規作成する（コードなし） 「詳細設計を作って」「設計書を完成させて」「実装に必要な設計書を全部作って」 「他のエンジニアに渡せる設計書にして」などのリクエストで使用する。