Update Claude

update-claude

既存の .claude/ 体系を診断し、理想形（日本語運用・カテゴリ別 Agent・Rules 整備・ 委譲ルール・model 配分・SessionStart hooks・implement-issue-tree 前提）との差分を提示して ユーザー承認後に差分のみ追補する。既存の Agent・Rules・CLAUDE.md は上書き前に確認を取る。

.claude/ が存在しないリポジトリには init-claude を使用する。

使い方

update-claude [対象リポジトリのパス]

パスを省略した場合はカレントディレクトリを対象とする。

前提条件

• 対象リポジトリに .claude/ ディレクトリが存在すること
• gh CLI がインストールされ、認証済みであること（gh auth status で確認）
• npx が使用できること（npx skills add によるスキル補完に使用）。skills CLI は固定版（SKILLS_CLI_VERSION）で実行する。値と更新手順は「skills CLI のバージョン固定と更新手順」節を参照
• readlink コマンドが使用できること（workflow js symlink の stale/dangling 判定に使用。command -v readlink で事前確認し、利用できない環境では該当処理を中断する）

フロー

Step 1: 対象リポジトリと既存 .claude/ を調査する

# .claude/ の存在確認
ls <target-repo>/.claude/ 2>/dev/null || echo ".claude/ が存在しない"

# 既存 Agent の一覧
find <target-repo>/.claude/agents -name "*.md" 2>/dev/null | sort

# 既存 Rules の一覧
find <target-repo>/.claude/rules -name "*.md" 2>/dev/null | sort

# 既存 Skills の一覧
ls <target-repo>/.claude/skills/ 2>/dev/null | sort

# hooks 確認
cat <target-repo>/.claude/settings.json 2>/dev/null || echo "settings.json なし"

# CLAUDE.md の確認
cat <target-repo>/CLAUDE.md 2>/dev/null | head -80 || echo "CLAUDE.md なし"

# skills-lock の確認
cat <target-repo>/skills-lock.json 2>/dev/null | head -30 || echo "skills-lock.json なし"

# implement-issue-tree workflow の確認（-L で symlink 判定し、readlink でターゲットも確認する）
# readlink の存在を事前確認する。利用できない環境では判定を中断する
LINK="<target-repo>/.claude/workflows/implement-issue-tree.js"
EXPECTED_TARGET="../skills/implement-issue-tree/scripts/implement-issue-tree.js"
if ! command -v readlink >/dev/null 2>&1; then
  echo "エラー: readlink コマンドが見つからない。workflow js の stale/dangling 判定を中断する"
elif [ -L "$LINK" ]; then
  echo "symlink ターゲット: $(readlink "$LINK")（期待値: $EXPECTED_TARGET）"
  [ -e "$LINK" ] || echo "警告: dangling symlink（参照先が存在しない）"
elif [ -e "$LINK" ]; then
  echo "実体ファイルとして存在する（symlink ではない）"
else
  echo "workflow js なし"
fi

.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-issue
• implement-issue・implement-issue-tree
• implement-review・implement-review-pr
• update-docs
• comment-code（code-comment-style.md 規約に従うコメント追加・補強スキル）

2-4. hooks 診断

2-5. CLAUDE.md 診断

2-6. implement-issue-tree 前提診断

gh auth status
# sub_issues は issue 番号付き `issues/{n}/sub_issues` のみ有効（リポジトリ直下に
# sub_issues エンドポイントは存在しない）。既存 issue があれば番号を指定して疎通確認する
# （issue が未作成なら gh auth status のみで前提確認とする）
gh api "repos/<owner>/<repo>/issues/<既存issue番号>/sub_issues" 2>&1 | head -5

# workflow js の symlink 検証（ターゲット一致・参照先解決も確認する）
LINK="<target-repo>/.claude/workflows/implement-issue-tree.js"
EXPECTED_TARGET="../skills/implement-issue-tree/scripts/implement-issue-tree.js"
if ! command -v readlink >/dev/null 2>&1; then
  echo "エラー: readlink コマンドが見つからない。workflow js の symlink 検証を中断する"
