update-claude
既存の .claude/ 体系を診断し、理想形(日本語運用・カテゴリ別 Agent・Rules 整備・
委譲ルール・model 配分・SessionStart hooks・implement-issue-tree 前提)との差分を提示して
ユーザー承認後に差分のみ追補する。既存の Agent・Rules・CLAUDE.md は上書き前に確認を取る。
.claude/ が存在しないリポジトリには init-claude を使用する。
使い方
パスを省略した場合はカレントディレクトリを対象とする。
前提条件
- 対象リポジトリに
.claude/ディレクトリが存在すること ghCLI がインストールされ、認証済みであること(gh auth statusで確認)npxが使用できること(npx skills addによるスキル補完に使用)。skillsCLI は固定版(SKILLS_CLI_VERSION)で実行する。値と更新手順は「skills CLI のバージョン固定と更新手順」節を参照readlinkコマンドが使用できること(workflow js symlink の stale/dangling 判定に使用。command -v readlinkで事前確認し、利用できない環境では該当処理を中断する)
フロー
Step 1: 対象リポジトリと既存 .claude/ を調査する
.claude/ が存在しない場合は init-claude を案内して処理を中断する。
Step 2: 理想形との差分を診断する
以下の観点で現状を診断し、ギャップ一覧を作成する。
2-1. Agent 診断
2-2. Rules 診断
2-3. Skills 診断
npx skills add Fandhe-AI/agent-cli-skills で導入できるスキルのうち、
skills-lock.json に含まれていないものを列挙する。
必須スキル(不足していれば追補対象):
create-commit・create-pr・create-issueimplement-issue・implement-issue-treeimplement-review・implement-review-prupdate-docscomment-code(code-comment-style.md規約に従うコメント追加・補強スキル)
2-4. hooks 診断
2-5. CLAUDE.md 診断
2-6. implement-issue-tree 前提診断
- gh auth の認証状態
- sub_issues API の応答(既存 issue 番号を指定。404 = GitHub Apps が有効でない可能性。
なお
repos/{owner}/{repo}/sub_issuesというリポジトリ直下のエンドポイントは存在しないため使わない) - workflow js の存在・ターゲット一致(stale でないか)・参照先解決(dangling でないか)
Step 3: ギャップ一覧をユーザーに提示して承認を得る
以下の形式でギャップ一覧を提示する。
ユーザーの承認なしに追補・変更を開始しない。
承認の粒度:
- 「全て追補する」→ Step 4 に進む
- 「項目を絞って追補する」→ 対象を確認してから Step 4 に進む
- 「既存ファイルを上書きする場合」→ 上書き前に個別確認を取る
Step 4: 差分を追補する
承認された項目のみ追補する。既存ファイルは上書き確認を取った項目のみ変更する。
4-1. 不足 Agent を追加する
.claude/agents/<category>/<name>.md に追加する。
対象リポに dotclaude-via-temp ルール(_/dotclaude/ 経由)が存在する場合はそのルールに従う。
存在しない場合は .claude/ へ直接書き込んで良い。
model: には対象リポの CLAUDE.md にある model 配分表(2-1 診断が確認する
最上位 tier / 標準 tier / 軽量 tier → alias の対応)に従って具体的な alias(haiku・sonnet・opus・fable 等、
導入先が別 alias を採用していればその値)を書く。対応表が無い場合は Step 2 の gap として先に記録し、
alias を決めてから追加する(対応表に無い alias を frontmatter へ直書きしない)。
frontmatter のキーは Claude Code の subagent 定義仕様に従い name を使う
(subagent_type は Agent ツール呼び出し時のパラメータ名であり、定義キーではない)。
4-2. 不足 Rules を追加する
.claude/rules/ に追加する。
delegation.md・delegation-impl.md は Fandhe-AI/agent-cli-skills の実例を参考に
対象リポのパス構成に合わせてカスタマイズする。
code-comment-style.md と out-of-scope-tracking.md が不足している場合は、
init-claude スキルの「3-3. rules/ を生成する」に記載の雛形骨子を参照して生成する。
生成時は対象リポの言語・構成(ドキュメンテーションコメント形式・ディレクトリ構成等)に合わせて調整する。
4-3. 不足スキルを補完する
skills-lock.json が更新されることを確認する。
4-4. hooks を追補する
settings.json に SessionStart hook を追加・更新する。
セキュリティ注意事項:
commandの値に API キー・トークン・パスワードを埋め込まない- ユーザー入力をそのまま
commandに展開しない
PostToolUse 自動整形フックは言語のツール存在確認後に提案し、ユーザーが希望する場合のみ追加する。
4-5. CLAUDE.md を更新する
不足セクション(委譲方針表・Sub-agents 一覧・Rules 一覧・model 配分表・Current Skills)を追補する。 既存セクションを上書きする場合は承認済み項目のみ変更する。
4-6. implement-issue-tree の前提を整備する
workflow js が存在しない場合の案内:
named workflow({name: "implement-issue-tree"})として呼ばない場合は .claude/workflows/ への配置自体が不要で、Workflow ツールの scriptPath に .claude/skills/implement-issue-tree/scripts/implement-issue-tree.js を直接指定すればよい。
named workflow として配置する場合は cp ではなく相対 symlink を使用する。cp で配置すると symlink が実体ファイルに置き換わり、npx skills add による更新が named workflow に届かなくなる。
symlink は readlink で現在のターゲットを検証し、期待ターゲットと異なる場合(stale)・参照先が消失している場合(dangling)は張り替える。実体ファイル(非 symlink)は上書きしない。対象リポに dotclaude-via-temp ルールがある場合はそのルールに従い _/dotclaude/ 経由で配置する(ない場合は ln -s 直接作成でも可)。readlink が利用できない環境では stale 判定が正しく行えず(空の CURRENT_TARGET により正常な symlink を stale と誤判定しうる)、そのまま張り替え処理へ進むと意図せず既存 symlink を書き換える危険があるため、command -v readlink で事前確認し、利用できない場合は自動張り替えを中断してユーザーに手動対応を案内する。
sub_issues API が使用できない場合は GitHub Apps の有効化をユーザーに案内する。
Step 5: 追補結果を報告する
報告項目:
- 追補したファイル一覧と変更内容
- スキップした項目と理由
- implement-issue-tree の動作前提の充足状況
- ユーザーへの次のアクション案内(手動設定が必要な項目など)
skills CLI のバージョン固定と更新手順
Why: npx skills add をバージョン未固定で実行すると、npx はローカルキャッシュに無い場合レジストリのその時点の最新版を確認なしで即時取得・実行する。skills(vercel-labs/skills)パッケージが乗っ取られた場合、これは任意コード実行の経路になる。exact 版(X.Y.Z。dist-tag・^/~ レンジは禁止)への固定が信頼アンカーになる。
固定版の決め方:
npm view skills versionで現在の latest を確認するnpm view skills repository.urlがvercel-labs/skillsであることを確認するnpm view skills time --json等で公開日時が不自然でないことを確認する
更新手順:
- Step 4-3 フェンス内の
SKILLS_CLI_VERSIONを更新する(このスキル内での正の定義箇所はここ 1 箇所のみ) node --test skills/update-claude/tests/*.mjsで exact semver・実行行の固定を検証する- 1 リポジトリで実際に実行し、差分が正常であることを確認する
chore(update-claude): skills CLI を X.Y.Z へ更新でコミットする- 同じ
skillsCLI を固定するinit-claude/sync-skills-lockの同名節も同時更新することを推奨する(値の同期は必須ではないが、乖離した場合はどちらかの節にその旨を記録する)
既知の乖離(記録): 本節の SKILLS_CLI_VERSION の値(1.5.23)は、sync-skills-lock/SKILL.md・sync-skills-lock/scripts/skills-lock-update.sh が固定する SKILLS_CLI_VERSION の値(1.5.22)と異なる(init-claude は本節と同一の値で同期済み)。各スキルは独立した固定版として運用しており同期は必須ではないため、意図的な乖離として記録する。次回いずれかを更新する際は、この乖離が解消したか維持されたかを本行で更新する。
fail-closed: 固定版が解決できない場合(該当版の不存在・レジストリ障害等どの原因でも)は npx が非ゼロ終了し停止する。未固定 npx skills add へのフォールバック再試行は行わない。
検証
注意事項
.claude/が存在しないリポジトリにはinit-claudeを案内して処理を中断する- 既存ファイルの上書きはユーザーの個別承認後のみ実施する
- ユーザーの診断承認なしに変更を開始しない
settings.jsonのcommandにトークン・シークレットをハードコードしない--no-verifyを含むコマンドを hooks に仕込まないnpx skills addが失敗した場合はエラーメッセージを表示してユーザーに手動手順を案内するskillsCLI は固定版で実行する。固定版の決め方・更新手順は「skills CLI のバージョン固定と更新手順」節を参照- 対象リポに
dotclaude-via-tempルールがある場合はそのルールに従う(ない場合は直接書き込み可) - Agent の
toolsリストは最小権限原則に従い必要なもののみ列挙する - セキュリティ問題(秘密情報の混入・インジェクションリスク)を発見した場合は追補を中断してユーザーに警告する


