Init Claude

init-claude

任意のリポジトリに Claude Code の .claude/ 体系を初期セットアップする。 日本語運用・目的別 Agent（カテゴリ分割）・Rules 整備・スキル導入・委譲による main 消費抑制・ model 配分・SessionStart hooks・implement-issue-tree の動作前提まで一括構成する。

既存の .claude/ が存在するリポジトリには update-claude を使用する。

使い方

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

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

前提条件

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

フロー

Step 1: 対象リポジトリを調査する

対象ディレクトリのルートを特定し、以下を把握する。

# 言語・フレームワーク検出
ls <target-repo>/
cat <target-repo>/package.json 2>/dev/null || true
cat <target-repo>/Cargo.toml 2>/dev/null || true
cat <target-repo>/pyproject.toml 2>/dev/null || true

# ディレクトリ構成（最大深度 3）
find <target-repo> -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' | head -80

# ビルド・テストコマンドの確認
cat <target-repo>/Makefile 2>/dev/null | head -40 || true
cat <target-repo>/.github/workflows/*.yml 2>/dev/null | head -60 || true

調査で把握する情報:

• 主要言語・フレームワーク（Rust / TypeScript / Python など）
• ディレクトリ構成（crates/ / src/ / packages/ など）
• ビルドコマンド（cargo build / npm run build / make など）
• テストコマンド（cargo test / npm test / pytest など）
• 既存の .claude/ ディレクトリの有無

既存の .claude/ がある場合は update-claude スキルへ誘導して処理を中断する。

Step 2: 構成案を設計してユーザーに提示・承認を得る

調査結果をもとに以下の構成案を設計する。

Agents 設計方針

技術レイヤ別の builder Agent と横断サポート Agent を組み合わせる。

• 実装系 Agent はリポの技術レイヤに合わせてカスタマイズする （例: Rust workspace → クレート別 builder / TypeScript monorepo → パッケージ別 builder）
• 複雑な横断判断・アーキテクチャ設計は opus または fable（fable は Opus 上位の最上位 tier。特に大規模設計や複雑な横断判断が必要な場面に限定する）
• 調査・生成・レビューは sonnet
• 機械的集計・frontmatter lint・ドキュメント更新は haiku

Rules 設計方針

以下を標準として生成し、リポ特性に応じて追加する。

Skills 設計方針

npx skills add Fandhe-AI/agent-cli-skills で以下を導入する。

• create-commit — Conventional Commits コミット作成
• create-pr — PR 作成
• create-issue — Issue 作成
• implement-issue — Issue 単体実装
• implement-issue-tree — Issue ツリー並列実装
• implement-review — レビュー対応
• implement-review-pr — PR レビュー対応
• update-docs — CLAUDE.md 更新
• comment-code — code-comment-style.md 規約に従ったコメント・ドキュメンテーションコメントの追加・補強

hooks 設計方針

• SessionStart: 日本語・委譲・Conventional Commits・--no-verify 禁止のリマインダー
• PostToolUse: 言語に応じた自動整形（Rust: rustfmt / TypeScript: biome または prettier / Python: ruff など）

model 配分表（CLAUDE.md に記載）

上記の構成案（Agent 一覧・Rules 一覧・model 配分・hooks・Skills）をユーザーに提示し承認を得てから次の Step に進む。

Step 3: .claude/ 一式を生成する

承認後、以下の順で生成する。対象リポに dotclaude-via-temp ルール（_/dotclaude/ 経由）がない場合は 対象リポの .claude/ へ直接書き込んで良い。

サブステップの実行順は 3-1（CLAUDE.md 骨子）→ 3-2（agents/）→ 3-3（rules/）→ 3-4（settings.json）→ 3-5（スキル導入）→ 3-6（CLAUDE.md 確定） の順とする。CLAUDE.md は Agent・Rules・Skills の一覧を参照するため、3-1 では確定済みの項目（Overview / Repository Structure 等）のみ記載し、Sub-agents / Rules / Current Skills の各表は 3-2〜3-5 完了後に 3-6 で実体に合わせて確定する。

3-1. CLAUDE.md の骨子を生成する

対象リポのルートに CLAUDE.md の骨子を作成する。以下のセクションを含めるが、Sub-agents / Rules / Current Skills は 3-2〜3-5 で実体を生成するまで見出しのみ（プレースホルダ）とし、内容は 3-6 で確定する。

# CLAUDE.md

## Overview
リポジトリの概要（調査結果から生成）

## Repository Structure
ディレクトリ構成ツリー（3〜4階層）

## 委譲方針（必読）
main の役割・パスベース切り替え表・model 配分表

## Sub-agents
（3-1 では見出しのみ。カテゴリ別 Agent 一覧の表は 3-2 完了後に 3-6 で確定する）

## Rules
（3-1 では見出しのみ。ルールファイル一覧の表は 3-3 完了後に 3-6 で確定する）
（標準セット: delegation / delegation-impl / coding-<lang> / security / japanese-style /
  conventional-commits / code-comment-style / out-of-scope-tracking）

## Current Skills
（3-1 では見出しのみ。導入済みスキル一覧は 3-5 完了後に 3-6 で確定する）

## Conventions
Conventional Commits・セキュリティレビュー・日本語出力・ユーザー承認フローなど

## hooks（settings.json）
SessionStart / PostToolUse の説明

3-2. agents/ を生成する

Step 2 で設計した Agent を .claude/agents/<category>/<name>.md に作成する。 各 Agent は以下の frontmatter を持つ。

---
name: <name>
description: "<役割の説明>"
model: <haiku|sonnet|opus>
tools: [必要最小限のツール]
---

frontmatter のキーは Claude Code の subagent 定義仕様に従い name を使う （subagent_type は Agent ツール呼び出し時のパラメータ名であり、定義キーではない）。

3-3. rules/ を生成する

Step 2 で設計したルールを .claude/rules/ に作成する。 delegation.md・delegation-impl.md は本リポの実例（Fandhe-AI/agent-cli-skills）を参考に 対象リポのパス構成に合わせてカスタマイズする。

code-comment-style.md と out-of-scope-tracking.md は以下の雛形骨子をベースに、 対象リポの言語・構成に合わせて調整して生成する。

code-comment-style.md の雛形骨子

# コメント規約

## 目的

後続の読み手（Claude を含む）は渡された情報からしか判断できない。
コメントはパッケージ・サービス・モジュール視点での役割と、他ファイル・他サービスとの
文脈を埋め込み、ファイル単体で文脈が伝わる状態にする。

## 何を書くか

- このファイル・モジュール・関数の役割と責務境界（1〜2行要約をドキュメンテーションコメントで）
- 呼び出し元・呼び出し先の文脈（「〜から呼ばれる」「〜を呼んで〜を返す」）
- 他ファイル・他サービスとの契約（インターフェース・プロトコル・前提条件）
- 非自明な前提・副作用・エラー処理の意図

## 何を書かないか

- コードを読めば分かる逐語説明（`i++  // i をインクリメント` 等）
- 陳腐化しやすい実装詳細の重複（コードと2重に管理しない）

## ドキュメンテーションコメントの形式

言語慣習に従う（Rust: `///`、TypeScript/JavaScript: `/** */`、Python: docstring 等）。
パッケージ・モジュール・公開 API の入口には必ず1〜2行の役割要約を付ける。

out-of-scope-tracking.md の雛形骨子

# 実装対象外の追跡規約

## 目的

実装・レビュー中にスコープ外と判断した事項を放置しない。
後で埋もれるのを防ぐため、発見したタイミングで Issue に記録して追跡可能にする。

## フロー

1. **検出**: 実装・レビュー中にスコープ外と判断した事項をメモする
2. **既存 Issue の確認**:

gh issue list --search "${KEYWORD}" --state open

   キーワードは `"${KEYWORD}"` でクォートして渡す。
3. **ユーザーに承認を得る**: 既存 Issue への追記か新規起票かをユーザーと確認する
4. **記録**:
   - 既存 Issue がある場合:

gh issue comment "${ISSUE_NUMBER}" --body "$(cat <<'EOF' （本文をここに記述） EOF )"

   - 存在しない場合: `create-issue-tree` または `create-issue` で適切な親 Issue 配下に起票
5. **元 PR・レビューに切り出し先を記録**: コメントまたは PR 本文に切り出し先の Issue 番号を記載する

## 注意

- ユーザーの承認なしに勝手に Issue を起票しない
- スコープ外の修正を現在の PR に混入させない（別 Issue・別 PR で対処する）

3-4. settings.json を生成する

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

言語に応じた PostToolUse 自動整形フックを提案し、ユーザーが希望する場合は追加する。

セキュリティ注意事項:

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

3-5. スキルを導入する

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 が生成されることを確認する。

3-6. CLAUDE.md を確定する

3-2〜3-5 で生成した Agent・Rules・導入スキルの実体をもとに、3-1 で見出しのみとした Sub-agents / Rules / Current Skills の各表を実際の一覧（subagent_type / model / ファイル名 / 導入スキル名）で埋めて確定する。未存在の項目を列挙したまま残さない。

Step 4: implement-issue-tree の動作前提を確認する