update-claude

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

update-claude

既存の

.claude/

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

.claude/

が存在しないリポジトリには

init-claude

を使用する。

Diagnose the existing

.claude/

system, present the differences from the ideal state (Japanese operation, category-based Agents, Rules maintenance, delegation rules, model allocation, SessionStart hooks, implement-issue-tree prerequisites), and only supplement the differences after user approval. Confirm before overwriting existing Agents, Rules, and CLAUDE.md.

Use

init-claude

for repositories where

.claude/

does not exist.

使い方

Usage

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

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

update-claude [path-to-target-repository]

If the path is omitted, the current directory is targeted.

前提条件

Prerequisites

対象リポジトリに
```
.claude/
```
ディレクトリが存在すること
```
gh
```
CLI がインストールされ、認証済みであること（
```
gh auth status
```
で確認）
```
npx
```
が使用できること（
```
npx skills add
```
によるスキル補完に使用）

The
```
.claude/
```
directory exists in the target repository
The
```
gh
```
CLI is installed and authenticated (check with
```
gh auth status
```
)
```
npx
```
is available (used for skill supplementation via
```
npx skills add
```
)

フロー

Flow

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

Step 1: Investigate the target repository and existing .claude/

bash

undefined

bash

undefined

.claude/ の存在確認

Check for existence of .claude/

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

ls <target-repo>/.claude/ 2>/dev/null || echo ".claude/ does not exist"

既存 Agent の一覧

List existing Agents

find <target-repo>/.claude/agents -name "*.md" 2>/dev/null | sort

既存 Rules の一覧

List existing Rules

find <target-repo>/.claude/rules -name "*.md" 2>/dev/null | sort

既存 Skills の一覧

List existing Skills

ls <target-repo>/.claude/skills/ 2>/dev/null | sort

hooks 確認

Check hooks

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

cat <target-repo>/.claude/settings.json 2>/dev/null || echo "No settings.json"

CLAUDE.md の確認

Check CLAUDE.md

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

cat <target-repo>/CLAUDE.md 2>/dev/null | head -80 || echo "No CLAUDE.md"

skills-lock の確認

Check skills-lock

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

cat <target-repo>/skills-lock.json 2>/dev/null | head -30 || echo "No skills-lock.json"

implement-issue-tree workflow の確認

Check implement-issue-tree workflow

ls <target-repo>/.claude/workflows/implement-issue-tree.js 2>/dev/null || echo "workflow js なし"


`.claude/` が存在しない場合は `init-claude` を案内して処理を中断する。

ls <target-repo>/.claude/workflows/implement-issue-tree.js 2>/dev/null || echo "No workflow js"


If `.claude/` does not exist, guide the user to use `init-claude` and interrupt processing.

Step 2: 理想形との差分を診断する

Step 2: Diagnose differences from the ideal state

以下の観点で現状を診断し、ギャップ一覧を作成する。

Diagnose the current state from the following perspectives and create a gap list.

2-1. Agent 診断

2-1. Agent Diagnosis

診断項目	確認内容
カテゴリ分割	research / implement / testing / quality / docs のカテゴリ分割があるか
技術レイヤ別 builder	リポの技術レイヤに対応した builder Agent が存在するか
model 配分	実装・調査=sonnet / 機械的=haiku / 横断判断=opus または fable（fable は Opus 上位の最上位 tier）が守られているか
最小権限	Agent の `tools` リストが必要最小限か
委譲 Agent	skill-author / agent-author / rules-author / docs-writer に相当する Agent があるか

Diagnosis Item	Check Content
Category Division	Is there category division into research / implement / testing / quality / docs?
Tech Layer-specific Builders	Are there builder Agents corresponding to the repo's technical layers?
Model Allocation	Is the allocation followed: implementation/research=sonnet / mechanical tasks=haiku / cross-cutting decisions=opus or fable (fable is the top tier above Opus)?
Least Privilege	Is the Agent's `tools` list kept to the minimum necessary?
Delegation Agents	Are there Agents equivalent to skill-author / agent-author / rules-author / docs-writer?

2-2. Rules 診断

2-2. Rules Diagnosis

診断項目	確認内容
delegation.md	調査モードの委譲原則・パスベース切り替え表があるか
delegation-impl.md	作成・編集モードの委譲マッピングがあるか
coding 規約	リポの主要言語に対応したコーディング規約があるか
security.md	OWASP Top 10・秘密情報混入防止の記載があるか
japanese-style.md	日本語出力スタイルの記載があるか
conventional-commits.md	Conventional Commits 詳細規約があるか
code-comment-style.md	コメント規約（役割・呼び出し文脈・責務境界の埋め込み方針）があるか
out-of-scope-tracking.md	スコープ外事項の追跡規約（Issue 確認→ユーザー承認→起票フロー）があるか

