Claude Code

• できる：リポ全体の読解 / ファイル編集 / シェル実行 / テスト作成 / PR 用の diff 作成
• できる：CLAUDE.md による規約学習、MCP でブラウザ・DB・GitHub を触る
• できない：GUI 単独での操作、ChatGPT のような Web UI（基本ターミナル）
• 課金：Claude Pro / Max、または API 従量。長時間セッションは $ が飛ぶので `/cost` で監視

• 効く：既存プロジェクトのリファクタ・バグ修正・テスト追加を任せたい人
• 効く：ターミナルに違和感がなく、diff レビューで承認する運用が回せる人
• 効かない：ゼロからの新規プロジェクト立ち上げだけを高速でやりたい人（Codex Cloud か Lovable の方が速い）
• 効かない：コマンドライン操作を避けたい人（Cursor などの IDE 統合型の方が合う）

1. Node.js 18+ を確認（`node -v`）。古ければ `nvm install 20`
2. グローバルインストール
3. 対象リポジトリの直下で `claude` を起動、ブラウザが開いて Anthropic ログイン
4. 初回は `/init` を実行し、リポ用の `CLAUDE.md` を生成させる

npm install -g @anthropic-ai/claude-code
cd your-project
claude
# 起動後、プロンプトで:
/init

実際に手が動く感覚を掴むためのシナリオ。任意の JS/TS プロジェクトで実行してみてください。

1. `claude` を起動し、まず `/init` で CLAUDE.md を作らせる
2. 計画モードに入る：`Shift+Tab` を 2 回押して plan モード（読み取り専用で計画を出す）
3. 以下のプロンプトを投げる
4. 計画に納得したら `Shift+Tab` で通常モードに戻し「実装して」と返す
5. diff が出るごとに `y` / `n` で承認。テストが赤なら「テストが通るまで直して」と返すだけで自走する
6. 終わったら `/cost` で消費を確認、`/clear` して次のタスクへ

プロンプト例：
「src/utils/date.ts の formatDate に、null / undefined を渡した時は 空文字 を返すようにしたい。
 まず該当箇所と既存テストを読み、変更計画を出して。実装は待って。」

プロジェクト直下に置くと、以後のセッションで自動的に読まれる規約ファイル。ここが薄いとエージェントの精度が一気に落ちる。

# Project: <名前>

## 実行コマンド
- 開発: `pnpm dev`
- テスト: `pnpm test`
- Lint / 型: `pnpm lint && pnpm typecheck`

## コーディング規約
- TypeScript strict、`any` 禁止
- コンポーネントは関数コンポーネント + hooks のみ
- スタイルは Tailwind、生 CSS は禁止

## 触ってはいけない領域
- `src/legacy/**`（凍結中）
- `prisma/migrations/**`（手書き禁止、`prisma migrate` 経由）

## タスクの進め方
1. 変更前に必ずテストの実行結果を報告
2. 破壊的変更は plan モードで確認を取ってから
3. コミットメッセージは Conventional Commits

① バグ再現テスト
「Issue #142 のバグを再現する最小テストを追加して。まだ実装は直さないで。」

② 大規模リネーム
「`UserProfile` を `MemberProfile` に全リネーム。型 / import / テスト / ストーリー全部。 plan モードで計画を先に。」

③ 依存アップデート
「package.json の依存を最新の minor に上げて、breaking がありそうなら plan に列挙して。」

④ ドキュメント生成
「src/api の各エンドポイントの JSDoc を、実装を読んで補完して。Response 型は type から拾って。」

⑤ レビュー依頼
「/review で HEAD の変更をレビューして。設計上の懸念とテスト不足を優先で。」

スキル = 特定の作業手順やアウトプット規約をあらかじめ AI に教え込んでおく『別紙マニュアル』。毎回同じ品質・同じフォーマットで出力させたい業務は全部これに切り出す。

• 品質の安定化：フォーマット指定を毎回書かなくても、同じ品質で出てくる
• コスト（トークン）節約：CLAUDE.md と違い『必要になった時だけ』読み込まれる。100 個作っても普段は 0 トークン
• 資産化：チーム / プロジェクトごとに配布・共有できる。書いた分だけ AI が育つ
• 例：議事録・週報・YouTube 台本・プレスリリース・ログ抽出・リリース手順 など『定型業務』全般

• 【CLAUDE.md】常に読まれる。使用言語 / パッケージマネージャ / テストコマンド / コード規約 / 触ってはいけない領域 など『前提』だけ
• 【CLAUDE.md】毎メッセージでトークンを消費するので 200 行以内が推奨。肥大化させないことが精度とコスト両方に効く
• 【Skills】呼び出し時だけ読まれる。議事録 / 台本 / 週報 / 変換スクリプト / デプロイ手順 など『特定目的の一連の作業』
• 【Skills】普段のコストに乗らないので、チェックリスト・NG 例・Few-shot 例まで細かく書いて OK

連携パターン例：週次レポートを PR 化するとき、CLAUDE.md にコミット規約（feat:/fix: など）を置き、Skill には『週報 MD 生成 → ブランチ作成 → コミット → PR 作成』の手順を置く。共通規約を守りつつ専用手順を正確に実行できる。