elif [ -L "$LINK" ]; then
  echo "symlink ターゲット: $(readlink "$LINK")（期待値: $EXPECTED_TARGET）"
  [ -e "$LINK" ] || echo "警告: dangling symlink"
else
  echo "workflow js: 未配置または非 symlink"
fi

• gh auth の認証状態
• sub_issues API の応答（既存 issue 番号を指定。404 = GitHub Apps が有効でない可能性。 なお repos/{owner}/{repo}/sub_issues というリポジトリ直下のエンドポイントは存在しないため使わない）
• workflow js の存在・ターゲット一致（stale でないか）・参照先解決（dangling でないか）

Step 3: ギャップ一覧をユーザーに提示して承認を得る

以下の形式でギャップ一覧を提示する。

## .claude/ 診断結果

### 不足・追補が必要な項目

#### Agents
- [ ] <カテゴリ>/<Agent名>.md: <不足理由>
- ...

#### Rules
- [ ] delegation.md: 存在しない
- [ ] coding-<lang>.md: 主要言語（<lang>）対応規約が存在しない
- ...

#### Skills（npx skills add で補完可能）
- [ ] <スキル名>: skills-lock.json に含まれていない
- ...

#### hooks
- [ ] SessionStart: settings.json に SessionStart hook がない
- [ ] PostToolUse: <lang> の自動整形フックがない
- ...

#### CLAUDE.md
- [ ] 委譲方針表: パスベース切り替え表がない
- ...

#### implement-issue-tree 前提
- [ ] workflow js: .claude/workflows/implement-issue-tree.js が存在しない
- [ ] workflow js: symlink のターゲットが期待値と異なる（stale。旧パスを指したまま）
- [ ] workflow js: symlink の参照先が消失している（dangling）
- ...

### 既存資産（上書き確認が必要な項目）

以下は既に存在します。変更する場合は個別に確認します。
- <ファイルパス>: <現在の状態の要約>

ユーザーの承認なしに追補・変更を開始しない。

承認の粒度:

• 「全て追補する」→ Step 4 に進む
• 「項目を絞って追補する」→ 対象を確認してから Step 4 に進む
• 「既存ファイルを上書きする場合」→ 上書き前に個別確認を取る

Step 4: 差分を追補する

承認された項目のみ追補する。既存ファイルは上書き確認を取った項目のみ変更する。

4-1. 不足 Agent を追加する

.claude/agents/<category>/<name>.md に追加する。 対象リポに dotclaude-via-temp ルール（_/dotclaude/ 経由）が存在する場合はそのルールに従う。 存在しない場合は .claude/ へ直接書き込んで良い。

---
name: <name>
description: "<役割の説明（発火トリガー語を含める）>"
model: <haiku|sonnet|opus|fable>
tools: [必要最小限のツール]
---

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. 不足スキルを補完する

cd <target-repo>
# skills CLI (vercel-labs/skills) は固定版でのみ実行する（未固定 npx はレジストリ
# 乗っ取り時の任意コード実行経路になる）。正の定義箇所・更新手順は下記
# 「skills CLI のバージョン固定と更新手順」節を参照。
SKILLS_CLI_VERSION="1.5.23"   # 正の定義箇所。更新手順は下記節を参照
npx --yes "skills@${SKILLS_CLI_VERSION}" add Fandhe-AI/agent-cli-skills || {
  echo "エラー: skills@${SKILLS_CLI_VERSION} の実行が失敗しました（該当版の不存在・レジストリ障害等、原因は問わない）。未固定 npx skills add へのフォールバックは行わない。原因を確認してから再実行する。" >&2
  exit 1
}

skills-lock.json が更新されることを確認する。

4-4. hooks を追補する

settings.json に SessionStart hook を追加・更新する。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '<リポ名>: 日本語でやりとり / 作業は subagent へ委譲し main 消費を抑える / Conventional Commits 厳守 (--no-verify 禁止) / implement-issue は計画承認後に実装'"
          }
        ]
      }
    ]
  }
}

セキュリティ注意事項:

• 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 に届かなくなる。