Diagnosis Item	Check Content
delegation.md	Does it contain delegation principles for research mode and path-based switching table?
delegation-impl.md	Does it contain delegation mappings for creation/edit mode?
Coding Standards	Are there coding standards corresponding to the repo's main language?
security.md	Does it include OWASP Top 10 and prevention of sensitive information inclusion?
japanese-style.md	Does it describe Japanese output style?
conventional-commits.md	Does it include detailed Conventional Commits rules?
code-comment-style.md	Does it include comment rules (policy for embedding role, invocation context, responsibility boundaries)?
out-of-scope-tracking.md	Does it include rules for tracking out-of-scope items (Issue confirmation → user approval → ticketing flow)?

2-3. Skills 診断

2-3. Skills Diagnosis

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
```
規約に従うコメント追加・補強スキル）

List skills available via

npx skills add Fandhe-AI/agent-cli-skills

that are not included in

skills-lock.json

Mandatory Skills (to be supplemented if missing):

```
create-commit
```
,
```
create-pr
```
,
```
create-issue
```
```
implement-issue
```
,
```
implement-issue-tree
```
```
implement-review
```
,
```
implement-review-pr
```
```
update-docs
```
```
comment-code
```
(skill to add/reinforce comments according to
```
code-comment-style.md
```
rules)

2-4. hooks 診断

2-4. hooks Diagnosis

診断項目	確認内容
SessionStart	日本語・委譲・Conventional Commits・--no-verify 禁止のリマインダーがあるか
PostToolUse	言語に応じた自動整形フックがあるか

Diagnosis Item	Check Content
SessionStart	Does it include reminders for Japanese language use, delegation, Conventional Commits compliance, and prohibition of --no-verify?
PostToolUse	Is there an auto-formatting hook corresponding to the language?

2-5. CLAUDE.md 診断

2-5. CLAUDE.md Diagnosis

診断項目	確認内容
委譲方針	パスベース切り替え表・model 配分表があるか
Sub-agents 一覧	カテゴリ別 Agent の表があるか
Rules 一覧	ルールファイルの表があるか
Current Skills	導入済みスキル一覧があるか

Diagnosis Item	Check Content
Delegation Policy	Does it include a path-based switching table and model allocation table?
Sub-agents List	Does it include a table of category-based Agents?
Rules List	Does it include a table of rule files?
Current Skills	Does it include a list of installed skills?

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

2-6. implement-issue-tree Prerequisite Diagnosis

bash

gh auth status

bash

gh auth status

sub_issues は issue 番号付き

issues/{n}/sub_issues

のみ有効（リポジトリ直下に

sub_issues are only valid with issue numbers in

issues/{n}/sub_issues

(there is no sub_issues endpoint directly under the repository). If existing issues exist, specify the number to verify connectivity

sub_issues エンドポイントは存在しない）。既存 issue があれば番号を指定して疎通確認する

(if no issue has been created, only gh auth status will be used for prerequisite confirmation)

（issue が未作成なら gh auth status のみで前提確認とする）

—

gh api "repos/<owner>/<repo>/issues/<既存issue番号>/sub_issues" 2>&1 | head -5 ls <target-repo>/.claude/workflows/implement-issue-tree.js 2>/dev/null


- gh auth の認証状態
- sub_issues API の応答（既存 issue 番号を指定。404 = GitHub Apps が有効でない可能性。
  なお `repos/{owner}/{repo}/sub_issues` というリポジトリ直下のエンドポイントは存在しないため使わない）
- workflow js の存在

gh api "repos/<owner>/<repo>/issues/<existing-issue-number>/sub_issues" 2>&1 | head -5 ls <target-repo>/.claude/workflows/implement-issue-tree.js 2>/dev/null


- gh auth authentication status
- sub_issues API response (specify existing issue number. 404 = possibility that GitHub Apps is not enabled.
  Note: Do not use the repository-level endpoint `repos/{owner}/{repo}/sub_issues` as it does not exist)
- Existence of workflow js

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

Step 3: Present gap list to user for approval

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

undefined

Present the gap list in the following format.

undefined

.claude/ 診断結果

.claude/ Diagnosis Results

不足・追補が必要な項目

Items requiring supplementation/enhancement

Agents

<カテゴリ>/<Agent名>.md: <不足理由>
...

<category>/<Agent-name>.md: <reason for deficiency>
...

Rules

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

delegation.md: Does not exist
coding-<lang>.md: No standards for main language (<lang>)
...

Skills（npx skills add で補完可能）

Skills (supplementable via npx skills add)

<スキル名>: skills-lock.json に含まれていない
...

<skill-name>: Not included in skills-lock.json
...

hooks

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

SessionStart: No SessionStart hook in settings.json
PostToolUse: No auto-formatting hook for <lang>
...

CLAUDE.md

委譲方針表: パスベース切り替え表がない
...

Delegation Policy Table: No path-based switching table
...

implement-issue-tree 前提

implement-issue-tree Prerequisites

workflow js: .claude/workflows/implement-issue-tree.js が存在しない
...

workflow js: .claude/workflows/implement-issue-tree.js does not exist
...

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

Existing Assets (items requiring overwrite confirmation)

以下は既に存在します。変更する場合は個別に確認します。

<ファイルパス>: <現在の状態の要約>


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

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

The following already exist. Confirm individually if changes are needed.

<file-path>: <summary of current state>


**Do not start supplementation/changes without user approval.**

Approval granularity:
- "Supplement all" → Proceed to Step 4
- "Supplement specific items" → Confirm targets then proceed to Step 4
- "Overwrite existing files" → Confirm individually before overwriting

Step 4: 差分を追補する

Step 4: Supplement differences

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

Only supplement approved items. Only modify existing files that have received overwrite confirmation.

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

4-1. Add missing Agents

.claude/agents/<category>/<name>.md

に追加する。対象リポに

dotclaude-via-temp

ルール（

_/dotclaude/

経由）が存在する場合はそのルールに従う。存在しない場合は

.claude/

へ直接書き込んで良い。

yaml

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

frontmatter のキーは Claude Code の subagent 定義仕様に従い

name

を使う（

subagent_type

は Agent ツール呼び出し時のパラメータ名であり、定義キーではない）。

Add to

.claude/agents/<category>/<name>.md

. If the target repo has a

dotclaude-via-temp

rule (via

_/dotclaude/

), follow that rule. If not, you can write directly to

.claude/

yaml

---
name: <name>
description: "<description of role (including trigger words)>"
model: <haiku|sonnet|opus|fable>
tools: [minimum necessary tools]
---

Follow Claude Code's subagent specification for frontmatter keys, using

name

(

subagent_type

is a parameter name for Agent tool calls, not a definition key).

4-2. 不足 Rules を追加する

4-2. Add missing 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/ を生成する」に記載の雛形骨子を参照して生成する。生成時は対象リポの言語・構成（ドキュメンテーションコメント形式・ディレクトリ構成等）に合わせて調整する。

Add to

.claude/rules/

. Customize

delegation.md

and

delegation-impl.md

according to the target repo's path structure, referencing examples from Fandhe-AI/agent-cli-skills.

code-comment-style.md

and

out-of-scope-tracking.md

are missing, generate them by referring to the template outline described in "3-3. Generate rules/" of the init-claude skill. Adjust according to the target repo's language and structure (documentation comment format, directory structure, etc.) when generating.

4-3. 不足スキルを補完する

4-3. Supplement missing Skills

bash

cd <target-repo>
npx skills add Fandhe-AI/agent-cli-skills

skills-lock.json

が更新されることを確認する。

bash

cd <target-repo>
npx skills add Fandhe-AI/agent-cli-skills

Confirm that

skills-lock.json

is updated.

4-4. hooks を追補する

4-4. Supplement hooks

settings.json

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

json

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

セキュリティ注意事項:

```
command
```
の値に API キー・トークン・パスワードを埋め込まない
ユーザー入力をそのまま
```
command
```
に展開しない

PostToolUse 自動整形フックは言語のツール存在確認後に提案し、ユーザーが希望する場合のみ追加する。

Add/update SessionStart hook in

settings.json

json

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '<repo-name>: Communicate in Japanese / Delegate tasks to subagents to reduce main model consumption / Strictly follow Conventional Commits (--no-verify prohibited) / Implement implement-issue only after plan approval'"
          }
        ]
      }
    ]
  }
}

Security Notes:

Do not embed API keys, tokens, or passwords in the
```
command
```
value
Do not directly expand user input into
```
command
```

Propose PostToolUse auto-formatting hooks after verifying the existence of language-specific tools, and only add them if the user wishes.

4-5. CLAUDE.md を更新する

4-5. Update CLAUDE.md

不足セクション（委譲方針表・Sub-agents 一覧・Rules 一覧・model 配分表・Current Skills）を追補する。 既存セクションを上書きする場合は承認済み項目のみ変更する。

Supplement missing sections (delegation policy table, Sub-agents list, Rules list, model allocation table, Current Skills). Only modify approved items when overwriting existing sections.

4-6. implement-issue-tree の前提を整備する

4-6. Prepare implement-issue-tree prerequisites

workflow js が存在しない場合の案内:

named workflow（

{name: "implement-issue-tree"}

）として呼ばない場合は

.claude/workflows/

への配置自体が不要で、Workflow ツールの

scriptPath

に

.claude/skills/implement-issue-tree/script/implement-issue-tree.js

を直接指定すればよい。

named workflow として配置する場合は

cp

ではなく相対 symlink を使用する。

cp

で配置すると symlink が実体ファイルに置き換わり、

npx skills add

による更新が named workflow に届かなくなる。

bash

undefined

Guidance if workflow js does not exist:

If not called as a named workflow (

{name: "implement-issue-tree"}

), placement in

.claude/workflows/

is not necessary at all—you can directly specify

.claude/skills/implement-issue-tree/script/implement-issue-tree.js

in the Workflow tool's

scriptPath

If placing as a named workflow, use a relative symlink instead of

cp

. If placed via

cp

, the symlink will be replaced with an actual file, and updates via

npx skills add

will not reach the named workflow.

bash

undefined

.claude/workflows/ への配置（named workflow として使う場合のみ）

Place in .claude/workflows/ (only if using as a named workflow)

mkdir -p <target-repo>/.claude/workflows/

既に symlink が存在する場合はそのままにする（実体ファイルを上書きしない）

Leave existing symlinks as-is (do not overwrite actual files)

if [ ! -e "<target-repo>/.claude/workflows/implement-issue-tree.js" ]; then

.claude/workflows/ から見た相対パスで symlink を作成する

ln -s ../skills/implement-issue-tree/script/implement-issue-tree.js
<target-repo>/.claude/workflows/implement-issue-tree.js else echo "既に存在する（symlink か実体かを確認: ls -la <target-repo>/.claude/workflows/implement-issue-tree.js）" fi


sub_issues API が使用できない場合は GitHub Apps の有効化をユーザーに案内する。

if [ ! -e "<target-repo>/.claude/workflows/implement-issue-tree.js" ]; then

Create symlink with relative path from .claude/workflows/

ln -s ../skills/implement-issue-tree/script/implement-issue-tree.js
<target-repo>/.claude/workflows/implement-issue-tree.js else echo "Already exists (check if symlink or actual file: ls -la <target-repo>/.claude/workflows/implement-issue-tree.js)" fi


If the sub_issues API cannot be used, guide the user to enable GitHub Apps.

Step 5: 追補結果を報告する

Step 5: Report supplementation results

報告項目:

追補したファイル一覧と変更内容
スキップした項目と理由
implement-issue-tree の動作前提の充足状況
ユーザーへの次のアクション案内（手動設定が必要な項目など）

Report Items:

List of supplemented files and changes made
Skipped items and reasons
Satisfaction status of implement-issue-tree prerequisites
Guidance on next actions for the user (items requiring manual setup, etc.)

検証

Verification

bash

undefined

bash

undefined

追補後のファイル一覧確認

Check list of files after supplementation

find <target-repo>/.claude -type f | sort

CLAUDE.md の存在確認

Check existence of CLAUDE.md

ls <target-repo>/CLAUDE.md

skills-lock.json の更新確認

Check update to skills-lock.json

cat <target-repo>/skills-lock.json 2>/dev/null | head -20

implement-issue-tree の前提確認

Check implement-issue-tree prerequisites

ls <target-repo>/.claude/workflows/implement-issue-tree.js 2>/dev/null || echo "workflow js: 未配置" gh auth status

undefined

ls <target-repo>/.claude/workflows/implement-issue-tree.js 2>/dev/null || echo "workflow js: Not placed" gh auth status

undefined

注意事項

Notes

```
.claude/
```
が存在しないリポジトリには
```
init-claude
```
を案内して処理を中断する
既存ファイルの上書きはユーザーの個別承認後のみ実施する
ユーザーの診断承認なしに変更を開始しない
```
settings.json
```
の
```
command
```
にトークン・シークレットをハードコードしない
```
--no-verify
```
を含むコマンドを hooks に仕込まない
```
npx skills add
```
が失敗した場合はエラーメッセージを表示してユーザーに手動手順を案内する
対象リポに
```
dotclaude-via-temp
```
ルールがある場合はそのルールに従う（ない場合は直接書き込み可）
Agent の
```
tools
```
リストは最小権限原則に従い必要なもののみ列挙する
セキュリティ問題（秘密情報の混入・インジェクションリスク）を発見した場合は追補を中断してユーザーに警告する

For repositories where
```
.claude/
```
does not exist, guide the user to use
```
init-claude
```
and interrupt processing
Only overwrite existing files after individual user approval
Do not start changes without user approval for diagnosis
Do not hardcode tokens or secrets in
```
settings.json
```
```
command
```
Do not include commands with
```
--no-verify
```
in hooks
If
```
npx skills add
```
fails, display the error message and guide the user through manual steps
Follow the
```
dotclaude-via-temp
```
rule if it exists in the target repo (if not, direct writing is allowed)
Follow the principle of least privilege when listing Agent
```
tools
```
—only include necessary items
If security issues (sensitive information inclusion, injection risks) are found, interrupt supplementation and warn the user