1. Claude Code に自然文で依頼：『YouTube の台本を作るスキルを作って。出力にはタイトル案と構成案を含めて』
2. `.claude/skills/<スキル名>/skill.md` が自動生成される。これが本体（別紙マニュアル）
3. エディタで `skill.md` を開く。上部の YAML ヘッダー（name / description）と本文（実際の指示）を実出力を見ながら微調整
4. 呼び出して回す → 気に入らない部分を書き足す、を繰り返して『育てる』

スコープ（配置場所）で使える範囲が変わる：

• グローバル（Personal）：`~/.claude/skills/` — どの作業フォルダから起動しても使える。個人の資産に
• プロジェクト：`./.claude/skills/` — その特定のリポでのみ。チームで git 管理して共有できる

• 自動発動：普段通り『男性一人暮らしの簡単レシピで台本を作って』と話しかける。AI が skill.md の description を読み取り、必要なスキルを自動で適用
• 手動発動：`/<スキル名>`（例：`/youtube-script`）で直接実行。『絶対にこのルールで動いてほしい』時に確実

1. 本文に変数を埋める：`$0`（1 つ目の引数）、`$1`（2 つ目）を書き込む
2. 省略時の安全網を書く：『もし $0 が指定されていない場合は、動画の長さを私に尋ねてください』を追記
3. ヘッダーに `argument_hints` を設定：スラッシュ実行時に『次に何を入れるか』のヒントが出る
4. 実行：`> /youtube-script 10分 デモ解説` のようにスペース区切りで条件を渡す

---
name: youtube-script
description: YouTubeの台本構成案を作成するスキル。動画の長さと方向性を指定して呼び出す。
argument_hints:
  - 動画の長さ
  - 動画の方向性
---

以下の条件でYouTubeの台本を作成してください。

- 動画の尺は **$0** に収まるようにしてください。
- 動画の方向性は **$1** としてください。

※もし $0 が指定されていない場合は、動画の長さを私に尋ねてください。
※もし $1 が指定されていない場合は、動画の方向性を私に尋ねてください。

.claude/skills/youtube-script/
 ├── skill.md                 ← 本体（振り分け役）
 └── references/              ← 参照用フォルダ
     ├── technical_exp.md     ← 技術解説用の詳細ルール
     ├── vlog.md              ← Vlog 用の詳細ルール
     └── talk_show.md         ← トーク系用の詳細ルール

1. スキルフォルダ直下に `references/` を作り、ジャンルごとに MD を作成
2. 各 MD にそのジャンル特有の構成案・注意点・品質チェックリストを詳細に書く（普段は読まれないのでいくら書いても OK）
3. `skill.md` 本体には『引数に応じて、どの MD を読むか』の振り分けだけ書く

指定された動画の方向性（$1）に応じて、以下のサポート資料を必ず読み込み、そのルールに従って台本を作成してください。

- 方向性が「技術解説」の場合：`references/technical_exp.md` を参照
- 方向性が「Vlog」の場合：`references/vlog.md` を参照
- 方向性が「トーク系」の場合：`references/talk_show.md` を参照

• default：ファイル書き込みとコマンド実行で毎回確認（学習中はこれ）
• acceptEdits：ファイル編集は自動承認、コマンドだけ確認（慣れてきたら）
• plan：読み取りのみ。計画立案 / 影響調査に使う。破壊的作業前に必ず一度これ
• bypassPermissions：全自動。CI やヘッドレスでのみ、隔離環境で使う

# ヘッドレスで CI から呼ぶ最小例
claude -p "lint エラーを全部直して PR 用の diff だけ出して" \
  --permission-mode acceptEdits --output-format json

MCP サーバを繋ぐと、Claude Code が GitHub / ブラウザ / DB / 社内 API を直接操作できるようになる。設定は `~/.claude/mcp.json`。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

• ○ タスクは 1 セッション 1 目的に絞る。終わったら `/clear`
• ○ 長丁場は `/compact` で会話を要約して圧縮
• ○ CLAUDE.md は「規約」より「実行方法と触ってはいけない場所」を厚めに
• × 「全部よしなに直して」系の丸投げ → 意図しない変更が広範囲に入る
• × 承認せず放置 → ターミナル閉じるとコンテキスト消失
• × `bypassPermissions` を普段使い → 破壊的操作の事故率が跳ね上がる

起動：      claude                # 対話モード
            claude -p "..."       # ヘッドレス（1 発実行）
            claude -c             # 前回セッションを継続

スラッシュ： /init      # CLAUDE.md を生成
            /clear     # 会話をリセット
            /compact   # 会話を要約圧縮
            /review    # HEAD の変更をレビュー
            /model     # 使用モデル切替
            /cost      # 累積コスト表示
            /permissions  # 権限モード変更
            /mcp       # MCP サーバ確認

キー：      Shift+Tab     # モード切替（default→acceptEdits→plan）
            Ctrl+C        # 中断
            Esc           # 現在の応答を止める

install → login → 最初の1コマンドまで。すべて公式の推奨手順です。