diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dab6311..39dd2e6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -142,3 +142,44 @@ repos: entry: uv run scripts/build_epub.py --lang vi pass_filenames: false files: ^(vi/.*\.md|scripts/build_epub\.py)$ + + # Japanese documentation checks + - repo: local + hooks: + - id: japanese-markdown-lint + name: japanese-markdown-lint + language: node + entry: markdownlint + args: ['--ignore', 'node_modules', '--ignore', '.venv', '--config', '.markdownlint.json'] + files: ^ja/.*\.md$ + additional_dependencies: ['markdownlint-cli'] + + - id: japanese-cross-references + name: japanese-cross-references + language: system + entry: python scripts/check_cross_references.py + pass_filenames: false + files: ^ja/.*\.md$ + + - id: japanese-mermaid + name: japanese-mermaid-syntax + language: system + entry: python scripts/check_mermaid.py + pass_filenames: false + files: ^ja/.*\.md$ + verbose: true + + - id: japanese-link-check + name: japanese-link-check + language: system + entry: python scripts/check_links.py + pass_filenames: false + files: ^ja/.*\.md$ + verbose: true + + - id: japanese-build-epub + name: japanese-build-epub + language: system + entry: uv run scripts/build_epub.py --lang ja + pass_filenames: false + files: ^(ja/.*\.md|scripts/build_epub\.py)$ diff --git a/README.md b/README.md index d456244..591f263 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ [![Version](https://img.shields.io/badge/version-2.1.119-brightgreen)](CHANGELOG.md) [![Claude Code](https://img.shields.io/badge/Claude_Code-2.1+-purple)](https://code.claude.com) -🌐 **Language / Ngôn ngữ / 语言 / Мова:** [English](README.md) | [Tiếng Việt](vi/README.md) | [中文](zh/README.md) | [Українська](uk/README.md) +🌐 **Language / Ngôn ngữ / 语言 / Мова:** [English](README.md) | [Tiếng Việt](vi/README.md) | [中文](zh/README.md) | [Українська](uk/README.md) | [日本語](ja/README.md) # Master Claude Code in a Weekend diff --git a/ja/.github/ISSUE_TEMPLATE/bug_report.md b/ja/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..3c410ce --- /dev/null +++ b/ja/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,46 @@ + + + +--- +name: Bug Report +about: サンプル、ガイド、ドキュメントの問題を報告する +title: "[BUG] " +labels: bug +assignees: '' + +--- + +## 概要 +問題の簡単な説明。 + +## 再現手順 +1. 手順 1 +2. 手順 2 +3. 手順 3 + +## 期待する動作 +本来どうなるべきか。 + +## 実際の動作 +実際にはどうなったか。 + +## 環境 +- **Claude Code バージョン**: （例: 1.0.5） +- **OS**: （例: macOS 14.1、Ubuntu 22.04、Windows 11） +- **Python バージョン**: （関連する場合、例: 3.11） +- **対象コンポーネント**: （例: 01-slash-commands、03-skills など） + +## サンプルコード +該当する場合、動作しないサンプルコードを記載してほしい。 +``` +[ここにコードを挿入] +``` + +## スクリーンショット +該当する場合、問題を示すスクリーンショットを添付してほしい。 + +## 補足情報 +問題の理解に役立つその他の情報があれば。 + +## 解決案 +修正方法の案があれば共有してほしい。 diff --git a/ja/.github/ISSUE_TEMPLATE/documentation.md b/ja/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..c27a428 --- /dev/null +++ b/ja/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,47 @@ + + + +--- +name: Documentation Issue +about: 不明瞭なドキュメント、誤字、情報の欠落を報告する +title: "[DOCS] " +labels: documentation +assignees: '' + +--- + +## 問題の種類 +- [ ] 誤字または文法ミス +- [ ] 説明が不明瞭 +- [ ] 情報の欠落 +- [ ] リンク切れまたは参照切れ +- [ ] 内容が古い +- [ ] より良い例が必要 + +## 場所 +どのセクションに問題があるか。 +- **ファイル**: （例: README.md、03-skills/README.md） +- **セクション**: （例: 「Installation Quick Reference」） +- **行・領域**: （特定できる場合） + +## 現在の内容 +現状はどう書かれているか。 +``` +[現在の文章をここに貼り付け] +``` + +## 問題の説明 +何が問題か。 + +## 改善案 +どう改善・明確化できるか。 +``` +[改善後の文章や提案をここに記載] +``` + +## なぜ重要か +この問題がユーザーにどう影響するか。 + +## 関連ドキュメント +関連セクションへのリンク。 +- 関連ガイド: diff --git a/ja/.github/ISSUE_TEMPLATE/feature_request.md b/ja/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..89c5772 --- /dev/null +++ b/ja/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,49 @@ + + + +--- +name: Feature Request +about: 新しいサンプル、ガイド、改善案を提案する +title: "[FEATURE] " +labels: enhancement +assignees: '' + +--- + +## 概要 +追加してほしい機能や改善内容を記述する。 + +## 解決する課題 +どのような課題やギャップに対応するか。 + +例： +- X 機能のサンプルがない +- Y のドキュメントが不明瞭 +- Z のユースケースのガイドが必要 +- 構造を以下のように改善できる… + +## ユースケース +いつ・どのように使うか。実際のシナリオを含める。 + +## 解決案 +どのように実装・ドキュメント化すべきか。 + +## 例 +該当する場合、想定する例を記載してほしい。 +``` +[ここに例を挿入] +``` + +## 関連サンプル +既存の関連サンプルやガイドへのリンク。 +- 既存ガイド: +- 機能: （例: Skills、Hooks、Subagents） + +## 補足情報 +他に役立つ情報があれば。 + +## 受け入れ基準 +この機能が完成したと判断する基準は何か。 +- [ ] 基準 1 +- [ ] 基準 2 +- [ ] 基準 3 diff --git a/ja/.github/ISSUE_TEMPLATE/question.md b/ja/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000..fc80310 --- /dev/null +++ b/ja/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,43 @@ + + + +--- +name: Question +about: Claude Code または本ガイドに関する質問をする +title: "[QUESTION] " +labels: question +assignees: '' + +--- + +## 質問 +何を知りたいか。 + +## 背景 +質問の背景・文脈を記載してほしい。 +- 何を実現しようとしているか +- すでに何を試したか +- どのサンプル・ガイドを参照したか + +## 関連トピック +どのトピックに関する質問か。 +- [ ] スラッシュコマンド +- [ ] メモリ +- [ ] スキル +- [ ] サブエージェント +- [ ] MCP プロトコル +- [ ] フック +- [ ] プラグイン +- [ ] チェックポイント +- [ ] 高度な機能 +- [ ] CLI リファレンス +- [ ] その他 + +## 試したこと +すでに試したことがあれば、その結果を記載してほしい。 + +## 期待する成果 +何があれば解決に役立つか。 + +## 関連リソース +関連しそうなリンクやリソースがあれば。 diff --git a/ja/.github/SECURITY_REPORTING.md b/ja/.github/SECURITY_REPORTING.md new file mode 100644 index 0000000..50828d7 --- /dev/null +++ b/ja/.github/SECURITY_REPORTING.md @@ -0,0 +1,312 @@ + + + +# セキュリティ脆弱性の報告 + +このファイルは、Claude How To プロジェクトに対するセキュリティ脆弱性の報告方法を説明する。 + +## クイックリンク + +- **非公開報告**: https://github.com/luongnv89/claude-howto/security/advisories +- **セキュリティポリシー**: [SECURITY.md](../SECURITY.md) +- **報告テンプレート**: 下記参照 + +## 脆弱性を報告する + +### 方法 1: GitHub の Private Vulnerability Report（推奨） + +セキュリティ脆弱性を報告する優先手段。 + +**手順:** +1. https://github.com/luongnv89/claude-howto/security/advisories を開く +2. 「Report a vulnerability」をクリック +3. 詳細を記入（下のテンプレートを使う） +4. 送信 + +**利点:** +- 修正版がリリースされるまで脆弱性を非公開に保つ +- メンテナーへの自動通知 +- 組み込みの共同作業機能 +- GitHub セキュリティツールとの統合 + +### 方法 2: GitHub Security Alert（依存関係向け） + +依存関係に脆弱性を発見した場合： + +1. https://github.com/luongnv89/claude-howto/security/advisories を開く +2. アラートを確認する +3. 修正案のプルリクエストを作成する +4. `security` ラベルを付ける + +### 方法 3: 非公開メール（GitHub が利用できない場合） + +GitHub の報告システムを使えない場合： + +**近日対応**: ここにセキュリティ問い合わせ用メールアドレスを追加予定 + +当面は、上記の GitHub の非公開脆弱性報告を使ってほしい。 + +## 脆弱性報告テンプレート + +脆弱性を報告するときは次のテンプレートを使う： + +``` +**Title**: [Brief description of vulnerability] + +**Severity**: [Critical/High/Medium/Low] +Estimated CVSS Score: [0-10] + +**Type**: [Code/Documentation/Dependency/Configuration] + +**Affected Component**: +- File: [path/to/file.py] +- Section: [Section name if documentation] +- Version: [latest/specific version] + +**Description**: +[Clear explanation of what the vulnerability is] + +**Potential Impact**: +[What could an attacker do with this vulnerability?] +[Who could be affected?] + +**Steps to Reproduce**: +1. [First step] +2. [Second step] +3. [Third step] +[Expected result vs actual result] + +**Proof of Concept** (if available): +[Code or steps to demonstrate the vulnerability] + +**Suggested Fix**: +[Your recommended solution, if you have one] + +**Additional Context**: +[Any other relevant information] + +**Your Information**: +- Name: [Your name or anonymous] +- Email: [Your email] +- Credit: [How you'd like to be credited, if at all] +``` + +## 報告後の流れ + +### タイムライン + +1. **即時（1 時間以内）** + - プロジェクトメンテナーに自動通知が送られる + +2. **24 時間以内** + - 報告内容を初期評価する + - 受領を確認する + - 暫定的な深刻度評価を行う + +3. **48 時間以内** + - セキュリティチームから詳細回答 + - 必要に応じて確認質問 + - 脆弱性が確認された場合の修正タイムライン + +4. **1〜7 日以内**（深刻度に依存） + - 修正の開発とテスト + - セキュリティアドバイザリの準備 + - 修正リリースと公開アドバイザリの公表 + +### コミュニケーション + +以下を通じて状況を共有する： +- GitHub 非公開脆弱性ディスカッション +- メール（提供されている場合） +- スレッド内の更新 + +報告者は以下を行える： +- 確認質問の投げかけ +- 追加情報の提供 +- 修正案の提案 +- タイムライン調整の依頼 + +### 開示タイムライン + +**緊急（CVSS 9.0〜10.0）** +- 修正: 即時リリース（24 時間以内） +- 開示: 同日に公開アドバイザリ +- 通知: 報告者に 24 時間前通知 + +**重大（CVSS 7.0〜8.9）** +- 修正: 48〜72 時間以内にリリース +- 開示: リリース時に公開アドバイザリ +- 通知: 報告者に 5 日前通知 + +**中程度（CVSS 4.0〜6.9）** +- 修正: 次回の通常更新に含める +- 開示: リリース時に公開アドバイザリ +- 通知: タイミングを調整 + +**軽微（CVSS 0.1〜3.9）** +- 修正: 次回の通常更新に含める +- 開示: リリース時にアドバイザリ +- 通知: リリース当日 + +## セキュリティ脆弱性の基準 + +### スコープ内 + +以下に関する報告を受け付ける： + +- **コードの脆弱性** + - インジェクション攻撃（コマンド、SQL など） + - サンプル中のクロスサイトスクリプティング（XSS） + - 認証・認可の不備 + - パストラバーサル脆弱性 + - 暗号関連の問題 + +- **ドキュメントのセキュリティ** + - 露出した秘密情報や認証情報 + - 安全でないコードパターン + - セキュリティアンチパターン + - 誤解を招くセキュリティ主張 + +- **依存関係の脆弱性** + - 既知の CVE が含まれる依存関係 + - サプライチェーン攻撃 + - 悪意ある依存関係 + +- **設定の問題** + - 安全でないデフォルト + - 欠落したセキュリティヘッダ + - サンプル内の認証情報露出 + +### スコープ外 + +以下に関する報告は受け付けない： + +- Claude Code 自体の脆弱性（Anthropic に連絡してほしい） +- 外部サービスの脆弱性 +- 証拠のない理論的脆弱性 +- すでに上流プロジェクトに報告済みの問題 +- ソーシャルエンジニアリングやフィッシング +- ユーザー教育・トレーニングの問題 + +## 責任ある開示のガイドライン + +### するべきこと ✅ + +- 公開開示の前に **非公開で報告** する +- ファイルパスや行番号など **具体的に** 記述する +- 脆弱性の **証拠を提示** する +- 修正の **時間を確保** する（協調開示） +- 詳細が見つかったら **更新** する +- すべてのやり取りで **プロフェッショナル** に振る舞う +- 公表まで **機密を尊重** する + +### してはいけないこと ❌ + +- 修正前に **公開開示しない** +- テストの範囲を超えて **脆弱性を悪用しない** +- 他ユーザーのデータを **改変しない** +- 金銭や見返りを **要求しない** +- 他者と脆弱性を **共有しない** +- いかなる形でも **悪用しない** +- セキュリティ以外の問題で **スパムしない** + +## 協調的開示 + +責任ある開示を実践している： + +1. **非公開報告**: 報告者は非公開で報告する +2. **当方の評価**: 当方が深刻度を評価する +3. **修正開発**: 修正を開発・テストする +4. **事前通知**: 公開前に報告者に事前通知する +5. **公開リリース**: 修正とアドバイザリを同時に公開する +6. **クレジット**: 希望に応じて貢献を明記する + +**タイムラインは深刻度により変動する**（上記セクション参照） + +## 修正リリース後 + +### 公開アドバイザリ + +公開セキュリティアドバイザリには以下が含まれる： +- 脆弱性の説明 +- 影響を受けるバージョン +- 深刻度（CVSS スコア） +- 修復手順 +- 修正へのリンク +- 報告者へのクレジット（許可がある場合） + +### 報告者の認知 + +クレジットを希望する場合： +- アドバイザリにあなたの名前・ハンドル +- プロフィール／Web サイトへのリンク +- リリースノートでの言及 +- Hall of Fame への追加（作成された場合） + +### 報酬なし + +注意： +- 本プロジェクトはボランティア運営のオープンソース +- 金銭的報酬は提供できない +- 認知とクレジットは提供する +- 貢献はコミュニティの助けになる + +## セキュリティリサーチ + +セキュリティリサーチを行う場合： + +1. **許可を取る**: まずメンテナーに連絡する +2. **スコープを定める**: 何をテストするか合意する +3. **報告する**: このプロセスを使う +4. **タイムラインを尊重する**: 修正の時間を確保する +5. **責任を持って公表する**: 当方と協調する + +## 質問 + +このプロセスに関する質問は： + +1. 詳細ポリシーは [SECURITY.md](../SECURITY.md) を確認する +2. 下の [FAQ](#faq) セクションを見る +3. `[SECURITY]` ラベル付きで Discussion を開く +4. 機密性の高い質問は非公開脆弱性報告を使う + +## FAQ + +**Q: 報告は秘密に保たれるか？** +A: はい、修正リリースまで秘密に保たれる。詳細は修正に関わる者にのみ共有する。 + +**Q: 公開開示まで待たなければならない期間は？** +A: 深刻度に応じた責任ある開示タイムライン（24 時間〜7 日）に従う。必要に応じて延長に同意できる。 + +**Q: クレジットは得られるか？** +A: はい、希望すればセキュリティアドバイザリとリリースノートに記載する（匿名希望でなければ）。 + +**Q: 軽微な脆弱性でも対応してもらえるか？** +A: 正当なセキュリティ問題はすべて真剣に扱う。軽微な修正でも認知する。 + +**Q: ドキュメントのみの脆弱性も報告してよいか？** +A: もちろん。ドキュメントセキュリティも重要。安全でないパターンを含む例はスコープ内。 + +**Q: セキュリティ問題か判断できない場合は？** +A: それでも報告してほしい。セキュリティ問題でなければそう伝える。誤検知でも問題ない。 + +**Q: 報告後に脆弱性を公開で議論してよいか？** +A: 不可。アドバイザリ公開まで非公開を保ってほしい。事前開示はユーザーを危険にさらす可能性がある。 + +**Q: 報告が受領されたか確認するには？** +A: GitHub から自動通知が送られ、24 時間以内に追って連絡する。 + +**Q: 返答がない場合は？** +A: GitHub セキュリティアドバイザリのページを確認する。それでも応答がない場合、非公開報告にコメントしてフォローアップしてほしい。 + +## リソース + +- [SECURITY.md](../SECURITY.md) — 完全なセキュリティポリシー +- [CONTRIBUTING.md](../CONTRIBUTING.md) — 貢献ガイドライン +- [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) — コミュニティ基準 +- [OWASP Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html) — 責任ある開示のベストプラクティス +- [Coordinated Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html) + +--- + +本プロジェクトのセキュリティ向上に協力してくれてありがとう！🔒 diff --git a/ja/.github/TESTING.md b/ja/.github/TESTING.md new file mode 100644 index 0000000..506dab8 --- /dev/null +++ b/ja/.github/TESTING.md @@ -0,0 +1,344 @@ + + + +# テストガイド + +本ドキュメントは Claude How To のテスト基盤について説明する。 + +## 概要 + +本プロジェクトは GitHub Actions を使い、すべてのプッシュとプルリクエストで自動的にテストを実行する。テスト内容： + +- **ユニットテスト**: pytest による Python テスト +- **コード品質**: Ruff によるリンティングとフォーマット +- **セキュリティ**: Bandit による脆弱性スキャン +- **型チェック**: mypy による静的型解析 +- **ビルド検証**: EPUB 生成テスト + +## ローカルでテストを実行する + +### 前提条件 + +```bash +# Install uv (fast Python package manager) +pip install uv + +# Or on macOS with Homebrew +brew install uv +``` + +### 環境セットアップ + +```bash +# Clone the repository +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto + +# Create virtual environment +uv venv + +# Activate it +source .venv/bin/activate # macOS/Linux +# or +.venv\Scripts\activate # Windows + +# Install development dependencies +uv pip install -r requirements-dev.txt +``` + +### テスト実行 + +```bash +# Run all unit tests +pytest scripts/tests/ -v + +# Run tests with coverage +pytest scripts/tests/ -v --cov=scripts --cov-report=html + +# Run specific test file +pytest scripts/tests/test_build_epub.py -v + +# Run specific test function +pytest scripts/tests/test_build_epub.py::test_function_name -v + +# Run tests in watch mode (requires pytest-watch) +ptw scripts/tests/ +``` + +### リンティング実行 + +```bash +# Check code formatting +ruff format --check scripts/ + +# Auto-fix formatting issues +ruff format scripts/ + +# Run linter +ruff check scripts/ + +# Auto-fix linter issues +ruff check --fix scripts/ +``` + +### セキュリティスキャン実行 + +```bash +# Run Bandit security scan +bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ + +# Generate JSON report +bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json +``` + +### 型チェック実行 + +```bash +# Check types with mypy +mypy scripts/ --ignore-missing-imports --no-implicit-optional +``` + +## GitHub Actions ワークフロー + +### トリガー + +- `main` または `develop` ブランチへの **プッシュ**（scripts が変更されたとき） +- `main` への **プルリクエスト**（scripts が変更されたとき） +- 手動の workflow dispatch + +### ジョブ + +#### 1. ユニットテスト（pytest） + +- **実行環境**: Ubuntu latest +- **Python バージョン**: 3.10、3.11、3.12 +- **内容**: + - `requirements-dev.txt` から依存関係をインストール + - カバレッジレポート付きで pytest を実行 + - カバレッジを Codecov へアップロード + - テスト結果とカバレッジ HTML をアーカイブ + +**結果**: テストが 1 つでも失敗するとワークフロー失敗（クリティカル） + +#### 2. コード品質（Ruff） + +- **実行環境**: Ubuntu latest +- **Python バージョン**: 3.11 +- **内容**: + - `ruff format` でコードフォーマットを確認 + - `ruff check` でリンターを実行 + - 問題を報告するがワークフローは失敗させない + +**結果**: ノンブロッキング（警告のみ） + +#### 3. セキュリティスキャン（Bandit） + +- **実行環境**: Ubuntu latest +- **Python バージョン**: 3.11 +- **内容**: + - セキュリティ脆弱性をスキャン + - JSON レポートを生成 + - レポートをアーティファクトとしてアップロード + +**結果**: ノンブロッキング（警告のみ） + +#### 4. 型チェック（mypy） + +- **実行環境**: Ubuntu latest +- **Python バージョン**: 3.11 +- **内容**: + - 静的型解析を実行 + - 型不一致を報告 + - 早期にバグを検出する助けになる + +**結果**: ノンブロッキング（警告のみ） + +#### 5. EPUB ビルド + +- **実行環境**: Ubuntu latest +- **依存ジョブ**: pytest、lint、security（すべてパスする必要がある） +- **内容**: + - `scripts/build_epub.py` を使い EPUB ファイルをビルド + - EPUB が正常に生成されたか検証 + - EPUB をアーティファクトとしてアップロード + +**結果**: ビルドが失敗するとワークフロー失敗（クリティカル） + +#### 6. サマリ + +- **実行環境**: Ubuntu latest +- **依存ジョブ**: 上記すべて +- **内容**: + - ワークフローサマリを生成 + - すべてのアーティファクトを一覧表示 + - 全体ステータスを報告 + +## テストの書き方 + +### テスト構造 + +テストは `scripts/tests/` 配下に `test_*.py` のような名前で配置する： + +```python +# scripts/tests/test_example.py +import pytest +from scripts.example_module import some_function + +def test_basic_functionality(): + """Test that some_function works correctly.""" + result = some_function("input") + assert result == "expected_output" + +def test_error_handling(): + """Test that some_function handles errors gracefully.""" + with pytest.raises(ValueError): + some_function("invalid_input") + +@pytest.mark.asyncio +async def test_async_function(): + """Test async functions.""" + result = await async_function() + assert result is not None +``` + +### テストのベストプラクティス + +- **記述的な名前を使う**: `test_function_returns_correct_value()` +- **テスト 1 つにつきアサート 1 つ**（可能な限り）: 失敗のデバッグが容易 +- **再利用可能なセットアップにフィクスチャを使う**: `scripts/tests/conftest.py` を参照 +- **外部サービスをモックする**: `unittest.mock` または `pytest-mock` を使う +- **エッジケースをテストする**: 空入力、None 値、エラー +- **テストを高速に保つ**: sleep() と外部 I/O を避ける +- **pytest マーカーを使う**: 遅いテストには `@pytest.mark.slow` + +### フィクスチャ + +共通フィクスチャは `scripts/tests/conftest.py` に定義する： + +```python +# Use fixtures in your tests +def test_something(tmp_path): + """tmp_path fixture provides temporary directory.""" + test_file = tmp_path / "test.txt" + test_file.write_text("content") + assert test_file.read_text() == "content" +``` + +## カバレッジレポート + +### ローカルカバレッジ + +```bash +# Generate coverage report +pytest scripts/tests/ --cov=scripts --cov-report=html + +# Open the coverage report in your browser +open htmlcov/index.html +``` + +### カバレッジ目標 + +- **最低カバレッジ**: 80% +- **ブランチカバレッジ**: 有効 +- **重点領域**: コア機能とエラー経路 + +## pre-commit フック + +本プロジェクトは pre-commit フックでコミット前に自動チェックを実行する： + +```bash +# Install pre-commit hooks +pre-commit install + +# Run hooks manually +pre-commit run --all-files + +# Skip hooks for a commit (not recommended) +git commit --no-verify +``` + +`.pre-commit-config.yaml` で設定済みのフック： +- Ruff フォーマッター +- Ruff リンター +- Bandit セキュリティスキャナ +- YAML 検証 +- ファイルサイズチェック +- マージコンフリクト検出 + +## トラブルシューティング + +### ローカルでパスするが CI で失敗する + +よくある原因： +1. **Python バージョンの違い**: CI は 3.10、3.11、3.12 を使う +2. **依存関係の不足**: `requirements-dev.txt` を更新する +3. **プラットフォーム差異**: パス区切り、環境変数 +4. **不安定なテスト**: タイミングや順序に依存するテスト + +解決策： +```bash +# Test with the same Python versions +uv python install 3.10 3.11 3.12 + +# Test with clean environment +rm -rf .venv +uv venv +uv pip install -r requirements-dev.txt +pytest scripts/tests/ +``` + +### Bandit が誤検知を出す + +セキュリティ警告の中には誤検知がある場合もある。`pyproject.toml` で設定する： + +```toml +[tool.bandit] +exclude_dirs = ["scripts/tests"] +skips = ["B101"] # Skip assert_used warning +``` + +### 型チェックが厳しすぎる + +特定ファイルで型チェックを緩める： + +```python +# Add at the top of file +# type: ignore + +# Or for specific lines +some_dynamic_code() # type: ignore +``` + +## 継続的インテグレーションのベストプラクティス + +1. **テストを高速に保つ**: 各テストは 1 秒以内で完了する +2. **外部 API をテストしない**: 外部サービスをモックする +3. **隔離してテストする**: 各テストは独立しているべき +4. **明確なアサートを使う**: `assert x` ではなく `assert x == 5` +5. **非同期テストを扱う**: `@pytest.mark.asyncio` を使う +6. **レポートを生成する**: カバレッジ、セキュリティ、型チェック + +## リソース + +- [pytest Documentation](https://docs.pytest.org/) +- [Ruff Documentation](https://docs.astral.sh/ruff/) +- [Bandit Documentation](https://bandit.readthedocs.io/) +- [mypy Documentation](https://mypy.readthedocs.io/) +- [GitHub Actions Documentation](https://docs.github.com/en/actions) + +## テストへの貢献 + +PR を提出する際： + +1. 新機能には **テストを書く** +2. **ローカルでテストを実行**: `pytest scripts/tests/ -v` +3. **カバレッジを確認**: `pytest scripts/tests/ --cov=scripts` +4. **リンティングを実行**: `ruff check scripts/` +5. **セキュリティスキャン**: `bandit -r scripts/ --exclude scripts/tests/` +6. テストが変わる場合は **ドキュメントを更新** + +すべての PR にはテストが必要！🧪 + +--- + +テストに関する質問や問題は、GitHub Issue または Discussion を開いてほしい。 diff --git a/ja/.github/pull_request_template.md b/ja/.github/pull_request_template.md new file mode 100644 index 0000000..aaf8be4 --- /dev/null +++ b/ja/.github/pull_request_template.md @@ -0,0 +1,60 @@ + + + +## 概要 +この PR が何をするのかを簡潔にまとめる。 + +## 変更の種類 +- [ ] 新しいサンプルまたはテンプレート +- [ ] ドキュメント改善 +- [ ] バグ修正 +- [ ] 機能ガイド +- [ ] その他（記述してほしい） + +## 関連 Issue +Closes #(issue 番号) + +## 変更内容 +- 変更 1 +- 変更 2 +- 変更 3 + +## レビューの観点 +レビュアーが特に注目すべき点は何か。 + +## 変更ファイル +- `path/to/file1.md` +- `path/to/file2.md` + +## テスト +どのようにテストしたか。 +- [ ] Claude Code でローカルにテスト済み +- [ ] サンプルが動作することを確認済み +- [ ] リンク・参照を確認済み +- [ ] 誤字・読みやすさを確認済み + +## チェックリスト +- [ ] プロジェクトの構造・規約に従っている +- [ ] 明確なドキュメント・サンプルを含む +- [ ] コード・サンプルがコピペで利用可能 +- [ ] すべてのリンクが検証済みで動作する +- [ ] 機密情報を含まない（鍵、トークン、認証情報など） +- [ ] 関連する README を更新済み +- [ ] コミットメッセージが Conventional Commits に従っている +- [ ] 大きいファイル（1MB 超）を追加していない + +## スクリーンショット・例 +該当する場合、追加内容を提示してほしい。 +``` +[サンプルコードまたは前後比較] +``` + +## 破壊的変更 +既存のコンテンツや動作を変更するか。 +- [ ] 破壊的変更なし +- [ ] あり、下記に記載 + +ある場合、内容を記載してほしい。 + +## 補足 +レビュアー向けの追加情報があれば。 diff --git a/ja/01-slash-commands/README.md b/ja/01-slash-commands/README.md new file mode 100644 index 0000000..2add43a --- /dev/null +++ b/ja/01-slash-commands/README.md @@ -0,0 +1,618 @@ + + + + + + + Claude How To + + +# スラッシュコマンド + +## 概要 + +スラッシュコマンドは、対話セッション中に Claude の動作を制御するためのショートカットである。次のようないくつかの種類がある: + +- **組み込みコマンド**: Claude Code が提供する（`/help`、`/clear`、`/model`） +- **スキル**: ユーザーが `SKILL.md` ファイルとして定義するコマンド（`/optimize`、`/pr`） +- **プラグインコマンド**: インストール済みプラグインから提供されるコマンド（`/frontend-design:frontend-design`） +- **MCP プロンプト**: MCP サーバーから提供されるコマンド（`/mcp__github__list_prs`） + +> **注意**: カスタムスラッシュコマンドはスキルに統合された。`.claude/commands/` のファイルは引き続き動くが、現在は `.claude/skills/` のスキル方式が推奨である。どちらも `/command-name` のショートカットを作る。完全なリファレンスは [スキルガイド](../03-skills/) を参照。 + +## 組み込みコマンドリファレンス + +組み込みコマンドはよく使うアクションのショートカットである。**60 種類以上の組み込みコマンド**と **5 つの同梱スキル**が利用できる。Claude Code 上で `/` をタイプすると一覧が出る。`/` の後に文字を続けるとフィルタできる。 + +| コマンド | 用途 | +|---------|------| +| `/add-dir ` | 作業ディレクトリを追加 | +| `/agents` | エージェント設定を管理 | +| `/branch [name]` | 会話を分岐させて新しいセッションにする（エイリアス: `/fork`）。注: `/fork` は v2.1.77 で `/branch` に改名 | +| `/btw ` | Claude がメインタスクを進めている間に、メイン会話のコンテキストを汚さず一時的なサイド質問をする | +| `/chrome` | Chrome ブラウザ統合を設定 | +| `/clear` | 会話をクリア（エイリアス: `/reset`、`/new`） | +| `/color [color\|default]` | プロンプトバーの色を設定 | +| `/compact [instructions]` | 任意のフォーカス指示を付けて会話を圧縮 | +| `/config` | 設定を開く（エイリアス: `/settings`） | +| `/context` | コンテキスト使用量をカラーグリッドで可視化 | +| `/copy [N]` | アシスタントの応答をクリップボードにコピー。`w` でファイル書き出し | +| `/cost` | `/usage` のタイピング用エイリアス — コストタブを開く（v2.1.118+） | +| `/desktop` | Desktop アプリで継続（エイリアス: `/app`） | +| `/diff` | 未コミット変更のインタラクティブ差分ビューア | +| `/doctor` | インストール状態を診断 — Claude が応答中でも開ける。ステータスアイコンを表示。`f` で問題を自動修正（v2.1.116 で強化） | +| `/effort [low\|medium\|high\|xhigh\|max\|auto]` | 矢印キーのスライダーで思考量を設定。レベル: `low` → `medium` → `high` → `xhigh`（v2.1.111 で追加）→ `max`。Opus 4.7 のデフォルトは `xhigh`、`max` は Opus 4.7 が必要 | +| `/exit` | REPL を終了（エイリアス: `/quit`） | +| `/export [filename]` | 現在の会話をファイルまたはクリップボードにエクスポート | +| `/extra-usage` | レート制限の追加使用量を設定 | +| `/fast [on\|off]` | 高速モードを切り替え | +| `/feedback` | フィードバックを送信（エイリアス: `/bug`） | +| `/focus` | フォーカスビューを切り替え（v2.1.110 で追加。フォーカス切替は `Ctrl+O` から本コマンドへ移行） | +| `/help` | ヘルプを表示 | +| `/hooks` | フック設定を表示 | +| `/ide` | IDE 統合を管理 | +| `/init` | `CLAUDE.md` を初期化。インタラクティブフローには `CLAUDE_CODE_NEW_INIT=1` を設定 | +| `/insights` | セッション分析レポートを生成 | +| `/install-github-app` | GitHub Actions アプリをセットアップ | +| `/install-slack-app` | Slack アプリをインストール | +| `/keybindings` | キーバインド設定を開く | +| `/less-permission-prompts` | 直近の Bash／MCP ツール呼び出しを分析し、優先度の高い許可リストを `.claude/settings.json` に追加して権限プロンプトを減らす（v2.1.111 で追加） | +| `/login` | Anthropic アカウントを切り替え | +| `/logout` | Anthropic アカウントからサインアウト | +| `/mcp` | MCP サーバーと OAuth を管理 | +| `/memory` | `CLAUDE.md` を編集、自動メモリを切り替え | +| `/mobile` | モバイルアプリの QR コード（エイリアス: `/ios`、`/android`） | +| `/model [model]` | モデル選択。左右キーで思考量を変更 | +| `/passes` | Claude Code 無料 1 週間を共有 | +| `/permissions` | 権限を表示／更新（エイリアス: `/allowed-tools`） | +| `/plan [description]` | プランモードに入る | +| `/plugin` | プラグインを管理 | +| `/proactive` | `/loop` のエイリアス（v2.1.105 で追加） | +| `/powerup` | アニメーション付きデモのインタラクティブレッスンで機能を発見 | +| `/privacy-settings` | プライバシー設定（Pro／Max のみ） | +| `/release-notes` | 変更履歴を表示 | +| `/recap` | セッションへ戻ってきた際にセッションのおさらい／要約を表示（v2.1.108 で追加） | +| `/reload-plugins` | アクティブなプラグインをリロード | +| `/remote-control` | claude.ai からのリモート制御（エイリアス: `/rc`） | +| `/remote-env` | デフォルトのリモート環境を設定 | +| `/rename [name]` | セッションをリネーム | +| `/resume [session]` | 会話を再開（エイリアス: `/continue`） | +| `/review` | **非推奨** — 代わりに `code-review` プラグインを導入する | +| `/rewind` | 会話やコードを巻き戻す（エイリアス: `/checkpoint`） | +| `/sandbox` | サンドボックスモードを切り替え | +| `/schedule [description]` | クラウドのスケジュールタスクを作成／管理 | +| `/security-review` | ブランチをセキュリティ脆弱性の観点で分析 | +| `/skills` | 利用可能なスキルを一覧表示 | +| `/stats` | `/usage` のタイピング用エイリアス — 統計タブ（日次使用量、セッション、ストリーク）を開く（v2.1.118+） | +| `/stickers` | Claude Code のステッカーを注文 | +| `/status` | バージョン、モデル、アカウントを表示 | +| `/statusline` | ステータスラインを設定 | +| `/tasks` | バックグラウンドタスクを一覧／管理 | +| `/team-onboarding` | プロジェクトの Claude Code 設定からチームメイト向けランプアップガイドを生成（v2.1.101 で新規） | +| `/terminal-setup` | ターミナルのキーバインドを設定 | +| `/theme` | テーマピッカーを開く／カスタムテーマを管理（v2.1.118）。カスタムテーマは `~/.claude/themes/.json` に JSON で定義 | +| `/tui` | ちらつきのないフルスクリーン TUI（テキストユーザーインターフェース）モードを切り替え（v2.1.110 で追加） | +| `/ultraplan ` | ultraplan セッションでプランを下書きし、ブラウザでレビュー | +| `/ultrareview` | マルチエージェント分析による包括的なクラウドベースのコードレビュー（v2.1.111 で追加） | +| `/undo` | `/rewind` のエイリアス（v2.1.108 で追加） | +| `/upgrade` | 上位プランへのアップグレードページを開く | +| `/usage` | 正式な使用状況ダッシュボード（v2.1.118）— プラン使用量制限、レート制限、コスト、日次セッション統計を統合。`/cost` と `/stats` は特定のタブを開くタイピング用エイリアス | +| `/voice` | プッシュトゥトーク音声入力を切り替え | + +### 同梱スキル + +これらのスキルは Claude Code に同梱され、スラッシュコマンドのように呼び出せる: + +| スキル | 用途 | +|-------|------| +| `/batch ` | ワークツリーを使った大規模並列変更をオーケストレートする | +| `/claude-api` | プロジェクトの言語に応じた Claude API リファレンスを読み込む | +| `/debug [description]` | デバッグログを有効化 | +| `/loop [interval] ` | プロンプトを定期的に繰り返し実行 | +| `/simplify [focus]` | 変更されたファイルをコード品質の観点でレビュー | + +### 非推奨コマンド + +| コマンド | ステータス | +|---------|----------| +| `/review` | 非推奨 — `code-review` プラグインに置き換え | +| `/output-style` | v2.1.73 から非推奨 | +| `/fork` | `/branch` に改名（エイリアスは引き続き有効、v2.1.77） | +| `/pr-comments` | v2.1.91 で削除 — Claude に直接 PR コメントを見るよう依頼する | +| `/vim` | v2.1.92 で削除 — /config → エディタモードを使う | + +### 直近の変更点 + +- `/fork` を `/branch` に改名し、`/fork` はエイリアスとして残置（v2.1.77） +- `/output-style` を非推奨化（v2.1.73） +- `/review` を非推奨化、`code-review` プラグインを推奨 +- `/effort` コマンドを追加。`max` レベルは Opus 4.7 が必要（当初は Opus 4.6 限定） +- プッシュトゥトーク音声入力の `/voice` コマンドを追加 +- スケジュールタスクの作成／管理用の `/schedule` コマンドを追加 +- プロンプトバーをカスタマイズする `/color` コマンドを追加 +- /pr-comments を v2.1.91 で削除 — Claude に直接 PR コメントを見るよう依頼する +- /vim を v2.1.92 で削除 — /config → エディタモードを使う +- ブラウザベースのプランレビューと実行を行う /ultraplan を追加 +- インタラクティブな機能レッスン用に /powerup を追加 +- サンドボックスモード切替用に /sandbox を追加 +- `/model` ピッカーが、生のモデル ID ではなく可読ラベル（例: "Sonnet 4.6"）を表示するようになった +- `/resume` が `/continue` エイリアスに対応 +- MCP プロンプトが `/mcp____` コマンドとして利用可能（[MCP プロンプトをコマンドとして使う](#mcp-プロンプトをコマンドとして使う) を参照） +- チームメイト向けランプアップガイドを自動生成する `/team-onboarding` を追加（v2.1.101） +- ちらつきのないフルスクリーン TUI 描画用に `/tui` コマンドを追加（v2.1.110） +- フォーカスビュー切替用に `/focus` コマンドを追加。`Ctrl+O` は詳細トランスクリプトの切替のみに（v2.1.110） +- セッションコンテキストのおさらいを手動で発火する `/recap` コマンドを追加（v2.1.108） +- `/undo` を `/rewind` のエイリアスとして追加（v2.1.108） +- `/proactive` を `/loop` のエイリアスとして追加（v2.1.105） +- `/effort` がインタラクティブな矢印キースライダーを獲得し、`high` と `max` の間に新しい `xhigh` レベルを追加。Opus 4.7 プランではデフォルト思考量が `xhigh` に引き上げられた（v2.1.111） +- 包括的なクラウドベースのマルチエージェントコードレビュー用に `/ultrareview` を追加（v2.1.111） +- Bash／MCP ツール呼び出しを分析し、`.claude/settings.json` の許可リストで権限プロンプトを減らす `/less-permission-prompts` を追加（v2.1.111） +- Opus 4.7 を利用する Max サブスクライバについて、Auto モードに `--enable-auto-mode` フラグが不要になった（v2.1.112） + +### `/team-onboarding` — チームメイト向けランプアップガイド + +> **v2.1.101 で新規追加** + +`/team-onboarding` を使うと、プロジェクトのローカルな Claude Code 利用状況からチームメイト向けランプアップガイドを生成できる。コマンドは `CLAUDE.md`、インストール済みのスキル、サブエージェント、フック、最近のワークフローを点検し、新しい開発者がすぐに生産的になれるオンボーディングドキュメントを作成する。 + +組み込みコマンドであり、インストール作業は不要である。 + +**使い方:** + +```bash +claude /team-onboarding +``` + +生成されるガイドは次の内容を要約する: + +- [`CLAUDE.md`](../02-memory/README.md) からのプロジェクトの目的と主な慣習 +- 利用可能な [スキル](../03-skills/README.md) と自動起動の条件 +- 設定済みの [サブエージェント](../04-subagents/README.md) とその責務 +- 一般的なイベントで実行される [フック](../06-hooks/README.md) +- 新規参加者が知っておくべき共通ワークフロー + +**提供開始:** Claude Code v2.1.101（2026 年 4 月 11 日）に同梱。 + +## カスタムコマンド（現在はスキル） + +カスタムスラッシュコマンドは **スキルに統合された**。どちらの方式でも `/command-name` で呼び出せるコマンドを作成できる: + +| 方式 | 配置場所 | ステータス | +|------|---------|----------| +| **スキル（推奨）** | `.claude/skills//SKILL.md` | 現行標準 | +| **レガシーコマンド** | `.claude/commands/.md` | 引き続き動作 | + +スキルとコマンドが同じ名前で存在する場合、**スキルが優先される**。例えば `.claude/commands/review.md` と `.claude/skills/review/SKILL.md` の両方が存在すれば、スキル版が使われる。 + +### 移行パス + +既存の `.claude/commands/` のファイルは、変更なしで動作し続ける。スキルへ移行するには: + +**変更前（コマンド）:** +``` +.claude/commands/optimize.md +``` + +**変更後（スキル）:** +``` +.claude/skills/optimize/SKILL.md +``` + +### なぜスキルなのか + +スキルはレガシーコマンドにはない次の機能を提供する: + +- **ディレクトリ構造**: スクリプト、テンプレート、参照ファイルをまとめられる +- **自動起動**: 関連性があるとき Claude が自動でスキルを発動できる +- **起動制御**: ユーザー、Claude、両者のうち誰が起動できるかを選べる +- **サブエージェント実行**: `context: fork` で隔離されたコンテキストでスキルを実行できる +- **段階的開示**: 必要なときだけ追加ファイルをロードする + +### スキルとしてカスタムコマンドを作成する + +`SKILL.md` を含むディレクトリを作る: + +```bash +mkdir -p .claude/skills/my-command +``` + +**ファイル:** `.claude/skills/my-command/SKILL.md` + +```yaml +--- +name: my-command +description: What this command does and when to use it +--- + +# My Command + +Instructions for Claude to follow when this command is invoked. + +1. First step +2. Second step +3. Third step +``` + +### フロントマターリファレンス + +| フィールド | 用途 | デフォルト | +|----------|------|----------| +| `name` | コマンド名（`/name` になる） | ディレクトリ名 | +| `description` | 簡単な説明（Claude がいつ使うか判断する材料） | 最初の段落 | +| `argument-hint` | 自動補完用の想定引数 | なし | +| `allowed-tools` | 権限なしで使えるツール | 継承 | +| `model` | 使用する特定のモデル | 継承 | +| `disable-model-invocation` | `true` ならユーザーのみ起動可（Claude は不可） | `false` | +| `user-invocable` | `false` なら `/` メニューから隠す | `true` | +| `context` | `fork` に設定すると隔離サブエージェントで実行 | なし | +| `agent` | `context: fork` 利用時のエージェント種別 | `general-purpose` | +| `hooks` | スキルスコープのフック（PreToolUse、PostToolUse、Stop） | なし | + +### 引数 + +コマンドは引数を受け取れる: + +**`$ARGUMENTS` で全引数を受ける:** + +```yaml +--- +name: fix-issue +description: Fix a GitHub issue by number +--- + +Fix issue #$ARGUMENTS following our coding standards +``` + +使い方: `/fix-issue 123` → `$ARGUMENTS` は "123" になる + +**個別引数を `$0`、`$1` などで受ける:** + +```yaml +--- +name: review-pr +description: Review a PR with priority +--- + +Review PR #$0 with priority $1 +``` + +使い方: `/review-pr 456 high` → `$0`="456"、`$1`="high" + +### シェルコマンドによる動的コンテキスト + +プロンプトの前に `!`command`` で bash コマンドを実行する: + +```yaml +--- +name: commit +description: Create a git commit with context +allowed-tools: Bash(git *) +--- + +## Context + +- Current git status: !`git status` +- Current git diff: !`git diff HEAD` +- Current branch: !`git branch --show-current` +- Recent commits: !`git log --oneline -5` + +## Your task + +Based on the above changes, create a single git commit. +``` + +### ファイル参照 + +`@` でファイル内容を埋め込む: + +```markdown +Review the implementation in @src/utils/helpers.js +Compare @src/old-version.js with @src/new-version.js +``` + +## プラグインコマンド + +プラグインはカスタムコマンドを提供できる: + +``` +/plugin-name:command-name +``` + +または、名前衝突がない場合はシンプルに `/command-name`。 + +**例:** +```bash +/frontend-design:frontend-design +/commit-commands:commit +``` + +## MCP プロンプトをコマンドとして使う + +MCP サーバーはプロンプトをスラッシュコマンドとして公開できる: + +``` +/mcp____ [arguments] +``` + +**例:** +```bash +/mcp__github__list_prs +/mcp__github__pr_review 456 +/mcp__jira__create_issue "Bug title" high +``` + +### MCP 権限の構文 + +権限設定で MCP サーバーへのアクセスを制御する: + +- `mcp__github` — GitHub MCP サーバー全体にアクセス +- `mcp__github__*` — すべてのツールにワイルドカードアクセス +- `mcp__github__get_issue` — 特定のツールにアクセス + +## コマンドアーキテクチャ + +```mermaid +graph TD + A["User Input: /command-name"] --> B{"Command Type?"} + B -->|Built-in| C["Execute Built-in"] + B -->|Skill| D["Load SKILL.md"] + B -->|Plugin| E["Load Plugin Command"] + B -->|MCP| F["Execute MCP Prompt"] + + D --> G["Parse Frontmatter"] + G --> H["Substitute Variables"] + H --> I["Execute Shell Commands"] + I --> J["Send to Claude"] + J --> K["Return Results"] +``` + +## コマンドのライフサイクル + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant FS as File System + participant CLI as Shell/Bash + + User->>Claude: Types /optimize + Claude->>FS: Searches .claude/skills/ and .claude/commands/ + FS-->>Claude: Returns optimize/SKILL.md + Claude->>Claude: Parses frontmatter + Claude->>CLI: Executes !`command` substitutions + CLI-->>Claude: Command outputs + Claude->>Claude: Substitutes $ARGUMENTS + Claude->>User: Processes prompt + Claude->>User: Returns results +``` + +## このフォルダで提供するコマンド + +これらのサンプルコマンドは、スキルとしても、レガシーコマンドとしてもインストールできる。 + +### 1. `/optimize` — コード最適化 + +パフォーマンス上の問題、メモリリーク、最適化の余地を分析する。 + +**使い方:** +``` +/optimize +[Paste your code] +``` + +### 2. `/pr` — プルリクエスト準備 + +リント、テスト、コミットメッセージのフォーマットなど、PR 準備チェックリストを案内する。 + +**使い方:** +``` +/pr +``` + +**スクリーンショット:** +![/pr](pr-slash-command.png) + +### 3. `/generate-api-docs` — API ドキュメント生成 + +ソースコードから網羅的な API ドキュメントを生成する。 + +**使い方:** +``` +/generate-api-docs +``` + +### 4. `/commit` — コンテキスト付き git コミット + +リポジトリの動的コンテキストを含めて git コミットを作成する。 + +**使い方:** +``` +/commit [optional message] +``` + +### 5. `/push-all` — ステージ・コミット・push + +全変更をステージングし、コミットを作成し、安全性チェックを行ってリモートへ push する。 + +**使い方:** +``` +/push-all +``` + +**安全性チェック:** +- シークレット: `.env*`、`*.key`、`*.pem`、`credentials.json` +- API キー: 実キーかプレースホルダかを判別 +- 大きなファイル: Git LFS なしの `>10MB` +- ビルド成果物: `node_modules/`、`dist/`、`__pycache__/` + +### 6. `/doc-refactor` — ドキュメント再構成 + +プロジェクトドキュメントを明瞭性とアクセシビリティの観点で再構成する。 + +**使い方:** +``` +/doc-refactor +``` + +### 7. `/setup-ci-cd` — CI/CD パイプライン設定 + +品質保証のために pre-commit フックと GitHub Actions を導入する。 + +**使い方:** +``` +/setup-ci-cd +``` + +### 8. `/unit-test-expand` — テストカバレッジ拡充 + +未テストの分岐とエッジケースを狙ってテストカバレッジを高める。 + +**使い方:** +``` +/unit-test-expand +``` + +## インストール + +### スキルとして（推奨） + +スキルディレクトリにコピーする: + +```bash +# skills ディレクトリを作成 +mkdir -p .claude/skills + +# 各コマンドファイルごとにスキルディレクトリを作成 +for cmd in optimize pr commit; do + mkdir -p .claude/skills/$cmd + cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md +done +``` + +### レガシーコマンドとして + +commands ディレクトリにコピーする: + +```bash +# プロジェクト全体（チーム向け） +mkdir -p .claude/commands +cp 01-slash-commands/*.md .claude/commands/ + +# 個人利用 +mkdir -p ~/.claude/commands +cp 01-slash-commands/*.md ~/.claude/commands/ +``` + +## 自前のコマンドを作る + +### スキルテンプレート（推奨） + +`.claude/skills/my-command/SKILL.md` を作成する: + +```yaml +--- +name: my-command +description: What this command does. Use when [trigger conditions]. +argument-hint: [optional-args] +allowed-tools: Bash(npm *), Read, Grep +--- + +# Command Title + +## Context + +- Current branch: !`git branch --show-current` +- Related files: @package.json + +## Instructions + +1. First step +2. Second step with argument: $ARGUMENTS +3. Third step + +## Output Format + +- How to format the response +- What to include +``` + +### ユーザーのみが起動可能なコマンド（自動起動なし） + +副作用があり、Claude に自動で発火させたくないコマンド向け: + +```yaml +--- +name: deploy +description: Deploy to production +disable-model-invocation: true +allowed-tools: Bash(npm *), Bash(git *) +--- + +Deploy the application to production: + +1. Run tests +2. Build application +3. Push to deployment target +4. Verify deployment +``` + +## ベストプラクティス + +| やる | やらない | +|------|---------| +| 動詞中心の明確な名前を使う | 一回限りのタスクをコマンドにする | +| 起動条件付きの `description` を含める | コマンド内に複雑なロジックを組む | +| 単一タスクに絞ったコマンドにする | 機微情報をハードコードする | +| 副作用がある場合は `disable-model-invocation` を使う | description フィールドを省く | +| 動的コンテキストには `!` プレフィックスを使う | Claude が現在の状態を知っている前提にする | +| 関連ファイルはスキルディレクトリで整理する | すべてを 1 ファイルに詰め込む | + +## トラブルシューティング + +### コマンドが見つからない + +**対処:** +- ファイルが `.claude/skills//SKILL.md` または `.claude/commands/.md` に置かれているか確認 +- フロントマターの `name` フィールドが期待するコマンド名と一致するか確認 +- Claude Code セッションを再起動 +- `/help` で利用可能なコマンドを確認 + +### コマンドが期待通りに動かない + +**対処:** +- 指示をより具体的にする +- スキルファイルに例を含める +- bash コマンドを使う場合は `allowed-tools` を確認 +- まずは単純な入力でテストする + +### スキルとコマンドが衝突する + +同じ名前で両方が存在する場合、**スキルが優先される**。どちらかを削除またはリネームする。 + +## 関連ガイド + +- **[スキル](../03-skills/)** — スキルの完全リファレンス（自動起動される機能） +- **[メモリ](../02-memory/)** — CLAUDE.md による永続コンテキスト +- **[サブエージェント](../04-subagents/)** — 委任型 AI エージェント +- **[プラグイン](../07-plugins/)** — まとめられたコマンド集 +- **[フック](../06-hooks/)** — イベント駆動の自動化 + +## 追加のリソース + +- [公式インタラクティブモードドキュメント](https://code.claude.com/docs/en/interactive-mode) — 組み込みコマンドリファレンス +- [公式スキルドキュメント](https://code.claude.com/docs/en/skills) — スキルの完全リファレンス +- [CLI リファレンス](https://code.claude.com/docs/en/cli-reference) — コマンドラインオプション + +--- + +**Last Updated**: April 24, 2026 +**Claude Code Version**: 2.1.119 +**Sources**: +- https://code.claude.com/docs/en/slash-commands +- https://code.claude.com/docs/en/interactive-mode +- https://code.claude.com/docs/en/changelog +- https://github.com/anthropics/claude-code/releases/tag/v2.1.118 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.116 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 + +*[Claude How To](../) ガイドシリーズの一部* diff --git a/ja/01-slash-commands/commit.md b/ja/01-slash-commands/commit.md new file mode 100644 index 0000000..bf08be0 --- /dev/null +++ b/ja/01-slash-commands/commit.md @@ -0,0 +1,33 @@ + + + + +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*) +argument-hint: [message] +description: コンテキスト付きで git コミットを作成する +--- + +## コンテキスト + +- 現在の git ステータス: !`git status` +- 現在の git 差分: !`git diff HEAD` +- 現在のブランチ: !`git branch --show-current` +- 直近のコミット: !`git log --oneline -10` + +## タスク + +上記の変更内容に基づいて、単一の git コミットを作成する。 + +引数でメッセージが指定された場合はそれを使う: $ARGUMENTS + +そうでない場合は、変更内容を分析し、Conventional Commits 形式に従って適切なコミットメッセージを作成する: +- `feat:` 新機能 +- `fix:` バグ修正 +- `docs:` ドキュメント変更 +- `refactor:` コードのリファクタリング +- `test:` テスト追加 +- `chore:` メンテナンスタスク + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/01-slash-commands/doc-refactor.md b/ja/01-slash-commands/doc-refactor.md new file mode 100644 index 0000000..32feca2 --- /dev/null +++ b/ja/01-slash-commands/doc-refactor.md @@ -0,0 +1,31 @@ + + + + +--- +name: Documentation Refactor +description: プロジェクトドキュメントを再構成して明瞭性とアクセシビリティを高める +tags: documentation, refactoring, organization +--- + +# ドキュメントリファクタリング + +プロジェクトの種類に合わせてドキュメント構造をリファクタリングする: + +1. **プロジェクトを分析**: 種類（ライブラリ／API／Web アプリ／CLI／マイクロサービス）、アーキテクチャ、ユーザーペルソナを特定する +2. **ドキュメントを集約**: 技術ドキュメントを `docs/` に移動し、適切な相互参照を整える +3. **ルート README.md**: 概要、クイックスタート、モジュール／コンポーネントのサマリ、ライセンス、連絡先を含むエントリーポイントとして整理する +4. **コンポーネント別ドキュメント**: モジュール／パッケージ／サービス単位の README ファイルを追加し、セットアップとテスト手順を記載する +5. **`docs/` を関連カテゴリで整理する**: + - Architecture、API Reference、Database、Design、Troubleshooting、Deployment、Contributing（プロジェクトの必要に応じて調整） +6. **ガイドを作成する**（該当するものを選ぶ）: + - User Guide: アプリケーションのエンドユーザー向けドキュメント + - API Documentation: API のエンドポイント、認証、サンプル + - Development Guide: セットアップ、テスト、コントリビューションのワークフロー + - Deployment Guide: サービス／アプリの本番デプロイ +7. **すべての図に Mermaid を使う**（アーキテクチャ、フロー、スキーマ） + +ドキュメントは簡潔に、流し読みしやすく、プロジェクトの種類に即した内容に保つ。 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/01-slash-commands/generate-api-docs.md b/ja/01-slash-commands/generate-api-docs.md new file mode 100644 index 0000000..7278574 --- /dev/null +++ b/ja/01-slash-commands/generate-api-docs.md @@ -0,0 +1,26 @@ + + + + +--- +description: ソースコードから網羅的な API ドキュメントを生成する +--- + +# API ドキュメント生成 + +次の手順で API ドキュメントを生成する: + +1. `/src/api/` 配下の全ファイルをスキャンする +2. 関数シグネチャと JSDoc コメントを抽出する +3. エンドポイント／モジュール単位で整理する +4. サンプル付きの Markdown を作成する +5. リクエスト／レスポンスのスキーマを含める +6. エラーに関するドキュメントを追加する + +出力形式: +- `/docs/api.md` に Markdown ファイルとして出力 +- 全エンドポイントについて curl のサンプルを含める +- TypeScript の型定義を追加する + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/01-slash-commands/optimize.md b/ja/01-slash-commands/optimize.md new file mode 100644 index 0000000..768a891 --- /dev/null +++ b/ja/01-slash-commands/optimize.md @@ -0,0 +1,26 @@ + + + + +--- +description: コードのパフォーマンス上の問題を分析し、最適化案を提示する +--- + +# コード最適化 + +提示されたコードについて、優先度の高い順に以下の項目をレビューする: + +1. **パフォーマンスのボトルネック** — O(n²) の処理や非効率なループを特定する +2. **メモリリーク** — 解放されていないリソースや循環参照を発見する +3. **アルゴリズムの改善** — より良いアルゴリズムやデータ構造を提案する +4. **キャッシュ可能な箇所** — 繰り返される計算を特定する +5. **並行性の問題** — 競合状態やスレッディングの問題を発見する + +回答は次の形式でまとめる: +- 問題の重大度（Critical／High／Medium／Low） +- コード上の該当箇所 +- 説明 +- 推奨される修正案とコード例 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/01-slash-commands/pr.md b/ja/01-slash-commands/pr.md new file mode 100644 index 0000000..732aa94 --- /dev/null +++ b/ja/01-slash-commands/pr.md @@ -0,0 +1,33 @@ + + + + +--- +description: コードを整え、変更をステージングし、プルリクエストを準備する +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*) +--- + +# プルリクエスト準備チェックリスト + +PR を作成する前に、以下のステップを実行する: + +1. リンタ実行: `prettier --write .` +2. テスト実行: `npm test` +3. git 差分のレビュー: `git diff HEAD` +4. 変更をステージング: `git add .` +5. Conventional Commits に従ったコミットメッセージを作成する: + - `fix:` バグ修正 + - `feat:` 新機能 + - `docs:` ドキュメント + - `refactor:` コード再構成 + - `test:` テスト追加 + - `chore:` メンテナンス + +6. PR サマリを生成する。次の項目を含める: + - 何を変更したか + - なぜ変更したか + - 実施したテスト + - 想定される影響 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/01-slash-commands/push-all.md b/ja/01-slash-commands/push-all.md new file mode 100644 index 0000000..bf1fc45 --- /dev/null +++ b/ja/01-slash-commands/push-all.md @@ -0,0 +1,160 @@ + + + + +--- +description: 全変更をステージング、コミット、リモートへ push する（取り扱い注意） +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*) +--- + +# すべてをコミット・push する + +⚠️ **注意**: すべての変更をステージング・コミットし、リモートへ push する。すべての変更がひとまとまりであると確信できる場合のみ使うこと。 + +## ワークフロー + +### 1. 変更を分析 + +並列で実行する: +- `git status` — 変更／追加／削除／追跡外ファイルを表示 +- `git diff --stat` — 変更統計を表示 +- `git log -1 --oneline` — メッセージスタイル参考のため直近のコミットを表示 + +### 2. 安全性チェック + +**❌ 検出時は STOP し WARN を出すべき項目:** +- シークレット: `.env*`、`*.key`、`*.pem`、`credentials.json`、`secrets.yaml`、`id_rsa`、`*.p12`、`*.pfx`、`*.cer` +- API キー: `*_API_KEY`、`*_SECRET`、`*_TOKEN` などの変数で実値が入っているもの（`your-api-key`、`xxx`、`placeholder` などのプレースホルダではないもの） +- 大きなファイル: Git LFS なしの `>10MB` +- ビルド成果物: `node_modules/`、`dist/`、`build/`、`__pycache__/`、`*.pyc`、`.venv/` +- 一時ファイル: `.DS_Store`、`thumbs.db`、`*.swp`、`*.tmp` + +**API キー検証:** +変更ファイルに以下のようなパターンがないか確認する: +```bash +OPENAI_API_KEY=sk-proj-xxxxx # ❌ 実キーを検出！ +AWS_SECRET_KEY=AKIA... # ❌ 実キーを検出！ +STRIPE_API_KEY=sk_live_... # ❌ 実キーを検出！ + +# ✅ 許容されるプレースホルダ: +API_KEY=your-api-key-here +SECRET_KEY=placeholder +TOKEN=xxx +API_KEY= +SECRET=${YOUR_SECRET} +``` + +**✅ 確認事項:** +- `.gitignore` が適切に設定されている +- マージ競合がない +- 正しいブランチである（main／master の場合は警告） +- API キーはプレースホルダのみ + +### 3. 確認を求める + +サマリを提示する: +``` +📊 Changes Summary: +- X files modified, Y added, Z deleted +- Total: +AAA insertions, -BBB deletions + +🔒 Safety: ✅ No secrets | ✅ No large files | ⚠️ [warnings] +🌿 Branch: [name] → origin/[name] + +I will: git add . → commit → push + +Type 'yes' to proceed or 'no' to cancel. +``` + +**明示的な "yes" を待ってから先へ進む。** + +### 4. 実行（確認後） + +順番に実行する: +```bash +git add . +git status # ステージングを確認 +``` + +### 5. コミットメッセージを生成 + +変更を分析し、Conventional Commits 形式のコミットを作成する: + +**形式:** +``` +[type]: Brief summary (max 72 characters) + +- Key change 1 +- Key change 2 +- Key change 3 +``` + +**Types:** `feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`、`perf`、`build`、`ci` + +**例:** +``` +docs: Update concept README files with comprehensive documentation + +- Add architecture diagrams and tables +- Include practical examples +- Expand best practices sections +``` + +### 6. コミットと push + +```bash +git commit -m "$(cat <<'EOF' +[Generated commit message] +EOF +)" +git push # 失敗時: git pull --rebase && git push +git log -1 --oneline --decorate # 確認 +``` + +### 7. 成功を通知 + +``` +✅ Successfully pushed to remote! + +Commit: [hash] [message] +Branch: [branch] → origin/[branch] +Files changed: X (+insertions, -deletions) +``` + +## エラーハンドリング + +- **git add 失敗**: 権限、ロックされたファイル、リポジトリ初期化済みかを確認 +- **git commit 失敗**: pre-commit フックを修正、git config（user.name／email）を確認 +- **git push 失敗**: + - non-fast-forward: `git pull --rebase && git push` + - リモートブランチなし: `git push -u origin [branch]` + - 保護ブランチ: PR ワークフローを使う + +## 使うべきとき + +✅ **適している場面:** +- 複数ファイルにまたがるドキュメント更新 +- テストとドキュメントを伴う機能追加 +- 複数ファイルにまたがるバグ修正 +- プロジェクト全体のフォーマット／リファクタリング +- 設定変更 + +❌ **避けるべき場面:** +- 何をコミットするか不明確 +- シークレット／機密データを含む +- レビューなしの保護ブランチ +- マージ競合がある +- 粒度の細かいコミット履歴を残したい +- pre-commit フックが失敗している + +## 代替案 + +ユーザーがより細かく制御したい場合は次を提案する: +1. **選択的ステージング**: 特定ファイルをレビュー／ステージング +2. **インタラクティブステージング**: パッチ単位の選択に `git add -p` +3. **PR ワークフロー**: ブランチを作成 → push → PR（`/pr` コマンドを使う） + +**⚠️ 注意**: push する前に必ず変更を確認する。迷ったら、より細かい制御のため個別の git コマンドを使う。 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/01-slash-commands/setup-ci-cd.md b/ja/01-slash-commands/setup-ci-cd.md new file mode 100644 index 0000000..1a94323 --- /dev/null +++ b/ja/01-slash-commands/setup-ci-cd.md @@ -0,0 +1,32 @@ + + + + +--- +name: Setup CI/CD Pipeline +description: 品質保証のための pre-commit フックと GitHub Actions を導入する +tags: ci-cd, devops, automation +--- + +# CI/CD パイプラインのセットアップ + +プロジェクトの種類に応じて、包括的な DevOps の品質ゲートを導入する: + +1. **プロジェクトを分析**: 言語、フレームワーク、ビルドシステム、既存ツールを検出する +2. **言語別ツールで pre-commit フックを設定する**: + - フォーマッタ: Prettier／Black／gofmt／rustfmt など + - リンタ: ESLint／Ruff／golangci-lint／Clippy など + - セキュリティ: Bandit／gosec／cargo-audit／npm audit など + - 型チェック: TypeScript／mypy／flow（該当する場合） + - テスト: 関連するテストスイートを実行する +3. **GitHub Actions ワークフローを作成する**（.github/workflows/）: + - push／PR 時に pre-commit と同じチェックを実行する + - 複数バージョン／プラットフォームのマトリクス（該当する場合） + - ビルドとテストの検証 + - デプロイ手順（必要な場合） +4. **パイプラインを検証する**: ローカルで動作確認し、テスト用 PR を作成し、全チェックの通過を確認する + +無料・オープンソースのツールを使う。既存の設定を尊重する。実行時間は短く保つ。 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/01-slash-commands/unit-test-expand.md b/ja/01-slash-commands/unit-test-expand.md new file mode 100644 index 0000000..0f4a7b7 --- /dev/null +++ b/ja/01-slash-commands/unit-test-expand.md @@ -0,0 +1,32 @@ + + + + +--- +name: Expand Unit Tests +description: 未テストの分岐やエッジケースを狙ってテストカバレッジを高める +tags: testing, coverage, unit-tests +--- + +# ユニットテストの拡充 + +プロジェクトのテストフレームワークに合わせて、既存のユニットテストを拡充する: + +1. **カバレッジを分析**: カバレッジレポートを実行し、未テストの分岐、エッジケース、低カバレッジ領域を特定する +2. **ギャップを特定**: コードを見直し、論理分岐、エラー経路、境界条件、null／空入力を確認する +3. **プロジェクトのフレームワークでテストを書く**: + - Jest／Vitest／Mocha（JavaScript／TypeScript） + - pytest／unittest（Python） + - Go testing／testify（Go） + - Rust のテストフレームワーク（Rust） +4. **特定のシナリオを狙う**: + - エラーハンドリングと例外 + - 境界値（最小／最大、空、null） + - エッジケース・コーナーケース + - 状態遷移と副作用 +5. **改善を確認**: 再度カバレッジを計測し、計測可能な向上を確認する + +新しく追加したテストコードのみを提示する。既存のテストパターンと命名規則に従う。 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/02-memory/README.md b/ja/02-memory/README.md new file mode 100644 index 0000000..526afdf --- /dev/null +++ b/ja/02-memory/README.md @@ -0,0 +1,1212 @@ + + + + + + + Claude How To + + +# メモリガイド + +メモリにより、Claude はセッションや会話をまたいでコンテキストを保持できる。メモリには 2 つの形態がある: claude.ai の自動合成と、Claude Code のファイルシステムベースの CLAUDE.md である。 + +## 概要 + +Claude Code のメモリは、複数のセッションや会話をまたいで持続するコンテキストを提供する。一時的なコンテキストウィンドウとは異なり、メモリファイルは次のことを可能にする: + +- プロジェクト標準をチームで共有する +- 個人の開発上の好みを保存する +- ディレクトリ固有のルールと設定を維持する +- 外部ドキュメントをインポートする +- メモリをプロジェクトの一部としてバージョン管理する + +メモリシステムは、グローバルな個人設定から特定のサブディレクトリまで複数の階層で動作し、Claude が何を覚え、それをどう適用するかを細かく制御できる。 + +## メモリコマンドのクイックリファレンス + +| コマンド | 用途 | 使い方 | 使うタイミング | +|---------|------|-------|--------------| +| `/init` | プロジェクトメモリを初期化 | `/init` | 新規プロジェクト開始時、初回の CLAUDE.md セットアップ | +| `/memory` | エディタでメモリファイルを編集 | `/memory` | 大規模な更新、再構成、内容のレビュー | +| `#` プレフィックス | ~~単一行を素早くメモリに追加~~ **廃止** | — | 代わりに `/memory` を使うか会話で依頼する | +| `@path/to/file` | 外部コンテンツをインポート | `@README.md` または `@docs/api.md` | CLAUDE.md から既存ドキュメントを参照する | + +## クイックスタート: メモリの初期化 + +### `/init` コマンド + +`/init` コマンドは Claude Code でプロジェクトメモリをセットアップする最速の方法である。基本となるプロジェクトドキュメントを含む CLAUDE.md ファイルを初期化する。 + +**使い方:** + +```bash +/init +``` + +**機能:** + +- プロジェクトに新しい CLAUDE.md ファイルを作成（通常は `./CLAUDE.md` または `./.claude/CLAUDE.md`） +- プロジェクトの慣習とガイドラインを確立する +- セッションをまたいだコンテキスト持続の基盤をセットアップ +- プロジェクト標準を文書化するためのテンプレート構造を提供 + +**強化されたインタラクティブモード:** `CLAUDE_CODE_NEW_INIT=1` を設定すると、ステップごとにプロジェクトセットアップを案内する複数フェーズのインタラクティブフローが有効になる: + +```bash +CLAUDE_CODE_NEW_INIT=1 claude +/init +``` + +**`/init` を使う場面:** + +- Claude Code で新規プロジェクトを開始するとき +- チームのコーディング標準と慣習を確立するとき +- コードベース構造に関するドキュメントを作るとき +- 共同開発のためにメモリ階層をセットアップするとき + +**ワークフロー例:** + +```markdown +# In your project directory +/init + +# Claude creates CLAUDE.md with structure like: +# Project Configuration +## Project Overview +- Name: Your Project +- Tech Stack: [Your technologies] +- Team Size: [Number of developers] + +## Development Standards +- Code style preferences +- Testing requirements +- Git workflow conventions +``` + +### メモリの簡易更新 + +> **注意**: インラインメモリ用の `#` ショートカットは廃止された。`/memory` でメモリファイルを直接編集するか、Claude に会話で覚えてほしいことを依頼する（例: 「TypeScript の strict モードを必ず使うことを覚えておいて」）。 + +メモリに情報を追加する推奨方法: + +**方法 1: `/memory` コマンドを使う** + +```bash +/memory +``` + +メモリファイルがシステムのエディタで開かれ、直接編集できる。 + +**方法 2: 会話で依頼する** + +``` +Remember that we always use TypeScript strict mode in this project. +Please add to memory: prefer async/await over promise chains. +``` + +Claude は依頼内容に基づき適切な CLAUDE.md ファイルを更新する。 + +**履歴用メモ**（現在は機能しない）: + +`#` プレフィックスショートカットは以前、ルールをインラインで追加できた: + +```markdown +# Always use TypeScript strict mode in this project ← no longer works +``` + +このパターンに依存していた場合は、`/memory` コマンドや会話依頼に切り替える。 + +### `/memory` コマンド + +`/memory` コマンドは、Claude Code セッション内から CLAUDE.md メモリファイルを直接編集する手段を提供する。メモリファイルをシステムのエディタで開き、包括的に編集できる。 + +**使い方:** + +```bash +/memory +``` + +**機能:** + +- メモリファイルをシステムのデフォルトエディタで開く +- 大規模な追加、修正、再構成を行える +- 階層内のすべてのメモリファイルへの直接アクセスを提供 +- セッションをまたいだ永続コンテキストの管理を可能にする + +**`/memory` を使う場面:** + +- 既存のメモリ内容をレビューするとき +- プロジェクト標準を大規模に更新するとき +- メモリ構造を再構成するとき +- 詳細なドキュメントやガイドラインを追加するとき +- プロジェクトの進化に合わせてメモリを保守・更新するとき + +**比較: `/memory` と `/init`** + +| 観点 | `/memory` | `/init` | +|------|-----------|---------| +| **目的** | 既存メモリファイルの編集 | 新規 CLAUDE.md の初期化 | +| **使う場面** | プロジェクトコンテキストの更新／修正 | 新規プロジェクト開始時 | +| **動作** | 編集用にエディタを開く | スターターテンプレートを生成 | +| **ワークフロー** | 継続的なメンテナンス | 一回限りのセットアップ | + +**ワークフロー例:** + +```markdown +# Open memory for editing +/memory + +# Claude presents options: +# 1. Managed Policy Memory +# 2. Project Memory (./CLAUDE.md) +# 3. User Memory (~/.claude/CLAUDE.md) +# 4. Local Project Memory + +# Choose option 2 (Project Memory) +# Your default editor opens with ./CLAUDE.md content + +# Make changes, save, and close editor +# Claude automatically reloads the updated memory +``` + +**メモリインポートの利用:** + +CLAUDE.md ファイルは、外部コンテンツを取り込む `@path/to/file` 構文をサポートする: + +```markdown +# Project Documentation +See @README.md for project overview +See @package.json for available npm commands +See @docs/architecture.md for system design + +# Import from home directory using absolute path +@~/.claude/my-project-instructions.md +``` + +**インポート機能:** + +- 相対パスと絶対パスの両方をサポート（例: `@docs/api.md`、`@~/.claude/my-project-instructions.md`） +- 再帰的インポートをサポート（最大ネスト深さ 5） +- 外部ロケーションからの初回インポートはセキュリティのため承認ダイアログが出る +- インポートディレクティブは Markdown のコードスパンやコードブロック内では評価されない（例として記述しても安全） +- 既存ドキュメントを参照することで重複を避けられる +- 参照されたコンテンツが Claude のコンテキストに自動で含まれる + +## メモリアーキテクチャ + +Claude Code のメモリは、スコープごとに異なる目的を持つ階層システムに従う: + +```mermaid +graph TB + A["Claude Session"] + B["User Input"] + C["Memory System"] + D["Memory Storage"] + + B -->|User provides info| C + C -->|Synthesizes every 24h| D + D -->|Loads automatically| A + A -->|Uses context| C +``` + +## Claude Code のメモリ階層 + +Claude Code は多階層のメモリシステムを使う。Claude Code 起動時にメモリファイルが自動でロードされ、上位レベルのファイルが優先される。 + +**メモリ階層全体（優先度の高い順）:** + +1. **Managed Policy** — 組織全体の指示 + - macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` + - Linux/WSL: `/etc/claude-code/CLAUDE.md` + - Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` + +2. **Managed Drop-ins** — アルファベット順にマージされるポリシーファイル（v2.1.83+） + - 管理ポリシー CLAUDE.md と並ぶ `managed-settings.d/` ディレクトリ + - モジュール式のポリシー管理のため、アルファベット順にマージされる + +3. **Project Memory** — チーム共有のコンテキスト（バージョン管理対象） + - `./.claude/CLAUDE.md` または `./CLAUDE.md`（リポジトリのルート） + +4. **Project Rules** — モジュール式・トピック別のプロジェクト指示 + - `./.claude/rules/*.md` + +5. **User Memory** — 個人設定（全プロジェクト） + - `~/.claude/CLAUDE.md` + +6. **User-Level Rules** — 個人ルール（全プロジェクト） + - `~/.claude/rules/*.md` + +7. **Local Project Memory** — プロジェクト固有の個人設定 + - `./CLAUDE.local.md` + +> **注意**: `CLAUDE.local.md` は完全にサポートされ、[公式ドキュメント](https://code.claude.com/docs/en/memory) にも記載されている。バージョン管理にコミットしないプロジェクト固有の個人設定を提供する。`CLAUDE.local.md` は `.gitignore` に追加すること。 + +8. **Auto Memory** — Claude による自動メモと学習内容 + - `~/.claude/projects//memory/` + +**メモリ探索の挙動:** + +Claude は次の順序でメモリファイルを探索し、上位の場所が優先される: + +```mermaid +graph TD + A["Managed Policy
/Library/.../ClaudeCode/CLAUDE.md"] -->|highest priority| A2["Managed Drop-ins
managed-settings.d/"] + A2 --> B["Project Memory
./CLAUDE.md"] + B --> C["Project Rules
./.claude/rules/*.md"] + C --> D["User Memory
~/.claude/CLAUDE.md"] + D --> E["User Rules
~/.claude/rules/*.md"] + E --> F["Local Project Memory
./CLAUDE.local.md"] + F --> G["Auto Memory
~/.claude/projects/.../memory/"] + + B -->|imports| H["@docs/architecture.md"] + H -->|imports| I["@docs/api-standards.md"] + + style A fill:#fce4ec,stroke:#333,color:#333 + style A2 fill:#fce4ec,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 + style G fill:#fff3e0,stroke:#333,color:#333 + style H fill:#e1f5fe,stroke:#333,color:#333 + style I fill:#e1f5fe,stroke:#333,color:#333 +``` + +## `claudeMdExcludes` で CLAUDE.md ファイルを除外する + +大規模モノレポでは、現在の作業に関係ない CLAUDE.md があり得る。`claudeMdExcludes` 設定により、特定の CLAUDE.md ファイルをスキップしてコンテキストにロードしないようにできる: + +```jsonc +// In ~/.claude/settings.json or .claude/settings.json +{ + "claudeMdExcludes": [ + "packages/legacy-app/CLAUDE.md", + "vendors/**/CLAUDE.md" + ] +} +``` + +パターンはプロジェクトルートからの相対パスに対して照合される。とくに次の場合に有用である: + +- 多くのサブプロジェクトを抱えるモノレポで、関連するのが一部のみのとき +- ベンダー製・サードパーティ製の CLAUDE.md を含むリポジトリ +- 古い・無関係な指示を除外して Claude のコンテキストウィンドウのノイズを減らしたいとき + +## 設定ファイルの階層 + +Claude Code の設定（`autoMemoryDirectory`、`claudeMdExcludes` などを含む）は 5 段階の階層から解決され、上位レベルが優先される: + +| レベル | 場所 | スコープ | +|-------|------|--------| +| 1（最高） | 管理ポリシー（システムレベル） | 組織全体への強制 | +| 2 | `managed-settings.d/`（v2.1.83+） | モジュール式のポリシードロップイン、アルファベット順にマージ | +| 3 | `~/.claude/settings.json` | ユーザー設定 | +| 4 | `.claude/settings.json` | プロジェクトレベル（git にコミット） | +| 5（最低） | `.claude/settings.local.json` | ローカルオーバーライド（git 無視） | + +**プラットフォーム固有の設定（v2.1.51+）:** + +設定は次の方法でも構成できる: +- **macOS**: プロパティリスト（plist）ファイル +- **Windows**: Windows レジストリ + +これらのプラットフォームネイティブの仕組みは JSON 設定ファイルとともに読み込まれ、同じ優先順位ルールに従う。 + +> **注意（v2.1.119）**: `/config` の変更は `~/.claude/settings.json` に永続化されるようになった。`/config` で書かれた値は、上記のプロジェクト／ローカル／ポリシーの優先順位チェーンに参加する — もはやセッション限りではない。インタラクティブな編集には `/config` を、スクリプト化または管理された設定には `settings.json` ファイルの直接編集を使う。 + +### 保持期間とクリーンアップ設定 + +| 設定 | 型 | デフォルト | 説明 | +|------|---|---------|------| +| `cleanupPeriodDays` | 整数（日） | 30 | ディスク上の成果物の保持期間。**v2.1.117 から**、checkpoints（`~/.claude/checkpoints/`）、tasks（`~/.claude/tasks/`）、shell-snapshots（`~/.claude/shell-snapshots/`）、backups（`~/.claude/backups/`）の 4 種すべてに適用される。期間より古いファイルは起動時に削除される。 | + +```jsonc +// ~/.claude/settings.json +{ + "cleanupPeriodDays": 14 +} +``` + +### 帰属表示・音声・PR URL の設定 + +| 設定 | 型 | 説明 | +|------|---|------| +| `attribution.commit` | boolean | Claude が作成したコミットに `Co-Authored-By: Claude` トレーラを追加。非推奨の `includeCoAuthoredBy` フラグを置き換え。 | +| `attribution.pr` | boolean | プルリクエストの説明に Claude の帰属表示を追加。PR について非推奨の `includeCoAuthoredBy` フラグを置き換え。 | +| `voice.enabled` | boolean | プッシュトゥトーク音声入力（`/voice`）を有効化。非推奨の `voiceEnabled` フラグを置き換え。 | +| `prUrlTemplate` | string | **v2.1.119 で新規。** フッターの PR バッジ用カスタム URL テンプレート。GitLab、Bitbucket、社内コードレビュー基盤などで有用。`{{owner}}`、`{{repo}}`、`{{number}}` プレースホルダをサポート。 | + +```jsonc +// ~/.claude/settings.json +{ + "attribution": { + "commit": false, + "pr": true + }, + "voice": { + "enabled": true + }, + "prUrlTemplate": "https://gitlab.internal/{{owner}}/{{repo}}/-/merge_requests/{{number}}" +} +``` + +#### 非推奨となった設定キー + +以下のレガシー設定キーは引き続き動作するが非推奨。上記の置き換えを優先する。 + +| 非推奨キー | 置き換え | 備考 | +|----------|--------|------| +| `includeCoAuthoredBy` | `attribution.commit` ／ `attribution.pr` | 旧来の単一フラグはコミット用と PR 用の別スイッチに分割された。古いインストール環境のユーザーはレガシーキーを使い続けてよいが、新規プロジェクトはネスト形式を使うべき。 | +| `voiceEnabled` | `voice.enabled` | 将来の音声関連オプションと同様、`voice` 名前空間にまとめられた。 | + +## モジュール式ルールシステム + +`.claude/rules/` ディレクトリ構造を使うと、整理された・パス固有のルールを作成できる。ルールはプロジェクトレベルとユーザーレベルの両方で定義できる: + +``` +your-project/ +├── .claude/ +│ ├── CLAUDE.md +│ └── rules/ +│ ├── code-style.md +│ ├── testing.md +│ ├── security.md +│ └── api/ # Subdirectories supported +│ ├── conventions.md +│ └── validation.md + +~/.claude/ +├── CLAUDE.md +└── rules/ # User-level rules (all projects) + ├── personal-style.md + └── preferred-patterns.md +``` + +ルールは `rules/` ディレクトリ内で再帰的に発見される（サブディレクトリも含む）。`~/.claude/rules/` のユーザーレベルルールはプロジェクトレベルルールより前にロードされ、プロジェクトが上書きできる個人デフォルトを設定できる。 + +### YAML フロントマターによるパス固有ルール + +特定のファイルパスにのみ適用されるルールを定義できる: + +```markdown +--- +paths: src/api/**/*.ts +--- + +# API Development Rules + +- All API endpoints must include input validation +- Use Zod for schema validation +- Document all parameters and response types +- Include error handling for all operations +``` + +**glob パターン例:** + +- `**/*.ts` — すべての TypeScript ファイル +- `src/**/*` — src/ 配下のすべてのファイル +- `src/**/*.{ts,tsx}` — 複数の拡張子 +- `{src,lib}/**/*.ts, tests/**/*.test.ts` — 複数のパターン + +### サブディレクトリとシンボリックリンク + +`.claude/rules/` のルールは 2 つの整理機能をサポートする: + +- **サブディレクトリ**: ルールは再帰的に発見されるため、トピック別フォルダに整理できる（例: `rules/api/`、`rules/testing/`、`rules/security/`） +- **シンボリックリンク**: 複数プロジェクト間でルールを共有するためにシンボリックリンクをサポート。例えば、共有ルールファイルを中央の場所から各プロジェクトの `.claude/rules/` ディレクトリにシンボリックリンクできる + +## メモリ配置一覧 + +| 場所 | スコープ | 優先度 | 共有 | アクセス | 適した用途 | +|------|--------|-------|------|--------|----------| +| `/Library/Application Support/ClaudeCode/CLAUDE.md`（macOS） | Managed Policy | 1（最高） | 組織 | システム | 会社全体のポリシー | +| `/etc/claude-code/CLAUDE.md`（Linux/WSL） | Managed Policy | 1（最高） | 組織 | システム | 組織標準 | +| `C:\Program Files\ClaudeCode\CLAUDE.md`（Windows） | Managed Policy | 1（最高） | 組織 | システム | 全社ガイドライン | +| `managed-settings.d/*.md`（ポリシーと並ぶ） | Managed Drop-ins | 1.5 | 組織 | システム | モジュール式ポリシーファイル（v2.1.83+） | +| `./CLAUDE.md` または `./.claude/CLAUDE.md` | Project Memory | 2 | チーム | Git | チーム標準、共有アーキテクチャ | +| `./.claude/rules/*.md` | Project Rules | 3 | チーム | Git | パス固有・モジュール式ルール | +| `~/.claude/CLAUDE.md` | User Memory | 4 | 個人 | ファイルシステム | 個人設定（全プロジェクト） | +| `~/.claude/rules/*.md` | User Rules | 5 | 個人 | ファイルシステム | 個人ルール（全プロジェクト） | +| `./CLAUDE.local.md` | Project Local | 6 | 個人 | Git（無視） | プロジェクト固有の個人設定 | +| `~/.claude/projects//memory/` | Auto Memory | 7（最低） | 個人 | ファイルシステム | Claude による自動メモと学習内容 | + +## メモリ更新のライフサイクル + +Claude Code セッションでメモリ更新がどう流れるかを示す: + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Editor as File System + participant Memory as CLAUDE.md + + User->>Claude: "Remember: use async/await" + Claude->>User: "Which memory file?" + User->>Claude: "Project memory" + Claude->>Editor: Open ~/.claude/settings.json + Claude->>Memory: Write to ./CLAUDE.md + Memory-->>Claude: File saved + Claude->>Claude: Load updated memory + Claude-->>User: "Memory saved!" +``` + +## 自動メモリ（Auto Memory） + +自動メモリは、Claude がプロジェクトでの作業中に学んだ内容、パターン、洞察を自動で記録する永続ディレクトリである。手動で書いて維持する CLAUDE.md ファイルとは異なり、自動メモリはセッション中に Claude 自身が書き込む。 + +### 自動メモリの仕組み + +- **場所**: `~/.claude/projects//memory/` +- **エントリポイント**: `MEMORY.md` が自動メモリディレクトリのメインファイルとして機能する +- **トピックファイル**: 特定の主題向けのオプションファイル（例: `debugging.md`、`api-conventions.md`） +- **ロード挙動**: セッション開始時に `MEMORY.md` の最初の 200 行（または最初の 25KB のうち先に達したほう）がコンテキストにロードされる。トピックファイルは起動時ではなくオンデマンドでロードされる +- **読み書き**: Claude はパターンやプロジェクト固有の知識を発見しながら、セッション中にメモリファイルを読み書きする + +### 自動メモリのアーキテクチャ + +```mermaid +graph TD + A["Claude Session Starts"] --> B["Load MEMORY.md
(first 200 lines / 25KB)"] + B --> C["Session Active"] + C --> D["Claude discovers
patterns & insights"] + D --> E{"Write to
auto memory"} + E -->|General notes| F["MEMORY.md"] + E -->|Topic-specific| G["debugging.md"] + E -->|Topic-specific| H["api-conventions.md"] + C --> I["On-demand load
topic files"] + I --> C + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e8f5e9,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#fff3e0,stroke:#333,color:#333 + style F fill:#fce4ec,stroke:#333,color:#333 + style G fill:#fce4ec,stroke:#333,color:#333 + style H fill:#fce4ec,stroke:#333,color:#333 + style I fill:#f3e5f5,stroke:#333,color:#333 +``` + +### 自動メモリのディレクトリ構造 + +``` +~/.claude/projects//memory/ +├── MEMORY.md # Entrypoint (first 200 lines / 25KB loaded at startup) +├── debugging.md # Topic file (loaded on demand) +├── api-conventions.md # Topic file (loaded on demand) +└── testing-patterns.md # Topic file (loaded on demand) +``` + +### バージョン要件 + +自動メモリには **Claude Code v2.1.59 以降** が必要である。古いバージョンを使っている場合は先にアップグレードする: + +```bash +npm install -g @anthropic-ai/claude-code@latest +``` + +### カスタム自動メモリディレクトリ + +デフォルトでは自動メモリは `~/.claude/projects//memory/` に保存される。`autoMemoryDirectory` 設定（**v2.1.74** 以降で利用可能）で場所を変更できる: + +```jsonc +// In ~/.claude/settings.json or .claude/settings.local.json (user/local settings only) +{ + "autoMemoryDirectory": "/path/to/custom/memory/directory" +} +``` + +> **注意**: `autoMemoryDirectory` はユーザーレベル（`~/.claude/settings.json`）またはローカル設定（`.claude/settings.local.json`）でのみ設定でき、プロジェクト設定や管理ポリシー設定には設定できない。 + +これは次のような用途で便利である: + +- 自動メモリを共有・同期可能な場所に保存したい場合 +- デフォルトの Claude 設定ディレクトリから自動メモリを分離したい場合 +- デフォルト階層の外にプロジェクト固有のパスを使いたい場合 + +### ワークツリーとリポジトリ間の共有 + +同じ git リポジトリ内のすべてのワークツリーとサブディレクトリは、単一の自動メモリディレクトリを共有する。つまり、ワークツリーを切り替えても、同じリポジトリの別サブディレクトリで作業しても、同じメモリファイルを読み書きする。 + +### サブエージェントのメモリ + +サブエージェント（Task のようなツールや並列実行で起動されるもの）は、独自のメモリコンテキストを持てる。サブエージェント定義の `memory` フロントマターフィールドで、ロードするメモリスコープを指定する: + +```yaml +memory: user # Load user-level memory only +memory: project # Load project-level memory only +memory: local # Load local memory only +``` + +これにより、サブエージェントはメモリ階層全体を継承するのではなく、絞られたコンテキストで動作できる。 + +> **注意**: サブエージェントは独自の自動メモリも保持できる。詳細は [公式サブエージェントメモリドキュメント](https://code.claude.com/docs/en/sub-agents#enable-persistent-memory) を参照。 + +### 自動メモリの制御 + +自動メモリは `CLAUDE_CODE_DISABLE_AUTO_MEMORY` 環境変数で制御できる: + +| 値 | 挙動 | +|----|------| +| `0` | 自動メモリを **強制 ON** | +| `1` | 自動メモリを **強制 OFF** | +| *(未設定)* | デフォルト挙動（自動メモリ有効） | + +```bash +# Disable auto memory for a session +CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude + +# Force auto memory on explicitly +CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 claude +``` + +## `--add-dir` で追加ディレクトリを指定する + +`--add-dir` フラグにより、現在の作業ディレクトリ以外のディレクトリからも CLAUDE.md ファイルをロードできる。モノレポや、他ディレクトリのコンテキストが関連するマルチプロジェクト構成で便利である。 + +この機能を有効化するには、環境変数を設定する: + +```bash +CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 +``` + +そしてフラグを付けて Claude Code を起動する: + +```bash +claude --add-dir /path/to/other/project +``` + +Claude は、現在の作業ディレクトリのメモリファイルに加えて、指定された追加ディレクトリの CLAUDE.md をロードする。 + +## 実例 + +### 例 1: プロジェクトメモリの構造 + +**ファイル:** `./CLAUDE.md` + +```markdown +# Project Configuration + +## Project Overview +- **Name**: E-commerce Platform +- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker +- **Team Size**: 5 developers +- **Deadline**: Q4 2025 + +## Architecture +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## Development Standards + +### Code Style +- Use Prettier for formatting +- Use ESLint with airbnb config +- Maximum line length: 100 characters +- Use 2-space indentation + +### Naming Conventions +- **Files**: kebab-case (user-controller.js) +- **Classes**: PascalCase (UserService) +- **Functions/Variables**: camelCase (getUserById) +- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL) +- **Database Tables**: snake_case (user_accounts) + +### Git Workflow +- Branch names: `feature/description` or `fix/description` +- Commit messages: Follow conventional commits +- PR required before merge +- All CI/CD checks must pass +- Minimum 1 approval required + +### Testing Requirements +- Minimum 80% code coverage +- All critical paths must have tests +- Use Jest for unit tests +- Use Cypress for E2E tests +- Test filenames: `*.test.ts` or `*.spec.ts` + +### API Standards +- RESTful endpoints only +- JSON request/response +- Use HTTP status codes correctly +- Version API endpoints: `/api/v1/` +- Document all endpoints with examples + +### Database +- Use migrations for schema changes +- Never hardcode credentials +- Use connection pooling +- Enable query logging in development +- Regular backups required + +### Deployment +- Docker-based deployment +- Kubernetes orchestration +- Blue-green deployment strategy +- Automatic rollback on failure +- Database migrations run before deploy + +## Common Commands + +| Command | Purpose | +|---------|---------| +| `npm run dev` | Start development server | +| `npm test` | Run test suite | +| `npm run lint` | Check code style | +| `npm run build` | Build for production | +| `npm run migrate` | Run database migrations | + +## Team Contacts +- Tech Lead: Sarah Chen (@sarah.chen) +- Product Manager: Mike Johnson (@mike.j) +- DevOps: Alex Kim (@alex.k) + +## Known Issues & Workarounds +- PostgreSQL connection pooling limited to 20 during peak hours +- Workaround: Implement query queuing +- Safari 14 compatibility issues with async generators +- Workaround: Use Babel transpiler + +## Related Projects +- Analytics Dashboard: `/projects/analytics` +- Mobile App: `/projects/mobile` +- Admin Panel: `/projects/admin` +``` + +### 例 2: ディレクトリ固有メモリ + +**ファイル:** `./src/api/CLAUDE.md` + +````markdown +# API Module Standards + +This file overrides root CLAUDE.md for everything in /src/api/ + +## API-Specific Standards + +### Request Validation +- Use Zod for schema validation +- Always validate input +- Return 400 with validation errors +- Include field-level error details + +### Authentication +- All endpoints require JWT token +- Token in Authorization header +- Token expires after 24 hours +- Implement refresh token mechanism + +### Response Format + +All responses must follow this structure: + +```json +{ + "success": true, + "data": { /* actual data */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +Error responses: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "User message", + "details": { /* field errors */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### Pagination +- Use cursor-based pagination (not offset) +- Include `hasMore` boolean +- Limit max page size to 100 +- Default page size: 20 + +### Rate Limiting +- 1000 requests per hour for authenticated users +- 100 requests per hour for public endpoints +- Return 429 when exceeded +- Include retry-after header + +### Caching +- Use Redis for session caching +- Cache duration: 5 minutes default +- Invalidate on write operations +- Tag cache keys with resource type +```` + +### 例 3: 個人メモリ + +**ファイル:** `~/.claude/CLAUDE.md` + +```markdown +# My Development Preferences + +## About Me +- **Experience Level**: 8 years full-stack development +- **Preferred Languages**: TypeScript, Python +- **Communication Style**: Direct, with examples +- **Learning Style**: Visual diagrams with code + +## Code Preferences + +### Error Handling +I prefer explicit error handling with try-catch blocks and meaningful error messages. +Avoid generic errors. Always log errors for debugging. + +### Comments +Use comments for WHY, not WHAT. Code should be self-documenting. +Comments should explain business logic or non-obvious decisions. + +### Testing +I prefer TDD (test-driven development). +Write tests first, then implementation. +Focus on behavior, not implementation details. + +### Architecture +I prefer modular, loosely-coupled design. +Use dependency injection for testability. +Separate concerns (Controllers, Services, Repositories). + +## Debugging Preferences +- Use console.log with prefix: `[DEBUG]` +- Include context: function name, relevant variables +- Use stack traces when available +- Always include timestamps in logs + +## Communication +- Explain complex concepts with diagrams +- Show concrete examples before explaining theory +- Include before/after code snippets +- Summarize key points at the end + +## Project Organization +I organize my projects as: + + project/ + ├── src/ + │ ├── api/ + │ ├── services/ + │ ├── models/ + │ └── utils/ + ├── tests/ + ├── docs/ + └── docker/ + +## Tooling +- **IDE**: VS Code with vim keybindings +- **Terminal**: Zsh with Oh-My-Zsh +- **Format**: Prettier (100 char line length) +- **Linter**: ESLint with airbnb config +- **Test Framework**: Jest with React Testing Library +``` + +_私のテスト_ +Claude に新しいルールを保存するよう依頼する。 + +![Ask Claude to save a new rule](memory-ask-claude.png) +どこにも `Claude.md` ファイルを置いていなかったため、Claude はルールを保存しなかった。続いて Claude に保存場所の確認を依頼した。 + +![Ask Claude to save a new rule](memory-saved.png) + +### 例 4: セッション中のメモリ更新 + +アクティブな Claude Code セッション中にメモリへ新しいルールを追加できる。方法は 2 つある。 + +#### 方法 1: 直接依頼 + +```markdown +User: Remember that I prefer using React hooks instead of class components + for all new components. + +Claude: I'm adding that to your memory. Which memory file should this go in? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: ✅ Memory saved! + +Added to ./CLAUDE.md: +--- + +### Component Development +- Use functional components with React Hooks +- Prefer hooks over class components +- Custom hooks for reusable logic +- Use useCallback for event handlers +- Use useMemo for expensive computations +``` + +#### 方法 2: 「# new rule into memory」パターンを使う + +明示的なパターン「# new rule into memory」でメモリ更新を発火させることもできる: + +```markdown +User: # new rule into memory + Always validate user input with Zod schemas before processing. + +Claude: I'm saving this rule to memory. Which memory file should I use? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: ✅ Memory saved! + +Added to ./CLAUDE.md: +--- + +### Input Validation +- Always validate user input with Zod schemas before processing +- Define schemas at the top of each API handler file +- Return 400 status with validation errors +``` + +#### メモリ追加のコツ + +- ルールは具体的かつ実行可能にする +- 関連するルールはセクション見出しの下にまとめる +- 内容を重複させず、既存セクションを更新する +- 適切なメモリスコープ（プロジェクト vs 個人）を選ぶ + +## メモリ機能の比較 + +| 機能 | Claude Web／Desktop | Claude Code（CLAUDE.md） | +|------|-------------------|------------------------| +| 自動合成 | ✅ 24 時間ごと | ✅ 自動メモリ | +| プロジェクト横断 | ✅ 共有 | ❌ プロジェクト固有 | +| チームアクセス | ✅ 共有プロジェクト | ✅ Git 管理 | +| 検索可能 | ✅ 標準搭載 | ✅ `/memory` 経由 | +| 編集可能 | ✅ チャット内 | ✅ 直接ファイル編集 | +| インポート／エクスポート | ✅ 可 | ✅ コピー／ペースト | +| 永続性 | ✅ 24 時間以上 | ✅ 無期限 | + +### Claude Web／Desktop のメモリ + +#### メモリ合成のタイムライン + +```mermaid +graph LR + A["Day 1: User
Conversations"] -->|24 hours| B["Day 2: Memory
Synthesis"] + B -->|Automatic| C["Memory Updated
Summarized"] + C -->|Loaded in| D["Day 2-N:
New Conversations"] + D -->|Add to| E["Memory"] + E -->|24 hours later| F["Memory Refreshed"] +``` + +**メモリサマリの例:** + +```markdown +## Claude's Memory of User + +### Professional Background +- Senior full-stack developer with 8 years experience +- Focus on TypeScript/Node.js backends and React frontends +- Active open source contributor +- Interested in AI and machine learning + +### Project Context +- Currently building e-commerce platform +- Tech stack: Node.js, PostgreSQL, React 18, Docker +- Working with team of 5 developers +- Using CI/CD and blue-green deployments + +### Communication Preferences +- Prefers direct, concise explanations +- Likes visual diagrams and examples +- Appreciates code snippets +- Explains business logic in comments + +### Current Goals +- Improve API performance +- Increase test coverage to 90% +- Implement caching strategy +- Document architecture +``` + +## ベストプラクティス + +### Do — 含めるべきこと + +- **具体的かつ詳細に**: 曖昧なガイダンスではなく、明確で詳細な指示を使う + - ✅ 良い: 「すべての JavaScript ファイルで 2 スペースのインデントを使う」 + - ❌ 避ける: 「ベストプラクティスに従う」 + +- **整理する**: 明確な Markdown のセクションと見出しでメモリファイルを構造化する + +- **適切な階層レベルを使う**: + - **Managed Policy**: 全社ポリシー、セキュリティ標準、コンプライアンス要件 + - **Project Memory**: チーム標準、アーキテクチャ、コーディング規約（git にコミット） + - **User Memory**: 個人設定、コミュニケーションスタイル、ツール選択 + - **Directory Memory**: モジュール固有のルールとオーバーライド + +- **インポートを活用する**: `@path/to/file` 構文で既存ドキュメントを参照する + - 最大 5 段階の再帰的ネストをサポート + - メモリファイル間の重複を避ける + - 例: `See @README.md for project overview` + +- **頻出コマンドを記録する**: 繰り返し使うコマンドを含めて時間を節約する + +- **プロジェクトメモリをバージョン管理する**: チームに恩恵があるよう、プロジェクトレベル CLAUDE.md を git にコミットする + +- **定期的に見直す**: プロジェクトの進化や要件変更に合わせ、メモリを定期的に更新する + +- **具体例を提示する**: コードスニペットや具体的なシナリオを含める + +### Don't — 避けるべきこと + +- **シークレットを保存しない**: API キー、パスワード、トークン、認証情報を絶対に含めない + +- **機微データを含めない**: 個人情報、私的情報、独自の機密情報は不可 + +- **内容を重複させない**: 既存ドキュメントを参照するためにインポート（`@path`）を使う + +- **曖昧にしない**: 「ベストプラクティスに従う」「良いコードを書く」のような汎用的記述を避ける + +- **長くしすぎない**: 個々のメモリファイルは焦点を絞り、500 行以下に保つ + +- **整理しすぎない**: 階層は戦略的に使う。サブディレクトリオーバーライドを過剰に作らない + +- **更新を忘れない**: 古いメモリは混乱と時代遅れの慣習を招く + +- **ネスト上限を超えない**: メモリインポートは最大 5 段階まで + +### メモリ管理のヒント + +**適切なメモリレベルを選ぶ:** + +| ユースケース | メモリレベル | 理由 | +|-----------|-----------|------| +| 全社セキュリティポリシー | Managed Policy | 組織全体の全プロジェクトに適用 | +| チームのコードスタイルガイド | Project | git でチームに共有 | +| 自分の好みのエディタショートカット | User | 個人設定であり共有しない | +| API モジュール標準 | Directory | そのモジュールのみに固有 | + +**素早い更新ワークフロー:** + +1. 単一ルールの場合: 会話で `#` プレフィックスを使う +2. 複数の変更の場合: `/memory` でエディタを開く +3. 初期セットアップの場合: `/init` でテンプレートを作成する + +**インポートのベストプラクティス:** + +```markdown +# Good: Reference existing docs +@README.md +@docs/architecture.md +@package.json + +# Avoid: Copying content that exists elsewhere +# Instead of copying README content into CLAUDE.md, just import it +``` + +## インストール手順 + +### プロジェクトメモリのセットアップ + +#### 方法 1: `/init` コマンドを使う（推奨） + +プロジェクトメモリをセットアップする最速の方法: + +1. **プロジェクトディレクトリに移動:** + ```bash + cd /path/to/your/project + ``` + +2. **Claude Code で init コマンドを実行:** + ```bash + /init + ``` + +3. **Claude がテンプレート構造で CLAUDE.md を作成・記入する** + +4. **生成されたファイルをプロジェクトに合わせてカスタマイズする** + +5. **git にコミット:** + ```bash + git add CLAUDE.md + git commit -m "Initialize project memory with /init" + ``` + +#### 方法 2: 手動作成 + +手動でセットアップしたい場合: + +1. **プロジェクトルートに CLAUDE.md を作成:** + ```bash + cd /path/to/your/project + touch CLAUDE.md + ``` + +2. **プロジェクト標準を追加:** + ```bash + cat > CLAUDE.md << 'EOF' + # Project Configuration + + ## Project Overview + - **Name**: Your Project Name + - **Tech Stack**: List your technologies + - **Team Size**: Number of developers + + ## Development Standards + - Your coding standards + - Naming conventions + - Testing requirements + EOF + ``` + +3. **git にコミット:** + ```bash + git add CLAUDE.md + git commit -m "Add project memory configuration" + ``` + +#### 方法 3: `#` で素早く更新する + +CLAUDE.md が存在したら、会話中に素早くルールを追加できる: + +```markdown +# Use semantic versioning for all releases + +# Always run tests before committing + +# Prefer composition over inheritance +``` + +Claude はどのメモリファイルを更新するかを尋ねる。 + +### 個人メモリのセットアップ + +1. **~/.claude ディレクトリを作成:** + ```bash + mkdir -p ~/.claude + ``` + +2. **個人 CLAUDE.md を作成:** + ```bash + touch ~/.claude/CLAUDE.md + ``` + +3. **設定を追加:** + ```bash + cat > ~/.claude/CLAUDE.md << 'EOF' + # My Development Preferences + + ## About Me + - Experience Level: [Your level] + - Preferred Languages: [Your languages] + - Communication Style: [Your style] + + ## Code Preferences + - [Your preferences] + EOF + ``` + +### ディレクトリ固有メモリのセットアップ + +1. **特定ディレクトリ用のメモリを作成:** + ```bash + mkdir -p /path/to/directory/.claude + touch /path/to/directory/CLAUDE.md + ``` + +2. **ディレクトリ固有のルールを追加:** + ```bash + cat > /path/to/directory/CLAUDE.md << 'EOF' + # [Directory Name] Standards + + This file overrides root CLAUDE.md for this directory. + + ## [Specific Standards] + EOF + ``` + +3. **バージョン管理にコミット:** + ```bash + git add /path/to/directory/CLAUDE.md + git commit -m "Add [directory] memory configuration" + ``` + +### セットアップ確認 + +1. **メモリの場所を確認:** + ```bash + # Project root memory + ls -la ./CLAUDE.md + + # Personal memory + ls -la ~/.claude/CLAUDE.md + ``` + +2. **Claude Code はセッション開始時にこれらのファイルを自動でロードする** + +3. **プロジェクトで新しいセッションを始め Claude Code でテストする** + +## 公式ドキュメント + +最新情報は公式 Claude Code ドキュメントを参照する: + +- **[メモリドキュメント](https://code.claude.com/docs/en/memory)** — メモリシステムの完全リファレンス +- **[スラッシュコマンドリファレンス](https://code.claude.com/docs/en/interactive-mode)** — `/init` や `/memory` を含む全組み込みコマンド +- **[CLI リファレンス](https://code.claude.com/docs/en/cli-reference)** — コマンドラインインターフェースのドキュメント + +### 公式ドキュメントから抜粋した主要な技術詳細 + +**メモリのロード:** + +- すべてのメモリファイルは Claude Code 起動時に自動でロードされる +- Claude は現在の作業ディレクトリから上位へさかのぼって CLAUDE.md ファイルを発見する +- サブツリー内のファイルはそのディレクトリにアクセスする際にコンテキスト的に発見・ロードされる + +**インポート構文:** + +- 外部コンテンツの取り込みに `@path/to/file` を使う（例: `@~/.claude/my-project-instructions.md`） +- 相対パスと絶対パスの両方をサポート +- 再帰的インポートをサポート（最大ネスト深さ 5） +- 外部からの初回インポートは承認ダイアログが出る +- Markdown のコードスパンやコードブロック内では評価されない +- 参照されたコンテンツが Claude のコンテキストに自動で含まれる + +**メモリ階層の優先順位:** + +1. Managed Policy（最高優先度） +2. Managed Drop-ins（`managed-settings.d/`、v2.1.83+） +3. Project Memory +4. Project Rules（`.claude/rules/`） +5. User Memory +6. User-Level Rules（`~/.claude/rules/`） +7. Local Project Memory +8. Auto Memory（最低優先度） + +## 関連概念へのリンク + +### 統合ポイント +- [MCP プロトコル](../05-mcp/) — メモリと並ぶライブデータアクセス +- [スラッシュコマンド](../01-slash-commands/) — セッション固有のショートカット +- [スキル](../03-skills/) — メモリコンテキストを伴う自動化ワークフロー + +### 関連する Claude 機能 +- [Claude Web メモリ](https://claude.ai) — 自動合成 +- [公式メモリドキュメント](https://code.claude.com/docs/en/memory) — Anthropic ドキュメント + +--- +**Last Updated**: April 24, 2026 +**Claude Code Version**: 2.1.119 +**Sources**: +- https://code.claude.com/docs/en/memory +- https://code.claude.com/docs/en/settings +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/ja/02-memory/directory-api-CLAUDE.md b/ja/02-memory/directory-api-CLAUDE.md new file mode 100644 index 0000000..8b346b2 --- /dev/null +++ b/ja/02-memory/directory-api-CLAUDE.md @@ -0,0 +1,68 @@ + + + + +# API モジュール標準 + +このファイルは /src/api/ 配下のすべてに対し、ルートの CLAUDE.md を上書きする。 + +## API 固有の標準 + +### リクエスト検証 +- スキーマ検証には Zod を使う +- 入力は必ず検証する +- 検証エラー時は 400 を返す +- フィールド単位のエラー詳細を含める + +### 認証 +- すべてのエンドポイントで JWT トークンを必須とする +- トークンは Authorization ヘッダに付ける +- トークンの有効期限は 24 時間 +- リフレッシュトークン機構を実装する + +### レスポンス形式 + +すべてのレスポンスは次の構造に従う: + +```json +{ + "success": true, + "data": { /* actual data */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +エラーレスポンス: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "User message", + "details": { /* field errors */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### ページネーション +- カーソルベースページネーションを使う（オフセット方式は使わない） +- `hasMore` の真偽値を含める +- 1 ページの最大サイズは 100 まで +- デフォルトのページサイズ: 20 + +### レート制限 +- 認証済みユーザー: 1 時間あたり 1000 リクエスト +- 公開エンドポイント: 1 時間あたり 100 リクエスト +- 上限超過時は 429 を返す +- retry-after ヘッダを付ける + +### キャッシュ +- セッションキャッシュには Redis を使う +- キャッシュ期間: デフォルト 5 分 +- 書き込み操作時に無効化する +- キャッシュキーにリソース種別のタグを付ける + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/02-memory/personal-CLAUDE.md b/ja/02-memory/personal-CLAUDE.md new file mode 100644 index 0000000..d99748a --- /dev/null +++ b/ja/02-memory/personal-CLAUDE.md @@ -0,0 +1,67 @@ + + + + +# 開発上の好み + +## プロフィール +- **経験年数**: フルスタック開発 8 年 +- **得意な言語**: TypeScript、Python +- **コミュニケーションスタイル**: 例を示しながら端的に +- **学び方**: 視覚的な図解 + コード + +## コードに関する好み + +### エラーハンドリング +try-catch ブロックと意味のあるエラーメッセージで、明示的にエラーを扱うのを好む。 +汎用的なエラーは避ける。デバッグのため必ずエラーをログに残す。 + +### コメント +コメントは「なぜ（WHY）」を書く。「なに（WHAT）」ではない。コードはそれ自身がドキュメントであるべき。 +ビジネスロジックや自明でない判断についてコメントで説明する。 + +### テスト +TDD（テスト駆動開発）を好む。 +先にテストを書き、その後で実装する。 +実装の詳細ではなく、振る舞いに焦点を当てる。 + +### アーキテクチャ +モジュール化された疎結合の設計を好む。 +テスト容易性のため依存性注入を使う。 +関心を分離する（Controllers、Services、Repositories）。 + +## デバッグの好み +- console.log にプレフィックスを付ける: `[DEBUG]` +- コンテキストを含める: 関数名、関連変数 +- 利用可能ならスタックトレースを使う +- ログには必ずタイムスタンプを含める + +## コミュニケーション +- 複雑な概念は図で説明する +- 理論より先に具体例を示す +- 変更前／変更後のコードスニペットを含める +- 最後に要点をまとめる + +## プロジェクト構成 +プロジェクトは次のように整理する: +``` +project/ + ├── src/ + │ ├── api/ + │ ├── services/ + │ ├── models/ + │ └── utils/ + ├── tests/ + ├── docs/ + └── docker/ +``` + +## ツール +- **IDE**: VS Code（vim キーバインド） +- **ターミナル**: Zsh + Oh-My-Zsh +- **フォーマッタ**: Prettier（行長 100 文字） +- **リンタ**: ESLint（airbnb config） +- **テストフレームワーク**: Jest + React Testing Library + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/02-memory/project-CLAUDE.md b/ja/02-memory/project-CLAUDE.md new file mode 100644 index 0000000..72275ac --- /dev/null +++ b/ja/02-memory/project-CLAUDE.md @@ -0,0 +1,95 @@ + + + + +# プロジェクト設定 + +## プロジェクト概要 +- **名称**: E コマースプラットフォーム +- **技術スタック**: Node.js、PostgreSQL、React 18、Docker +- **チーム規模**: 開発者 5 名 +- **デッドライン**: 2025 年第 4 四半期 + +## アーキテクチャ +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## 開発標準 + +### コードスタイル +- フォーマットには Prettier を使う +- ESLint（airbnb config）を使う +- 1 行の最大長: 100 文字 +- インデント: スペース 2 個 + +### 命名規則 +- **ファイル**: kebab-case（user-controller.js） +- **クラス**: PascalCase（UserService） +- **関数／変数**: camelCase（getUserById） +- **定数**: UPPER_SNAKE_CASE（API_BASE_URL） +- **データベーステーブル**: snake_case（user_accounts） + +### Git ワークフロー +- ブランチ名: `feature/description` または `fix/description` +- コミットメッセージ: Conventional Commits に従う +- マージ前に PR が必要 +- すべての CI/CD チェックを通す +- 最低 1 名の承認が必要 + +### テスト要件 +- コードカバレッジ最低 80% +- すべての主要パスにテストが必要 +- ユニットテストには Jest を使う +- E2E テストには Cypress を使う +- テストファイル名: `*.test.ts` または `*.spec.ts` + +### API 標準 +- RESTful エンドポイントのみ +- リクエスト／レスポンスは JSON +- HTTP ステータスコードを正しく使う +- API はバージョン付きエンドポイント: `/api/v1/` +- 全エンドポイントに例付きドキュメントを用意する + +### データベース +- スキーマ変更にはマイグレーションを使う +- 認証情報をハードコードしない +- コネクションプーリングを使う +- 開発環境ではクエリログを有効化する +- 定期的なバックアップを必須とする + +### デプロイ +- Docker ベースのデプロイ +- Kubernetes によるオーケストレーション +- Blue-Green デプロイ戦略 +- 失敗時は自動ロールバック +- データベースマイグレーションはデプロイ前に実行する + +## よく使うコマンド + +| コマンド | 用途 | +|---------|------| +| `npm run dev` | 開発サーバを起動 | +| `npm test` | テストスイートを実行 | +| `npm run lint` | コードスタイルを確認 | +| `npm run build` | 本番向けビルド | +| `npm run migrate` | データベースマイグレーションを実行 | + +## チーム連絡先 +- Tech Lead: Sarah Chen (@sarah.chen) +- Product Manager: Mike Johnson (@mike.j) +- DevOps: Alex Kim (@alex.k) + +## 既知の問題と回避策 +- ピーク時、PostgreSQL のコネクションプールが 20 に制限される +- 回避策: クエリのキューイングを実装する +- Safari 14 で async generator の互換性問題 +- 回避策: Babel トランスパイラを使う + +## 関連プロジェクト +- Analytics Dashboard: `/projects/analytics` +- Mobile App: `/projects/mobile` +- Admin Panel: `/projects/admin` + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/03-skills/README.md b/ja/03-skills/README.md new file mode 100644 index 0000000..5281168 --- /dev/null +++ b/ja/03-skills/README.md @@ -0,0 +1,832 @@ + + + + + + Claude How To + + +# Agent Skills ガイド + +Agent Skills は、Claude の機能を拡張する再利用可能でファイルシステムベースの能力である。ドメイン固有の専門知識、ワークフロー、ベストプラクティスを、関連性に応じて Claude が自動的に利用できる発見可能なコンポーネントへとパッケージ化する。 + +## 概要 + +**Agent Skills** は汎用エージェントを専門家へと変貌させるモジュール化された能力である。プロンプト（単発タスク向けの会話レベルの指示）と異なり、スキルは必要に応じてロードされ、複数の会話にわたって同じガイダンスを繰り返し提供する必要をなくす。 + +### 主なメリット + +- **Claude を専門化**: ドメイン固有のタスク向けに能力を仕立てる +- **繰り返しの削減**: 一度作成すれば、会話をまたいで自動的に利用される +- **能力の組み合わせ**: スキルを組み合わせて複雑なワークフローを構築できる +- **ワークフローのスケール**: 複数のプロジェクトやチームでスキルを再利用できる +- **品質の維持**: ベストプラクティスをワークフローへ直接埋め込める + +スキルは [Agent Skills](https://agentskills.io) のオープン標準に準拠しており、複数の AI ツールで動作する。Claude Code は、呼び出し制御、サブエージェント実行、動的コンテキスト注入といった追加機能で標準を拡張している。 + +> **Note**: カスタムスラッシュコマンドはスキルへ統合された。`.claude/commands/` 内のファイルは引き続き動作し、同じフロントマターフィールドをサポートする。新規開発ではスキルが推奨される。同一パスに両方が存在する場合（例: `.claude/commands/review.md` と `.claude/skills/review/SKILL.md`）、スキルが優先される。 + +## スキルの仕組み: プログレッシブディスクロージャ + +スキルは **プログレッシブディスクロージャ** アーキテクチャを活用する。Claude は事前に全てを消費するのではなく、必要に応じて段階的に情報をロードする。これにより、無制限のスケーラビリティを保ちつつ効率的なコンテキスト管理が可能となる。 + +### 3 段階のロード + +```mermaid +graph TB + subgraph "Level 1: Metadata (Always Loaded)" + A["YAML Frontmatter"] + A1["~100 tokens per skill"] + A2["name + description"] + end + + subgraph "Level 2: Instructions (When Triggered)" + B["SKILL.md Body"] + B1["Under 5k tokens"] + B2["Workflows & guidance"] + end + + subgraph "Level 3: Resources (As Needed)" + C["Bundled Files"] + C1["Effectively unlimited"] + C2["Scripts, templates, docs"] + end + + A --> B + B --> C +``` + +| レベル | ロードされるタイミング | トークンコスト | 内容 | +|-------|------------|------------|---------| +| **Level 1: メタデータ** | 常時（起動時） | スキルあたり約 100 トークン | YAML フロントマターの `name` と `description` | +| **Level 2: 命令** | スキルがトリガーされたとき | 5k トークン未満 | SKILL.md 本文の指示とガイダンス | +| **Level 3+: リソース** | 必要に応じて | 実質無制限 | bash 経由で実行されるバンドル済みファイル（コンテンツはコンテキストにロードされない） | + +つまり、コンテキストにペナルティを与えずに多数のスキルをインストールできる。Claude は、実際にトリガーされるまでは各スキルの存在と用途しか知らない。 + +## スキルのロードプロセス + +```mermaid +sequenceDiagram + participant User + participant Claude + participant System + participant SkillInst as Skill Instructions + participant SkillRes as Skill Resources + + User->>Claude: "Review this code for security issues" + Claude->>System: Check available skills (metadata) + System-->>Claude: Skill descriptions loaded at startup + Claude->>Claude: Match request to skill description + Claude->>SkillInst: Read code-review/SKILL.md + SkillInst-->>Claude: Level 2: Instructions loaded + Claude->>Claude: Determine: Need templates? + Claude->>SkillRes: Read templates/checklist.md + SkillRes-->>Claude: Level 3: Template loaded + Claude->>Claude: Execute skill instructions + Claude->>User: Comprehensive code review +``` + +## スキルの種類と配置場所 + +| 種類 | 配置場所 | スコープ | 共有 | 適した用途 | +|------|----------|-------|--------|----------| +| **Enterprise** | 管理対象設定 | 組織内全ユーザー | あり | 組織全体の標準 | +| **Personal** | `~/.claude/skills//SKILL.md` | 個人 | なし | 個人のワークフロー | +| **Project** | `.claude/skills//SKILL.md` | チーム | あり（git 経由） | チームの標準 | +| **Plugin** | `/skills//SKILL.md` | 有効化された範囲 | プラグインに依存 | プラグインへのバンドル | + +スキル名がレベル間で重複する場合、優先度の高い配置場所が優先される: **enterprise > personal > project**。プラグインスキルは `plugin-name:skill-name` の名前空間を用いるため衝突しない。 + +### 自動検出 + +**ネストされたディレクトリ**: サブディレクトリ内のファイルを扱う際、Claude Code はネストされた `.claude/skills/` ディレクトリからスキルを自動的に検出する。例えば `packages/frontend/` 内のファイルを編集中の場合、Claude Code は `packages/frontend/.claude/skills/` 内のスキルも探す。これは、パッケージごとに独自のスキルを持つモノレポ構成をサポートする。 + +**`--add-dir` ディレクトリ**: `--add-dir` で追加されたディレクトリのスキルは、変更のライブ検出を伴って自動的にロードされる。それらのディレクトリ内のスキルファイルへの編集は、Claude Code を再起動せずに直ちに反映される。 + +**description のバジェット**: スキルの説明（Level 1 メタデータ）は **コンテキストウィンドウの 1 %** が上限となる（フォールバック: **8,000 文字**）。多数のスキルをインストールしている場合、説明が短縮されることがある。スキル名は常に含まれるが、説明は容量に合わせて切り詰められる。説明では主要なユースケースを冒頭に置くこと。バジェットは環境変数 `SLASH_COMMAND_TOOL_CHAR_BUDGET` で上書きできる。 + +## カスタムスキルの作成 + +### 基本ディレクトリ構造 + +``` +my-skill/ +├── SKILL.md # メイン命令（必須） +├── template.md # Claude が埋めるテンプレート +├── examples/ +│ └── sample.md # 期待される形式を示す出力例 +└── scripts/ + └── validate.sh # Claude が実行できるスクリプト +``` + +### SKILL.md の形式 + +```yaml +--- +name: your-skill-name +description: Brief description of what this Skill does and when to use it +--- + +# Your Skill Name + +## Instructions +Provide clear, step-by-step guidance for Claude. + +## Examples +Show concrete examples of using this Skill. +``` + +### 必須フィールド + +- **name**: 小文字、数字、ハイフンのみ（最大 64 文字）。"anthropic" や "claude" を含めることはできない。 +- **description**: スキルが何をするかと、いつ使うか（最大 1024 文字）。Claude がスキルを発火させるべきタイミングを判断する上で重要である。 + +### オプションのフロントマターフィールド + +```yaml +--- +name: my-skill +description: What this skill does and when to use it +argument-hint: "[filename] [format]" # 自動補完用ヒント +disable-model-invocation: true # ユーザーのみ呼び出し可 +user-invocable: false # スラッシュメニューから非表示 +allowed-tools: Read, Grep, Glob # ツールアクセスの制限 +model: opus # 使用するモデルの指定 +effort: high # 努力レベルの上書き（low, medium, high, max） +context: fork # 隔離されたサブエージェントで実行 +agent: Explore # エージェントタイプ（context: fork と併用） +shell: bash # コマンドのシェル: bash（既定）または powershell +hooks: # スキルスコープのフック + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/validate.sh" +paths: "src/api/**/*.ts" # スキルの発火を制限する glob パターン +--- +``` + +| フィールド | 説明 | +|-------|-------------| +| `name` | 小文字、数字、ハイフンのみ（最大 64 文字）。"anthropic" や "claude" を含められない。 | +| `description` | スキルが何をするかと、いつ使うか（最大 1024 文字）。自動呼び出しのマッチングに重要。 | +| `argument-hint` | `/` の自動補完メニューに表示されるヒント（例: `"[filename] [format]"`）。 | +| `disable-model-invocation` | `true` = ユーザーのみが `/name` で呼び出せる。Claude は自動呼び出ししない。 | +| `user-invocable` | `false` = `/` メニューから非表示。Claude のみが自動呼び出し可能。 | +| `allowed-tools` | 許可プロンプトなしでスキルが利用可能なツールのカンマ区切りリスト。 | +| `model` | スキルが有効な間のモデルの上書き（例: `opus`, `sonnet`）。 | +| `effort` | スキルが有効な間の努力レベルの上書き: `low`, `medium`, `high`, `max`。 | +| `context` | `fork` を指定するとスキルを独自のコンテキストウィンドウを持つフォーク済みサブエージェントコンテキストで実行する。 | +| `agent` | `context: fork` の際のサブエージェントタイプ（例: `Explore`, `Plan`, `general-purpose`）。 | +| `shell` | `!`command`` 置換とスクリプトに使うシェル: `bash`（既定）または `powershell`。 | +| `hooks` | このスキルのライフサイクルにスコープされたフック（グローバルフックと同じ形式）。 | +| `paths` | スキルが自動発火する条件を制限する glob パターン。カンマ区切り文字列または YAML リスト。パス固有ルールと同じ形式。 | + +## スキルのコンテンツの種類 + +スキルは目的に応じて 2 種類のコンテンツを含むことができる。 + +### リファレンスコンテンツ + +現在の作業に Claude が適用する知識を追加する。規約、パターン、スタイルガイド、ドメイン知識など。会話のコンテキストとインラインで動作する。 + +```yaml +--- +name: api-conventions +description: API design patterns for this codebase +--- + +When writing API endpoints: +- Use RESTful naming conventions +- Return consistent error formats +- Include request validation +``` + +### タスクコンテンツ + +特定のアクションを行うステップバイステップの命令。`/skill-name` で直接呼び出されることが多い。 + +```yaml +--- +name: deploy +description: Deploy the application to production +context: fork +disable-model-invocation: true +--- + +Deploy the application: +1. Run the test suite +2. Build the application +3. Push to the deployment target +``` + +## スキルの呼び出し制御 + +既定では、ユーザーも Claude もどのスキルでも呼び出せる。2 つのフロントマターフィールドが 3 つの呼び出しモードを制御する。 + +| フロントマター | ユーザー呼び出し | Claude 呼び出し | +|---|---|---| +| （既定） | 可 | 可 | +| `disable-model-invocation: true` | 可 | 不可 | +| `user-invocable: false` | 不可 | 可 | + +**`disable-model-invocation: true` を使うべき場面**: 副作用のあるワークフロー（`/commit`, `/deploy`, `/send-slack-message`）。コードが整って見えるからといって Claude が勝手にデプロイすることは望まれない。 + +**`user-invocable: false` を使うべき場面**: コマンドとして実行可能ではない背景知識。`legacy-system-context` のようなスキルは古いシステムの仕組みを説明するもので、Claude には有用だがユーザーにとって意味のあるアクションではない。 + +## 文字列置換 + +スキルは、コンテンツが Claude に届く前に解決される動的な値をサポートする。 + +| 変数 | 説明 | +|----------|-------------| +| `$ARGUMENTS` | スキル呼び出し時に渡された全引数 | +| `$ARGUMENTS[N]` または `$N` | インデックス（0 始まり）で特定の引数にアクセス | +| `${CLAUDE_SESSION_ID}` | 現在のセッション ID | +| `${CLAUDE_SKILL_DIR}` | スキルの SKILL.md ファイルを含むディレクトリ | +| `` !`command` `` | 動的コンテキスト注入 — シェルコマンドを実行し出力をインライン化する | + +**例:** + +```yaml +--- +name: fix-issue +description: Fix a GitHub issue +--- + +Fix GitHub issue $ARGUMENTS following our coding standards. +1. Read the issue description +2. Implement the fix +3. Write tests +4. Create a commit +``` + +`/fix-issue 123` を実行すると `$ARGUMENTS` が `123` に置換される。 + +## 動的コンテキストの注入 + +`!`command`` 構文は、スキルコンテンツが Claude に送信される前にシェルコマンドを実行する。 + +```yaml +--- +name: pr-summary +description: Summarize changes in a pull request +context: fork +agent: Explore +--- + +## Pull request context +- PR diff: !`gh pr diff` +- PR comments: !`gh pr view --comments` +- Changed files: !`gh pr diff --name-only` + +## Your task +Summarize this pull request... +``` + +コマンドは即座に実行され、Claude には最終出力のみが見える。既定では `bash` で実行される。フロントマターで `shell: powershell` を設定すれば PowerShell を使える。 + +## サブエージェント内でのスキル実行 + +スキルに `context: fork` を追加すると、隔離されたサブエージェントコンテキストで実行される。スキルのコンテンツが、独自のコンテキストウィンドウを持つ専用サブエージェントへのタスクとなり、メインの会話を散らかさない。 + +`agent` フィールドはどのエージェントタイプを使うかを指定する。 + +| エージェントタイプ | 適した用途 | +|---|---| +| `Explore` | 読み取り専用のリサーチ、コードベース解析 | +| `Plan` | 実装プランの作成 | +| `general-purpose` | 全ツールが必要な広範なタスク | +| カスタムエージェント | 設定で定義された専門エージェント | + +**フロントマターの例:** + +```yaml +--- +context: fork +agent: Explore +--- +``` + +**完全なスキル例:** + +```yaml +--- +name: deep-research +description: Research a topic thoroughly +context: fork +agent: Explore +--- + +Research $ARGUMENTS thoroughly: +1. Find relevant files using Glob and Grep +2. Read and analyze the code +3. Summarize findings with specific file references +``` + +## 実用例 + +### 例 1: コードレビュースキル + +**ディレクトリ構造:** + +``` +~/.claude/skills/code-review/ +├── SKILL.md +├── templates/ +│ ├── review-checklist.md +│ └── finding-template.md +└── scripts/ + ├── analyze-metrics.py + └── compare-complexity.py +``` + +**ファイル:** `~/.claude/skills/code-review/SKILL.md` + +```yaml +--- +name: code-review-specialist +description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, evaluate pull requests, or mention code review, security analysis, or performance optimization. +--- + +# Code Review Skill + +This skill provides comprehensive code review capabilities focusing on: + +1. **Security Analysis** + - Authentication/authorization issues + - Data exposure risks + - Injection vulnerabilities + - Cryptographic weaknesses + +2. **Performance Review** + - Algorithm efficiency (Big O analysis) + - Memory optimization + - Database query optimization + - Caching opportunities + +3. **Code Quality** + - SOLID principles + - Design patterns + - Naming conventions + - Test coverage + +4. **Maintainability** + - Code readability + - Function size (should be < 50 lines) + - Cyclomatic complexity + - Type safety + +## Review Template + +For each piece of code reviewed, provide: + +### Summary +- Overall quality assessment (1-5) +- Key findings count +- Recommended priority areas + +### Critical Issues (if any) +- **Issue**: Clear description +- **Location**: File and line number +- **Impact**: Why this matters +- **Severity**: Critical/High/Medium +- **Fix**: Code example + +For detailed checklists, see [templates/review-checklist.md](templates/review-checklist.md). +``` + +### 例 2: コードベース可視化スキル + +インタラクティブな HTML 可視化を生成するスキル。 + +**ディレクトリ構造:** + +``` +~/.claude/skills/codebase-visualizer/ +├── SKILL.md +└── scripts/ + └── visualize.py +``` + +**ファイル:** `~/.claude/skills/codebase-visualizer/SKILL.md` + +````yaml +--- +name: codebase-visualizer +description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files. +allowed-tools: Bash(python *) +--- + +# Codebase Visualizer + +Generate an interactive HTML tree view showing your project's file structure. + +## Usage + +Run the visualization script from your project root: + +```bash +python ~/.claude/skills/codebase-visualizer/scripts/visualize.py . +``` + +This creates `codebase-map.html` and opens it in your default browser. + +## What the visualization shows + +- **Collapsible directories**: Click folders to expand/collapse +- **File sizes**: Displayed next to each file +- **Colors**: Different colors for different file types +- **Directory totals**: Shows aggregate size of each folder +```` + +バンドルされた Python スクリプトが重い処理を担い、Claude はオーケストレーションを行う。 + +### 例 3: デプロイスキル（ユーザー呼び出し専用） + +```yaml +--- +name: deploy +description: Deploy the application to production +disable-model-invocation: true +allowed-tools: Bash(npm *), Bash(git *) +--- + +Deploy $ARGUMENTS to production: + +1. Run the test suite: `npm test` +2. Build the application: `npm run build` +3. Push to the deployment target +4. Verify the deployment succeeded +5. Report deployment status +``` + +### 例 4: ブランドボイススキル（背景知識） + +```yaml +--- +name: brand-voice +description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, or public-facing content. +user-invocable: false +--- + +## Tone of Voice +- **Friendly but professional** - approachable without being casual +- **Clear and concise** - avoid jargon +- **Confident** - we know what we're doing +- **Empathetic** - understand user needs + +## Writing Guidelines +- Use "you" when addressing readers +- Use active voice +- Keep sentences under 20 words +- Start with value proposition + +For templates, see [templates/](templates/). +``` + +### 例 5: CLAUDE.md ジェネレータースキル + +```yaml +--- +name: claude-md +description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding. Use when users mention CLAUDE.md, project documentation, or AI onboarding. +--- + +## Core Principles + +**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation. + +### The Golden Rules + +1. **Less is More**: Keep under 300 lines (ideally under 100) +2. **Universal Applicability**: Only include information relevant to EVERY session +3. **Don't Use Claude as a Linter**: Use deterministic tools instead +4. **Never Auto-Generate**: Craft it manually with careful consideration + +## Essential Sections + +- **Project Name**: Brief one-line description +- **Tech Stack**: Primary language, frameworks, database +- **Development Commands**: Install, test, build commands +- **Critical Conventions**: Only non-obvious, high-impact conventions +- **Known Issues / Gotchas**: Things that trip up developers +``` + +### 例 6: スクリプトを伴うリファクタリングスキル + +**ディレクトリ構造:** + +``` +refactor/ +├── SKILL.md +├── references/ +│ ├── code-smells.md +│ └── refactoring-catalog.md +├── templates/ +│ └── refactoring-plan.md +└── scripts/ + ├── analyze-complexity.py + └── detect-smells.py +``` + +**ファイル:** `refactor/SKILL.md` + +```yaml +--- +name: code-refactor +description: Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, or eliminate code smells. +--- + +# Code Refactoring Skill + +A phased approach emphasizing safe, incremental changes backed by tests. + +## Workflow + +Phase 1: Research & Analysis → Phase 2: Test Coverage Assessment → +Phase 3: Code Smell Identification → Phase 4: Refactoring Plan Creation → +Phase 5: Incremental Implementation → Phase 6: Review & Iteration + +## Core Principles + +1. **Behavior Preservation**: External behavior must remain unchanged +2. **Small Steps**: Make tiny, testable changes +3. **Test-Driven**: Tests are the safety net +4. **Continuous**: Refactoring is ongoing, not a one-time event + +For code smell catalog, see [references/code-smells.md](references/code-smells.md). +For refactoring techniques, see [references/refactoring-catalog.md](references/refactoring-catalog.md). +``` + +## 補助ファイル + +スキルは `SKILL.md` 以外にも複数のファイルをディレクトリに含められる。これらの補助ファイル（テンプレート、例、スクリプト、リファレンスドキュメント）は、必要に応じて Claude がロードできる追加リソースを提供しつつ、メインのスキルファイルを焦点の絞られた状態に保つ。 + +``` +my-skill/ +├── SKILL.md # メイン命令（必須、500 行以下に保つ） +├── templates/ # Claude が埋めるテンプレート +│ └── output-format.md +├── examples/ # 期待される形式を示す出力例 +│ └── sample-output.md +├── references/ # ドメイン知識と仕様 +│ └── api-spec.md +└── scripts/ # Claude が実行できるスクリプト + └── validate.sh +``` + +補助ファイルのガイドライン: + +- `SKILL.md` は **500 行以下** に保つ。詳細なリファレンス、大きな例、仕様は別ファイルへ移す。 +- `SKILL.md` から追加ファイルを参照する際は **相対パス** を使う（例: `[API reference](references/api-spec.md)`）。 +- 補助ファイルは Level 3（必要に応じて）でロードされるため、Claude が実際に読むまではコンテキストを消費しない。 + +## スキルの管理 + +### 利用可能なスキルの確認 + +Claude に直接尋ねる: +``` +What Skills are available? +``` + +またはファイルシステムを確認する: +```bash +# 個人スキル一覧 +ls ~/.claude/skills/ + +# プロジェクトスキル一覧 +ls .claude/skills/ +``` + +### スキルのテスト + +テスト方法は 2 種類ある。 + +**Claude に自動で呼び出させる**: 説明にマッチするものを聞く: +``` +Can you help me review this code for security issues? +``` + +**スキル名で直接呼び出す**: +``` +/code-review src/auth/login.ts +``` + +### スキルの更新 + +`SKILL.md` を直接編集する。変更は次回の Claude Code 起動時に反映される。 + +```bash +# 個人スキル +code ~/.claude/skills/my-skill/SKILL.md + +# プロジェクトスキル +code .claude/skills/my-skill/SKILL.md +``` + +### Claude のスキルアクセス制限 + +Claude が呼び出せるスキルを制御する 3 つの方法。 + +**全スキルの無効化** は `/permissions` で: +``` +# deny ルールに追加: +Skill +``` + +**特定のスキルを許可または拒否**: +``` +# 特定スキルのみ許可 +Skill(commit) +Skill(review-pr *) + +# 特定スキルを拒否 +Skill(deploy *) +``` + +**個別スキルの非表示** は、フロントマターに `disable-model-invocation: true` を追加する。 + +## ベストプラクティス + +### 1. 説明を具体的にする + +- **悪い例（曖昧）**: "Helps with documents" +- **良い例（具体的）**: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction." + +### 2. スキルを 1 つの目的に絞る + +- 1 スキル = 1 機能 +- 良い例: "PDF form filling" +- 悪い例: "Document processing"（広すぎる） + +### 3. トリガーワードを含める + +ユーザーのリクエストとマッチするキーワードを説明に追加する: +```yaml +description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files. +``` + +### 4. SKILL.md を 500 行以下に保つ + +詳細なリファレンスは別ファイルへ移し、必要に応じて Claude がロードできるようにする。 + +### 5. 補助ファイルを参照する + +```markdown +## Additional resources + +- For complete API details, see [reference.md](reference.md) +- For usage examples, see [examples.md](examples.md) +``` + +### やるべきこと + +- 明確で説明的な名前を使う +- 包括的な命令を含める +- 具体的な例を入れる +- 関連スクリプトとテンプレートをパッケージ化する +- 実シナリオでテストする +- 依存関係をドキュメント化する + +### やってはいけないこと + +- 一度きりのタスク向けにスキルを作らない +- 既存機能を重複させない +- スキルを広くしすぎない +- description フィールドを省略しない +- 信頼できないソースのスキルを監査せずにインストールしない + +## トラブルシューティング + +### クイックリファレンス + +| 問題 | 解決策 | +|-------|----------| +| Claude がスキルを使わない | description をトリガー語句で具体化する | +| スキルファイルが見つからない | パス確認: `~/.claude/skills/name/SKILL.md` | +| YAML エラー | `---` マーカー、インデント、タブ無し確認 | +| スキルが衝突する | description に区別できるトリガー語句を入れる | +| スクリプトが動かない | パーミッション確認: `chmod +x scripts/*.py` | +| Claude が一部スキルを認識しない | スキルが多すぎる。`/context` で警告を確認 | + +### スキルがトリガーされない場合 + +Claude が期待通りにスキルを使わない場合: + +1. ユーザーが自然に発する語句が description のキーワードに含まれているか確認する +2. 「What skills are available?」と尋ねてスキルが表示されるか確認する +3. リクエストを description にマッチするように言い換える +4. `/skill-name` で直接呼び出してテストする + +### スキルが過剰にトリガーされる場合 + +意図しないところで Claude がスキルを使う場合: + +1. description をより具体的にする +2. 手動呼び出しのみとするため `disable-model-invocation: true` を追加する + +### Claude が一部のスキルを認識しない場合 + +スキルの description は **コンテキストウィンドウの 1 %** を上限としてロードされる（フォールバック: **8,000 文字**）。各エントリはバジェットに関係なく 250 文字に制限される。`/context` を実行して除外されたスキルに関する警告を確認する。バジェットは環境変数 `SLASH_COMMAND_TOOL_CHAR_BUDGET` で上書きできる。 + +## セキュリティ上の考慮事項 + +**信頼できるソースのスキルのみを使うこと。** スキルは命令とコードを通じて Claude に能力を与える。悪意あるスキルは、Claude に有害な方法でツールを呼び出させたりコードを実行させたりする可能性がある。 + +**主要なセキュリティ考慮事項:** + +- **徹底した監査**: スキルディレクトリ内の全ファイルをレビューする +- **外部ソースはリスクが高い**: 外部 URL から取得するスキルは侵害される恐れがある +- **ツールの悪用**: 悪意あるスキルが有害な方法でツールを呼び出すおそれがある +- **ソフトウェアインストールと同様に扱う**: 信頼できるソースのスキルのみを使う + +### スキル内のシェル置換の無効化 + +スキルは Claude が見る前に `` !`command` `` 構文でシェルコマンドの出力をプロンプトに挿入できる。セキュリティ重視の環境（共有された組織展開、ロックダウンされた CI ランナー）では、`disableSkillShellExecution` 設定で置換を完全に無効化できる（**v2.1.91** で追加）: + +```jsonc +// ~/.claude/settings.json または管理ポリシー +{ + "disableSkillShellExecution": true +} +``` + +`disableSkillShellExecution` が `true` のとき、スキル内の `` !`command` `` マーカーは実行されずリテラル文字列として残される。スキル自体を無効化することなく、スキルレベルのシェルインジェクション攻撃面を取り除ける。多層防御のため、`allowedTools` 許可リストとの組み合わせを検討するとよい。 + +## スキルと他機能の比較 + +| 機能 | 呼び出し | 適した用途 | +|---------|------------|----------| +| **スキル** | 自動または `/name` | 再利用可能な専門知識、ワークフロー | +| **スラッシュコマンド** | ユーザー起点 `/name` | 簡易ショートカット（スキルへ統合済み） | +| **サブエージェント** | 自動委譲 | 隔離されたタスク実行 | +| **メモリ（CLAUDE.md）** | 常時ロード | 永続的なプロジェクトコンテキスト | +| **MCP** | リアルタイム | 外部データやサービスへのアクセス | +| **フック** | イベント駆動 | 自動化された副作用 | + +## バンドル済みスキル + +Claude Code には、インストール不要で常時利用できる組み込みスキルが複数同梱されている。 + +| スキル | 説明 | +|-------|-------------| +| `/simplify` | 変更ファイルを再利用性、品質、効率の観点でレビューする。3 つの並列レビューエージェントを起動 | +| `/batch ` | git worktree を用いてコードベース全体に大規模な並列変更をオーケストレーション | +| `/debug [description]` | デバッグログを読んで現在のセッションをトラブルシュート | +| `/loop [interval] ` | プロンプトを定期的に繰り返し実行（例: `/loop 5m check the deploy`） | +| `/claude-api` | Claude API/SDK リファレンスをロード。`anthropic`/`@anthropic-ai/sdk` のインポート時に自動発火 | + +これらのスキルは追加インストールや設定なしでそのまま使える。カスタムスキルと同じ SKILL.md 形式に従う。 + +## スキルの共有 + +### プロジェクトスキル（チーム共有） + +1. `.claude/skills/` にスキルを作成する +2. git にコミットする +3. チームメンバーが pull すれば即時に利用可能となる + +### 個人スキル + +```bash +# 個人ディレクトリへコピー +cp -r my-skill ~/.claude/skills/ + +# スクリプトを実行可能にする +chmod +x ~/.claude/skills/my-skill/scripts/*.py +``` + +### プラグイン配布 + +より広範な配布のため、プラグインの `skills/` ディレクトリにスキルをパッケージ化する。 + +## さらに進むには: スキルコレクションとスキルマネージャー + +スキルを本格的に作り始めると、2 つのものが不可欠となる。実証済みスキルのライブラリと、それらを管理するツールである。 + +**[luongnv89/skills](https://github.com/luongnv89/skills)** — ほぼ全プロジェクトで日々使っているスキルのコレクション。ハイライトとして `logo-designer`（プロジェクトロゴをその場で生成）や `ollama-optimizer`（ハードウェアに合わせてローカル LLM の性能をチューニング）がある。すぐ使えるスキルを探しているなら良い出発点である。 + +**[luongnv89/asm](https://github.com/luongnv89/asm)** — Agent Skill Manager。スキル開発、重複検出、テストを扱う。`asm link` コマンドにより、ファイルをコピーすることなく任意のプロジェクトでスキルをテストできる。スキルが少し増えてきたら不可欠なツールである。 + +## 追加リソース + +- [公式スキルドキュメント](https://code.claude.com/docs/en/skills) +- [Agent Skills アーキテクチャブログ](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) +- [Skills リポジトリ](https://github.com/luongnv89/skills) - すぐ使えるスキルのコレクション +- [スラッシュコマンドガイド](../01-slash-commands/) - ユーザー起点のショートカット +- [サブエージェントガイド](../04-subagents/) - 委譲された AI エージェント +- [メモリガイド](../02-memory/) - 永続的なコンテキスト +- [MCP（Model Context Protocol）](../05-mcp/) - リアルタイム外部データ +- [フックガイド](../06-hooks/) - イベント駆動の自動化 + +--- +**最終更新**: 2026 年 4 月 24 日 +**Claude Code バージョン**: 2.1.119 +**情報源**: +- https://code.claude.com/docs/en/skills +- https://code.claude.com/docs/en/settings +- https://code.claude.com/docs/en/changelog +**対応モデル**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/ja/03-skills/blog-draft/SKILL.md b/ja/03-skills/blog-draft/SKILL.md new file mode 100644 index 0000000..7bd496c --- /dev/null +++ b/ja/03-skills/blog-draft/SKILL.md @@ -0,0 +1,278 @@ + + + + +--- +name: blog-draft +description: アイデアとリソースからブログ記事の下書きを作成する。ブログ記事の執筆、リサーチからのコンテンツ作成、記事の下書き作成時に使用する。リサーチ、ブレインストーミング、アウトライン作成、バージョン管理付きの反復的な下書き作成を案内する。 +--- + +## ユーザー入力 + +```text +$ARGUMENTS +``` + +進める前にユーザー入力を**必ず**考慮する。ユーザーは以下を提供すべきである。 +- **Idea/Topic**: ブログ記事の主要なコンセプトやテーマ +- **Resources**: URL、ファイル、リサーチ用の参考情報（任意だが推奨） +- **Target audience**: ブログ記事の対象読者（任意） +- **Tone/Style**: フォーマル、カジュアル、技術的、など（任意） + +**重要**: ユーザーが**既存のブログ記事**の更新を要求している場合、ステップ 0-8 をスキップして直接**ステップ 9**から開始する。まず既存の下書きファイルを読み、その後で反復プロセスを進める。 + +## 実行フロー + +以下のステップを順次実行する。**ステップをスキップしたり、指示された箇所でユーザー承認なしに進めたりしてはならない。** + +### Step 0: プロジェクトフォルダの作成 + +1. 次の形式でフォルダ名を生成する: `YYYY-MM-DD-short-topic-name` + - 今日の日付を使用 + - トピックから短く URL フレンドリーなスラッグを作成（小文字、ハイフン、最大 5 単語） + +2. フォルダ構造を作成: + ``` + blog-posts/ + └── YYYY-MM-DD-short-topic-name/ + └── resources/ + ``` + +3. 進める前にフォルダ作成をユーザーに確認する。 + +### Step 1: リサーチとリソース収集 + +1. ブログ記事ディレクトリ内に `resources/` サブフォルダを作成 + +2. 提供された各リソースに対して: + - **URLs**: 取得して主要情報を `resources/` にマークダウンファイルとして保存 + - **Files**: 読み込んで `resources/` に要約 + - **Topics**: ウェブ検索を使用して最新情報を収集 + +3. 各リソースについて、`resources/` に要約ファイルを作成: + - `resources/source-1-[short-name].md` + - `resources/source-2-[short-name].md` + - など + +4. 各要約には以下を含める: + ```markdown + # Source: [Title/URL] + + ## Key Points + - Point 1 + - Point 2 + + ## Relevant Quotes/Data + - Quote or statistic 1 + - Quote or statistic 2 + + ## How This Relates to Topic + 関連性の簡潔な説明 + ``` + +5. リサーチの要約をユーザーに提示する。 + +### Step 2: ブレインストーミングと明確化 + +1. アイデアとリサーチしたリソースに基づき、以下を提示: + - リサーチから特定された**主要テーマ** + - ブログ記事の**取りうる切り口** + - カバーすべき**重要ポイント** + - 明確化が必要な情報の**ギャップ** + +2. 明確化のための質問: + - 読者に持って帰ってほしい主要なテイクアウェイは何か？ + - リサーチの中で特に強調したい点はあるか？ + - 目標の長さは？（short: 500-800 words、medium: 1000-1500、long: 2000+） + - 除外したい点はあるか？ + +3. **進める前にユーザー応答を待つ。** + +### Step 3: アウトライン提案 + +1. 以下を含む構造化されたアウトラインを作成: + + ```markdown + # Blog Post Outline: [Title] + + ## Meta Information + - **Target Audience**: [who] + - **Tone**: [style] + - **Target Length**: [word count] + - **Main Takeaway**: [key message] + + ## Proposed Structure + + ### Hook/Introduction + - Opening hook idea + - Context setting + - Thesis statement + + ### Section 1: [Title] + - Key point A + - Key point B + - Supporting evidence from [source] + + ### Section 2: [Title] + - Key point A + - Key point B + + [全セクションについて続ける...] + + ### Conclusion + - Summary of key points + - Call to action or final thought + + ## Sources to Cite + - Source 1 + - Source 2 + ``` + +2. アウトラインをユーザーに提示し、**承認または修正を求める**。 + +### Step 4: 承認されたアウトラインの保存 + +1. ユーザーがアウトラインを承認したら、ブログ記事フォルダ内の `OUTLINE.md` に保存する。 + +2. アウトラインが保存されたことを確認する。 + +### Step 5: アウトラインのコミット（git リポジトリの場合） + +1. カレントディレクトリが git リポジトリかどうか確認する。 + +2. はいの場合: + - 新しいファイル（ブログ記事フォルダ、resources、OUTLINE.md）をステージング + - 次のメッセージでコミットを作成: `docs: Add outline for blog post - [topic-name]` + - リモートへプッシュ + +3. git リポジトリでない場合は、このステップをスキップしユーザーに伝える。 + +### Step 6: 下書き作成 + +1. 承認されたアウトラインに基づき、ブログ記事の下書き全文を作成する。 + +2. OUTLINE.md の構造に厳密に従う。 + +3. 含めるもの: + - フック付きの魅力的な導入 + - 明確なセクション見出し + - リサーチからの裏付けとなる証拠と例 + - セクション間の滑らかな遷移 + - テイクアウェイのある力強い結論 + - **Citations**: すべての比較、統計、データポイント、事実主張は元のソースを必ず引用すること + +4. 下書きをブログ記事フォルダ内に `draft-v0.1.md` として保存する。 + +5. フォーマット: + ```markdown + # [Blog Post Title] + + *[Optional: subtitle or tagline]* + + [インライン引用付きの本文...] + + --- + + ## References + - [1] Source 1 Title - URL or Citation + - [2] Source 2 Title - URL or Citation + - [3] Source 3 Title - URL or Citation + ``` + +6. **引用要件**: + - すべてのデータポイント、統計、比較にはインライン引用を必ず付ける + - [1]、[2] などの番号引用、または [Source Name] のような名前付き引用を使用 + - 引用を末尾の References セクションへリンクする + - 例: "Studies show that 65% of developers prefer TypeScript [1]" + - 例: "React outperforms Vue in rendering speed by 20% [React Benchmarks 2024]" + +### Step 7: 下書きのコミット（git リポジトリの場合） + +1. git リポジトリかどうか確認する。 + +2. はいの場合: + - 下書きファイルをステージング + - 次のメッセージでコミットを作成: `docs: Add draft v0.1 for blog post - [topic-name]` + - リモートへプッシュ + +3. git リポジトリでない場合は、スキップしてユーザーに伝える。 + +### Step 8: レビュー用に下書きを提示 + +1. 下書きの内容をユーザーに提示する。 + +2. フィードバックを求める: + - 全体の印象は？ + - 拡張または削減が必要なセクションは？ + - トーン調整は必要か？ + - 不足している情報は？ + - 具体的な編集や書き直しは？ + +3. **ユーザー応答を待つ。** + +### Step 9: 反復または最終化 + +**ユーザーが変更を要求した場合:** +1. すべての要望を記録する +2. 以下の調整を加えてステップ 6 へ戻る: + - バージョン番号を増加（v0.2、v0.3 など） + - すべてのフィードバックを反映 + - `draft-v[X.Y].md` として保存 + - ステップ 7-8 を繰り返す + +**ユーザーが承認した場合:** +1. 最終下書きのバージョンを確認 +2. ユーザーが要求すれば任意で `final.md` にリネーム +3. ブログ記事作成プロセスを要約: + - 作成したバージョンの総数 + - バージョン間の主要な変更 + - 最終ワード数 + - 作成したファイル + +## バージョン追跡 + +すべての下書きは段階的なバージョン番号付きで保持する: +- `draft-v0.1.md` - 初回下書き +- `draft-v0.2.md` - 1 回目のフィードバック反映後 +- `draft-v0.3.md` - 2 回目のフィードバック反映後 +- など + +これによりブログ記事の進化を追跡し、必要に応じて差し戻すことができる。 + +## 出力ファイル構造 + +``` +blog-posts/ +└── YYYY-MM-DD-topic-name/ + ├── resources/ + │ ├── source-1-name.md + │ ├── source-2-name.md + │ └── ... + ├── OUTLINE.md + ├── draft-v0.1.md + ├── draft-v0.2.md (反復した場合) + └── draft-v0.3.md (さらに反復した場合) +``` + +## 品質のためのヒント + +- **Hook**: 質問、意外な事実、共感できるシナリオで始める +- **Flow**: 各段落は次の段落と接続させる +- **Evidence**: リサーチデータで主張を裏付ける +- **Citations**: 以下については必ずソースを引用する: + - すべての統計とデータポイント（例: "According to [Source], 75% of..."） + - 製品、サービス、アプローチ間の比較（例: "X performs 2x faster than Y [Source]"） + - 市場トレンド、リサーチ結果、ベンチマークについての事実主張 + - 形式: [Source Name] または [Author, Year] のインライン引用を使用 +- **Voice**: 全体を通じて一貫したトーンを保つ +- **Length**: 目標ワード数を尊重 +- **Readability**: 短い段落、適切な箇所での箇条書きを使用 +- **CTA**: 明確な CTA または考えさせる問いで終える + +## 注意事項 + +- 指定されたチェックポイントでは必ずユーザー承認を待つ +- 履歴のためすべての下書きバージョンを保持する +- URL が提供された場合は最新情報のためウェブ検索を使用する +- リソースが不十分な場合はユーザーに追加を求めるか、追加リサーチを提案する +- 対象読者（技術系、一般、ビジネスなど）に応じてトーンを適応させる diff --git a/ja/03-skills/blog-draft/templates/draft-template.md b/ja/03-skills/blog-draft/templates/draft-template.md new file mode 100644 index 0000000..660bee0 --- /dev/null +++ b/ja/03-skills/blog-draft/templates/draft-template.md @@ -0,0 +1,71 @@ + + + + +# [Blog Post Title] + +*[サブタイトルまたはタグライン - 任意]* + +**[Author Name]** | [Date] + +--- + +[オープニング・フック - すぐに注目を集める] + +[文脈と背景 - なぜ重要か] + +[テーゼ・ステートメント - この記事で扱う内容] + +--- + +## [Section 1 Title] + +[明確で魅力的な散文によるセクション内容] + +[論点を支える証拠、例、データを含める] + +> "研究からの関連する引用" - Source + +[次のセクションへの遷移] + +--- + +## [Section 2 Title] + +[本文を継続] + +**重要なポイント:** [重要事項を太字またはコールアウトボックスで強調] + +[追加の補足コンテンツ] + +--- + +## [Section 3 Title] + +[必要に応じて追加セクション] + +### サブセクション（必要な場合） + +[サブセクション内容] + +--- + +## 結論 + +[扱った主要なポイントを要約] + +[主要なテイクアウェイを補強] + +[CTA または考えさせる最後の一文] + +--- + +## References + +1. [Source Title](#) +2. [Source Title](#) +3. [Source Title](#) + +--- + +*[任意: 著者プロフィールまたは関連記事の提案]* diff --git a/ja/03-skills/blog-draft/templates/outline-template.md b/ja/03-skills/blog-draft/templates/outline-template.md new file mode 100644 index 0000000..234c4b7 --- /dev/null +++ b/ja/03-skills/blog-draft/templates/outline-template.md @@ -0,0 +1,101 @@ + + + + +# Blog Post Outline: [Title] + +## メタ情報 + +| Attribute | Value | +|-----------|-------| +| **Target Audience** | [誰に向けてか？] | +| **Tone** | [Formal/Casual/Technical/Conversational] | +| **Target Length** | [単語数の範囲] | +| **Main Takeaway** | [一文で：読者に何を覚えてほしいか？] | +| **Keywords** | [関連する場合の SEO キーワード] | + +--- + +## 提案する構成 + +### 1. 導入 / フック + +**オープニング・フックの選択肢:** +- [ ] 読者に共鳴する問い +- [ ] 意外な統計や事実 +- [ ] 短いストーリーやシナリオ +- [ ] 大胆な主張 + +**文脈の設定:** +- 必要な背景情報 +- なぜ今このトピックが重要か + +**テーゼ・ステートメント:** +- 記事で扱う内容を明確に提示 + +--- + +### 2. [Section Title] + +**重要ポイント:** +- Point A: [説明] +- Point B: [説明] + +**裏付けとなる証拠:** +- [source] より: [関連データ/引用] + +**次セクションへの遷移:** +- [次の内容との関連] + +--- + +### 3. [Section Title] + +**重要ポイント:** +- Point A: [説明] +- Point B: [説明] + +**裏付けとなる証拠:** +- [source] より: [関連データ/引用] + +**次セクションへの遷移:** +- [次の内容との関連] + +--- + +### 4. [Section Title]（必要に応じてセクションを追加） + +**重要ポイント:** +- Point A: [説明] +- Point B: [説明] + +**裏付けとなる証拠:** +- [source] より: [関連データ/引用] + +--- + +### 5. 結論 + +**重要ポイントの要約:** +- ポイント 1 のおさらい +- ポイント 2 のおさらい +- ポイント 3 のおさらい + +**最後のひと言 / CTA:** +- [読者に次に何をしてほしいか、何を考えてほしいか？] + +--- + +## 引用するソース + +1. [Source Name](#) - 利用目的: [どの情報に使うか] +2. [Source Name](#) - 利用目的: [どの情報に使うか] +3. [Source Name](#) - 利用目的: [どの情報に使うか] + +--- + +## 下書き用メモ + +- [固有の要件や制約] +- [強調したい点] +- [避けるべき点] diff --git a/ja/03-skills/brand-voice/SKILL.md b/ja/03-skills/brand-voice/SKILL.md new file mode 100644 index 0000000..2768790 --- /dev/null +++ b/ja/03-skills/brand-voice/SKILL.md @@ -0,0 +1,76 @@ + + + + +--- +name: brand-voice-consistency +description: すべてのコミュニケーションがブランドボイスとトーンのガイドラインに沿うことを保証する。マーケティングコピー、顧客向け連絡、公開コンテンツの作成時、またはブランドボイス、トーン、文体について言及がある場合に使用する。 +--- + +# ブランドボイス・スキル + +## 概要 +このスキルは、すべてのコミュニケーションにおいて一貫したブランドボイス、トーン、メッセージングを維持する。 + +## ブランドアイデンティティ + +### ミッション +チームが AI で開発ワークフローを自動化することを支援する + +### バリュー +- **シンプリシティ**: 複雑なものをシンプルにする +- **信頼性**: 揺るぎない実行 +- **エンパワーメント**: 人間の創造性を引き出す + +### トーン・オブ・ボイス +- **フレンドリーかつプロフェッショナル** - カジュアルにならず、親しみやすい +- **明快で簡潔** - 専門用語を避け、技術的な概念をわかりやすく説明する +- **自信を持って** - 自分たちが何をしているかを理解している +- **共感的** - ユーザーのニーズと痛みを理解する + +## 執筆ガイドライン + +### やるべきこと ✅ +- 読者を指す際には「you」を使用 +- 能動態を使用: 「Claude generates reports」とし、「Reports are generated by Claude」としない +- 価値提案から始める +- 具体例を用いる +- 1 文を 20 語未満に保つ +- 明確化のためリストを使用 +- CTA（行動喚起）を含める + +### 避けるべきこと ❌ +- 企業ジャーゴンを使わない +- 見下したり過度に単純化したりしない +- 「we believe」や「we think」を使わない +- 強調以外で全大文字を使わない +- 文章の壁を作らない +- 技術的な前提知識を仮定しない + +## ボキャブラリー + +### ✅ 推奨用語 +- Claude（「the Claude AI」ではなく） +- Code generation（「auto-coding」ではなく） +- Agent（「bot」ではなく） +- Streamline（「revolutionize」ではなく） +- Integrate（「synergize」ではなく） + +### ❌ 避ける用語 +- 「Cutting-edge」（使い古されている） +- 「Game-changer」（曖昧） +- 「Leverage」（企業用語的） +- 「Utilize」（「use」を使う） +- 「Paradigm shift」（不明瞭） + +## 例 + +### ✅ 良い例 +"Claude automates your code review process. Instead of manually checking each PR, Claude reviews security, performance, and quality—saving your team hours every week." + +なぜ機能するか: 明確な価値、具体的なメリット、行動志向 + +### ❌ 悪い例 +"Claude leverages cutting-edge AI to provide comprehensive software development solutions." + +なぜ機能しないか: 曖昧、企業ジャーゴン、具体的な価値がない diff --git a/ja/03-skills/brand-voice/tone-examples.md b/ja/03-skills/brand-voice/tone-examples.md new file mode 100644 index 0000000..371b092 --- /dev/null +++ b/ja/03-skills/brand-voice/tone-examples.md @@ -0,0 +1,17 @@ + + + + +# ブランドボイスのトーン例 + +## 期待を高めるアナウンス +"コードレビューを週 8 時間削減。Claude が PR を自動でレビューする。" + +## 共感を示すサポート +"デプロイがストレスになることは理解している。Claude がテストを担当するため、心配は不要だ。" + +## 自信を示すプロダクト機能 +"Claude は単にコードを提案するだけではない。アーキテクチャを理解し、一貫性を保つ。" + +## 教育的なブログ記事 +"エージェントがコードレビューのワークフローをどのように改善するかを見ていこう。学んだことは次のとおりである……" diff --git a/ja/03-skills/claude-md/SKILL.md b/ja/03-skills/claude-md/SKILL.md new file mode 100644 index 0000000..d1fd184 --- /dev/null +++ b/ja/03-skills/claude-md/SKILL.md @@ -0,0 +1,215 @@ + + + +--- +name: claude-md +description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding +--- + +## ユーザー入力 + +```text +$ARGUMENTS +``` + +ユーザー入力が空でない場合、進める前に **必ず** 内容を考慮すること。ユーザーは以下を指定する場合がある: +- `create` - 新しい CLAUDE.md をゼロから作成 +- `update` - 既存 CLAUDE.md を改善 +- `audit` - 現在の CLAUDE.md の品質を分析しレポート +- 作成・更新する具体的なパス（例: ディレクトリ固有命令向けの `src/api/CLAUDE.md`） + +## 基本原則 + +**LLM はステートレス**: CLAUDE.md は、すべての会話に自動的に含まれる唯一のファイルである。コードベースに対する AI エージェントの主要なオンボーディングドキュメントとして機能する。 + +### ゴールデンルール + +1. **少ないほど良い**: フロンティア LLM は約 150〜200 個の命令に従える。Claude Code のシステムプロンプトはすでに約 50 個を使用している。CLAUDE.md は焦点を絞り簡潔に保つこと。 + +2. **普遍的な適用性**: あらゆるセッションに関係する情報のみを含める。タスク固有の命令は別ファイルに置く。 + +3. **Claude をリンターとして使わない**: スタイルガイドラインはコンテキストを膨張させ命令の遵守を低下させる。代わりに決定論的なツール（prettier, eslint など）を使う。 + +4. **絶対に自動生成しない**: CLAUDE.md は AI ハーネスにおける最も影響力の高いポイントである。慎重に手作業で作り上げること。 + +## 実行フロー + +### 1. プロジェクト分析 + +まず現在のプロジェクト状態を分析する: + +1. 既存の CLAUDE.md ファイルを確認: + - ルートレベル: `./CLAUDE.md` または `.claude/CLAUDE.md` + - ディレクトリ固有: `**/CLAUDE.md` + - グローバルユーザー設定: `~/.claude/CLAUDE.md` + +2. プロジェクト構造を特定: + - 技術スタック（言語、フレームワーク） + - プロジェクト種別（モノレポ、単一アプリ、ライブラリ） + - 開発ツール（パッケージマネージャー、ビルドシステム、テストランナー） + +3. 既存ドキュメントをレビュー: + - README.md + - CONTRIBUTING.md + - package.json, pyproject.toml, Cargo.toml など + +### 2. コンテンツ戦略（WHAT, WHY, HOW） + +CLAUDE.md を 3 つの観点で構成する: + +#### WHAT - 技術と構造 +- 技術スタックの概要 +- プロジェクトの編成（モノレポでは特に重要） +- 主要ディレクトリとその目的 + +#### WHY - 目的と背景 +- プロジェクトが何をするか +- なぜ特定の設計判断が下されたのか +- 各主要コンポーネントが何を担当するか + +#### HOW - ワークフローと規約 +- 開発ワークフロー（bun と node、pip と uv など） +- テスト手順とコマンド +- 検証およびビルド手段 +- 重要な「ハマりどころ」や明示されない要件 + +### 3. プログレッシブディスクロージャ戦略 + +大規模プロジェクトでは `agent_docs/` フォルダの作成を推奨する: + +``` +agent_docs/ + |- building_the_project.md + |- running_tests.md + |- code_conventions.md + |- architecture_decisions.md +``` + +CLAUDE.md からは以下のような命令でこれらのファイルを参照する: +```markdown +For detailed build instructions, refer to `agent_docs/building_the_project.md` +``` + +**重要**: 古くなるコンテキストを避けるため、コードスニペットではなく `file:line` 参照を用いる。 + +### 4. 品質制約 + +CLAUDE.md を作成・更新する際: + +1. **目標の長さ**: 300 行以下（理想は 100 行以下） +2. **スタイルルールなし**: lint やフォーマットの命令は除く +3. **タスク固有命令なし**: 別ファイルへ移す +4. **コードスニペットなし**: ファイル参照を用いる +5. **冗長情報なし**: package.json や README にあるものを繰り返さない + +### 5. 必須セクション + +良く構成された CLAUDE.md には以下を含めるべきである: + +```markdown +# Project Name + +Brief one-line description. + +## Tech Stack +- Primary language and version +- Key frameworks/libraries +- Database/storage (if any) + +## Project Structure +[Only for monorepos or complex structures] +- `apps/` - Application entry points +- `packages/` - Shared libraries + +## Development Commands +- Install: `command` +- Test: `command` +- Build: `command` + +## Critical Conventions +[Only non-obvious, high-impact conventions] +- Convention 1 with brief explanation +- Convention 2 with brief explanation + +## Known Issues / Gotchas +[Things that consistently trip up developers] +- Issue 1 +- Issue 2 +``` + +### 6. 避けるべきアンチパターン + +**含めてはいけないもの:** +- コードスタイルガイドライン（リンターを使う） +- Claude の使い方に関するドキュメント +- 自明なパターンへの長い説明 +- コピー＆ペーストされたコード例 +- 一般的なベストプラクティス（"write clean code"） +- 特定タスク向けの命令 +- 自動生成された内容 +- 大量の TODO リスト + +### 7. 検証チェックリスト + +最終化前に確認: + +- [ ] 300 行以下（できれば 100 行以下） +- [ ] すべての行があらゆるセッションに適用される +- [ ] スタイルやフォーマットのルールがない +- [ ] コードスニペットがない（ファイル参照を使う） +- [ ] コマンドが動作することを検証済み +- [ ] 複雑なプロジェクトでプログレッシブディスクロージャを利用 +- [ ] 重要なハマりどころがドキュメント化されている +- [ ] README.md と内容が重複していない + +## 出力形式 + +### `create` または既定の場合: + +1. プロジェクトを分析する +2. 上記の構造に従って CLAUDE.md の草案を作る +3. 草案をレビュー用に提示する +4. 承認後、適切な場所へ書き込む + +### `update` の場合: + +1. 既存 CLAUDE.md を読む +2. ベストプラクティスに照らして監査する +3. 以下を特定する: + - 削除する内容（スタイルルール、コードスニペット、タスク固有） + - 凝縮する内容 + - 不足している必須情報 +4. 変更内容をレビュー用に提示する +5. 承認後、変更を適用する + +### `audit` の場合: + +1. 既存 CLAUDE.md を読む +2. 以下を含むレポートを生成する: + - 現在の行数と目標値 + - 普遍的に適用可能なコンテンツの割合 + - 検出されたアンチパターンの一覧 + - 改善のための推奨 +3. ファイルを変更しない、レポートのみを行う + +## AGENTS.md の取り扱い + +ユーザーが AGENTS.md の作成・更新を求めた場合: + +AGENTS.md は専門エージェントの振る舞いを定義するために用いられる。プロジェクトコンテキスト用の CLAUDE.md と異なり、AGENTS.md では以下を定義する: +- カスタムエージェントの役割と能力 +- エージェント固有の命令と制約 +- マルチエージェントシナリオのワークフロー定義 + +同様の原則を適用する: +- 焦点を絞り簡潔に保つ +- プログレッシブディスクロージャを用いる +- 内容を埋め込むのではなく外部ドキュメントを参照する + +## 注意事項 + +- コマンドを含める前に必ず動作確認する +- 迷ったら省略する。少ないほど良い +- システムリマインダーは Claude に対して CLAUDE.md は「関係があるかどうかわからない」と告げている。ノイズが多いほど無視されやすい +- モノレポは明確な WHAT/WHY/HOW 構造の恩恵が最も大きい +- ディレクトリ固有の CLAUDE.md ファイルはさらに焦点を絞るべきである diff --git a/ja/03-skills/code-review/SKILL.md b/ja/03-skills/code-review/SKILL.md new file mode 100644 index 0000000..02e2ece --- /dev/null +++ b/ja/03-skills/code-review/SKILL.md @@ -0,0 +1,74 @@ + + + + +--- +name: code-review-specialist +description: セキュリティ、パフォーマンス、品質分析を含む包括的なコードレビュー。コードレビュー、コード品質分析、プルリクエスト評価の依頼があった場合、またはコードレビュー、セキュリティ分析、パフォーマンス最適化について言及がある場合に使用する。 +--- + +# コードレビュー・スキル + +このスキルは、以下に焦点を当てた包括的なコードレビュー機能を提供する。 + +1. **セキュリティ分析** + - 認証・認可の問題 + - データ漏洩リスク + - インジェクション脆弱性 + - 暗号の弱点 + - 機密データのロギング + +2. **パフォーマンス・レビュー** + - アルゴリズム効率（Big O 分析） + - メモリ最適化 + - データベースクエリ最適化 + - キャッシュ機会 + - 並行性の問題 + +3. **コード品質** + - SOLID 原則 + - デザインパターン + - 命名規則 + - ドキュメント + - テストカバレッジ + +4. **保守性** + - コードの可読性 + - 関数サイズ（50 行未満が望ましい） + - 循環的複雑度 + - 依存関係管理 + - 型安全性 + +## レビュー・テンプレート + +レビューしたコードごとに、以下を提供する。 + +### サマリー +- 全体品質評価（1-5） +- 主要な指摘件数 +- 推奨される優先領域 + +### クリティカルな問題（あれば） +- **Issue**: 明確な説明 +- **Location**: ファイルと行番号 +- **Impact**: なぜ重要か +- **Severity**: Critical/High/Medium +- **Fix**: コード例 + +### カテゴリ別の指摘事項 + +#### セキュリティ（問題が見つかった場合） +セキュリティ脆弱性を例示しながら列挙 + +#### パフォーマンス（問題が見つかった場合） +複雑度分析を含めパフォーマンス問題を列挙 + +#### 品質（問題が見つかった場合） +リファクタリング提案を含めコード品質の問題を列挙 + +#### 保守性（問題が見つかった場合） +改善案を含め保守性の問題を列挙 + +## バージョン履歴 + +- v1.0.0 (2024-12-10): セキュリティ、パフォーマンス、品質、保守性分析を含む初回リリース diff --git a/ja/03-skills/code-review/templates/finding-template.md b/ja/03-skills/code-review/templates/finding-template.md new file mode 100644 index 0000000..1fc89b4 --- /dev/null +++ b/ja/03-skills/code-review/templates/finding-template.md @@ -0,0 +1,116 @@ + + + + +# コードレビュー指摘事項テンプレート + +コードレビュー中に見つけた各問題を文書化する際にこのテンプレートを使用する。 + +--- + +## Issue: [TITLE] + +### 重要度 +- [ ] Critical（デプロイをブロック） +- [ ] High（マージ前に修正すべき） +- [ ] Medium（早期に修正すべき） +- [ ] Low（あれば望ましい） + +### カテゴリ +- [ ] Security +- [ ] Performance +- [ ] Code Quality +- [ ] Maintainability +- [ ] Testing +- [ ] Design Pattern +- [ ] Documentation + +### 場所 +**File:** `src/components/UserCard.tsx` + +**Lines:** 45-52 + +**Function/Method:** `renderUserDetails()` + +### 問題の説明 + +**What:** 問題の内容を記述する。 + +**Why it matters:** 影響と修正が必要な理由を説明する。 + +**Current behavior:** 問題のあるコードや挙動を示す。 + +**Expected behavior:** 代わりに期待される挙動を記述する。 + +### コード例 + +#### 現状（問題あり） + +```typescript +// N+1 クエリ問題を示す +const users = fetchUsers(); +users.forEach(user => { + const posts = fetchUserPosts(user.id); // ユーザーごとにクエリ！ + renderUserPosts(posts); +}); +``` + +#### 修正案 + +```typescript +// JOIN クエリで最適化 +const usersWithPosts = fetchUsersWithPosts(); +usersWithPosts.forEach(({ user, posts }) => { + renderUserPosts(posts); +}); +``` + +### 影響分析 + +| Aspect | Impact | Severity | +|--------|--------|----------| +| Performance | 20 ユーザーで 100 件以上のクエリ | High | +| User Experience | ページ読み込みが遅い | High | +| Scalability | 規模拡大で破綻 | Critical | +| Maintainability | デバッグが困難 | Medium | + +### 関連する問題 + +- `AdminUserList.tsx` 120 行目に類似の問題 +- 関連 PR: #456 +- 関連 issue: #789 + +### 追加リソース + +- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) +- [Database Join Documentation](https://docs.example.com/joins) + +### レビュアーのメモ + +- このコードベースでよく見られるパターンである +- コードスタイルガイドへの追加を検討する +- ヘルパー関数を作成する価値があるかもしれない + +### 著者の応答（フィードバック用） + +*コード作成者が記入する:* + +- [ ] 修正実装コミット: `abc123` +- [ ] 修正状況: Complete / In Progress / Needs Discussion +- [ ] 質問や懸念: （記述） + +--- + +## 指摘統計（レビュアー用） + +複数の指摘をレビューする際は、以下を追跡する。 + +- **Total Issues Found:** X +- **Critical:** X +- **High:** X +- **Medium:** X +- **Low:** X + +**Recommendation:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion + +**Overall Code Quality:** 1-5 stars diff --git a/ja/03-skills/code-review/templates/review-checklist.md b/ja/03-skills/code-review/templates/review-checklist.md new file mode 100644 index 0000000..ab27278 --- /dev/null +++ b/ja/03-skills/code-review/templates/review-checklist.md @@ -0,0 +1,51 @@ + + + + +# コードレビュー・チェックリスト + +## セキュリティ・チェックリスト +- [ ] ハードコードされた認証情報や秘密情報がない +- [ ] すべてのユーザー入力に対する入力検証 +- [ ] SQL インジェクション対策（パラメータ化クエリ） +- [ ] 状態を変更する操作への CSRF 対策 +- [ ] 適切なエスケープによる XSS 対策 +- [ ] 保護されたエンドポイントでの認証チェック +- [ ] リソースに対する認可チェック +- [ ] 安全なパスワードハッシュ化（bcrypt、argon2） +- [ ] ログに機密データを含めない +- [ ] HTTPS の強制 + +## パフォーマンス・チェックリスト +- [ ] N+1 クエリがない +- [ ] インデックスの適切な利用 +- [ ] 効果的な箇所でのキャッシュ実装 +- [ ] メインスレッドでのブロッキング操作がない +- [ ] async/await の正しい使用 +- [ ] 大規模データセットのページネーション +- [ ] データベースコネクションプーリング +- [ ] 正規表現の最適化 +- [ ] 不要なオブジェクト生成がない +- [ ] メモリリーク対策 + +## 品質チェックリスト +- [ ] 関数が 50 行未満 +- [ ] 明確な変数命名 +- [ ] 重複コードがない +- [ ] 適切なエラーハンドリング +- [ ] コメントは「何を」ではなく「なぜ」を説明 +- [ ] 本番環境に console.log がない +- [ ] 型チェック（TypeScript/JSDoc） +- [ ] SOLID 原則の遵守 +- [ ] デザインパターンの正しい適用 +- [ ] 自己説明的なコード + +## テスト・チェックリスト +- [ ] ユニットテストの記述 +- [ ] エッジケースの網羅 +- [ ] エラーシナリオのテスト +- [ ] 統合テストの存在 +- [ ] カバレッジが 80% 以上 +- [ ] flaky テストがない +- [ ] 外部依存のモック化 +- [ ] 明確なテスト名 diff --git a/ja/03-skills/doc-generator/SKILL.md b/ja/03-skills/doc-generator/SKILL.md new file mode 100644 index 0000000..0538253 --- /dev/null +++ b/ja/03-skills/doc-generator/SKILL.md @@ -0,0 +1,80 @@ + + + + +--- +name: api-documentation-generator +description: ソースコードから包括的かつ正確な API ドキュメントを生成する。API ドキュメントの作成・更新、OpenAPI 仕様の生成時、または API ドキュメント、エンドポイント、ドキュメントについて言及がある場合に使用する。 +--- + +# API ドキュメント生成スキル + +## 生成するもの + +- OpenAPI/Swagger 仕様 +- API エンドポイントのドキュメント +- SDK 利用例 +- 統合ガイド +- エラーコード・リファレンス +- 認証ガイド + +## ドキュメント構造 + +### 各エンドポイントごと + +```markdown +## GET /api/v1/users/:id + +### Description +このエンドポイントの動作を簡潔に説明 + +### Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| id | string | Yes | User ID | + +### Response + +**200 Success** +```json +{ + "id": "usr_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +**404 Not Found** +```json +{ + "error": "USER_NOT_FOUND", + "message": "User does not exist" +} +``` + +### Examples + +**cURL** +```bash +curl -X GET "https://api.example.com/api/v1/users/usr_123" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +**JavaScript** +```javascript +const user = await fetch('/api/v1/users/usr_123', { + headers: { 'Authorization': 'Bearer token' } +}).then(r => r.json()); +``` + +**Python** +```python +response = requests.get( + 'https://api.example.com/api/v1/users/usr_123', + headers={'Authorization': 'Bearer token'} +) +user = response.json() +``` +``` diff --git a/ja/03-skills/refactor/SKILL.md b/ja/03-skills/refactor/SKILL.md new file mode 100644 index 0000000..189b213 --- /dev/null +++ b/ja/03-skills/refactor/SKILL.md @@ -0,0 +1,429 @@ + + + +--- +name: code-refactor +description: Martin Fowler の方法論に基づく体系的なコードリファクタリング。ユーザーがコードのリファクタリング、コード構造の改善、技術的負債の削減、レガシーコードのクリーンアップ、コードスメルの解消、コード保守性の向上を求めた際に使用する。本スキルは、リサーチ・計画・安全な段階的実装からなる段階的アプローチを案内する。 +--- + +# コードリファクタリングスキル + +Martin Fowler 著『Refactoring: Improving the Design of Existing Code』(第 2 版) に基づくコードリファクタリングへの体系的アプローチ。本スキルは、テストに支えられた安全で段階的な変更を重視する。 + +> "Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure." — Martin Fowler + +## 中核となる原則 + +1. **振る舞いの保全**: 外部から見える振る舞いは変えてはならない +2. **小さなステップ**: テスト可能な微小な変更を積み重ねる +3. **テスト駆動**: テストはセーフティネットである +4. **継続的**: リファクタリングは一度きりの作業ではなく継続的に行う +5. **協調的**: 各フェーズでユーザーの承認が必要 + +## ワークフロー概要 + +``` +Phase 1: Research & Analysis + ↓ +Phase 2: Test Coverage Assessment + ↓ +Phase 3: Code Smell Identification + ↓ +Phase 4: Refactoring Plan Creation + ↓ +Phase 5: Incremental Implementation + ↓ +Phase 6: Review & Iteration +``` + +--- + +## フェーズ 1: リサーチと分析 + +### 目的 +- コードベースの構造と目的を把握する +- リファクタリングの範囲を特定する +- ビジネス要件に関するコンテキストを収集する + +### ユーザーへの確認事項 +開始前に次の点を明確化する。 + +1. **範囲**: どのファイル/モジュール/関数をリファクタリングするのか? +2. **目標**: 何を解決したいのか?(可読性、性能、保守性) +3. **制約**: 変更してはいけない領域はあるか? +4. **時間的圧力**: 他作業のブロッカーになっているか? +5. **テスト状況**: テストは存在するか?パスしているか? + +### アクション +- [ ] 対象コードを読み、理解する +- [ ] 依存関係と統合箇所を洗い出す +- [ ] 現行アーキテクチャを文書化する +- [ ] 既存の技術的負債マーカー(TODO、FIXME)を控える + +### 出力 +ユーザーへの提示内容: +- コード構造のサマリー +- 検出された問題箇所 +- 初期推奨事項 +- **着手の承認を依頼する** + +--- + +## フェーズ 2: テストカバレッジの評価 + +### なぜテストが重要か +> "Refactoring without tests is like driving without a seatbelt." — Martin Fowler + +テストは安全なリファクタリングを可能にする**鍵となる要素**である。テストがなければ、バグを混入させるリスクがある。 + +### 評価ステップ + +1. **既存テストの確認** + ```bash + # テストファイルを探す + find . -name "*test*" -o -name "*spec*" | head -20 + ``` + +2. **既存テストの実行** + ```bash + # JavaScript/TypeScript + npm test + + # Python + pytest -v + + # Java + mvn test + ``` + +3. **カバレッジの確認(可能な場合)** + ```bash + # JavaScript + npm run test:coverage + + # Python + pytest --cov=. + ``` + +### 判断ポイント: ユーザーへの確認 + +**テストが存在し、かつパスしている場合:** +- フェーズ 3 へ進む + +**テストが不足、または不完全な場合:** +次の選択肢を提示する。 +1. 先にテストを書く(推奨) +2. リファクタリング中に段階的にテストを追加する +3. テストなしで進める(リスクあり、ユーザーの明示的同意が必要) + +**テストが失敗している場合:** +- STOP。リファクタリング前に失敗テストを修正する +- ユーザーに確認: 先にテストを直すべきか? + +### テスト作成のガイドライン(必要時) + +リファクタリング対象の各関数について、以下をテストでカバーする。 +- ハッピーパス(通常動作) +- エッジケース(空入力、null、境界値) +- エラーシナリオ(無効入力、例外) + +「red-green-refactor」サイクルを用いる。 +1. 失敗するテストを書く(red) +2. パスさせる(green) +3. リファクタリングする + +--- + +## フェーズ 3: コードスメルの特定 + +### コードスメルとは? +コードに潜むより深い問題の症状である。バグそのものではないが、コード改善の余地を示す指標となる。 + +### よくチェックすべきコードスメル + +完全なカタログは [references/code-smells.md](references/code-smells.md) を参照。 + +#### クイックリファレンス + +| スメル | 兆候 | 影響 | +|-------|-------|--------| +| **Long Method（長すぎる関数）** | メソッドが 30〜50 行を超える | 理解、テスト、保守が困難 | +| **Duplicated Code（重複したコード）** | 同じロジックが複数箇所に存在 | バグ修正を複数箇所で行う必要がある | +| **Large Class（巨大なクラス）** | 責務が多すぎるクラス | 単一責任原則に違反 | +| **Feature Envy（機能の横恋慕）** | 他クラスのデータを多く使用するメソッド | カプセル化が不十分 | +| **Primitive Obsession（プリミティブ型への執着）** | オブジェクト化すべき所をプリミティブで多用 | ドメイン概念が欠落 | +| **Long Parameter List（長すぎるパラメータリスト）** | パラメータが 4 個以上 | 正しく呼び出すのが困難 | +| **Data Clumps（データの群れ）** | 同じデータ項目が常に一緒に現れる | 抽象化が欠落 | +| **Switch Statements（スイッチ文)** | 複雑な switch / if-else の連鎖 | 拡張が困難 | +| **Speculative Generality（投機的一般化）** | 「念のため」のコード | 不要な複雑さ | +| **Dead Code（デッドコード）** | 使われていないコード | 混乱と保守負担 | + +### 分析ステップ + +1. **自動分析**(スクリプトが利用可能な場合) + ```bash + python scripts/detect-smells.py + ``` + +2. **手動レビュー** + - コードを体系的に読み進める + - 各スメルを場所と深刻度とともに記録する + - 影響度別に分類する(Critical / High / Medium / Low) + +3. **優先順位付け** + 次のようなスメルに注力する。 + - 現在の開発をブロックしているもの + - バグや混乱を引き起こしているもの + - 変更頻度が高いコードパスに影響するもの + +### 出力: スメルレポート + +ユーザーへの提示内容: +- 検出されたスメルの一覧と場所 +- 各スメルの深刻度評価 +- 推奨される優先順位 +- **優先順位の承認を依頼する** + +--- + +## フェーズ 4: リファクタリング計画の作成 + +### リファクタリング技法の選定 + +各スメルに対して、カタログから適切なリファクタリング技法を選ぶ。 + +完全な一覧は [references/refactoring-catalog.md](references/refactoring-catalog.md) を参照。 + +#### スメル別の推奨リファクタリング + +| コードスメル | 推奨リファクタリング | +|------------|---------------------------| +| Long Method（長すぎる関数） | メソッドの抽出、Replace Temp with Query | +| Duplicated Code（重複したコード） | メソッドの抽出、Pull Up Method、Form Template Method | +| Large Class（巨大なクラス） | クラスの抽出、Extract Subclass | +| Feature Envy（機能の横恋慕） | Move Method、Move Field | +| Primitive Obsession（プリミティブ型への執着） | Replace Primitive with Object、Replace Type Code with Class | +| Long Parameter List（長すぎるパラメータリスト） | パラメータオブジェクトの導入、Preserve Whole Object | +| Data Clumps（データの群れ） | クラスの抽出、パラメータオブジェクトの導入 | +| Switch Statements（スイッチ文） | ポリモーフィズムによる条件記述の置き換え | +| Speculative Generality（投機的一般化） | Collapse Hierarchy、Inline Class、デッドコードの削除 | +| Dead Code（デッドコード） | デッドコードの削除 | + +### 計画の構成 + +[templates/refactoring-plan.md](templates/refactoring-plan.md) のテンプレートを使用する。 + +各リファクタリングごとに次の項目を埋める。 +1. **対象**: 何を変更するか +2. **スメル**: どの問題に対処するか +3. **リファクタリング**: どの技法を適用するか +4. **手順**: 細かいマイクロステップ +5. **リスク**: 何が失敗しうるか +6. **ロールバック**: 取り消す方法 + +### 段階的アプローチ + +**重要**: リファクタリングはフェーズに分けて段階的に導入する。 + +**フェーズ A: クイックウィン**(低リスク、高価値) +- 明確化のための変数名変更 +- 明らかな重複コードの抽出 +- デッドコードの削除 + +**フェーズ B: 構造改善**(中リスク) +- 長すぎる関数からのメソッド抽出 +- パラメータオブジェクトの導入 +- メソッドを適切なクラスへ移動 + +**フェーズ C: アーキテクチャ変更**(高リスク) +- 条件分岐をポリモーフィズムで置換 +- クラスの抽出 +- デザインパターンの導入 + +### 判断ポイント: ユーザーへの計画提示 + +実装前に: +- 完全なリファクタリング計画を提示する +- 各フェーズの内容とリスクを説明する +- 各フェーズについて明示的な承認を得る +- **質問**: 「フェーズ A を進めてもよいか?」 + +--- + +## フェーズ 5: 段階的な実装 + +### ゴールデンルール +> "Change → Test → Green? → Commit → Next step" + +### 実装のリズム + +各リファクタリングステップで: + +1. **事前チェック** + - テストがパスしている(green) + - コードがコンパイルできる + +2. **小さな変更を 1 つだけ行う** + - カタログのメカニクスに従う + - 変更は最小限に保つ + +3. **検証** + - 直ちにテストを実行 + - コンパイルエラーがないか確認 + +4. **テストがパス(green)した場合** + - 説明的なコミットメッセージでコミット + - 次のステップへ進む + +5. **テストが失敗(red)した場合** + - 直ちに STOP + - 変更を取り消す + - 何が起きたかを分析する + - 不明な場合はユーザーに確認する + +### コミット戦略 + +各コミットは次の性質を満たすこと。 +- **アトミック**: 論理的に 1 つの変更 +- **可逆**: 容易に revert できる +- **説明的**: 明確なコミットメッセージ + +コミットメッセージ例: +``` +refactor: Extract calculateTotal() from processOrder() +refactor: Rename 'x' to 'customerCount' for clarity +refactor: Remove unused validateOldFormat() method +``` + +### 進捗報告 + +サブフェーズごとに、ユーザーへ次を報告する。 +- 行った変更 +- テストはまだパスしているか +- 発生した問題 +- **質問**: 「次のバッチへ進めてもよいか?」 + +--- + +## フェーズ 6: レビューと反復 + +### リファクタリング後チェックリスト + +- [ ] 全テストがパスする +- [ ] 新たな警告/エラーが出ていない +- [ ] コードが正常にコンパイルできる +- [ ] 振る舞いが変わっていない(手動検証) +- [ ] 必要に応じてドキュメントが更新されている +- [ ] コミット履歴が整理されている + +### メトリクス比較 + +リファクタリング前後で複雑度解析を実施する。 +```bash +python scripts/analyze-complexity.py +``` + +改善点を提示する。 +- コード行数の変化 +- 循環的複雑度の変化 +- 保守性指数の変化 + +### ユーザーレビュー + +最終結果を提示する。 +- 全変更のサマリー +- Before / After のコード比較 +- メトリクスの改善 +- 残る技術的負債 +- **質問**: 「この変更内容で問題ないか?」 + +### 次のステップ + +ユーザーと議論する。 +- 追加で対処すべきスメルはあるか? +- フォローアップのリファクタリングを計画するか? +- 同様の変更を他箇所にも適用するか? + +--- + +## 重要なガイドライン + +### STOP してユーザーに相談すべきタイミング + +次の場合、必ず一旦止まりユーザーに相談する。 +- ビジネスロジックに不確実性がある +- 外部 API に影響しうる変更 +- テストカバレッジが不十分 +- 重大なアーキテクチャ判断が必要 +- リスクレベルが上昇する +- 想定外の複雑さに遭遇した + +### 安全のためのルール + +1. **テストなしでリファクタリングしない**(ユーザーが明示的にリスクを受容しない限り) +2. **大きな変更を一度にしない** - 微小なステップに分割する +3. **各変更後のテスト実行を省略しない** +4. **テスト失敗時は続行しない** - 修正かロールバックを先に行う +5. **思い込みで進めない** - 疑問があれば確認する + +### やってはいけないこと + +- リファクタリングと機能追加を同時に行わない +- 本番障害対応中にリファクタリングしない +- 理解していないコードをリファクタリングしない +- 過剰設計をしない - シンプルに保つ +- 全てを一度にリファクタリングしない + +--- + +## クイックスタート例 + +### シナリオ: 重複を含む長い関数 + +**Before:** +```javascript +function processOrder(order) { + // 150 行のコードに以下が混在: + // - 重複したバリデーションロジック + // - インラインの計算処理 + // - 複数の責務 +} +``` + +**リファクタリング手順:** + +1. processOrder() に対する**テストの存在を確認** +2. バリデーションを validateOrder() に**抽出** +3. **テスト** - パスすること +4. 計算を calculateOrderTotal() に**抽出** +5. **テスト** - パスすること +6. 通知を notifyCustomer() に**抽出** +7. **テスト** - パスすること +8. **レビュー** - processOrder() は明確な 3 関数の調整役となる + +**After:** +```javascript +function processOrder(order) { + validateOrder(order); + const total = calculateOrderTotal(order); + notifyCustomer(order, total); + return { order, total }; +} +``` + +--- + +## 参考文献 + +- [Code Smells Catalog](references/code-smells.md) - コードスメルの完全な一覧 +- [Refactoring Catalog](references/refactoring-catalog.md) - リファクタリング技法 +- [Refactoring Plan Template](templates/refactoring-plan.md) - 計画用テンプレート + +## スクリプト + +- `scripts/analyze-complexity.py` - コード複雑度メトリクスの分析 +- `scripts/detect-smells.py` - スメルの自動検出 + +## バージョン履歴 + +- v1.0.0 (2025-01-15): Fowler の方法論、段階的アプローチ、ユーザー相談ポイントを備えた初版リリース diff --git a/ja/03-skills/refactor/references/code-smells.md b/ja/03-skills/refactor/references/code-smells.md new file mode 100644 index 0000000..8b51742 --- /dev/null +++ b/ja/03-skills/refactor/references/code-smells.md @@ -0,0 +1,672 @@ + + + +# コードスメルカタログ + +Martin Fowler 著『Refactoring』(第 2 版) に基づく、コードスメルの包括的なリファレンスである。コードスメルはより深い問題の症状であり、コード設計に何か問題がある可能性を示す指標となる。 + +> "A code smell is a surface indication that usually corresponds to a deeper problem in the system." — Martin Fowler + +--- + +## Bloaters（肥満児） + +効果的に扱うには大きくなりすぎたものを表すコードスメル群である。 + +### Long Method（長すぎる関数） + +**兆候:** +- メソッドが 30〜50 行を超える +- メソッド全体を見るのにスクロールが必要 +- ネストが多重になっている +- セクションごとに何をしているかを説明するコメントがある + +**なぜ悪いか:** +- 理解しづらい +- 単独でテストするのが難しい +- 変更が予期しない影響を及ぼす +- 内部に重複ロジックが隠れる + +**リファクタリング:** +- メソッドの抽出 +- Replace Temp with Query +- パラメータオブジェクトの導入 +- Replace Method with Method Object +- 条件記述の分解 + +**例（Before）:** +```javascript +function processOrder(order) { + // 注文の検証 (20 行) + if (!order.items) throw new Error('No items'); + if (order.items.length === 0) throw new Error('Empty order'); + // ... さらに検証 + + // 合計金額の計算 (30 行) + let subtotal = 0; + for (const item of order.items) { + subtotal += item.price * item.quantity; + } + // ... 税、送料、割引 + + // 通知の送信 (20 行) + // ... メール送信ロジック +} +``` + +**例（After）:** +```javascript +function processOrder(order) { + validateOrder(order); + const totals = calculateOrderTotals(order); + sendOrderNotifications(order, totals); + return { order, totals }; +} +``` + +--- + +### Large Class（巨大なクラス） + +**兆候:** +- クラスのインスタンス変数が多い(7〜10 個超) +- クラスのメソッドが多い(15〜20 個超) +- クラス名が漠然としている(Manager、Handler、Processor) +- 全インスタンス変数を使わないメソッドがある + +**なぜ悪いか:** +- 単一責任原則に違反する +- テストが困難 +- 変更が無関係な機能にも波及する +- 部分的な再利用が難しい + +**リファクタリング:** +- クラスの抽出 +- Extract Subclass +- Extract Interface + +**検出基準:** +``` +コード行数 > 300 +メソッド数 > 15 +フィールド数 > 10 +``` + +--- + +### Primitive Obsession（プリミティブ型への執着） + +**兆候:** +- ドメイン概念にプリミティブを使う(メールに string、金額に int) +- オブジェクトでなくプリミティブの配列を使う +- タイプコードに文字列定数を使う +- マジックナンバーやマジックストリング + +**なぜ悪いか:** +- 型レベルでの検証ができない +- ロジックがコードベース全体に散らばる +- 誤った値を渡しやすい +- ドメイン概念が欠落する + +**リファクタリング:** +- Replace Primitive with Object +- Replace Type Code with Class +- Replace Type Code with Subclasses +- Replace Type Code with State/Strategy + +**例（Before）:** +```javascript +const user = { + email: 'john@example.com', // 単なる文字列 + phone: '1234567890', // 単なる文字列 + status: 'active', // マジックストリング + balance: 10050 // セント単位の整数 +}; +``` + +**例（After）:** +```javascript +const user = { + email: new Email('john@example.com'), + phone: new PhoneNumber('1234567890'), + status: UserStatus.ACTIVE, + balance: Money.cents(10050) +}; +``` + +--- + +### Long Parameter List（長すぎるパラメータリスト） + +**兆候:** +- パラメータが 4 個以上のメソッド +- 常に一緒に現れるパラメータ +- メソッドの振る舞いを切り替える真偽値フラグ +- null/undefined が頻繁に渡される + +**なぜ悪いか:** +- 正しく呼び出すのが難しい +- 引数順序の混乱を招く +- メソッドが多くを抱え込んでいるサイン +- パラメータの追加が難しい + +**リファクタリング:** +- パラメータオブジェクトの導入 +- Preserve Whole Object +- Replace Parameter with Method Call +- Remove Flag Argument + +**例（Before）:** +```javascript +function createUser(firstName, lastName, email, phone, + street, city, state, zip, + isAdmin, isActive, createdBy) { + // ... +} +``` + +**例（After）:** +```javascript +function createUser(personalInfo, address, options) { + // personalInfo: { firstName, lastName, email, phone } + // address: { street, city, state, zip } + // options: { isAdmin, isActive, createdBy } +} +``` + +--- + +### Data Clumps（データの群れ） + +**兆候:** +- 同じ 3 個以上のフィールドが繰り返し一緒に現れる +- 常に一緒に渡されるパラメータ群 +- 一塊として属するべきフィールド集合を持つクラス + +**なぜ悪いか:** +- 取り扱いロジックが重複する +- 抽象化が欠けている +- 拡張しづらい +- 隠れたクラスの存在を示す + +**リファクタリング:** +- クラスの抽出 +- パラメータオブジェクトの導入 +- Preserve Whole Object + +**例:** +```javascript +// データの群れ: (x, y, z) 座標 +function movePoint(x, y, z, dx, dy, dz) { } +function scalePoint(x, y, z, factor) { } +function distanceBetween(x1, y1, z1, x2, y2, z2) { } + +// Point3D クラスを抽出 +class Point3D { + constructor(x, y, z) { } + move(delta) { } + scale(factor) { } + distanceTo(other) { } +} +``` + +--- + +## Object-Orientation Abusers（オブジェクト指向の濫用者） + +オブジェクト指向の原則を不完全または誤って使っていることを示すスメル群である。 + +### Switch Statements（スイッチ文） + +**兆候:** +- 長い switch/case や if/else の連鎖 +- 同じ switch が複数箇所に存在 +- タイプコードに対する switch +- 新ケース追加で各所を変更する必要がある + +**なぜ悪いか:** +- 開放閉鎖原則に違反する +- 全ての switch 箇所に変更が波及する +- 拡張が困難 +- ポリモーフィズム不在のサインであることが多い + +**リファクタリング:** +- ポリモーフィズムによる条件記述の置き換え +- Replace Type Code with Subclasses +- Replace Type Code with State/Strategy + +**例（Before）:** +```javascript +function calculatePay(employee) { + switch (employee.type) { + case 'hourly': + return employee.hours * employee.rate; + case 'salaried': + return employee.salary / 12; + case 'commissioned': + return employee.sales * employee.commission; + } +} +``` + +**例（After）:** +```javascript +class HourlyEmployee { + calculatePay() { + return this.hours * this.rate; + } +} + +class SalariedEmployee { + calculatePay() { + return this.salary / 12; + } +} +``` + +--- + +### Temporary Field（一時的フィールド） + +**兆候:** +- 一部のメソッドでのみ使用されるインスタンス変数 +- 条件付きで設定されるフィールド +- 特定ケースのために複雑な初期化を要する + +**なぜ悪いか:** +- 紛らわしい - フィールドが存在するが null の場合がある +- オブジェクトの状態が理解しづらい +- 隠れた条件分岐ロジックを示す + +**リファクタリング:** +- クラスの抽出 +- Introduce Null Object +- Replace Temp Field with Local + +--- + +### Refused Bequest（相続拒否） + +**兆候:** +- サブクラスが継承したメソッド/データを使わない +- サブクラスがオーバーライドして何もしない +- IS-A 関係ではなくコード再利用目的の継承 + +**なぜ悪いか:** +- 抽象化が誤っている +- リスコフの置換原則に違反する +- 階層が誤解を招く + +**リファクタリング:** +- Push Down Method/Field +- Replace Subclass with Delegate +- Replace Inheritance with Delegation + +--- + +### Alternative Classes with Different Interfaces（異なるインターフェイスの代替クラス） + +**兆候:** +- 似たことをする 2 つのクラス +- 同じ概念に異なるメソッド名を使っている +- 互いに置換可能だが共通インターフェイスがない + +**なぜ悪いか:** +- 実装が重複する +- 共通インターフェイスがない +- 切り替えが難しい + +**リファクタリング:** +- Rename Method +- Move Method +- Extract Superclass +- Extract Interface + +--- + +## Change Preventers（変更の妨げ） + +変更を困難にするスメル群 - ある変更のために他の多くを変える必要が生じる。 + +### Divergent Change（変更の発散） + +**兆候:** +- 1 つのクラスが異なる複数の理由で変更される +- 異なる領域の変更が同じクラスへの編集を引き起こす +- そのクラスは「神クラス」化している + +**なぜ悪いか:** +- 単一責任原則に違反する +- 変更頻度が高くなる +- マージコンフリクトを招く + +**リファクタリング:** +- クラスの抽出 +- Extract Superclass +- Extract Subclass + +**例:** +`User` クラスが次の理由で変更される: +- 認証の変更 +- プロフィールの変更 +- 課金の変更 +- 通知の変更 + +→ 抽出: `AuthService`、`ProfileService`、`BillingService`、`NotificationService` + +--- + +### Shotgun Surgery（散弾銃手術） + +**兆候:** +- 1 つの変更で多くのクラスへの編集が必要 +- 小さな機能でも 10 ファイル以上に手を入れる +- 変更箇所が散在し、すべてを見つけにくい + +**なぜ悪いか:** +- 修正漏れが起きやすい +- 結合度が高い +- 変更がエラーを誘発しやすい + +**リファクタリング:** +- Move Method +- Move Field +- Inline Class + +**検出基準:** +1 フィールドの追加で 5 ファイル以上の変更が必要かを確認する。 + +--- + +### Parallel Inheritance Hierarchies（並行継承階層） + +**兆候:** +- 一方の階層にサブクラスを作ると、もう一方にも作る必要がある +- クラス名のプレフィックスが揃っている(例: `DatabaseOrder`、`DatabaseProduct`) + +**なぜ悪いか:** +- 保守コストが倍になる +- 階層間の結合度が高い +- 片側を忘れやすい + +**リファクタリング:** +- Move Method +- Move Field +- 一方の階層を削除する + +--- + +## Dispensables（不要物） + +不要であり削除すべきものを表すスメル群である。 + +### Comments（過剰なコメント） + +**兆候:** +- コードが何をしているかを説明するコメント +- コメントアウトされたコード +- 永遠に残る TODO/FIXME +- 言い訳のコメント + +**なぜ悪いか:** +- コメントは嘘をつく(コードと乖離する) +- コードは自己文書化されているべき +- 死んだコードは混乱を生む + +**リファクタリング:** +- メソッドの抽出(名前で「何」を表す) +- Rename(コメントなしで明確化) +- コメントアウトされたコードの削除 +- Introduce Assertion + +**良いコメントと悪いコメント:** +```javascript +// 悪い: 「何」を説明している +// users をループしてアクティブかどうか確認 +for (const user of users) { + if (user.status === 'active') { } +} + +// 良い: 「なぜ」を説明している +// アクティブなユーザーのみ。非アクティブはクリーンアップジョブで処理される +const activeUsers = users.filter(u => u.isActive); +``` + +--- + +### Duplicate Code（重複したコード） + +**兆候:** +- 同じコードが複数箇所にある +- わずかな違いだけの似たコード +- コピペのパターン + +**なぜ悪いか:** +- バグ修正を複数箇所で行う必要がある +- 不整合のリスク +- コードベースが肥大化する + +**リファクタリング:** +- メソッドの抽出 +- クラスの抽出 +- Pull Up Method(階層内) +- Form Template Method + +**検出ルール:** +3 回以上重複するコードは抽出すべきである。 + +--- + +### Lazy Class（怠け者のクラス） + +**兆候:** +- クラスが存在を正当化できるほど働いていない +- 付加価値のないラッパー +- 過剰設計の結果 + +**なぜ悪いか:** +- 保守オーバーヘッド +- 不要な間接参照 +- メリットなき複雑さ + +**リファクタリング:** +- Inline Class +- Collapse Hierarchy + +--- + +### Dead Code（デッドコード） + +**兆候:** +- 到達不能なコード +- 使われていない変数/メソッド/クラス +- コメントアウトされたコード +- 起こり得ない条件下にあるコード + +**なぜ悪いか:** +- 混乱を招く +- 保守の負担 +- 理解の速度を落とす + +**リファクタリング:** +- デッドコードの削除 +- Safe Delete + +**検出基準:** +```bash +# 未使用のエクスポートを探す +# 参照されない関数を探す +# IDE の「未使用」警告を確認 +``` + +--- + +### Speculative Generality（投機的一般化） + +**兆候:** +- サブクラスが 1 つしかない抽象クラス +- 「将来のため」の未使用パラメータ +- 委譲のみのメソッド +- 1 用途しかない「フレームワーク」 + +**なぜ悪いか:** +- メリットなき複雑さ +- YAGNI(You Ain't Gonna Need It) +- 理解しづらい + +**リファクタリング:** +- Collapse Hierarchy +- Inline Class +- Remove Parameter +- Rename Method + +--- + +## Couplers（結合の問題） + +クラス間の過剰な結合を表すスメル群である。 + +### Feature Envy（機能の横恋慕） + +**兆候:** +- メソッドが自クラスより他クラスのデータを多く使う +- 他オブジェクトへの getter 呼び出しが多い +- データと振る舞いが分離している + +**なぜ悪いか:** +- 振る舞いの置き場所が誤っている +- カプセル化が不十分 +- 保守が難しい + +**リファクタリング:** +- Move Method +- Move Field +- メソッドの抽出(その後 move) + +**例（Before）:** +```javascript +class Order { + getDiscountedPrice(customer) { + // customer のデータを多く使っている + if (customer.loyaltyYears > 5) { + return this.price * customer.discountRate; + } + return this.price; + } +} +``` + +**例（After）:** +```javascript +class Customer { + getDiscountedPriceFor(price) { + if (this.loyaltyYears > 5) { + return price * this.discountRate; + } + return price; + } +} +``` + +--- + +### Inappropriate Intimacy（不適切な親密さ） + +**兆候:** +- クラスが互いのプライベート部分にアクセスする +- 双方向の参照 +- サブクラスが親について詳しすぎる + +**なぜ悪いか:** +- 結合度が高い +- 変更が連鎖する +- 一方を変えると他方も変える必要がある + +**リファクタリング:** +- Move Method +- Move Field +- Change Bidirectional to Unidirectional +- クラスの抽出 +- Hide Delegate + +--- + +### Message Chains（メッセージの連鎖） + +**兆候:** +- メソッド呼び出しの長い連鎖: `a.getB().getC().getD().getValue()` +- クライアントがナビゲーション構造に依存している +- 「列車事故」コード + +**なぜ悪いか:** +- 脆弱 - 連鎖中のいずれかが変わると壊れる +- デメテルの法則に違反する +- 構造への結合 + +**リファクタリング:** +- Hide Delegate +- メソッドの抽出 +- Move Method + +**例:** +```javascript +// 悪い: メッセージの連鎖 +const managerName = employee.getDepartment().getManager().getName(); + +// 良い: 委譲を隠す +const managerName = employee.getManagerName(); +``` + +--- + +### Middle Man（仲介人） + +**兆候:** +- 他クラスへ委譲するだけのクラス +- メソッドの半数が委譲 +- 付加価値がない + +**なぜ悪いか:** +- 不要な間接参照 +- 保守オーバーヘッド +- アーキテクチャが分かりにくい + +**リファクタリング:** +- Remove Middle Man +- メソッドのインライン化 + +--- + +## スメル深刻度ガイド + +| 深刻度 | 説明 | 対応 | +|----------|-------------|--------| +| **Critical** | 開発をブロックし、バグの原因となる | 直ちに修正 | +| **High** | 保守負担が大きい | 当該スプリント中に修正 | +| **Medium** | 目に付くが許容範囲 | 近い将来に計画 | +| **Low** | 軽微な不便 | 機会があれば修正 | + +--- + +## 簡易検出チェックリスト + +コードをスキャンする際に使うチェックリストである。 + +- [ ] 30 行を超えるメソッドはあるか? +- [ ] 300 行を超えるクラスはあるか? +- [ ] 4 個を超えるパラメータを持つメソッドはあるか? +- [ ] 重複したコードブロックはあるか? +- [ ] タイプコードに対する switch/case はあるか? +- [ ] 使われていないコードはあるか? +- [ ] 他クラスのデータを多く使っているメソッドはあるか? +- [ ] メソッド呼び出しの長い連鎖はあるか? +- [ ] 「なぜ」ではなく「何」を説明しているコメントはあるか? +- [ ] オブジェクト化すべきプリミティブはあるか? + +--- + +## 参考文献 + +- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.) +- Kerievsky, J. (2004). *Refactoring to Patterns* +- Feathers, M. (2004). *Working Effectively with Legacy Code* diff --git a/ja/03-skills/refactor/references/refactoring-catalog.md b/ja/03-skills/refactor/references/refactoring-catalog.md new file mode 100644 index 0000000..8b02a00 --- /dev/null +++ b/ja/03-skills/refactor/references/refactoring-catalog.md @@ -0,0 +1,1027 @@ + + + + +# リファクタリングカタログ + +Martin Fowler 著『Refactoring』(第 2 版) から厳選したリファクタリング技法のカタログである。各リファクタリングには動機、手順、例を掲載している。 + +> 「リファクタリングは、その手順、すなわち変更を実施するための正確なステップ列によって定義される。」 — Martin Fowler + +--- + +## このカタログの使い方 + +1. コードスメルのリファレンスを使って **コードスメルを特定する** +2. このカタログから **対応するリファクタリングを探す** +3. **手順に沿って一段ずつ進める** +4. **各ステップごとにテスト** を実行し、振る舞いが保たれていることを確認する + +**鉄則**: ある手順に 10 分以上かかるのであれば、もっと小さなステップに分割すること。 + +--- + +## 最も頻出するリファクタリング + +### メソッドの抽出 (Extract Method) + +**使う場面**: 長いメソッド、重複コード、概念に名前を付けたいとき + +**動機**: コード片を、目的を表す名前を持つメソッドに切り出す。 + +**手順**: +1. やっていること(どうやってではなく)にちなんだ名前で新しいメソッドを作成する +2. コード片を新しいメソッドへコピーする +3. コード片で使われているローカル変数を洗い出す +4. ローカル変数をパラメータとして渡す(あるいはメソッド内で宣言する) +5. 戻り値を適切に処理する +6. 元のコード片を新しいメソッドの呼び出しに置き換える +7. テストする + +**Before**: +```javascript +function printOwing(invoice) { + let outstanding = 0; + + console.log("***********************"); + console.log("**** Customer Owes ****"); + console.log("***********************"); + + // 未払額の計算 + for (const order of invoice.orders) { + outstanding += order.amount; + } + + // 詳細の出力 + console.log(`name: ${invoice.customer}`); + console.log(`amount: ${outstanding}`); +} +``` + +**After**: +```javascript +function printOwing(invoice) { + printBanner(); + const outstanding = calculateOutstanding(invoice); + printDetails(invoice, outstanding); +} + +function printBanner() { + console.log("***********************"); + console.log("**** Customer Owes ****"); + console.log("***********************"); +} + +function calculateOutstanding(invoice) { + return invoice.orders.reduce((sum, order) => sum + order.amount, 0); +} + +function printDetails(invoice, outstanding) { + console.log(`name: ${invoice.customer}`); + console.log(`amount: ${outstanding}`); +} +``` + +--- + +### メソッドのインライン化 (Inline Method) + +**使う場面**: メソッド本体が名前と同じくらい明快な場合、過度な委譲が見られる場合 + +**動機**: メソッドが価値を加えていない場合、不要な間接参照を取り除く。 + +**手順**: +1. メソッドがポリモーフィックでないことを確認する +2. メソッドの呼び出し箇所をすべて見つける +3. 各呼び出しをメソッド本体で置き換える +4. 置き換えるたびにテストする +5. メソッド定義を削除する + +**Before**: +```javascript +function getRating(driver) { + return moreThanFiveLateDeliveries(driver) ? 2 : 1; +} + +function moreThanFiveLateDeliveries(driver) { + return driver.numberOfLateDeliveries > 5; +} +``` + +**After**: +```javascript +function getRating(driver) { + return driver.numberOfLateDeliveries > 5 ? 2 : 1; +} +``` + +--- + +### 変数の抽出 (Extract Variable) + +**使う場面**: 複雑で理解しづらい式があるとき + +**動機**: 複雑な式の一部に名前を付ける。 + +**手順**: +1. 式に副作用がないことを確認する +2. イミュータブルな変数を宣言する +3. 式(または式の一部)の結果をその変数に代入する +4. 元の式を変数で置き換える +5. テストする + +**Before**: +```javascript +return order.quantity * order.itemPrice - + Math.max(0, order.quantity - 500) * order.itemPrice * 0.05 + + Math.min(order.quantity * order.itemPrice * 0.1, 100); +``` + +**After**: +```javascript +const basePrice = order.quantity * order.itemPrice; +const quantityDiscount = Math.max(0, order.quantity - 500) * order.itemPrice * 0.05; +const shipping = Math.min(basePrice * 0.1, 100); +return basePrice - quantityDiscount + shipping; +``` + +--- + +### 変数のインライン化 (Inline Variable) + +**使う場面**: 変数名が式以上の情報を伝えていないとき + +**動機**: 不要な間接参照を取り除く。 + +**手順**: +1. 右辺に副作用がないことを確認する +2. 変数がイミュータブルでなければイミュータブルにし、テストする +3. 最初の参照箇所を見つけて式で置き換える +4. テストする +5. すべての参照箇所について繰り返す +6. 宣言と代入を削除する +7. テストする + +--- + +### 変数名の変更 (Rename Variable) + +**使う場面**: 名前が目的を明確に伝えていないとき + +**動機**: クリーンなコードには良い名前が不可欠である。 + +**手順**: +1. 変数が広く使われている場合は、カプセル化を検討する +2. すべての参照箇所を見つける +3. 各参照箇所を変更する +4. テストする + +**Tips**: +- 意図を明らかにする名前を使う +- 略語を避ける +- ドメイン用語を用いる + +```javascript +// 悪い例 +const d = 30; +const x = users.filter(u => u.a); + +// 良い例 +const daysSinceLastLogin = 30; +const activeUsers = users.filter(user => user.isActive); +``` + +--- + +### 関数宣言の変更 (Change Function Declaration) + +**使う場面**: 関数名が目的を表していない、パラメータの変更が必要な場合 + +**動機**: 良い関数名はコードを自己説明的にする。 + +**手順 (シンプル版)**: +1. 不要なパラメータを削除する +2. 名前を変更する +3. 必要なパラメータを追加する +4. テストする + +**手順 (マイグレーション版 — 複雑な変更向け)**: +1. パラメータを削除する場合、それが使われていないことを確認する +2. 望ましい宣言の新しい関数を作成する +3. 古い関数から新しい関数を呼び出すようにする +4. テストする +5. 呼び出し側を新しい関数を使うように変更する +6. 各変更後にテストする +7. 古い関数を削除する + +**Before**: +```javascript +function circum(radius) { + return 2 * Math.PI * radius; +} +``` + +**After**: +```javascript +function circumference(radius) { + return 2 * Math.PI * radius; +} +``` + +--- + +### 変数のカプセル化 (Encapsulate Variable) + +**使う場面**: データに複数箇所から直接アクセスしているとき + +**動機**: データ操作のための明確なアクセスポイントを提供する。 + +**手順**: +1. getter と setter 関数を作成する +2. すべての参照箇所を見つける +3. 読み取りを getter で置き換える +4. 書き込みを setter で置き換える +5. 各変更後にテストする +6. 変数の可視性を制限する + +**Before**: +```javascript +let defaultOwner = { firstName: "Martin", lastName: "Fowler" }; + +// 多くの場所で利用される +spaceship.owner = defaultOwner; +``` + +**After**: +```javascript +let defaultOwnerData = { firstName: "Martin", lastName: "Fowler" }; + +function defaultOwner() { return defaultOwnerData; } +function setDefaultOwner(arg) { defaultOwnerData = arg; } + +spaceship.owner = defaultOwner(); +``` + +--- + +### パラメータオブジェクトの導入 (Introduce Parameter Object) + +**使う場面**: いくつかのパラメータがしばしばまとまって登場する場合 + +**動機**: 自然にまとまるべきデータをグループ化する。 + +**手順**: +1. グループ化したパラメータ用の新しいクラス/構造体を作成する +2. テストする +3. 「関数宣言の変更」で新しいオブジェクトを追加する +4. テストする +5. グループ内の各パラメータについて、関数から取り除き新しいオブジェクトを使うようにする +6. 各変更後にテストする + +**Before**: +```javascript +function amountInvoiced(startDate, endDate) { ... } +function amountReceived(startDate, endDate) { ... } +function amountOverdue(startDate, endDate) { ... } +``` + +**After**: +```javascript +class DateRange { + constructor(start, end) { + this.start = start; + this.end = end; + } +} + +function amountInvoiced(dateRange) { ... } +function amountReceived(dateRange) { ... } +function amountOverdue(dateRange) { ... } +``` + +--- + +### 関数群のクラス化 (Combine Functions into Class) + +**使う場面**: 複数の関数が同じデータを操作している場合 + +**動機**: 関数を、それらが操作するデータと共にまとめる。 + +**手順**: +1. 共通データに「レコードのカプセル化 (Encapsulate Record)」を適用する +2. 各関数をクラス内に移動する +3. 移動するたびにテストする +4. データ引数をクラスのフィールド利用に置き換える + +**Before**: +```javascript +function base(reading) { ... } +function taxableCharge(reading) { ... } +function calculateBaseCharge(reading) { ... } +``` + +**After**: +```javascript +class Reading { + constructor(data) { this._data = data; } + + get base() { ... } + get taxableCharge() { ... } + get calculateBaseCharge() { ... } +} +``` + +--- + +### 段階の分割 (Split Phase) + +**使う場面**: コードが 2 つの異なる事柄を扱っている場合 + +**動機**: コードを明確な境界を持つ別々のフェーズに分離する。 + +**手順**: +1. 第 2 フェーズ用の関数を作成する +2. テストする +3. フェーズ間の中間データ構造を導入する +4. テストする +5. 第 1 フェーズを独立した関数として抽出する +6. テストする + +**Before**: +```javascript +function priceOrder(product, quantity, shippingMethod) { + const basePrice = product.basePrice * quantity; + const discount = Math.max(quantity - product.discountThreshold, 0) + * product.basePrice * product.discountRate; + const shippingPerCase = (basePrice > shippingMethod.discountThreshold) + ? shippingMethod.discountedFee : shippingMethod.feePerCase; + const shippingCost = quantity * shippingPerCase; + return basePrice - discount + shippingCost; +} +``` + +**After**: +```javascript +function priceOrder(product, quantity, shippingMethod) { + const priceData = calculatePricingData(product, quantity); + return applyShipping(priceData, shippingMethod); +} + +function calculatePricingData(product, quantity) { + const basePrice = product.basePrice * quantity; + const discount = Math.max(quantity - product.discountThreshold, 0) + * product.basePrice * product.discountRate; + return { basePrice, quantity, discount }; +} + +function applyShipping(priceData, shippingMethod) { + const shippingPerCase = (priceData.basePrice > shippingMethod.discountThreshold) + ? shippingMethod.discountedFee : shippingMethod.feePerCase; + const shippingCost = priceData.quantity * shippingPerCase; + return priceData.basePrice - priceData.discount + shippingCost; +} +``` + +--- + +## 機能の移動 + +### メソッドの移動 (Move Method) + +**使う場面**: メソッドが自分のクラスより他のクラスの機能を多く使っている場合 + +**動機**: 関数を、最もよく利用するデータの近くに置く。 + +**手順**: +1. 自クラス内でメソッドが利用しているプログラム要素をすべて調べる +2. メソッドがポリモーフィックかどうか確認する +3. 移動先クラスにメソッドをコピーする +4. 新しいコンテキストに合わせて調整する +5. 元のメソッドが移動先に委譲するようにする +6. テストする +7. 元のメソッドの削除を検討する + +--- + +### フィールドの移動 (Move Field) + +**使う場面**: フィールドが他のクラスでより多く使われている場合 + +**動機**: データを、それを使う関数と共に保持する。 + +**手順**: +1. まだの場合はフィールドをカプセル化する +2. テストする +3. 移動先にフィールドを作成する +4. 参照箇所を移動先のフィールドを使うように更新する +5. テストする +6. 元のフィールドを削除する + +--- + +### 関数への文の移動 (Move Statements into Function) + +**使う場面**: 同じコードが必ずある関数呼び出しと一緒に現れる場合 + +**動機**: 繰り返しコードを関数内に移動して重複を取り除く。 + +**手順**: +1. まだの場合は繰り返しコードを関数として抽出する +2. その関数の中に文を移動する +3. テストする +4. 呼び出し側で単独の文が不要になったら削除する + +--- + +### 呼び出し側への文の移動 (Move Statements to Callers) + +**使う場面**: 共通の振る舞いが呼び出し側ごとに異なる場合 + +**動機**: 振る舞いを変える必要があるなら、関数の外に移す。 + +**手順**: +1. 移動するコードに「メソッドの抽出」を適用する +2. 元の関数に「メソッドのインライン化」を適用する +3. インライン化された呼び出しを削除する +4. 抽出したコードを各呼び出し側に移動する +5. テストする + +--- + +## データの再編成 + +### プリミティブをオブジェクトで置き換える (Replace Primitive with Object) + +**使う場面**: データ項目に単純な値以上の振る舞いが必要な場合 + +**動機**: データを振る舞いと共にカプセル化する。 + +**手順**: +1. 「変数のカプセル化」を適用する +2. シンプルな値クラスを作成する +3. setter を新しいインスタンス生成に変更する +4. getter を値の返却に変更する +5. テストする +6. 新しいクラスにより豊かな振る舞いを追加する + +**Before**: +```javascript +class Order { + constructor(data) { + this.priority = data.priority; // 文字列: "high"、"rush" など + } +} + +// 利用箇所 +if (order.priority === "high" || order.priority === "rush") { ... } +``` + +**After**: +```javascript +class Priority { + constructor(value) { + if (!Priority.legalValues().includes(value)) + throw new Error(`Invalid priority: ${value}`); + this._value = value; + } + + static legalValues() { return ['low', 'normal', 'high', 'rush']; } + get value() { return this._value; } + + higherThan(other) { + return Priority.legalValues().indexOf(this._value) > + Priority.legalValues().indexOf(other._value); + } +} + +// 利用箇所 +if (order.priority.higherThan(new Priority("normal"))) { ... } +``` + +--- + +### 一時変数を問い合わせで置き換える (Replace Temp with Query) + +**使う場面**: 一時変数が式の結果を保持している場合 + +**動機**: 式を関数として切り出すことでコードを明快にする。 + +**手順**: +1. 変数が一度だけ代入されていることを確認する +2. 代入の右辺をメソッドとして抽出する +3. 一時変数の参照箇所をメソッド呼び出しで置き換える +4. テストする +5. 一時変数の宣言と代入を削除する + +**Before**: +```javascript +const basePrice = this._quantity * this._itemPrice; +if (basePrice > 1000) { + return basePrice * 0.95; +} else { + return basePrice * 0.98; +} +``` + +**After**: +```javascript +get basePrice() { + return this._quantity * this._itemPrice; +} + +// メソッド内 +if (this.basePrice > 1000) { + return this.basePrice * 0.95; +} else { + return this.basePrice * 0.98; +} +``` + +--- + +## 条件記述の単純化 + +### 条件記述の分解 (Decompose Conditional) + +**使う場面**: 複雑な条件分岐 (if-then-else) があるとき + +**動機**: 条件と動作を抽出して意図を明確にする。 + +**手順**: +1. 条件部分に「メソッドの抽出」を適用する +2. then 節に「メソッドの抽出」を適用する +3. else 節 (もしあれば) に「メソッドの抽出」を適用する + +**Before**: +```javascript +if (!aDate.isBefore(plan.summerStart) && !aDate.isAfter(plan.summerEnd)) { + charge = quantity * plan.summerRate; +} else { + charge = quantity * plan.regularRate + plan.regularServiceCharge; +} +``` + +**After**: +```javascript +if (isSummer(aDate, plan)) { + charge = summerCharge(quantity, plan); +} else { + charge = regularCharge(quantity, plan); +} + +function isSummer(date, plan) { + return !date.isBefore(plan.summerStart) && !date.isAfter(plan.summerEnd); +} + +function summerCharge(quantity, plan) { + return quantity * plan.summerRate; +} + +function regularCharge(quantity, plan) { + return quantity * plan.regularRate + plan.regularServiceCharge; +} +``` + +--- + +### 条件式の統合 (Consolidate Conditional Expression) + +**使う場面**: 同じ結果を返す条件が複数あるとき + +**動機**: それらの条件が単一のチェックであることを明らかにする。 + +**手順**: +1. 条件に副作用がないことを確認する +2. 条件を `and` または `or` で結合する +3. 結合した条件に「メソッドの抽出」を検討する + +**Before**: +```javascript +if (employee.seniority < 2) return 0; +if (employee.monthsDisabled > 12) return 0; +if (employee.isPartTime) return 0; +``` + +**After**: +```javascript +if (isNotEligibleForDisability(employee)) return 0; + +function isNotEligibleForDisability(employee) { + return employee.seniority < 2 || + employee.monthsDisabled > 12 || + employee.isPartTime; +} +``` + +--- + +### ガード節による入れ子の条件記述の置き換え (Replace Nested Conditional with Guard Clauses) + +**使う場面**: 入れ子の条件分岐が深く、流れを追いにくいとき + +**動機**: 特殊ケースにガード節を使い、通常フローを明確に保つ。 + +**手順**: +1. 特殊ケースの条件を見つける +2. それらを早期 return するガード節で置き換える +3. 各変更後にテストする + +**Before**: +```javascript +function payAmount(employee) { + let result; + if (employee.isSeparated) { + result = { amount: 0, reasonCode: "SEP" }; + } else { + if (employee.isRetired) { + result = { amount: 0, reasonCode: "RET" }; + } else { + result = calculateNormalPay(employee); + } + } + return result; +} +``` + +**After**: +```javascript +function payAmount(employee) { + if (employee.isSeparated) return { amount: 0, reasonCode: "SEP" }; + if (employee.isRetired) return { amount: 0, reasonCode: "RET" }; + return calculateNormalPay(employee); +} +``` + +--- + +### ポリモーフィズムによる条件記述の置き換え (Replace Conditional with Polymorphism) + +**使う場面**: 型に基づく switch/case、型ごとに変化する条件ロジック + +**動機**: オブジェクト自身に振る舞いを担わせる。 + +**手順**: +1. クラス階層を作成する (なければ) +2. オブジェクト生成にファクトリ関数を使う +3. 条件ロジックをスーパークラスのメソッドに移す +4. ケースごとにサブクラスのメソッドを作成する +5. 元の条件記述を削除する + +**Before**: +```javascript +function plumages(birds) { + return birds.map(b => plumage(b)); +} + +function plumage(bird) { + switch (bird.type) { + case 'EuropeanSwallow': + return "average"; + case 'AfricanSwallow': + return (bird.numberOfCoconuts > 2) ? "tired" : "average"; + case 'NorwegianBlueParrot': + return (bird.voltage > 100) ? "scorched" : "beautiful"; + default: + return "unknown"; + } +} +``` + +**After**: +```javascript +class Bird { + get plumage() { return "unknown"; } +} + +class EuropeanSwallow extends Bird { + get plumage() { return "average"; } +} + +class AfricanSwallow extends Bird { + get plumage() { + return (this.numberOfCoconuts > 2) ? "tired" : "average"; + } +} + +class NorwegianBlueParrot extends Bird { + get plumage() { + return (this.voltage > 100) ? "scorched" : "beautiful"; + } +} + +function createBird(data) { + switch (data.type) { + case 'EuropeanSwallow': return new EuropeanSwallow(data); + case 'AfricanSwallow': return new AfricanSwallow(data); + case 'NorwegianBlueParrot': return new NorwegianBlueParrot(data); + default: return new Bird(data); + } +} +``` + +--- + +### 特殊ケースの導入 (Introduce Special Case / Null Object) + +**使う場面**: 特殊ケースに対する null チェックが繰り返される場合 + +**動機**: 特殊ケースを処理する特殊オブジェクトを返す。 + +**手順**: +1. 期待されるインターフェースを持つ特殊ケースクラスを作成する +2. isSpecialCase チェックを追加する +3. ファクトリメソッドを導入する +4. null チェックを特殊ケースオブジェクトの利用で置き換える +5. テストする + +**Before**: +```javascript +const customer = site.customer; +// ... 多数の箇所でチェック +if (customer === "unknown") { + customerName = "occupant"; +} else { + customerName = customer.name; +} +``` + +**After**: +```javascript +class UnknownCustomer { + get name() { return "occupant"; } + get billingPlan() { return registry.defaultPlan; } +} + +// ファクトリメソッド +function customer(site) { + return site.customer === "unknown" + ? new UnknownCustomer() + : site.customer; +} + +// 利用箇所 — null チェック不要 +const customerName = customer.name; +``` + +--- + +## API のリファクタリング + +### 問い合わせと変更の分離 (Separate Query from Modifier) + +**使う場面**: 関数が値を返すと同時に副作用も持つ場合 + +**動機**: どの操作に副作用があるのかを明確にする。 + +**手順**: +1. 新しい問い合わせ関数を作成する +2. 元の関数の戻り値ロジックをコピーする +3. 元の関数を void を返すように変更する +4. 戻り値を使っていた呼び出しを置き換える +5. テストする + +**Before**: +```javascript +function alertForMiscreant(people) { + for (const p of people) { + if (p === "Don") { + setOffAlarms(); + return "Don"; + } + if (p === "John") { + setOffAlarms(); + return "John"; + } + } + return ""; +} +``` + +**After**: +```javascript +function findMiscreant(people) { + for (const p of people) { + if (p === "Don") return "Don"; + if (p === "John") return "John"; + } + return ""; +} + +function alertForMiscreant(people) { + if (findMiscreant(people) !== "") setOffAlarms(); +} +``` + +--- + +### 関数のパラメータ化 (Parameterize Function) + +**使う場面**: 似たような処理を異なる値で行う関数が複数あるとき + +**動機**: パラメータを追加することで重複を取り除く。 + +**手順**: +1. 一つの関数を選ぶ +2. 変動するリテラル用のパラメータを追加する +3. 本体をそのパラメータを使うように変更する +4. テストする +5. 呼び出し側をパラメータ化された版を使うように変更する +6. 不要になった関数を削除する + +**Before**: +```javascript +function tenPercentRaise(person) { + person.salary = person.salary * 1.10; +} + +function fivePercentRaise(person) { + person.salary = person.salary * 1.05; +} +``` + +**After**: +```javascript +function raise(person, factor) { + person.salary = person.salary * (1 + factor); +} + +// 利用箇所 +raise(person, 0.10); +raise(person, 0.05); +``` + +--- + +### フラグ引数の削除 (Remove Flag Argument) + +**使う場面**: 関数の振る舞いを切り替えるブール型パラメータがある場合 + +**動機**: 別々の関数を通して振る舞いを明示的にする。 + +**手順**: +1. フラグの値ごとに明示的な関数を作成する +2. 各呼び出しを適切な新しい関数で置き換える +3. 各変更後にテストする +4. 元の関数を削除する + +**Before**: +```javascript +function bookConcert(customer, isPremium) { + if (isPremium) { + // プレミアム予約のロジック + } else { + // 通常予約のロジック + } +} + +bookConcert(customer, true); +bookConcert(customer, false); +``` + +**After**: +```javascript +function bookPremiumConcert(customer) { + // プレミアム予約のロジック +} + +function bookRegularConcert(customer) { + // 通常予約のロジック +} + +bookPremiumConcert(customer); +bookRegularConcert(customer); +``` + +--- + +## 継承の取り扱い + +### メソッドの引き上げ (Pull Up Method) + +**使う場面**: 同じメソッドが複数のサブクラスにあるとき + +**動機**: クラス階層内の重複を取り除く。 + +**手順**: +1. メソッド同士が同一であることを確認する +2. シグネチャが同じであることを確認する +3. スーパークラスに新しいメソッドを作成する +4. 一つのサブクラスから本体をコピーする +5. 一つのサブクラスからメソッドを削除し、テストする +6. 他のサブクラスのメソッドも順次削除し、その都度テストする + +--- + +### メソッドの押し下げ (Push Down Method) + +**使う場面**: サブクラスの一部のみに関係する振る舞いがあるとき + +**動機**: メソッドを使われる場所に置く。 + +**手順**: +1. メソッドを必要とする各サブクラスにコピーする +2. スーパークラスからメソッドを削除する +3. テストする +4. 必要としないサブクラスからは削除する +5. テストする + +--- + +### サブクラスを委譲で置き換える (Replace Subclass with Delegate) + +**使う場面**: 継承が誤って使われている、もしくはより柔軟性が必要な場合 + +**動機**: 適切な場面では継承よりコンポジションを優先する。 + +**手順**: +1. 委譲先用の空クラスを作成する +2. 委譲先を保持するフィールドをホストクラスに追加する +3. ホストから呼ばれる委譲先のコンストラクタを作成する +4. 機能を委譲先へ移動する +5. 移動するたびにテストする +6. 継承を委譲で置き換える + +--- + +## クラスの抽出 (Extract Class) + +**使う場面**: 複数の責務を持つ大きなクラスがあるとき + +**動機**: クラスを分割して単一責務を保つ。 + +**手順**: +1. 責務をどう分けるか決める +2. 新しいクラスを作成する +3. フィールドを元のクラスから新しいクラスへ移動する +4. テストする +5. メソッドを元のクラスから新しいクラスへ移動する +6. 移動するたびにテストする +7. 両クラスを見直して必要なら名前を変更する +8. 新しいクラスをどう公開するかを決める + +**Before**: +```javascript +class Person { + get name() { return this._name; } + set name(arg) { this._name = arg; } + get officeAreaCode() { return this._officeAreaCode; } + set officeAreaCode(arg) { this._officeAreaCode = arg; } + get officeNumber() { return this._officeNumber; } + set officeNumber(arg) { this._officeNumber = arg; } + + get telephoneNumber() { + return `(${this._officeAreaCode}) ${this._officeNumber}`; + } +} +``` + +**After**: +```javascript +class Person { + constructor() { + this._telephoneNumber = new TelephoneNumber(); + } + get name() { return this._name; } + set name(arg) { this._name = arg; } + get telephoneNumber() { return this._telephoneNumber.toString(); } + get officeAreaCode() { return this._telephoneNumber.areaCode; } + set officeAreaCode(arg) { this._telephoneNumber.areaCode = arg; } +} + +class TelephoneNumber { + get areaCode() { return this._areaCode; } + set areaCode(arg) { this._areaCode = arg; } + get number() { return this._number; } + set number(arg) { this._number = arg; } + toString() { return `(${this._areaCode}) ${this._number}`; } +} +``` + +--- + +## クイックリファレンス: スメルからリファクタリングへ + +| コードスメル | 主なリファクタリング | 代替 | +|------------|-------------------|-------------| +| 長すぎるメソッド (Long Method) | メソッドの抽出 | 一時変数を問い合わせで置き換える | +| 重複コード (Duplicate Code) | メソッドの抽出 | メソッドの引き上げ | +| 大きすぎるクラス (Large Class) | クラスの抽出 | サブクラスの抽出 | +| 長すぎるパラメータリスト (Long Parameter List) | パラメータオブジェクトの導入 | オブジェクトそのものの受け渡し | +| 機能の横恋慕 (Feature Envy) | メソッドの移動 | メソッドの抽出 + 移動 | +| データのかたまり (Data Clumps) | クラスの抽出 | パラメータオブジェクトの導入 | +| プリミティブ依存症 (Primitive Obsession) | プリミティブをオブジェクトで置き換える | タイプコードの置き換え | +| switch 文 (Switch Statements) | ポリモーフィズムによる条件記述の置き換え | タイプコードの置き換え | +| 一時的属性 (Temporary Field) | クラスの抽出 | Null オブジェクトの導入 | +| メッセージの連鎖 (Message Chains) | 委譲の隠蔽 | メソッドの抽出 | +| 仲介人 (Middle Man) | 中間者の除去 | メソッドのインライン化 | +| 変更の分散 (Divergent Change) | クラスの抽出 | 段階の分割 | +| 散弾銃手術 (Shotgun Surgery) | メソッドの移動 | クラスのインライン化 | +| 死せるコード (Dead Code) | 死せるコードの除去 | - | +| 投機的一般性 (Speculative Generality) | 階層の平坦化 | クラスのインライン化 | + +--- + +## 参考文献 + +- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.) +- オンラインカタログ: https://refactoring.com/catalog/ diff --git a/ja/03-skills/refactor/templates/refactoring-plan.md b/ja/03-skills/refactor/templates/refactoring-plan.md new file mode 100644 index 0000000..0fd871b --- /dev/null +++ b/ja/03-skills/refactor/templates/refactoring-plan.md @@ -0,0 +1,287 @@ + + + +# リファクタリング計画テンプレート + +リファクタリング作業を文書化し、進捗を追跡するためのテンプレートである。 + +--- + +## プロジェクト情報 + +| 項目 | 値 | +|-------|-------| +| **プロジェクト/モジュール** | [プロジェクト名] | +| **対象ファイル** | [リファクタリング対象ファイルの一覧] | +| **作成日** | [日付] | +| **作成者** | [氏名] | +| **ステータス** | Draft / In Review / Approved / In Progress / Completed | + +--- + +## エグゼクティブサマリー + +### 目標 +- [ ] [主目標: 例、決済処理の可読性向上] +- [ ] [副目標: 例、コード重複の削減] +- [ ] [第三目標: 例、テスト容易性の向上] + +### 制約 +- [ ] [制約 1: 例、公開 API は変更不可] +- [ ] [制約 2: 例、後方互換性を維持すること] +- [ ] [制約 3: 例、データベーススキーマは変更しない] + +### リスクレベル +- [ ] Low - 小規模変更、十分にテストされたコード +- [ ] Medium - 中規模変更、ある程度のリスクあり +- [ ] High - 大規模変更、慎重な対応が必要 + +--- + +## リファクタリング前チェックリスト + +### テストカバレッジの評価 + +| 指標 | 現状 | 目標 | ステータス | +|--------|---------|--------|--------| +| ユニットテストカバレッジ | __% | ≥80% | | +| 統合テスト | Yes/No | Yes | | +| 全テストがパス | Yes/No | Yes | | + +### 開始前に必要な事項 +- [ ] 全テストがパスしている +- [ ] コードがレビューされ理解されている +- [ ] バックアップ/バージョン管理が準備済み +- [ ] ユーザーの承認を得ている + +--- + +## 検出されたコードスメル + +### サマリー + +| # | スメル | 場所 | 深刻度 | 優先度 | +|---|-------|----------|----------|----------| +| 1 | [例、Long Method（長すぎる関数）] | [file:line] | High | P1 | +| 2 | [例、Duplicate Code（重複したコード）] | [file:line] | Medium | P2 | +| 3 | [例、Feature Envy（機能の横恋慕）] | [file:line] | Low | P3 | + +### 詳細分析 + +#### スメル #1: [名称] + +**場所**: `path/to/file.js:45-120` + +**説明**: [問題点の詳細説明] + +**影響**: +- [影響 1] +- [影響 2] + +**提案する解決策**: [修正方法の概要] + +--- + +## リファクタリングのフェーズ + +### フェーズ A: クイックウィン（低リスク） + +**目的**: 即効性のあるシンプルな改善 + +**変更見積もり**: [X ファイル、Y メソッド] + +**ユーザー承認の要否**: Yes / No + +| # | タスク | ファイル | リファクタリング | ステータス | +|---|------|------|-------------|--------| +| A1 | 変数 `x` を `userCount` に名称変更 | utils.js:15 | 変数名の変更 | [ ] | +| A2 | 未使用の `oldHandler()` を削除 | api.js:89 | デッドコードの削除 | [ ] | +| A3 | 重複バリデーションを抽出 | form.js:23,67 | メソッドの抽出 | [ ] | + +**ロールバック計画**: コミット A1〜A3 を revert + +--- + +### フェーズ B: 構造改善（中リスク） + +**目的**: コードの構成と明確さを改善する + +**変更見積もり**: [X ファイル、Y メソッド] + +**ユーザー承認の要否**: Yes + +**依存関係**: フェーズ A 完了が前提 + +| # | タスク | ファイル | リファクタリング | ステータス | +|---|------|------|-------------|--------| +| B1 | 長い関数から `calculatePrice()` を抽出 | order.js:45 | メソッドの抽出 | [ ] | +| B2 | `OrderDetails` パラメータオブジェクトを導入 | order.js:12 | パラメータオブジェクトの導入 | [ ] | +| B3 | `formatAddress()` を Address クラスに移動 | customer.js:78 | メソッドの移動 | [ ] | + +**ロールバック計画**: フェーズ A 完了直後のコミットへ revert + +--- + +### フェーズ C: アーキテクチャ変更（高リスク） + +**目的**: より深い構造上の問題に対処する + +**変更見積もり**: [X ファイル、Y メソッド] + +**ユーザー承認の要否**: Yes + +**依存関係**: フェーズ A と B の完了が前提 + +| # | タスク | ファイル | リファクタリング | ステータス | +|---|------|------|-------------|--------| +| C1 | 価格 switch をポリモーフィズムで置換 | pricing.js:30 | ポリモーフィズムによる条件記述の置き換え | [ ] | +| C2 | `NotificationService` クラスを抽出 | user.js:100 | クラスの抽出 | [ ] | + +**ロールバック計画**: フェーズ B 完了直後のコミットへ revert + +--- + +## 詳細なリファクタリング手順 + +### タスク [ID]: [タスク名] + +**対処するスメル**: [スメル名] + +**リファクタリング技法**: [技法名] + +**リスクレベル**: Low / Medium / High + +#### コンテキスト + +**Before**（現状）: +```javascript +// 現状のコードをここに貼り付け +``` + +**After**（期待される状態）: +```javascript +// 期待されるコードをここに貼り付け +``` + +#### ステップごとの手順 + +1. [ ] **ステップ 1**: [説明] + - テスト: このステップ後にテストを実行する + - 期待結果: 全テストがパスする + +2. [ ] **ステップ 2**: [説明] + - テスト: このステップ後にテストを実行する + - 期待結果: 全テストがパスする + +3. [ ] **ステップ 3**: [説明] + - テスト: このステップ後にテストを実行する + - 期待結果: 全テストがパスする + +#### 検証 + +- [ ] 全テストがパスする +- [ ] 振る舞いが変わっていない +- [ ] コードがコンパイルできる +- [ ] 新たな警告が出ていない + +#### コミットメッセージ +``` +refactor: [リファクタリング内容を記述] +``` + +--- + +## 進捗管理 + +### フェーズステータス + +| フェーズ | ステータス | 開始日 | 完了日 | テストパス | +|-------|--------|---------|-----------|---------------| +| A | Not Started / In Progress / Done | | | | +| B | Not Started / In Progress / Done | | | | +| C | Not Started / In Progress / Done | | | | + +### 発生した課題 + +| # | 課題 | 解決策 | ステータス | +|---|-------|------------|--------| +| 1 | [説明] | [解決方法] | Open / Resolved | + +--- + +## メトリクス比較 + +### リファクタリング前 + +| 指標 | File 1 | File 2 | 合計 | +|--------|--------|--------|-------| +| コード行数 | | | | +| 循環的複雑度 | | | | +| 保守性指数 | | | | +| メソッド数 | | | | +| 平均メソッド行数 | | | | + +### リファクタリング後 + +| 指標 | File 1 | File 2 | 合計 | 変化 | +|--------|--------|--------|-------|--------| +| コード行数 | | | | | +| 循環的複雑度 | | | | | +| 保守性指数 | | | | | +| メソッド数 | | | | | +| 平均メソッド行数 | | | | | + +--- + +## リファクタリング後チェックリスト + +- [ ] 全テストがパスする +- [ ] 新たな警告やエラーが出ていない +- [ ] コードが正常にコンパイルできる +- [ ] 手動検証が完了している +- [ ] ドキュメントが必要に応じて更新されている +- [ ] コードレビュー済み +- [ ] メトリクスが改善している +- [ ] ユーザーの承認を得ている + +--- + +## 学んだ教訓 + +### 良かった点 +- [項目 1] +- [項目 2] + +### 改善余地 +- [項目 1] +- [項目 2] + +### 今後への提言 +- [項目 1] +- [項目 2] + +--- + +## 承認 + +| 役割 | 氏名 | 日付 | 署名 | +|------|------|------|-----------| +| 計画作成者 | | | | +| テクニカルリード | | | | +| プロダクトオーナー | | | | + +--- + +## 付録 + +### A. 関連ドキュメント +- [関連ドキュメントへのリンク] + +### B. 参考資料 +- [コードスメルカタログへのリンク] +- [リファクタリングカタログへのリンク] + +### C. 使用したツール +- [テストフレームワーク] +- [リンタツール] +- [複雑度解析ツール] diff --git a/ja/04-subagents/README.md b/ja/04-subagents/README.md new file mode 100644 index 0000000..f9003d7 --- /dev/null +++ b/ja/04-subagents/README.md @@ -0,0 +1,1251 @@ + + + + + + + Claude How To + + +# サブエージェント — 完全リファレンスガイド + +サブエージェントは、Claude Code がタスクを委譲できる専門化された AI アシスタントである。各サブエージェントは特定の目的を持ち、メインの会話とは別の独自のコンテキストウィンドウを使い、特定のツールとカスタムシステムプロンプトで構成できる。 + +## 目次 + +1. [概要](#概要) +2. [主な利点](#主な利点) +3. [ファイルの配置場所](#ファイルの配置場所) +4. [設定](#設定) +5. [組み込みサブエージェント](#組み込みサブエージェント) +6. [サブエージェントの管理](#サブエージェントの管理) +7. [サブエージェントの使い方](#サブエージェントの使い方) +8. [再開可能なエージェント](#再開可能なエージェント) +9. [サブエージェントの連鎖](#サブエージェントの連鎖) +10. [サブエージェントの永続メモリ](#サブエージェントの永続メモリ) +11. [バックグラウンドサブエージェント](#バックグラウンドサブエージェント) +12. [ワークツリー分離](#ワークツリー分離) +13. [生成可能なサブエージェントの制限](#生成可能なサブエージェントの制限) +14. [`claude agents` CLI コマンド](#claude-agents-cli-コマンド) +15. [Agent Teams（実験的）](#agent-teams実験的) +16. [プラグインサブエージェントのセキュリティ](#プラグインサブエージェントのセキュリティ) +17. [アーキテクチャ](#アーキテクチャ) +18. [コンテキスト管理](#コンテキスト管理) +19. [サブエージェントを使うべきとき](#サブエージェントを使うべきとき) +20. [ベストプラクティス](#ベストプラクティス) +21. [このフォルダのサンプルサブエージェント](#このフォルダのサンプルサブエージェント) +22. [インストール手順](#インストール手順) +23. [関連概念](#関連概念) + +--- + +## 概要 + +サブエージェントは、Claude Code に以下を可能にしてタスクの委譲実行を実現する： + +- 別のコンテキストウィンドウを持つ **隔離された AI アシスタント** の作成 +- 専門的な知見のための **カスタマイズされたシステムプロンプト** の提供 +- 機能を制限するための **ツールアクセス制御** の強制 +- 複雑なタスクによる **コンテキスト汚染の防止** +- 複数の専門タスクの **並列実行** の実現 + +各サブエージェントは独立して動作し、クリーンスレートの状態でそのタスクに必要な特定のコンテキストのみを受け取り、結果をメインエージェントに返して統合する。 + +**クイックスタート**：`/agents` コマンドを使うと、サブエージェントを対話的に作成・表示・編集・管理できる。 + +--- + +## 主な利点 + +| 利点 | 説明 | +|------|------| +| **コンテキスト保持** | 別コンテキストで動作し、メイン会話の汚染を防ぐ | +| **専門化された知見** | 特定ドメインに調整され、成功率が高い | +| **再利用性** | 異なるプロジェクト間で利用でき、チームと共有できる | +| **柔軟な権限** | サブエージェントの種類ごとに異なるツールアクセスレベル | +| **スケーラビリティ** | 複数のエージェントが異なる側面に同時に取り組める | + +--- + +## ファイルの配置場所 + +サブエージェントファイルはスコープの異なる複数の場所に保存できる： + +| 優先度 | 種類 | 場所 | スコープ | +|--------|------|------|---------| +| 1（最高） | **CLI 定義** | `--agents` フラグ経由（JSON） | セッションのみ | +| 2 | **プロジェクトサブエージェント** | `.claude/agents/` | 現在のプロジェクト | +| 3 | **ユーザーサブエージェント** | `~/.claude/agents/` | 全プロジェクト | +| 4（最低） | **プラグインエージェント** | プラグインの `agents/` ディレクトリ | プラグイン経由 | + +同名が複数存在する場合、優先度の高いソースが優先される。 + +--- + +## 設定 + +### ファイル形式 + +サブエージェントは YAML フロントマターで定義され、その後に Markdown 形式のシステムプロンプトが続く： + +```yaml +--- +name: your-sub-agent-name +description: Description of when this subagent should be invoked +tools: tool1, tool2, tool3 # オプション — 省略するとすべてのツールを継承 +disallowedTools: tool4 # オプション — 明示的に禁止するツール +model: sonnet # オプション — sonnet、opus、haiku、または inherit +permissionMode: default # オプション — 権限モード +maxTurns: 20 # オプション — エージェント的なターン数を制限 +skills: skill1, skill2 # オプション — コンテキストにプリロードするスキル +mcpServers: server1 # オプション — 利用可能にする MCP サーバー +memory: user # オプション — 永続メモリのスコープ（user、project、local） +background: false # オプション — バックグラウンドタスクとして実行 +effort: high # オプション — 推論努力（low、medium、high、max） +isolation: worktree # オプション — git ワークツリー分離 +initialPrompt: "Start by analyzing the codebase" # オプション — 自動送信される最初のターン +hooks: # オプション — コンポーネントスコープのフック + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/security-check.sh" +--- + +サブエージェントのシステムプロンプトをここに記述する。複数段落になってもよく、 +サブエージェントの役割、機能、問題解決のアプローチを明確に定義すべきである。 +``` + +### 設定フィールド + +| フィールド | 必須 | 説明 | +|-----------|-----|------| +| `name` | はい | 一意な識別子（小文字とハイフン） | +| `description` | はい | 用途の自然言語による説明。"use PROACTIVELY" を含めると自動呼び出しが促進される | +| `tools` | いいえ | 特定ツールのカンマ区切りリスト。省略するとすべてのツールを継承。`Agent(agent_name)` 構文で生成可能なサブエージェントを制限できる | +| `disallowedTools` | いいえ | サブエージェントが使用してはならないツールのカンマ区切りリスト | +| `model` | いいえ | 使用モデル：`sonnet`、`opus`、`haiku`、フルモデル ID、または `inherit`。デフォルトは設定済みのサブエージェントモデル | +| `permissionMode` | いいえ | `default`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan` | +| `maxTurns` | いいえ | サブエージェントが取れるエージェント的ターンの最大数 | +| `skills` | いいえ | プリロードするスキルのカンマ区切りリスト。起動時にスキルの全内容をサブエージェントのコンテキストに注入する | +| `mcpServers` | いいえ | サブエージェントから利用可能にする MCP サーバー | +| `hooks` | いいえ | コンポーネントスコープのフック（PreToolUse、PostToolUse、Stop） | +| `memory` | いいえ | 永続メモリディレクトリのスコープ：`user`、`project`、`local` | +| `background` | いいえ | `true` にすると常にこのサブエージェントをバックグラウンドタスクとして実行 | +| `effort` | いいえ | 推論努力レベル：`low`、`medium`、`high`、`max` | +| `isolation` | いいえ | `worktree` にするとサブエージェント専用の git ワークツリーを与える | +| `initialPrompt` | いいえ | サブエージェントがメインエージェントとして実行されるとき、自動送信される最初のターン | + +### メインスレッドエージェントのフロントマター尊重（v2.1.117+/v2.1.119+） + +エージェントがメインスレッドエージェントとして呼び出されるとき（`claude --agent ` または `--print` モード経由）、以下のフロントマターフィールドが尊重される： + +| フィールド | バージョン | 備考 | +|-----------|---------|------| +| `mcpServers` | v2.1.117+ | `claude --agent ` でメインスレッドエージェントとして呼び出されたときにロード | +| `permissionMode` | v2.1.119+ | `--agent ` 経由の組み込みエージェントで尊重される | +| `tools` / `disallowedTools` | v2.1.119+ | `--print` モード（非対話／スクリプト用途）で尊重される | + +**例 — `mcpServers` と `permissionMode` を持つエージェント：** + +```yaml +--- +name: secure-researcher +description: Research agent with scoped MCP access and restricted permissions +permissionMode: acceptEdits +mcpServers: + notion: + type: http + url: https://mcp.notion.com/mcp + github: + type: http + url: https://api.github.com/mcp +tools: Read, Grep, Glob +--- + +You are a research agent. You may query Notion and GitHub through the +configured MCP servers, and read local files, but you cannot write or +execute commands outside of accepted edits. +``` + +実行： + +```bash +claude --agent secure-researcher +``` + +### ツール設定オプション + +**オプション 1：すべてのツールを継承（フィールドを省略）** + +```yaml +--- +name: full-access-agent +description: Agent with all available tools +--- +``` + +**オプション 2：個別ツールを指定** + +```yaml +--- +name: limited-agent +description: Agent with specific tools only +tools: Read, Grep, Glob, Bash +--- +``` + +> **Glob/Grep に関する注記（v2.1.113+）：** ネイティブ macOS/Linux ビルドでは、Glob と Grep は別個のツールではなく Bash ツール経由で `bfs`/`ugrep` として提供される。Windows と npm-JS ビルドでは引き続きスタンドアロンツールとして公開される。著者は引き続き `allowedTools` で Glob/Grep を参照でき、バックエンドの置換は透過的に行われる。 + +**オプション 3：条件付きツールアクセス** + +```yaml +--- +name: conditional-agent +description: Agent with filtered tool access +tools: Read, Bash(npm:*), Bash(test:*) +--- +``` + +### CLI ベースの設定 + +`--agents` フラグを JSON 形式で使うと、単一セッション用にサブエージェントを定義できる： + +```bash +claude --agents '{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + } +}' +``` + +**`--agents` フラグの JSON 形式：** + +```json +{ + "agent-name": { + "description": "Required: when to invoke this agent", + "prompt": "Required: system prompt for the agent", + "tools": ["Optional", "array", "of", "tools"], + "model": "optional: sonnet|opus|haiku" + } +} +``` + +**エージェント定義の優先順位：** + +エージェント定義は次の優先順位でロードされる（最初に一致したものが優先）： + +1. **CLI 定義** — `--agents` フラグ（セッションのみ、JSON） +2. **プロジェクトレベル** — `.claude/agents/`（現在のプロジェクト） +3. **ユーザーレベル** — `~/.claude/agents/`（すべてのプロジェクト） +4. **プラグインレベル** — プラグインの `agents/` ディレクトリ + +これにより、CLI 定義が単一セッションにおいて他のすべてのソースを上書きできる。 + +--- + +## 組み込みサブエージェント + +Claude Code には常に利用可能な組み込みサブエージェントがいくつか含まれている： + +| エージェント | モデル | 目的 | +|-------------|-------|------| +| **general-purpose** | 継承 | 複雑な多段タスク | +| **Plan** | 継承 | プランモードのリサーチ | +| **Explore** | Haiku | 読み取り専用のコードベース探索（quick/medium/very thorough） | +| **Bash** | 継承 | 別コンテキストでのターミナルコマンド | +| **statusline-setup** | Sonnet | ステータスラインの設定 | +| **Claude Code Guide** | Haiku | Claude Code の機能に関する質問への回答 | + +### General-Purpose サブエージェント + +| プロパティ | 値 | +|-----------|-----| +| **モデル** | 親から継承 | +| **ツール** | 全ツール | +| **目的** | 複雑な調査タスク、多段操作、コード変更 | + +**使用場面**：探索と変更の両方が必要で、複雑な推論を伴うタスク。 + +### Plan サブエージェント + +| プロパティ | 値 | +|-----------|-----| +| **モデル** | 親から継承 | +| **ツール** | Read、Glob、Grep、Bash | +| **目的** | プランモードでコードベースを調査するために自動で使われる | + +**使用場面**：Claude がプランを提示する前にコードベースを理解する必要があるとき。 + +### Explore サブエージェント + +| プロパティ | 値 | +|-----------|-----| +| **モデル** | Haiku（高速・低レイテンシ） | +| **モード** | 厳密に読み取り専用 | +| **ツール** | Glob、Grep、Read、Bash（読み取り専用コマンドのみ） | +| **目的** | 高速なコードベース検索と分析 | + +**使用場面**：変更を加えずにコードを検索・理解するとき。 + +**徹底度レベル** — 探索の深さを指定する： + +- **"quick"** — 最小限の探索による高速検索。特定パターンを見つけるのに適する +- **"medium"** — 適度な探索。速度と徹底度のバランスが取れたデフォルトのアプローチ +- **"very thorough"** — 複数の場所と命名規約をまたぐ網羅的分析。時間がかかる場合がある + +### Bash サブエージェント + +| プロパティ | 値 | +|-----------|-----| +| **モデル** | 親から継承 | +| **ツール** | Bash | +| **目的** | 別のコンテキストウィンドウでターミナルコマンドを実行 | + +**使用場面**：隔離されたコンテキストの恩恵を受けるシェルコマンドを実行するとき。 + +### Statusline Setup サブエージェント + +| プロパティ | 値 | +|-----------|-----| +| **モデル** | Sonnet | +| **ツール** | Read、Write、Bash | +| **目的** | Claude Code のステータスライン表示を設定 | + +**使用場面**：ステータスラインのセットアップやカスタマイズ時。 + +### Claude Code Guide サブエージェント + +| プロパティ | 値 | +|-----------|-----| +| **モデル** | Haiku（高速・低レイテンシ） | +| **ツール** | 読み取り専用 | +| **目的** | Claude Code の機能と使い方に関する質問に回答 | + +**使用場面**：ユーザーが Claude Code の動作や特定機能の使い方について質問するとき。 + +--- + +## サブエージェントの管理 + +### `/agents` コマンドを使う（推奨） + +```bash +/agents +``` + +これは以下を行う対話メニューを提供する： + +- 利用可能なすべてのサブエージェント（組み込み、ユーザー、プロジェクト）の表示 +- ガイド付きセットアップで新しいサブエージェントを作成 +- 既存のカスタムサブエージェントとツールアクセスの編集 +- カスタムサブエージェントの削除 +- 重複がある場合にどのサブエージェントが有効かを確認 + +### 直接ファイル管理 + +```bash +# プロジェクトサブエージェントを作成 +mkdir -p .claude/agents +cat > .claude/agents/test-runner.md << 'EOF' +--- +name: test-runner +description: Use proactively to run tests and fix failures +--- + +You are a test automation expert. When you see code changes, proactively +run the appropriate tests. If tests fail, analyze the failures and fix +them while preserving the original test intent. +EOF + +# ユーザーサブエージェントを作成（すべてのプロジェクトで利用可能） +mkdir -p ~/.claude/agents +``` + +--- + +## サブエージェントの使い方 + +### 自動委譲 + +Claude は以下に基づいて積極的にタスクを委譲する： + +- リクエスト内のタスク説明 +- サブエージェント設定の `description` フィールド +- 現在のコンテキストと利用可能なツール + +積極的な使用を促すには、`description` フィールドに "use PROACTIVELY" または "MUST BE USED" を含める： + +```yaml +--- +name: code-reviewer +description: Expert code review specialist. Use PROACTIVELY after writing or modifying code. +--- +``` + +### 明示的な呼び出し + +特定のサブエージェントを明示的にリクエストできる： + +``` +> Use the test-runner subagent to fix failing tests +> Have the code-reviewer subagent look at my recent changes +> Ask the debugger subagent to investigate this error +``` + +### @-Mention による呼び出し + +`@` プレフィックスを使うと、特定のサブエージェントが確実に呼び出される（自動委譲のヒューリスティクスをバイパス）： + +``` +> @"code-reviewer (agent)" review the auth module +``` + +### セッション全体のエージェント + +特定のエージェントをメインエージェントとしてセッション全体を実行する： + +```bash +# CLI フラグ経由 +claude --agent code-reviewer + +# settings.json 経由 +{ + "agent": "code-reviewer" +} +``` + +### 利用可能なエージェントの一覧表示 + +`claude agents` コマンドを使って、すべてのソースから設定済みエージェントを一覧表示する： + +```bash +claude agents +``` + +--- + +## 再開可能なエージェント + +サブエージェントは、完全なコンテキストを保持したまま以前の会話を継続できる： + +```bash +# 初回呼び出し +> Use the code-analyzer agent to start reviewing the authentication module +# agentId を返す: "abc123" + +# 後でエージェントを再開 +> Resume agent abc123 and now analyze the authorization logic as well +``` + +**ユースケース**： + +- 複数セッションをまたぐ長期にわたる調査 +- コンテキストを失わない反復的な調整 +- コンテキストを維持する多段ワークフロー + +--- + +## サブエージェントの連鎖 + +複数のサブエージェントを順次実行する： + +```bash +> First use the code-analyzer subagent to find performance issues, + then use the optimizer subagent to fix them +``` + +これにより、あるサブエージェントの出力を別のサブエージェントへ流す複雑なワークフローが実現できる。 + +--- + +## サブエージェントの永続メモリ + +`memory` フィールドは、会話をまたいで存続する永続ディレクトリをサブエージェントに与える。これによりサブエージェントは、メモやセッション間で永続する文脈と発見を蓄積できる。 + +### メモリスコープ + +| スコープ | ディレクトリ | ユースケース | +|---------|------------|------------| +| `user` | `~/.claude/agent-memory//` | 全プロジェクト共通の個人メモと好み | +| `project` | `.claude/agent-memory//` | チームと共有するプロジェクト固有の知識 | +| `local` | `.claude/agent-memory-local//` | バージョン管理にコミットしないローカルプロジェクト知識 | + +### しくみ + +- メモリディレクトリ内の `MEMORY.md` の最初の 200 行が自動的にサブエージェントのシステムプロンプトにロードされる +- メモリファイルを管理するため `Read`、`Write`、`Edit` ツールがサブエージェントに自動的に有効化される +- サブエージェントは必要に応じてメモリディレクトリ内に追加ファイルを作成できる + +### 設定例 + +```yaml +--- +name: researcher +memory: user +--- + +You are a research assistant. Use your memory directory to store findings, +track progress across sessions, and build up knowledge over time. + +Check your MEMORY.md file at the start of each session to recall previous context. +``` + +```mermaid +graph LR + A["Subagent
Session 1"] -->|writes| M["MEMORY.md
(persistent)"] + M -->|loads into| B["Subagent
Session 2"] + B -->|updates| M + M -->|loads into| C["Subagent
Session 3"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style M fill:#f3e5f5,stroke:#333,color:#333 +``` + +--- + +## バックグラウンドサブエージェント + +サブエージェントはバックグラウンドで実行でき、メイン会話を他のタスクのために解放できる。 + +### 設定 + +フロントマターで `background: true` を設定すると、常にバックグラウンドタスクとしてサブエージェントを実行する： + +```yaml +--- +name: long-runner +background: true +description: Performs long-running analysis tasks in the background +--- +``` + +### キーボードショートカット + +| ショートカット | 動作 | +|-------------|------| +| `Ctrl+B` | 現在実行中のサブエージェントタスクをバックグラウンド化 | +| `Ctrl+F` | バックグラウンドエージェントをすべて終了（確認のため 2 回押下） | + +### バックグラウンドタスクの無効化 + +環境変数を設定するとバックグラウンドタスクのサポートを完全に無効化できる： + +```bash +export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 +``` + +--- + +## ワークツリー分離 + +`isolation: worktree` 設定により、サブエージェントに独自の git ワークツリーが与えられ、メインの作業ツリーに影響を与えずに独立して変更を加えられる。 + +### 設定 + +```yaml +--- +name: feature-builder +isolation: worktree +description: Implements features in an isolated git worktree +tools: Read, Write, Edit, Bash, Grep, Glob +--- +``` + +### しくみ + +```mermaid +graph TB + Main["Main Working Tree"] -->|spawns| Sub["Subagent with
Isolated Worktree"] + Sub -->|makes changes in| WT["Separate Git
Worktree + Branch"] + WT -->|no changes| Clean["Auto-cleaned"] + WT -->|has changes| Return["Returns worktree
path and branch"] + + style Main fill:#e1f5fe,stroke:#333,color:#333 + style Sub fill:#f3e5f5,stroke:#333,color:#333 + style WT fill:#e8f5e9,stroke:#333,color:#333 + style Clean fill:#fff3e0,stroke:#333,color:#333 + style Return fill:#fff3e0,stroke:#333,color:#333 +``` + +- サブエージェントは独立したブランチ上の独自の git ワークツリーで動作する +- サブエージェントが変更を加えなかった場合、ワークツリーは自動的にクリーンアップされる +- 変更がある場合、ワークツリーのパスとブランチ名がメインエージェントに返され、レビューやマージが可能になる + +--- + +## フォークサブエージェント + +フォークサブエージェント（`context: fork`）は、フォーク時点の親エージェントの会話コンテキスト全体を継承し、クリーンスレートではなくその状態から開始する。これは、これまでの作業を失わずに代替案を探索する場合に有用である。 + +> **可用性**：v2.1.117 で GA。外部ビルド（ファーストパーティ以外の配布）では `CLAUDE_CODE_FORK_SUBAGENT=1` を設定するとフォークが有効化される。 + +### 設定 + +```yaml +--- +name: alternative-explorer +description: Explore an alternative implementation path while preserving parent context +context: fork +tools: Read, Edit, Bash, Grep, Glob +--- + +You are a forked subagent. You inherit the parent's full conversation and +may explore an alternative approach. Return your findings and the parent +will decide whether to adopt them. +``` + +### 外部ビルドでの有効化 + +```bash +export CLAUDE_CODE_FORK_SUBAGENT=1 +claude +``` + +### Fork とクリーンコンテキストの使い分け + +| シナリオ | `context: fork` | クリーンコンテキスト（デフォルト） | +|---------|-----------------|-------------------------| +| 代替実装の探索 | はい | いいえ（コンテキストを失う） | +| 既存コンテキストを伴う長期調査 | はい | いいえ | +| 独立した専門タスク | いいえ | はい | +| コンテキスト汚染を避ける | いいえ | はい | + +--- + +## 生成可能なサブエージェントの制限 + +`tools` フィールドで `Agent(agent_type)` 構文を使うと、特定のサブエージェントが生成できるサブエージェントを制御できる。これは委譲対象の特定サブエージェントを許可リスト化する手段を提供する。 + +> **注**：v2.1.63 で `Task` ツールは `Agent` にリネームされた。既存の `Task(...)` 参照は引き続きエイリアスとして機能する。 + +### 例 + +```yaml +--- +name: coordinator +description: Coordinates work between specialized agents +tools: Agent(worker, researcher), Read, Bash +--- + +You are a coordinator agent. You can delegate work to the "worker" and +"researcher" subagents only. Use Read and Bash for your own exploration. +``` + +この例では、`coordinator` サブエージェントは `worker` と `researcher` サブエージェントのみ生成できる。他のサブエージェントが定義されていても、それらを生成することはできない。 + +--- + +## `claude agents` CLI コマンド + +`claude agents` コマンドは、設定済みのすべてのエージェントをソース別（組み込み、ユーザーレベル、プロジェクトレベル）にグループ化して一覧表示する： + +```bash +claude agents +``` + +このコマンドは： + +- すべてのソースから利用可能なエージェントを表示する +- ソースの場所別にエージェントをグループ化する +- 高い優先度レベルのエージェントが低い優先度のエージェントを覆い隠す場合（例：ユーザーレベルと同名のプロジェクトレベルエージェント）、**override** を表示する + +--- + +## Agent Teams（実験的） + +Agent Teams は、複雑なタスクで連携する複数の Claude Code インスタンスをコーディネートする。サブエージェント（委譲されたサブタスクが結果を返す形）と異なり、チームメイトは独自のコンテキストウィンドウで独立して動作し、共有メールボックスシステムを通じて互いに直接メッセージを送れる。 + +> **公式ドキュメント**：[code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) + +> **注**：Agent Teams は実験的でデフォルトでは無効。Claude Code v2.1.32+ が必要。使用前に有効化すること。 + +### サブエージェント vs Agent Teams + +| 観点 | サブエージェント | Agent Teams | +|-----|-----------|-------------| +| **委譲モデル** | 親がサブタスクを委譲し、結果を待つ | チームリードが作業をコーディネートし、チームメイトが独立して実行 | +| **コンテキスト** | サブタスクごとに新しいコンテキスト、結果は蒸留して戻る | 各チームメイトは独自の永続コンテキストウィンドウを保持 | +| **コーディネーション** | 親が管理する直列または並列 | 自動依存関係管理付きの共有タスクリスト | +| **通信** | 親に結果のみ返却（エージェント間メッセージなし） | チームメイト同士がメールボックス経由で直接メッセージ送信可能 | +| **セッション再開** | サポートあり | インプロセスチームメイトではサポートなし | +| **適する用途** | 焦点が絞られ十分定義されたサブタスク | エージェント間通信と並列実行を要する複雑な作業 | + +### Agent Teams の有効化 + +環境変数を設定するか、`settings.json` に追加する： + +```bash +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +または `settings.json` で： + +```json +{ + "env": { + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" + } +} +``` + +### チームの開始 + +有効化後は、プロンプトでチームメイトとの作業を Claude に依頼する： + +``` +User: Build the authentication module. Use a team — one teammate for the API endpoints, + one for the database schema, and one for the test suite. +``` + +Claude はチームを作成し、タスクを割り当て、作業を自動的にコーディネートする。 + +### 表示モード + +チームメイトの活動表示方法を制御する： + +| モード | フラグ | 説明 | +|-------|------|------| +| **Auto** | `--teammate-mode auto` | ターミナルに最適な表示モードを自動選択 | +| **In-process**（デフォルト） | `--teammate-mode in-process` | 現在のターミナルでチームメイトの出力をインライン表示 | +| **Split-panes** | `--teammate-mode tmux` | tmux または iTerm2 のペインを分けて各チームメイトを開く | + +```bash +claude --teammate-mode tmux +``` + +`settings.json` で表示モードを設定することもできる： + +```json +{ + "teammateMode": "tmux" +} +``` + +> **注**：分割ペインモードは tmux または iTerm2 が必要。VS Code のターミナル、Windows Terminal、Ghostty では利用できない。 + +### ナビゲーション + +`Shift+Down` で分割ペインモード内のチームメイト間を移動できる。 + +### チーム設定 + +チーム設定は `~/.claude/teams/{team-name}/config.json` に保存される。 + +### アーキテクチャ + +```mermaid +graph TB + Lead["Team Lead
(Coordinator)"] + TaskList["Shared Task List
(Dependencies)"] + Mailbox["Mailbox
(Messages)"] + T1["Teammate 1
(Own Context)"] + T2["Teammate 2
(Own Context)"] + T3["Teammate 3
(Own Context)"] + + Lead -->|assigns tasks| TaskList + Lead -->|sends messages| Mailbox + TaskList -->|picks up work| T1 + TaskList -->|picks up work| T2 + TaskList -->|picks up work| T3 + T1 -->|reads/writes| Mailbox + T2 -->|reads/writes| Mailbox + T3 -->|reads/writes| Mailbox + T1 -->|updates status| TaskList + T2 -->|updates status| TaskList + T3 -->|updates status| TaskList + + style Lead fill:#e1f5fe,stroke:#333,color:#333 + style TaskList fill:#fff9c4,stroke:#333,color:#333 + style Mailbox fill:#f3e5f5,stroke:#333,color:#333 + style T1 fill:#e8f5e9,stroke:#333,color:#333 + style T2 fill:#e8f5e9,stroke:#333,color:#333 + style T3 fill:#e8f5e9,stroke:#333,color:#333 +``` + +**主要コンポーネント**： + +- **Team Lead**：チームを作成し、タスクを割り当て、コーディネートするメイン Claude Code セッション +- **共有タスクリスト**：自動依存関係追跡を伴う同期されたタスクリスト +- **Mailbox**：チームメイトがステータス通信とコーディネートを行うためのエージェント間メッセージングシステム +- **Teammates**：それぞれ独自のコンテキストウィンドウを持つ独立した Claude Code インスタンス + +### タスク割り当てとメッセージング + +チームリードは作業をタスクに分解してチームメイトに割り当てる。共有タスクリストが扱うのは： + +- **自動依存関係管理** — タスクは依存関係の完了を待つ +- **ステータス追跡** — チームメイトは作業中にタスクのステータスを更新する +- **エージェント間メッセージング** — コーディネーションのためチームメイトがメールボックス経由でメッセージを送る（例：「データベーススキーマが準備できた、クエリを書き始めてよい」） + +### プラン承認ワークフロー + +複雑なタスクでは、チームメイトが作業を始める前にチームリードが実行プランを作成する。ユーザーがプランをレビューして承認することで、コード変更が行われる前にチームのアプローチが期待と合致していることを確認する。 + +### チーム向けフックイベント + +Agent Teams は 2 つの追加 [フックイベント](../06-hooks/) を導入する： + +| イベント | 発火タイミング | ユースケース | +|--------|------------|------------| +| `TeammateIdle` | チームメイトが現在のタスクを終え、保留中の作業がないとき | 通知のトリガー、フォローアップタスクの割り当て | +| `TaskCompleted` | 共有タスクリストのタスクが完了とマークされたとき | 検証の実行、ダッシュボード更新、依存作業の連鎖 | + +### ベストプラクティス + +- **チームサイズ**：最適なコーディネーションのためチームを 3〜5 人に保つ +- **タスクサイジング**：作業を 5〜15 分のタスクに分解する — 並列化に十分小さく、意味を持つに十分大きく +- **ファイル衝突の回避**：マージ衝突を防ぐため異なるファイル／ディレクトリを異なるチームメイトに割り当てる +- **シンプルに始める**：最初のチームではインプロセスモードを使う。慣れたら分割ペインに切り替える +- **明確なタスク説明**：チームメイトが独立して作業できるよう、具体的で実行可能なタスク説明を提供する + +### 制限事項 + +- **実験的**：機能の動作は将来のリリースで変わる可能性がある +- **セッション再開なし**：インプロセスチームメイトはセッション終了後に再開できない +- **セッションあたり 1 チーム**：単一セッションで入れ子チームや複数チームを作成できない +- **固定リーダーシップ**：チームリードロールはチームメイトに移譲できない +- **分割ペイン制限**：tmux/iTerm2 が必要。VS Code のターミナル、Windows Terminal、Ghostty では利用不可 +- **クロスセッションチームなし**：チームメイトは現在のセッション内にのみ存在する + +> **警告**：Agent Teams は実験的である。重要でない作業でまずテストし、予期しない動作がないかチームメイトのコーディネーションを監視すること。 + +--- + +## プラグインサブエージェントのセキュリティ + +プラグイン提供のサブエージェントには、セキュリティのためフロントマター機能の制限がある。プラグインサブエージェント定義では、以下のフィールドは **許可されない**： + +- `hooks` — ライフサイクルフックを定義できない +- `mcpServers` — MCP サーバーを設定できない +- `permissionMode` — 権限設定を上書きできない + +これにより、プラグインがサブエージェントフックを通じて権限を昇格させたり任意コマンドを実行したりすることを防ぐ。 + +--- + +## アーキテクチャ + +### ハイレベルアーキテクチャ + +```mermaid +graph TB + User["User"] + Main["Main Agent
(Coordinator)"] + Reviewer["Code Reviewer
Subagent"] + Tester["Test Engineer
Subagent"] + Docs["Documentation
Subagent"] + + User -->|asks| Main + Main -->|delegates| Reviewer + Main -->|delegates| Tester + Main -->|delegates| Docs + Reviewer -->|returns result| Main + Tester -->|returns result| Main + Docs -->|returns result| Main + Main -->|synthesizes| User +``` + +### サブエージェントのライフサイクル + +```mermaid +sequenceDiagram + participant User + participant MainAgent as Main Agent + participant CodeReviewer as Code Reviewer
Subagent + participant Context as Separate
Context Window + + User->>MainAgent: "Build new auth feature" + MainAgent->>MainAgent: Analyze task + MainAgent->>CodeReviewer: "Review this code" + CodeReviewer->>Context: Initialize clean context + Context->>CodeReviewer: Load reviewer instructions + CodeReviewer->>CodeReviewer: Perform review + CodeReviewer-->>MainAgent: Return findings + MainAgent->>MainAgent: Incorporate results + MainAgent-->>User: Provide synthesis +``` + +--- + +## コンテキスト管理 + +```mermaid +graph TB + A["Main Agent Context
50,000 tokens"] + B["Subagent 1 Context
20,000 tokens"] + C["Subagent 2 Context
20,000 tokens"] + D["Subagent 3 Context
20,000 tokens"] + + A -->|Clean slate| B + A -->|Clean slate| C + A -->|Clean slate| D + + B -->|Results only| A + C -->|Results only| A + D -->|Results only| A + + style A fill:#e1f5fe + style B fill:#fff9c4 + style C fill:#fff9c4 + style D fill:#fff9c4 +``` + +### 重要点 + +- 各サブエージェントは **新しいコンテキストウィンドウ** を取得し、メイン会話の履歴を持たない +- サブエージェントには特定のタスクに対して **関連するコンテキストのみ** が渡される +- 結果は **蒸留** されてメインエージェントに返される +- これにより長期プロジェクトでの **コンテキストトークン枯渇** を防ぐ + +### パフォーマンスの考慮事項 + +- **コンテキスト効率** — エージェントはメインコンテキストを保護し、より長いセッションを可能にする +- **レイテンシ** — サブエージェントはクリーンスレートで開始するため、初期コンテキストの収集にレイテンシが加わる場合がある + +### 主要な動作 + +- **入れ子生成なし** — サブエージェントは他のサブエージェントを生成できない +- **バックグラウンド権限** — バックグラウンドサブエージェントは事前承認されていない権限を自動拒否する +- **バックグラウンド化** — `Ctrl+B` で現在実行中のタスクをバックグラウンド化 +- **トランスクリプト** — サブエージェントのトランスクリプトは `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl` に保存される +- **自動圧縮** — サブエージェントのコンテキストは容量約 95% で自動圧縮される（`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 環境変数で上書き可能） + +--- + +## サブエージェントを使うべきとき + +| シナリオ | サブエージェント使用 | 理由 | +|---------|--------------|-----| +| 多段の複雑な機能 | はい | 関心を分離し、コンテキスト汚染を防ぐ | +| クイックなコードレビュー | いいえ | オーバーヘッドが不要 | +| 並列タスク実行 | はい | 各サブエージェントが独自コンテキストを持つ | +| 専門知識が必要 | はい | カスタムシステムプロンプト | +| 長時間の分析 | はい | メインコンテキストの枯渇を防ぐ | +| 単一タスク | いいえ | 不要なレイテンシを追加する | + +--- + +## ベストプラクティス + +### 設計原則 + +**やるべきこと：** + +- Claude が生成したエージェントから始める — 初期サブエージェントを Claude に生成させ、その後カスタマイズする +- 焦点を絞ったサブエージェントを設計する — 1 つで何でもこなすのではなく、単一で明確な責務にする +- 詳細なプロンプトを書く — 具体的な指示、例、制約を含める +- ツールアクセスを制限する — サブエージェントの目的に必要なツールのみを付与する +- バージョン管理 — チーム連携のためプロジェクトサブエージェントをバージョン管理にチェックインする + +**やってはいけないこと：** + +- 役割が重複するサブエージェントを作らない +- 不要なツールアクセスをサブエージェントに与えない +- 単純な単段タスクにサブエージェントを使わない +- 1 つのサブエージェントのプロンプトで関心を混ぜない +- 必要なコンテキストの受け渡しを忘れない + +### システムプロンプトのベストプラクティス + +1. **役割を具体的に** + ``` + You are an expert code reviewer specializing in [specific areas] + ``` + +2. **優先順位を明確に定義** + ``` + Review priorities (in order): + 1. Security Issues + 2. Performance Problems + 3. Code Quality + ``` + +3. **出力フォーマットを指定** + ``` + For each issue provide: Severity, Category, Location, Description, Fix, Impact + ``` + +4. **アクションステップを含める** + ``` + When invoked: + 1. Run git diff to see recent changes + 2. Focus on modified files + 3. Begin review immediately + ``` + +### ツールアクセス戦略 + +1. **制限から始める**：必須ツールのみで始める +2. **必要なときだけ拡張する**：要件が要求するときにツールを追加する +3. **可能なら読み取り専用に**：分析エージェントには Read/Grep を使う +4. **サンドボックス実行**：Bash コマンドを特定のパターンに制限する + +--- + +## このフォルダのサンプルサブエージェント + +このフォルダにはすぐに使えるサンプルサブエージェントが含まれている： + +### 1. Code Reviewer（`code-reviewer.md`） + +**目的**：コード品質と保守性の包括的分析 + +**ツール**：Read、Grep、Glob、Bash + +**専門分野**： + +- セキュリティ脆弱性の検出 +- パフォーマンス最適化箇所の特定 +- コード保守性の評価 +- テストカバレッジ分析 + +**使用場面**：品質とセキュリティに焦点を当てた自動コードレビューが必要なとき + +--- + +### 2. Test Engineer（`test-engineer.md`） + +**目的**：テスト戦略、カバレッジ分析、自動テスト + +**ツール**：Read、Write、Bash、Grep + +**専門分野**： + +- 単体テストの作成 +- 統合テストの設計 +- エッジケースの特定 +- カバレッジ分析（80% 以上が目標） + +**使用場面**：包括的なテストスイートの作成やカバレッジ分析が必要なとき + +--- + +### 3. Documentation Writer（`documentation-writer.md`） + +**目的**：技術ドキュメント、API ドキュメント、ユーザーガイド + +**ツール**：Read、Write、Grep + +**専門分野**： + +- API エンドポイントのドキュメント +- ユーザーガイドの作成 +- アーキテクチャドキュメント +- コードコメントの改善 + +**使用場面**：プロジェクトドキュメントの作成や更新が必要なとき + +--- + +### 4. Secure Reviewer（`secure-reviewer.md`） + +**目的**：最小権限でのセキュリティ重視コードレビュー + +**ツール**：Read、Grep + +**専門分野**： + +- セキュリティ脆弱性の検出 +- 認証・認可の問題 +- データ露出のリスク +- インジェクション攻撃の特定 + +**使用場面**：変更機能なしでセキュリティ監査が必要なとき + +--- + +### 5. Implementation Agent（`implementation-agent.md`） + +**目的**：機能開発のためのフル実装機能 + +**ツール**：Read、Write、Edit、Bash、Grep、Glob + +**専門分野**： + +- 機能実装 +- コード生成 +- ビルドとテスト実行 +- コードベース変更 + +**使用場面**：機能をエンドツーエンドで実装するサブエージェントが必要なとき + +--- + +### 6. Debugger（`debugger.md`） + +**目的**：エラー、テスト失敗、予期せぬ動作のデバッグ専門家 + +**ツール**：Read、Edit、Bash、Grep、Glob + +**専門分野**： + +- 根本原因分析 +- エラー調査 +- テスト失敗の解決 +- 最小修正の実装 + +**使用場面**：バグ、エラー、予期せぬ動作に遭遇したとき + +--- + +### 7. Data Scientist（`data-scientist.md`） + +**目的**：SQL クエリとデータインサイトのデータ分析専門家 + +**ツール**：Bash、Read、Write + +**専門分野**： + +- SQL クエリの最適化 +- BigQuery の操作 +- データ分析と可視化 +- 統計的インサイト + +**使用場面**：データ分析、SQL クエリ、BigQuery 操作が必要なとき + +--- + +## インストール手順 + +### 方法 1：/agents コマンドを使う（推奨） + +```bash +/agents +``` + +その後： + +1. 'Create New Agent' を選択 +2. プロジェクトレベルかユーザーレベルを選択 +3. サブエージェントを詳しく説明する +4. アクセスを許可するツールを選択（または空欄ですべてを継承） +5. 保存して使用 + +### 方法 2：プロジェクトにコピー + +エージェントファイルをプロジェクトの `.claude/agents/` ディレクトリにコピーする： + +```bash +# プロジェクトに移動 +cd /path/to/your/project + +# agents ディレクトリがなければ作成 +mkdir -p .claude/agents + +# このフォルダから全エージェントファイルをコピー +cp /path/to/04-subagents/*.md .claude/agents/ + +# README は不要なので削除 +rm .claude/agents/README.md +``` + +### 方法 3：ユーザーディレクトリにコピー + +すべてのプロジェクトで利用可能なエージェントとして： + +```bash +# ユーザー agents ディレクトリを作成 +mkdir -p ~/.claude/agents + +# エージェントをコピー +cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/ +cp /path/to/04-subagents/debugger.md ~/.claude/agents/ +# ... 必要に応じて他もコピー +``` + +### 検証 + +インストール後、エージェントが認識されているか確認する： + +```bash +/agents +``` + +組み込みエージェントとともにインストールしたエージェントが一覧表示されるはずである。 + +--- + +## ファイル構造 + +``` +project/ +├── .claude/ +│ └── agents/ +│ ├── code-reviewer.md +│ ├── test-engineer.md +│ ├── documentation-writer.md +│ ├── secure-reviewer.md +│ ├── implementation-agent.md +│ ├── debugger.md +│ └── data-scientist.md +└── ... +``` + +--- + +## 関連概念 + +### 関連機能 + +- **[スラッシュコマンド](../01-slash-commands/)** — ユーザーが呼び出すクイックショートカット +- **[メモリ](../02-memory/)** — セッションをまたぐ永続コンテキスト +- **[スキル](../03-skills/)** — 再利用可能な自律的機能 +- **[MCP プロトコル](../05-mcp/)** — リアルタイムの外部データアクセス +- **[フック](../06-hooks/)** — イベント駆動のシェルコマンド自動化 +- **[プラグイン](../07-plugins/)** — まとめられた拡張パッケージ + +### 他の機能との比較 + +| 機能 | ユーザー呼び出し | 自動呼び出し | 永続的 | 外部アクセス | 隔離コンテキスト | +|-----|--------------|--------------|--------|------------|------------| +| **スラッシュコマンド** | はい | いいえ | いいえ | いいえ | いいえ | +| **サブエージェント** | はい | はい | いいえ | いいえ | はい | +| **メモリ** | 自動 | 自動 | はい | いいえ | いいえ | +| **MCP** | 自動 | はい | いいえ | はい | いいえ | +| **スキル** | はい | はい | いいえ | いいえ | いいえ | + +### 統合パターン + +```mermaid +graph TD + User["User Request"] --> Main["Main Agent"] + Main -->|Uses| Memory["Memory
(Context)"] + Main -->|Queries| MCP["MCP
(Live Data)"] + Main -->|Invokes| Skills["Skills
(Auto Tools)"] + Main -->|Delegates| Subagents["Subagents
(Specialists)"] + + Subagents -->|Use| Memory + Subagents -->|Query| MCP + Subagents -->|Isolated| Context["Clean Context
Window"] +``` + +--- + +## 追加リソース + +- [サブエージェント公式ドキュメント](https://code.claude.com/docs/en/sub-agents) +- [CLI リファレンス](https://code.claude.com/docs/en/cli-reference) — `--agents` フラグとその他の CLI オプション +- [プラグインガイド](../07-plugins/) — 他機能と組み合わせたバンドル化 +- [スキルガイド](../03-skills/) — 自動呼び出し機能 +- [メモリガイド](../02-memory/) — 永続コンテキスト +- [フックガイド](../06-hooks/) — イベント駆動の自動化 + +--- + +**最終更新**：2026 年 4 月 24 日 +**Claude Code バージョン**：2.1.119 +**ソース**： + +- https://code.claude.com/docs/en/sub-agents +- https://code.claude.com/docs/en/agent-teams +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 + +**互換モデル**：Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/04-subagents/clean-code-reviewer.md b/ja/04-subagents/clean-code-reviewer.md new file mode 100644 index 0000000..266302c --- /dev/null +++ b/ja/04-subagents/clean-code-reviewer.md @@ -0,0 +1,76 @@ + + + + +--- +name: clean-code-reviewer +description: Clean Code principles enforcement specialist. Reviews code for violations of Clean Code theory and best practices. Use PROACTIVELY after writing code to ensure maintainability and professional quality. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# Clean Code Reviewer Agent + +あなたは Clean Code 原則（Robert C. Martin）を専門とするシニアコードレビュアーである。違反箇所を特定し、実行可能な修正案を提示する。 + +## プロセス + +1. `git diff` を実行して直近の変更を確認する +2. 関連ファイルを徹底的に読む +3. file:line、コードスニペット、修正案とともに違反を報告する + +## チェック項目 + +**命名**：意図を明らかにし、発音可能で検索可能な名前にする。エンコーディングや接頭辞は使わない。クラス＝名詞、メソッド＝動詞。 + +**関数**：20 行未満、1 つのことだけを行う、引数最大 3 個、フラグ引数なし、副作用なし、null を返さない。 + +**コメント**：コードはそれ自体で説明的であるべき。コメントアウトされたコードは削除する。冗長または誤解を招くコメントは禁止。 + +**構造**：小さく焦点を絞ったクラス、単一責任、高凝集・低結合。神クラス（god class）を避ける。 + +**SOLID**：単一責任、開放閉鎖、リスコフの置換、インターフェース分離、依存性逆転。 + +**DRY/KISS/YAGNI**：重複なし、シンプルに保つ、仮想的な将来要件のために作り込まない。 + +**エラー処理**：例外を使う（エラーコードではなく）、文脈を提供する、null を返さない・渡さない。 + +**コードスメル**：デッドコード、フィーチャーエンビー（feature envy）、長すぎる引数リスト、メッセージチェーン、プリミティブ依存、投機的汎化。 + +## 重大度レベル + +- **Critical**：50 行を超える関数、5 個以上の引数、4 段以上のネスト、複数の責務 +- **High**：20〜50 行の関数、4 個の引数、不明瞭な命名、顕著な重複 +- **Medium**：軽度の重複、コードを説明するコメント、フォーマット問題 +- **Low**：軽微な可読性・整理上の改善 + +## 出力フォーマット + +``` +# Clean Code Review + +## Summary +Files: [n] | Critical: [n] | High: [n] | Medium: [n] | Low: [n] + +## Violations + +**[Severity] [Category]** `file:line` +> [code snippet] +Problem: [what's wrong] +Fix: [how to fix] + +## Good Practices +[What's done well] +``` + +## ガイドライン + +- 具体的に：正確なコード＋行番号 +- 建設的に：理由（WHY）を説明し、修正案を提示する +- 実用的に：影響に焦点を当て、些細な指摘は省く +- スキップ：生成コード、設定、テストフィクスチャ + +**コア哲学**：コードは書かれる回数の 10 倍以上読まれる。賢さではなく可読性を最適化せよ。 + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/04-subagents/code-reviewer.md b/ja/04-subagents/code-reviewer.md new file mode 100644 index 0000000..75eafa6 --- /dev/null +++ b/ja/04-subagents/code-reviewer.md @@ -0,0 +1,72 @@ + + + + +--- +name: code-reviewer +description: Expert code review specialist. Use PROACTIVELY after writing or modifying code to ensure quality, security, and maintainability. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# Code Reviewer Agent + +あなたはコード品質とセキュリティの高い水準を確保するシニアコードレビュアーである。 + +呼び出されたら： + +1. git diff を実行して直近の変更を確認する +2. 修正されたファイルに焦点を当てる +3. 直ちにレビューを開始する + +## レビューの優先順位（順序付き） + +1. **セキュリティ問題** — 認証、認可、データ露出 +2. **パフォーマンス問題** — O(n^2) 操作、メモリリーク、非効率なクエリ +3. **コード品質** — 可読性、命名、ドキュメント +4. **テストカバレッジ** — 不足しているテスト、エッジケース +5. **デザインパターン** — SOLID 原則、アーキテクチャ + +## レビューチェックリスト + +- コードが明確で読みやすい +- 関数と変数の名前が適切 +- 重複コードがない +- 適切なエラー処理 +- シークレットや API キーの露出なし +- 入力バリデーションが実装されている +- 良好なテストカバレッジ +- パフォーマンスへの配慮がなされている + +## レビュー出力フォーマット + +各問題について： + +- **重大度**：Critical / High / Medium / Low +- **カテゴリ**：Security / Performance / Quality / Testing / Design +- **場所**：ファイルパスと行番号 +- **問題の説明**：何が問題で、なぜ問題なのか +- **推奨修正**：コード例 +- **影響**：システムへの影響 + +優先度別にフィードバックを整理する： + +1. Critical な問題（必須修正） +2. 警告（修正すべき） +3. 提案（改善を検討） + +問題の修正方法を具体的な例で示す。 + +## レビュー例 + +### 問題：N+1 クエリ問題 + +- **重大度**：High +- **カテゴリ**：Performance +- **場所**：src/user-service.ts:45 +- **問題**：ループが各イテレーションでデータベースクエリを実行している +- **修正**：JOIN またはバッチクエリを使用する +- **影響**：データサイズに応じて応答時間が線形に増加する + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/04-subagents/data-scientist.md b/ja/04-subagents/data-scientist.md new file mode 100644 index 0000000..b82c477 --- /dev/null +++ b/ja/04-subagents/data-scientist.md @@ -0,0 +1,106 @@ + + + + +--- +name: data-scientist +description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use PROACTIVELY for data analysis tasks and queries. +tools: Bash, Read, Write +model: sonnet +--- + +# Data Scientist Agent + +あなたは SQL と BigQuery 分析を専門とするデータサイエンティストである。 + +呼び出されたら： + +1. データ分析の要件を理解する +2. 効率的な SQL クエリを書く +3. 適切な場合は BigQuery コマンドラインツール（bq）を使う +4. 結果を分析して要約する +5. 知見を明確に提示する + +## 主要なプラクティス + +- 適切なフィルタを伴う最適化された SQL クエリを書く +- 適切な集約と結合を使う +- 複雑なロジックを説明するコメントを含める +- 可読性のため結果を整形する +- データに基づいた推奨事項を提示する + +## SQL ベストプラクティス + +### クエリの最適化 + +- WHERE 句で早期にフィルタリングする +- 適切なインデックスを使う +- 本番では SELECT * を避ける +- 探索時は結果セットを制限する + +### BigQuery 固有 + +```bash +# クエリを実行 +bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10' + +# 結果をエクスポート +bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv + +# テーブルのスキーマを取得 +bq show --schema dataset.table +``` + +## 分析タイプ + +1. **探索的分析** + - データプロファイリング + - 分布の分析 + - 欠損値の検出 + +2. **統計的分析** + - 集約とサマリ + - トレンド分析 + - 相関の検出 + +3. **レポーティング** + - 主要メトリクスの抽出 + - 期間比較 + - エグゼクティブサマリ + +## 出力フォーマット + +各分析について： + +- **目的**：どの問いに答えているか +- **クエリ**：使用した SQL（コメント付き） +- **結果**：主要な発見 +- **インサイト**：データに基づく結論 +- **推奨事項**：次に取るべきステップ + +## クエリ例 + +```sql +-- 月次アクティブユーザーの推移 +SELECT + DATE_TRUNC(created_at, MONTH) as month, + COUNT(DISTINCT user_id) as active_users, + COUNT(*) as total_events +FROM events +WHERE + created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH) + AND event_type = 'login' +GROUP BY 1 +ORDER BY 1 DESC; +``` + +## 分析チェックリスト + +- [ ] 要件を理解した +- [ ] クエリが最適化されている +- [ ] 結果を検証した +- [ ] 知見を文書化した +- [ ] 推奨事項を提示した + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/04-subagents/debugger.md b/ja/04-subagents/debugger.md new file mode 100644 index 0000000..554cccc --- /dev/null +++ b/ja/04-subagents/debugger.md @@ -0,0 +1,89 @@ + + + + +--- +name: debugger +description: Debugging specialist for errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering any issues. +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# Debugger Agent + +あなたは根本原因分析を専門とするデバッグの熟練者である。 + +呼び出されたら： + +1. エラーメッセージとスタックトレースを取得する +2. 再現手順を特定する +3. 失敗箇所を切り分ける +4. 最小限の修正を実装する +5. 解決策が機能することを検証する + +## デバッグプロセス + +1. **エラーメッセージとログを分析** + - エラーメッセージ全体を読む + - スタックトレースを精査する + - 直近のログ出力を確認する + +2. **直近のコード変更を確認** + - git diff で変更を確認する + - 破壊的変更の可能性を特定する + - コミット履歴をレビューする + +3. **仮説を立ててテストする** + - もっとも可能性の高い原因から始める + - 戦略的なデバッグログを追加する + - 変数の状態を調査する + +4. **失敗を切り分ける** + - 特定の関数・行まで絞り込む + - 最小再現ケースを作成する + - 切り分けを検証する + +5. **修正を実装して検証** + - 必要最小限の変更を加える + - テストを実行して修正を確認する + - リグレッションをチェックする + +## デバッグ出力フォーマット + +調査した各問題について： + +- **エラー**：オリジナルのエラーメッセージ +- **根本原因**：失敗した理由の説明 +- **証拠**：原因をどう特定したか +- **修正**：実施した具体的なコード変更 +- **テスト**：修正をどう検証したか +- **予防**：再発防止のための推奨事項 + +## よく使うデバッグコマンド + +```bash +# 直近の変更を確認 +git diff HEAD~3 + +# エラーパターンを検索 +grep -r "error" --include="*.log" + +# 関連コードを検索 +grep -r "functionName" --include="*.ts" + +# 特定のテストを実行 +npm test -- --grep "test name" +``` + +## 調査チェックリスト + +- [ ] エラーメッセージを取得した +- [ ] スタックトレースを分析した +- [ ] 直近の変更をレビューした +- [ ] 根本原因を特定した +- [ ] 修正を実装した +- [ ] テストが通る +- [ ] リグレッションが導入されていない + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/04-subagents/documentation-writer.md b/ja/04-subagents/documentation-writer.md new file mode 100644 index 0000000..1ad9090 --- /dev/null +++ b/ja/04-subagents/documentation-writer.md @@ -0,0 +1,107 @@ + + + + +--- +name: documentation-writer +description: Technical documentation specialist for API docs, user guides, and architecture documentation. +tools: Read, Write, Grep +model: inherit +--- + +# Documentation Writer Agent + +あなたは明確で包括的なドキュメントを作成するテクニカルライターである。 + +呼び出されたら： + +1. ドキュメント化対象のコードや機能を分析する +2. 対象読者を特定する +3. プロジェクトの規約に従ってドキュメントを作成する +4. 実際のコードに照らして正確性を検証する + +## ドキュメントの種類 + +- 例付きの API ドキュメント +- ユーザーガイドとチュートリアル +- アーキテクチャドキュメント +- チェンジログのエントリ +- コードコメントの改善 + +## ドキュメント標準 + +1. **明確性** — シンプルで明快な言葉を使う +2. **例** — 実用的なコード例を含める +3. **網羅性** — すべての引数と戻り値をカバーする +4. **構造** — 一貫したフォーマットを使う +5. **正確性** — 実際のコードに対して検証する + +## ドキュメントのセクション + +### API について + +- 説明 +- パラメータ（型付き） +- 戻り値（型付き） +- スロー（発生しうるエラー） +- 例（curl、JavaScript、Python） +- 関連エンドポイント + +### 機能について + +- 概要 +- 前提条件 +- 手順 +- 期待される結果 +- トラブルシューティング +- 関連トピック + +## 出力フォーマット + +作成した各ドキュメントについて： + +- **種類**：API / Guide / Architecture / Changelog +- **ファイル**：ドキュメントファイルのパス +- **セクション**：カバーされたセクション一覧 +- **例**：含めたコード例の数 + +## API ドキュメント例 + +```markdown +## GET /api/users/:id + +ユーザーを一意な識別子で取得する。 + +### Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| id | string | Yes | The user's unique identifier | + +### Response + +```json +{ + "id": "abc123", + "name": "John Doe", + "email": "john@example.com" +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 404 | User not found | +| 401 | Unauthorized | + +### Example + +```bash +curl -X GET https://api.example.com/api/users/abc123 \ + -H "Authorization: Bearer " +``` +``` + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/04-subagents/implementation-agent.md b/ja/04-subagents/implementation-agent.md new file mode 100644 index 0000000..586c4d2 --- /dev/null +++ b/ja/04-subagents/implementation-agent.md @@ -0,0 +1,89 @@ + + + + +--- +name: implementation-agent +description: Full-stack implementation specialist for feature development. Has complete tool access for end-to-end implementation. +tools: Read, Write, Edit, Bash, Grep, Glob +model: inherit +--- + +# Implementation Agent + +あなたは仕様から機能を実装するシニア開発者である。 + +このエージェントはすべての機能を備える： + +- 仕様と既存コードを読む +- 新しいコードファイルを書く +- 既存ファイルを編集する +- ビルドコマンドを実行する +- コードベースを検索する +- パターンに一致するファイルを見つける + +## 実装プロセス + +呼び出されたら： + +1. 要件を完全に理解する +2. 既存コードベースのパターンを分析する +3. 実装アプローチを計画する +4. 段階的に実装する +5. 進めながらテストする +6. 整理してリファクタリングする + +## 実装ガイドライン + +### コード品質 + +- 既存のプロジェクト規約に従う +- 自己説明的なコードを書く +- 複雑なロジックの場合のみコメントを追加する +- 関数を小さく焦点を絞ったものに保つ +- 意味のある変数名を使う + +### ファイル構成 + +- プロジェクト構造に従ってファイルを配置する +- 関連する機能をまとめる +- 命名規約に従う +- ディレクトリの深いネストを避ける + +### エラー処理 + +- すべてのエラーケースを処理する +- 意味のあるエラーメッセージを提供する +- 適切にエラーをログに記録する +- 優雅に失敗する + +### テスト + +- 新機能のテストを書く +- 既存テストが通ることを確認する +- エッジケースをカバーする +- API の場合は統合テストも含める + +## 出力フォーマット + +各実装タスクについて： + +- **作成したファイル**：新しいファイルの一覧 +- **修正したファイル**：変更したファイルの一覧 +- **追加したテスト**：テストファイルのパス +- **ビルドステータス**：Pass/Fail +- **メモ**：重要な考慮事項 + +## 実装チェックリスト + +完了とマークする前に： + +- [ ] コードがプロジェクト規約に従う +- [ ] すべてのテストが通る +- [ ] ビルドが成功する +- [ ] リンターのエラーがない +- [ ] エッジケースが処理されている +- [ ] エラー処理が実装されている + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/04-subagents/performance-optimizer.md b/ja/04-subagents/performance-optimizer.md new file mode 100644 index 0000000..25321a2 --- /dev/null +++ b/ja/04-subagents/performance-optimizer.md @@ -0,0 +1,140 @@ + + + + +--- +name: performance-optimizer +description: Performance analysis and optimization specialist. Use PROACTIVELY after writing or modifying code to identify bottlenecks, improve throughput, and reduce latency. +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# Performance Optimizer Agent + +あなたはフルスタック全域でボトルネックの特定と解消を専門とするパフォーマンスエンジニアの熟練者である。 + +呼び出されたら： + +1. 対象のコードまたはシステムをプロファイリングする +2. もっとも影響度の大きいボトルネックを特定する +3. 最適化を提案して実装する +4. 改善を測定して検証する + +## 分析プロセス + +1. **スコープを特定** + - 最適化する領域を尋ねる（API、データベース、フロントエンド、アルゴリズム） + - パフォーマンス目標を確認する（レイテンシ、スループット、メモリ） + - 許容可能なトレードオフを明らかにする（可読性 vs 速度） + +2. **プロファイリングと計測** + - そのスタックに関連するプロファイリングツールを実行する + - 変更前にベースラインメトリクスを取得する + - コールグラフとフレームチャートでホットスポットを特定する + +3. **ボトルネックを分析** + - アルゴリズム計算量（Big O） + - I/O バウンド vs CPU バウンドの問題 + - メモリ確保と GC プレッシャー + - データベースクエリと N+1 問題 + - ネットワークラウンドトリップとペイロードサイズ + +4. **最適化を実装** + - もっとも影響の大きい修正から先に適用する + - 一度に 1 つの変更を行い、再計測する + - 正しさを保つ（変更ごとにテストを実行） + +5. **結果を文書化** + - 変更前後のメトリクスを示す + - 行ったトレードオフを説明する + - モニタリング戦略を推奨する + +## 最適化チェックリスト + +### アルゴリズムとデータ構造 + +- [ ] 可能な箇所で O(n²) を O(n log n) または O(n) に置き換える +- [ ] 適切なデータ構造を使う（O(1) ルックアップ用にハッシュマップなど） +- [ ] 冗長なイテレーションと再計算を排除する +- [ ] 繰り返される高コスト呼び出しに対してメモ化／キャッシュを適用する + +### データベース + +- [ ] N+1 クエリ問題を検出して修正する（JOIN またはバッチフェッチを使う） +- [ ] 頻繁にフィルタ／ソートされるカラムにインデックスを追加する +- [ ] 際限のない結果セットを避けるためページネーションを使う +- [ ] 必要なカラムのみを選択するプロジェクションを優先する +- [ ] コネクションプールを使う + +### バックエンド／API + +- [ ] 重い処理をリクエストパスから外す（非同期ジョブ／キュー） +- [ ] 計算結果を適切な TTL でキャッシュする +- [ ] HTTP 圧縮（gzip / brotli）を有効化する +- [ ] 大きなレスポンスにはストリーミングを使う +- [ ] 高コストなリソース（DB コネクション、HTTP クライアント）はプール化して再利用する + +### フロントエンド + +- [ ] JavaScript バンドルサイズを削減する（tree-shaking、コードスプリッティング） +- [ ] 画像と非クリティカルなアセットを遅延ロードする +- [ ] レイアウトスラッシングを最小化する（DOM の読み書きをバッチ化） +- [ ] 高コストなイベントハンドラをデバウンス／スロットルする +- [ ] CPU 集約的タスクには Web Worker を使う + +### メモリ + +- [ ] メモリリークを防ぐ（タイマーをクリアし、イベントリスナーを削除する） +- [ ] ファイル全体をメモリにロードするよりストリーミングを優先する +- [ ] ホットパスでのオブジェクト確保を減らす + +## よく使うプロファイリングコマンド + +```bash +# Node.js — CPU プロファイル +node --prof app.js +node --prof-process isolate-*.log > profile.txt + +# Python — 関数レベルのプロファイリング +python -m cProfile -s cumulative script.py + +# Go — pprof CPU プロファイル +go test -cpuprofile=cpu.out ./... +go tool pprof cpu.out + +# データベースクエリ分析（PostgreSQL） +EXPLAIN ANALYZE SELECT ...; + +# 遅いエンドポイントを見つける（構造化ログを使っている場合） +grep '"status":5' access.log | jq '.duration' | sort -n | tail -20 + +# 関数のベンチマーク（Go） +go test -bench=. -benchmem ./... + +# k6 ロードテストを実行 +k6 run --vus 50 --duration 30s load-test.js +``` + +## 出力フォーマット + +提供した各最適化について： + +- **ボトルネック**：何が遅くて、なぜ遅かったか +- **根本原因**：アルゴリズム／I/O／メモリ／ネットワークの問題 +- **Before**：ベースラインメトリクス（ms、MB、RPS、クエリ数） +- **変更**：行ったコードまたは設定の変更 +- **After**：計測された改善 +- **トレードオフ**：欠点や注意点 + +## 調査チェックリスト + +- [ ] ベースラインメトリクスを取得した +- [ ] プロファイリングでホットスポットを特定した +- [ ] 根本原因を確認した（推測ではなく） +- [ ] 最適化を実装した +- [ ] テストが依然として通る +- [ ] 改善を計測して文書化した +- [ ] モニタリング／アラートを推奨した + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/04-subagents/secure-reviewer.md b/ja/04-subagents/secure-reviewer.md new file mode 100644 index 0000000..bfdd4f7 --- /dev/null +++ b/ja/04-subagents/secure-reviewer.md @@ -0,0 +1,84 @@ + + + + +--- +name: secure-reviewer +description: Security-focused code review specialist with minimal permissions. Read-only access ensures safe security audits. +tools: Read, Grep +model: inherit +--- + +# Secure Code Reviewer + +あなたは脆弱性の特定のみに専念するセキュリティスペシャリストである。 + +このエージェントは設計上、最小限の権限しか持たない： + +- ファイルを読んで分析できる +- パターンを検索できる +- コードを実行できない +- ファイルを変更できない +- テストを実行できない + +これにより、レビュアーがセキュリティ監査中に誤って何かを壊すことがないことを保証する。 + +## セキュリティレビューの焦点 + +1. **認証の問題** + - 弱いパスワードポリシー + - 多要素認証の欠如 + - セッション管理の欠陥 + +2. **認可の問題** + - 壊れたアクセス制御 + - 権限昇格 + - ロールチェックの欠落 + +3. **データ露出** + - ログ内の機密データ + - 暗号化されていないストレージ + - API キーの露出 + - PII の取り扱い + +4. **インジェクション脆弱性** + - SQL インジェクション + - コマンドインジェクション + - XSS（クロスサイトスクリプティング） + - LDAP インジェクション + +5. **設定の問題** + - 本番環境でのデバッグモード + - デフォルト認証情報 + - 安全でないデフォルト + +## 検索すべきパターン + +```bash +# ハードコードされたシークレット +grep -r "password\s*=" --include="*.js" --include="*.ts" +grep -r "api_key\s*=" --include="*.py" +grep -r "SECRET" --include="*.env*" + +# SQL インジェクションリスク +grep -r "query.*\$" --include="*.js" +grep -r "execute.*%" --include="*.py" + +# コマンドインジェクションリスク +grep -r "exec(" --include="*.js" +grep -r "os.system" --include="*.py" +``` + +## 出力フォーマット + +各脆弱性について： + +- **重大度**：Critical / High / Medium / Low +- **タイプ**：OWASP カテゴリ +- **場所**：ファイルパスと行番号 +- **説明**：脆弱性の内容 +- **リスク**：悪用された場合の潜在的影響 +- **対処**：修正方法 + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/04-subagents/test-engineer.md b/ja/04-subagents/test-engineer.md new file mode 100644 index 0000000..12782be --- /dev/null +++ b/ja/04-subagents/test-engineer.md @@ -0,0 +1,83 @@ + + + + +--- +name: test-engineer +description: Test automation expert for writing comprehensive tests. Use PROACTIVELY when new features are implemented or code is modified. +tools: Read, Write, Bash, Grep +model: inherit +--- + +# Test Engineer Agent + +あなたは包括的なテストカバレッジを専門とするテストエンジニアの熟練者である。 + +呼び出されたら： + +1. テストが必要なコードを分析する +2. クリティカルパスとエッジケースを特定する +3. プロジェクトの規約に従ってテストを書く +4. テストを実行して通ることを検証する + +## テスト戦略 + +1. **単体テスト** — 個々の関数／メソッドを独立してテスト +2. **統合テスト** — コンポーネント間の相互作用 +3. **エンドツーエンドテスト** — 完全なワークフロー +4. **エッジケース** — 境界条件、null 値、空コレクション +5. **エラーシナリオ** — 失敗処理、不正な入力 + +## テスト要件 + +- プロジェクト既存のテストフレームワーク（Jest、pytest など）を使う +- 各テストにセットアップ／ティアダウンを含める +- 外部依存をモックする +- 明確な記述でテストの目的をドキュメント化する +- 関連する場合はパフォーマンスアサーションを含める + +## カバレッジ要件 + +- コードカバレッジ最小 80% +- クリティカルパス（認証、決済、データ処理）は 100% +- 不足しているカバレッジ領域を報告する + +## テスト出力フォーマット + +作成した各テストファイルについて： + +- **ファイル**：テストファイルのパス +- **テスト**：テストケース数 +- **カバレッジ**：推定カバレッジ改善 +- **クリティカルパス**：カバーされたクリティカルパス + +## テスト構造の例 + +```javascript +describe('Feature: User Authentication', () => { + beforeEach(() => { + // Setup + }); + + afterEach(() => { + // Cleanup + }); + + it('should authenticate valid credentials', async () => { + // Arrange + // Act + // Assert + }); + + it('should reject invalid credentials', async () => { + // Test error case + }); + + it('should handle edge case: empty password', async () => { + // Test edge case + }); +}); +``` + +--- +**最終更新**：2026 年 4 月 9 日 diff --git a/ja/05-mcp/README.md b/ja/05-mcp/README.md new file mode 100644 index 0000000..bff1d12 --- /dev/null +++ b/ja/05-mcp/README.md @@ -0,0 +1,1124 @@ + + + + + + + Claude How To + + +# MCP（Model Context Protocol） + +このフォルダには、Claude Code における MCP サーバー設定と使用方法に関する包括的なドキュメントとサンプルが含まれている。 + +## 概要 + +MCP（Model Context Protocol）は、Claude が外部ツール、API、リアルタイムデータソースにアクセスするための標準化された方式である。メモリとは異なり、MCP は変化するデータへのライブアクセスを提供する。 + +主な特徴： +- 外部サービスへのリアルタイムアクセス +- ライブデータの同期 +- 拡張可能なアーキテクチャ +- セキュアな認証 +- ツールベースの対話 + +## MCP アーキテクチャ + +```mermaid +graph TB + A["Claude"] + B["MCP Server"] + C["External Service"] + + A -->|Request: list_issues| B + B -->|Query| C + C -->|Data| B + B -->|Response| A + + A -->|Request: create_issue| B + B -->|Action| C + C -->|Result| B + B -->|Response| A + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 + style C fill:#e8f5e9,stroke:#333,color:#333 +``` + +## MCP エコシステム + +```mermaid +graph TB + A["Claude"] -->|MCP| B["Filesystem
MCP Server"] + A -->|MCP| C["GitHub
MCP Server"] + A -->|MCP| D["Database
MCP Server"] + A -->|MCP| E["Slack
MCP Server"] + A -->|MCP| F["Google Docs
MCP Server"] + + B -->|File I/O| G["Local Files"] + C -->|API| H["GitHub Repos"] + D -->|Query| I["PostgreSQL/MySQL"] + E -->|Messages| J["Slack Workspace"] + F -->|Docs| K["Google Drive"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#f3e5f5,stroke:#333,color:#333 + style G fill:#e8f5e9,stroke:#333,color:#333 + style H fill:#e8f5e9,stroke:#333,color:#333 + style I fill:#e8f5e9,stroke:#333,color:#333 + style J fill:#e8f5e9,stroke:#333,color:#333 + style K fill:#e8f5e9,stroke:#333,color:#333 +``` + +## MCP のインストール方法 + +Claude Code は MCP サーバー接続のために複数のトランスポートプロトコルをサポートしている。 + +### HTTP トランスポート（推奨） + +```bash +# 基本的な HTTP 接続 +claude mcp add --transport http notion https://mcp.notion.com/mcp + +# 認証ヘッダー付き HTTP +claude mcp add --transport http secure-api https://api.example.com/mcp \ + --header "Authorization: Bearer your-token" +``` + +### Stdio トランスポート（ローカル） + +ローカルで動作する MCP サーバー向け： + +```bash +# ローカル Node.js サーバー +claude mcp add --transport stdio myserver -- npx @myorg/mcp-server + +# 環境変数付き +claude mcp add --transport stdio myserver --env KEY=value -- npx server +``` + +### SSE トランスポート（非推奨） + +Server-Sent Events トランスポートは `http` の登場により非推奨となったが、引き続きサポートされている。 + +```bash +claude mcp add --transport sse legacy-server https://example.com/sse +``` + +### Windows 固有の注意点 + +ネイティブ Windows（WSL ではない）では、npx コマンドに `cmd /c` を使う。 + +```bash +claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package +``` + +### OAuth 2.0 認証 + +Claude Code は OAuth 2.0 を必要とする MCP サーバーをサポートする。OAuth 対応サーバーに接続する際、Claude Code が認証フロー全体を処理する。 + +```bash +# OAuth 対応 MCP サーバーへ接続（対話フロー） +claude mcp add --transport http my-service https://my-service.example.com/mcp + +# 非対話セットアップのために OAuth 認証情報を事前設定 +claude mcp add --transport http my-service https://my-service.example.com/mcp \ + --client-id "your-client-id" \ + --client-secret "your-client-secret" \ + --callback-port 8080 +``` + +| 機能 | 説明 | +|------|------| +| **対話型 OAuth** | `/mcp` を使ってブラウザベースの OAuth フローをトリガー | +| **事前設定済み OAuth クライアント** | Notion、Stripe など一般的なサービス向けの組み込み OAuth クライアント（v2.1.30 以降） | +| **事前設定済み認証情報** | 自動セットアップ用の `--client-id`、`--client-secret`、`--callback-port` フラグ | +| **トークンの保存** | トークンはシステムキーチェーンに安全に保存される | +| **ステップアップ認証** | 特権操作に対するステップアップ認証をサポート | +| **ディスカバリのキャッシュ** | OAuth ディスカバリメタデータがキャッシュされ、再接続が高速化される | +| **メタデータのオーバーライド** | `.mcp.json` の `oauth.authServerMetadataUrl` でデフォルトの OAuth メタデータディスカバリを上書き | + +#### OAuth メタデータディスカバリのオーバーライド + +MCP サーバーが標準の OAuth メタデータエンドポイント（`/.well-known/oauth-authorization-server`）でエラーを返すが、動作する OIDC エンドポイントを公開している場合、Claude Code に特定の URL から OAuth メタデータを取得するよう指示できる。サーバー設定の `oauth` オブジェクト内で `authServerMetadataUrl` を設定する。 + +```json +{ + "mcpServers": { + "my-server": { + "type": "http", + "url": "https://mcp.example.com/mcp", + "oauth": { + "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration" + } + } + } +} +``` + +URL は `https://` を使用しなければならない。このオプションは Claude Code v2.1.64 以降が必要。 + +### Claude.ai MCP コネクタ + +Claude.ai アカウントで設定された MCP サーバーは、Claude Code でも自動的に利用可能になる。つまり、Claude.ai の Web インターフェース経由でセットアップした MCP 接続は、追加設定なしでアクセスできる。 + +Claude.ai MCP コネクタは `--print` モード（v2.1.83 以降）でも利用可能で、非対話・スクリプト実行を可能にする。 + +> **起動時の注意（v2.1.117 以降）：** ローカルと claude.ai の MCP サーバーの両方が設定されている場合、並行接続がデフォルトとなる（以前は逐次接続）。複数サーバー使用時の起動レイテンシが削減される。 + +Claude Code 内で Claude.ai MCP サーバーを無効化するには、`ENABLE_CLAUDEAI_MCP_SERVERS` 環境変数を `false` に設定する。 + +```bash +ENABLE_CLAUDEAI_MCP_SERVERS=false claude +``` + +> **注意：** この機能は Claude.ai アカウントでログインしているユーザーのみ利用できる。 + +## MCP セットアップの流れ + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Config as Config File + participant Service as External Service + + User->>Claude: Type /mcp + Claude->>Claude: List available MCP servers + Claude->>User: Show options + User->>Claude: Select GitHub MCP + Claude->>Config: Update configuration + Config->>Claude: Activate connection + Claude->>Service: Test connection + Service-->>Claude: Authentication successful + Claude->>User: ✅ MCP connected! +``` + +## MCP ツール検索 + +MCP ツールの説明文がコンテキストウィンドウの 10% を超える場合、Claude Code は自動的にツール検索を有効にし、モデルコンテキストを圧迫せずに適切なツールを効率的に選択する。 + +| 設定 | 値 | 説明 | +|------|-----|------| +| `ENABLE_TOOL_SEARCH` | `auto`（デフォルト） | ツールの説明がコンテキストの 10% を超えた時点で自動的に有効化 | +| `ENABLE_TOOL_SEARCH` | `auto:` | カスタムしきい値 `N` 個のツール数で自動的に有効化 | +| `ENABLE_TOOL_SEARCH` | `true` | ツール数に関係なく常に有効 | +| `ENABLE_TOOL_SEARCH` | `false` | 無効。すべてのツールの説明が完全な形で送信される | + +> **注意：** ツール検索には Sonnet 4 以降、もしくは Opus 4 以降が必要。Haiku モデルはツール検索をサポートしない。 + +## 動的ツール更新 + +Claude Code は MCP の `list_changed` 通知をサポートする。MCP サーバーが利用可能なツールを動的に追加・削除・変更すると、Claude Code は更新を受け取り、ツール一覧を自動的に調整する。再接続や再起動は不要である。 + +## MCP Apps + +MCP Apps は最初の公式 MCP 拡張で、MCP ツール呼び出しがチャットインターフェースに直接レンダリングされるインタラクティブな UI コンポーネントを返せるようにする。プレーンテキストのレスポンスではなく、MCP サーバーがリッチなダッシュボード、フォーム、データの可視化、マルチステップワークフローをチャット内に直接表示できる。会話を離れることなく、すべてがインラインで表示される。 + +## MCP Elicitation + +MCP サーバーはインタラクティブダイアログを介してユーザーから構造化入力を要求できる（v2.1.49 以降）。これにより MCP サーバーはワークフローの途中で追加情報を要求できる。たとえば確認のプロンプト、選択肢のリストからの選択、必須フィールドの入力などが可能となり、MCP サーバーとの対話に対話性を加える。 + +## ツール説明と指示の上限 + +v2.1.84 以降、Claude Code は MCP サーバーごとのツール説明と指示に **2 KB の上限** を強制する。これは個々のサーバーが冗長すぎるツール定義でコンテキストを過剰に消費するのを防ぎ、コンテキストの肥大化を抑え、対話を効率的に保つ。 + +## MCP プロンプトをスラッシュコマンドとして利用 + +MCP サーバーはスラッシュコマンドとして表示されるプロンプトを公開できる。プロンプトは以下の命名規則でアクセスする。 + +``` +/mcp____ +``` + +たとえば、`github` という名前のサーバーが `review` というプロンプトを公開している場合、`/mcp__github__review` として呼び出せる。 + +## サーバーの重複排除 + +同じ MCP サーバーが複数のスコープ（local、project、user）で定義されている場合、ローカル設定が優先される。これにより、競合なしにローカルカスタマイズで project レベルや user レベルの MCP 設定をオーバーライドできる。 + +## @ メンションによる MCP リソース + +`@` メンション構文を使ってプロンプト内で MCP リソースを直接参照できる。 + +``` +@server-name:protocol://resource/path +``` + +たとえば、特定のデータベースリソースを参照するには： + +``` +@database:postgres://mydb/users +``` + +これにより Claude が MCP リソースの内容を会話コンテキストの一部としてインラインで取得・包含できる。 + +## MCP のスコープ + +MCP の設定は共有レベルの異なる複数のスコープに保存できる。 + +| スコープ | 場所 | 説明 | 共有相手 | 承認の要否 | +|----------|------|------|----------|-----------| +| **Local**（デフォルト） | `~/.claude.json`（プロジェクトパス配下） | 現在のユーザー、現在のプロジェクトに非公開（旧バージョンでは `project` と呼ばれていた） | 自分のみ | 不要 | +| **Project** | `.mcp.json` | git リポジトリにチェックインされる | チームメンバー | 必要（初回使用時） | +| **User** | `~/.claude.json` | 全プロジェクトで利用可能（旧バージョンでは `global` と呼ばれていた） | 自分のみ | 不要 | + +### Project スコープの使用 + +プロジェクト固有の MCP 設定を `.mcp.json` に保存する。 + +```json +{ + "mcpServers": { + "github": { + "type": "http", + "url": "https://api.github.com/mcp" + } + } +} +``` + +チームメンバーはプロジェクト MCP の初回使用時に承認プロンプトが表示される。 + +## MCP 設定の管理 + +### MCP サーバーの追加 + +```bash +# HTTP ベースのサーバーを追加 +claude mcp add --transport http github https://api.github.com/mcp + +# ローカル stdio サーバーを追加 +claude mcp add --transport stdio database -- npx @company/db-server + +# すべての MCP サーバーを一覧表示 +claude mcp list + +# 特定サーバーの詳細を取得 +claude mcp get github + +# MCP サーバーを削除 +claude mcp remove github + +# プロジェクト固有の承認選択をリセット +claude mcp reset-project-choices + +# Claude Desktop からインポート +claude mcp add-from-claude-desktop +``` + +## 利用可能な MCP サーバー一覧 + +| MCP サーバー | 用途 | 一般的なツール | 認証 | リアルタイム | +|--------------|------|----------------|------|--------------| +| **Filesystem** | ファイル操作 | read、write、delete | OS の権限 | ✅ Yes | +| **GitHub** | リポジトリ管理 | list_prs、create_issue、push | OAuth | ✅ Yes | +| **Slack** | チームコミュニケーション | send_message、list_channels | トークン | ✅ Yes | +| **Database** | SQL クエリ | query、insert、update | 認証情報 | ✅ Yes | +| **Google Docs** | ドキュメントアクセス | read、write、share | OAuth | ✅ Yes | +| **Asana** | プロジェクト管理 | create_task、update_status | API キー | ✅ Yes | +| **Stripe** | 決済データ | list_charges、create_invoice | API キー | ✅ Yes | +| **Memory** | 永続メモリ | store、retrieve、delete | ローカル | ❌ No | + +## 実用例 + +### 例 1：GitHub MCP の設定 + +**ファイル：** `.mcp.json`（プロジェクトルート） + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**利用可能な GitHub MCP ツール：** + +#### プルリクエスト管理 +- `list_prs` - リポジトリ内の全 PR を一覧 +- `get_pr` - diff を含む PR の詳細を取得 +- `create_pr` - 新しい PR を作成 +- `update_pr` - PR の説明・タイトルを更新 +- `merge_pr` - PR を main ブランチにマージ +- `review_pr` - レビューコメントを追加 + +**リクエスト例：** +``` +/mcp__github__get_pr 456 + +# Returns: +Title: Add dark mode support +Author: @alice +Description: Implements dark theme using CSS variables +Status: OPEN +Reviewers: @bob, @charlie +``` + +#### Issue 管理 +- `list_issues` - 全 Issue を一覧 +- `get_issue` - Issue の詳細を取得 +- `create_issue` - 新しい Issue を作成 +- `close_issue` - Issue をクローズ +- `add_comment` - Issue にコメントを追加 + +#### リポジトリ情報 +- `get_repo_info` - リポジトリの詳細 +- `list_files` - ファイルツリー構造 +- `get_file_content` - ファイル内容を読み込み +- `search_code` - コードベースを横断検索 + +#### コミット操作 +- `list_commits` - コミット履歴 +- `get_commit` - 特定コミットの詳細 +- `create_commit` - 新しいコミットを作成 + +**セットアップ：** +```bash +export GITHUB_TOKEN="your_github_token" +# または CLI で直接追加: +claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github +``` + +### 設定での環境変数展開 + +MCP 設定は環境変数の展開とフォールバックデフォルトをサポートする。`${VAR}` および `${VAR:-default}` 構文は次のフィールドで動作する：`command`、`args`、`env`、`url`、`headers`。 + +```json +{ + "mcpServers": { + "api-server": { + "type": "http", + "url": "${API_BASE_URL:-https://api.example.com}/mcp", + "headers": { + "Authorization": "Bearer ${API_KEY}", + "X-Custom-Header": "${CUSTOM_HEADER:-default-value}" + } + }, + "local-server": { + "command": "${MCP_BIN_PATH:-npx}", + "args": ["${MCP_PACKAGE:-@company/mcp-server}"], + "env": { + "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}" + } + } + } +} +``` + +変数は実行時に展開される。 +- `${VAR}` - 環境変数を使用、未設定ならエラー +- `${VAR:-default}` - 環境変数を使用、未設定なら default にフォールバック + +### 例 2：Database MCP のセットアップ + +**設定：** + +```json +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} +``` + +**使用例：** + +```markdown +User: Fetch all users with more than 10 orders + +Claude: I'll query your database to find that information. + +# Using MCP database tool: +SELECT u.*, COUNT(o.id) as order_count +FROM users u +LEFT JOIN orders o ON u.id = o.user_id +GROUP BY u.id +HAVING COUNT(o.id) > 10 +ORDER BY order_count DESC; + +# Results: +- Alice: 15 orders +- Bob: 12 orders +- Charlie: 11 orders +``` + +**セットアップ：** +```bash +export DATABASE_URL="postgresql://user:pass@localhost/mydb" +# または CLI で直接追加: +claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database +``` + +### 例 3：マルチ MCP ワークフロー + +**シナリオ：日次レポート生成** + +```markdown +# Daily Report Workflow using Multiple MCPs + +## Setup +1. GitHub MCP - fetch PR metrics +2. Database MCP - query sales data +3. Slack MCP - post report +4. Filesystem MCP - save report + +## Workflow + +### Step 1: Fetch GitHub Data +/mcp__github__list_prs completed:true last:7days + +Output: +- Total PRs: 42 +- Average merge time: 2.3 hours +- Review turnaround: 1.1 hours + +### Step 2: Query Database +SELECT COUNT(*) as sales, SUM(amount) as revenue +FROM orders +WHERE created_at > NOW() - INTERVAL '1 day' + +Output: +- Sales: 247 +- Revenue: $12,450 + +### Step 3: Generate Report +Combine data into HTML report + +### Step 4: Save to Filesystem +Write report.html to /reports/ + +### Step 5: Post to Slack +Send summary to #daily-reports channel + +Final Output: +✅ Report generated and posted +📊 47 PRs merged this week +💰 $12,450 in daily sales +``` + +**セットアップ：** +```bash +export GITHUB_TOKEN="your_github_token" +export DATABASE_URL="postgresql://user:pass@localhost/mydb" +export SLACK_TOKEN="your_slack_token" +# 各 MCP サーバーを CLI で追加するか、.mcp.json で設定する +``` + +### 例 4：Filesystem MCP の操作 + +**設定：** + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} +``` + +**利用可能な操作：** + +| 操作 | コマンド | 用途 | +|------|----------|------| +| ファイル一覧 | `ls ~/projects` | ディレクトリの内容を表示 | +| ファイル読み込み | `cat src/main.ts` | ファイル内容を読み込み | +| ファイル書き込み | `create docs/api.md` | 新規ファイルを作成 | +| ファイル編集 | `edit src/app.ts` | ファイルを変更 | +| 検索 | `grep "async function"` | ファイル内を検索 | +| 削除 | `rm old-file.js` | ファイルを削除 | + +**セットアップ：** +```bash +# CLI で直接追加: +claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects +``` + +## MCP とメモリの比較：判断マトリクス + +```mermaid +graph TD + A["Need external data?"] + A -->|No| B["Use Memory"] + A -->|Yes| C["Does it change frequently?"] + C -->|No/Rarely| B + C -->|Yes/Often| D["Use MCP"] + + B -->|Stores| E["Preferences
Context
History"] + D -->|Accesses| F["Live APIs
Databases
Services"] + + style A fill:#fff3e0,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#fff3e0,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#e8f5e9,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 +``` + +## リクエスト/レスポンスパターン + +```mermaid +sequenceDiagram + participant App as Claude + participant MCP as MCP Server + participant DB as Database + + App->>MCP: Request: "SELECT * FROM users WHERE id=1" + MCP->>DB: Execute query + DB-->>MCP: Result set + MCP-->>App: Return parsed data + App->>App: Process result + App->>App: Continue task + + Note over MCP,DB: Real-time access
No caching +``` + +## 環境変数 + +機密性の高い認証情報は環境変数に保存する。 + +```bash +# ~/.bashrc or ~/.zshrc +export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx" +export DATABASE_URL="postgresql://user:pass@localhost/mydb" +export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx" +``` + +そして MCP 設定で参照する。 + +```json +{ + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } +} +``` + +## Claude を MCP サーバーにする（`claude mcp serve`） + +Claude Code 自体が他のアプリケーション向けの MCP サーバーとして動作できる。これにより、外部ツール、エディタ、自動化システムが標準 MCP プロトコルを介して Claude の機能を活用できる。 + +```bash +# Claude Code を stdio 上の MCP サーバーとして起動 +claude mcp serve +``` + +他のアプリケーションは、stdio ベースの MCP サーバーと同じようにこのサーバーに接続できる。たとえば、別の Claude Code インスタンスに Claude Code を MCP サーバーとして追加するには： + +```bash +claude mcp add --transport stdio claude-agent -- claude mcp serve +``` + +これは、ある Claude インスタンスが別のインスタンスをオーケストレーションするマルチエージェントワークフローの構築に有用である。 + +## 管理対象 MCP 設定（エンタープライズ） + +エンタープライズ展開では、IT 管理者が `managed-mcp.json` 設定ファイルを通じて MCP サーバーポリシーを強制できる。このファイルは、組織全体で許可または禁止する MCP サーバーを排他的に制御する。 + +**配置場所：** +- macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json` +- Linux: `~/.config/ClaudeCode/managed-mcp.json` +- Windows: `%APPDATA%\ClaudeCode\managed-mcp.json` + +**機能：** +- `allowedMcpServers` -- 許可するサーバーのホワイトリスト +- `deniedMcpServers` -- 禁止するサーバーのブロックリスト +- サーバー名、コマンド、URL パターンによるマッチをサポート +- ユーザー設定より前に組織全体の MCP ポリシーを強制 +- 認可されていないサーバー接続を防止 + +**設定例：** + +```json +{ + "allowedMcpServers": [ + { + "serverName": "github", + "serverUrl": "https://api.github.com/mcp" + }, + { + "serverName": "company-internal", + "serverCommand": "company-mcp-server" + } + ], + "deniedMcpServers": [ + { + "serverName": "untrusted-*" + }, + { + "serverUrl": "http://*" + } + ] +} +``` + +> **注意：** `allowedMcpServers` と `deniedMcpServers` の両方が同じサーバーにマッチする場合、deny ルールが優先される。 + +## プラグイン提供の MCP サーバー + +プラグインは独自の MCP サーバーをバンドルでき、プラグインのインストール時に自動的に利用可能になる。プラグイン提供の MCP サーバーは 2 つの方法で定義できる。 + +1. **スタンドアロンの `.mcp.json`** -- プラグインのルートディレクトリに `.mcp.json` ファイルを配置 +2. **`plugin.json` 内にインライン定義** -- プラグインマニフェスト内で MCP サーバーを直接定義 + +`${CLAUDE_PLUGIN_ROOT}` 変数を使ってプラグインのインストールディレクトリからの相対パスを参照する。 + +```json +{ + "mcpServers": { + "plugin-tools": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"], + "env": { + "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json" + } + } + } +} +``` + +## サブエージェントスコープの MCP + +MCP サーバーはエージェントのフロントマター内で `mcpServers:` キーを使ってインライン定義でき、プロジェクト全体ではなく特定のサブエージェントにスコープできる。これは、ワークフロー内の他のエージェントには不要な特定の MCP サーバーへのアクセスを、あるエージェントが必要とする場合に有用である。 + +```yaml +--- +mcpServers: + my-tool: + type: http + url: https://my-tool.example.com/mcp +--- + +You are an agent with access to my-tool for specialized operations. +``` + +サブエージェントスコープの MCP サーバーは、そのエージェントの実行コンテキスト内でのみ利用でき、親エージェントや兄弟エージェントとは共有されない。 + +## MCP の出力上限 + +Claude Code はコンテキストオーバーフローを防ぐため、MCP ツールの出力に上限を強制する。 + +| 上限 | しきい値 | 動作 | +|------|----------|------| +| **警告** | 10,000 トークン | 出力が大きいことを示す警告を表示 | +| **デフォルト最大値** | 25,000 トークン | この上限を超えた出力は切り詰められる | +| **ディスク永続化** | 50,000 文字 | 50K 文字を超えるツール結果はディスクに永続化される | + +最大出力上限は `MAX_MCP_OUTPUT_TOKENS` 環境変数で設定可能。 + +```bash +# 最大出力を 50,000 トークンに引き上げる +export MAX_MCP_OUTPUT_TOKENS=50000 +``` + +## コード実行によるコンテキスト肥大化の解決 + +MCP の採用が拡大するにつれ、数十のサーバーと数百〜数千のツールに接続することは大きな課題を生む：**コンテキストの肥大化** である。これは MCP がスケールしたときの最大の問題と言ってよく、Anthropic のエンジニアリングチームが提案するエレガントな解決策が、ツールを直接呼び出す代わりにコード実行を使う方法である。 + +> **出典：** [Code Execution with MCP: Building More Efficient Agents](https://www.anthropic.com/engineering/code-execution-with-mcp) — Anthropic Engineering Blog + +### 問題：トークン浪費の 2 つの源 + +**1. ツール定義がコンテキストウィンドウを過負荷にする** + +ほとんどの MCP クライアントは全ツール定義を事前に読み込む。数千のツールに接続している場合、モデルはユーザーのリクエストを読む前に数十万トークンを処理しなければならない。 + +**2. 中間結果がさらにトークンを消費する** + +すべての中間ツール結果はモデルのコンテキストを通過する。Google Drive から Salesforce へ会議の文字起こしを転送する場合を考えると、文字起こし全体がコンテキストを **2 回** 流れる。読み込むときと、宛先に書き込むときである。2 時間の会議の文字起こしは 50,000 トークン以上の追加になり得る。 + +```mermaid +graph LR + A["Model"] -->|"Tool Call: getDocument"| B["MCP Server"] + B -->|"Full transcript (50K tokens)"| A + A -->|"Tool Call: updateRecord
(re-sends full transcript)"| B + B -->|"Confirmation"| A + + style A fill:#ffcdd2,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 +``` + +### 解決策：コード API としての MCP ツール + +ツール定義と結果をコンテキストウィンドウに通す代わりに、エージェントが MCP ツールを API として呼び出す **コードを書く**。コードはサンドボックス化された実行環境で動作し、最終結果のみがモデルに返される。 + +```mermaid +graph LR + A["Model"] -->|"Writes code"| B["Code Execution
Environment"] + B -->|"Calls tools directly"| C["MCP Servers"] + C -->|"Data stays in
execution env"| B + B -->|"Only final result
(minimal tokens)"| A + + style A fill:#c8e6c9,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 +``` + +#### 仕組み + +MCP ツールは型付き関数のファイルツリーとして提示される。 + +``` +servers/ +├── google-drive/ +│ ├── getDocument.ts +│ └── index.ts +├── salesforce/ +│ ├── updateRecord.ts +│ └── index.ts +└── ... +``` + +各ツールファイルには型付きラッパーが含まれる。 + +```typescript +// ./servers/google-drive/getDocument.ts +import { callMCPTool } from "../../../client.js"; + +interface GetDocumentInput { + documentId: string; +} + +interface GetDocumentResponse { + content: string; +} + +export async function getDocument( + input: GetDocumentInput +): Promise { + return callMCPTool( + 'google_drive__get_document', input + ); +} +``` + +エージェントはツールをオーケストレーションするコードを書く。 + +```typescript +import * as gdrive from './servers/google-drive'; +import * as salesforce from './servers/salesforce'; + +// データはツール間で直接流れる — モデルを経由しない +const transcript = ( + await gdrive.getDocument({ documentId: 'abc123' }) +).content; + +await salesforce.updateRecord({ + objectType: 'SalesMeeting', + recordId: '00Q5f000001abcXYZ', + data: { Notes: transcript } +}); +``` + +**結果：トークン使用量は約 150,000 から約 2,000 に減少 — 98.7% の削減。** + +### 主な利点 + +| 利点 | 説明 | +|------|------| +| **段階的開示** | エージェントはファイルシステムを参照して必要なツール定義のみを読み込み、全ツールを事前読込みしない | +| **コンテキスト効率の良い結果** | データは実行環境内でフィルタ/変換されてからモデルに返される | +| **強力な制御フロー** | ループ、条件分岐、エラー処理がモデルへのラウンドトリップなしにコード内で動作 | +| **プライバシー保護** | 中間データ（PII、機密レコード）は実行環境内に留まり、モデルコンテキストに入らない | +| **状態の永続化** | エージェントは中間結果をファイルに保存し、再利用可能なスキル関数を構築できる | + +#### 例：大規模データセットのフィルタリング + +```typescript +// コード実行なし — 10,000 行すべてがコンテキストを流れる +// TOOL CALL: gdrive.getSheet(sheetId: 'abc123') +// -> returns 10,000 rows in context + +// コード実行あり — 実行環境内でフィルタリング +const allRows = await gdrive.getSheet({ sheetId: 'abc123' }); +const pendingOrders = allRows.filter( + row => row["Status"] === 'pending' +); +console.log(`Found ${pendingOrders.length} pending orders`); +console.log(pendingOrders.slice(0, 5)); // 5 行のみがモデルに到達 +``` + +#### 例：ラウンドトリップなしのループ + +```typescript +// デプロイ通知をポーリング — すべてコード内で実行 +let found = false; +while (!found) { + const messages = await slack.getChannelHistory({ + channel: 'C123456' + }); + found = messages.some( + m => m.text.includes('deployment complete') + ); + if (!found) await new Promise(r => setTimeout(r, 5000)); +} +console.log('Deployment notification received'); +``` + +### 考慮すべきトレードオフ + +コード実行は独自の複雑さを持ち込む。エージェント生成のコードを実行するには次が必要となる。 + +- 適切なリソース上限を持つ **セキュアなサンドボックス実行環境** +- 実行されたコードの **監視とログ記録** +- ツールの直接呼び出しと比較した追加の **インフラオーバーヘッド** + +利点（トークンコスト削減、レイテンシ低下、ツール構成の改善）は、こうした実装コストと天秤にかける必要がある。MCP サーバーが少数だけのエージェントなら、ツールの直接呼び出しのほうがシンプルかもしれない。スケールするエージェント（数十のサーバー、数百のツール）にとって、コード実行は大きな改善である。 + +### MCPorter：MCP ツール構成のためのランタイム + +[MCPorter](https://github.com/steipete/mcporter) は、MCP サーバーへの呼び出しをボイラープレートなしで実用的にする TypeScript ランタイム＆ CLI ツールキットである。選択的なツール公開と型付きラッパーを通じてコンテキストの肥大化を抑える助けにもなる。 + +**解決すること：** すべての MCP サーバーから全ツール定義を事前読み込みする代わりに、MCPorter は特定のツールを必要に応じて発見、検査、呼び出しできるようにする。これによりコンテキストを軽量に保てる。 + +**主な機能：** + +| 機能 | 説明 | +|------|------| +| **ゼロ設定での発見** | Cursor、Claude、Codex、ローカル設定から MCP サーバーを自動発見 | +| **型付きツールクライアント** | `mcporter emit-ts` が `.d.ts` インターフェースとすぐ動作するラッパーを生成 | +| **構成可能な API** | `createServerProxy()` がツールを camelCase メソッドとして公開し、`.text()`、`.json()`、`.markdown()` ヘルパーを提供 | +| **CLI 生成** | `mcporter generate-cli` が任意の MCP サーバーをスタンドアロン CLI に変換し、`--include-tools` / `--exclude-tools` でフィルタリング | +| **パラメータの非表示** | オプションパラメータはデフォルトで非表示となり、スキーマの冗長性を低減 | + +**インストール：** + +```bash +npx mcporter list # インストール不要 — サーバーをすぐに発見 +pnpm add mcporter # プロジェクトに追加 +brew install steipete/tap/mcporter # macOS の Homebrew 経由 +``` + +**例 — TypeScript でツールを構成：** + +```typescript +import { createRuntime, createServerProxy } from "mcporter"; + +const runtime = await createRuntime(); +const gdrive = createServerProxy(runtime, "google-drive"); +const salesforce = createServerProxy(runtime, "salesforce"); + +// データはモデルコンテキストを通過せずにツール間を流れる +const doc = await gdrive.getDocument({ documentId: "abc123" }); +await salesforce.updateRecord({ + objectType: "SalesMeeting", + recordId: "00Q5f000001abcXYZ", + data: { Notes: doc.text() } +}); +``` + +**例 — CLI ツール呼び出し：** + +```bash +# 特定のツールを直接呼び出し +npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!' + +# 利用可能なサーバーとツールを一覧 +npx mcporter list +``` + +MCPorter は上述のコード実行アプローチを補完するもので、MCP ツールを型付き API として呼び出すためのランタイム基盤を提供する。中間データをモデルコンテキストの外に保つことを容易にする。 + +## ベストプラクティス + +### セキュリティに関する考慮事項 + +#### 推奨 ✅ +- すべての認証情報に環境変数を使用する +- トークンと API キーを定期的にローテーションする（毎月推奨） +- 可能な限り読み取り専用トークンを使用する +- MCP サーバーのアクセス範囲を必要最小限に制限する +- MCP サーバーの使用状況とアクセスログを監視する +- 利用可能であれば外部サービスに OAuth を使用する +- MCP リクエストにレート制限を実装する +- 本番運用前に MCP 接続をテストする +- 稼働中の MCP 接続をすべてドキュメント化する +- MCP サーバーパッケージを最新に保つ + +#### 非推奨 ❌ +- 認証情報を設定ファイルにハードコードしない +- トークンや秘密情報を git にコミットしない +- チームのチャットやメールでトークンを共有しない +- 個人用トークンをチームプロジェクトに使用しない +- 不要な権限を付与しない +- 認証エラーを無視しない +- MCP エンドポイントを公開しない +- MCP サーバーを root/admin 権限で実行しない +- 機密データをログにキャッシュしない +- 認証メカニズムを無効化しない + +### 設定のベストプラクティス + +1. **バージョン管理：** `.mcp.json` を git に保存するが、シークレットには環境変数を使う +2. **最小権限：** 各 MCP サーバーに必要最小限の権限のみ付与する +3. **分離：** 可能なら異なる MCP サーバーを別プロセスで実行する +4. **監視：** 監査証跡のため、すべての MCP リクエストとエラーを記録する +5. **テスト：** 本番デプロイ前にすべての MCP 設定をテストする + +### パフォーマンスのヒント + +- 頻繁にアクセスするデータはアプリケーションレベルでキャッシュする +- データ転送量を減らすため、特定の MCP クエリを使う +- MCP 操作のレスポンスタイムを監視する +- 外部 API にはレート制限を検討する +- 複数操作を実行するときはバッチ処理を使う + +## インストール手順 + +### 前提条件 +- Node.js と npm がインストール済み +- Claude Code CLI がインストール済み +- 外部サービス用の API トークン/認証情報 + +### ステップバイステップのセットアップ + +1. **最初の MCP サーバーを追加**（例：GitHub）： +```bash +claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github +``` + + または、プロジェクトルートに `.mcp.json` ファイルを作成： +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +2. **環境変数を設定：** +```bash +export GITHUB_TOKEN="your_github_personal_access_token" +``` + +3. **接続をテスト：** +```bash +claude /mcp +``` + +4. **MCP ツールを使う：** +```bash +/mcp__github__list_prs +/mcp__github__create_issue "Title" "Description" +``` + +### 特定サービスのインストール + +**GitHub MCP：** +```bash +npm install -g @modelcontextprotocol/server-github +``` + +**Database MCP：** +```bash +npm install -g @modelcontextprotocol/server-database +``` + +**Filesystem MCP：** +```bash +npm install -g @modelcontextprotocol/server-filesystem +``` + +**Slack MCP：** +```bash +npm install -g @modelcontextprotocol/server-slack +``` + +## トラブルシューティング + +### MCP サーバーが見つからない +```bash +# MCP サーバーがインストールされているか確認 +npm list -g @modelcontextprotocol/server-github + +# 未インストールならインストール +npm install -g @modelcontextprotocol/server-github +``` + +### 認証失敗 +```bash +# 環境変数が設定されているか確認 +echo $GITHUB_TOKEN + +# 必要なら再設定 +export GITHUB_TOKEN="your_token" + +# トークンが正しい権限を持つか確認 +# GitHub のトークンスコープは https://github.com/settings/tokens で確認 +``` + +### 接続タイムアウト +- ネットワーク疎通を確認：`ping api.github.com` +- API エンドポイントが到達可能か確認 +- API のレート制限を確認 +- 設定でタイムアウトを延ばしてみる +- ファイアウォールやプロキシの問題を確認 + +### MCP サーバーがクラッシュする +- MCP サーバーのログを確認：`~/.claude/logs/` +- すべての環境変数が設定されているか確認 +- 適切なファイル権限を確認 +- MCP サーバーパッケージの再インストールを試す +- 同じポートで競合するプロセスがないか確認 + +## 関連概念 + +### メモリと MCP +- **メモリ：** 永続的で変化しないデータを保存（設定、コンテキスト、履歴） +- **MCP：** 変化するライブデータにアクセス（API、データベース、リアルタイムサービス） + +### どちらを使うか +- **メモリを使う場合：** ユーザー設定、会話履歴、学習したコンテキスト +- **MCP を使う場合：** 現在の GitHub Issue、ライブデータベースクエリ、リアルタイムデータ + +### 他の Claude 機能との統合 +- メモリと MCP を組み合わせて豊かなコンテキストを構築 +- プロンプト内で MCP ツールを使い、より良い推論を実現 +- 複雑なワークフローには複数の MCP を活用 + +## 追加リソース + +- [Official MCP Documentation](https://code.claude.com/docs/en/mcp) +- [MCP Protocol Specification](https://modelcontextprotocol.io/specification) +- [MCP GitHub Repository](https://github.com/modelcontextprotocol/servers) +- [Available MCP Servers](https://github.com/modelcontextprotocol/servers) +- [MCPorter](https://github.com/steipete/mcporter) — ボイラープレートなしで MCP サーバーを呼び出すための TypeScript ランタイム＆ CLI +- [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) — コンテキスト肥大化の解決に関する Anthropic のエンジニアリングブログ +- [Claude Code CLI Reference](https://code.claude.com/docs/en/cli-reference) +- [Claude API Documentation](https://docs.anthropic.com) + +--- + +**最終更新：** 2026 年 4 月 24 日 +**Claude Code バージョン：** 2.1.119 +**情報源：** +- https://code.claude.com/docs/en/mcp +- https://code.claude.com/docs/en/changelog +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +**対応モデル：** Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/05-mcp/database-mcp.json b/ja/05-mcp/database-mcp.json new file mode 100644 index 0000000..eaa832a --- /dev/null +++ b/ja/05-mcp/database-mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} diff --git a/ja/05-mcp/filesystem-mcp.json b/ja/05-mcp/filesystem-mcp.json new file mode 100644 index 0000000..c76fdf6 --- /dev/null +++ b/ja/05-mcp/filesystem-mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} diff --git a/ja/05-mcp/github-mcp.json b/ja/05-mcp/github-mcp.json new file mode 100644 index 0000000..0f62131 --- /dev/null +++ b/ja/05-mcp/github-mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} diff --git a/ja/05-mcp/multi-mcp.json b/ja/05-mcp/multi-mcp.json new file mode 100644 index 0000000..62d8fa5 --- /dev/null +++ b/ja/05-mcp/multi-mcp.json @@ -0,0 +1,29 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + }, + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "${DATABASE_URL}" + } + }, + "slack": { + "command": "npx", + "args": ["@modelcontextprotocol/server-slack"], + "env": { + "SLACK_TOKEN": "${SLACK_TOKEN}" + } + }, + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} diff --git a/ja/06-hooks/README.md b/ja/06-hooks/README.md new file mode 100644 index 0000000..b714d4f --- /dev/null +++ b/ja/06-hooks/README.md @@ -0,0 +1,1369 @@ + + + + + + + Claude How To + + +# フック + +フックは、Claude Code セッション中の特定イベントに応答して実行される自動化スクリプトである。自動化、検証、権限管理、カスタムワークフローを可能にする。 + +## 概要 + +フックは、Claude Code 内で特定イベントが発生したときに自動実行される自動化アクション（シェルコマンド、HTTP webhook、LLM プロンプト、MCP ツール呼び出し、サブエージェント評価）である。フックは JSON 入力を受け取り、終了コードと JSON 出力で結果を伝える。 + +**主な機能：** +- イベント駆動の自動化 +- JSON ベースの入出力 +- `command`、`http`、`mcp_tool`、`prompt`、`agent` の各フックタイプをサポート +- ツール固有のフック向けのパターンマッチング + +## 設定 + +フックは設定ファイル内に決まった構造で記述する。 + +- `~/.claude/settings.json` - ユーザー設定（全プロジェクト） +- `.claude/settings.json` - プロジェクト設定（共有可、コミット対象） +- `.claude/settings.local.json` - ローカルプロジェクト設定（コミットしない） +- 管理ポリシー - 組織全体の設定 +- プラグインの `hooks/hooks.json` - プラグインスコープのフック +- スキル/エージェントのフロントマター - コンポーネントライフタイムフック + +### 基本的な設定構造 + +```json +{ + "hooks": { + "EventName": [ + { + "matcher": "ToolPattern", + "hooks": [ + { + "type": "command", + "command": "your-command-here", + "timeout": 60 + } + ] + } + ] + } +} +``` + +**主要フィールド：** + +| フィールド | 説明 | 例 | +|-----------|------|-----| +| `matcher` | ツール名にマッチするパターン（大文字小文字を区別） | `"Write"`、`"Edit\|Write"`、`"*"` | +| `hooks` | フック定義の配列 | `[{ "type": "command", ... }]` | +| `type` | フックタイプ：`"command"`（bash）、`"prompt"`（LLM）、`"http"`（webhook）、`"mcp_tool"`（MCP ツール呼び出し、v2.1.118 以降）、`"agent"`（サブエージェント） | `"command"` | +| `command` | 実行するシェルコマンド | `"$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"` | +| `timeout` | オプションのタイムアウト（秒、デフォルト 60） | `30` | +| `once` | `true` の場合、フックはセッションごとに 1 回のみ実行 | `true` | + +### マッチャーパターン + +| パターン | 説明 | 例 | +|---------|------|-----| +| 完全一致文字列 | 特定のツールにマッチ | `"Write"` | +| 正規表現 | 複数のツールにマッチ | `"Edit\|Write"` | +| ワイルドカード | すべてのツールにマッチ | `"*"` または `""` | +| MCP ツール | サーバーとツールのパターン | `"mcp__memory__.*"` | + +**InstructionsLoaded のマッチャー値：** + +| マッチャー値 | 説明 | +|-------------|------| +| `session_start` | セッション開始時に読み込まれる指示 | +| `nested_traversal` | ネストされたディレクトリ走査中に読み込まれる指示 | +| `path_glob_match` | パス glob パターンマッチで読み込まれる指示 | + +## フックタイプ + +Claude Code は 5 種類のフックタイプをサポートする。 + +### Command フック + +デフォルトのフックタイプ。シェルコマンドを実行し、JSON の標準入出力と終了コードで通信する。 + +```json +{ + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py\"", + "timeout": 60 +} +``` + +### HTTP フック + +> v2.1.63 で追加。 + +リモート webhook エンドポイントが、command フックと同じ JSON 入力を受け取る。HTTP フックは URL に JSON を POST し、JSON レスポンスを受け取る。サンドボックスが有効な場合、HTTP フックはサンドボックス経由でルーティングされる。URL 内の環境変数展開には、セキュリティのため明示的な `allowedEnvVars` リストが必要。 + +```json +{ + "hooks": { + "PostToolUse": [{ + "type": "http", + "url": "https://my-webhook.example.com/hook", + "matcher": "Write" + }] + } +} +``` + +**主要プロパティ：** +- `"type": "http"` -- HTTP フックであることを示す +- `"url"` -- webhook エンドポイント URL +- サンドボックスが有効ならサンドボックス経由でルーティング +- URL 内の環境変数展開には明示的な `allowedEnvVars` リストが必要 + +### Prompt フック + +LLM が評価するプロンプトで、フック内容は Claude が評価するプロンプトとなる。主に `Stop` および `SubagentStop` イベントで、知的なタスク完了チェックに使用される。 + +```json +{ + "type": "prompt", + "prompt": "Evaluate if Claude completed all requested tasks.", + "timeout": 30 +} +``` + +LLM はプロンプトを評価し、構造化された判定を返す（詳細は [Prompt ベースのフック](#prompt-ベースのフック) を参照）。 + +### MCP Tool フック + +> v2.1.118 で追加。 + +`mcp_tool` タイプは設定された MCP ツールを直接呼び出す。設定はシェルコマンドや URL ではなく、MCP サーバーとツール名を参照する。検証や反応ロジックがすでに設定済みの MCP サーバー側にある場合に有用である。 + +```json +{ + "matcher": "Edit", + "hooks": [{ + "type": "mcp_tool", + "server": "my-mcp-server", + "tool": "validate_edit" + }] +} +``` + +**主要プロパティ：** +- `"type": "mcp_tool"` -- MCP ツールフックであることを示す +- `"server"` -- 設定済み MCP サーバーの名前 +- `"tool"` -- そのサーバー上で呼び出すツール名 + +フック入力（ツール名、ツール入力、セッションコンテキスト）は MCP ツールの引数として渡される。MCP サーバーの設定方法は [MCP サーバーセットアップ](../05-mcp/README.md) を参照。 + +### Agent フック + +サブエージェントベースの検証フックで、専用エージェントを生成して条件評価や複雑なチェックを実行する。prompt フック（単発の LLM 評価）と異なり、agent フックはツールを使用してマルチステップの推論を行える。 + +```json +{ + "type": "agent", + "prompt": "Verify the code changes follow our architecture guidelines. Check the relevant design docs and compare.", + "timeout": 120 +} +``` + +**主要プロパティ：** +- `"type": "agent"` -- agent フックであることを示す +- `"prompt"` -- サブエージェントへのタスク説明 +- エージェントはツール（Read、Grep、Bash など）を使用して評価を行える +- prompt フックと同様に構造化された判定を返す + +## フックイベント + +Claude Code は **28 種類のフックイベント** をサポートする。 + +| イベント | 発火タイミング | マッチャー入力 | ブロック可否 | 用途例 | +|----------|---------------|---------------|-------------|--------| +| **SessionStart** | セッション開始/再開/clear/compact | startup/resume/clear/compact | 不可 | 環境セットアップ | +| **InstructionsLoaded** | CLAUDE.md やルールファイルが読み込まれた後 | （なし） | 不可 | 指示の修正/フィルタ | +| **UserPromptSubmit** | ユーザーがプロンプトを送信 | （なし） | 可 | プロンプト検証 | +| **UserPromptExpansion** | ユーザープロンプトが展開（`@` メンション、スラッシュコマンド解決など） | （なし） | 可 | 展開後のプロンプトを変換/検査 | +| **PreToolUse** | ツール実行前 | ツール名 | 可（allow/deny/ask） | 入力の検証・修正 | +| **PermissionRequest** | 権限ダイアログ表示 | ツール名 | 可 | 自動承認/拒否 | +| **PermissionDenied** | ユーザーが権限プロンプトを拒否 | ツール名 | 不可 | ロギング、解析、ポリシー強制 | +| **PostToolUse** | ツール成功後 | ツール名 | 不可 | コンテキスト追加、フィードバック | +| **PostToolUseFailure** | ツール実行失敗時 | ツール名 | 不可 | エラー処理、ロギング | +| **PostToolBatch** | ツールバッチ完了後 | （なし） | 不可 | 集約レポート、バッチ検証 | +| **Notification** | 通知送信時 | 通知タイプ | 不可 | カスタム通知 | +| **SubagentStart** | サブエージェント生成 | エージェントタイプ名 | 不可 | サブエージェントセットアップ | +| **SubagentStop** | サブエージェント完了 | エージェントタイプ名 | 可 | サブエージェント検証 | +| **Stop** | Claude が応答を終えたとき | （なし） | 可 | タスク完了チェック | +| **StopFailure** | API エラーでターン終了 | （なし） | 不可 | エラー復旧、ロギング | +| **TeammateIdle** | エージェントチームのメイトがアイドル | （なし） | 可 | チームメイト連携 | +| **TaskCompleted** | タスク完了マーク | （なし） | 可 | タスク後の処理 | +| **TaskCreated** | TaskCreate でタスク作成 | （なし） | 不可 | タスク追跡、ロギング | +| **ConfigChange** | 設定ファイル変更 | （なし） | 可（ポリシーを除く） | 設定更新への反応 | +| **CwdChanged** | 作業ディレクトリ変更 | （なし） | 不可 | ディレクトリ固有のセットアップ | +| **FileChanged** | 監視ファイル変更 | （なし） | 不可 | ファイル監視、再ビルド | +| **PreCompact** | コンテキスト圧縮前 | manual/auto | 不可 | 圧縮前の処理 | +| **PostCompact** | 圧縮完了後 | （なし） | 不可 | 圧縮後の処理 | +| **WorktreeCreate** | ワークツリー作成中 | （なし） | 可（パス返却） | ワークツリー初期化 | +| **WorktreeRemove** | ワークツリー削除中 | （なし） | 不可 | ワークツリークリーンアップ | +| **Elicitation** | MCP サーバーがユーザー入力を要求 | （なし） | 可 | 入力検証 | +| **ElicitationResult** | ユーザーが elicitation に応答 | （なし） | 可 | 応答処理 | +| **SessionEnd** | セッション終了 | （なし） | 不可 | クリーンアップ、最終ロギング | + +> **PostToolUse の duration（v2.1.119）：** `PostToolUse` と `PostToolUseFailure` のフック入力に `duration_ms` が含まれるようになった。詳細は [PostToolUse](#posttooluse) セクションを参照。 + +### PreToolUse + +Claude がツールパラメータを生成した後、処理開始前に動作する。ツール入力の検証・修正に使う。 + +**設定：** +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py" + } + ] + } + ] + } +} +``` + +**一般的なマッチャー：** `Task`、`Bash`、`Glob`、`Grep`、`Read`、`Edit`、`Write`、`WebFetch`、`WebSearch` + +**出力制御：** +- `permissionDecision`: `"allow"`、`"deny"`、`"ask"` +- `permissionDecisionReason`: 判定の理由 +- `updatedInput`: 修正されたツール入力パラメータ + +### PostToolUse + +ツール完了直後に動作する。検証、ロギング、Claude へのコンテキスト返却に使う。 + +**設定：** +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py" + } + ] + } + ] + } +} +``` + +**出力制御：** +- `"block"` 判定で Claude にフィードバックを促す +- `additionalContext`: Claude へ追加されるコンテキスト + +**追加入力フィールド（v2.1.119）：** + +| フィールド | 型 | 説明 | +|-----------|----|------| +| `duration_ms` | number | ツール実行時間（ミリ秒）。権限プロンプトおよび PreToolUse フック実行時間は除外。`PostToolUse` と `PostToolUseFailure` の両フックで利用可能。 | + +### UserPromptSubmit + +ユーザーがプロンプトを送信し、Claude が処理を開始する前に動作する。 + +**設定：** +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py" + } + ] + } + ] + } +} +``` + +**出力制御：** +- `decision`: `"block"` で処理を阻止 +- `reason`: ブロックされた理由 +- `additionalContext`: プロンプトに追加されるコンテキスト + +### Stop と SubagentStop + +Claude が応答を終えたとき（Stop）、サブエージェントが完了したとき（SubagentStop）に動作する。知的なタスク完了チェックのために、prompt ベースの評価をサポートする。 + +**追加入力フィールド：** `Stop` と `SubagentStop` の両フックは、JSON 入力に `last_assistant_message` フィールドを受け取る。これは停止前の Claude もしくはサブエージェントからの最終メッセージを含み、タスク完了の評価に有用である。 + +**設定：** +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Evaluate if Claude completed all requested tasks.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +### SubagentStart + +サブエージェントが実行を開始したときに動作する。マッチャー入力はエージェントタイプ名であり、特定のサブエージェントタイプを対象にできる。 + +**設定：** +```json +{ + "hooks": { + "SubagentStart": [ + { + "matcher": "code-review", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-init.sh" + } + ] + } + ] + } +} +``` + +### SessionStart + +セッション開始または再開時に動作する。環境変数を永続化できる。 + +**マッチャー：** `startup`、`resume`、`clear`、`compact` + +**特別な機能：** `CLAUDE_ENV_FILE` を使って環境変数を永続化できる（`CwdChanged` と `FileChanged` フックでも利用可能）。 + +```bash +#!/bin/bash +if [ -n "$CLAUDE_ENV_FILE" ]; then + echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE" +fi +exit 0 +``` + +### SessionEnd + +セッション終了時に、クリーンアップや最終ロギングを実行する。終了をブロックすることはできない。 + +**Reason フィールドの値：** +- `clear` - ユーザーがセッションをクリア +- `logout` - ユーザーがログアウト +- `prompt_input_exit` - ユーザーがプロンプト入力で終了 +- `other` - その他の理由 + +**設定：** +```json +{ + "hooks": { + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"" + } + ] + } + ] + } +} +``` + +### Notification イベント + +通知イベントの更新済みマッチャー： +- `permission_prompt` - 権限要求の通知 +- `idle_prompt` - アイドル状態の通知 +- `auth_success` - 認証成功 +- `elicitation_dialog` - ユーザーへ表示されるダイアログ + +## コンポーネントスコープのフック + +フックは、特定のコンポーネント（スキル、エージェント、コマンド）のフロントマターにアタッチできる。 + +**SKILL.md、agent.md、command.md 内：** + +```yaml +--- +name: secure-operations +description: Perform operations with security checks +hooks: + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/check.sh" + once: true # セッションごとに 1 回のみ実行 +--- +``` + +**コンポーネントフックでサポートされるイベント：** `PreToolUse`、`PostToolUse`、`Stop` + +これにより、フックを使用するコンポーネント内に直接定義でき、関連コードを近くにまとめられる。 + +### サブエージェントフロントマター内のフック + +サブエージェントのフロントマターで `Stop` フックを定義すると、自動的にそのサブエージェントにスコープされた `SubagentStop` フックに変換される。これにより、メインセッション停止時ではなく、その特定サブエージェント完了時にのみフックが発火することが保証される。 + +```yaml +--- +name: code-review-agent +description: Automated code review subagent +hooks: + Stop: + - hooks: + - type: prompt + prompt: "Verify the code review is thorough and complete." + # 上記の Stop フックは、このサブエージェント用の SubagentStop に自動変換される +--- +``` + +## PermissionRequest イベント + +カスタム出力フォーマットで権限要求を処理する。 + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PermissionRequest", + "decision": { + "behavior": "allow|deny", + "updatedInput": {}, + "message": "Custom message", + "interrupt": false + } + } +} +``` + +## フックの入出力 + +### JSON 入力（stdin 経由） + +すべてのフックは stdin 経由で JSON 入力を受け取る。 + +```json +{ + "session_id": "abc123", + "transcript_path": "/path/to/transcript.jsonl", + "cwd": "/current/working/directory", + "permission_mode": "default", + "hook_event_name": "PreToolUse", + "tool_name": "Write", + "tool_input": { + "file_path": "/path/to/file.js", + "content": "..." + }, + "tool_use_id": "toolu_01ABC123...", + "agent_id": "agent-abc123", + "agent_type": "main", + "worktree": "/path/to/worktree" +} +``` + +**共通フィールド：** + +| フィールド | 説明 | +|-----------|------| +| `session_id` | セッションの一意識別子 | +| `transcript_path` | 会話トランスクリプトファイルへのパス | +| `cwd` | カレント作業ディレクトリ | +| `hook_event_name` | フックを発火させたイベント名 | +| `agent_id` | このフックを実行しているエージェントの識別子 | +| `agent_type` | エージェントタイプ（`"main"`、サブエージェントタイプ名など） | +| `worktree` | エージェントが git ワークツリーで動作している場合のパス | + +### 終了コード + +| 終了コード | 意味 | 動作 | +|-----------|------|------| +| **0** | 成功 | 続行、JSON stdout を解析 | +| **2** | ブロッキングエラー | 操作をブロック、stderr をエラーとして表示 | +| **その他** | 非ブロッキングエラー | 続行、verbose モードで stderr を表示 | + +### JSON 出力（stdout、終了コード 0） + +```json +{ + "continue": true, + "stopReason": "Optional message if stopping", + "suppressOutput": false, + "systemMessage": "Optional warning message", + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "allow", + "permissionDecisionReason": "File is in allowed directory", + "updatedInput": { + "file_path": "/modified/path.js" + } + } +} +``` + +## 環境変数 + +| 変数 | 利用可能なフック | 説明 | +|------|-----------------|------| +| `CLAUDE_PROJECT_DIR` | すべてのフック | プロジェクトルートへの絶対パス | +| `CLAUDE_ENV_FILE` | SessionStart、CwdChanged、FileChanged | 環境変数を永続化するファイルパス | +| `CLAUDE_CODE_REMOTE` | すべてのフック | リモート環境で動作中なら `"true"` | +| `${CLAUDE_PLUGIN_ROOT}` | プラグインフック | プラグインディレクトリへのパス | +| `${CLAUDE_PLUGIN_DATA}` | プラグインフック | プラグインデータディレクトリへのパス | +| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | SessionEnd フック | SessionEnd フック向けのミリ秒単位タイムアウト設定（デフォルトを上書き） | + +## Prompt ベースのフック + +`Stop` および `SubagentStop` イベントには、LLM ベースの評価を使用できる。 + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Review if all tasks are complete. Return your decision.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +**LLM レスポンススキーマ：** +```json +{ + "decision": "approve", + "reason": "All tasks completed successfully", + "continue": false, + "stopReason": "Task complete" +} +``` + +## 例 + +### 例 1：Bash コマンドバリデータ（PreToolUse） + +**ファイル：** `.claude/hooks/validate-bash.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +BLOCKED_PATTERNS = [ + (r"\brm\s+-rf\s+/", "Blocking dangerous rm -rf / command"), + (r"\bsudo\s+rm", "Blocking sudo rm command"), +] + +def main(): + input_data = json.load(sys.stdin) + + tool_name = input_data.get("tool_name", "") + if tool_name != "Bash": + sys.exit(0) + + command = input_data.get("tool_input", {}).get("command", "") + + for pattern, message in BLOCKED_PATTERNS: + if re.search(pattern, command): + print(message, file=sys.stderr) + sys.exit(2) # 終了コード 2 = ブロッキングエラー + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +**設定：** +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"" + } + ] + } + ] + } +} +``` + +### 例 2：セキュリティスキャナ（PostToolUse） + +**ファイル：** `.claude/hooks/security-scan.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +SECRET_PATTERNS = [ + (r"password\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded password"), + (r"api[_-]?key\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded API key"), +] + +def main(): + input_data = json.load(sys.stdin) + + tool_name = input_data.get("tool_name", "") + if tool_name not in ["Write", "Edit"]: + sys.exit(0) + + tool_input = input_data.get("tool_input", {}) + content = tool_input.get("content", "") or tool_input.get("new_string", "") + file_path = tool_input.get("file_path", "") + + warnings = [] + for pattern, message in SECRET_PATTERNS: + if re.search(pattern, content, re.IGNORECASE): + warnings.append(message) + + if warnings: + output = { + "hookSpecificOutput": { + "hookEventName": "PostToolUse", + "additionalContext": f"Security warnings for {file_path}: " + "; ".join(warnings) + } + } + print(json.dumps(output)) + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +### 例 3：コード自動フォーマット（PostToolUse） + +**ファイル：** `.claude/hooks/format-code.sh` + +```bash +#!/bin/bash + +# stdin から JSON を読み取る +INPUT=$(cat) +TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_name', ''))") +FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_input', {}).get('file_path', ''))") + +if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then + exit 0 +fi + +# ファイル拡張子に基づいてフォーマット +case "$FILE_PATH" in + *.js|*.jsx|*.ts|*.tsx|*.json) + command -v prettier &>/dev/null && prettier --write "$FILE_PATH" 2>/dev/null + ;; + *.py) + command -v black &>/dev/null && black "$FILE_PATH" 2>/dev/null + ;; + *.go) + command -v gofmt &>/dev/null && gofmt -w "$FILE_PATH" 2>/dev/null + ;; +esac + +exit 0 +``` + +### 例 4：プロンプトバリデータ（UserPromptSubmit） + +**ファイル：** `.claude/hooks/validate-prompt.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +BLOCKED_PATTERNS = [ + (r"delete\s+(all\s+)?database", "Dangerous: database deletion"), + (r"rm\s+-rf\s+/", "Dangerous: root deletion"), +] + +def main(): + input_data = json.load(sys.stdin) + prompt = input_data.get("user_prompt", "") or input_data.get("prompt", "") + + for pattern, message in BLOCKED_PATTERNS: + if re.search(pattern, prompt, re.IGNORECASE): + output = { + "decision": "block", + "reason": f"Blocked: {message}" + } + print(json.dumps(output)) + sys.exit(0) + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +### 例 5：知的な Stop フック（Prompt ベース） + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Review if Claude completed all requested tasks. Check: 1) Were all files created/modified? 2) Were there unresolved errors? If incomplete, explain what's missing.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +### 例 6：コンテキスト使用量トラッカー（フックペア） + +`UserPromptSubmit`（メッセージ前）と `Stop`（応答後）フックを組み合わせて、リクエストごとのトークン消費量を追跡する。 + +**ファイル：** `.claude/hooks/context-tracker.py` + +```python +#!/usr/bin/env python3 +""" +Context Usage Tracker - Tracks token consumption per request. + +Uses UserPromptSubmit as "pre-message" hook and Stop as "post-response" hook +to calculate the delta in token usage for each request. + +Token Counting Methods: +1. Character estimation (default): ~4 chars per token, no dependencies +2. tiktoken (optional): More accurate (~90-95%), requires: pip install tiktoken +""" +import json +import os +import sys +import tempfile + +# 設定 +CONTEXT_LIMIT = 128000 # Claude のコンテキストウィンドウ（モデルに合わせて調整） +USE_TIKTOKEN = False # tiktoken がインストール済みなら True にして精度向上 + + +def get_state_file(session_id: str) -> str: + """メッセージ前のトークン数を保存する一時ファイルパスを取得（セッションごとに分離）。""" + return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json") + + +def count_tokens(text: str) -> int: + """ + テキスト内のトークン数をカウント。 + + tiktoken が利用可能なら p50k_base エンコーディングを使用（約 90〜95% の精度）、 + それ以外は文字数による推定にフォールバック（約 80〜90% の精度）。 + """ + if USE_TIKTOKEN: + try: + import tiktoken + enc = tiktoken.get_encoding("p50k_base") + return len(enc.encode(text)) + except ImportError: + pass # 推定にフォールバック + + # 文字ベースの推定：英語の場合、約 4 文字で 1 トークン + return len(text) // 4 + + +def read_transcript(transcript_path: str) -> str: + """トランスクリプトファイルから全コンテンツを読み込み連結。""" + if not transcript_path or not os.path.exists(transcript_path): + return "" + + content = [] + with open(transcript_path, "r") as f: + for line in f: + try: + entry = json.loads(line.strip()) + # 様々なメッセージ形式からテキストコンテンツを抽出 + if "message" in entry: + msg = entry["message"] + if isinstance(msg.get("content"), str): + content.append(msg["content"]) + elif isinstance(msg.get("content"), list): + for block in msg["content"]: + if isinstance(block, dict) and block.get("type") == "text": + content.append(block.get("text", "")) + except json.JSONDecodeError: + continue + + return "\n".join(content) + + +def handle_user_prompt_submit(data: dict) -> None: + """メッセージ前フック：リクエスト前の現在のトークン数を保存。""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # 後で比較するため一時ファイルに保存 + state_file = get_state_file(session_id) + with open(state_file, "w") as f: + json.dump({"pre_tokens": current_tokens}, f) + + +def handle_stop(data: dict) -> None: + """応答後フック：トークンの差分を計算してレポート。""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # メッセージ前のカウントを読み込む + state_file = get_state_file(session_id) + pre_tokens = 0 + if os.path.exists(state_file): + try: + with open(state_file, "r") as f: + state = json.load(f) + pre_tokens = state.get("pre_tokens", 0) + except (json.JSONDecodeError, IOError): + pass + + # 差分を計算 + delta_tokens = current_tokens - pre_tokens + remaining = CONTEXT_LIMIT - current_tokens + percentage = (current_tokens / CONTEXT_LIMIT) * 100 + + # 使用量をレポート + method = "tiktoken" if USE_TIKTOKEN else "estimated" + print(f"Context ({method}): ~{current_tokens:,} tokens ({percentage:.1f}% used, ~{remaining:,} remaining)", file=sys.stderr) + if delta_tokens > 0: + print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr) + + +def main(): + data = json.load(sys.stdin) + event = data.get("hook_event_name", "") + + if event == "UserPromptSubmit": + handle_user_prompt_submit(data) + elif event == "Stop": + handle_stop(data) + + sys.exit(0) + + +if __name__ == "__main__": + main() +``` + +**設定：** +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\"" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\"" + } + ] + } + ] + } +} +``` + +**動作の仕組み：** +1. `UserPromptSubmit` がプロンプト処理前に発火し、現在のトークン数を保存 +2. `Stop` が Claude の応答後に発火し、差分を計算して使用量をレポート +3. 各セッションは一時ファイル名内の `session_id` で分離 + +**トークンカウント方式：** + +| 方式 | 精度 | 依存 | 速度 | +|------|------|------|------| +| 文字推定 | 約 80〜90% | なし | 1ms 未満 | +| tiktoken（p50k_base） | 約 90〜95% | `pip install tiktoken` | 10ms 未満 | + +> **注意：** Anthropic は公式のオフライントークナイザをリリースしていない。両方式とも近似である。トランスクリプトはユーザープロンプト、Claude の応答、ツール出力を含むが、システムプロンプトや内部コンテキストは含まれない。 + +### 例 7：自動モード権限のシード（一度限りのセットアップスクリプト） + +`~/.claude/settings.json` に Claude Code の自動モードベースラインに相当する約 67 個の安全な権限ルールをシードする一度限りのセットアップスクリプト。フックなし、将来の選択を覚えることもなし。1 回実行すれば良く、再実行しても安全（既存ルールはスキップ）。 + +**ファイル：** `09-advanced-features/setup-auto-mode-permissions.py` + +```bash +# 追加内容をプレビュー +python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run + +# 適用 +python3 09-advanced-features/setup-auto-mode-permissions.py +``` + +**追加される項目：** + +| カテゴリ | 例 | +|----------|-----| +| 組み込みツール | `Read(*)`、`Edit(*)`、`Write(*)`、`Glob(*)`、`Grep(*)`、`Agent(*)`、`WebSearch(*)` | +| Git 読み取り | `Bash(git status:*)`、`Bash(git log:*)`、`Bash(git diff:*)` | +| Git 書き込み（ローカル） | `Bash(git add:*)`、`Bash(git commit:*)`、`Bash(git checkout:*)` | +| パッケージマネージャ | `Bash(npm install:*)`、`Bash(pip install:*)`、`Bash(cargo build:*)` | +| ビルド・テスト | `Bash(make:*)`、`Bash(pytest:*)`、`Bash(go test:*)` | +| 一般的なシェル | `Bash(ls:*)`、`Bash(cat:*)`、`Bash(find:*)`、`Bash(cp:*)`、`Bash(mv:*)` | +| GitHub CLI | `Bash(gh pr view:*)`、`Bash(gh pr create:*)`、`Bash(gh issue list:*)` | + +**意図的に除外される項目**（このスクリプトでは追加されない）： +- `rm -rf`、`sudo`、force push、`git reset --hard` +- `DROP TABLE`、`kubectl delete`、`terraform destroy` +- `npm publish`、`curl | bash`、本番デプロイ + +### 例 8：学習進捗ロガー（SessionEnd） + +各 Claude Code セッション終了時に、どのモジュールを学習したかをログに残す。進捗は +`~/.claude-howto-progress.json` に保存される。これはリポジトリ外のため、`git pull` 後も +上書きされず保持される。 + +**なぜ `Stop` ではなく `SessionEnd` を使うのか？** +`Stop` は Claude の *すべての* 応答後に発火する。`SessionEnd` はセッション終了時に +1 回だけ発火する。セッション終了時の日記エントリにはまさにこれが必要である。 + +**なぜ入力に `/dev/tty` を使うのか？** +フックスクリプトはフック JSON ペイロードを `stdin` 経由で受け取る。そのため対話的な +`read` はターミナルに到達するために `/dev/tty` を直接使う必要がある。 + +**ファイル：** `06-hooks/session-end.sh` + +```bash +#!/usr/bin/env bash +# SessionEnd hook: prompts for modules worked on, then appends a session record +# to ~/.claude-howto-progress.json for persistent learning progress tracking. + +PROGRESS_FILE="$HOME/.claude-howto-progress.json" + +# ガード：このリポジトリ内でのみ実行 +if [[ "$CLAUDE_PROJECT_DIR" != *"claude-howto"* ]] && [[ "$PWD" != *"claude-howto"* ]]; then + exit 0 +fi + +if [ ! -f "$PROGRESS_FILE" ]; then + echo '{"sessions":[]}' > "$PROGRESS_FILE" +fi + +DATE=$(date +"%Y-%m-%d") +TIME=$(date +"%H:%M") + +echo "" +echo " Which modules did you work on? (e.g. 06,07 or press Enter to skip)" +echo " 01=Slash 02=Memory 03=Skills 04=Subagents 05=MCP" +echo " 06=Hooks 07=Plugins 08=Checkpoints 09=Advanced 10=CLI" +printf " > " +read -r INPUT __` パターンに従う。 + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "mcp__memory__.*", + "hooks": [ + { + "type": "command", + "command": "echo '{\"systemMessage\": \"Memory operation logged\"}'" + } + ] + } + ] + } +} +``` + +## セキュリティに関する考慮事項 + +### 免責事項 + +**自己責任で使用すること：** フックは任意のシェルコマンドを実行する。以下については利用者が単独で責任を負う。 +- 設定したコマンド +- ファイルアクセス/変更権限 +- データ損失やシステム障害の可能性 +- 本番運用前に安全な環境でフックをテストすること + +### セキュリティ上の注意点 + +- **ワークスペースの信頼が必要：** `statusLine` および `fileSuggestion` のフック出力コマンドは、有効化前にワークスペースの信頼を受け入れる必要がある。 +- **HTTP フックと環境変数：** HTTP フックは URL 内で環境変数の補間を使うために明示的な `allowedEnvVars` リストを必要とする。これにより、機密の環境変数がリモートエンドポイントへ意図せず漏洩することを防ぐ。 +- **管理対象設定の階層：** `disableAllHooks` 設定は管理対象設定の階層を尊重するようになった。つまり、組織レベルの設定でフック無効化を強制でき、個別ユーザーが上書きできない。 +- **PowerShell 自動承認（v2.1.119）：** PowerShell ツールコマンドは権限モードで Bash と同様に自動承認可能になった。Windows ユーザーが PowerShell バックエンドのシェルツールで Claude Code を実行する際の同等性が確保された。 + +### ベストプラクティス + +| 推奨 | 非推奨 | +|------|-------| +| すべての入力を検証・サニタイズ | 入力データを盲目的に信用 | +| シェル変数を引用符で囲む：`"$VAR"` | 引用符なし：`$VAR` | +| パストラバーサル（`..`）をブロック | 任意のパスを許可 | +| `$CLAUDE_PROJECT_DIR` を使った絶対パス | パスのハードコード | +| 機密ファイル（`.env`、`.git/`、鍵）をスキップ | すべてのファイルを処理 | +| まずフックを単独でテスト | 未テストのフックをデプロイ | +| HTTP フックには明示的な `allowedEnvVars` を使う | webhook へすべての環境変数を露出 | + +## デバッグ + +### デバッグモードの有効化 + +詳細なフックログを得るため、Claude をデバッグフラグ付きで実行する。 + +```bash +claude --debug +``` + +### Verbose モード + +Claude Code 内で `Ctrl+O` を押して verbose モードを有効化し、フック実行の進捗を確認する。 + +### フックを単独でテスト + +```bash +# サンプル JSON 入力でテスト +echo '{"tool_name": "Bash", "tool_input": {"command": "ls -la"}}' | python3 .claude/hooks/validate-bash.py + +# 終了コードを確認 +echo $? +``` + +## 完全な設定例 + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"", + "timeout": 10 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh\"", + "timeout": 30 + }, + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py\"", + "timeout": 10 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py\"" + } + ] + } + ], + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-init.sh\"" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Verify all tasks are complete before stopping.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +## フック実行の詳細 + +| 項目 | 動作 | +|------|------| +| **タイムアウト** | デフォルト 60 秒、コマンドごとに設定可能 | +| **並列化** | マッチしたフックはすべて並列実行 | +| **重複排除** | 同一のフックコマンドは重複排除される | +| **環境** | カレントディレクトリで Claude Code の環境のもと実行 | + +## トラブルシューティング + +### フックが実行されない +- JSON 設定の構文が正しいことを確認 +- マッチャーパターンがツール名にマッチするか確認 +- スクリプトが存在し実行可能であること：`chmod +x script.sh` +- `claude --debug` でフック実行ログを確認 +- フックが（コマンド引数ではなく）stdin から JSON を読み込んでいるか確認 + +### フックが想定外にブロックする +- サンプル JSON でフックをテスト：`echo '{"tool_name": "Write", ...}' | ./hook.py` +- 終了コードを確認：許可は 0、ブロックは 2 +- stderr 出力を確認（終了コード 2 のときに表示される） + +### JSON パースエラー +- 必ず stdin から読み込み、コマンド引数を使わない +- 適切な JSON パースを使用（文字列操作ではなく） +- 欠落フィールドを安全に処理 + +## インストール + +### Step 1：フックディレクトリの作成 +```bash +mkdir -p ~/.claude/hooks +``` + +### Step 2：フックの例をコピー +```bash +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh +``` + +### Step 3：設定ファイルでの設定 +`~/.claude/settings.json` または `.claude/settings.json` を上記のフック設定で編集する。 + +## 関連概念 + +- **[チェックポイントと巻き戻し](../08-checkpoints/)** - 会話状態の保存と復元 +- **[スラッシュコマンド](../01-slash-commands/)** - カスタムスラッシュコマンドの作成 +- **[スキル](../03-skills/)** - 再利用可能な自律機能 +- **[サブエージェント](../04-subagents/)** - 委譲タスクの実行 +- **[プラグイン](../07-plugins/)** - 拡張機能のバンドルパッケージ +- **[高度な機能](../09-advanced-features/)** - 高度な Claude Code 機能の探索 + +## 追加リソース + +- **[Official Hooks Documentation](https://code.claude.com/docs/en/hooks)** - 完全なフックリファレンス +- **[CLI Reference](https://code.claude.com/docs/en/cli-reference)** - コマンドラインインターフェースのドキュメント +- **[メモリガイド](../02-memory/)** - 永続的コンテキストの設定 + +--- + +**最終更新：** 2026 年 4 月 24 日 +**Claude Code バージョン：** 2.1.119 +**情報源：** +- https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/changelog +- https://github.com/anthropics/claude-code/releases/tag/v2.1.118 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**対応モデル：** Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/06-hooks/dependency-check.sh b/ja/06-hooks/dependency-check.sh new file mode 100755 index 0000000..a81bc34 --- /dev/null +++ b/ja/06-hooks/dependency-check.sh @@ -0,0 +1,156 @@ +#!/bin/bash +# マニフェストファイルが変更された後に、依存関係の既知の脆弱性をチェックする。 +# フック：PostToolUse:Write + +FILE=$1 + +if [ -z "$FILE" ]; then + echo "使い方: $0 " + exit 0 +fi + +# マッチング用に basename を使う — $1 は絶対パスの可能性がある +BASENAME=$(basename "$FILE") + +# 依存関係マニフェストが書き換えられた場合のみ実行 +case "$BASENAME" in + package.json|package-lock.json|yarn.lock|pnpm-lock.yaml| \ + requirements.txt|Pipfile|Pipfile.lock|pyproject.toml| \ + go.mod|go.sum| \ + Cargo.toml|Cargo.lock| \ + Gemfile|Gemfile.lock| \ + composer.json|composer.lock| \ + pom.xml|build.gradle|build.gradle.kts) + echo "📦 依存関係マニフェストを更新: $FILE — 脆弱性をスキャンしています..." + ;; + *) + exit 0 + ;; +esac + +ISSUES_FOUND=0 + +# ── npm / yarn / pnpm ──────────────────────────────────────────────────────── +if [[ "$BASENAME" == package*.json || "$BASENAME" == yarn.lock || "$BASENAME" == pnpm-lock.yaml ]]; then + if command -v npm &>/dev/null; then + echo "🔍 npm audit を実行中..." + if ! npm audit --audit-level=high --json 2>/dev/null | \ + python3 -c " +import sys, json +data = json.load(sys.stdin) +vulns = data.get('metadata', {}).get('vulnerabilities', {}) +high = vulns.get('high', 0) + vulns.get('critical', 0) +if high: + print(f' ⚠️ {high} 件の高／致命的な npm 脆弱性を検出。実行: npm audit fix') + sys.exit(1) +" 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " ✅ 高／致命的な npm 脆弱性なし" + fi + fi + + if command -v yarn &>/dev/null && [[ "$BASENAME" == yarn.lock ]]; then + echo "🔍 yarn audit を実行中..." + if ! yarn audit --level high --json 2>/dev/null | \ + grep -q '"type":"auditAdvisory"' 2>/dev/null; then + echo " ✅ 高レベルの yarn 脆弱性なし" + else + echo " ⚠️ yarn audit が脆弱性を検出。実行: yarn audit --level high" + ISSUES_FOUND=1 + fi + fi +fi + +# ── Python ─────────────────────────────────────────────────────────────────── +if [[ "$BASENAME" == requirements.txt || "$BASENAME" == Pipfile* || "$BASENAME" == pyproject.toml ]]; then + if command -v pip-audit &>/dev/null; then + echo "🔍 pip-audit を実行中..." + if pip-audit --format=json 2>/dev/null | \ + python3 -c " +import sys, json +data = json.load(sys.stdin) +vulns = [d for d in data.get('dependencies', []) if d.get('vulns')] +if vulns: + for dep in vulns: + for v in dep['vulns']: + print(f' ⚠️ {dep[\"name\"]} {dep[\"version\"]}: {v[\"id\"]} — {v[\"fix_versions\"]}') + sys.exit(1) +" 2>/dev/null; then + echo " ✅ Python の脆弱性なし" + else + ISSUES_FOUND=1 + echo " 詳細は実行: pip-audit" + fi + elif command -v safety &>/dev/null; then + echo "🔍 safety check を実行中..." + OUTPUT=$(safety check --short-report 2>&1) + EXIT_CODE=$? + if [ $EXIT_CODE -eq 0 ]; then + echo " ✅ Python の脆弱性なし" + elif echo "$OUTPUT" | grep -qiE "vulnerability|CVE|insecure"; then + echo "$OUTPUT" + ISSUES_FOUND=1 + else + echo " ⚠️ safety check が完了できなかった（ネットワークまたは設定エラー）" >&2 + fi + fi +fi + +# ── Go ─────────────────────────────────────────────────────────────────────── +if [[ "$BASENAME" == go.mod || "$BASENAME" == go.sum ]]; then + if command -v govulncheck &>/dev/null; then + echo "🔍 govulncheck を実行中..." + OUTPUT=$(govulncheck ./... 2>&1) + EXIT_CODE=$? + if [ $EXIT_CODE -eq 0 ]; then + echo " ✅ Go の脆弱性なし" + elif echo "$OUTPUT" | grep -q "Vulnerability #"; then + echo "$OUTPUT" + ISSUES_FOUND=1 + else + echo " ⚠️ govulncheck が完了できなかった: $OUTPUT" >&2 + fi + fi +fi + +# ── Rust ───────────────────────────────────────────────────────────────────── +if [[ "$BASENAME" == Cargo.toml || "$BASENAME" == Cargo.lock ]]; then + if command -v cargo-audit &>/dev/null; then + echo "🔍 cargo audit を実行中..." + if ! cargo audit 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " ✅ Rust の脆弱性なし" + fi + fi +fi + +# ── Ruby ───────────────────────────────────────────────────────────────────── +if [[ "$BASENAME" == Gemfile || "$BASENAME" == Gemfile.lock ]]; then + if command -v bundler-audit &>/dev/null; then + echo "🔍 bundler-audit を実行中..." + bundler-audit check --update 2>/dev/null || ISSUES_FOUND=1 + fi +fi + +# ── 汎用フォールバック：trivy ─────────────────────────────────────────────── +if command -v trivy &>/dev/null; then + echo "🔍 trivy fs scan を実行中..." + if ! trivy fs --exit-code 1 --severity HIGH,CRITICAL --quiet . 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " ✅ trivy は HIGH/CRITICAL の問題を検出せず" + fi +fi + +if [ "$ISSUES_FOUND" -eq 0 ]; then + echo "✅ 依存関係チェック合格 — 脆弱性は検出されませんでした" +else + echo "" + echo "⚠️ 脆弱性が検出されました。コミット前に依存関係を確認・更新してください。" + echo " このフックは助言のみで、ワークフローをブロックしません。" +fi + +# 常に exit 0 — このフックは警告のみで、ブロックしない +exit 0 diff --git a/ja/06-hooks/format-code.sh b/ja/06-hooks/format-code.sh new file mode 100644 index 0000000..c96ef15 --- /dev/null +++ b/ja/06-hooks/format-code.sh @@ -0,0 +1,49 @@ +#!/bin/bash +# 書き込み後にコードを自動整形する +# フック：PostToolUse:Write +# +# 標準入力の JSON から対象ファイルパスを読み取り、Claude がファイルを書き込んだ +# 後に、そのファイルに対して適切なフォーマッタをインプレースで実行する。 +# +# 対応：macOS、Linux、Windows（Git Bash） + +# Claude Code フックプロトコルに従い、標準入力から JSON を読み取る +INPUT=$(cat) + +# sed で file_path を抽出（全プラットフォーム互換） +FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then + exit 0 +fi + +# ファイル種別を判定して整形 +case "$FILE_PATH" in + *.js|*.jsx|*.ts|*.tsx) + if command -v prettier &> /dev/null; then + prettier --write "$FILE_PATH" 2>/dev/null + fi + ;; + *.py) + if command -v black &> /dev/null; then + black "$FILE_PATH" 2>/dev/null + fi + ;; + *.go) + if command -v gofmt &> /dev/null; then + gofmt -w "$FILE_PATH" 2>/dev/null + fi + ;; + *.rs) + if command -v rustfmt &> /dev/null; then + rustfmt "$FILE_PATH" 2>/dev/null + fi + ;; + *.java) + if command -v google-java-format &> /dev/null; then + google-java-format -i "$FILE_PATH" 2>/dev/null + fi + ;; +esac + +exit 0 diff --git a/ja/06-hooks/log-bash.sh b/ja/06-hooks/log-bash.sh new file mode 100644 index 0000000..5df5c86 --- /dev/null +++ b/ja/06-hooks/log-bash.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# すべての bash コマンドを記録する +# フック：PostToolUse:Bash +# +# 標準入力の JSON から実行コマンドを読み取り、ファイルに記録する。 +# +# 対応：macOS、Linux、Windows（Git Bash） + +# Claude Code フックプロトコルに従い、標準入力から JSON を読み取る +INPUT=$(cat) + +# tool_input から bash コマンドを抽出 +# 注：sed の [^"]* は JSON 内のエスケープされた引用符で停止する。ダブルクォートを +# 含むコマンドの場合、最初の \" までしかキャプチャできない。これは sed ベースの +# JSON パースの既知の制約だが、ロギング用途としては許容範囲。 +COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$COMMAND" ]; then + exit 0 +fi + +TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S") +LOGFILE="$HOME/.claude/bash-commands.log" + +# ログディレクトリが無ければ作成 +mkdir -p "$(dirname "$LOGFILE")" + +# コマンドを記録 +echo "[$TIMESTAMP] $COMMAND" >> "$LOGFILE" + +exit 0 diff --git a/ja/06-hooks/notify-team.sh b/ja/06-hooks/notify-team.sh new file mode 100644 index 0000000..d541c53 --- /dev/null +++ b/ja/06-hooks/notify-team.sh @@ -0,0 +1,68 @@ +#!/bin/bash +# イベント発生時に通知を送信する +# フック：PostToolUse（matcher: Bash）— bash コマンドの後に実行し、スクリプト側で git push を判別する +# 注：Claude Code にネイティブの PostPush イベントは無い。git push をトリガにするには、 +# matcher または本スクリプト内の条件で bash コマンド文字列に "git push" が含まれるかを確認する。 + +REPO_NAME=$(basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null) +COMMIT_MSG=$(git log -1 --pretty=%B 2>/dev/null) +AUTHOR=$(git log -1 --pretty=%an 2>/dev/null) +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) + +echo "📢 チームへ通知を送信しています..." + +# Slack Webhook の例（Webhook URL は自分のものに置き換える） +SLACK_WEBHOOK="${SLACK_WEBHOOK_URL:-}" + +if [ -n "$SLACK_WEBHOOK" ]; then + curl -X POST "$SLACK_WEBHOOK" \ + -H 'Content-Type: application/json' \ + -d "{ + \"text\": \"*$REPO_NAME* に新しい push がありました\", + \"attachments\": [{ + \"color\": \"good\", + \"fields\": [ + {\"title\": \"ブランチ\", \"value\": \"$BRANCH\", \"short\": true}, + {\"title\": \"作者\", \"value\": \"$AUTHOR\", \"short\": true}, + {\"title\": \"コミット\", \"value\": \"$COMMIT_MSG\"} + ] + }] + }" \ + --silent --output /dev/null + + echo "✅ Slack 通知を送信しました" +fi + +# Discord Webhook の例（Webhook URL は自分のものに置き換える） +DISCORD_WEBHOOK="${DISCORD_WEBHOOK_URL:-}" + +if [ -n "$DISCORD_WEBHOOK" ]; then + curl -X POST "$DISCORD_WEBHOOK" \ + -H 'Content-Type: application/json' \ + -d "{ + \"content\": \"**$REPO_NAME に新しい push がありました**\", + \"embeds\": [{ + \"title\": \"$COMMIT_MSG\", + \"color\": 3066993, + \"fields\": [ + {\"name\": \"ブランチ\", \"value\": \"$BRANCH\", \"inline\": true}, + {\"name\": \"作者\", \"value\": \"$AUTHOR\", \"inline\": true} + ] + }] + }" \ + --silent --output /dev/null + + echo "✅ Discord 通知を送信しました" +fi + +# Email 通知の例 +EMAIL_TO="${TEAM_EMAIL:-}" + +if [ -n "$EMAIL_TO" ]; then + echo "$AUTHOR が $REPO_NAME に push しました" | \ + mail -s "Git Push: $BRANCH" "$EMAIL_TO" + + echo "✅ Email 通知を送信しました" +fi + +exit 0 diff --git a/ja/06-hooks/pre-commit.sh b/ja/06-hooks/pre-commit.sh new file mode 100644 index 0000000..bf15aea --- /dev/null +++ b/ja/06-hooks/pre-commit.sh @@ -0,0 +1,50 @@ +#!/bin/bash +# コミット前にテストを実行する +# フック：PreToolUse（matcher: Bash）— コマンドが git commit か判定する +# 注：「PreCommit」フックイベントは存在しない。PreToolUse と Bash matcher の組み合わせで +# コマンドを検査し、git commit を検出する。 + +echo "🧪 コミット前にテストを実行しています..." + +# package.json の有無を確認（Node.js プロジェクト） +if [ -f "package.json" ]; then + if grep -q "\"test\":" package.json; then + npm test + if [ $? -ne 0 ]; then + echo "❌ テスト失敗。コミットをブロックします。" + exit 1 + fi + fi +fi + +# pytest が使えるか確認（Python プロジェクト） +if [ -f "pytest.ini" ] || [ -f "setup.py" ]; then + if command -v pytest &> /dev/null; then + pytest + if [ $? -ne 0 ]; then + echo "❌ テスト失敗。コミットをブロックします。" + exit 1 + fi + fi +fi + +# go.mod の有無を確認（Go プロジェクト） +if [ -f "go.mod" ]; then + go test ./... + if [ $? -ne 0 ]; then + echo "❌ テスト失敗。コミットをブロックします。" + exit 1 + fi +fi + +# Cargo.toml の有無を確認（Rust プロジェクト） +if [ -f "Cargo.toml" ]; then + cargo test + if [ $? -ne 0 ]; then + echo "❌ テスト失敗。コミットをブロックします。" + exit 1 + fi +fi + +echo "✅ 全テスト合格。コミットを続行します。" +exit 0 diff --git a/ja/06-hooks/pre-tool-check.sh b/ja/06-hooks/pre-tool-check.sh new file mode 100644 index 0000000..a238f78 --- /dev/null +++ b/ja/06-hooks/pre-tool-check.sh @@ -0,0 +1,128 @@ +#!/bin/bash +# Bash コマンドの事前安全チェック +# フック：PreToolUse（matcher: Bash） +# +# このフックは Bash ツールが実行されるたびに走り、破壊的またはハイリスクなシェル +# コマンドをブロック／警告する。 +# +# セットアップ： +# cp 06-hooks/pre-tool-check.sh ~/.claude/hooks/ +# chmod +x ~/.claude/hooks/pre-tool-check.sh +# +# ~/.claude/settings.json の設定例： +# { +# "hooks": { +# "PreToolUse": [ +# { +# "matcher": "Bash", +# "hooks": [ +# { +# "type": "command", +# "command": "~/.claude/hooks/pre-tool-check.sh" +# } +# ] +# } +# ] +# } +# } +# +# 入力：以下の形式の JSON を標準入力から受け取る： +# { "tool_name": "Bash", "tool_input": { "command": "..." } } +# +# 出力規約（Claude Code フックプロトコルに準拠）： +# - exit 0 → 許可。stdout には JSON（hookSpecificOutput）を出力可能。stderr は +# 黙って捨てられるため、stderr への警告出力は表示されない。許可された +# コマンドの可観測性を担保するには、監査ログファイルに書き出す。 +# - exit 2 → ブロック。stderr が Claude にブロック理由として返される。 +# ブロック理由を説明する echo は必ず `>&2` で stderr にリダイレクトする。 +# さもないと Claude Code は「No stderr output」と報告する。 +# +# 監査ログ：すべての呼び出しを以下に記録する +# $CLAUDE_PROJECT_DIR/.claude/hooks/audit.log +# 判定（BLOCK/WARN/ALLOW）と一緒に保存するため、stderr が Claude Code に捨てられる +# WARN 階層のマッチも観測できる。 + +# 標準入力から JSON 全体を読み取る +INPUT=$(cat) + +# 移植性のある sed でコマンドを抽出（macOS / Linux 双方互換） +COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +# 抽出に失敗した場合は生の入力にフォールバック +if [ -z "$COMMAND" ]; then + COMMAND="$INPUT" +fi + +# ── 監査ログ ───────────────────────────────────────────────────────────────── +# すべての呼び出しを最終判定とともに記録する。Claude Code は exit 0 のときに +# stderr を黙って捨てるため、WARN 階層を確実に観測できる唯一の手段がこれ。 +# Claude Code 外（ローカルテスト等）では $(pwd) にフォールバックする。 +LOG_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/.claude/hooks" +LOG_FILE="$LOG_DIR/audit.log" +mkdir -p "$LOG_DIR" 2>/dev/null +log_decision() { + echo "$(date -u +%FT%TZ) [$1] $COMMAND" >> "$LOG_FILE" +} + +# ── ブロックパターン ───────────────────────────────────────────────────────── +# 自動化された文脈ではほぼ確実に破壊的かつ意図的でないため、無条件にブロックする。 + +BLOCKED_PATTERNS=( + # `rm -rf /` を厳密に判定するため、`/` の後に空白か行末を要求する。 + # 部分一致だと `rm -rf /tmp/foo` のような正当ケースを誤検出してしまう。 + "rm -rf /([[:space:]]|$)" + "rm -rf \*" + "dd if=/dev/zero" + "dd if=/dev/random" + ":\(\)\{:\|:&\};:" # フォーク爆弾（正規表現メタ文字をエスケープ） + "mkfs\." # ファイルシステムのフォーマット + "format c:" # Windows のディスクフォーマット +) + +for pattern in "${BLOCKED_PATTERNS[@]}"; do + if echo "$COMMAND" | grep -qE "$pattern"; then + log_decision "BLOCK:$pattern" + # ここの echo は必ず stderr へ — Claude Code は exit 2 のとき stderr を + # ブロック理由として表面化する。stdout に書くと「No stderr output」と表示される。 + echo "❌ ブロック：破壊的な可能性のあるコマンドを検出: $pattern" >&2 + echo " コマンド: $COMMAND" >&2 + exit 2 + fi +done + +# ── 警告パターン ───────────────────────────────────────────────────────────── +# リスクは高いが意図的な場合もある。警告を記録して許可する。 + +WARNING_PATTERNS=( + "rm -rf" + "git push --force" + "git reset --hard" + "git clean -f" + "chmod -R 777" + "sudo rm" + "DROP TABLE" + "DROP DATABASE" + "truncate" +) + +MATCHED_WARNINGS="" +for pattern in "${WARNING_PATTERNS[@]}"; do + if echo "$COMMAND" | grep -qi "$pattern"; then + MATCHED_WARNINGS="${MATCHED_WARNINGS:+$MATCHED_WARNINGS,}$pattern" + # フックを手動実行する人間向けに stderr へも警告を出す。 + # Claude Code は exit 0 のときこれを捨てるため、確実な記録は監査ログ + # （WARN エントリ）参照のこと。 + echo "⚠️ 警告：ハイリスクな操作を検出: $pattern" >&2 + fi +done + +if [ -n "$MATCHED_WARNINGS" ]; then + log_decision "WARN:$MATCHED_WARNINGS" + echo " コマンド: $COMMAND" >&2 + echo " 続行します — 上記の警告を確認してから続けてください。" >&2 +else + log_decision "ALLOW" +fi + +# ── 許可 ──────────────────────────────────────────────────────────────────── +exit 0 diff --git a/ja/06-hooks/security-scan.sh b/ja/06-hooks/security-scan.sh new file mode 100644 index 0000000..b4457e2 --- /dev/null +++ b/ja/06-hooks/security-scan.sh @@ -0,0 +1,78 @@ +#!/bin/bash +# ファイル書き込み時のセキュリティスキャン +# フック：PostToolUse:Write +# +# ハードコードされたシークレット・API キー・認証情報をファイルからスキャンする。 +# 検出時は additionalContext を介して非ブロッキングの警告を出力する。 +# +# 対応：macOS、Linux、Windows（Git Bash） + +# Claude Code フックプロトコルに従い、標準入力から JSON を読み取る +INPUT=$(cat) + +# sed で file_path を抽出（Windows Git Bash を含む全プラットフォーム互換） +# grep -P（Windows Git Bash で使えない）と python3 依存を避ける +FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then + exit 0 +fi + +# バイナリファイル・ベンダディレクトリ・ビルド成果物はスキップ +case "$FILE_PATH" in + *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.woff|*.woff2|*.ttf|*.eot) exit 0 ;; + */node_modules/*|*/.git/*|*/dist/*|*/build/*) exit 0 ;; +esac + +ISSUES="" + +# ハードコードされたパスワードの検出 +# JSON 形式（"password": "value"）とコード形式（password = 'value'）の両方に対応 +# 区切り文字には \\n を使う — JSON の改行エスケープとして有効で、printf でも安全に通る +if grep -qiE '"password"[[:space:]]*:[[:space:]]*"[^"]+"' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- 警告: ハードコードされたパスワードの可能性を検出\\n" +elif grep -qiE '(password|passwd|pwd)[[:space:]]*=[[:space:]]*'"'"'[^'"'"']+'"'"'' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- 警告: ハードコードされたパスワードの可能性を検出\\n" +fi + +# ハードコードされた API キーの検出 +if grep -qiE '"(api[_-]?key|apikey|access[_-]?token)"[[:space:]]*:[[:space:]]*"[^"]+"' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- 警告: ハードコードされた API キーの可能性を検出\\n" +fi + +# ハードコードされたシークレット・トークンの検出 +if grep -qiE '(secret|token)[[:space:]]*=[[:space:]]*['"'"'"][^'"'"'"]+['"'"'"]' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- 警告: ハードコードされたシークレットまたはトークンの可能性を検出\\n" +fi + +# 秘密鍵の検出 +if grep -q "BEGIN.*PRIVATE KEY" "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- 警告: 秘密鍵を検出\\n" +fi + +# AWS アクセスキーの検出 +if grep -qE "AKIA[0-9A-Z]{16}" "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- 警告: AWS アクセスキーを検出\\n" +fi + +# semgrep が利用可能ならスキャン（JSON 出力との混在を避けるため stdout は抑止） +if command -v semgrep &> /dev/null; then + semgrep --config=auto "$FILE_PATH" --quiet >/dev/null 2>/dev/null +fi + +# trufflehog が利用可能ならスキャン（JSON 出力との混在を避けるため stdout は抑止） +if command -v trufflehog &> /dev/null; then + trufflehog filesystem "$FILE_PATH" --only-verified --quiet >/dev/null 2>/dev/null +fi + +# 問題が見つかったら additionalContext として出力（非ブロッキング警告） +# Claude Code PostToolUse プロトコルが要求する hookSpecificOutput 形式を使う +if [ -n "$ISSUES" ]; then + # ファイルパスを JSON 用にエスケープ（バックスラッシュとダブルクォート） + # ISSUES は既に \\n を区切り文字に用いている（有効な JSON エスケープ）— ダブルクォートのみエスケープする + SAFE_PATH=$(printf '%s' "$FILE_PATH" | sed 's/\\/\\\\/g; s/"/\\"/g') + SAFE_ISSUES=$(printf '%s' "$ISSUES" | sed 's/"/\\"/g') + printf '{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": "セキュリティスキャンで %s に問題を検出しました:\\n%s環境変数の使用を検討してください。"}}' "$SAFE_PATH" "$SAFE_ISSUES" +fi + +exit 0 diff --git a/ja/06-hooks/session-end.sh b/ja/06-hooks/session-end.sh new file mode 100755 index 0000000..fad1ebc --- /dev/null +++ b/ja/06-hooks/session-end.sh @@ -0,0 +1,94 @@ +#!/usr/bin/env bash +# SessionEnd フック：取り組んだモジュールを尋ね、~/.claude-howto-progress.json に +# セッション記録を追記して、学習進捗を永続的に追跡する。 +# +# Claude Code セッション終了時に 1 回だけ発火する（応答ごとではない）。 +# 標準入力にはフックの JSON ペイロードが流れているため、対話入力には /dev/tty を使う。 +# +# 導入：.claude/settings.json の "SessionEnd" イベントに登録する（下記参照）。 + +PROGRESS_FILE="$HOME/.claude-howto-progress.json" + +# ガード：このリポジトリ内でのみ動かす +if [[ "$CLAUDE_PROJECT_DIR" != *"claude-howto"* ]] && [[ "$PWD" != *"claude-howto"* ]]; then + exit 0 +fi + +# 進捗ファイルが無ければ作成 +if [ ! -f "$PROGRESS_FILE" ]; then + echo '{"sessions":[]}' > "$PROGRESS_FILE" +fi + +DATE=$(date +"%Y-%m-%d") +TIME=$(date +"%H:%M") + +echo "" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo " Claude Code — 学習セッション終了" +echo " $DATE $TIME" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" +echo " どのモジュールに取り組みましたか？（例：06,07 / Enter でスキップ）" +echo " 01=Slash 02=Memory 03=Skills 04=Subagents 05=MCP" +echo " 06=Hooks 07=Plugins 08=Checkpoints 09=Advanced 10=CLI" +echo "" +printf " > " +read -r INPUT + + + + + + Claude How To + + +# Claude Code プラグイン + +このフォルダには、複数の Claude Code 機能をひとつのインストール可能なパッケージにまとめた、完成度の高いプラグインの例が収録されている。 + +## 概要 + +Claude Code プラグインは、カスタマイズ（スラッシュコマンド、サブエージェント、MCP サーバー、フック）を束ねて 1 コマンドでインストールできるバンドル形式である。複数の機能をまとめて配布できる、最も上位の拡張機構と言える。 + +## プラグインのアーキテクチャ + +```mermaid +graph TB + A["Plugin"] + B["Slash Commands"] + C["Subagents"] + D["MCP Servers"] + E["Hooks"] + F["Configuration"] + + A -->|bundles| B + A -->|bundles| C + A -->|bundles| D + A -->|bundles| E + A -->|bundles| F +``` + +## プラグインの読み込みプロセス + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Plugin as Plugin Marketplace + participant Install as Installation + participant SlashCmds as Slash Commands + participant Subagents + participant MCPServers as MCP Servers + participant Hooks + participant Tools as Configured Tools + + User->>Claude: /plugin install pr-review + Claude->>Plugin: Download plugin manifest + Plugin-->>Claude: Return plugin definition + Claude->>Install: Extract components + Install->>SlashCmds: Configure + Install->>Subagents: Configure + Install->>MCPServers: Configure + Install->>Hooks: Configure + SlashCmds-->>Tools: Ready to use + Subagents-->>Tools: Ready to use + MCPServers-->>Tools: Ready to use + Hooks-->>Tools: Ready to use + Tools-->>Claude: Plugin installed ✅ +``` + +## プラグインの種類と配布 + +| 種別 | スコープ | 共有範囲 | 管理主体 | 例 | +|------|---------|---------|---------|----| +| Official | グローバル | 全ユーザー | Anthropic | PR Review、Security Guidance | +| Community | 公開 | 全ユーザー | コミュニティ | DevOps、Data Science | +| Organization | 社内 | チームメンバー | 企業 | 社内標準・ツール | +| Personal | 個人 | 単一ユーザー | 開発者 | 個別ワークフロー | + +## プラグイン定義の構造 + +プラグインのマニフェストは `.claude-plugin/plugin.json` の JSON 形式で記述する： + +```json +{ + "name": "my-first-plugin", + "description": "A greeting plugin", + "version": "1.0.0", + "author": { + "name": "Your Name" + }, + "homepage": "https://example.com", + "repository": "https://github.com/user/repo", + "license": "MIT" +} +``` + +## プラグイン構造の例 + +``` +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json # マニフェスト（name、description、version、author） +├── commands/ # Markdown 形式のスキル +│ ├── task-1.md +│ ├── task-2.md +│ └── workflows/ +├── agents/ # カスタムエージェント定義 +│ ├── specialist-1.md +│ ├── specialist-2.md +│ └── configs/ +├── skills/ # SKILL.md ファイルを伴うエージェントスキル +│ ├── skill-1.md +│ └── skill-2.md +├── hooks/ # hooks.json のイベントハンドラ +│ └── hooks.json +├── .mcp.json # MCP サーバーの設定 +├── .lsp.json # コードインテリジェンス用の LSP サーバー設定 +├── bin/ # プラグイン有効化中に Bash ツールの PATH に追加される実行ファイル +├── settings.json # プラグイン有効化時に適用されるデフォルト設定（現状は `agent` キーのみサポート） +├── themes/ # 任意：Claude Code のカスタムテーマを同梱（v2.1.118 以降） +├── templates/ +│ └── issue-template.md +├── scripts/ +│ ├── helper-1.sh +│ └── helper-2.py +├── docs/ +│ ├── README.md +│ └── USAGE.md +└── tests/ + └── plugin.test.js +``` + +### LSP サーバーの設定 + +プラグインはリアルタイムなコードインテリジェンス向けに Language Server Protocol（LSP）サポートを含められる。LSP サーバーは作業中の診断、コードナビゲーション、シンボル情報を提供する。 + +**設定の場所**： +- プラグインのルートディレクトリにある `.lsp.json` +- `plugin.json` 内のインライン `lsp` キー + +#### フィールドリファレンス + +| フィールド | 必須 | 説明 | +|----------|----|-----| +| `command` | はい | LSP サーバーのバイナリ（PATH 上にある必要あり） | +| `extensionToLanguage` | はい | ファイル拡張子を言語 ID にマップ | +| `args` | いいえ | サーバーへのコマンドライン引数 | +| `transport` | いいえ | 通信方式：`stdio`（デフォルト）または `socket` | +| `env` | いいえ | サーバープロセス用の環境変数 | +| `initializationOptions` | いいえ | LSP 初期化時に送るオプション | +| `settings` | いいえ | サーバーへ渡すワークスペース設定 | +| `workspaceFolder` | いいえ | ワークスペースフォルダのパスを上書き | +| `startupTimeout` | いいえ | サーバー起動を待つ最大時間（ミリ秒） | +| `shutdownTimeout` | いいえ | 正常終了を待つ最大時間（ミリ秒） | +| `restartOnCrash` | いいえ | クラッシュ時に自動再起動するか | +| `maxRestarts` | いいえ | 諦めるまでの再起動回数の上限 | + +#### 設定例 + +**Go（gopls）**： + +```json +{ + "go": { + "command": "gopls", + "args": ["serve"], + "extensionToLanguage": { + ".go": "go" + } + } +} +``` + +**Python（pyright）**： + +```json +{ + "python": { + "command": "pyright-langserver", + "args": ["--stdio"], + "extensionToLanguage": { + ".py": "python", + ".pyi": "python" + } + } +} +``` + +**TypeScript**： + +```json +{ + "typescript": { + "command": "typescript-language-server", + "args": ["--stdio"], + "extensionToLanguage": { + ".ts": "typescript", + ".tsx": "typescriptreact", + ".js": "javascript", + ".jsx": "javascriptreact" + } + } +} +``` + +#### 利用可能な LSP プラグイン + +公式マーケットプレイスには事前設定された LSP プラグインが含まれる： + +| プラグイン | 言語 | サーバーバイナリ | インストールコマンド | +|----------|------|---------------|-----------------| +| `pyright-lsp` | Python | `pyright-langserver` | `pip install pyright` | +| `typescript-lsp` | TypeScript / JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` | +| `rust-lsp` | Rust | `rust-analyzer` | `rustup component add rust-analyzer` でインストール | + +#### LSP の機能 + +設定が完了すると、LSP サーバーは以下を提供する： + +- **即時診断** — 編集直後にエラーや警告が表示される +- **コードナビゲーション** — 定義へジャンプ、参照や実装を検索 +- **ホバー情報** — ホバー時に型シグネチャやドキュメントを表示 +- **シンボル一覧** — 現在のファイルやワークスペースのシンボルを閲覧 + +## プラグインのオプション（v2.1.83 以降） + +プラグインはマニフェストの `userConfig` を介してユーザーが設定可能なオプションを宣言できる。`sensitive: true` のフィールドは平文の設定ファイルではなくシステムキーチェーンに保存される： + +```json +{ + "name": "my-plugin", + "version": "1.0.0", + "userConfig": { + "apiKey": { + "description": "API key for the service", + "sensitive": true + }, + "region": { + "description": "Deployment region", + "default": "us-east-1" + } + } +} +``` + +## 永続的なプラグインデータ（`${CLAUDE_PLUGIN_DATA}`）（v2.1.78 以降） + +プラグインは `${CLAUDE_PLUGIN_DATA}` 環境変数経由で永続的な状態保存ディレクトリにアクセスできる。このディレクトリはプラグインごとに固有で、セッションをまたいで残るため、キャッシュ・データベース・その他の永続状態の保存先に適している： + +```json +{ + "hooks": { + "PostToolUse": [ + { + "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js" + } + ] + } +} +``` + +このディレクトリはプラグインのインストール時に自動作成される。ここに保存したファイルはプラグインがアンインストールされるまで保持される。 + +### バックグラウンドモニター（v2.1.105） + +プラグインは、セッション開始時やプラグインのスキル呼び出し時に自動起動するバックグラウンドモニターを登録できる。プラグインマニフェストにトップレベルの `monitors` キーを追加する： + +```json +{ + "name": "my-plugin", + "version": "1.0.0", + "monitors": [ + { + "command": "tail -f /var/log/app.log", + "trigger": "session_start" + } + ] +} +``` + +`trigger` フィールドが受け付ける値： +- `"session_start"` — セッション開始時に自動でモニターを起動 +- `"skill_invoke"` — プラグインのスキルが呼ばれたときにモニターを起動 + +モニターは内部的に Monitor ツールを利用しており、stdout の各行を Claude が反応できるイベントとしてストリーミングする。 + +## 設定によるインラインプラグイン（`source: 'settings'`）（v2.1.80 以降） + +プラグインは、`source: 'settings'` フィールドを使って設定ファイル中にマーケットプレイスエントリとしてインラインで定義できる。これにより、別個のリポジトリやマーケットプレイスを用意せずにプラグイン定義を直接埋め込める： + +```json +{ + "pluginMarketplaces": [ + { + "name": "inline-tools", + "source": "settings", + "plugins": [ + { + "name": "quick-lint", + "source": "./local-plugins/quick-lint" + } + ] + } + ] +} +``` + +## プラグインの設定 + +プラグインはデフォルト設定を提供するために `settings.json` を同梱できる。現状サポートされるのは `agent` キーで、プラグインのメインスレッドエージェントを設定する： + +```json +{ + "agent": "agents/specialist-1.md" +} +``` + +`settings.json` を含むプラグインをインストールすると、そのデフォルト値が適用される。ユーザーは自身のプロジェクト設定やユーザー設定で上書きできる。 + +## スタンドアロン vs プラグイン方式 + +| 方式 | コマンド名 | 設定 | 向いているケース | +|------|----------|----|-------------| +| **スタンドアロン** | `/hello` | CLAUDE.md で手動セットアップ | 個人用、プロジェクト固有 | +| **プラグイン** | `/plugin-name:hello` | plugin.json で自動化 | 共有・配布・チーム利用 | + +個人で素早く使うワークフローには **スタンドアロンのスラッシュコマンド** を、複数機能をまとめてチームで共有したり配布したい場合は **プラグイン** を使う。 + +## 実用例 + +### 例 1：PR Review プラグイン + +**ファイル：** `.claude-plugin/plugin.json` + +```json +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "repository": "https://github.com/your-org/pr-review", + "license": "MIT" +} +``` + +**ファイル：** `commands/review-pr.md` + +```markdown +--- +name: Review PR +description: Start comprehensive PR review with security and testing checks +--- + +# PR Review + +This command initiates a complete pull request review including: + +1. Security analysis +2. Test coverage verification +3. Documentation updates +4. Code quality checks +5. Performance impact assessment +``` + +**ファイル：** `agents/security-reviewer.md` + +```yaml +--- +name: security-reviewer +description: Security-focused code review +tools: read, grep, diff +--- + +# Security Reviewer + +Specializes in finding security vulnerabilities: +- Authentication/authorization issues +- Data exposure +- Injection attacks +- Secure configuration +``` + +**インストール：** + +```bash +/plugin install pr-review + +# Result: +# ✅ 3 slash commands installed +# ✅ 3 subagents configured +# ✅ 2 MCP servers connected +# ✅ 4 hooks registered +# ✅ Ready to use! +``` + +### 例 2：DevOps プラグイン + +**構成要素：** + +``` +devops-automation/ +├── commands/ +│ ├── deploy.md +│ ├── rollback.md +│ ├── status.md +│ └── incident.md +├── agents/ +│ ├── deployment-specialist.md +│ ├── incident-commander.md +│ └── alert-analyzer.md +├── mcp/ +│ ├── github-config.json +│ ├── kubernetes-config.json +│ └── prometheus-config.json +├── hooks/ +│ ├── pre-deploy.js +│ ├── post-deploy.js +│ └── on-error.js +└── scripts/ + ├── deploy.sh + ├── rollback.sh + └── health-check.sh +``` + +### 例 3：Documentation プラグイン + +**同梱コンポーネント：** + +``` +documentation/ +├── commands/ +│ ├── generate-api-docs.md +│ ├── generate-readme.md +│ ├── sync-docs.md +│ └── validate-docs.md +├── agents/ +│ ├── api-documenter.md +│ ├── code-commentator.md +│ └── example-generator.md +├── mcp/ +│ ├── github-docs-config.json +│ └── slack-announce-config.json +└── templates/ + ├── api-endpoint.md + ├── function-docs.md + └── adr-template.md +``` + +## プラグインマーケットプレイス + +Anthropic が運営する公式プラグインディレクトリは `anthropics/claude-plugins-official` である。エンタープライズ管理者は社内配布用にプライベートのプラグインマーケットプレイスを作ることもできる。 + +```mermaid +graph TB + A["Plugin Marketplace"] + B["Official
anthropics/claude-plugins-official"] + C["Community
Marketplace"] + D["Enterprise
Private Registry"] + + A --> B + A --> C + A --> D + + B -->|Categories| B1["Development"] + B -->|Categories| B2["DevOps"] + B -->|Categories| B3["Documentation"] + + C -->|Search| C1["DevOps Automation"] + C -->|Search| C2["Mobile Dev"] + C -->|Search| C3["Data Science"] + + D -->|Internal| D1["Company Standards"] + D -->|Internal| D2["Legacy Systems"] + D -->|Internal| D3["Compliance"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e8f5e9,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 + style D fill:#fff3e0,stroke:#333,color:#333 +``` + +### マーケットプレイスの設定 + +エンタープライズや上級ユーザーは、設定を通じてマーケットプレイスの挙動を制御できる： + +| 設定 | 説明 | +|-----|-----| +| `extraKnownMarketplaces` | デフォルト以外のマーケットプレイスソースを追加 | +| `strictKnownMarketplaces` | ユーザーが追加できるマーケットプレイスを制限（管理者専用） | +| `blockedMarketplaces` | 管理者が管理するマーケットプレイスのブロックリスト（v2.1.119 以降は `hostPattern` / `pathPattern` の正規表現フィールドをサポート） | +| `deniedPlugins` | 管理者が管理する、特定のプラグインをインストールさせないブロックリスト | + +> **適用範囲**（v2.1.117 以降）：`blockedMarketplaces` と `strictKnownMarketplaces` は最初の追加時だけでなく、インストール・更新・リフレッシュ・自動更新といったあらゆるプラグインのライフサイクルイベントで適用される。`strictKnownMarketplaces` は管理者専用。 + +`blockedMarketplaces` でホスト / パス正規表現を使う例（v2.1.119）： + +```json +{ + "blockedMarketplaces": [ + { + "hostPattern": "^evil\\.example\\.com$", + "pathPattern": "^/marketplaces/.*" + } + ] +} +``` + +### マーケットプレイスの追加機能 + +- **デフォルトの git タイムアウト**：大規模なプラグインリポジトリ向けに 30 秒から 120 秒へ拡大 +- **カスタム npm レジストリ**：依存関係解決にカスタム npm レジストリ URL を指定可能 +- **バージョンピン留め**：再現可能な環境のためにプラグインを特定バージョンに固定 + +### マーケットプレイス定義のスキーマ + +プラグインマーケットプレイスは `.claude-plugin/marketplace.json` で定義する： + +```json +{ + "name": "my-team-plugins", + "owner": "my-org", + "plugins": [ + { + "name": "code-standards", + "source": "./plugins/code-standards", + "description": "Enforce team coding standards", + "version": "1.2.0", + "author": "platform-team" + }, + { + "name": "deploy-helper", + "source": { + "source": "github", + "repo": "my-org/deploy-helper", + "ref": "v2.0.0" + }, + "description": "Deployment automation workflows" + } + ] +} +``` + +| フィールド | 必須 | 説明 | +|----------|----|-----| +| `name` | はい | kebab-case のマーケットプレイス名 | +| `owner` | はい | マーケットプレイスを保守する組織またはユーザー | +| `plugins` | はい | プラグインエントリの配列 | +| `plugins[].name` | はい | プラグイン名（kebab-case） | +| `plugins[].source` | はい | プラグインソース（パス文字列または source オブジェクト） | +| `plugins[].description` | いいえ | プラグインの簡単な説明 | +| `plugins[].version` | いいえ | セマンティックバージョン文字列 | +| `plugins[].author` | いいえ | プラグイン作者名 | + +### プラグインソースの種類 + +プラグインは複数のソースから取得できる： + +| ソース | 構文 | 例 | +|-------|----|----| +| **相対パス** | パス文字列 | `"./plugins/my-plugin"` | +| **GitHub** | `{ "source": "github", "repo": "owner/repo" }` | `{ "source": "github", "repo": "acme/lint-plugin", "ref": "v1.0" }` | +| **Git URL** | `{ "source": "url", "url": "..." }` | `{ "source": "url", "url": "https://git.internal/plugin.git" }` | +| **Git サブディレクトリ** | `{ "source": "git-subdir", "url": "...", "path": "..." }` | `{ "source": "git-subdir", "url": "https://github.com/org/monorepo.git", "path": "packages/plugin" }` | +| **npm** | `{ "source": "npm", "package": "..." }` | `{ "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0" }` | +| **pip** | `{ "source": "pip", "package": "..." }` | `{ "source": "pip", "package": "claude-data-plugin", "version": ">=1.0" }` | + +GitHub および git ソースは、バージョンピン留め用に任意の `ref`（ブランチ / タグ）と `sha`（コミットハッシュ）フィールドをサポートする。 + +### 配布方法 + +**GitHub（推奨）**： +```bash +# Users add your marketplace +/plugin marketplace add owner/repo-name +``` + +**その他の git サービス**（完全な URL が必要）： +```bash +/plugin marketplace add https://gitlab.com/org/marketplace-repo.git +``` + +**プライベートリポジトリ**：git の credential helper や環境変数のトークン経由でサポートされる。ユーザーは対象リポジトリへの読み取り権限を持っている必要がある。 + +**公式マーケットプレイスへの提出**：[claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit) または [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit) から、Anthropic がキュレートする公式マーケットプレイスにプラグインを提出して広く配布できる。 + +### マーケットプレイスの管理 + +```bash +# Marketplace CLI commands +claude plugin marketplace add # Add marketplace (GitHub, URL, local) +claude plugin marketplace update [name] # Refresh catalog index +claude plugin marketplace remove # Remove marketplace +claude plugin marketplace list # List configured marketplaces +``` + +> **重要**：`marketplace update` はプラグインカタログ（インストール可能な一覧）を更新するだけで、インストール済みプラグインは更新しない。インストール済みプラグインを更新するには `plugin update ` を使う。 + +### Strict モード + +マーケットプレイス定義とローカルの `plugin.json` の関係を制御する： + +| 設定 | 動作 | +|-----|-----| +| `strict: true`（デフォルト） | ローカルの `plugin.json` が正で、マーケットプレイスのエントリは補足扱い | +| `strict: false` | マーケットプレイスのエントリがプラグイン定義の全てとなる | + +`strictKnownMarketplaces` による **組織の制限**： + +| 値 | 効果 | +|----|----| +| 未設定 | 制限なし — ユーザーは任意のマーケットプレイスを追加可能 | +| 空配列 `[]` | ロックダウン — マーケットプレイスを追加不可 | +| パターン配列 | 許可リスト — 一致するマーケットプレイスのみ追加可能 | + +```json +{ + "strictKnownMarketplaces": [ + "my-org/*", + "github.com/trusted-vendor/*" + ] +} +``` + +> **警告**：`strictKnownMarketplaces` を使った strict モードでは、ユーザーは許可リストにあるマーケットプレイスからしかプラグインをインストールできない。プラグイン配布を制御したいエンタープライズ環境で有用。 + +## プラグインのインストールとライフサイクル + +```mermaid +graph LR + A["Discover"] -->|Browse| B["Marketplace"] + B -->|Select| C["Plugin Page"] + C -->|View| D["Components"] + D -->|Install| E["/plugin install"] + E -->|Extract| F["Configure"] + F -->|Activate| G["Use"] + G -->|Check| H["Update"] + H -->|Available| G + G -->|Done| I["Disable"] + I -->|Later| J["Enable"] + J -->|Back| G +``` + +## プラグインの機能比較 + +| 機能 | スラッシュコマンド | スキル | サブエージェント | プラグイン | +|------|--------------|------|-------------|---------| +| **インストール** | 手動コピー | 手動コピー | 手動設定 | 1 コマンド | +| **セットアップ時間** | 5 分 | 10 分 | 15 分 | 2 分 | +| **バンドル** | 単一ファイル | 単一ファイル | 単一ファイル | 複数 | +| **バージョン管理** | 手動 | 手動 | 手動 | 自動 | +| **チーム共有** | ファイルコピー | ファイルコピー | ファイルコピー | インストール ID | +| **更新** | 手動 | 手動 | 手動 | 自動取得 | +| **依存関係** | なし | なし | なし | 含めることが可能 | +| **マーケットプレイス** | なし | なし | なし | あり | +| **配布** | リポジトリ | リポジトリ | リポジトリ | マーケットプレイス | + +## プラグイン CLI コマンド + +すべてのプラグイン操作は CLI コマンドとして利用できる： + +```bash +claude plugin install @ # Install from a marketplace +claude plugin uninstall # Remove a plugin +claude plugin update # Update installed plugin to latest version +claude plugin list # List installed plugins +claude plugin enable # Enable a disabled plugin +claude plugin disable # Disable a plugin +claude plugin validate # Validate plugin structure +claude plugin tag # Create a release git tag with version validation (v2.1.118+) +``` + +例：`claude plugin tag v0.3.0` はバージョン形式を検証し、対応する git タグを作成する。配布用にプラグインをリリースする際の推奨手順である。 + +## インストール方法 + +### マーケットプレイスから +```bash +/plugin install plugin-name +# or from CLI: +claude plugin install plugin-name@marketplace-name +``` + +### 有効化 / 無効化（スコープは自動検出） +```bash +/plugin enable plugin-name +/plugin disable plugin-name +``` + +### ローカルプラグイン（開発用） +```bash +# CLI flag for local testing (repeatable for multiple plugins) +claude --plugin-dir ./path/to/plugin +claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b +``` + +### Git リポジトリから +```bash +/plugin install github:username/repo +``` + +## 自動更新 + +Claude Code は起動時にマーケットプレイスとそこにインストール済みのプラグインを自動更新できる。 + +| マーケットプレイス種別 | 自動更新のデフォルト | 切り替え方法 | +|----------------|---------------|----------| +| Official（`claude-plugins-official`） | ✅ 有効 | `/plugin` → Marketplaces → 選択 | +| サードパーティ / ローカル | ❌ 無効 | 同じ UI パス | + +自動更新が走ると、Claude Code は次の処理を行う： +1. マーケットプレイスのカタログを更新 +2. インストール済みプラグインを最新バージョンへ更新 +3. `/reload-plugins` を促す通知を表示 + +### 環境変数 + +| 変数 | 効果 | +|-----|----| +| `DISABLE_AUTOUPDATER=1` | すべての自動更新（Claude Code + プラグイン）を無効化 | +| `DISABLE_AUTOUPDATER=1` + `FORCE_AUTOUPDATE_PLUGINS=1` | プラグインの自動更新は維持し、Claude Code 自体の更新を無効化 | + +```bash +# Disable all auto-updates +export DISABLE_AUTOUPDATER=1 + +# Keep plugin auto-updates only +export DISABLE_AUTOUPDATER=1 +export FORCE_AUTOUPDATE_PLUGINS=1 +``` + +## プラグインを作るべきとき + +```mermaid +graph TD + A["Should I create a plugin?"] + A -->|Need multiple components| B{"Multiple commands
or subagents
or MCPs?"} + B -->|Yes| C["✅ Create Plugin"] + B -->|No| D["Use Individual Feature"] + A -->|Team workflow| E{"Share with
team?"} + E -->|Yes| C + E -->|No| F["Keep as Local Setup"] + A -->|Complex setup| G{"Needs auto
configuration?"} + G -->|Yes| C + G -->|No| D +``` + +### プラグインのユースケース + +| ユースケース | 推奨 | 理由 | +|----------|----|----| +| **チームのオンボーディング** | ✅ プラグインを使う | 即時セットアップで設定がすべて整う | +| **フレームワークのセットアップ** | ✅ プラグインを使う | フレームワーク固有のコマンドをまとめられる | +| **エンタープライズ標準** | ✅ プラグインを使う | 一元配布とバージョン管理 | +| **小さなタスクの自動化** | ❌ コマンドを使う | プラグインは過剰 | +| **単一ドメインの専門知識** | ❌ スキルを使う | プラグインは重すぎる、スキルで十分 | +| **特殊な解析** | ❌ サブエージェントを使う | 手動作成またはスキルで対応 | +| **ライブデータへのアクセス** | ❌ MCP を使う | 単独で使い、バンドルしない | + +## プラグインのテスト + +公開前に、`--plugin-dir` CLI フラグ（複数指定可能）を使ってプラグインをローカルでテストする： + +```bash +claude --plugin-dir ./my-plugin +claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin +``` + +これによりプラグインを読み込んだ状態で Claude Code が起動し、次を確認できる： +- すべてのスラッシュコマンドが利用可能であること +- サブエージェントとエージェントが正しく機能すること +- MCP サーバーが正常に接続されること +- フックが実行されること +- LSP サーバーの設定 +- 設定エラーがないこと + +## ホットリロード + +プラグインは開発中のホットリロードをサポートする。プラグインのファイルを修正すると Claude Code が変更を自動検出する。次のコマンドでも強制的にリロードできる： + +```bash +/reload-plugins +``` + +これにより、セッションを再起動せずに、すべてのプラグインのマニフェスト・コマンド・エージェント・スキル・フック・MCP / LSP 設定が再読み込みされる。 + +## プラグイン向けの管理対象設定 + +管理者は管理対象設定を使って組織全体のプラグイン挙動を制御できる： + +| 設定 | 説明 | +|-----|-----| +| `enabledPlugins` | デフォルトで有効化するプラグインの許可リスト | +| `deniedPlugins` | インストールを禁止するプラグインのブロックリスト | +| `extraKnownMarketplaces` | デフォルト以外のマーケットプレイスソースを追加 | +| `strictKnownMarketplaces` | ユーザーが追加できるマーケットプレイスを制限（管理者専用、v2.1.117 以降はあらゆるプラグインのライフサイクルイベントで適用） | +| `blockedMarketplaces` | マーケットプレイスのブロックリスト（v2.1.117 以降はあらゆるライフサイクルイベントで適用、v2.1.119 以降は `hostPattern` / `pathPattern` の正規表現フィールドをサポート） | +| `allowedChannelPlugins` | リリースチャネルごとに許可するプラグインを制御 | + +これらの設定は管理対象設定ファイルで組織レベルに適用でき、ユーザーレベルの設定より優先される。 + +## プラグインのセキュリティ + +プラグインのサブエージェントは制限付きサンドボックスで動作する。プラグインのサブエージェント定義では以下のフロントマターキーは **使用不可** である： + +- `hooks` — サブエージェントはイベントハンドラを登録できない +- `mcpServers` — サブエージェントは MCP サーバーを設定できない +- `permissionMode` — サブエージェントは権限モデルを上書きできない + +これにより、プラグインが宣言したスコープを超えて権限昇格したりホスト環境を変更したりできないようにしている。 + +## プラグインの公開 + +**公開手順：** + +1. すべてのコンポーネントを含むプラグイン構造を作成 +2. `.claude-plugin/plugin.json` マニフェストを記述 +3. ドキュメント用の `README.md` を作成 +4. `claude --plugin-dir ./my-plugin` でローカルテスト +5. `claude plugin tag v0.3.0`（v2.1.118 以降）でリリースタグを作成 — バージョン文字列を検証し、対応する git タグを作成 +6. プラグインマーケットプレイスへ提出 +7. レビューと承認を受ける +8. マーケットプレイスで公開 +9. ユーザーが 1 コマンドでインストール可能になる + +**提出例：** + +```markdown +# PR Review Plugin + +## Description +Complete PR review workflow with security, testing, and documentation checks. + +## What's Included +- 3 slash commands for different review types +- 3 specialized subagents +- GitHub and CodeQL MCP integration +- Automated security scanning hooks + +## Installation +```bash +/plugin install pr-review +``` + +## Features +✅ Security analysis +✅ Test coverage checking +✅ Documentation verification +✅ Code quality assessment +✅ Performance impact analysis + +## Usage +```bash +/review-pr +/check-security +/check-tests +``` + +## Requirements +- Claude Code 1.0+ +- GitHub access +- CodeQL (optional) +``` + +## プラグイン vs 手動設定 + +**手動セットアップ（2 時間以上）：** +- スラッシュコマンドを 1 つずつインストール +- サブエージェントを個別に作成 +- MCP を別々に設定 +- フックを手動で設定 +- すべてをドキュメント化 +- チームに共有（正しく設定してくれることを祈る） + +**プラグインを使う場合（2 分）：** +```bash +/plugin install pr-review +# ✅ Everything installed and configured +# ✅ Ready to use immediately +# ✅ Team can reproduce exact setup +``` + +## ベストプラクティス + +### Do（推奨）✅ +- 明快で説明的なプラグイン名を使う +- 包括的な README を含める +- セマンティックバージョニングで適切にバージョン管理する +- すべてのコンポーネントを通しでテストする +- 必要要件を明確にドキュメント化する +- 使用例を提供する +- エラーハンドリングを含める +- 検索性を高めるタグを付ける +- 後方互換性を維持する +- プラグインを焦点を絞った一貫性ある内容に保つ +- 包括的なテストを含める +- すべての依存関係をドキュメント化する + +### Don't（避ける）❌ +- 関連のない機能を混ぜない +- 認証情報をハードコードしない +- テストを省略しない +- ドキュメントを忘れない +- 重複したプラグインを作らない +- バージョン管理を軽視しない +- コンポーネント間の依存を複雑にしすぎない +- エラーを優雅に処理することを忘れない + +## インストール手順 + +### マーケットプレイスからインストール + +1. **利用可能なプラグインを閲覧：** + ```bash + /plugin list + ``` + +2. **プラグインの詳細を表示：** + ```bash + /plugin info plugin-name + ``` + +3. **プラグインをインストール：** + ```bash + /plugin install plugin-name + ``` + +### ローカルパスからインストール + +```bash +/plugin install ./path/to/plugin-directory +``` + +### GitHub からインストール + +```bash +/plugin install github:username/repo +``` + +### インストール済みプラグインの一覧 + +```bash +/plugin list --installed +``` + +### プラグインの更新 + +```bash +/plugin update plugin-name +``` + +### プラグインの無効化 / 有効化 + +```bash +# Temporarily disable +/plugin disable plugin-name + +# Re-enable +/plugin enable plugin-name +``` + +### プラグインのアンインストール + +```bash +/plugin uninstall plugin-name +``` + +## 関連概念 + +以下の Claude Code 機能はプラグインと組み合わせて動作する： + +- **[スラッシュコマンド](../01-slash-commands/)** — プラグインに含まれる個々のコマンド +- **[メモリ](../02-memory/)** — プラグイン用の永続コンテキスト +- **[スキル](../03-skills/)** — プラグインに包めるドメイン専門知識 +- **[サブエージェント](../04-subagents/)** — プラグインのコンポーネントとして含まれる専門エージェント +- **[MCP サーバー](../05-mcp/)** — プラグインに同梱される Model Context Protocol 連携 +- **[フック](../06-hooks/)** — プラグインのワークフローを起動するイベントハンドラ + +## 完全なワークフロー例 + +### PR Review プラグインの全ワークフロー + +``` +1. User: /review-pr + +2. Plugin executes: + ├── pre-review.js hook validates git repo + ├── GitHub MCP fetches PR data + ├── security-reviewer subagent analyzes security + ├── test-checker subagent verifies coverage + └── performance-analyzer subagent checks performance + +3. Results synthesized and presented: + ✅ Security: No critical issues + ⚠️ Testing: Coverage 65% (recommend 80%+) + ✅ Performance: No significant impact + 📝 12 recommendations provided +``` + +## トラブルシューティング + +### プラグインがインストールできない +- Claude Code のバージョン互換性を確認：`/version` +- JSON バリデーターで `plugin.json` の構文を検証 +- インターネット接続を確認（リモートプラグインの場合） +- 権限を確認：`ls -la plugin/` + +### コンポーネントが読み込まれない +- `plugin.json` のパスが実際のディレクトリ構造と一致するか確認 +- ファイル権限を確認：`chmod +x scripts/` +- コンポーネントファイルの構文を確認 +- ログを確認：`/plugin debug plugin-name` + +### MCP 接続が失敗する +- 環境変数が正しく設定されているか確認 +- MCP サーバーのインストール状況と健全性を確認 +- `/mcp test` で MCP 接続を単独で確認 +- `mcp/` ディレクトリ内の MCP 設定を確認 + +### インストール後にコマンドが利用できない +- プラグインが正しくインストールされているか確認：`/plugin list --installed` +- プラグインが有効か確認：`/plugin status plugin-name` +- Claude Code を再起動：`exit` して再度開く +- 既存のコマンドと名前が衝突していないか確認 + +### フック実行の問題 +- フックファイルの権限が正しいか確認 +- フックの構文とイベント名を確認 +- フックのログでエラー詳細を確認 +- 可能ならフックを手動でテスト + +## 追加リソース + +- [公式プラグインドキュメント](https://code.claude.com/docs/en/plugins) +- [プラグインを探す](https://code.claude.com/docs/en/discover-plugins) +- [プラグインマーケットプレイス](https://code.claude.com/docs/en/plugin-marketplaces) +- [プラグインリファレンス](https://code.claude.com/docs/en/plugins-reference) +- [MCP サーバーリファレンス](https://modelcontextprotocol.io/) +- [サブエージェント設定ガイド](../04-subagents/README.md) +- [フックシステムリファレンス](../06-hooks/README.md) + +--- + +**最終更新**: 2026 年 4 月 24 日 +**Claude Code バージョン**: 2.1.119 +**出典**: +- https://code.claude.com/docs/en/plugins +- https://code.claude.com/docs/en/plugin-marketplaces +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.118 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**対応モデル**: Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/07-plugins/devops-automation/README.md b/ja/07-plugins/devops-automation/README.md new file mode 100644 index 0000000..d2e2f04 --- /dev/null +++ b/ja/07-plugins/devops-automation/README.md @@ -0,0 +1,120 @@ + + + + + + + Claude How To + + +# DevOps Automation プラグイン + +デプロイ、監視、インシデントレスポンスを統合した DevOps 自動化プラグイン。 + +## 機能 + +✅ 自動デプロイ +✅ ロールバック手順 +✅ システム健全性の監視 +✅ インシデントレスポンスのワークフロー +✅ Kubernetes 連携 + +## インストール + +```bash +/plugin install devops-automation +``` + +## 同梱内容 + +### スラッシュコマンド +- `/deploy` — 本番またはステージングへデプロイ +- `/rollback` — 前バージョンへロールバック +- `/status` — システムの健全性を確認 +- `/incident` — 本番インシデントに対応 + +### サブエージェント +- `deployment-specialist` — デプロイ作業 +- `incident-commander` — インシデント統括 +- `alert-analyzer` — システム健全性の解析 + +### MCP サーバー +- Kubernetes 連携 + +### スクリプト +- `deploy.sh` — デプロイ自動化 +- `rollback.sh` — ロールバック自動化 +- `health-check.sh` — ヘルスチェックユーティリティ + +### フック +- `pre-deploy.js` — デプロイ前検証 +- `post-deploy.js` — デプロイ後処理 + +## 使い方 + +### ステージングへデプロイ +``` +/deploy staging +``` + +### 本番へデプロイ +``` +/deploy production +``` + +### ロールバック +``` +/rollback production +``` + +### ステータス確認 +``` +/status +``` + +### インシデント対応 +``` +/incident +``` + +## 必要要件 + +- Claude Code 1.0 以上 +- Kubernetes CLI（kubectl） +- クラスタへのアクセス設定 + +## 設定 + +Kubernetes 設定をセットアップする： +```bash +export KUBECONFIG=~/.kube/config +``` + +## ワークフロー例 + +``` +User: /deploy production + +Claude: +1. Runs pre-deploy hook (validates kubectl, cluster connection) +2. Delegates to deployment-specialist subagent +3. Runs deploy.sh script +4. Monitors deployment progress via Kubernetes MCP +5. Runs post-deploy hook (waits for pods, smoke tests) +6. Provides deployment summary + +Result: +✅ Deployment complete +📦 Version: v2.1.0 +🚀 Pods: 3/3 ready +⏱️ Time: 2m 34s +``` + +--- + +**最終更新**: 2026 年 4 月 24 日 +**Claude Code バージョン**: 2.1.119 +**出典**: +- https://code.claude.com/docs/en/plugins +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**対応モデル**: Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/07-plugins/devops-automation/agents/alert-analyzer.md b/ja/07-plugins/devops-automation/agents/alert-analyzer.md new file mode 100644 index 0000000..28a3aa6 --- /dev/null +++ b/ja/07-plugins/devops-automation/agents/alert-analyzer.md @@ -0,0 +1,18 @@ + + + + +--- +name: alert-analyzer +description: 監視アラートとシステムメトリクスを解析する +tools: read, grep, bash +--- + +# Alert Analyzer + +システムの健全性とアラートを解析する： +- アラートの相関分析 +- トレンド分析 +- 根本原因の特定 +- メトリクスの可視化 +- 問題の予兆検知 diff --git a/ja/07-plugins/devops-automation/agents/deployment-specialist.md b/ja/07-plugins/devops-automation/agents/deployment-specialist.md new file mode 100644 index 0000000..7a7d414 --- /dev/null +++ b/ja/07-plugins/devops-automation/agents/deployment-specialist.md @@ -0,0 +1,18 @@ + + + + +--- +name: deployment-specialist +description: あらゆるデプロイ作業を担当する +tools: read, write, bash, grep +--- + +# Deployment Specialist + +デプロイ作業のエキスパート： +- ブルーグリーンデプロイ +- カナリアリリース +- ロールバック手順 +- ヘルスチェック +- データベースマイグレーション diff --git a/ja/07-plugins/devops-automation/agents/incident-commander.md b/ja/07-plugins/devops-automation/agents/incident-commander.md new file mode 100644 index 0000000..6854f39 --- /dev/null +++ b/ja/07-plugins/devops-automation/agents/incident-commander.md @@ -0,0 +1,18 @@ + + + + +--- +name: incident-commander +description: インシデントレスポンスを統括する +tools: read, write, bash, grep +--- + +# Incident Commander + +インシデントレスポンスを管理する： +- 重大度の評価 +- チーム調整 +- ステータス更新 +- 解決状況の追跡 +- ポストモーテムの取りまとめ diff --git a/ja/07-plugins/devops-automation/commands/deploy.md b/ja/07-plugins/devops-automation/commands/deploy.md new file mode 100644 index 0000000..4c01cce --- /dev/null +++ b/ja/07-plugins/devops-automation/commands/deploy.md @@ -0,0 +1,19 @@ + + + + +--- +name: Deploy +description: アプリケーションを本番環境またはステージング環境へデプロイする +--- + +# Deploy Application + +デプロイのワークフローを実行する： + +1. デプロイ前チェックを実行 +2. アプリケーションをビルド +3. テストを実行 +4. 対象環境へデプロイ +5. ヘルスチェックを実行 +6. Slack でチームに通知 diff --git a/ja/07-plugins/devops-automation/commands/incident.md b/ja/07-plugins/devops-automation/commands/incident.md new file mode 100644 index 0000000..7a7a5f2 --- /dev/null +++ b/ja/07-plugins/devops-automation/commands/incident.md @@ -0,0 +1,20 @@ + + + + +--- +name: Incident Response +description: 構造化された手順で本番インシデントに対応する +--- + +# Incident Response + +構造化されたインシデントレスポンスのワークフロー： + +1. インシデントレコードを作成 +2. 重大度と影響範囲を評価 +3. オンコールチームへ通知 +4. 診断情報を収集 +5. 対応活動を統率 +6. 解決内容をドキュメント化 +7. ポストモーテムを設定 diff --git a/ja/07-plugins/devops-automation/commands/rollback.md b/ja/07-plugins/devops-automation/commands/rollback.md new file mode 100644 index 0000000..d4df311 --- /dev/null +++ b/ja/07-plugins/devops-automation/commands/rollback.md @@ -0,0 +1,18 @@ + + + + +--- +name: Rollback +description: 前回のデプロイへロールバックする +--- + +# Rollback Deployment + +直前の安定バージョンへロールバックする： + +1. 前回のデプロイを特定 +2. ロールバック先が正常であることを確認 +3. ロールバック手順を実行 +4. ヘルスチェックを実行 +5. チームに通知 diff --git a/ja/07-plugins/devops-automation/commands/status.md b/ja/07-plugins/devops-automation/commands/status.md new file mode 100644 index 0000000..4b2cb0c --- /dev/null +++ b/ja/07-plugins/devops-automation/commands/status.md @@ -0,0 +1,19 @@ + + + + +--- +name: System Status +description: システム全体の健全性とステータスを確認する +--- + +# System Status Check + +全サービスにわたってシステムの健全性を確認する： + +1. Kubernetes Pod のステータスを照会 +2. データベース接続を確認 +3. API のレスポンスタイムを監視 +4. エラー率をレビュー +5. リソース使用率を確認 +6. 全体の健全性を報告 diff --git a/ja/07-plugins/documentation/README.md b/ja/07-plugins/documentation/README.md new file mode 100644 index 0000000..570eb74 --- /dev/null +++ b/ja/07-plugins/documentation/README.md @@ -0,0 +1,132 @@ + + + + + + + Claude How To + + +# Documentation プラグイン + +プロジェクトのドキュメント生成と保守を包括的に行うプラグイン。 + +## 機能 + +✅ API ドキュメント生成 +✅ README の作成と更新 +✅ ドキュメント同期 +✅ コードコメントの改善 +✅ サンプルコード生成 + +## インストール + +```bash +/plugin install documentation +``` + +## 同梱内容 + +### スラッシュコマンド +- `/generate-api-docs` — API ドキュメントを生成 +- `/generate-readme` — README を作成または更新 +- `/sync-docs` — コード変更にドキュメントを同期 +- `/validate-docs` — ドキュメントを検証 + +### サブエージェント +- `api-documenter` — API ドキュメンテーションのスペシャリスト +- `code-commentator` — コードコメントの改善 +- `example-generator` — コード例の作成 + +### テンプレート +- `api-endpoint.md` — API エンドポイントのドキュメントテンプレート +- `function-docs.md` — 関数ドキュメントのテンプレート +- `adr-template.md` — Architecture Decision Record（ADR）テンプレート + +### MCP サーバー +- ドキュメント同期のための GitHub 連携 + +## 使い方 + +### API ドキュメントを生成 +``` +/generate-api-docs +``` + +### README を作成 +``` +/generate-readme +``` + +### ドキュメントを同期 +``` +/sync-docs +``` + +### ドキュメントを検証 +``` +/validate-docs +``` + +## 必要要件 + +- Claude Code 1.0 以上 +- GitHub アクセス（任意） + +## ワークフロー例 + +``` +User: /generate-api-docs + +Claude: +1. Scans all API endpoints in /src/api/ +2. Delegates to api-documenter subagent +3. Extracts function signatures and JSDoc +4. Organizes by module/endpoint +5. Uses api-endpoint.md template +6. Generates comprehensive markdown docs +7. Includes curl, JavaScript, and Python examples + +Result: +✅ API documentation generated +📄 Files created: + - docs/api/users.md + - docs/api/auth.md + - docs/api/products.md +📊 Coverage: 23/23 endpoints documented +``` + +## テンプレートの使い方 + +### API Endpoint テンプレート +REST API エンドポイントを完全な例つきでドキュメント化する。 + +### Function Documentation テンプレート +個々の関数 / メソッドのドキュメント化に使う。 + +### ADR テンプレート +アーキテクチャ判断のドキュメント化に使う。 + +## 設定 + +ドキュメント同期用の GitHub トークンを設定する： +```bash +export GITHUB_TOKEN="your_github_token" +``` + +## ベストプラクティス + +- ドキュメントはコードの近くに置く +- コード変更とともにドキュメントも更新する +- 実用的な例を含める +- 定期的に検証する +- 一貫性のためにテンプレートを使う + +--- + +**最終更新**: 2026 年 4 月 24 日 +**Claude Code バージョン**: 2.1.119 +**出典**: +- https://code.claude.com/docs/en/plugins +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**対応モデル**: Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/07-plugins/documentation/agents/api-documenter.md b/ja/07-plugins/documentation/agents/api-documenter.md new file mode 100644 index 0000000..539b210 --- /dev/null +++ b/ja/07-plugins/documentation/agents/api-documenter.md @@ -0,0 +1,18 @@ + + + + +--- +name: api-documenter +description: API ドキュメンテーションのスペシャリスト +tools: read, write, grep +--- + +# API Documenter + +包括的な API ドキュメントを作成する： +- エンドポイントのドキュメント化 +- パラメータの説明 +- レスポンススキーマ +- コード例（curl、JS、Python） +- エラーコード diff --git a/ja/07-plugins/documentation/agents/code-commentator.md b/ja/07-plugins/documentation/agents/code-commentator.md new file mode 100644 index 0000000..e7362d9 --- /dev/null +++ b/ja/07-plugins/documentation/agents/code-commentator.md @@ -0,0 +1,18 @@ + + + + +--- +name: code-commentator +description: コードコメントとインラインドキュメントのスペシャリスト +tools: read, write, edit +--- + +# Code Commentator + +コードのドキュメント品質を向上させる： +- JSDoc / docstring コメント +- インライン説明 +- パラメータの説明 +- 戻り値の型ドキュメント +- 使用例 diff --git a/ja/07-plugins/documentation/agents/example-generator.md b/ja/07-plugins/documentation/agents/example-generator.md new file mode 100644 index 0000000..c78f642 --- /dev/null +++ b/ja/07-plugins/documentation/agents/example-generator.md @@ -0,0 +1,18 @@ + + + + +--- +name: example-generator +description: コード例とチュートリアルのスペシャリスト +tools: read, write +--- + +# Example Generator + +実用的なコード例を作成する： +- 入門ガイド +- よくあるユースケース +- 連携のサンプル +- ベストプラクティス +- トラブルシューティングのシナリオ diff --git a/ja/07-plugins/documentation/commands/generate-api-docs.md b/ja/07-plugins/documentation/commands/generate-api-docs.md new file mode 100644 index 0000000..2ed10af --- /dev/null +++ b/ja/07-plugins/documentation/commands/generate-api-docs.md @@ -0,0 +1,19 @@ + + + + +--- +name: Generate API Documentation +description: ソースコードから包括的な API ドキュメントを生成する +--- + +# API Documentation Generator + +完全な API ドキュメントを生成する： + +1. API エンドポイントをスキャン +2. 関数シグネチャと JSDoc を抽出 +3. モジュール / エンドポイントごとに整理 +4. 例つきの Markdown を作成 +5. リクエスト / レスポンスのスキーマを含める +6. エラーのドキュメントを追加 diff --git a/ja/07-plugins/documentation/commands/generate-readme.md b/ja/07-plugins/documentation/commands/generate-readme.md new file mode 100644 index 0000000..20b34b3 --- /dev/null +++ b/ja/07-plugins/documentation/commands/generate-readme.md @@ -0,0 +1,19 @@ + + + + +--- +name: Generate README +description: プロジェクト README を作成または更新する +--- + +# README Generator + +包括的な README を生成する： + +1. プロジェクト概要と説明 +2. インストール手順 +3. 使用例 +4. API ドキュメントへのリンク +5. コントリビューションガイドライン +6. ライセンス情報 diff --git a/ja/07-plugins/documentation/commands/sync-docs.md b/ja/07-plugins/documentation/commands/sync-docs.md new file mode 100644 index 0000000..c5c2951 --- /dev/null +++ b/ja/07-plugins/documentation/commands/sync-docs.md @@ -0,0 +1,18 @@ + + + + +--- +name: Sync Documentation +description: コード変更にドキュメントを同期する +--- + +# Documentation Sync + +コードベースとドキュメントを同期する： + +1. コード変更を検出 +2. 古くなったドキュメントを特定 +3. 影響を受けるドキュメントを更新 +4. サンプルが今も動くことを検証 +5. バージョン番号を更新 diff --git a/ja/07-plugins/documentation/commands/validate-docs.md b/ja/07-plugins/documentation/commands/validate-docs.md new file mode 100644 index 0000000..adbc25a --- /dev/null +++ b/ja/07-plugins/documentation/commands/validate-docs.md @@ -0,0 +1,18 @@ + + + + +--- +name: Validate Documentation +description: ドキュメントの完全性と正確性を検証する +--- + +# Documentation Validation + +ドキュメント品質を検証する： + +1. リンク切れをチェック +2. コード例を検証 +3. 完全性を確認 +4. フォーマットをチェック +5. 実際のコードと突き合わせて検証 diff --git a/ja/07-plugins/documentation/templates/adr-template.md b/ja/07-plugins/documentation/templates/adr-template.md new file mode 100644 index 0000000..9941d03 --- /dev/null +++ b/ja/07-plugins/documentation/templates/adr-template.md @@ -0,0 +1,43 @@ + + + + +# ADR [Number]: [Title] + +## ステータス +[Proposed | Accepted | Deprecated | Superseded] + +## 背景 +この判断や変更を促している、いま発生している問題は何か？ + +## 決定事項 +提案している、あるいは実施している変更は何か？ + +## 影響 +この変更により、何が容易になり、何が難しくなるか？ + +### ポジティブ +- メリット 1 +- メリット 2 + +### ネガティブ +- デメリット 1 +- デメリット 2 + +### ニュートラル +- 留意点 1 +- 留意点 2 + +## 検討した代替案 +他にどのような選択肢を検討し、なぜ採用しなかったか？ + +### 代替案 1 +内容と採用しなかった理由。 + +### 代替案 2 +内容と採用しなかった理由。 + +## 参考資料 +- 関連 ADR +- 外部ドキュメント +- 議論へのリンク diff --git a/ja/07-plugins/documentation/templates/api-endpoint.md b/ja/07-plugins/documentation/templates/api-endpoint.md new file mode 100644 index 0000000..5644432 --- /dev/null +++ b/ja/07-plugins/documentation/templates/api-endpoint.md @@ -0,0 +1,105 @@ + + + + +# [METHOD] /api/v1/[endpoint] + +## 説明 +このエンドポイントの動作の簡単な説明。 + +## 認証 +必要な認証方式（例：Bearer トークン）。 + +## パラメータ + +### Path Parameters +| Name | Type | Required | 説明 | +|------|------|----------|-----| +| id | string | Yes | リソース ID | + +### Query Parameters +| Name | Type | Required | 説明 | +|------|------|----------|-----| +| page | integer | No | ページ番号（デフォルト: 1） | +| limit | integer | No | 1 ページあたりの件数（デフォルト: 20） | + +### Request Body +```json +{ + "field": "value" +} +``` + +## レスポンス + +### 200 OK +```json +{ + "success": true, + "data": { + "id": "123", + "name": "Example" + } +} +``` + +### 400 Bad Request +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "Invalid input" + } +} +``` + +### 404 Not Found +```json +{ + "success": false, + "error": { + "code": "NOT_FOUND", + "message": "Resource not found" + } +} +``` + +## サンプル + +### cURL +```bash +curl -X GET "https://api.example.com/api/v1/endpoint" \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" +``` + +### JavaScript +```javascript +const response = await fetch('/api/v1/endpoint', { + headers: { + 'Authorization': 'Bearer token', + 'Content-Type': 'application/json' + } +}); +const data = await response.json(); +``` + +### Python +```python +import requests + +response = requests.get( + 'https://api.example.com/api/v1/endpoint', + headers={'Authorization': 'Bearer token'} +) +data = response.json() +``` + +## レート制限 +- 認証済みユーザーは 1 時間あたり 1000 リクエスト +- 公開エンドポイントは 1 時間あたり 100 リクエスト + +## 関連エンドポイント +- [GET /api/v1/related](#) +- [POST /api/v1/related](#) diff --git a/ja/07-plugins/documentation/templates/function-docs.md b/ja/07-plugins/documentation/templates/function-docs.md new file mode 100644 index 0000000..1abab0a --- /dev/null +++ b/ja/07-plugins/documentation/templates/function-docs.md @@ -0,0 +1,54 @@ + + + + +# 関数: `functionName` + +## 説明 +関数の動作の簡単な説明。 + +## シグネチャ +```typescript +function functionName(param1: Type1, param2: Type2): ReturnType +``` + +## パラメータ + +| Parameter | Type | Required | 説明 | +|-----------|------|----------|-----| +| param1 | Type1 | Yes | param1 の説明 | +| param2 | Type2 | No | param2 の説明 | + +## 戻り値 +**Type**: `ReturnType` + +返される値の説明。 + +## 例外 +- `Error`: 不正な入力が与えられたとき +- `TypeError`: 誤った型が渡されたとき + +## サンプル + +### 基本的な使い方 +```typescript +const result = functionName('value1', 'value2'); +console.log(result); +``` + +### 応用的な使い方 +```typescript +const result = functionName( + complexParam1, + { option: true } +); +``` + +## 補足 +- 追加の注意事項や警告 +- パフォーマンス上の考慮事項 +- ベストプラクティス + +## 関連項目 +- [関連関数](#) +- [API ドキュメント](#) diff --git a/ja/07-plugins/pr-review/README.md b/ja/07-plugins/pr-review/README.md new file mode 100644 index 0000000..adafbf5 --- /dev/null +++ b/ja/07-plugins/pr-review/README.md @@ -0,0 +1,104 @@ + + + + + + + Claude How To + + +# PR Review プラグイン + +セキュリティ、テスト、ドキュメントのチェックを伴う完全な PR レビューワークフロー。 + +## 機能 + +✅ セキュリティ解析 +✅ テストカバレッジのチェック +✅ ドキュメントの検証 +✅ コード品質の評価 +✅ パフォーマンス影響の解析 + +## インストール + +```bash +/plugin install pr-review +``` + +## 同梱内容 + +### スラッシュコマンド +- `/review-pr` — 包括的な PR レビュー +- `/check-security` — セキュリティ観点のレビュー +- `/check-tests` — テストカバレッジ解析 + +### サブエージェント +- `security-reviewer` — セキュリティ脆弱性の検出 +- `test-checker` — テストカバレッジ解析 +- `performance-analyzer` — パフォーマンス影響の評価 + +### MCP サーバー +- PR データ取得のための GitHub 連携 + +### フック +- `pre-review.js` — レビュー前検証 + +## 使い方 + +### 基本的な PR レビュー +``` +/review-pr +``` + +### セキュリティチェックのみ +``` +/check-security +``` + +### テストカバレッジチェック +``` +/check-tests +``` + +## 必要要件 + +- Claude Code 1.0 以上 +- GitHub アクセス +- Git リポジトリ + +## 設定 + +GitHub トークンを設定する： +```bash +export GITHUB_TOKEN="your_github_token" +``` + +## ワークフロー例 + +``` +User: /review-pr + +Claude: +1. Runs pre-review hook (validates git repo) +2. Fetches PR data via GitHub MCP +3. Delegates security review to security-reviewer subagent +4. Delegates testing to test-checker subagent +5. Delegates performance to performance-analyzer subagent +6. Synthesizes all findings +7. Provides comprehensive review report + +Result: +✅ Security: No critical issues found +⚠️ Testing: Coverage is 65%, recommend 80%+ +✅ Performance: No significant impact +📝 Recommendations: Add tests for edge cases +``` + +--- + +**最終更新**: 2026 年 4 月 24 日 +**Claude Code バージョン**: 2.1.119 +**出典**: +- https://code.claude.com/docs/en/plugins +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**対応モデル**: Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/07-plugins/pr-review/agents/performance-analyzer.md b/ja/07-plugins/pr-review/agents/performance-analyzer.md new file mode 100644 index 0000000..e2142ed --- /dev/null +++ b/ja/07-plugins/pr-review/agents/performance-analyzer.md @@ -0,0 +1,17 @@ + + + + +--- +name: performance-analyzer +description: パフォーマンス影響の解析 +tools: read, grep, bash +--- + +# Performance Analyzer + +変更によるパフォーマンス影響を評価する： +- アルゴリズムの計算量 +- データベースクエリの効率 +- メモリ使用量 +- キャッシュの活用余地 diff --git a/ja/07-plugins/pr-review/agents/security-reviewer.md b/ja/07-plugins/pr-review/agents/security-reviewer.md new file mode 100644 index 0000000..4cf54d6 --- /dev/null +++ b/ja/07-plugins/pr-review/agents/security-reviewer.md @@ -0,0 +1,17 @@ + + + + +--- +name: security-reviewer +description: セキュリティに特化したコードレビュー +tools: read, grep, bash +--- + +# Security Reviewer + +セキュリティ脆弱性の検出を専門とする： +- 認証 / 認可の問題 +- データ漏洩 +- インジェクション攻撃 +- 安全な設定 diff --git a/ja/07-plugins/pr-review/agents/test-checker.md b/ja/07-plugins/pr-review/agents/test-checker.md new file mode 100644 index 0000000..237ce72 --- /dev/null +++ b/ja/07-plugins/pr-review/agents/test-checker.md @@ -0,0 +1,17 @@ + + + + +--- +name: test-checker +description: テストカバレッジと品質の解析 +tools: read, bash, grep +--- + +# Test Checker + +テストカバレッジと品質を解析する： +- カバレッジの割合 +- 欠けているテストケース +- テスト品質の評価 +- エッジケースの特定 diff --git a/ja/07-plugins/pr-review/commands/check-security.md b/ja/07-plugins/pr-review/commands/check-security.md new file mode 100644 index 0000000..7411cfb --- /dev/null +++ b/ja/07-plugins/pr-review/commands/check-security.md @@ -0,0 +1,18 @@ + + + + +--- +name: Security Check +description: セキュリティに特化したコードレビューを実行する +--- + +# Security Check + +コード変更に対してセキュリティ観点の解析を実施する： + +1. 認証 / 認可のチェック +2. データ漏洩リスク +3. インジェクション脆弱性 +4. 暗号処理の弱点 +5. ログに含まれる機微情報 diff --git a/ja/07-plugins/pr-review/commands/check-tests.md b/ja/07-plugins/pr-review/commands/check-tests.md new file mode 100644 index 0000000..84f6716 --- /dev/null +++ b/ja/07-plugins/pr-review/commands/check-tests.md @@ -0,0 +1,18 @@ + + + + +--- +name: Test Coverage Check +description: テストカバレッジと品質を検証する +--- + +# Test Coverage Check + +テストカバレッジと品質を解析する： + +1. テストカバレッジの割合をチェック +2. テストされていないコードパスを特定 +3. テスト品質をレビュー +4. 不足しているテストケースを提案 +5. エッジケースが網羅されているかを検証 diff --git a/ja/07-plugins/pr-review/commands/review-pr.md b/ja/07-plugins/pr-review/commands/review-pr.md new file mode 100644 index 0000000..967d1a1 --- /dev/null +++ b/ja/07-plugins/pr-review/commands/review-pr.md @@ -0,0 +1,18 @@ + + + + +--- +name: Review PR +description: セキュリティチェックとテストチェックを含む包括的な PR レビューを開始する +--- + +# PR Review + +このコマンドは以下を含むプルリクエストレビューを開始する： + +1. セキュリティ解析 +2. テストカバレッジの検証 +3. ドキュメント更新 +4. コード品質チェック +5. パフォーマンス影響の評価 diff --git a/ja/08-checkpoints/README.md b/ja/08-checkpoints/README.md new file mode 100644 index 0000000..10f5502 --- /dev/null +++ b/ja/08-checkpoints/README.md @@ -0,0 +1,338 @@ + + + + + + + Claude How To + + +# チェックポイントと巻き戻し + +チェックポイントは、Claude Code セッションの会話状態を保存し、過去の地点へ巻き戻すための機能である。複数のアプローチを比較したい場合、ミスから復旧したい場合、代替案を見比べたい場合に大きな威力を発揮する。 + +## 概観 + +チェックポイントを使うと、会話状態を保存して過去の地点に戻れるため、安全に試行錯誤と複数アプローチの探索ができる。チェックポイントは会話状態のスナップショットであり、以下を含む： +- やり取りされた全メッセージ +- 加えられたファイル変更 +- ツール使用履歴 +- セッションコンテキスト + +別アプローチの試行、ミスからの復旧、代替案の比較といった場面で威力を発揮する。 + +## 主要な概念 + +| 概念 | 説明 | +|------|------| +| **Checkpoint（チェックポイント）** | メッセージ・ファイル・コンテキストを含む会話状態のスナップショット | +| **Rewind（巻き戻し）** | 過去のチェックポイントへ戻り、それ以降の変更を破棄する操作 | +| **Branch Point（分岐点）** | 複数のアプローチを試すための起点となるチェックポイント | + +## チェックポイントへのアクセス + +チェックポイントへアクセス・管理する主な方法は 2 つある。 + +### キーボードショートカット +`Esc` キーを 2 回（`Esc` + `Esc`）押すと、チェックポイントインターフェイスが開き、保存済みチェックポイントを参照できる。 + +### スラッシュコマンド +すばやくアクセスしたい場合は `/rewind` コマンド（エイリアス：`/checkpoint`）を使う： + +```bash +# 巻き戻しインターフェイスを開く +/rewind + +# またはエイリアスを利用 +/checkpoint +``` + +## 巻き戻しオプション + +巻き戻しを実行すると、5 つのオプションメニューが表示される： + +1. **Restore code and conversation** -- 指定したチェックポイントの状態にファイルとメッセージの両方を戻す +2. **Restore conversation** -- メッセージのみ巻き戻し、現在のコードはそのまま残す +3. **Restore code** -- ファイル変更のみ戻し、会話履歴は完全に維持する +4. **Summarize from here** -- そこ以降の会話を AI 生成のサマリに圧縮し、コンテキストウィンドウを解放する。選択点より前のメッセージはそのまま残る。ディスク上のファイルは変更されない。元のメッセージはセッショントランスクリプトに保存される。サマリを特定のトピックに絞るための指示を任意で与えられる。 +5. **Never mind** -- 操作をキャンセルし、現在の状態に戻る + +> **注意**: 会話を復元または要約した後、選択したメッセージの元のプロンプトが入力欄に復元され、再送信や編集ができる状態になる。 + +## 自動チェックポイント + +Claude Code は自動でチェックポイントを作成する： + +- **ユーザーの入力ごと** - 入力のたびに新しいチェックポイントが生成される +- **セッション間で保持** - 別セッションを跨いでもチェックポイントは残る +- **自動クリーンアップ** - 30 日経過したチェックポイントは自動削除される + +これにより、数分前から数日前まで、会話のどの時点へも巻き戻せる。 + +## ユースケース + +| シナリオ | ワークフロー | +|----------|-------------| +| **アプローチの探索** | 保存 → 案 A を試す → 保存 → 巻き戻し → 案 B を試す → 比較 | +| **安全なリファクタリング** | 保存 → リファクタリング → テスト → 失敗なら巻き戻し | +| **A/B テスト** | 保存 → 設計 A → 保存 → 巻き戻し → 設計 B → 比較 | +| **ミスからの復旧** | 問題に気づく → 直前の良好な状態へ巻き戻し | + +## チェックポイントの利用 + +### 一覧表示と巻き戻し + +`Esc` を 2 回押すか `/rewind` を実行するとチェックポイントブラウザが開く。タイムスタンプ付きの一覧から好きなチェックポイントを選ぶと、その状態に巻き戻る。 + +### チェックポイントの詳細 + +各チェックポイントには以下が表示される： +- 作成時のタイムスタンプ +- 変更されたファイル +- 会話内のメッセージ数 +- 使用されたツール + +## 実用例 + +### 例 1: 別アプローチを試す + +``` +User: Let's add a caching layer to the API + +Claude: I'll add Redis caching to your API endpoints... +[Makes changes at checkpoint A] + +User: Actually, let's try in-memory caching instead + +Claude: I'll rewind to explore a different approach... +[User presses Esc+Esc and rewinds to checkpoint A] +[Implements in-memory caching at checkpoint B] + +User: Now I can compare both approaches +``` + +### 例 2: ミスからの復旧 + +``` +User: Refactor the authentication module to use JWT + +Claude: I'll refactor the authentication module... +[Makes extensive changes] + +User: Wait, that broke the OAuth integration. Let's go back. + +Claude: I'll help you rewind to before the refactoring... +[User presses Esc+Esc and selects the checkpoint before the refactor] + +User: Let's try a more conservative approach this time +``` + +### 例 3: 安全な試行錯誤 + +``` +User: Let's try rewriting this in a functional style +[Creates checkpoint before experiment] + +Claude: [Makes experimental changes] + +User: The tests are failing. Let's rewind. +[User presses Esc+Esc and rewinds to the checkpoint] + +Claude: I've rewound the changes. Let's try a different approach. +``` + +### 例 4: アプローチの分岐 + +``` +User: I want to compare two database designs +[Takes note of checkpoint - call it "Start"] + +Claude: I'll create the first design... +[Implements Schema A] + +User: Now let me go back and try the second approach +[User presses Esc+Esc and rewinds to "Start"] + +Claude: Now I'll implement Schema B... +[Implements Schema B] + +User: Great! Now I have both schemas to choose from +``` + +## チェックポイントの保持期間 + +Claude Code はチェックポイントを自動管理する： + +- ユーザー入力ごとにチェックポイントが自動作成される +- 古いチェックポイントは最大 30 日まで保持される +- ストレージが無限に増えないよう自動でクリーンアップされる + +## ワークフローパターン + +### 探索のための分岐戦略 + +複数アプローチを試すとき： + +``` +1. 初期実装 → チェックポイント A +2. アプローチ 1 を試す → チェックポイント B +3. チェックポイント A に巻き戻し +4. アプローチ 2 を試す → チェックポイント C +5. B と C の結果を比較 +6. 最良案を選んで継続 +``` + +### 安全なリファクタリングのパターン + +大きな変更を加えるとき： + +``` +1. 現状 → チェックポイント（自動） +2. リファクタリング開始 +3. テスト実行 +4. 成功 → 続行 +5. 失敗 → 巻き戻して別案を試す +``` + +## ベストプラクティス + +チェックポイントは自動作成されるため、状態保存を意識せず作業に集中できる。ただし以下のポイントは押さえておくとよい。 + +### チェックポイントを効果的に使う + +✅ **やる:** +- 巻き戻し前に利用可能なチェックポイントを確認する +- 別方向を試したいときに巻き戻しを使う +- 複数アプローチの比較用にチェックポイントを残す +- 各巻き戻しオプション（コードと会話の復元、会話のみ復元、コードのみ復元、要約）の挙動を理解する + +❌ **やらない:** +- コード保全をチェックポイントだけに頼る +- ファイルシステムへの外部変更まで追跡されると思い込む +- git コミットの代わりにチェックポイントを使う + +## 設定 + +チェックポイントは Claude Code の組み込み機能で、有効化のための設定は不要である。ユーザー入力のたびにチェックポイントが自動生成される。 + +チェックポイントに関連する唯一の設定は `cleanupPeriodDays` で、セッションとチェックポイントの保持期間を制御する： + +```json +{ + "cleanupPeriodDays": 30 +} +``` + +- `cleanupPeriodDays`: セッション履歴とチェックポイントの保持日数（デフォルト: `30`） + +> **v2.1.117 のアップデート**: `cleanupPeriodDays` がチェックポイントだけでなく、ディスク上の 4 種類のキャッシュの保持期間を統合的に制御するようになった： +> +> - セッションチェックポイント +> - `~/.claude/tasks/` — 永続的なタスクリスト +> - `~/.claude/shell-snapshots/` — 取得済みのシェル環境スナップショット +> - `~/.claude/backups/` — 設定ファイル / CLAUDE.md の循環バックアップ +> +> 1 つの設定で 4 つのディレクトリが同じ日数で一律に整理される。 + +## 制限事項 + +チェックポイントには次の制限がある： + +- **bash コマンドによる変更は追跡されない** - `rm`、`mv`、`cp` などのファイルシステム操作はチェックポイントに含まれない +- **外部の変更は追跡されない** - エディタやターミナルなど Claude Code の外で行った変更は捕捉されない +- **バージョン管理の代わりにはならない** - 永続的で監査可能な変更には git を使う + +## トラブルシューティング + +### チェックポイントが見つからない + +**問題**: 期待したチェックポイントが存在しない + +**対処法**: +- チェックポイントが消去されていないか確認する +- ディスク容量を確認する +- `cleanupPeriodDays` を十分大きくする（デフォルト: 30 日） + +### 巻き戻しに失敗する + +**問題**: チェックポイントへ巻き戻せない + +**対処法**: +- 未コミットの変更が衝突していないか確認する +- チェックポイントが破損していないか確認する +- 別のチェックポイントへ戻すことを試す + +## Git との連携 + +チェックポイントは git を補完するが、置き換えるものではない： + +| 項目 | Git | チェックポイント | +|------|-----|----------------| +| 範囲 | ファイルシステム | 会話 + ファイル | +| 永続性 | 永続的 | セッション単位 | +| 粒度 | コミット単位 | 任意の地点 | +| 速度 | 比較的遅い | 即時 | +| 共有 | 可 | 限定的 | + +両者を組み合わせて使う： +1. 試行錯誤にはチェックポイントを使う +2. 確定した変更には git コミットを使う +3. git 操作の前にチェックポイントを作成する +4. 良好なチェックポイントの状態を git にコミットする + +## クイックスタートガイド + +### 基本ワークフロー + +1. **普通に作業する** - Claude Code が自動でチェックポイントを作成 +2. **戻りたくなったら** - `Esc` を 2 回押すか `/rewind` を使う +3. **チェックポイントを選ぶ** - リストから巻き戻し先を選択 +4. **復元対象を選ぶ** - コードと会話、会話のみ、コードのみ、要約、キャンセルから選択 +5. **作業を続ける** - 選んだ時点に戻った状態で再開 + +### キーボードショートカット + +- **`Esc` + `Esc`** - チェックポイントブラウザを開く +- **`/rewind`** - チェックポイントへの別アクセス手段 +- **`/checkpoint`** - `/rewind` のエイリアス + +## いつ巻き戻すかを知る：コンテキスト監視 + +チェックポイントで戻ることはできるが、*いつ*戻るべきかをどう判断するか。会話が長くなるにつれて Claude のコンテキストウィンドウは消費され、モデル品質は静かに劣化する。気づかないうちに半盲状態のモデルからコードを受け取っているかもしれない。 + +**[cc-context-stats](https://github.com/luongnv89/cc-context-stats)** は、Claude Code のステータスバーにリアルタイムの **コンテキストゾーン** を追加してこの問題を解決する。コンテキストウィンドウのどの位置にいるかを追跡し、**Plan**（緑、計画とコーディングが安全）から **Code**（黄、新しい計画は始めない）、**Dump**（橙、まとめて巻き戻す）まで段階表示する。ゾーンが切り替わったら、劣化した出力で押し切らずチェックポイントから新しく始めるべきタイミングだとわかる。 + +## 関連概念 + +- **[高度な機能](../09-advanced-features/)** - プランニングモードやその他の高度な機能 +- **[メモリ管理](../02-memory/)** - 会話履歴とコンテキストの管理 +- **[スラッシュコマンド](../01-slash-commands/)** - ユーザーが起動するショートカット +- **[フック](../06-hooks/)** - イベント駆動の自動化 +- **[プラグイン](../07-plugins/)** - バンドルされた拡張パッケージ + +## 追加リソース + +- [チェックポイント公式ドキュメント](https://code.claude.com/docs/en/checkpointing) +- [高度な機能ガイド](../09-advanced-features/) - 拡張思考などの機能 + +## まとめ + +チェックポイントは Claude Code の自動機能で、作業を失う恐れなく安全にさまざまなアプローチを試せる。ユーザー入力のたびに新しいチェックポイントが作られるため、セッションのどの時点へも戻れる。 + +主な利点： +- 複数アプローチを恐れずに試せる +- ミスからすばやく復旧できる +- 異なる解決案を並べて比較できる +- バージョン管理と安全に組み合わせられる + +注意：チェックポイントは git の代わりにはならない。試行錯誤にはチェックポイント、永続的なコード変更には git を使う。 + +--- + +**最終更新**: 2026 年 4 月 24 日 +**Claude Code バージョン**: 2.1.119 +**出典**: +- https://code.claude.com/docs/en/checkpointing +- https://code.claude.com/docs/en/settings +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +**対応モデル**: Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/08-checkpoints/checkpoint-examples.md b/ja/08-checkpoints/checkpoint-examples.md new file mode 100644 index 0000000..c2be4f8 --- /dev/null +++ b/ja/08-checkpoints/checkpoint-examples.md @@ -0,0 +1,346 @@ + + + + +# チェックポイントの例 + +Claude Code でチェックポイントを効果的に使うための実例集。 + +注意：チェックポイントはユーザー入力ごとに自動作成される。手動保存は不要である。巻き戻すには `Esc` を 2 回（`Esc+Esc`）押すか `/rewind` を使ってチェックポイントブラウザを開く。 + +## 例 1: データベースマイグレーション + +### シナリオ +MySQL から PostgreSQL へ移行したいが、直接マイグレーションと段階的なデュアルライト方式の両方を試したい。 + +### ワークフロー + +``` +User: Let's implement a direct migration from MySQL to PostgreSQL + [Checkpoint A created automatically] + +Claude: I'll implement the direct migration... +[Changes database driver, updates queries, modifies schema] + +User: Run the tests + [Checkpoint B created automatically] + +Claude: Running tests... +❌ 15 tests failing - connection pool issues + +User: This approach has issues. Let's try the dual-write pattern instead. +[User presses Esc+Esc, selects Checkpoint A, chooses "Restore code and conversation"] + +User: Now implement a dual-write pattern where we write to both databases + +Claude: I'll implement dual-write migration... +[Implements dual-write layer, gradual migration strategy] + +User: Run the tests + +Claude: Running tests... +✅ All tests passing + +User: The dual-write approach is clearly safer. Let's commit this. +``` + +## 例 2: パフォーマンス最適化 + +### シナリオ +複数のパフォーマンス最適化戦略を試す。 + +### ワークフロー + +``` +User: Let's optimize the API response time. Current: 450ms + [Checkpoint "Baseline" created automatically] + +Claude: I'll add database query caching... +[Implements Redis caching] + +User: Run performance tests + +Claude: Results: 280ms average response time (38% improvement) + +User: Let me try a different approach. +[User presses Esc+Esc, selects "Baseline" checkpoint, chooses "Restore code and conversation"] + +User: Try database query optimization instead + +Claude: I'll optimize database queries... +[Adds indexes, optimizes N+1 queries] + +User: Run performance tests + +Claude: Results: 180ms average response time (60% improvement) + +User: Let me also try a third approach. +[User presses Esc+Esc, selects "Baseline" checkpoint, chooses "Restore code and conversation"] + +User: Try response compression and CDN + +Claude: I'll add compression and CDN... +[Implements gzip, sets up CDN] + +User: Run performance tests + +Claude: Results: 320ms average response time (29% improvement) + +User: Query optimization was the best. Let me go back and combine it with caching. +[User presses Esc+Esc, selects the checkpoint after query optimization, chooses "Restore code and conversation"] + +User: Now add Redis caching on top of these optimized queries + +Claude: [Adds Redis caching on top of optimized queries] + +User: Run performance tests + +Claude: Results: 95ms average response time (79% improvement) 🎉 + +User: Perfect! This is the winner. Let's commit this. +``` + +## 例 3: UI/UX のイテレーション + +### シナリオ +ダッシュボードに複数のレイアウト案を試す。 + +### ワークフロー + +``` +User: Let's redesign the dashboard with a sidebar layout + [Checkpoint "Start" created automatically] + +Claude: [Implements sidebar layout] + +User: Show me a screenshot + +Claude: [Shows screenshot] + +User: The sidebar feels cramped. Let's try a top navigation instead. +[User presses Esc+Esc, selects "Start" checkpoint, chooses "Restore code and conversation"] + +User: Try a top navigation layout + +Claude: [Implements top navigation] + +User: Show me a screenshot + +Claude: [Shows screenshot] + +User: Better, but let's try a card-based grid layout +[User presses Esc+Esc, selects "Start" checkpoint, chooses "Restore code and conversation"] + +User: Try a card-based grid layout + +Claude: [Implements card grid] + +User: Show me a screenshot + +Claude: [Shows screenshot] + +User: This is great! But can we combine the top nav with the card grid? +[User presses Esc+Esc, selects the checkpoint after the card grid, chooses "Restore code and conversation"] + +User: Add top navigation to the card grid layout + +Claude: [Adds top navigation to card grid] + +User: Perfect! This is the final design. +``` + +## 例 4: デバッグセッション + +### シナリオ +複数の仮説を立てながら厄介なバグを追う。 + +### ワークフロー + +``` +User: There's a memory leak in the application + [Checkpoint "Before debugging" created automatically] + +Claude: Let me investigate... +[Analyzes code] + +User: I think it's in the event listeners. Let's fix those. + +Claude: [Fixes event listener cleanup] + +User: Run memory profiler + +Claude: Still leaking memory - event listeners weren't the issue + +User: Let me go back and try a different hypothesis. +[User presses Esc+Esc, selects "Before debugging" checkpoint, chooses "Restore code and conversation"] + +User: Maybe it's the database connections? + +Claude: [Implements connection pooling fixes] + +User: Run memory profiler + +Claude: Still leaking - not the connections either + +User: Let me go back and try another angle. +[User presses Esc+Esc, selects "Before debugging" checkpoint, chooses "Restore code and conversation"] + +User: Let's check for circular references + +Claude: [Finds and fixes circular references in cache] + +User: Run memory profiler + +Claude: ✅ Memory leak fixed! The circular references in the caching layer were the culprit. + +User: Excellent! Let's commit this fix. +``` + +## 例 5: API 設計の進化 + +### シナリオ +複数回のイテレーションで REST API を設計する。 + +### ワークフロー + +``` +User: Create a REST API for our blog platform + [Checkpoint "Before API design" created automatically] + +Claude: [Creates basic CRUD API] + +User: This is too simple. Let's add pagination and filtering + +Claude: [Adds pagination and filtering] + +User: We need better resource relationships + +Claude: [Implements HATEOAS links] + +User: Actually, let's try GraphQL instead of REST +[User presses Esc+Esc, selects "Before API design" checkpoint, chooses "Restore code and conversation"] + +User: Implement a GraphQL API for our blog platform instead + +Claude: [Implements GraphQL API] + +User: I think REST is better for our use case. +[User presses Esc+Esc, selects the checkpoint after HATEOAS, chooses "Restore code and conversation"] + +User: Let's finalize the REST approach. +``` + +## 例 6: 設定管理 + +### シナリオ +複数の設定方式を試す。 + +### ワークフロー + +``` +User: Move configuration to environment variables + [Checkpoint "Original config" created automatically] + +Claude: [Implements env var configuration] + +User: Test in development + +Claude: Works locally but deployment issues in production + +User: Let me try a different approach. +[User presses Esc+Esc, selects "Original config" checkpoint, chooses "Restore code and conversation"] + +User: Try a config file approach with validation + +Claude: [Implements YAML config with JSON schema validation] + +User: Test in development + +Claude: ✅ Works well, good validation errors + +User: Can we also support env vars for sensitive values? + +Claude: [Adds env var override for secrets] + +User: Test deployment + +Claude: ✅ All environments working correctly + +User: Perfect! This is production-ready. +``` + +## 例 7: テスト戦略 + +### シナリオ +包括的なテストを実装する。 + +### ワークフロー + +``` +User: Add unit tests for the auth module + [Checkpoint created automatically] + +Claude: [Adds Jest unit tests] + +User: Run tests + +Claude: 45 tests passing, 78% coverage + +User: Add integration tests too + +Claude: [Adds integration tests] + +User: Run tests + +Claude: 89 tests passing, 92% coverage, but tests are slow (3 minutes) + +User: The tests are too slow. Let's optimize. + +Claude: [Optimizes test setup, adds parallel execution] + +User: Run tests + +Claude: 89 tests passing, 92% coverage, 35 seconds ✅ + +User: Great! Now add E2E tests for critical paths + +Claude: [Adds Playwright E2E tests] + +User: Run all tests + +Claude: 112 tests passing, 94% coverage, 2 minutes + +User: Perfect balance of coverage and speed! +``` + +## 例 8: チェックポイントから要約する + +### シナリオ +長いデバッグセッションの後、コンテキストを保ったまま会話を圧縮したい。 + +### ワークフロー + +``` +User: [After 20+ messages of debugging and exploration] + +[User presses Esc+Esc, selects an early checkpoint, chooses "Summarize from here"] +[Optionally provides instructions: "Focus on what we tried and what worked"] + +Claude: [Generates a summary of the conversation from that point forward] +[Original messages are preserved in the transcript] +[The summary replaces the visible conversation, reducing context window usage] + +User: Now let's continue with the approach that worked. +``` + +## 重要なポイント + +1. **チェックポイントは自動**: ユーザー入力ごとに作成されるため手動保存は不要 +2. **`Esc+Esc` または `/rewind` を使う**: チェックポイントブラウザを開く 2 つの方法 +3. **適切な復元オプションを選ぶ**: コードのみ、会話のみ、両方、要約のうち目的に合うものを選択 +4. **試行錯誤を恐れない**: チェックポイントがあるため大胆な変更を安心して試せる +5. **git と組み合わせる**: 試行錯誤にはチェックポイント、確定したものには git を使う +6. **長いセッションは要約する**: 「Summarize from here」で会話量を扱いやすく保つ + +--- +**最終更新**: 2026 年 4 月 9 日 diff --git a/ja/09-advanced-features/README.md b/ja/09-advanced-features/README.md new file mode 100644 index 0000000..c3f8d99 --- /dev/null +++ b/ja/09-advanced-features/README.md @@ -0,0 +1,2179 @@ + + + + + + + Claude How To + + +# 高度な機能 + +Claude Code の高度な機能を網羅的に解説するガイド。プランニングモード、拡張思考、オートモード、バックグラウンドタスク、権限モード、プリントモード（非対話モード）、セッション管理、対話機能、チャンネル、音声入力、リモートコントロール、Web セッション、デスクトップアプリ、タスクリスト、プロンプト候補、Git ワークツリー、サンドボックス、マネージド設定、設定ファイルなどを扱う。 + +## 目次 + +1. [概要](#概要) +2. [プランニングモード](#プランニングモード) +3. [Ultraplan（クラウドでのプラン作成）](#ultraplanクラウドでのプラン作成) +4. [拡張思考](#拡張思考) +5. [オートモード](#オートモード) +6. [バックグラウンドタスク](#バックグラウンドタスク) +7. [Monitor ツール（イベント駆動ストリーム）](#monitor-ツールイベント駆動ストリーム) +8. [スケジュールタスク](#スケジュールタスク) +9. [権限モード](#権限モード) +10. [ヘッドレスモード](#ヘッドレスモード) +11. [セッション管理](#セッション管理) +12. [対話機能](#対話機能) +13. [TUI モード（フルスクリーン）](#tui-モードフルスクリーン) +14. [音声入力](#音声入力) +15. [チャンネル](#チャンネル) +16. [Chrome 連携](#chrome-連携) +17. [リモートコントロール](#リモートコントロール) +18. [Web セッション](#web-セッション) +19. [デスクトップアプリ](#デスクトップアプリ) +20. [タスクリスト](#タスクリスト) +21. [プロンプト候補](#プロンプト候補) +22. [Git ワークツリー](#git-ワークツリー) +23. [サンドボックス](#サンドボックス) +24. [マネージド設定（エンタープライズ）](#マネージド設定エンタープライズ) +25. [設定とコンフィグ](#設定とコンフィグ) +26. [エージェントチーム](#エージェントチーム) +27. [ベストプラクティス](#ベストプラクティス) +28. [追加リソース](#追加リソース) + +--- + +## 概要 + +Claude Code の高度な機能は、プランニング、推論、自動化、制御の各仕組みでコア機能を拡張する。これらの機能により、複雑な開発タスク、コードレビュー、自動化、複数セッション管理に対応した高度なワークフローを実現できる。 + +**主な高度な機能：** +- **プランニングモード**：コーディング前に詳細な実装計画を作成する +- **拡張思考**：複雑な問題に対する深い推論を行う +- **オートモード**：バックグラウンドの安全分類器が各アクションを実行前にレビューする（Research Preview） +- **バックグラウンドタスク**：会話をブロックせずに長時間処理を実行する +- **権限モード**：Claude が実行可能な操作を制御する（`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`） +- **プリントモード**：自動化や CI/CD のために Claude Code を非対話で実行する（`claude -p`） +- **セッション管理**：複数の作業セッションを管理する +- **対話機能**：キーボードショートカット、複数行入力、コマンド履歴 +- **音声入力**：プッシュ・トゥ・トークによる音声入力（20 言語の STT 対応） +- **チャンネル**：MCP サーバが実行中セッションにメッセージをプッシュする（Research Preview） +- **リモートコントロール**：Claude.ai または Claude アプリから Claude Code を操作する +- **Web セッション**：claude.ai/code 上でブラウザから Claude Code を実行する +- **デスクトップアプリ**：視覚的な diff レビューと複数セッション対応のスタンドアロンアプリ +- **タスクリスト**：コンテキストコンパクション後も維持される永続的なタスク追跡 +- **プロンプト候補**：コンテキストに応じたスマートなコマンド候補表示 +- **Git ワークツリー**：並列作業のための隔離されたワークツリーブランチ +- **サンドボックス**：OS レベルのファイルシステムとネットワーク隔離 +- **マネージド設定**：plist、レジストリ、マネージドファイルによるエンタープライズ展開 +- **設定**：JSON 設定ファイルで挙動をカスタマイズする + +--- + +## プランニングモード + +プランニングモードでは、複雑なタスクを実装する前に Claude が思考を巡らせ、レビューと承認が可能な詳細な計画を作成できる。 + +### プランニングモードとは + +プランニングモードは 2 段階のアプローチである： +1. **計画フェーズ**：Claude がタスクを分析し、詳細な実装計画を作成する +2. **実装フェーズ**：承認後、Claude が計画を実行する + +### プランニングモードを使うべきとき + +✅ プランニングモードが向くケース： +- 複雑な複数ファイルにまたがるリファクタリング +- 新機能の実装 +- アーキテクチャ変更 +- データベースマイグレーション +- 大規模な API 再設計 + +❌ プランニングモードが向かないケース： +- 単純なバグ修正 +- フォーマット変更 +- 単一ファイルの編集 +- 簡単な質問 + +### プランニングモードの起動 + +**スラッシュコマンド：** +```bash +/plan Implement user authentication system +``` + +**CLI フラグ：** +```bash +claude --permission-mode plan +``` + +**デフォルトとして設定：** +```json +{ + "permissions": { + "defaultMode": "plan" + } +} +``` + +**キーボードショートカット：** +- `Shift + Tab` — 権限モードを切り替える（プランモードを含む） +- `Alt + M` — 権限モードを切り替える（Windows/Linux） + +### プランニングモードのメリット + +- **構造化された実装アプローチ**：実装ステップを詳細に分解する +- **レビューと承認**：実行前に計画を承認または調整できる +- **リスクの特定**：実装前に潜在的な問題を洗い出す +- **明確なフェーズ分け**：実装フェーズとマイルストーンを整理する + +### 例：機能実装 + +``` +User: /plan Add a real-time notification system + +Claude: I'll create a plan for implementing real-time notifications. + +## Implementation Plan + +### Phase 1: Infrastructure Setup +1. Install WebSocket libraries (socket.io) +2. Set up WebSocket server +3. Configure connection management + +### Phase 2: Backend Implementation +4. Create notification service +5. Implement notification queue +6. Add database schema for notifications +7. Create API endpoints + +### Phase 3: Frontend Integration +8. Set up WebSocket client +9. Create notification UI components +10. Implement notification state management +11. Add notification permissions + +### Phase 4: Testing & Deployment +12. Write unit tests +13. Write integration tests +14. Update documentation +15. Deploy to staging + +Estimated time: 3-4 hours +Files to modify: 12 +New files to create: 8 + +Ready to proceed? (yes/no/modify plan) + +User: yes + +Claude: [Begins implementation following the plan] +``` + +### 計画の修正 + +``` +User: Modify the plan - skip the queue for now, we'll add it later + +Claude: Updated plan: +[Shows modified plan with queue removed] + +User: Looks good, proceed + +Claude: [Implements modified plan] +``` + +### プランニングモードの設定 + +プランニングモードは CLI フラグまたはスラッシュコマンドで起動する： + +```bash +# CLI でプランモードを起動 +claude --permission-mode plan + +# または REPL 内で /plan スラッシュコマンドを使う +/plan Implement user authentication system +``` + +**プラン用のモデルエイリアス：** `opusplan` をモデルエイリアスとして使うと、プランニングに Opus、実行に Sonnet を使い分けられる： + +```bash +claude --model opusplan "design and implement the new API" +``` + +**外部エディタで計画を編集：** `Ctrl+G` を押すと、現在の計画を外部エディタで開いて詳細に修正できる。 + +> **v2.1.112 アップデート：** 計画ファイルがランダムな単語ではなく、生成元プロンプトに基づいた名前で保存されるようになり、閲覧と再利用が容易になった。 + +--- + +## Ultraplan（クラウドでのプラン作成） + +> **v2.1.101 で新登場：** Ultraplan は初回起動時に Claude Code on the web のクラウド環境を自動作成するようになり、手動セットアップやコンテナ起動の待ち時間なしでドラフト作成を始められる。 + +> **注：** Ultraplan は Research Preview であり、Claude Code v2.1.91 以降が必要である。 + +`/ultraplan` は、ローカル CLI からプランニングタスクを Claude Code on the web のセッション（プランモード）に引き渡す。Claude がクラウドで計画を作成している間、ターミナルは別の作業に使え、ブラウザでドラフトをレビューしてから、同じクラウドセッションで実行するか、ターミナルにテレポートして実行するかを選べる。 + +### Ultraplan を使うべきとき + +- ターミナルより豊かなレビュー環境が欲しいとき：インラインコメント、絵文字リアクション、アウトラインのサイドバー、永続的な履歴を活用できる。 +- ローカルでコーディングを続けながら、ハンズオフでドラフトを進めたいとき：クラウドセッションがリポジトリを調査し計画を書き、CLI をブロックしない。 +- 実行前にステークホルダーのレビューが必要なとき：共有可能な Web URL がターミナルのスクロール内容を貼り付けるより便利。 + +### 必要要件 + +- Claude Code on the web アカウント +- GitHub リポジトリ（クラウドセッションが実コードに対してドラフト作成するためにクローンする） +- Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry では **利用不可** + +### 起動方法 3 種 + +- **コマンド：** `/ultraplan ` — 明示的に呼び出す。 +- **キーワード：** 通常のプロンプトに `ultraplan` を含めると、Claude がリクエストをクラウドにルーティングする。 +- **ローカル計画から：** Claude がローカルで計画を作成した後、承認ダイアログで「No, refine with Ultraplan on Claude Code on the web」を選ぶと、より深い調査のためにドラフトを引き渡せる。 + +### 利用例 + +```bash +/ultraplan migrate the auth service from sessions to JWTs +``` + +Claude が応答してクラウド環境を起動し（v2.1.101 以降は初回実行時に自動作成）、ブラウザで開けるセッションリンクを返す。 + +### ステータス表示 + +| ステータス | 意味 | +|---|---| +| `◇ ultraplan` | Claude がコードベースを調査し、計画をドラフト中 | +| `◇ ultraplan needs your input` | Claude が確認質問を持っている。セッションリンクを開いて応答する | +| `◆ ultraplan ready` | 計画がブラウザでレビュー可能になった | + +### 実行オプション + +計画が完成すると、実行経路は 2 つある。ブラウザで計画を承認して同じクラウドセッションで実行する場合、Claude がリモートで変更を実装し、Web UI からプルリクエストを開く。あるいは「Approve plan and teleport back to terminal」を選んでローカルで実装する。ターミナルテレポートのダイアログでは 3 つの選択肢が表示される： + +- **Implement here** — 現在のターミナルセッションで承認済み計画を実行する。 +- **Start new session** — 同じ作業ディレクトリで新規セッションを開いて実行する。 +- **Cancel** — 計画をファイルに保存し、後で再開できるようにする。 + +> **警告：** Ultraplan を開始するとリモートコントロールは切断される。両機能とも claude.ai/code インターフェースを共有しているため、同時に有効化できるのは一方のみである。 + +--- + +## 拡張思考 + +拡張思考により、Claude は複雑な問題について、解を提示する前により多くの時間をかけて推論できる。 + +### 拡張思考とは + +拡張思考は意図的なステップバイステップの推論プロセスで、Claude は次を行う： +- 複雑な問題の分解 +- 複数のアプローチの検討 +- トレードオフの評価 +- エッジケースの推論 + +### 拡張思考の起動 + +**キーボードショートカット：** +- `Option + T`（macOS）／ `Alt + T`（Windows/Linux）— 拡張思考を切り替える + +**自動起動：** +- 全モデル（Opus 4.7、Sonnet 4.6、Haiku 4.5）でデフォルト有効 +- Opus 4.7：適応的推論で努力度レベルを指定可能：`low`（○）、`medium`（◐）、`high`（●）、`xhigh`（Opus 4.7 限定、Opus 4.7 のローンチ以降 Claude Code でデフォルト、2026-04-16）、`max`。Opus 4.6 と Sonnet 4.6 も `low`、`medium`、`high`、`max` をサポートする（`xhigh` なし）。Opus 4.7 はネイティブで 1M トークンのコンテキストウィンドウを持つ（1M コンテキスト対応は v2.1.117 で導入された。それ以前は `/context` が Opus 4.7 を 200K ウィンドウとして誤計算し、早期の自動コンパクションを引き起こしていた）。 +- Pro/Max サブスクライバの Opus 4.6 / Sonnet 4.6：v2.1.117 でデフォルト努力度が `medium` から `high` に引き上げられた。 +- その他のモデル：固定バジェット（最大 31,999 トークン） + +**設定方法：** +- 切り替え：`Alt+T` / `Option+T`、または `/config` から +- 推論内容を表示：`Ctrl+O`（verbose モード） +- 努力度を設定：`/effort` コマンドまたは `--effort` フラグ + +**カスタムバジェット：** +```bash +export MAX_THINKING_TOKENS=1024 +``` + +**努力度レベル**（Opus 4.7、Opus 4.6、Sonnet 4.6 でサポート）： +```bash +export CLAUDE_CODE_EFFORT_LEVEL=xhigh # low (○), medium (◐), high (●), xhigh (Opus 4.7 only, default), or max +``` + +**CLI フラグ：** +```bash +claude --effort high "complex architectural review" +``` + +**スラッシュコマンド：** +``` +/effort high +``` + +> **注：** プロンプトに「ultrathink」というキーワードを含めると深い推論モードが起動する。努力度レベル `low`、`medium`、`high`、`max` は Opus 4.7、Opus 4.6、Sonnet 4.6 でサポートされる。`xhigh`（Opus 4.7 でのデフォルト）は Opus 4.7 専用である。 + +### 拡張思考のメリット + +- **深い推論**：複雑な問題に対してより多くの時間をかけて思考する +- **より良いアーキテクチャ判断**：包括的な評価に基づいて情報に基づく選択ができる +- **エッジケースの考慮**：起こりうる問題やシナリオを丁寧に検討する +- **徹底的な分析**：複雑な問題解決への構造化されたアプローチ + +### 例：アーキテクチャ判断 + +``` +User: /think Should we use microservices or a monolith for our e-commerce platform? + +Claude: Let me think through this architectural decision carefully... + + +## Context Analysis +- Team size: 5 developers +- Expected traffic: 10k daily users initially +- Need to scale to 100k+ users +- Limited DevOps resources +- 6-month timeline to MVP + +## Approach 1: Microservices +Pros: ++ Independent scaling ++ Technology flexibility ++ Team independence ++ Fault isolation + +Cons: +- Operational complexity +- Network overhead +- Distributed tracing needed +- Requires DevOps expertise +- Slower initial development + +## Approach 2: Monolith +Pros: ++ Simpler deployment ++ Faster initial development ++ Easier debugging ++ Lower operational overhead ++ Single codebase + +Cons: +- Scaling challenges later +- All-or-nothing deployments +- Technology lock-in +- Potential for tight coupling + +## Decision Factors +1. Team size (5 devs) → Favors monolith +2. DevOps resources (limited) → Favors monolith +3. Timeline (6 months) → Favors monolith +4. Future scale (100k users) → Achievable with monolith + caching +5. Complexity budget → Limited + +## Recommendation +Start with a **modular monolith**: +- Single deployment unit +- Clear module boundaries +- Clean interfaces between modules +- Prepare for future extraction to microservices if needed + +This gives you: +✓ Fast initial development +✓ Low operational complexity +✓ Option to extract services later +✓ Clear architecture + +Migration path: When you reach 50k+ users or specific modules need independent scaling, extract those modules into microservices. + + +**Recommendation**: Implement a modular monolith with clean module boundaries. + +This approach balances your current constraints (team size, timeline, DevOps resources) with future scalability needs. You can migrate specific modules to microservices later when there's a clear business need. +``` + +### 拡張思考の設定 + +拡張思考は環境変数、キーボードショートカット、CLI フラグで制御する： + +```bash +# 思考トークンのバジェットを設定 +export MAX_THINKING_TOKENS=16000 + +# 努力度レベルを設定 (Opus 4.7, Opus 4.6, Sonnet 4.6): low (○), medium (◐), high (●), xhigh (Opus 4.7 only, default), or max +export CLAUDE_CODE_EFFORT_LEVEL=xhigh +``` + +セッション中に切り替える場合は `Alt+T` / `Option+T`、努力度の設定は `/effort`、その他の設定は `/config` を使う。 + +--- + +## オートモード + +オートモードは Research Preview の権限モード（2026 年 3 月）で、バックグラウンドの安全分類器が各アクションを実行前にレビューする。Claude が自律的に作業しつつ、危険な操作はブロックできる。 + +### 必要要件 + +- **プラン：** Team、Enterprise、または API（Pro や Max プランでは利用不可） +- **モデル：** Claude Sonnet 4.6 または Opus 4.7 +- **プロバイダ：** Anthropic API のみ（Bedrock、Vertex、Foundry では非対応） +- **分類器：** Claude Sonnet 4.6 上で動作する（追加のトークンコストが発生） + +### オートモードの有効化 + +```bash +# Unlock auto mode with CLI flag (no longer required for Max subscribers on Opus 4.7 — access it directly) +claude --enable-auto-mode + +# Then cycle to it with Shift+Tab in the REPL +``` + +> **v2.1.112 アップデート：** オートモードに `--enable-auto-mode` フラグは不要になった。Max サブスクライバは Opus 4.7 で直接アクセスできる。 + +または、デフォルトの権限モードとして設定する： + +```bash +claude --permission-mode auto +``` + +設定ファイルで指定する： +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### 分類器の動作 + +バックグラウンド分類器は次の決定順で各アクションを評価する： + +1. **許可／拒否ルール** — 明示的な権限ルールが最初にチェックされる +2. **読み取り専用／編集の自動承認** — ファイル読み取りと編集は自動的に通過する +3. **分類器** — バックグラウンド分類器がアクションをレビューする +4. **フォールバック** — 連続 3 回または合計 20 回のブロック後、プロンプト確認に切り替わる + +### デフォルトでブロックされる操作 + +オートモードはデフォルトで以下をブロックする： + +| ブロック対象 | 例 | +|----------------|---------| +| パイプ経由のシェルインストール | `curl \| bash` | +| 機密データの外部送信 | API キーや認証情報のネットワーク送信 | +| 本番デプロイ | 本番を対象とするデプロイコマンド | +| 一括削除 | 大規模ディレクトリでの `rm -rf` | +| IAM の変更 | 権限とロールの変更 | +| main への強制プッシュ | `git push --force origin main` | + +### デフォルトで許可される操作 + +| 許可対象 | 例 | +|----------------|---------| +| ローカルファイル操作 | プロジェクトファイルの読み書きと編集 | +| 宣言された依存関係のインストール | マニフェスト経由の `npm install`、`pip install` | +| 読み取り専用 HTTP | ドキュメント取得のための `curl` | +| 現在のブランチへのプッシュ | `git push origin feature-branch` | + +### オートモードの設定 + +**デフォルトルールを JSON で出力：** +```bash +claude auto-mode defaults +``` + +**信頼インフラの設定：** エンタープライズ展開向けに `autoMode.environment` マネージド設定を使う。これにより、管理者は信頼できる CI/CD 環境、デプロイ先、インフラパターンを定義できる。 + +#### `"$defaults"` で既定値を拡張する（v2.1.118） + +v2.1.118 以降、`autoMode.allow`、`autoMode.soft_deny`、`autoMode.environment` は `"$defaults"` トークンを受け付ける。これにより、組み込みリストを置き換えるのではなく、ルールを **追加** できる。v2.1.118 より前では、ユーザー定義の配列が無告知で組み込み設定を上書きしていた。 + +**変更前（組み込みを置き換える — v2.1.118 より前の挙動）：** + +```json +{ + "autoMode": { + "allow": ["Bash(gh pr list:*)"] + } +} +``` + +**変更後（組み込みを拡張する — v2.1.118 以降）：** + +```json +{ + "autoMode": { + "allow": ["$defaults", "Bash(gh pr list:*)"], + "soft_deny": ["$defaults", "Bash(kubectl delete:*)"], + "environment": ["$defaults", "trusted-ci.internal"] + } +} +``` + +組織やプロジェクト固有の追加を重ねつつ、出荷時のベースラインルールを維持したいときは `"$defaults"` を使う。 + +### フォールバックの動作 + +分類器の判断が不確実な場合、オートモードはユーザーへのプロンプト確認にフォールバックする： +- **連続 3 回** の分類器ブロック後 +- セッション内で **合計 20 回** の分類器ブロック後 + +これにより、分類器が確信を持って承認できない場合でも、ユーザーは常に制御を保持できる。 + +### オートモード相当の権限を投入する（Team プラン不要） + +Team プランを持っていない場合、またはバックグラウンド分類器なしでよりシンプルなアプローチを取りたい場合は、`~/.claude/settings.json` に保守的なベースラインの安全な権限ルールを投入できる。スクリプトはまず読み取り専用とローカル検査のルールから始まり、編集、テスト、ローカル Git 書き込み、パッケージインストール、GitHub 書き込み操作などはオプトインで有効化する。 + +**ファイル：** `09-advanced-features/setup-auto-mode-permissions.py` + +```bash +# Preview what would be added (no changes written) +python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run + +# Apply the conservative baseline +python3 09-advanced-features/setup-auto-mode-permissions.py + +# Add more capability only when you need it +python3 09-advanced-features/setup-auto-mode-permissions.py --include-edits --include-tests +python3 09-advanced-features/setup-auto-mode-permissions.py --include-git-write --include-packages +``` + +このスクリプトは以下のカテゴリにわたるルールを追加する： + +| カテゴリ | 例 | +|----------|---------| +| コア読み取り専用ツール | `Read(*)`、`Glob(*)`、`Grep(*)`、`Agent(*)`、`WebSearch(*)`、`WebFetch(*)` | +| ローカル検査 | `Bash(git status:*)`、`Bash(git log:*)`、`Bash(git diff:*)`、`Bash(cat:*)` | +| オプションの編集 | `Edit(*)`、`Write(*)`、`NotebookEdit(*)` | +| オプションのテスト／ビルド | `Bash(pytest:*)`、`Bash(python3 -m pytest:*)`、`Bash(cargo test:*)` | +| オプションの Git 書き込み | `Bash(git add:*)`、`Bash(git commit:*)`、`Bash(git stash:*)` | +| Git（ローカル書き込み） | `Bash(git add:*)`、`Bash(git commit:*)`、`Bash(git checkout:*)` | +| パッケージマネージャ | `Bash(npm install:*)`、`Bash(pip install:*)`、`Bash(cargo build:*)` | +| ビルドとテスト | `Bash(make:*)`、`Bash(pytest:*)`、`Bash(go test:*)` | +| よく使うシェル | `Bash(ls:*)`、`Bash(cat:*)`、`Bash(find:*)`、`Bash(cp:*)`、`Bash(mv:*)` | +| GitHub CLI | `Bash(gh pr view:*)`、`Bash(gh pr create:*)`、`Bash(gh issue list:*)` | + +危険な操作（`rm -rf`、`sudo`、強制プッシュ、`DROP TABLE`、`terraform destroy` など）は意図的に除外されている。スクリプトは冪等であり、2 回実行してもルールは重複しない。 + +--- + +## バックグラウンドタスク + +バックグラウンドタスクにより、長時間処理を会話をブロックせずに実行できる。 + +### バックグラウンドタスクとは + +バックグラウンドタスクは作業を継続しつつ非同期で実行される： +- 長時間のテストスイート +- ビルドプロセス +- データベースマイグレーション +- デプロイスクリプト +- 解析ツール + +**基本的な使い方：** +```bash +User: Run tests in background + +Claude: Started task bg-1234 + +/task list # Show all tasks +/task status bg-1234 # Check progress +/task show bg-1234 # View output +/task cancel bg-1234 # Cancel task +``` + +### バックグラウンドタスクの起動 + +``` +User: Run the full test suite in the background + +Claude: Starting tests in background (task-id: bg-1234) +You can continue working while tests run. + +[You can continue the conversation] + +User: Meanwhile, let's refactor the auth module + +Claude: [Works on auth module while tests run in background] + +[Later, when tests complete] + +Claude: 📢 Background task bg-1234 completed: +✅ 245 tests passed +❌ 3 tests failed +View results: /task show bg-1234 +``` + +### バックグラウンドタスクの管理 + +**実行中タスクの一覧：** +``` +User: /task list + +Active background tasks: +1. [bg-1234] Running tests (50% complete, 2min remaining) +2. [bg-1235] Building Docker image (25% complete, 8min remaining) +3. [bg-1236] Deploying to staging (90% complete, 30sec remaining) +``` + +**タスクの状態確認：** +``` +User: /task status bg-1234 + +Task bg-1234: Running tests +Status: In progress +Progress: 120/245 tests (49%) +Started: 2025-11-08 10:30:15 +Estimated completion: 2025-11-08 10:34:22 +``` + +**タスク出力の表示：** +``` +User: /task show bg-1234 + +[Shows live output from the test run] +``` + +**タスクのキャンセル：** +``` +User: /task cancel bg-1234 + +Cancelled background task bg-1234 +``` + +### 例：並列開発 + +``` +User: Run the build in the background + +Claude: Starting build... (task-id: bg-5001) + +User: Also run the linter in background + +Claude: Starting linter... (task-id: bg-5002) + +User: While those run, let's implement the new API endpoint + +Claude: [Implements API endpoint while build and linter run] + +[10 minutes later] + +Claude: 📢 Build completed successfully (bg-5001) +📢 Linter found 12 issues (bg-5002) + +User: Show me the linter issues + +Claude: [Shows linter output from bg-5002] +``` + +### 設定 + +```json +{ + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5, + "notifyOnCompletion": true, + "autoCleanup": true, + "logOutput": true + } +} +``` + +--- + +## Monitor ツール（イベント駆動ストリーム） + +> **v2.1.98 で新登場：** Monitor ツールは Claude がバックグラウンドコマンドの stdout を監視し、マッチするイベントが現れた瞬間に反応できるようにする。長時間プロセスの待機にポーリングループや `sleep` を使う必要がなくなる。 + +Monitor は stdout に書き込む任意のシェルコマンドにアタッチする。コマンドからの stdout 行ごとに通知が発生し、セッションがウェイクする。Claude がコマンドを指定し、ハーネスが出力をストリーミングしてイベント発生時に配信する。基盤プロセスの起動については関連する [バックグラウンドタスク](#バックグラウンドタスク) のセクションを参照。 + +### なぜ重要か + +`/loop` や `sleep` でポーリングすると、何も変わっていなくてもサイクルごとに API ラウンドトリップを 1 回消費してしまう。Monitor はイベントが発生するまで沈黙を守り、コマンドが静かな間は **トークン消費ゼロ** で待機する。イベントが発生した瞬間に Claude は反応する — 次のポーリングティックを待つ遅延がない。数分以上動作する処理にはポーリングループより安価かつ高速である。 + +### よくある 2 つのパターン + +**ストリームフィルタ** は長時間動作するソースからの連続出力を監視する。コマンドは永続的に動作し、マッチする行ごとにイベントとなる。 + +```bash +tail -f /var/log/app.log | grep --line-buffered "ERROR" +``` + +**ポーリング・アンド・エミットフィルタ** はソースを定期的にチェックし、変化があったときだけ出力する。ネイティブストリームを持たない API、データベースなどで使う。 + +```bash +last=$(date -u +%Y-%m-%dT%H:%M:%SZ) +while true; do + gh api "repos/owner/repo/issues/123/comments?since=$last" || true + last=$(date -u +%Y-%m-%dT%H:%M:%SZ) + sleep 30 +done +``` + +### 具体例 + +「dev サーバを起動してエラーを監視して」と頼むと、Claude はサーバをバックグラウンドタスクとして起動し、Monitor フィルタ（`tail -F server.log | grep --line-buffered -E "ERROR|FATAL"`）をアタッチする。セッションは静かになる。ログにエラー行が現れた瞬間、Claude は目覚めてエラーを読み、反応できる — サーバ再起動、バグ修正、ユーザーへの通知のいずれも、ユーザーが状況確認に来なくても可能になる。 + +> **警告：** `grep` にパイプするときは **必ず** `grep --line-buffered` を使う。これがないと grep は stdout を 4KB チャンクでバッファリングし、低トラフィックのストリームでは数分の遅延が生じることがある。これは Monitor が実運用で壊れる最大の原因である。フィルタが本来鳴るはずなのに沈黙している場合、まず `--line-buffered` フラグを確認すること。 + +--- + +## スケジュールタスク + +スケジュールタスクを使うと、定期スケジュールで自動的にプロンプトを実行したり、1 回だけのリマインダーとして実行したりできる。タスクはセッションスコープ — Claude Code が動作している間だけ実行され、セッション終了時にクリアされる。v2.1.72 以降で利用可能。 + +### `/loop` コマンド + +```bash +# Explicit interval +/loop 5m check if the deployment finished + +# Natural language +/loop check build status every 30 minutes +``` + +正確なスケジューリングのため、標準 5 フィールドの cron 式もサポートされる。 + +### 1 回限りのリマインダー + +特定の時刻に 1 回だけ実行するリマインダーを設定できる： + +``` +remind me at 3pm to push the release branch +in 45 minutes, run the integration tests +``` + +### スケジュールタスクの管理 + +| ツール | 説明 | +|------|-------------| +| `CronCreate` | 新規スケジュールタスクを作成する | +| `CronList` | アクティブなスケジュールタスクを一覧表示する | +| `CronDelete` | スケジュールタスクを削除する | + +**制限と挙動：** +- セッションあたり最大 **50 個のスケジュールタスク** +- セッションスコープ — セッション終了時にクリアされる +- 定期タスクは **3 日後** に自動失効する +- タスクは Claude Code の動作中のみ実行される — 取りこぼしの追加実行はない + +### 挙動の詳細 + +| 項目 | 詳細 | +|--------|--------| +| **定期実行のジッタ** | 間隔の最大 10%（最大 15 分） | +| **1 回限りのジッタ** | :00／:30 境界で最大 90 秒 | +| **取りこぼし** | キャッチアップなし — Claude Code が動いていなければスキップされる | +| **永続化** | 再起動をまたいで保持されない | + +### クラウドスケジュールタスク + +`/schedule` を使うと、Anthropic のインフラ上で動作するクラウドスケジュールタスクを作成できる： + +``` +/schedule daily at 9am run the test suite and report failures +``` + +クラウドスケジュールタスクは再起動をまたいで永続化され、Claude Code をローカルで動かす必要はない。 + +### スケジュールタスクの無効化 + +```bash +export CLAUDE_CODE_DISABLE_CRON=1 +``` + +### 例：デプロイの監視 + +``` +/loop 5m check the deployment status of the staging environment. + If the deploy succeeded, notify me and stop looping. + If it failed, show the error logs. +``` + +> **ヒント：** スケジュールタスクはセッションスコープである。再起動後も生き残る永続的な自動化には、CI/CD パイプライン、GitHub Actions、デスクトップアプリのスケジュールタスクを使う。 + +--- + +## 権限モード + +権限モードは、明示的な承認なしに Claude が実行できる操作を制御する。 + +### 利用可能な権限モード + +| モード | 挙動 | +|---|---| +| `default` | ファイル読み取りのみ。それ以外の操作は確認を求める | +| `acceptEdits` | ファイル読み取りと編集を許可。コマンドは確認を求める | +| `plan` | ファイル読み取りのみ（リサーチモード、編集なし） | +| `auto` | バックグラウンドの安全分類器のチェック付きで全操作を許可（Research Preview） | +| `bypassPermissions` | 全操作、権限チェックなし（危険） | +| `dontAsk` | 事前承認済みツールのみ実行、その他はすべて拒否 | + +CLI では `Shift+Tab` でモードを切り替える。デフォルトは `--permission-mode` フラグまたは `permissions.defaultMode` 設定で指定する。 + +### 起動方法 + +**キーボードショートカット：** +```bash +Shift + Tab # Cycle through all 6 modes +``` + +**スラッシュコマンド：** +```bash +/plan # Enter plan mode +``` + +**CLI フラグ：** +```bash +claude --permission-mode plan +claude --permission-mode auto +``` + +**設定：** +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### 権限モードの例 + +#### Default モード +Claude は重要な操作の前に確認を求める： + +``` +User: Fix the bug in auth.ts + +Claude: I need to modify src/auth.ts to fix the bug. +The change will update the password validation logic. + +Approve this change? (yes/no/show) +``` + +#### Plan モード +実行前に実装計画をレビューする： + +``` +User: /plan Implement user authentication system + +Claude: I'll create a plan for implementing authentication. + +## Implementation Plan +[Detailed plan with phases and steps] + +Ready to proceed? (yes/no/modify) +``` + +#### Accept Edits モード +ファイル変更を自動承認する： + +``` +User: acceptEdits +User: Fix the bug in auth.ts + +Claude: [Makes changes without asking] +``` + +### ユースケース + +**コードレビュー：** +``` +User: claude --permission-mode plan +User: Review this PR and suggest improvements + +Claude: [Reads code, provides feedback, but cannot modify] +``` + +**ペアプログラミング：** +``` +User: claude --permission-mode default +User: Let's implement the feature together + +Claude: [Asks for approval before each change] +``` + +**自動化タスク：** +``` +User: claude --permission-mode acceptEdits +User: Fix all linting issues in the codebase + +Claude: [Auto-accepts file edits without asking] +``` + +--- + +## ヘッドレスモード + +プリントモード（`claude -p`）により Claude Code を対話入力なしで実行できる。自動化や CI/CD に最適である。これは非対話モードであり、旧来の `--headless` フラグを置き換える。 + +### プリントモードとは + +プリントモードでは次が可能になる： +- スクリプトの自動実行 +- CI/CD 統合 +- バッチ処理 +- スケジュールタスク + +### プリントモードでの実行（非対話） + +```bash +# Run specific task +claude -p "Run all tests" + +# Process piped content +cat error.log | claude -p "Analyze these errors" + +# CI/CD integration (GitHub Actions) +- name: AI Code Review + run: claude -p "Review PR" +``` + +### プリントモードのその他の使用例 + +```bash +# Run a specific task with output capture +claude -p "Run all tests and generate coverage report" + +# With structured output +claude -p --output-format json "Analyze code quality" + +# With input from stdin +echo "Analyze code quality" | claude -p "explain this" +``` + +### 例：CI/CD 統合 + +**GitHub Actions：** +```yaml +# .github/workflows/code-review.yml +name: AI Code Review + +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Claude Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p --output-format json \ + --max-turns 3 \ + "Review this PR for: + - Code quality issues + - Security vulnerabilities + - Performance concerns + - Test coverage + Output results as JSON" > review.json + + - name: Post Review Comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: JSON.stringify(review, null, 2) + }); +``` + +### プリントモードの設定 + +プリントモード（`claude -p`）は自動化向けにいくつかのフラグをサポートする： + +```bash +# Limit autonomous turns +claude -p --max-turns 5 "refactor this module" + +# Structured JSON output +claude -p --output-format json "analyze this codebase" + +# With schema validation +claude -p --json-schema '{"type":"object","properties":{"issues":{"type":"array"}}}' \ + "find bugs in this code" + +# Disable session persistence +claude -p --no-session-persistence "one-off analysis" +``` + +--- + +## セッション管理 + +複数の Claude Code セッションを効果的に管理する。 + +### セッション管理コマンド + +| コマンド | 説明 | +|---------|-------------| +| `/resume` | ID または名前で会話を再開する | +| `/rename` | 現在のセッションに名前を付ける | +| `/fork` | 現在のセッションを新規ブランチとしてフォークする | +| `claude -c` | 直近の会話を継続する | +| `claude -r "session"` | 名前または ID でセッションを再開する | + +### セッションの再開 + +**直近の会話を継続：** +```bash +claude -c +``` + +**名前付きセッションの再開：** +```bash +claude -r "auth-refactor" "finish this PR" +``` + +**現在のセッションを名前付きにする**（REPL 内）： +``` +/rename auth-refactor +``` + +### セッションのフォーク + +別アプローチを試したいが元のセッションを失いたくないとき、セッションをフォークする： + +``` +/fork +``` + +CLI からも実行できる： +```bash +claude --resume auth-refactor --fork-session "try OAuth instead" +``` + +### セッションの永続化 + +セッションは自動保存され、いつでも再開できる： + +```bash +# Continue last conversation +claude -c + +# Resume specific session by name or ID +claude -r "auth-refactor" + +# Resume and fork for experimentation +claude --resume auth-refactor --fork-session "alternative approach" +``` + +### セッションリキャップ（v2.1.108） + +しばらく離れた後にセッションへ戻ると、Claude は何が達成されたかを簡潔に振り返れる。テレメトリが無効化されているユーザー（Bedrock、Vertex、Foundry ユーザー）ではデフォルトで有効である。 + +**リキャップ動作の制御：** + +```bash +/recap # manually trigger a recap +/config # toggle auto-recap on/off +``` + +または環境変数で： +```bash +CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0 claude # disable recap +CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1 claude # force enable recap +``` + +--- + +## 対話機能 + +### キーボードショートカット + +Claude Code は効率向上のためキーボードショートカットをサポートする。公式ドキュメントの完全リファレンス： + +| ショートカット | 説明 | +|----------|-------------| +| `Ctrl+C` | 入力／生成のキャンセル | +| `Ctrl+D` | Claude Code を終了 | +| `Ctrl+G` | 計画を外部エディタで編集 | +| `Ctrl+L` | ターミナル画面のクリア | +| `Ctrl+O` | 詳細出力の切り替え（推論を表示） | +| `Ctrl+R` | 履歴の逆方向検索 | +| `Ctrl+T` | タスクリストビューの切り替え | +| `Ctrl+B` | 実行中タスクをバックグラウンド化 | +| `Esc+Esc` | コード／会話の巻き戻し | +| `Shift+Tab` / `Alt+M` | 権限モードの切り替え | +| `Option+P` / `Alt+P` | モデルの切り替え | +| `Option+T` / `Alt+T` | 拡張思考の切り替え | + +**行編集（標準 readline ショートカット）：** + +| ショートカット | 動作 | +|----------|--------| +| `Ctrl + A` | 行頭へ移動 | +| `Ctrl + E` | 行末へ移動 | +| `Ctrl + K` | 行末まで切り取り | +| `Ctrl + U` | 行頭まで切り取り | +| `Ctrl + W` | 後方の単語を削除 | +| `Ctrl + Y` | ペースト（ヤンク） | +| `Tab` | 自動補完 | +| `↑ / ↓` | コマンド履歴 | + +### キーバインドのカスタマイズ + +`/keybindings` を実行するとカスタムキーボードショートカットを作成できる。コマンドは `~/.claude/keybindings.json` を編集用に開く（v2.1.18 以降）。 + +**設定形式：** + +```json +{ + "$schema": "https://www.schemastore.org/claude-code-keybindings.json", + "bindings": [ + { + "context": "Chat", + "bindings": { + "ctrl+e": "chat:externalEditor", + "ctrl+u": null, + "ctrl+k ctrl+s": "chat:stash" + } + }, + { + "context": "Confirmation", + "bindings": { + "ctrl+a": "confirmation:yes" + } + } + ] +} +``` + +バインドを `null` に設定するとデフォルトのショートカットを解除できる。 + +### 利用可能なコンテキスト + +キーバインドは特定の UI コンテキストにスコープされる： + +| コンテキスト | 主な動作 | +|---------|-------------| +| **Chat** | `submit`、`cancel`、`cycleMode`、`modelPicker`、`thinkingToggle`、`undo`、`externalEditor`、`stash`、`imagePaste` | +| **Confirmation** | `yes`、`no`、`previous`、`next`、`nextField`、`cycleMode`、`toggleExplanation` | +| **Global** | `interrupt`、`exit`、`toggleTodos`、`toggleTranscript` | +| **Autocomplete** | `accept`、`dismiss`、`next`、`previous` | +| **HistorySearch** | `search`、`previous`、`next` | +| **Settings** | コンテキスト固有の設定ナビゲーション | +| **Tabs** | タブの切り替えと管理 | +| **Help** | ヘルプパネルのナビゲーション | + +`Transcript`、`Task`、`ThemePicker`、`Attachments`、`Footer`、`MessageSelector`、`DiffDialog`、`ModelPicker`、`Select` を含め、合計 18 のコンテキストがある。 + +### コードのサポート + +キーバインドはコード（複数キーの組み合わせ）をサポートする： + +``` +"ctrl+k ctrl+s" → Two-key sequence: press ctrl+k, then ctrl+s +"ctrl+shift+p" → Simultaneous modifier keys +``` + +**キー記法：** +- **修飾キー：** `ctrl`、`alt`（または `opt`）、`shift`、`meta`（または `cmd`） +- **大文字は Shift を含意：** `K` は `shift+k` と等価 +- **特殊キー：** `escape`、`enter`、`return`、`tab`、`space`、`backspace`、`delete`、矢印キー + +### 予約キーと競合キー + +| キー | 状態 | 備考 | +|-----|--------|-------| +| `Ctrl+C` | 予約 | リバインド不可（割り込み） | +| `Ctrl+D` | 予約 | リバインド不可（終了） | +| `Ctrl+B` | ターミナル競合 | tmux のプレフィックスキー | +| `Ctrl+A` | ターミナル競合 | GNU Screen のプレフィックスキー | +| `Ctrl+Z` | ターミナル競合 | プロセスサスペンド | + +> **ヒント：** ショートカットが効かない場合、ターミナルエミュレータやマルチプレクサとの競合を確認すること。 + +### タブ補完 + +Claude Code はインテリジェントなタブ補完を提供する： + +``` +User: /rew +→ /rewind + +User: /plu +→ /plugin + +User: /plugin +→ /plugin install +→ /plugin enable +→ /plugin disable +``` + +### コマンド履歴 + +過去のコマンドにアクセスする： + +``` +User: <↑> # Previous command +User: <↓> # Next command +User: Ctrl+R # Search history + +(reverse-i-search)`test': run all tests +``` + +### 複数行入力 + +複雑なクエリには複数行モードを使う： + +```bash +User: \ +> Long complex prompt +> spanning multiple lines +> \end +``` + +**例：** + +``` +User: \ +> Implement a user authentication system +> with the following requirements: +> - JWT tokens +> - Email verification +> - Password reset +> - 2FA support +> \end + +Claude: [Processes the multi-line request] +``` + +### インライン編集 + +送信前にコマンドを編集できる： + +``` +User: Deploy to prodcutionuction + +[Edit in-place before sending] +``` + +### Vim モード + +テキスト編集に Vi/Vim キーバインドを有効化する： + +**起動：** +- `/config` で有効化（「Editor / Vim mode」を切り替え）するか、`~/.claude/settings.json` に `editorMode: "vim"` を設定する。スタンドアロンの `/vim` スラッシュコマンドは削除された（[issue #43370](https://github.com/anthropics/claude-code/issues/43370) を参照）。Vim モードは設定駆動になった。 +- モード切り替え：NORMAL は `Esc`、INSERT は `i/a/o`、VISUAL は `v`、VISUAL-LINE は `V`（v2.1.118 以降） + +**ナビゲーションキー：** +- `h` / `l` — 左／右へ移動 +- `j` / `k` — 下／上へ移動 +- `w` / `b` / `e` — 単語単位で移動 +- `0` / `$` — 行頭／行末へ移動 +- `gg` / `G` — テキストの先頭／末尾へジャンプ + +**テキストオブジェクト：** +- `iw` / `aw` — inner / around 単語 +- `i"` / `a"` — inner / around 引用文字列 +- `i(` / `a(` — inner / around 括弧 + +**ビジュアルモード（v2.1.118 以降）：** + +| キー | モード | 挙動 | +|-----|------|----------| +| `v` | Visual | 文字単位の選択。視覚的フィードバック付き。モーションキーで拡張する | +| `V` | Visual-line | 行単位の選択。常に行全体を選択する | +| `y` | Yank | 現在のビジュアル選択をコピー | +| `d` / `x` | Delete | 現在のビジュアル選択を削除 | +| `c` | Change | 選択を削除して INSERT モードへ | +| `Esc` | Exit | NORMAL モードへ戻る | + +ビジュアル選択は入力フィールド内でハイライトされ、操作確定前にヤンク／削除／変更の対象を正確に確認できる。 + +### Bash モード + +`!` プレフィックスでシェルコマンドを直接実行する： + +```bash +! npm test +! git status +! cat src/index.js +``` + +コンテキストを切り替えずに素早くコマンドを実行したいときに使う。 + +--- + +## TUI モード（フルスクリーン） + +> **v2.1.110 で新登場** + +TUI（Text User Interface）モードは Claude Code をちらつきのない出力でフルスクリーン表示する。tmux や iTerm2 の分割ペインなどのターミナルマルチプレクサに最適である。 + +### TUI モードの有効化 + +`/tui` コマンドで切り替えるか、`--tui` フラグで起動する： + +```bash +/tui # toggle from within a session +claude --tui # start directly in TUI mode +``` + +### 設定 + +| 設定 | 説明 | デフォルト | +|---------|-------------|---------| +| `autoScrollEnabled` | 最新メッセージへ自動スクロール | `true` | + +`/config` または `settings.json` から自動スクロールを無効化する： + +```json +{ + "autoScrollEnabled": false +} +``` + +### フォーカスビュー + +`/focus` コマンドはフォーカスビューを切り替える — 最も関連性の高い出力だけを表示する集中モードである。`Ctrl+O` は通常表示と詳細トランスクリプト表示の切り替えのみを行うようになった（フォーカスビューは `/focus`）。 + +--- + +## 音声入力 + +音声入力は Claude Code でプッシュ・トゥ・トークの音声入力を提供し、タイピングではなくプロンプトを話して入力できるようにする。 + +### 音声入力の起動 + +``` +/voice +``` + +### 機能 + +| 機能 | 説明 | +|---------|-------------| +| **プッシュ・トゥ・トーク** | キーを押している間録音し、離すと送信する | +| **20 言語対応** | 音声テキスト変換が 20 言語をサポート | +| **カスタムキーバインド** | `/keybindings` でプッシュ・トゥ・トークキーを設定 | +| **アカウント要件** | STT 処理に Claude.ai アカウントが必要 | + +### 設定 + +キーバインド設定ファイル（`/keybindings`）でプッシュ・トゥ・トークのキーバインドをカスタマイズする。音声入力は Claude.ai アカウントを使って音声テキスト変換を行う。 + +--- + +## チャンネル + +チャンネルは Research Preview の機能で、MCP サーバ経由で外部サービスのイベントを実行中の Claude Code セッションにプッシュする。Telegram、Discord、iMessage、任意の Webhook をソースとして利用でき、ポーリングなしで Claude がリアルタイム通知に反応できる。 + +### チャンネルの購読 + +```bash +# Subscribe to channel plugins at startup +claude --channels discord,telegram + +# Subscribe to multiple sources +claude --channels discord,telegram,imessage,webhooks +``` + +### サポート対象の連携 + +| 連携 | 説明 | +|-------------|-------------| +| **Discord** | セッション内で Discord メッセージを受信して応答する | +| **Telegram** | セッション内で Telegram メッセージを受信して応答する | +| **iMessage** | セッション内で iMessage 通知を受信する | +| **Webhooks** | 任意の Webhook ソースからイベントを受信する | + +### 設定 + +起動時に `--channels` フラグでチャンネルを設定する。エンタープライズ展開では、許可するチャンネルプラグインを制御するマネージド設定を使う： + +```json +{ + "allowedChannelPlugins": ["discord", "telegram"] +} +``` + +`allowedChannelPlugins` マネージド設定は、組織全体で許可されるチャンネルプラグインを制御する。 + +### 仕組み + +1. MCP サーバが外部サービスに接続するチャンネルプラグインとして動作する +2. 受信メッセージとイベントがアクティブな Claude Code セッションへプッシュされる +3. Claude はセッションのコンテキスト内でメッセージを読んで応答できる +4. チャンネルプラグインは `allowedChannelPlugins` マネージド設定で承認が必要 +5. ポーリング不要 — イベントはリアルタイムでプッシュされる + +--- + +## Chrome 連携 + +Chrome 連携は、Claude Code を Chrome または Microsoft Edge ブラウザに接続し、ライブな Web 自動化とデバッグを行う機能である。これは v2.0.73 以降で利用可能なベータ機能である（Edge サポートは v1.0.36 以降で追加）。 + +### Chrome 連携の有効化 + +**起動時：** + +```bash +claude --chrome # Enable Chrome connection +claude --no-chrome # Disable Chrome connection +``` + +**セッション内：** + +``` +/chrome +``` + +「Enabled by default」を選択すると、今後すべてのセッションで Chrome 連携が有効になる。Claude Code はブラウザのログイン状態を共有するため、認証済み Web アプリと対話できる。 + +### 機能 + +| 機能 | 説明 | +|------------|-------------| +| **ライブデバッグ** | コンソールログの読み取り、DOM 要素の検査、JavaScript のリアルタイムデバッグ | +| **デザイン検証** | レンダリングされたページとデザインモックアップを比較 | +| **フォーム検証** | フォーム送信、入力検証、エラーハンドリングをテスト | +| **Web アプリのテスト** | 認証済みアプリ（Gmail、Google Docs、Notion など）と対話 | +| **データ抽出** | Web ページのコンテンツをスクレイプして処理 | +| **セッション録画** | ブラウザ操作を GIF ファイルとして録画 | + +### サイト単位の権限 + +Chrome 拡張機能はサイトごとのアクセスを管理する。拡張機能のポップアップから、特定サイトへのアクセスをいつでも許可・取り消しできる。Claude Code は明示的に許可されたサイトとのみ対話する。 + +### 仕組み + +Claude Code は表示されたウィンドウ内でブラウザを操作する — 操作の様子をリアルタイムで観察できる。ブラウザがログインページや CAPTCHA に遭遇すると、Claude は一時停止して手動対応を待つ。 + +### 既知の制限 + +- **ブラウザ対応：** Chrome と Edge のみ — Brave、Arc、その他の Chromium ブラウザは非対応 +- **WSL：** Windows Subsystem for Linux では利用不可 +- **サードパーティプロバイダ：** Bedrock、Vertex、Foundry の API プロバイダでは非対応 +- **サービスワーカーのアイドル：** 長時間セッション中に Chrome 拡張機能のサービスワーカーがアイドル状態になることがある + +> **ヒント：** Chrome 連携はベータ機能である。今後のリリースでブラウザサポートが拡大する可能性がある。 + +--- + +## リモートコントロール + +リモートコントロールにより、ローカルで動作中の Claude Code セッションをスマートフォン、タブレット、任意のブラウザから継続できる。ローカルセッションはマシン上で動き続ける — クラウドへ移動するものは何もない。Pro、Max、Team、Enterprise プランで利用可能（v2.1.51 以降）。 + +### リモートコントロールの開始 + +**CLI から：** + +```bash +# Start with default session name +claude remote-control + +# Start with a custom name +claude remote-control --name "Auth Refactor" +``` + +**セッション内から：** + +``` +/remote-control +/remote-control "Auth Refactor" +``` + +**利用可能なフラグ：** + +| フラグ | 説明 | +|------|-------------| +| `--name "title"` | 識別しやすいセッションタイトル | +| `--verbose` | 詳細な接続ログを表示 | +| `--sandbox` | ファイルシステムとネットワークの隔離を有効化 | +| `--no-sandbox` | サンドボックスを無効化（デフォルト） | + +### セッションへの接続 + +別デバイスから接続する 3 つの方法： + +1. **セッション URL** — セッション開始時にターミナルに出力される。任意のブラウザで開ける +2. **QR コード** — 開始後 `spacebar` を押すとスキャン可能な QR コードが表示される +3. **名前で検索** — claude.ai/code または Claude モバイルアプリ（iOS/Android）でセッションを参照 + +### セキュリティ + +- マシン上で **インバウンドポートを開かない** +- **アウトバウンド HTTPS のみ**（TLS 経由） +- **スコープ付き認証情報** — 短命で狭くスコープされた複数のトークン +- **セッション分離** — 各リモートセッションは独立 + +### リモートコントロール vs Claude Code on the web + +| 観点 | リモートコントロール | Claude Code on Web | +|--------|---------------|-------------------| +| **実行場所** | マシン上で動作 | Anthropic クラウド上で動作 | +| **ローカルツール** | ローカル MCP サーバ、ファイル、CLI へのフルアクセス | ローカル依存なし | +| **ユースケース** | 別デバイスからローカル作業を継続 | 任意のブラウザで新規開始 | + +### 制限 + +- Claude Code インスタンスごとにリモートセッションは 1 つ +- ホストマシンのターミナルを開いたままにする必要がある +- ネットワーク到達不能時は約 10 分でセッションがタイムアウト + +### ユースケース + +- デスクから離れた場所からモバイルデバイスやタブレットで Claude Code を操作する +- ローカルツール実行を保ちつつ、より豊かな claude.ai UI を使う +- 完全なローカル開発環境とともに外出先で素早くコードレビュー + +### プッシュ通知（v2.1.110） + +リモートコントロールがアクティブで、`/config` で「Push when Claude decides」が有効になっている場合、Claude はモバイルプッシュ通知を送信できる — 例えば長時間タスクの完了時や入力が必要なときなど。 + +有効化方法： +1. リモートコントロールを起動：`/remote-control` または `claude --rc` +2. `/config` を開いて **Push when Claude decides** を有効化 + +プッシュ通知には Claude サブスクリプションと Claude モバイルアプリが必要である。 + +--- + +## Web セッション + +Web セッションでは、claude.ai/code 上のブラウザで直接 Claude Code を実行したり、CLI から Web セッションを作成したりできる。 + +### Web セッションの作成 + +```bash +# Create a new web session from the CLI +claude --remote "implement the new API endpoints" +``` + +これにより claude.ai 上で Claude Code セッションが開始され、任意のブラウザからアクセスできる。 + +### Web セッションをローカルで再開 + +Web で開始したセッションをローカルで継続したい場合： + +```bash +# Resume a web session in the local terminal +claude --teleport +``` + +または対話 REPL 内で： +``` +/teleport +``` + +### ユースケース + +- 1 台のマシンで作業を始め、別のマシンで継続する +- セッション URL をチームメンバーと共有する +- 視覚的な diff レビューには Web UI を使い、実行はターミナルに切り替える + +--- + +## デスクトップアプリ + +Claude Code デスクトップアプリは、視覚的な diff レビュー、並列セッション、統合コネクタを備えたスタンドアロンアプリケーションである。macOS と Windows で利用可能（Pro、Max、Team、Enterprise プラン）。 + +### インストール + +[claude.ai](https://claude.ai) からプラットフォームに合わせてダウンロードする： +- **macOS：** ユニバーサルビルド（Apple Silicon と Intel） +- **Windows：** x64 と ARM64 のインストーラを利用可能 + +セットアップ手順は [Desktop Quickstart](https://code.claude.com/docs/en/desktop-quickstart) を参照。 + +### CLI からの引き渡し + +現在の CLI セッションをデスクトップアプリに転送する： + +``` +/desktop +``` + +### コア機能 + +| 機能 | 説明 | +|---------|-------------| +| **Diff ビュー** | ファイルごとの視覚的レビューとインラインコメント。Claude はコメントを読んで修正する | +| **アプリプレビュー** | dev サーバを自動起動し、組み込みブラウザでライブ検証 | +| **PR 監視** | GitHub CLI 連携。CI 失敗の自動修正、チェック完了時の自動マージ | +| **並列セッション** | サイドバーで複数セッションを管理。Git ワークツリーで自動的に隔離 | +| **スケジュールタスク** | 定期タスク（時次、日次、平日、週次）。アプリが開いている間に実行 | +| **リッチレンダリング** | コード、Markdown、図表のレンダリングとシンタックスハイライト | + +### アプリプレビューの設定 + +`.claude/launch.json` で dev サーバの動作を設定する： + +```json +{ + "command": "npm run dev", + "port": 3000, + "readyPattern": "ready on", + "persistCookies": true +} +``` + +### コネクタ + +外部サービスを接続してより豊かなコンテキストを得る： + +| コネクタ | 機能 | +|-----------|------------| +| **GitHub** | PR 監視、Issue トラッキング、コードレビュー | +| **Slack** | 通知、チャンネルコンテキスト | +| **Linear** | Issue トラッキング、スプリント管理 | +| **Notion** | ドキュメント、ナレッジベースアクセス | +| **Asana** | タスク管理、プロジェクト追跡 | +| **Calendar** | スケジュール認識、ミーティングコンテキスト | + +> **注：** コネクタはリモート（クラウド）セッションでは利用不可。 + +### リモートと SSH セッション + +- **リモートセッション：** Anthropic のクラウドインフラで動作。アプリを閉じても継続する。claude.ai/code または Claude モバイルアプリからアクセス可能 +- **SSH セッション：** SSH 経由でリモートマシンに接続し、リモートのファイルシステムとツールへのフルアクセスを得る。Claude Code をリモートマシンにインストールする必要がある + +### デスクトップでの権限モード + +デスクトップアプリは CLI と同じ 4 つの権限モードをサポートする： + +| モード | 挙動 | +|------|----------| +| **Ask permissions**（デフォルト） | すべての編集とコマンドをレビューして承認 | +| **Auto accept edits** | ファイル編集は自動承認、コマンドは手動承認 | +| **Plan mode** | 変更前にアプローチをレビュー | +| **Bypass permissions** | 自動実行（サンドボックス限定、管理者制御） | + +### エンタープライズ機能 + +- **管理コンソール：** 組織のコードタブアクセスと権限設定を制御 +- **MDM 展開：** macOS は MDM、Windows は MSIX で展開 +- **SSO 統合：** 組織メンバーにシングルサインオンを必須にする +- **マネージド設定：** チーム設定とモデルの可用性を一元管理 + +--- + +## タスクリスト + +タスクリスト機能はコンテキストコンパクション（コンテキストウィンドウに収めるため会話履歴がトリミングされること）を生き延びる永続的なタスク追跡を提供する。 + +### タスクリストの切り替え + +セッション中に `Ctrl+T` を押すとタスクリストビューを切り替えられる。 + +### 永続的なタスク + +タスクはコンテキストコンパクションをまたいで永続化されるため、長時間の作業項目が会話コンテキストのトリミング時に失われない。複雑で多段階の実装に特に有用である。 + +### 名前付きタスクディレクトリ + +`CLAUDE_CODE_TASK_LIST_ID` 環境変数を使うと、複数セッションで共有される名前付きタスクディレクトリを作成できる： + +```bash +export CLAUDE_CODE_TASK_LIST_ID=my-project-sprint-3 +``` + +これにより複数セッションが同じタスクリストを共有でき、チームワークフローや複数セッションプロジェクトに有用である。 + +--- + +## プロンプト候補 + +プロンプト候補は、Git 履歴と現在の会話コンテキストに基づき、グレーアウトされた例示コマンドを表示する。 + +### 仕組み + +- 候補は入力プロンプトの下にグレーアウトされたテキストとして表示される +- `Tab` を押すと候補を受け入れる +- `Enter` を押すと受け入れて即座に送信する +- 候補はコンテキストを認識し、Git 履歴と会話状態から導出される + +### プロンプト候補の無効化 + +```bash +export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false +``` + +--- + +## Git ワークツリー + +Git ワークツリーにより、隔離されたワークツリーで Claude Code を起動できる。スタッシュやブランチ切り替えなしに、異なるブランチでの並列作業が可能になる。 + +### ワークツリーで起動 + +```bash +# Start Claude Code in an isolated worktree +claude --worktree +# or +claude -w +``` + +### ワークツリーの保存場所 + +ワークツリーは以下に作成される： +``` +/.claude/worktrees/ +``` + +### モノレポ向けスパースチェックアウト + +`worktree.sparsePaths` 設定でモノレポにスパースチェックアウトを行い、ディスク使用量とクローン時間を削減できる： + +```json +{ + "worktree": { + "sparsePaths": ["packages/my-package", "shared/"] + } +} +``` + +### ワークツリーのツールとフック + +| 項目 | 説明 | +|------|-------------| +| `ExitWorktree` | 現在のワークツリーを終了してクリーンアップするツール | +| `WorktreeCreate` | ワークツリー作成時に発火するフックイベント | +| `WorktreeRemove` | ワークツリー削除時に発火するフックイベント | + +### 自動クリーンアップ + +ワークツリーで変更が行われていない場合、セッション終了時に自動でクリーンアップされる。 + +### ユースケース + +- メインブランチを触らずに機能ブランチで作業する +- 作業ディレクトリに影響を与えずにテストを隔離実行する +- 使い捨て環境で実験的な変更を試す +- モノレポで特定パッケージをスパースチェックアウトして起動を高速化する + +--- + +## サンドボックス + +サンドボックスは、Claude Code が実行する Bash コマンドに OS レベルのファイルシステムとネットワーク隔離を提供する。これは権限ルールを補完し、追加のセキュリティレイヤーを提供する。 + +### サンドボックスの有効化 + +**スラッシュコマンド：** +``` +/sandbox +``` + +**CLI フラグ：** +```bash +claude --sandbox # Enable sandboxing +claude --no-sandbox # Disable sandboxing +``` + +### 設定項目 + +| 設定 | 説明 | +|---------|-------------| +| `sandbox.enabled` | サンドボックスを有効化／無効化 | +| `sandbox.failIfUnavailable` | サンドボックスを起動できない場合に失敗させる | +| `sandbox.filesystem.allowWrite` | 書き込みを許可するパス | +| `sandbox.filesystem.allowRead` | 読み取りを許可するパス | +| `sandbox.filesystem.denyRead` | 読み取りを拒否するパス | +| `sandbox.network.allowedDomains` | Bash 起動プロセスからアクセスを許可するドメイン（`*.` ワイルドカード対応） | +| `sandbox.network.deniedDomains` | `allowedDomains` のワイルドカードで許可されてもブロックするドメイン（v2.1.113 以降） | +| `sandbox.enableWeakerNetworkIsolation` | macOS で弱いネットワーク隔離を有効化 | + +`deniedDomains` が広いワイルドカードを上書きする例（v2.1.113 以降）： + +```json +{ + "sandbox": { + "network": { + "allowedDomains": ["*.example.com"], + "deniedDomains": ["evil.example.com"] + } + } +} +``` + +ワイルドカードによって `example.com` 上のすべてが通過するが、`deniedDomains` で個別指定したホストはブロックされる。 + +### 設定例 + +```json +{ + "sandbox": { + "enabled": true, + "failIfUnavailable": true, + "filesystem": { + "allowWrite": ["/Users/me/project"], + "allowRead": ["/Users/me/project", "/usr/local/lib"], + "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"] + }, + "enableWeakerNetworkIsolation": true + } +} +``` + +### 仕組み + +- Bash コマンドはファイルシステムアクセスを制限したサンドボックス環境で動作する +- ネットワークアクセスを隔離して意図しない外部接続を防げる +- 多層防御のため権限ルールと併用できる +- macOS では `sandbox.enableWeakerNetworkIsolation` でネットワーク制限を行う（macOS では完全なネットワーク隔離は利用不可） + +### ユースケース + +- 信頼できないコードや生成コードを安全に実行する +- プロジェクト外ファイルへの誤った変更を防ぐ +- 自動化タスク中のネットワークアクセスを制限する + +--- + +## マネージド設定（エンタープライズ） + +マネージド設定により、エンタープライズ管理者がプラットフォームネイティブの管理ツールを使って組織全体で Claude Code 設定を展開できる。 + +### 展開方法 + +| プラットフォーム | 方法 | 対応バージョン | +|----------|--------|-------| +| macOS | マネージド plist ファイル（MDM） | v2.1.51 以降 | +| Windows | Windows レジストリ | v2.1.51 以降 | +| クロスプラットフォーム | マネージド設定ファイル | v2.1.51 以降 | +| クロスプラットフォーム | マネージドドロップイン（`managed-settings.d/` ディレクトリ） | v2.1.83 以降 | + +### マネージドドロップイン + +v2.1.83 以降、管理者は複数のマネージド設定ファイルを `managed-settings.d/` ディレクトリに配置できる。ファイルはアルファベット順にマージされ、チーム横断のモジュラー設定が可能になる： + +``` +~/.claude/managed-settings.d/ + 00-org-defaults.json + 10-team-policies.json + 20-project-overrides.json +``` + +### 利用可能なマネージド設定 + +| 設定 | 説明 | +|---------|-------------| +| `disableBypassPermissionsMode` | ユーザーによる bypass permissions の有効化を防ぐ | +| `availableModels` | ユーザーが選択可能なモデルを制限する | +| `allowedChannelPlugins` | 許可するチャンネルプラグインを制御する | +| `autoMode.environment` | オートモードの信頼インフラを設定する | +| `wslInheritsWindowsSettings` | Windows/WSL 限定（v2.1.118 以降）：`true` の場合、WSL 内で動作する Claude Code が Windows ホストのマネージド設定を継承し、Registry/MDM で展開された企業ポリシーが Windows シェルと WSL シェルで均一に適用される | +| カスタムポリシー | 組織固有の権限とツールポリシー | + +### 例：macOS Plist + +```xml + + + + + disableBypassPermissionsMode + + availableModels + + claude-sonnet-4-6 + claude-haiku-4-5 + + + +``` + +--- + +## 設定とコンフィグ + +### 設定ファイルの場所 + +1. **グローバル設定：** `~/.claude/config.json` +2. **プロジェクト設定：** `./.claude/config.json` +3. **ユーザー設定：** `~/.config/claude-code/settings.json` + +### 完全な設定例 + +**コア高度機能の設定：** + +```json +{ + "permissions": { + "mode": "default" + }, + "hooks": { + "PreToolUse:Edit": "eslint --fix ${file_path}", + "PostToolUse:Write": "~/.claude/hooks/security-scan.sh" + }, + "mcp": { + "enabled": true, + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"] + } + } + } +} +``` + +**拡張設定例：** + +```json +{ + "permissions": { + "mode": "default", + "allowedTools": ["Bash(git log:*)", "Read"], + "disallowedTools": ["Bash(rm -rf:*)"] + }, + + "hooks": { + "PreToolUse": [{ "matcher": "Edit", "hooks": ["eslint --fix ${file_path}"] }], + "PostToolUse": [{ "matcher": "Write", "hooks": ["~/.claude/hooks/security-scan.sh"] }], + "Stop": [{ "hooks": ["~/.claude/hooks/notify.sh"] }] + }, + + "mcp": { + "enabled": true, + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } + } +} +``` + +### 環境変数 + +設定を環境変数で上書きする： + +```bash +# Model selection +export ANTHROPIC_MODEL=claude-opus-4-7 +export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7 +export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6 +export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 + +# API configuration +export ANTHROPIC_API_KEY=sk-ant-... + +# Thinking configuration +export MAX_THINKING_TOKENS=16000 +export CLAUDE_CODE_EFFORT_LEVEL=xhigh # low, medium, high, xhigh (Opus 4.7 only, default), or max (supported on Opus 4.7, Opus 4.6, Sonnet 4.6) + +# Feature toggles +export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true +export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true +export CLAUDE_CODE_DISABLE_CRON=1 +export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=true +export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=true +export CLAUDE_CODE_DISABLE_1M_CONTEXT=true +export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=true +export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false +export CLAUDE_CODE_ENABLE_TASKS=true +export CLAUDE_CODE_SIMPLE=true # Set by --bare flag + +# MCP configuration +export MAX_MCP_OUTPUT_TOKENS=50000 +export ENABLE_TOOL_SEARCH=true + +# Prompt caching +export ENABLE_PROMPT_CACHING_1H=1 # Use 1-hour prompt cache TTL (default is 5 min) + +# Task management +export CLAUDE_CODE_TASK_LIST_ID=my-project-tasks + +# Agent teams (experimental) +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 + +# Subagent and plugin configuration +export CLAUDE_CODE_SUBAGENT_MODEL=sonnet +export CLAUDE_CODE_PLUGIN_SEED_DIR=./my-plugins +export CLAUDE_CODE_NEW_INIT=1 + +# Subprocess and streaming +export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB="SECRET_KEY,DB_PASSWORD" +export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 +export CLAUDE_STREAM_IDLE_TIMEOUT_MS=30000 +export ANTHROPIC_CUSTOM_MODEL_OPTION=my-custom-model +export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000 +``` + +> **v2.1.108：** `ENABLE_PROMPT_CACHING_1H=1` — デフォルトの 5 分 TTL ではなく 1 時間のプロンプトキャッシュ TTL を使用する。安定した長時間セッションでキャッシュミスを削減する。 + +### 設定管理コマンド + +``` +User: /config +[Opens interactive configuration menu] +``` + +`/config` コマンドは以下のような設定をトグルする対話メニューを提供する： +- 拡張思考のオン／オフ +- 詳細出力 +- 権限モード +- モデル選択 + +### プロジェクト単位の設定 + +プロジェクトに `.claude/config.json` を作成する： + +```json +{ + "hooks": { + "PreToolUse": [{ "matcher": "Bash", "hooks": ["npm test && npm run lint"] }] + }, + "permissions": { + "mode": "default" + }, + "mcp": { + "servers": { + "project-db": { + "command": "mcp-postgres", + "env": { + "DATABASE_URL": "${PROJECT_DB_URL}" + } + } + } + } +} +``` + +--- + +## エージェントチーム + +エージェントチームは複数の Claude Code インスタンスがタスクで協業できる実験的機能である。デフォルトでは無効化されている。 + +### エージェントチームの有効化 + +環境変数または設定で有効化する： + +```bash +# Environment variable +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +または設定 JSON に追加する： + +```json +{ + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" +} +``` + +### エージェントチームの仕組み + +- **チームリード** が全体タスクを調整し、サブタスクをチームメイトに委譲する +- **チームメイト** はそれぞれ独自のコンテキストウィンドウを持ち、独立して作業する +- **共有タスクリスト** によりチームメンバー間の自己調整が可能になる +- サブエージェント定義（`.claude/agents/` または `--agents` フラグ）でチームメイトの役割と専門性を定義する + +### 表示モード + +エージェントチームは `--teammate-mode` フラグで設定する 2 つの表示モードをサポートする： + +| モード | 説明 | +|------|-------------| +| `in-process`（デフォルト） | チームメイトが同じターミナルプロセス内で動作する | +| `tmux` | 各チームメイトが専用の分割ペインを持つ（tmux または iTerm2 が必要） | +| `auto` | 最適な表示モードを自動選択する | + +```bash +# Use tmux split panes for teammate display +claude --teammate-mode tmux + +# Explicitly use in-process mode +claude --teammate-mode in-process +``` + +### ユースケース + +- 異なるチームメイトが異なるモジュールを担当する大規模リファクタリング +- 並列のコードレビューと実装 +- コードベース横断的な複数ファイル変更の調整 + +> **注：** エージェントチームは実験的機能であり、今後のリリースで変更される可能性がある。完全なリファレンスは [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) を参照。 + +--- + +## ベストプラクティス + +### プランニングモード +- ✅ 複雑な複数ステップタスクに使う +- ✅ 承認前に計画をレビューする +- ✅ 必要に応じて計画を修正する +- ❌ 単純なタスクには使わない + +### 拡張思考 +- ✅ アーキテクチャ判断に使う +- ✅ 複雑な問題解決に使う +- ✅ 思考プロセスをレビューする +- ❌ 単純なクエリには使わない + +### バックグラウンドタスク +- ✅ 長時間実行操作に使う +- ✅ タスクの進捗を監視する +- ✅ タスクの失敗を適切に処理する +- ❌ 同時タスクを多すぎるほど起動しない + +### 権限 +- ✅ コードレビューには `plan`（読み取り専用）を使う +- ✅ 対話的開発には `default` を使う +- ✅ 自動化ワークフローには `acceptEdits` を使う +- ✅ セーフティガードレール付きの自律作業には `auto` を使う +- ✅ どうしても必要でない限り `bypassPermissions` を使わない + +### セッション +- ✅ 異なるタスクには別々のセッションを使う +- ✅ 重要なセッション状態を保存する +- ✅ 古いセッションをクリーンアップする +- ❌ 1 つのセッションに無関係な作業を混在させない + +--- + +## 追加リソース + +Claude Code および関連機能の詳細： + +- [Official Interactive Mode Documentation](https://code.claude.com/docs/en/interactive-mode) +- [Official Headless Mode Documentation](https://code.claude.com/docs/en/headless) +- [CLI Reference](https://code.claude.com/docs/en/cli-reference) +- [Checkpoints Guide](../08-checkpoints/) — セッション管理と巻き戻し +- [Slash Commands](../01-slash-commands/) — コマンドリファレンス +- [Memory Guide](../02-memory/) — 永続コンテキスト +- [Skills Guide](../03-skills/) — 自律機能 +- [Subagents Guide](../04-subagents/) — タスク委譲実行 +- [MCP Guide](../05-mcp/) — 外部データアクセス +- [Hooks Guide](../06-hooks/) — イベント駆動自動化 +- [Plugins Guide](../07-plugins/) — バンドル拡張 +- [Official Scheduled Tasks Documentation](https://code.claude.com/docs/en/scheduled-tasks) +- [Official Chrome Integration Documentation](https://code.claude.com/docs/en/chrome) +- [Official Remote Control Documentation](https://code.claude.com/docs/en/remote-control) +- [Official Keybindings Documentation](https://code.claude.com/docs/en/keybindings) +- [Official Desktop App Documentation](https://code.claude.com/docs/en/desktop) +- [Official Agent Teams Documentation](https://code.claude.com/docs/en/agent-teams) + +--- + +**最終更新：** 2026 年 4 月 24 日 +**Claude Code バージョン：** 2.1.119 +**情報源：** +- https://code.claude.com/docs/en/permission-modes +- https://code.claude.com/docs/en/interactive-mode +- https://code.claude.com/docs/en/settings +- https://www.anthropic.com/news/claude-opus-4-7 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.118 + +**互換モデル：** Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/09-advanced-features/planning-mode-examples.md b/ja/09-advanced-features/planning-mode-examples.md new file mode 100644 index 0000000..99acebc --- /dev/null +++ b/ja/09-advanced-features/planning-mode-examples.md @@ -0,0 +1,540 @@ + + + + +# プランニングモードの例 + +Claude Code でプランニングモードを効果的に使う実例集。 + +## 例 1: REST API の構築 + +### プランニングモードを使わない場合 + +``` +User: Build a REST API for a blog + +Claude: I'll create the API... +[Starts coding immediately, may miss requirements] +``` + +### プランニングモードを使う場合 + +``` +User: /plan Build a REST API for a blog + +Claude: Let me create a comprehensive plan for the blog API. + +## Blog REST API Implementation Plan + +### Phase 1: Project Setup (15 min) +1. Initialize Node.js project with Express +2. Set up TypeScript configuration +3. Install dependencies (express, pg, jwt, joi) +4. Configure environment variables +5. Set up project structure + +### Phase 2: Database Layer (30 min) +6. Design database schema + - users table (id, email, password_hash, created_at) + - posts table (id, user_id, title, content, published, created_at, updated_at) + - comments table (id, post_id, user_id, content, created_at) +7. Create migration files +8. Set up database connection pool +9. Implement database models + +### Phase 3: Authentication (45 min) +10. Implement user registration endpoint +11. Implement login endpoint with JWT +12. Create authentication middleware +13. Add password hashing with bcrypt +14. Implement token refresh logic + +### Phase 4: Posts API (40 min) +15. GET /api/posts - List all published posts (with pagination) +16. GET /api/posts/:id - Get single post +17. POST /api/posts - Create new post (auth required) +18. PUT /api/posts/:id - Update post (auth required, ownership check) +19. DELETE /api/posts/:id - Delete post (auth required, ownership check) +20. GET /api/users/:id/posts - Get user's posts + +### Phase 5: Comments API (30 min) +21. GET /api/posts/:id/comments - Get post comments +22. POST /api/posts/:id/comments - Add comment (auth required) +23. DELETE /api/comments/:id - Delete comment (auth required, ownership check) + +### Phase 6: Validation & Error Handling (30 min) +24. Add request validation with Joi +25. Implement global error handler +26. Add input sanitization +27. Implement rate limiting + +### Phase 7: Testing (60 min) +28. Write unit tests for models +29. Write integration tests for auth endpoints +30. Write integration tests for posts endpoints +31. Write integration tests for comments endpoints +32. Achieve 80%+ code coverage + +### Phase 8: Documentation & Deployment (30 min) +33. Generate API documentation with Swagger +34. Create README with setup instructions +35. Add Docker configuration +36. Set up CI/CD pipeline + +**Estimated Time**: 4.5 hours +**Files to Create**: ~25 +**Key Technologies**: Express, PostgreSQL, JWT, TypeScript + +**API Endpoints Summary**: +- Authentication: 2 endpoints +- Posts: 6 endpoints +- Comments: 3 endpoints +- Total: 11 endpoints + +Ready to proceed? (yes/no/modify) + +User: yes + +Claude: Starting Phase 1: Project Setup... +[Implements each phase systematically] +``` + +## 例 2: データベースマイグレーション + +### プランニングモードを使う場合 + +``` +User: /plan Migrate from MongoDB to PostgreSQL + +Claude: This is a complex migration. Let me create a detailed plan. + +## MongoDB to PostgreSQL Migration Plan + +### Phase 1: Analysis & Preparation (Day 1) +1. Analyze current MongoDB schema +2. Identify data relationships and constraints +3. Document current data volume and growth rate +4. Design equivalent PostgreSQL schema +5. Plan data type mappings +6. Identify potential migration challenges + +### Phase 2: PostgreSQL Setup (Day 1) +7. Set up PostgreSQL database +8. Create schema with tables, indexes, constraints +9. Set up connection pooling +10. Configure backup strategy + +### Phase 3: Dual-Write Implementation (Day 2-3) +11. Create database abstraction layer +12. Implement dual-write to both databases +13. Add data consistency checks +14. Deploy dual-write to staging +15. Monitor for issues + +### Phase 4: Data Migration (Day 4) +16. Create data export scripts for MongoDB +17. Create data import scripts for PostgreSQL +18. Implement data transformation logic +19. Run initial migration on copy of production data +20. Validate migrated data integrity + +### Phase 5: Gradual Cutover (Day 5-7) +21. Enable dual-write in production +22. Migrate historical data in batches +23. Continuously validate data consistency +24. Monitor both databases +25. Fix any data synchronization issues + +### Phase 6: PostgreSQL Primary (Day 8) +26. Switch read operations to PostgreSQL +27. Monitor query performance +28. Optimize slow queries +29. Continue dual-write for safety + +### Phase 7: MongoDB Retirement (Day 9-10) +30. Stop writing to MongoDB +31. Keep MongoDB as backup for 2 weeks +32. Remove MongoDB dependencies from code +33. Archive MongoDB data +34. Decommission MongoDB instance + +**Estimated Time**: 10 days +**Risk Level**: High +**Rollback Strategy**: Keep MongoDB running with dual-write +**Success Criteria**: +- Zero data loss +- <5% performance regression +- All tests passing + +**Key Risks**: +1. Data inconsistency during migration +2. Query performance degradation +3. Application downtime +4. Data loss + +**Mitigation**: +- Dual-write pattern for safety +- Gradual cutover +- Continuous monitoring +- Quick rollback capability + +Proceed with this plan? (yes/no/modify) + +User: Modify - let's add a rollback plan for each phase + +Claude: Updated plan with rollback procedures for each phase... +``` + +## 例 3: フロントエンドのリファクタリング + +``` +User: /plan Refactor our React app from class components to hooks + +Claude: I'll create a systematic refactoring plan. + +## React Class to Hooks Migration Plan + +### Phase 1: Preparation & Analysis (2 hours) +1. Audit all class components (find all .jsx/.tsx files) +2. Categorize by complexity: + - Simple (state only): ~15 components + - Medium (lifecycle methods): ~23 components + - Complex (multiple lifecycle, refs): ~8 components +3. Identify third-party libraries that need updates +4. Create component dependency graph +5. Plan migration order (leaf nodes first) + +### Phase 2: Setup & Tooling (1 hour) +6. Update React to v18+ +7. Set up ESLint rules for hooks +8. Create conversion templates +9. Set up automated tests +10. Create checkpoint before starting + +### Phase 3: Migrate Simple Components (4 hours) +11. Convert simple stateful components (15 components) +12. Replace this.state with useState +13. Replace this.setState with state setters +14. Test each component after conversion +15. Update tests + +### Phase 4: Migrate Medium Components (8 hours) +16. Convert components with lifecycle methods (23 components) +17. Replace componentDidMount with useEffect +18. Replace componentDidUpdate with useEffect +19. Replace componentWillUnmount with useEffect cleanup +20. Test thoroughly + +### Phase 5: Migrate Complex Components (12 hours) +21. Convert complex components (8 components) +22. Replace refs with useRef +23. Extract custom hooks for shared logic +24. Handle edge cases (multiple useEffect) +25. Extensive testing + +### Phase 6: Shared Logic Extraction (6 hours) +26. Identify duplicated logic across components +27. Create custom hooks: + - useAuth + - useFetch + - useLocalStorage + - useDebounce +28. Refactor components to use custom hooks +29. Test custom hooks independently + +### Phase 7: Performance Optimization (4 hours) +30. Add React.memo where needed +31. Optimize with useCallback +32. Optimize with useMemo +33. Profile and fix performance regressions + +### Phase 8: Cleanup & Documentation (2 hours) +34. Remove unused class component utilities +35. Update documentation +36. Update coding guidelines +37. Create migration guide for team + +**Estimated Time**: 5 days (39 hours) +**Files to Modify**: 46 components +**Risk Level**: Medium + +**Migration Order**: +1. Leaf components (no dependencies) +2. Mid-level components +3. Top-level container components +4. App.jsx (last) + +**Testing Strategy**: +- Unit tests for each component +- Integration tests for user flows +- Visual regression tests +- Performance benchmarks + +**Success Metrics**: +- All tests passing +- No visual regressions +- Performance maintained or improved +- Bundle size not significantly increased + +Proceed? (yes/no/modify) +``` + +## 例 4: セキュリティ実装 + +``` +User: /plan Implement comprehensive security for our web app + +Claude: Let me create a thorough security implementation plan. + +## Web Application Security Implementation Plan + +### Phase 1: Security Audit (Day 1) +1. Run automated security scanners (npm audit, Snyk) +2. Review dependencies for vulnerabilities +3. Check OWASP Top 10 compliance +4. Audit authentication flows +5. Review data handling practices +6. Document current security gaps + +### Phase 2: Authentication Hardening (Day 2-3) +7. Implement strong password requirements +8. Add password strength meter +9. Implement rate limiting on login +10. Add account lockout after failed attempts +11. Implement 2FA (TOTP) +12. Add session management improvements +13. Implement secure password reset flow + +### Phase 3: Authorization & Access Control (Day 3-4) +14. Implement RBAC (Role-Based Access Control) +15. Add permission checks on all endpoints +16. Implement principle of least privilege +17. Add audit logging for sensitive operations +18. Implement resource-level permissions + +### Phase 4: Data Protection (Day 4-5) +19. Implement encryption at rest (sensitive fields) +20. Ensure TLS/SSL for all communications +21. Implement secure session storage +22. Add PII data masking in logs +23. Implement data retention policies +24. Add secure file upload handling + +### Phase 5: Input Validation & Sanitization (Day 5-6) +25. Implement input validation on all endpoints +26. Add XSS protection (Content Security Policy) +27. Implement SQL injection prevention (parameterized queries) +28. Add CSRF protection +29. Implement request size limits +30. Add file upload type validation + +### Phase 6: Security Headers & Configuration (Day 6) +31. Add security headers: + - Strict-Transport-Security + - X-Content-Type-Options + - X-Frame-Options + - X-XSS-Protection + - Content-Security-Policy +32. Configure CORS properly +33. Disable unnecessary HTTP methods +34. Remove server version headers + +### Phase 7: Monitoring & Logging (Day 7) +35. Implement security event logging +36. Add anomaly detection +37. Set up intrusion detection +38. Implement real-time alerting +39. Create security dashboard + +### Phase 8: Testing & Documentation (Day 8-9) +40. Perform penetration testing +41. Run security scanners +42. Test all security features +43. Create security documentation +44. Train team on security practices +45. Create incident response plan + +### Phase 9: Compliance & Policies (Day 10) +46. GDPR compliance check +47. Create privacy policy +48. Implement data subject rights +49. Add cookie consent +50. Create security policies documentation + +**Estimated Time**: 10 days +**Risk Level**: Critical +**Priority**: High + +**Security Improvements Summary**: +- Authentication: 7 enhancements +- Authorization: 5 enhancements +- Data Protection: 6 enhancements +- Input Validation: 6 enhancements +- Infrastructure: 9 enhancements +- Monitoring: 5 enhancements + +**Compliance**: OWASP Top 10, GDPR + +**Success Criteria**: +- Zero critical vulnerabilities +- All OWASP Top 10 mitigated +- Security score >90/100 +- All pen test issues resolved + +Proceed? (yes/no/modify) +``` + +## 例 5: パフォーマンス最適化 + +``` +User: /plan Optimize our slow e-commerce website + +Claude: Let me create a comprehensive performance optimization plan. + +## E-commerce Performance Optimization Plan + +### Phase 1: Performance Audit (4 hours) +1. Run Lighthouse audit +2. Analyze Chrome DevTools performance profile +3. Measure Core Web Vitals: + - LCP (Largest Contentful Paint) + - FID (First Input Delay) + - CLS (Cumulative Layout Shift) +4. Identify performance bottlenecks +5. Create baseline performance metrics + +**Current Metrics**: +- LCP: 4.2s (target: <2.5s) +- FID: 280ms (target: <100ms) +- CLS: 0.25 (target: <0.1) +- Page Load: 8.3s (target: <3s) + +### Phase 2: Image Optimization (6 hours) +6. Convert images to WebP format +7. Implement responsive images +8. Add lazy loading for images +9. Optimize image sizes (compression) +10. Implement CDN for images +11. Add image placeholders + +**Expected Impact**: -40% load time + +### Phase 3: Code Splitting & Lazy Loading (8 hours) +12. Implement route-based code splitting +13. Lazy load non-critical components +14. Split vendor bundles +15. Optimize chunk sizes +16. Implement dynamic imports +17. Add preloading for critical resources + +**Expected Impact**: -30% initial bundle size + +### Phase 4: Caching Strategy (6 hours) +18. Implement browser caching (Cache-Control) +19. Add service worker for offline support +20. Implement API response caching +21. Add Redis cache for database queries +22. Implement stale-while-revalidate +23. Configure CDN caching + +**Expected Impact**: -50% API response time + +### Phase 5: Database Optimization (8 hours) +24. Add database indexes +25. Optimize slow queries (>100ms) +26. Implement query result caching +27. Add connection pooling +28. Denormalize where appropriate +29. Implement database read replicas + +**Expected Impact**: -60% database query time + +### Phase 6: Frontend Optimization (10 hours) +30. Minimize and compress JavaScript +31. Minimize and compress CSS +32. Remove unused CSS (PurgeCSS) +33. Implement critical CSS +34. Defer non-critical JavaScript +35. Reduce DOM size +36. Optimize React rendering (memo, useMemo) +37. Implement virtual scrolling for long lists + +**Expected Impact**: -35% JavaScript execution time + +### Phase 7: Network Optimization (4 hours) +38. Enable HTTP/2 +39. Implement resource hints (preconnect, prefetch) +40. Reduce number of HTTP requests +41. Enable Brotli compression +42. Optimize third-party scripts + +**Expected Impact**: -25% network time + +### Phase 8: Monitoring & Testing (4 hours) +43. Set up performance monitoring (Datadog/New Relic) +44. Add Real User Monitoring (RUM) +45. Create performance budgets +46. Set up automated Lighthouse CI +47. Test on real devices + +**Estimated Time**: 50 hours (2 weeks) + +**Target Metrics** (90th percentile): +- LCP: <2.0s (from 4.2s) ✅ +- FID: <50ms (from 280ms) ✅ +- CLS: <0.05 (from 0.25) ✅ +- Page Load: <2.5s (from 8.3s) ✅ + +**Expected Revenue Impact**: +- 100ms faster = 1% conversion increase +- Target: 5.8s improvement = ~58% conversion increase +- Estimated additional revenue: Significant + +**Priority Order**: +1. Image optimization (quick wins) +2. Code splitting (high impact) +3. Caching (high impact) +4. Database optimization (critical) +5. Frontend optimization (polish) + +Proceed with this plan? (yes/no/modify) +``` + +## 重要なポイント + +### プランニングモードの利点 + +1. **明確化**: 着手前にロードマップが定まる +2. **見積もり**: 時間と工数の見積もりが得られる +3. **リスク評価**: 潜在的な問題を早期に特定できる +4. **優先順位付け**: タスクの論理的な順序を整理できる +5. **承認**: 実行前にレビュー・承認できる +6. **修正**: フィードバックに応じて計画を調整できる + +### プランニングモードを使うべきとき + +✅ **常に使うべき場面**: +- 複数日にわたるプロジェクト +- チームでの協業 +- 重要なシステム変更 +- 新しい概念の学習 +- 複雑なリファクタリング + +❌ **使うべきでない場面**: +- バグ修正 +- 小さな調整 +- 単純な質問 +- 軽い試行錯誤 + +### ベストプラクティス + +1. 承認前に計画を **慎重にレビュー** する +2. 問題を見つけたら **計画を修正** する +3. 複雑なタスクは **分解** する +4. **現実的な** 時間見積もりを行う +5. **ロールバック** 戦略を含める +6. **成功基準** を設ける +7. 各フェーズの **テスト計画** を含める + +--- +**最終更新**: 2026 年 4 月 9 日 diff --git a/ja/10-cli/README.md b/ja/10-cli/README.md new file mode 100644 index 0000000..0718f02 --- /dev/null +++ b/ja/10-cli/README.md @@ -0,0 +1,887 @@ + + + + + + + Claude How To + + +# CLI リファレンス + +## 概観 + +Claude Code CLI（Command Line Interface）は Claude Code を操作する主要な手段である。クエリの実行、セッション管理、モデル設定、開発ワークフローへの組み込みを行う強力なオプション群を備えている。 + +## アーキテクチャ + +```mermaid +graph TD + A["User Terminal"] -->|"claude [options] [query]"| B["Claude Code CLI"] + B -->|Interactive| C["REPL Mode"] + B -->|"--print"| D["Print Mode (SDK)"] + B -->|"--resume"| E["Session Resume"] + C -->|Conversation| F["Claude API"] + D -->|Single Query| F + E -->|Load Context| F + F -->|Response| G["Output"] + G -->|text/json/stream-json| H["Terminal/Pipe"] +``` + +## ランタイムとパッケージング + +**v2.1.113** 以降、Claude Code CLI は npm のオプション依存を介して **プラットフォーム別のネイティブバイナリ**（macOS、Linux、Windows）を起動する。バイナリはインストール時に OS とアーキテクチャに合わせて選択される — 旧来のバンドル JavaScript ランタイムは macOS / Linux ではもはやデフォルトではない。 + +**ユーザー側のインストール手順は変わらない**: `npm install -g @anthropic-ai/claude-code` がそのまま動作し、引き続き推奨経路である。裏側で npm がプラットフォームに合った正しいネイティブバイナリを取得する。 + +**ダウンロードホスト**（v2.1.116+）: ネイティブバイナリ成果物は `https://downloads.claude.ai/claude-code-releases` から配信される。 + +> **企業ネットワーク／プロキシ環境**: ネットワークが明示的な許可リストを必要とする場合、プロキシのエグレスルールに `downloads.claude.ai`（および `https://downloads.claude.ai/claude-code-releases`）を追加すること。以前 `storage.googleapis.com` または npm レジストリのみを許可していた環境は更新が必要で、未対応のままだと `claude update` や初回インストールが失敗する。 + +旧来の JavaScript バンドルは Windows 用および固定利用の環境向けに引き続き提供される。これらのインストールでは Glob と Grep が引き続きファーストクラスツールとして同梱される（[ツール](#ツールと権限の管理) 節の Glob/Grep 注記を参照）。 + +## CLI コマンド + +| コマンド | 説明 | 例 | +|---------|------|-----| +| `claude` | 対話型 REPL を起動 | `claude` | +| `claude "query"` | 初期プロンプト付きで REPL を起動 | `claude "explain this project"` | +| `claude -p "query"` | プリントモード - クエリ実行後に終了 | `claude -p "explain this function"` | +| `cat file \| claude -p "query"` | パイプ入力を処理 | `cat logs.txt \| claude -p "explain"` | +| `claude -c` | 直近の会話を継続 | `claude -c` | +| `claude -c -p "query"` | プリントモードで継続 | `claude -c -p "check for type errors"` | +| `claude -r "" "query"` | ID または名前でセッション再開 | `claude -r "auth-refactor" "finish this PR"` | +| `claude update` | 最新版に更新 | `claude update` | +| `/doctor`（スラッシュコマンド） | インストール、設定、プラグインの健全性を診断する。v2.1.116 以降は **Claude が応答中でも開ける** ようになり、ステータスアイコンをインライン表示し、`f` キーで検出された問題を自動修正する | REPL 内で `/doctor` を実行 | +| `claude mcp` | MCP サーバーを設定 | [MCP のドキュメント](../05-mcp/) を参照 | +| `claude mcp serve` | Claude Code を MCP サーバーとして起動 | `claude mcp serve` | +| `claude agents` | 設定済みのサブエージェントを一覧表示 | `claude agents` | +| `claude auto-mode defaults` | 自動モードのデフォルトルールを JSON で出力 | `claude auto-mode defaults` | +| `claude remote-control` | リモートコントロールサーバーを起動 | `claude remote-control` | +| `claude plugin` | プラグインを管理（インストール・有効化・無効化） | `claude plugin install my-plugin` | +| `claude plugin tag ` | バージョン検証付きでプラグインのリリース git タグを作成（v2.1.118+） | `claude plugin tag v0.3.0` | +| `claude install [version]` | 指定したネイティブバイナリのバージョンをインストール。`stable`、`latest`、明示的なバージョン文字列を受け付ける | `claude install 2.1.119` | +| `claude auth login` | ログイン（`--email`、`--sso` をサポート） | `claude auth login --email user@example.com` | +| `claude auth logout` | 現在のアカウントからログアウト | `claude auth logout` | +| `claude auth status` | 認証状態を確認（ログイン中なら exit 0、未ログインなら 1） | `claude auth status` | + +## 主要フラグ + +| フラグ | 説明 | 例 | +|------|------|-----| +| `-p, --print` | 対話モードを使わず応答を出力 | `claude -p "query"` | +| `-c, --continue` | 直近の会話を読み込む | `claude --continue` | +| `-r, --resume` | ID または名前で特定セッションを再開 | `claude --resume auth-refactor` | +| `-v, --version` | バージョン番号を出力 | `claude -v` | +| `-w, --worktree` | 隔離された git ワークツリーで起動 | `claude -w` | +| `-n, --name` | セッションの表示名 | `claude -n "auth-refactor"` | +| `--from-pr ` | プル／マージリクエストに紐づくセッションを再開する。v2.1.119 以降は GitHub（クラウド + Enterprise）、GitLab MR、Bitbucket PR の URL を受け付ける（以前は GitHub.com のみ） | `claude --from-pr 42` または `claude --from-pr https://gitlab.example.com/org/repo/-/merge_requests/17` | +| `--remote "task"` | claude.ai 上に web セッションを作成 | `claude --remote "implement API"` | +| `--remote-control, --rc` | リモートコントロール付きの対話セッション | `claude --rc` | +| `--teleport` | web セッションをローカルで再開 | `claude --teleport` | +| `--teammate-mode` | エージェントチームの表示モード | `claude --teammate-mode tmux` | +| `--bare` | 最小モード（フック、スキル、プラグイン、MCP、自動メモリ、CLAUDE.md をスキップ） | `claude --bare` | +| `--enable-auto-mode` | 自動権限モードを解禁（Opus 4.7 の Max 加入者には不要） | `claude --enable-auto-mode` | +| `--channels` | MCP チャンネルプラグインを購読 | `claude --channels discord,telegram` | +| `--chrome` / `--no-chrome` | Chrome ブラウザ統合を有効化／無効化 | `claude --chrome` | +| `--effort` | 思考労力レベルを設定 | `claude --effort high` | +| `--init` / `--init-only` | 初期化フックを実行 | `claude --init` | +| `--maintenance` | メンテナンスフックを実行して終了 | `claude --maintenance` | +| `--disable-slash-commands` | すべてのスキルとスラッシュコマンドを無効化 | `claude --disable-slash-commands` | +| `--no-session-persistence` | セッション保存を無効化（プリントモード） | `claude -p --no-session-persistence "query"` | +| `--exclude-dynamic-system-prompt-sections` | プロンプトキャッシュヒット率向上のため、システムプロンプトから動的セクションを除外 | `claude -p --exclude-dynamic-system-prompt-sections "query"` | + +### 対話モードとプリントモード + +```mermaid +graph LR + A["claude"] -->|Default| B["Interactive REPL"] + A -->|"-p flag"| C["Print Mode"] + B -->|Features| D["Multi-turn conversation
Tab completion
History
Slash commands"] + C -->|Features| E["Single query
Scriptable
Pipeable
JSON output"] +``` + +**対話モード**（デフォルト）: +```bash +# 対話セッションを開始 +claude + +# 初期プロンプト付きで開始 +claude "explain the authentication flow" +``` + +**プリントモード**（非対話）: +```bash +# 単一クエリ実行後に終了 +claude -p "what does this function do?" + +# ファイル内容を処理 +cat error.log | claude -p "explain this error" + +# 他のツールとチェーン +claude -p "list todos" | grep "URGENT" +``` + +## モデルと設定 + +| フラグ | 説明 | 例 | +|------|------|-----| +| `--model` | モデルを設定（sonnet、opus、haiku、または完全名） | `claude --model opus` | +| `--fallback-model` | 過負荷時の自動フォールバックモデル | `claude -p --fallback-model sonnet "query"` | +| `--agent` | セッションに使うエージェントを指定 | `claude --agent my-custom-agent` | +| `--agents` | JSON でカスタムサブエージェントを定義 | [Agents の設定](#agents-の設定) を参照 | +| `--effort` | 労力レベルを設定（low、medium、high、xhigh、max） | `claude --effort xhigh` | + +### モデル選択の例 + +```bash +# 複雑なタスクには Opus 4.7 +claude --model opus "design a caching strategy" + +# 速いタスクには Haiku 4.5 +claude --model haiku -p "format this JSON" + +# モデル名のフルネーム指定 +claude --model claude-sonnet-4-6-20250929 "review this code" + +# 信頼性のためフォールバック付き +claude -p --model opus --fallback-model sonnet "analyze architecture" + +# opusplan（Opus が計画、Sonnet が実装） +claude --model opusplan "design and implement the caching layer" +``` + +## システムプロンプトのカスタマイズ + +| フラグ | 説明 | 例 | +|------|------|-----| +| `--system-prompt` | デフォルトプロンプト全体を置き換える | `claude --system-prompt "You are a Python expert"` | +| `--system-prompt-file` | ファイルからプロンプトを読み込む（プリントモード） | `claude -p --system-prompt-file ./prompt.txt "query"` | +| `--append-system-prompt` | デフォルトプロンプトに追記 | `claude --append-system-prompt "Always use TypeScript"` | + +### システムプロンプトの例 + +```bash +# 完全カスタムなペルソナ +claude --system-prompt "You are a senior security engineer. Focus on vulnerabilities." + +# 特定の指示を追加 +claude --append-system-prompt "Always include unit tests with code examples" + +# 複雑なプロンプトをファイルから読み込み +claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py" +``` + +### システムプロンプトフラグの比較 + +| フラグ | 挙動 | 対話 | プリント | +|------|-----|------|---------| +| `--system-prompt` | デフォルトのシステムプロンプト全体を置き換える | ✅ | ✅ | +| `--system-prompt-file` | ファイルのプロンプトに置き換える | ❌ | ✅ | +| `--append-system-prompt` | デフォルトに追記する | ✅ | ✅ | + +**`--system-prompt-file` はプリントモードでのみ使用する。対話モードでは `--system-prompt` または `--append-system-prompt` を使うこと。** + +## ツールと権限の管理 + +| フラグ | 説明 | 例 | +|------|------|-----| +| `--tools` | 利用可能な組み込みツールを制限 | `claude -p --tools "Bash,Edit,Read" "query"` | +| `--allowedTools` | 確認なしで実行できるツール | `"Bash(git log:*)" "Read"` | +| `--disallowedTools` | コンテキストから除外するツール | `"Bash(rm:*)" "Edit"` | +| `--dangerously-skip-permissions` | 全ての権限プロンプトをスキップ | `claude --dangerously-skip-permissions` | +| `--permission-mode` | 指定した権限モードで開始 | `claude --permission-mode auto` | +| `--permission-prompt-tool` | 権限処理用の MCP ツール | `claude -p --permission-prompt-tool mcp_auth "query"` | +| `--enable-auto-mode` | 自動権限モードを解禁 | `claude --enable-auto-mode` | + +> **Glob / Grep 注記（v2.1.113+）**: ネイティブな macOS／Linux ビルドでは、`Glob` と `Grep` は独立したファーストクラスツールではなく、Bash ツール経由で呼び出される組み込みの `bfs` および `ugrep` バイナリとして提供される。Windows 版および npm バンドル（JS）版では引き続きスタンドアロンツールとして公開される。サブエージェントの `allowedTools` ／ `disallowedTools` リストでは、バックエンド側の置換は透過的なため、どのプラットフォームでも設定では引き続き `Glob` ／ `Grep` を参照すればよい。 + +> **PowerShell の自動承認（v2.1.119）**: PowerShell ツールのコマンドは、Bash コマンドとまったく同じ方式で権限モードによる自動承認が可能になった。`Bash(...)` ルールで使うのと同じマッチャ構文で PowerShell の権限を絞り込める — 例: `PowerShell(Get-ChildItem:*)`。 + +### 権限の例 + +```bash +# コードレビュー用の読み取り専用モード +claude --permission-mode plan "review this codebase" + +# 安全なツールのみに制限 +claude --tools "Read,Grep,Glob" -p "find all TODO comments" + +# 特定の git コマンドを確認なしで許可 +claude --allowedTools "Bash(git status:*)" "Bash(git log:*)" + +# 危険な操作をブロック +claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)" +``` + +## 出力とフォーマット + +| フラグ | 説明 | オプション | 例 | +|------|------|-----------|-----| +| `--output-format` | 出力フォーマット指定（プリントモード） | `text`、`json`、`stream-json` | `claude -p --output-format json "query"` | +| `--input-format` | 入力フォーマット指定（プリントモード） | `text`、`stream-json` | `claude -p --input-format stream-json` | +| `--verbose` | 詳細ログを有効化 | | `claude --verbose` | +| `--include-partial-messages` | ストリーミングイベントを含める | `stream-json` が必要 | `claude -p --output-format stream-json --include-partial-messages "query"` | +| `--json-schema` | スキーマに沿って検証された JSON を取得 | | `claude -p --json-schema '{"type":"object"}' "query"` | +| `--max-budget-usd` | プリントモードでの最大支出額 | | `claude -p --max-budget-usd 5.00 "query"` | + +### 出力フォーマットの例 + +```bash +# プレーンテキスト（デフォルト） +claude -p "explain this code" + +# プログラムから扱うための JSON +claude -p --output-format json "list all functions in main.py" + +# リアルタイム処理向けのストリーミング JSON +claude -p --output-format stream-json "generate a long report" + +# スキーマ検証付きの構造化出力 +claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \ + "find bugs in this code and return as JSON" +``` + +## ワークスペースとディレクトリ + +| フラグ | 説明 | 例 | +|------|------|-----| +| `--add-dir` | 追加の作業ディレクトリを指定 | `claude --add-dir ../apps ../lib` | +| `--setting-sources` | カンマ区切りの設定ソース | `claude --setting-sources user,project` | + +> **`/config` の永続化（v2.1.119）**: `/config` コマンドで対話的に行った変更は `~/.claude/settings.json` に書き込まれ、通常の優先順位チェーン（project → local → policy → user）に組み込まれるようになった。v2.1.119 以前は一部の `/config` 変更がセッション限定だった。完全な優先順位については [メモリと設定](../02-memory/README.md) を参照。 +| `--settings` | ファイルまたは JSON から設定を読み込む | `claude --settings ./settings.json` | +| `--plugin-dir` | ディレクトリからプラグインを読み込む（複数指定可） | `claude --plugin-dir ./my-plugin` | + +### 複数ディレクトリの例 + +```bash +# 複数のプロジェクトディレクトリを横断作業 +claude --add-dir ../frontend ../backend ../shared "find all API endpoints" + +# カスタム設定の読み込み +claude --settings '{"model":"opus","verbose":true}' "complex task" +``` + +## MCP の設定 + +| フラグ | 説明 | 例 | +|------|------|-----| +| `--mcp-config` | JSON から MCP サーバーを読み込む | `claude --mcp-config ./mcp.json` | +| `--strict-mcp-config` | 指定した MCP 設定のみを使う | `claude --strict-mcp-config --mcp-config ./mcp.json` | +| `--channels` | MCP チャンネルプラグインを購読 | `claude --channels discord,telegram` | + +### MCP の例 + +```bash +# GitHub MCP サーバーの読み込み +claude --mcp-config ./github-mcp.json "list open PRs" + +# 厳密モード - 指定したサーバーのみ +claude --strict-mcp-config --mcp-config ./production-mcp.json "deploy to staging" +``` + +## セッション管理 + +| フラグ | 説明 | 例 | +|------|------|-----| +| `--session-id` | 特定セッション ID（UUID）を使用 | `claude --session-id "550e8400-..."` | +| `--fork-session` | 再開時に新しいセッションを作成 | `claude --resume abc123 --fork-session` | + +### セッションの例 + +```bash +# 直前の会話を継続 +claude -c + +# 名前付きセッションを再開 +claude -r "feature-auth" "continue implementing login" + +# 試行錯誤のためセッションをフォーク +claude --resume feature-auth --fork-session "try alternative approach" + +# 特定のセッション ID を使用 +claude --session-id "550e8400-e29b-41d4-a716-446655440000" "continue" +``` + +### セッションのフォーク + +既存セッションから分岐したブランチを作成し試行錯誤する： + +```bash +# 別アプローチを試すためにセッションをフォーク +claude --resume abc123 --fork-session "try alternative implementation" + +# カスタムメッセージ付きでフォーク +claude -r "feature-auth" --fork-session "test with different architecture" +``` + +**ユースケース:** +- 元のセッションを失わずに別実装を試す +- 並行して複数のアプローチを試行錯誤する +- 成功した作業からバリエーションのブランチを作る +- メインセッションに影響を与えずに破壊的な変更を試す + +元のセッションは変更されず、フォークは新しい独立セッションになる。 + +## 高度な機能 + +| フラグ | 説明 | 例 | +|------|------|-----| +| `--chrome` | Chrome ブラウザ統合を有効化 | `claude --chrome` | +| `--no-chrome` | Chrome ブラウザ統合を無効化 | `claude --no-chrome` | +| `--ide` | 利用可能なら IDE と自動接続 | `claude --ide` | +| `--max-turns` | エージェントターンを制限（非対話） | `claude -p --max-turns 3 "query"` | +| `--debug` | フィルタ付きデバッグモードを有効化 | `claude --debug "api,mcp"` | +| `--enable-lsp-logging` | 詳細な LSP ログを有効化 | `claude --enable-lsp-logging` | +| `--betas` | API リクエストのベータヘッダ | `claude --betas interleaved-thinking` | +| `--plugin-dir` | ディレクトリからプラグインを読み込む（複数指定可） | `claude --plugin-dir ./my-plugin` | +| `--enable-auto-mode` | 自動権限モードを解禁 | `claude --enable-auto-mode` | +| `--effort` | 思考労力レベルを設定 | `claude --effort high` | +| `--bare` | 最小モード（フック、スキル、プラグイン、MCP、自動メモリ、CLAUDE.md をスキップ） | `claude --bare` | +| `--channels` | MCP チャンネルプラグインを購読 | `claude --channels discord` | +| `--tmux` | ワークツリー用に tmux セッションを作成 | `claude --tmux` | +| `--fork-session` | 再開時に新しいセッション ID を作成 | `claude --resume abc --fork-session` | +| `--max-budget-usd` | 最大支出額（プリントモード） | `claude -p --max-budget-usd 5.00 "query"` | +| `--json-schema` | 検証付き JSON 出力 | `claude -p --json-schema '{"type":"object"}' "q"` | + +### プラットフォームとテーマの注記（v2.1.112） + +- **Windows 版の PowerShell ツール**: Windows 向けに専用の PowerShell ツールがロールアウトされ、環境変数で制御できる。 +- **「Auto（ターミナルに合わせる）」テーマ**: 新しい "Auto (match terminal)" テーマで Claude Code のライト／ダーク表示をターミナルと同期できる。 +- **静かな権限プロンプト**: 読み取り専用の `Bash` 呼び出しと `Glob` パターンは権限プロンプトを発生させなくなった。 + +### 高度な例 + +```bash +# 自律アクション数を制限 +claude -p --max-turns 5 "refactor this module" + +# API 呼び出しをデバッグ +claude --debug "api" "test query" + +# IDE 統合を有効化 +claude --ide "help me with this file" +``` + +## Agents の設定 + +`--agents` フラグはセッションに対するカスタムサブエージェントを定義する JSON オブジェクトを受け取る。 + +### Agents の JSON フォーマット + +```json +{ + "agent-name": { + "description": "Required: when to invoke this agent", + "prompt": "Required: system prompt for the agent", + "tools": ["Optional", "array", "of", "tools"], + "model": "optional: sonnet|opus|haiku" + } +} +``` + +**必須フィールド:** +- `description` - エージェントを使う場面の自然言語による説明 +- `prompt` - エージェントの役割と挙動を定義するシステムプロンプト + +**任意フィールド:** +- `tools` - 利用可能なツールの配列（省略時は全ツールを継承） + - 形式: `["Read", "Grep", "Glob", "Bash"]` +- `model` - 使用するモデル: `sonnet`、`opus`、`haiku` + +### 完全な Agents の例 + +```json +{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + }, + "debugger": { + "description": "Debugging specialist for errors and test failures.", + "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.", + "tools": ["Read", "Edit", "Bash", "Grep"], + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist for generating guides.", + "prompt": "You are a technical writer. Create clear, comprehensive documentation.", + "tools": ["Read", "Write"], + "model": "haiku" + } +} +``` + +### Agents コマンドの例 + +```bash +# カスタムエージェントをインラインで定義 +claude --agents '{ + "security-auditor": { + "description": "Security specialist for vulnerability analysis", + "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.", + "tools": ["Read", "Grep", "Glob"], + "model": "opus" + } +}' "audit this codebase for security issues" + +# ファイルからエージェントを読み込み +claude --agents "$(cat ~/.claude/agents.json)" "review the auth module" + +# 他のフラグと組み合わせ +claude -p --agents "$(cat agents.json)" --model sonnet "analyze performance" +``` + +### エージェントの優先順位 + +複数のエージェント定義が存在する場合、以下の優先順位で読み込まれる： +1. **CLI 定義**（`--agents` フラグ） - セッション固有 +2. **プロジェクトレベル**（`.claude/agents/`） - 現在のプロジェクト +3. **ユーザーレベル**（`~/.claude/agents/`） - 全プロジェクト + +CLI 定義のエージェントは、当該セッションにおいてプロジェクトおよびユーザーのエージェントを上書きする。プロジェクトレベルのエージェントは、名前が衝突した場合にユーザーレベルのエージェントを上書きする。プラグインレベルのエージェントを含む完全な優先順位表は [Lesson 04 — サブエージェント](../04-subagents/README.md#file-locations) を参照。 + +--- + +## 価値の高いユースケース + +### 1. CI/CD への組み込み + +Claude Code を CI/CD パイプラインに組み込み、コードレビュー、テスト、ドキュメント生成を自動化する。 + +**GitHub Actions の例:** + +```yaml +name: AI Code Review + +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p --output-format json \ + --max-turns 1 \ + "Review the changes in this PR for: + - Security vulnerabilities + - Performance issues + - Code quality + Output as JSON with 'issues' array" > review.json + + - name: Post Review Comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + // Process and post review comments +``` + +**Jenkins パイプライン:** + +```groovy +pipeline { + agent any + stages { + stage('AI Review') { + steps { + sh ''' + claude -p --output-format json \ + --max-turns 3 \ + "Analyze test coverage and suggest missing tests" \ + > coverage-analysis.json + ''' + } + } + } +} +``` + +### 2. スクリプトのパイプ処理 + +ファイル、ログ、データを Claude に流し込んで分析する。 + +**ログ解析:** + +```bash +# エラーログの分析 +tail -1000 /var/log/app/error.log | claude -p "summarize these errors and suggest fixes" + +# アクセスログ内のパターン抽出 +cat access.log | claude -p "identify suspicious access patterns" + +# git 履歴の要約 +git log --oneline -50 | claude -p "summarize recent development activity" +``` + +**コード処理:** + +```bash +# 特定ファイルのレビュー +cat src/auth.ts | claude -p "review this authentication code for security issues" + +# ドキュメントの生成 +cat src/api/*.ts | claude -p "generate API documentation in markdown" + +# TODO の抽出と優先順位付け +grep -r "TODO" src/ | claude -p "prioritize these TODOs by importance" +``` + +### 3. マルチセッションのワークフロー + +複数の会話スレッドで複雑なプロジェクトを管理する。 + +```bash +# フィーチャーブランチ用セッションを開始 +claude -r "feature-auth" "let's implement user authentication" + +# 後で同じセッションを継続 +claude -r "feature-auth" "add password reset functionality" + +# 別アプローチを試すためフォーク +claude --resume feature-auth --fork-session "try OAuth instead" + +# 別の機能のセッションへ切り替え +claude -r "feature-payments" "continue with Stripe integration" +``` + +### 4. カスタムエージェントの設定 + +チームのワークフロー向けに専門エージェントを定義する。 + +```bash +# エージェント設定をファイルに保存 +cat > ~/.claude/agents.json << 'EOF' +{ + "reviewer": { + "description": "Code reviewer for PR reviews", + "prompt": "Review code for quality, security, and maintainability.", + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist", + "prompt": "Generate clear, comprehensive documentation.", + "model": "sonnet" + }, + "refactorer": { + "description": "Code refactoring expert", + "prompt": "Suggest and implement clean code refactoring.", + "tools": ["Read", "Edit", "Glob"] + } +} +EOF + +# セッションでエージェントを使用 +claude --agents "$(cat ~/.claude/agents.json)" "review the auth module" +``` + +### 5. バッチ処理 + +一貫した設定で複数クエリを処理する。 + +```bash +# 複数ファイルの処理 +for file in src/*.ts; do + echo "Processing $file..." + claude -p --model haiku "summarize this file: $(cat $file)" >> summaries.md +done + +# バッチコードレビュー +find src -name "*.py" -exec sh -c ' + echo "## $1" >> review.md + cat "$1" | claude -p "brief code review" >> review.md +' _ {} \; + +# 全モジュールのテスト生成 +for module in $(ls src/modules/); do + claude -p "generate unit tests for src/modules/$module" > "tests/$module.test.ts" +done +``` + +### 6. セキュリティを意識した開発 + +権限制御で安全に運用する。 + +```bash +# 読み取り専用のセキュリティ監査 +claude --permission-mode plan \ + --tools "Read,Grep,Glob" \ + "audit this codebase for security vulnerabilities" + +# 危険なコマンドをブロック +claude --disallowedTools "Bash(rm:*)" "Bash(curl:*)" "Bash(wget:*)" \ + "help me clean up this project" + +# 制限付き自動化 +claude -p --max-turns 2 \ + --allowedTools "Read" "Glob" \ + "find all hardcoded credentials" +``` + +### 7. JSON API としての利用 + +`jq` のパースと組み合わせて、Claude をプログラム可能な API として活用する。 + +```bash +# 構造化された分析を取得 +claude -p --output-format json \ + --json-schema '{"type":"object","properties":{"functions":{"type":"array"},"complexity":{"type":"string"}}}' \ + "analyze main.py and return function list with complexity rating" + +# jq で処理に組み込む +claude -p --output-format json "list all API endpoints" | jq '.endpoints[]' + +# スクリプト内で利用 +RESULT=$(claude -p --output-format json "is this code secure? answer with {secure: boolean, issues: []}" < code.py) +if echo "$RESULT" | jq -e '.secure == false' > /dev/null; then + echo "Security issues found!" + echo "$RESULT" | jq '.issues[]' +fi +``` + +### jq でのパース例 + +`jq` で Claude の JSON 出力をパース・処理する： + +```bash +# 特定フィールドの抽出 +claude -p --output-format json "analyze this code" | jq '.result' + +# 配列要素のフィルタ +claude -p --output-format json "list issues" | jq -r '.issues[] | select(.severity=="high")' + +# 複数フィールドの抽出 +claude -p --output-format json "describe the project" | jq -r '.{name, version, description}' + +# CSV への変換 +claude -p --output-format json "list functions" | jq -r '.functions[] | [.name, .lineCount] | @csv' + +# 条件付き処理 +claude -p --output-format json "check security" | jq 'if .vulnerabilities | length > 0 then "UNSAFE" else "SAFE" end' + +# ネストされた値の取得 +claude -p --output-format json "analyze performance" | jq '.metrics.cpu.usage' + +# 配列全体の処理 +claude -p --output-format json "find todos" | jq '.todos | length' + +# 出力の変換 +claude -p --output-format json "list improvements" | jq 'map({title: .title, priority: .priority})' +``` + +--- + +## モデル + +Claude Code は能力の異なる複数のモデルをサポートする： + +| モデル | ID | コンテキストウィンドウ | 備考 | +|-------|-----|----------------------|------| +| Opus 4.7 | `claude-opus-4-7` | 1M トークン（1M コンテキスト対応は v2.1.117 で実装） | 最も能力が高く、適応的な労力レベルを備える。Claude Code では Opus 4.7 ローンチ（2026-04-16）以降 `xhigh` がデフォルトの労力レベル | +| Sonnet 4.6 | `claude-sonnet-4-6` | 1M トークン | 速度と能力のバランスが良い。Pro／Max 加入者のデフォルト労力は v2.1.117 で `medium` から `high` に引き上げられた | +| Haiku 4.5 | `claude-haiku-4-5` | 1M トークン | 最速で、軽いタスクに最適 | + +### モデルの選択 + +```bash +# 短縮名で指定 +claude --model opus "complex architectural review" +claude --model sonnet "implement this feature" +claude --model haiku -p "format this JSON" + +# opusplan エイリアス（Opus が計画、Sonnet が実装） +claude --model opusplan "design and implement the API" + +# セッション中にファストモードを切り替え +/fast +``` + +### 労力レベル（Opus 4.7） + +Opus 4.7 は適応的推論をサポートし、軽い順から `low`（○）、`medium`（◐）、`high`（●）、`xhigh`（Claude Code では Opus 4.7 ローンチ以降のデフォルト、2026-04-16）、`max`（Opus 4.7 のみ）の労力レベルを持つ。Opus 4.6 ／ Sonnet 4.6 では、Pro／Max 加入者のデフォルト労力が v2.1.117 で `medium` から `high` に引き上げられた。 + +```bash +# CLI フラグで労力レベルを設定 +claude --effort xhigh "complex review" + +# スラッシュコマンドで労力レベルを設定 +/effort xhigh + +# 環境変数で労力レベルを設定 +export CLAUDE_CODE_EFFORT_LEVEL=xhigh # low, medium, high, xhigh (default on Opus 4.7), or max (Opus 4.7 only) +``` + +プロンプト内のキーワード「ultrathink」は深い推論を有効化する。`max` の労力レベルは Opus 4.7 専用である。 + +--- + +## 主要な環境変数 + +| 変数 | 説明 | +|------|------| +| `ANTHROPIC_API_KEY` | 認証用の API キー | +| `ANTHROPIC_MODEL` | デフォルトモデルを上書き | +| `ANTHROPIC_CUSTOM_MODEL_OPTION` | API 用のカスタムモデルオプション | +| `ANTHROPIC_DEFAULT_OPUS_MODEL` | デフォルトの Opus モデル ID を上書き | +| `ANTHROPIC_DEFAULT_SONNET_MODEL` | デフォルトの Sonnet モデル ID を上書き | +| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | デフォルトの Haiku モデル ID を上書き | +| `MAX_THINKING_TOKENS` | 拡張思考のトークン予算を設定 | +| `CLAUDE_CODE_EFFORT_LEVEL` | 労力レベルを設定（`low`／`medium`／`high`／`xhigh`／`max`） — `xhigh` は Opus 4.7 のデフォルト、`max` は Opus 4.7 のみ | +| `CLAUDE_CODE_SIMPLE` | 最小モード（`--bare` フラグで設定される） | +| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | CLAUDE.md の自動更新を無効化 | +| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | バックグラウンドタスク実行を無効化 | +| `CLAUDE_CODE_DISABLE_CRON` | スケジュール／cron タスクを無効化 | +| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | git 関連の指示を無効化 | +| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | ターミナルタイトル更新を無効化 | +| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 1M トークンコンテキストウィンドウを無効化 | +| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | 非ストリーミングフォールバックを無効化 | +| `CLAUDE_CODE_ENABLE_TASKS` | タスクリスト機能を有効化 | +| `CLAUDE_CODE_TASK_LIST_ID` | セッション間で共有する名前付きタスクディレクトリ | +| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | プロンプトサジェストを切り替え（`true`／`false`） | +| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | 実験的なエージェントチームを有効化 | +| `CLAUDE_CODE_NEW_INIT` | 新しい初期化フローを使用 | +| `CLAUDE_CODE_SUBAGENT_MODEL` | サブエージェント実行用モデル | +| `CLAUDE_CODE_PLUGIN_SEED_DIR` | プラグインシードファイル用ディレクトリ | +| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | サブプロセスから取り除く環境変数 | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 自動コンパクションのパーセンテージを上書き | +| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | ストリームのアイドルタイムアウト（ミリ秒） | +| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | スラッシュコマンドツールの文字数予算 | +| `ENABLE_TOOL_SEARCH` | ツール検索機能を有効化 | +| `MAX_MCP_OUTPUT_TOKENS` | MCP ツール出力の最大トークン数 | +| `CLAUDE_CODE_PERFORCE_MODE` | `1` を設定すると Perforce モードを有効化 — ファイルをデフォルトで読み取り専用として扱う（Perforce/P4 バージョン管理ワークフロー向け）（v2.1.98 追加） | +| `DISABLE_UPDATES` | 手動の `claude update` を含むすべての更新経路をブロックする。バックグラウンドの自動更新のみブロックする `DISABLE_AUTOUPDATER` より厳密（v2.1.118+） | +| `CLAUDE_CODE_HIDE_CWD` | `1` に設定すると、起動時ロゴでカレント作業ディレクトリを隠す（プライバシー／画面共有用途）（v2.1.119+） | +| `CLAUDE_CODE_FORK_SUBAGENT` | `1` を設定すると外部ビルド（Bedrock、Vertex、Foundry）でフォーク済みサブエージェントを有効化。Anthropic API ではフォーク済みサブエージェントが GA のため効果なし（v2.1.117+） | +| `OTEL_LOG_TOOL_DETAILS` | `1` を設定すると OpenTelemetry イベント中のカスタムおよび MCP コマンド名のリダクションを解除する（v2.1.117+）。デフォルトはリダクション有効。 | + +> **Vertex AI 上の `ENABLE_TOOL_SEARCH`（v2.1.119+）**: ツール検索は **Google Cloud Vertex AI 上のデプロイではデフォルト無効** である。Vertex 上でツール検索機能を使いたい場合は `export ENABLE_TOOL_SEARCH=true` で明示的にオプトインする必要がある。Anthropic API 直結ではデフォルト有効のままである。 + +--- + +## クイックリファレンス + +### 最もよく使うコマンド + +```bash +# 対話セッション +claude + +# サッと質問 +claude -p "how do I..." + +# 会話を継続 +claude -c + +# ファイルを処理 +cat file.py | claude -p "review this" + +# スクリプト用の JSON 出力 +claude -p --output-format json "query" +``` + +### フラグの組み合わせ + +| ユースケース | コマンド | +|-------------|----------| +| 簡易コードレビュー | `cat file | claude -p "review"` | +| 構造化出力 | `claude -p --output-format json "query"` | +| 安全な探索 | `claude --permission-mode plan` | +| 安全装置付き自律実行 | `claude --enable-auto-mode --permission-mode auto` | +| CI/CD 連携 | `claude -p --max-turns 3 --output-format json` | +| 作業の再開 | `claude -r "session-name"` | +| カスタムモデル | `claude --model opus "complex task"` | +| 最小モード | `claude --bare "quick query"` | +| 予算上限付き実行 | `claude -p --max-budget-usd 2.00 "analyze code"` | + +--- + +## トラブルシューティング + +### コマンドが見つからない + +**問題:** `claude: command not found` + +**対処法:** +- Claude Code をインストール: `npm install -g @anthropic-ai/claude-code` +- PATH に npm のグローバル bin ディレクトリが含まれていることを確認 +- フルパスで実行を試す: `npx claude` + +### API キーの問題 + +**問題:** 認証に失敗する + +**対処法:** +- API キーを設定: `export ANTHROPIC_API_KEY=your-key` +- キーが有効でクレジットが十分か確認 +- 要求モデルに対するキー権限を確認 + +### セッションが見つからない + +**問題:** セッションを再開できない + +**対処法:** +- 利用可能なセッションを一覧表示し、正しい名前／ID を確認 +- セッションは一定期間使用しないと失効する場合がある +- `-c` で直近のセッションを継続する + +### 出力フォーマットの問題 + +**問題:** JSON 出力が壊れている + +**対処法:** +- `--json-schema` で構造を強制する +- プロンプト内に明示的な JSON 指示を含める +- プロンプトで JSON を要求するだけでなく `--output-format json` を使用する + +### 権限拒否 + +**問題:** ツール実行がブロックされる + +**対処法:** +- `--permission-mode` 設定を確認 +- `--allowedTools` と `--disallowedTools` フラグを見直す +- 自動化用途では（注意のうえ）`--dangerously-skip-permissions` を使用 + +--- + +## 追加リソース + +- **[公式 CLI リファレンス](https://code.claude.com/docs/en/cli-reference)** - 完全なコマンドリファレンス +- **[ヘッドレスモードのドキュメント](https://code.claude.com/docs/en/headless)** - 自動実行 +- **[スラッシュコマンド](../01-slash-commands/)** - Claude 内のカスタムショートカット +- **[メモリガイド](../02-memory/)** - CLAUDE.md による永続コンテキスト +- **[MCP プロトコル](../05-mcp/)** - 外部ツール連携 +- **[高度な機能](../09-advanced-features/)** - プランニングモード、拡張思考 +- **[サブエージェントガイド](../04-subagents/)** - 委譲によるタスク実行 + +--- + +*[Claude How To](../) ガイドシリーズの一部* + +--- + +**最終更新**: 2026 年 4 月 24 日 +**Claude Code バージョン**: 2.1.119 +**出典**: +- https://code.claude.com/docs/en/cli-reference +- https://code.claude.com/docs/en/settings +- https://code.claude.com/docs/en/changelog +- https://www.anthropic.com/news/claude-opus-4-7 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.113 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.116 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.118 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**対応モデル**: Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/CATALOG.md b/ja/CATALOG.md new file mode 100644 index 0000000..9aa84e3 --- /dev/null +++ b/ja/CATALOG.md @@ -0,0 +1,544 @@ + + + + + + + Claude How To + + +# Claude Code 機能カタログ + +> Claude Code 全機能のクイックリファレンス：コマンド、エージェント、スキル、プラグイン、フック。 + +**ナビゲーション**：[コマンド](#スラッシュコマンド) | [権限モード](#権限モード) | [サブエージェント](#サブエージェント) | [スキル](#スキル) | [プラグイン](#プラグイン) | [MCP サーバ](#mcp-サーバ) | [フック](#フック) | [メモリ](#メモリファイル) | [新機能](#新機能2026-年-4-月) + +--- + +## サマリー + +| 機能 | 組み込み | 例 | 合計 | リファレンス | +|---------|----------|----------|-------|-----------| +| **スラッシュコマンド** | 60 個以上 | 8 | 68 個以上 | [01-slash-commands/](01-slash-commands/) | +| **サブエージェント** | 6 | 11 | 17 | [04-subagents/](04-subagents/) | +| **スキル** | バンドル 5 | 4 | 9 | [03-skills/](03-skills/) | +| **プラグイン** | - | 3 | 3 | [07-plugins/](07-plugins/) | +| **MCP サーバ** | 1 | 8 | 9 | [05-mcp/](05-mcp/) | +| **フック** | 28 イベント | 8 | 8 | [06-hooks/](06-hooks/) | +| **メモリ** | 7 種類 | 3 | 3 | [02-memory/](02-memory/) | +| **合計** | **99** | **45** | **119** | | + +--- + +## スラッシュコマンド + +コマンドはユーザーが起動する、特定の動作を実行するショートカットである。 + +### 組み込みコマンド + +| コマンド | 説明 | 利用シーン | +|---------|-------------|-------------| +| `/help` | ヘルプ情報を表示 | 初心者、コマンド習得 | +| `/btw` | 一時的な脇道質問 — メインコンテキストを汚さない | ちょっとした横道質問 | +| `/chrome` | Chrome 連携を設定 | ブラウザ自動化 | +| `/clear` | 会話履歴をクリア | やり直し、コンテキスト削減 | +| `/diff` | 対話式 diff ビューア | 変更レビュー | +| `/config` | 設定を表示・編集 | 動作カスタマイズ | +| `/status` | セッション状態を表示 | 現状確認 | +| `/agents` | 利用可能エージェントを表示 | 委譲オプション確認 | +| `/skills` | 利用可能スキルを表示 | 自動起動機能の確認 | +| `/hooks` | 設定済みフックを表示 | 自動化のデバッグ | +| `/insights` | セッションパターンを分析 | セッション最適化 | +| `/install-slack-app` | Claude Slack アプリのインストール | Slack 連携 | +| `/keybindings` | キーボードショートカットをカスタマイズ | キーカスタマイズ | +| `/mcp` | MCP サーバを一覧表示 | 外部統合の確認 | +| `/memory` | 読み込まれたメモリファイルを表示 | コンテキスト読込デバッグ | +| `/mobile` | モバイル用 QR コードを生成 | モバイルアクセス | +| `/passes` | 使用パスを表示 | サブスクリプション情報 | +| `/plugin` | プラグインを管理 | 拡張のインストール / 削除 | +| `/plan` | プランニングモードに入る | 複雑な実装 | +| `/proactive` | `/loop` のエイリアス（v2.1.105） | `/loop` と同じ | +| `/recap` | セッションに戻ってきたときに要約を表示 | 離席後のコンテキスト把握 | +| `/rewind` | チェックポイントへ巻き戻し | 変更取消、別案探索 | +| `/checkpoint` | チェックポイント管理 | 状態の保存 / 復元 | +| `/cost` | `/usage` のコストタブを開くエイリアス（v2.1.118+） | 支出監視 | +| `/context` | コンテキストウィンドウ使用量を表示 | 会話長の管理 | +| `/export` | 会話をエクスポート | 参照用に保存 | +| `/extra-usage` | 追加使用上限を設定 | レート制限管理 | +| `/feedback` | フィードバックやバグ報告を送信 | 問題報告 | +| `/login` | Anthropic で認証 | 機能アクセス | +| `/logout` | サインアウト | アカウント切替 | +| `/sandbox` | サンドボックスモード切替 | 安全なコマンド実行 | +| `/doctor` | 診断を実行 | 問題のトラブルシューティング | +| `/reload-plugins` | インストール済みプラグインを再読込 | プラグイン管理 | +| `/release-notes` | リリースノートを表示 | 新機能の確認 | +| `/remote-control` | リモートコントロールを有効化 | リモートアクセス | +| `/permissions` | 権限を管理 | アクセス制御 | +| `/session` | セッションを管理 | マルチセッションワークフロー | +| `/rename` | 現在のセッションを改名 | セッション整理 | +| `/resume` | 過去のセッションを再開 | 作業の継続 | +| `/todo` | TODO リストを表示・管理 | タスク追跡 | +| `/tui` | フルスクリーン TUI（テキストユーザーインターフェース）モード切替 | フルスクリーン / tmux でのちらつきのない描画 | +| `/tasks` | バックグラウンドタスクを表示 | 非同期処理の監視 | +| `/copy` | 直前の応答をクリップボードにコピー | 出力の素早い共有 | +| `/teleport` | セッションを別マシンに転送 | リモートでの作業継続 | +| `/desktop` | Claude デスクトップアプリを開く | デスクトップへ切替 | +| `/theme` | カラーテーマを変更。v2.1.118 で `~/.claude/themes/.json` 経由のカスタムテーマが追加（プラグインは `themes/` ディレクトリを同梱可能） | 外観のカスタマイズ | +| `/usage` | 使用量・コスト・統計の正規コマンド — `/cost` と `/stats` を 1 つのタブビューに統合（v2.1.118） | クォータとコストの監視 | +| `/focus` | フォーカスビュー（注意散漫を防ぐ出力表示）を切替 | 長時間タスク中の視覚的ノイズ低減 | +| `/fork` | 現在の会話をフォーク | 別案の探索 | +| `/stats` | `/usage` の stats タブを開くエイリアス（v2.1.118+） | セッション指標の確認 | +| `/statusline` | ステータスラインを設定 | ステータス表示のカスタマイズ | +| `/stickers` | セッションステッカーを表示 | 楽しいご褒美 | +| `/fast` | 高速出力モード切替 | 応答の高速化 | +| `/terminal-setup` | ターミナル統合を設定 | ターミナル機能のセットアップ | +| `/undo` | `/rewind` のエイリアス（v2.1.108） | `/rewind` と同じ | +| `/upgrade` | アップデート確認 | バージョン管理 | +| `/team-onboarding` | このプロジェクトの Claude Code 利用状況からオンボーディングガイドを生成 | 新メンバーのオンボーディング（v2.1.101） | +| `/ultraplan` | プランニングタスクを Claude Code Web セッションに渡す（plan モード） | 重い計画作業のオフロード（Research Preview、v2.1.91+） | +| `/ultrareview` | 現在の変更に対するクラウドのマルチエージェントコードレビューを実行 | マージ前の深いマルチエージェントレビュー（v2.1.112） | +| `/less-permission-prompts` | トランスクリプトをスキャンし、よく使う読取専用ツールの優先許可リストを提案 | プロジェクトでの権限プロンプト繰り返しを削減（v2.1.112） | + +### カスタムコマンド（例） + +| コマンド | 説明 | 利用シーン | スコープ | インストール | +|---------|-------------|-------------|-------|--------------| +| `/optimize` | コードを最適化分析 | パフォーマンス改善 | プロジェクト | `cp 01-slash-commands/optimize.md .claude/commands/` | +| `/pr` | プルリクエスト準備 | PR 提出前 | プロジェクト | `cp 01-slash-commands/pr.md .claude/commands/` | +| `/generate-api-docs` | API ドキュメント生成 | API のドキュメント化 | プロジェクト | `cp 01-slash-commands/generate-api-docs.md .claude/commands/` | +| `/commit` | コンテキスト付き git コミット作成 | 変更のコミット | ユーザー | `cp 01-slash-commands/commit.md .claude/commands/` | +| `/push-all` | ステージ・コミット・プッシュ | 高速デプロイ | ユーザー | `cp 01-slash-commands/push-all.md .claude/commands/` | +| `/doc-refactor` | ドキュメント再構成 | ドキュメント改善 | プロジェクト | `cp 01-slash-commands/doc-refactor.md .claude/commands/` | +| `/setup-ci-cd` | CI/CD パイプライン構築 | 新規プロジェクト | プロジェクト | `cp 01-slash-commands/setup-ci-cd.md .claude/commands/` | +| `/unit-test-expand` | テストカバレッジ拡張 | テスト強化 | プロジェクト | `cp 01-slash-commands/unit-test-expand.md .claude/commands/` | + +> **スコープ**：`ユーザー` = 個人ワークフロー（`~/.claude/commands/`）、`プロジェクト` = チーム共有（`.claude/commands/`） + +**リファレンス**：[01-slash-commands/](01-slash-commands/) | [公式ドキュメント](https://code.claude.com/docs/en/interactive-mode) + +**クイックインストール（全カスタムコマンド）**： +```bash +cp 01-slash-commands/*.md .claude/commands/ +``` + +--- + +## 権限モード + +Claude Code はツール使用の許可を制御する 6 つの権限モードをサポートする。 + +| モード | 説明 | 利用シーン | +|------|-------------|-------------| +| `default` | ツール呼び出しごとに確認 | 標準的な対話利用 | +| `acceptEdits` | ファイル編集を自動承認、それ以外は確認 | 信頼できる編集ワークフロー | +| `plan` | 読み取り専用ツールのみ、書き込みなし | 計画と探索 | +| `auto` | プロンプトなしですべてのツールを承認 | 完全自律動作（Research Preview） | +| `bypassPermissions` | すべての権限チェックをスキップ | CI/CD、ヘッドレス環境 | +| `dontAsk` | 権限が必要なツールをスキップ | 非対話スクリプト | + +> **注**：`auto` モードは Research Preview 機能（2026 年 3 月）。`bypassPermissions` は信頼されたサンドボックス環境でのみ利用すること。 + +**リファレンス**：[公式ドキュメント](https://code.claude.com/docs/en/permissions) + +--- + +## サブエージェント + +特定タスク向けに分離コンテキストを持つ専門特化 AI アシスタント。 + +### 組み込みサブエージェント + +| エージェント | 説明 | ツール | モデル | 利用シーン | +|-------|-------------|-------|-------|-------------| +| **general-purpose** | 多段タスク、調査 | 全ツール | モデル継承 | 複雑な調査、複数ファイルタスク | +| **Plan** | 実装計画 | Read、Glob、Grep、Bash | モデル継承 | アーキテクチャ設計、計画 | +| **Explore** | コードベース探索 | Read、Glob、Grep | Haiku 4.5 | 高速検索、コード理解 | +| **Bash** | コマンド実行 | Bash | モデル継承 | Git 操作、ターミナル作業 | +| **statusline-setup** | ステータスライン設定 | Bash、Read、Write | Sonnet 4.6 | ステータスライン表示の設定 | +| **Claude Code Guide** | ヘルプとドキュメント | Read、Glob、Grep | Haiku 4.5 | ヘルプ、機能学習 | + +### サブエージェント設定フィールド + +| フィールド | 型 | 説明 | +|-------|------|-------------| +| `name` | 文字列 | エージェント識別子 | +| `description` | 文字列 | エージェントの役割 | +| `model` | 文字列 | モデル上書き（例：`haiku-4.5`） | +| `tools` | 配列 | 許可ツール一覧 | +| `effort` | 文字列 | 推論努力レベル（`low`、`medium`、`high`） | +| `initialPrompt` | 文字列 | エージェント開始時に注入されるシステムプロンプト | +| `disallowedTools` | 配列 | 当エージェントに明示的に禁止するツール | + +### カスタムサブエージェント（例） + +| エージェント | 説明 | 利用シーン | スコープ | インストール | +|-------|-------------|-------------|-------|--------------| +| `code-reviewer` | 包括的なコード品質 | コードレビュー | プロジェクト | `cp 04-subagents/code-reviewer.md .claude/agents/` | +| `code-architect` | 機能アーキテクチャ設計 | 新機能計画 | プロジェクト | `cp 04-subagents/code-architect.md .claude/agents/` | +| `code-explorer` | コードベース深掘り分析 | 既存機能の理解 | プロジェクト | `cp 04-subagents/code-explorer.md .claude/agents/` | +| `clean-code-reviewer` | クリーンコード原則レビュー | 保守性レビュー | プロジェクト | `cp 04-subagents/clean-code-reviewer.md .claude/agents/` | +| `test-engineer` | テスト戦略とカバレッジ | テスト計画 | プロジェクト | `cp 04-subagents/test-engineer.md .claude/agents/` | +| `documentation-writer` | 技術ドキュメント | API ドキュメント、ガイド | プロジェクト | `cp 04-subagents/documentation-writer.md .claude/agents/` | +| `secure-reviewer` | セキュリティ重視レビュー | セキュリティ監査 | プロジェクト | `cp 04-subagents/secure-reviewer.md .claude/agents/` | +| `implementation-agent` | フル機能実装 | 機能開発 | プロジェクト | `cp 04-subagents/implementation-agent.md .claude/agents/` | +| `debugger` | 根本原因分析 | バグ調査 | ユーザー | `cp 04-subagents/debugger.md .claude/agents/` | +| `data-scientist` | SQL クエリ、データ分析 | データタスク | ユーザー | `cp 04-subagents/data-scientist.md .claude/agents/` | +| `performance-optimizer` | プロファイリングとチューニング | ボトルネック調査 | プロジェクト | `cp 04-subagents/performance-optimizer.md .claude/agents/` | + +> **スコープ**：`ユーザー` = 個人（`~/.claude/agents/`）、`プロジェクト` = チーム共有（`.claude/agents/`） + +**リファレンス**：[04-subagents/](04-subagents/) | [公式ドキュメント](https://code.claude.com/docs/en/sub-agents) + +**クイックインストール（全カスタムエージェント）**： +```bash +cp 04-subagents/*.md .claude/agents/ +``` + +--- + +## スキル + +指示書、スクリプト、テンプレートを伴う自動起動機能。 + +### スキル例 + +| スキル | 説明 | 自動起動の条件 | スコープ | インストール | +|-------|-------------|-------------------|-------|--------------| +| `code-review` | 包括的なコードレビュー | "Review this code", "Check quality" | プロジェクト | `cp -r 03-skills/code-review .claude/skills/` | +| `brand-voice` | ブランド一貫性チェック | マーケティングコピー作成時 | プロジェクト | `cp -r 03-skills/brand-voice .claude/skills/` | +| `doc-generator` | API ドキュメント生成 | "Generate docs", "Document API" | プロジェクト | `cp -r 03-skills/doc-generator .claude/skills/` | +| `refactor` | 体系的リファクタリング（Martin Fowler） | "Refactor this", "Clean up code" | ユーザー | `cp -r 03-skills/refactor ~/.claude/skills/` | + +> **スコープ**：`ユーザー` = 個人（`~/.claude/skills/`）、`プロジェクト` = チーム共有（`.claude/skills/`） + +### スキル構造 + +``` +~/.claude/skills/skill-name/ +├── SKILL.md # スキル定義と指示 +├── scripts/ # 補助スクリプト +└── templates/ # 出力テンプレート +``` + +### スキルフロントマターのフィールド + +スキルは設定のため `SKILL.md` 内で YAML フロントマターをサポートする。 + +| フィールド | 型 | 説明 | +|-------|------|-------------| +| `name` | 文字列 | スキル表示名 | +| `description` | 文字列 | スキルの役割 | +| `autoInvoke` | 配列 | 自動起動のトリガーフレーズ | +| `effort` | 文字列 | 推論努力レベル（`low`、`medium`、`high`） | +| `shell` | 文字列 | スクリプト実行に使うシェル（`bash`、`zsh`、`sh`） | + +**リファレンス**：[03-skills/](03-skills/) | [公式ドキュメント](https://code.claude.com/docs/en/skills) + +**クイックインストール（全スキル）**： +```bash +cp -r 03-skills/* ~/.claude/skills/ +``` + +### バンドルスキル + +| スキル | 説明 | 自動起動の条件 | +|-------|-------------|-------------------| +| `/simplify` | 品質目線でコードレビュー | コード執筆後 | +| `/batch` | 複数ファイルでプロンプト実行 | バッチ処理 | +| `/debug` | 失敗テスト・エラーのデバッグ | デバッグセッション | +| `/loop` | 一定間隔でプロンプト実行 | 反復タスク | +| `/claude-api` | Claude API でアプリ構築 | API 開発 | + +--- + +## プラグイン + +コマンド、エージェント、MCP サーバ、フックをまとめたバンドル。 + +### プラグイン例 + +| プラグイン | 説明 | 構成要素 | 利用シーン | スコープ | インストール | +|--------|-------------|------------|-------------|-------|--------------| +| `pr-review` | PR レビューワークフロー | コマンド 3、エージェント 3、GitHub MCP | コードレビュー | プロジェクト | `/plugin install pr-review` | +| `devops-automation` | デプロイと監視 | コマンド 4、エージェント 3、K8s MCP | DevOps タスク | プロジェクト | `/plugin install devops-automation` | +| `documentation` | ドキュメント生成スイート | コマンド 4、エージェント 3、テンプレート | ドキュメント | プロジェクト | `/plugin install documentation` | + +> **スコープ**：`プロジェクト` = チーム共有、`ユーザー` = 個人ワークフロー + +### プラグイン構造 + +``` +.claude-plugin/ +├── plugin.json # マニフェストファイル +├── commands/ # スラッシュコマンド +├── agents/ # サブエージェント +├── skills/ # スキル +├── mcp/ # MCP 設定 +├── hooks/ # フックスクリプト +└── scripts/ # ユーティリティスクリプト +``` + +**リファレンス**：[07-plugins/](07-plugins/) | [公式ドキュメント](https://code.claude.com/docs/en/plugins) + +**プラグイン管理コマンド**： +```bash +/plugin list # インストール済みプラグイン一覧 +/plugin install # プラグインをインストール +/plugin remove # プラグインを削除 +/plugin update # プラグインを更新 +``` + +--- + +## MCP サーバ + +外部ツールおよび API アクセスのための Model Context Protocol サーバ。 + +### 一般的な MCP サーバ + +| サーバ | 説明 | 利用シーン | スコープ | インストール | +|--------|-------------|-------------|-------|--------------| +| **GitHub** | PR 管理、issue、コード | GitHub ワークフロー | プロジェクト | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` | +| **Database** | SQL クエリ、データアクセス | DB 操作 | プロジェクト | `claude mcp add db -- npx -y @modelcontextprotocol/server-postgres` | +| **Filesystem** | 高度なファイル操作 | 複雑なファイルタスク | ユーザー | `claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem` | +| **Slack** | チームコミュニケーション | 通知、更新 | プロジェクト | 設定で構成 | +| **Google Docs** | ドキュメントアクセス | ドキュメント編集・レビュー | プロジェクト | 設定で構成 | +| **Asana** | プロジェクト管理 | タスク追跡 | プロジェクト | 設定で構成 | +| **Stripe** | 決済データ | 財務分析 | プロジェクト | 設定で構成 | +| **Memory** | 永続メモリ | セッション横断の想起 | ユーザー | 設定で構成 | +| **Context7** | ライブラリドキュメント | 最新ドキュメント検索 | 組み込み | 組み込み | + +> **スコープ**：`プロジェクト` = チーム（`.mcp.json`）、`ユーザー` = 個人（`~/.claude.json`）、`組み込み` = プリインストール + +### MCP 設定例 + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**リファレンス**：[05-mcp/](05-mcp/) | [MCP プロトコルドキュメント](https://modelcontextprotocol.io) + +**クイックインストール（GitHub MCP）**： +```bash +export GITHUB_TOKEN="your_token" && claude mcp add github -- npx -y @modelcontextprotocol/server-github +``` + +--- + +## フック + +Claude Code のイベントでシェルコマンドを自動実行するイベント駆動の自動化。 + +### フックイベント + +| イベント | 説明 | 発火タイミング | ユースケース | +|-------|-------------|----------------|-----------| +| `SessionStart` | セッション開始・再開 | セッション初期化時 | セットアップタスク | +| `InstructionsLoaded` | 指示読み込み完了 | CLAUDE.md またはルールファイルの読込時 | カスタム指示の処理 | +| `UserPromptSubmit` | プロンプト処理前 | ユーザーがメッセージ送信時 | 入力検証 | +| `PreToolUse` | ツール実行前 | 任意のツールが走る前 | 検証、ログ | +| `PermissionRequest` | 権限ダイアログ表示 | 機微な操作の前 | カスタム承認フロー | +| `PostToolUse` | ツール成功後 | 任意のツール完了後 | 整形、通知 | +| `PostToolUseFailure` | ツール実行失敗 | ツールエラー後 | エラー処理、ログ | +| `Notification` | 通知送信 | Claude が通知送信時 | 外部アラート | +| `SubagentStart` | サブエージェント生成 | サブエージェントタスク開始時 | サブエージェントコンテキスト初期化 | +| `SubagentStop` | サブエージェント終了 | サブエージェントタスク完了時 | アクション連鎖 | +| `Stop` | Claude が応答完了 | 応答完了時 | 後処理、レポート | +| `StopFailure` | API エラーでターン終了 | API エラー発生時 | エラー復旧、ログ | +| `TeammateIdle` | チームメンバーエージェントがアイドル | エージェントチーム協調時 | 作業の分配 | +| `TaskCompleted` | タスク完了マーク | タスク完了時 | タスク後処理 | +| `TaskCreated` | TaskCreate でタスク作成 | 新タスク作成時 | タスク追跡、ログ | +| `ConfigChange` | 設定更新 | 設定変更時 | 設定変更への対応 | +| `CwdChanged` | 作業ディレクトリ変更 | ディレクトリ変更時 | ディレクトリ別セットアップ | +| `FileChanged` | 監視ファイルの変更 | ファイル変更時 | ファイル監視、再ビルド | +| `PreCompact` | コンパクト操作前 | コンテキスト圧縮時 | 状態保全 | +| `PostCompact` | コンパクト完了後 | コンパクト完了時 | コンパクト後アクション | +| `WorktreeCreate` | ワークツリー作成中 | Git ワークツリー作成時 | ワークツリー環境セットアップ | +| `WorktreeRemove` | ワークツリー削除中 | Git ワークツリー削除時 | ワークツリーリソースのクリーンアップ | +| `Elicitation` | MCP サーバが入力を要求 | MCP elicitation 発生時 | 入力検証 | +| `ElicitationResult` | ユーザーが elicitation に応答 | ユーザー応答時 | 応答処理 | +| `SessionEnd` | セッション終了 | セッション終了時 | クリーンアップ、状態保存 | + +### フック例 + +| フック | 説明 | イベント | スコープ | インストール | +|------|-------------|-------|-------|--------------| +| `validate-bash.py` | コマンド検証 | PreToolUse:Bash | プロジェクト | `cp 06-hooks/validate-bash.py .claude/hooks/` | +| `security-scan.py` | セキュリティスキャン | PostToolUse:Write | プロジェクト | `cp 06-hooks/security-scan.py .claude/hooks/` | +| `format-code.sh` | 自動整形 | PostToolUse:Write | ユーザー | `cp 06-hooks/format-code.sh ~/.claude/hooks/` | +| `validate-prompt.py` | プロンプト検証 | UserPromptSubmit | プロジェクト | `cp 06-hooks/validate-prompt.py .claude/hooks/` | +| `context-tracker.py` | トークン使用量追跡 | Stop | ユーザー | `cp 06-hooks/context-tracker.py ~/.claude/hooks/` | +| `pre-commit.sh` | コミット前検証 | PreToolUse:Bash | プロジェクト | `cp 06-hooks/pre-commit.sh .claude/hooks/` | +| `log-bash.sh` | コマンドログ | PostToolUse:Bash | ユーザー | `cp 06-hooks/log-bash.sh ~/.claude/hooks/` | +| `dependency-check.sh` | マニフェスト変更時の脆弱性スキャン | PostToolUse:Write | プロジェクト | `cp 06-hooks/dependency-check.sh .claude/hooks/` | + +> **スコープ**：`プロジェクト` = チーム（`.claude/settings.json`）、`ユーザー` = 個人（`~/.claude/settings.json`） + +### フック設定 + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "command": "~/.claude/hooks/validate-bash.py" + } + ], + "PostToolUse": [ + { + "matcher": "Write", + "command": "~/.claude/hooks/format-code.sh" + } + ] + } +} +``` + +**リファレンス**：[06-hooks/](06-hooks/) | [公式ドキュメント](https://code.claude.com/docs/en/hooks) + +**クイックインストール（全フック）**： +```bash +mkdir -p ~/.claude/hooks && cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh +``` + +--- + +## メモリファイル + +セッション横断で自動読み込みされる永続コンテキスト。 + +### メモリの種類 + +| 種類 | 配置場所 | スコープ | 利用シーン | +|------|----------|-------|-------------| +| **マネージドポリシー** | 組織管理ポリシー | 組織 | 組織全体の標準を強制 | +| **プロジェクト** | `./CLAUDE.md` | プロジェクト（チーム） | チーム規約、プロジェクト文脈 | +| **プロジェクトルール** | `.claude/rules/` | プロジェクト（チーム） | モジュール化されたプロジェクトルール | +| **ユーザー** | `~/.claude/CLAUDE.md` | ユーザー（個人） | 個人の好み | +| **ユーザールール** | `~/.claude/rules/` | ユーザー（個人） | モジュール化された個人ルール | +| **ローカル** | `./CLAUDE.local.md` | ローカル（git 無視） | マシン固有の上書き（2026 年 3 月時点で公式ドキュメントに記載なし、レガシーの可能性） | +| **Auto Memory** | 自動 | セッション | 自動取得された洞察と訂正 | + +> **スコープ**：`組織` = 管理者管理、`プロジェクト` = git でチーム共有、`ユーザー` = 個人の好み、`ローカル` = コミット非対象、`セッション` = 自動管理 + +**リファレンス**：[02-memory/](02-memory/) | [公式ドキュメント](https://code.claude.com/docs/en/memory) + +**クイックインストール**： +```bash +cp 02-memory/project-CLAUDE.md ./CLAUDE.md +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +--- + +## 新機能（2026 年 4 月） + +| 機能 | 説明 | 使い方 | +|---------|-------------|------------| +| **/focus** | 注意散漫を防ぐ出力表示のためのフォーカスビュー切替（v2.1.110） | `/focus` で長時間タスク中の視覚的ノイズを低減 | +| **/proactive** | `/loop` のエイリアス — 同じ反復タスク動作（v2.1.105） | `/proactive` を `/loop` と互換に利用 | +| **/recap** | 既存セッションに戻ったときに要約を表示（v2.1.108） | 離席後に `/recap` を実行して文脈を取り戻す | +| **/tui** | フルスクリーン TUI モードを切替してちらつきのない描画（v2.1.110） | フルスクリーンターミナルや tmux で `/tui` を使う | +| **/undo** | `/rewind` のエイリアス — 直前のチェックポイントへ戻す（v2.1.108） | `/undo` を `/rewind` と互換に利用 | +| **Monitor ツール** | バックグラウンドコマンドの stdout を監視し、ポーリングではなくイベントで反応（v2.1.98+） | [高度な機能](09-advanced-features/) 経由で Monitor ツールを利用 | +| **/team-onboarding** | プロジェクトの Claude Code 設定からオンボーディングガイドを自動生成（v2.1.101） | プロジェクトで `/team-onboarding` を実行 | +| **Ultraplan 自動作成** | 初回 `/ultraplan` 実行時にクラウド環境を自動作成、手動セットアップ不要（v2.1.101） | `/ultraplan ` を使う | +| **リモートコントロール** | API 経由で Claude Code セッションを遠隔制御 | リモートコントロール API でプロンプト送信と応答取得をプログラム的に行う | +| **Web セッション** | ブラウザベース環境で Claude Code を実行 | `claude web` または Anthropic Console でアクセス | +| **デスクトップアプリ** | Claude Code のネイティブデスクトップアプリ | `/desktop` または Anthropic サイトからダウンロード | +| **Agent Teams** | 関連タスクで複数エージェントを協調 | コラボレーションと文脈共有を行う teammate エージェントを設定 | +| **タスクリスト** | バックグラウンドタスクの管理と監視 | `/tasks` でバックグラウンド処理を表示・管理 | +| **プロンプト候補** | コンテキスト依存のコマンド候補 | 現在の文脈に応じて候補が自動表示 | +| **Git ワークツリー** | 並列開発のための隔離 git ワークツリー | ワークツリーコマンドで安全な並列ブランチ作業 | +| **サンドボックス化** | 安全のための隔離実行環境 | `/sandbox` で切替、制限環境内でコマンドを実行 | +| **MCP OAuth** | MCP サーバ向け OAuth 認証 | 安全なアクセスのため MCP サーバ設定で OAuth 認証情報を構成 | +| **MCP ツール検索** | MCP ツールを動的に検索・発見 | 接続済みサーバ全体で利用可能な MCP ツールを検索 | +| **スケジュールタスク** | `/loop` および cron ツールで反復タスクを設定 | `/loop 5m /command` または CronCreate ツールを使う | +| **Chrome 連携** | ヘッドレス Chromium によるブラウザ自動化 | `--chrome` フラグまたは `/chrome` コマンドを使う | +| **キーバインドカスタマイズ** | コード対応を含むキーバインドのカスタマイズ | `/keybindings` を使うか `~/.claude/keybindings.json` を編集 | +| **Auto Mode** | 権限プロンプトなしの完全自律動作（Research Preview） | `--mode auto` または `/permissions auto` を使う、2026 年 3 月 | +| **チャンネル** | 複数チャネル通信（Telegram、Slack など）（Research Preview） | チャンネルプラグインを設定、2026 年 3 月 | +| **音声入力** | プロンプトの音声入力 | マイクアイコンまたは音声キーバインドを使う | +| **Agent フック種別** | シェルコマンド実行ではなくサブエージェントを生成するフック | フック設定で `"type": "agent"` を指定 | +| **Prompt フック種別** | プロンプトテキストを会話に注入するフック | フック設定で `"type": "prompt"` を指定 | +| **MCP Elicitation** | MCP サーバがツール実行中にユーザー入力を要求できる | `Elicitation` および `ElicitationResult` フックイベントで処理 | +| **プラグイン LSP サポート** | プラグイン経由の Language Server Protocol 統合 | エディタ機能のため `plugin.json` で LSP サーバを設定 | +| **マネージド Drop-in** | 組織管理のドロップイン設定（v2.1.83） | 管理ポリシーで管理者が設定、全ユーザーに自動適用 | + +--- + +## クイックリファレンスマトリクス + +### 機能選定ガイド + +| 必要なもの | 推奨機能 | 理由 | +|------|---------------------|-----| +| 高速ショートカット | スラッシュコマンド | 手動、即時 | +| 永続コンテキスト | メモリ | 自動読み込み | +| 複雑な自動化 | スキル | 自動起動 | +| 専門タスク | サブエージェント | コンテキスト分離 | +| 外部データ | MCP サーバ | リアルタイムアクセス | +| イベント自動化 | フック | イベントトリガー | +| 完全ソリューション | プラグイン | オールインワン | + +### インストール優先順位 + +| 優先度 | 機能 | コマンド | +|----------|---------|---------| +| 1. 必須 | メモリ | `cp 02-memory/project-CLAUDE.md ./CLAUDE.md` | +| 2. 日常利用 | スラッシュコマンド | `cp 01-slash-commands/*.md .claude/commands/` | +| 3. 品質 | サブエージェント | `cp 04-subagents/*.md .claude/agents/` | +| 4. 自動化 | フック | `cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh` | +| 5. 外部 | MCP | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` | +| 6. 高度 | スキル | `cp -r 03-skills/* ~/.claude/skills/` | +| 7. 完全 | プラグイン | `/plugin install pr-review` | + +--- + +## ワンコマンド完全インストール + +このリポジトリの全例題をインストールする： + +```bash +# ディレクトリを作成 +mkdir -p .claude/{commands,agents,skills} ~/.claude/{hooks,skills} + +# 全機能をインストール +cp 01-slash-commands/*.md .claude/commands/ && \ +cp 02-memory/project-CLAUDE.md ./CLAUDE.md && \ +cp -r 03-skills/* ~/.claude/skills/ && \ +cp 04-subagents/*.md .claude/agents/ && \ +cp 06-hooks/*.sh ~/.claude/hooks/ && \ +chmod +x ~/.claude/hooks/*.sh +``` + +--- + +## 追加リソース + +- [Claude Code 公式ドキュメント](https://code.claude.com/docs/en/overview) +- [MCP プロトコル仕様](https://modelcontextprotocol.io) +- [学習ロードマップ](LEARNING-ROADMAP.md) +- [メイン README](README.md) + +--- + +**最終更新**：2026 年 4 月 24 日 +**Claude Code バージョン**：2.1.119 +**情報源**： +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/commands +- https://code.claude.com/docs/en/hooks +- https://github.com/anthropics/claude-code/releases/tag/v2.1.118 +**互換モデル**：Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/CHANGELOG.md b/ja/CHANGELOG.md new file mode 100644 index 0000000..1e1b984 --- /dev/null +++ b/ja/CHANGELOG.md @@ -0,0 +1,192 @@ + + + + +# 変更履歴 + +## v2.1.112 — 2026-04-16 + +### ハイライト + +- すべての英語チュートリアルを Claude Code v2.1.112 および新しい Opus 4.7 モデル（`claude-opus-4-7`）に同期。Opus 4.7 でデフォルトとなる新しい `xhigh` エフォートレベル（`high` と `max` の中間）、2 つの新しい組み込みスラッシュコマンド（`/ultrareview`、`/less-permission-prompts`）、Opus 4.7 の Max サブスクライバー向けに `--enable-auto-mode` を不要としたオートモード、Windows の PowerShell ツール、「Auto（ターミナルに合わせる）」テーマ、およびプロンプト名で命名されるプランファイルを反映。18 件の英語ドキュメントのフッターを Claude Code v2.1.112 に更新。@Luong NGUYEN + +### 機能 + +- 全モジュール、ルートドキュメント、サンプル、リファレンスにわたるウクライナ語（uk）ローカライズを完全追加（039dde2）@Evgenij I + +### バグ修正 + +- pre-tool-check.sh フックのプロトコルバグを修正（bce7cf8）@yarlinghe +- CI を通すため不正な mermaid サンプルをテキストブロックに変更（b8a7b1f）@Evgenij I +- ウクライナ語版 claude_concepts_guide.md の目次における CP1251 エンコード問題を修正（d970cc6）@Evgenij I +- スタブのウクライナ語 README を完全翻訳に置き換え、壊れたアンカーを修正（f6d73e2）@Evgenij I +- 全フッターの Claude Code バージョンを 2.1.97 に統一（63a1416）@Luong NGUYEN +- 2026-04-09 のドキュメント正確性アップデートを適用（e015f39）@Luong NGUYEN + +### ドキュメント + +- Claude Code v2.1.112 に同期（Opus 4.7、`xhigh` エフォート、`/ultrareview`、`/less-permission-prompts`、PowerShell ツール、Auto-match-terminal テーマ）@Luong NGUYEN +- Claude Code v2.1.110 に同期（TUI、プッシュ通知、セッションリキャップ）（15f0085）@Luong NGUYEN +- Claude Code v2.1.101 に同期（`/team-onboarding`、`/ultraplan`、Monitor ツール）（2deba3a）@Luong NGUYEN +- ベトナム語ドキュメントを英語ソースに同期（561c6cb）@Thiên Toán +- 全ファイルの Last Updated 日付と Claude Code バージョンを更新（7f2e773）@Luong NGUYEN +- 言語切替えにウクライナ語へのリンクを追加（9c224ff）@Luong NGUYEN +- コントリビューターセクションを削除（f07313d）@Luong NGUYEN +- GitHub メトリクスを 21,800+ stars、2,585+ forks に更新（4f55374）@Luong NGUYEN + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.3.0...v2.1.112 + +--- + +## v2.3.0 — 2026-04-07 + +### 機能 + +- 言語ごとの EPUB アーティファクトをビルド・公開（90e9c30）@Thiên Toán +- 不足していた pre-tool-check.sh フックを 06-hooks に追加（b511ed1）@JiayuWang +- zh/ ディレクトリに中国語翻訳を追加（89e89d4）@Luong NGUYEN +- performance-optimizer サブエージェントと dependency-check フックを追加（f53d080）@qk + +### バグ修正 + +- Windows Git Bash 互換性 + stdin JSON プロトコル（2cbb10c）@Luong NGUYEN +- 08-checkpoints の autoCheckpoint 設定ドキュメントを修正（749c79f）@JiayuWang +- プレースホルダー置換の代わりに SVG 画像を埋め込み（1b16709）@Thiên Toán +- memory README におけるネストされたコードフェンスのレンダリングを修正（ce24423）@Zhaoshan Duan +- squash merge により失われたレビュー修正を再適用（34259ca）@Luong NGUYEN +- フックスクリプトを Windows Git Bash 互換にし、stdin JSON プロトコルを使用（107153d）@binyu li + +### ドキュメント + +- 全チュートリアルを Claude Code 最新ドキュメント（2026 年 4 月）に同期（72d3b01）@Luong NGUYEN +- 言語切替えに中国語へのリンクを追加（6cbaa4d）@Luong NGUYEN +- 英語とベトナム語の言語切替えを追加（100c45e）@Luong NGUYEN +- GitHub #1 Trending バッジを追加（0ca8c37）@Luong NGUYEN +- コンテキストゾーン監視のための cc-context-stats を導入（d41b335）@Luong NGUYEN +- luongnv89/skills コレクションと luongnv89/asm スキルマネージャを導入（7e3c0b6）@Luong NGUYEN +- README の統計情報を最新の GitHub メトリクス（5,900+ stars、690+ forks）に更新（5001525）@Luong NGUYEN +- README の統計情報を最新の GitHub メトリクス（3,900+ stars、460+ forks）に更新（9cb92d6）@Luong NGUYEN + +### リファクタリング + +- Kroki HTTP 依存をローカルの mmdc レンダリングに置き換え（e76bbe4）@Luong NGUYEN +- 品質チェックを pre-commit に前倒しし、CI を 2 回目のパスとする（6d1e0ae）@Luong NGUYEN +- オートモードの権限ベースラインを絞り込み（2790fb2）@Luong NGUYEN +- auto-adapt フックをワンタイム権限セットアップスクリプトに置き換え（995a5d6）@Luong NGUYEN + +### その他 + +- 品質ゲートのシフトレフト — pre-commit に mypy を追加し、CI 失敗を修正（699fb39）@Luong NGUYEN +- ベトナム語（Tiếng Việt）ローカライズを追加（a70777e）@Thiên Toán + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.2.0...v2.3.0 + +--- + +## v2.2.0 — 2026-03-26 + +### ドキュメント + +- 全チュートリアルとリファレンスを Claude Code v2.1.84 に同期（f78c094）@luongnv89 + - スラッシュコマンドを 55+ 個の組み込み + 5 個のバンドルスキルに更新、3 個を非推奨としてマーク + - フックイベントを 18 から 25 に拡張、`agent` フックタイプを追加（4 タイプに） + - Auto Mode、Channels、Voice Dictation を高度な機能に追加 + - スキル frontmatter に `effort`、`shell` フィールドを追加；エージェントに `initialPrompt`、`disallowedTools` フィールドを追加 + - WebSocket MCP トランスポート、エリシテーション、2KB ツール上限を追加 + - プラグインの LSP サポート、`userConfig`、`${CLAUDE_PLUGIN_DATA}` を追加 + - 全リファレンスドキュメント（CATALOG、QUICK_REFERENCE、LEARNING-ROADMAP、INDEX）を更新 +- README をランディングページ構成のガイドに書き直し（32a0776）@luongnv89 + +### バグ修正 + +- CI 準拠のため不足していた cSpell 単語と README セクションを追加（93f9d51）@luongnv89 +- cSpell 辞書に `Sandboxing` を追加（b80ce6f）@luongnv89 + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.1.1...v2.2.0 + +--- + +## v2.1.1 — 2026-03-13 + +### バグ修正 + +- CI のリンクチェックで失敗するデッドマーケットプレイスリンクを削除（3fdf0d6）@luongnv89 +- cSpell 辞書に `sandboxed` と `pycache` を追加（dc64618）@luongnv89 + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1 + +--- + +## v2.1.0 — 2026-03-13 + +### 機能 + +- セルフアセスメントとレッスンクイズスキルによる適応学習パスを追加（1ef46cd）@luongnv89 + - `/self-assessment` — 10 個の機能領域にわたる対話型習熟度クイズと個別最適化された学習パス + - `/lesson-quiz [lesson]` — 8〜10 問の的を絞った質問によるレッスンごとの知識チェック + +### バグ修正 + +- 壊れた URL、非推奨化、古いリファレンスを更新（8fe4520）@luongnv89 +- リソースおよび self-assessment スキル内の壊れたリンクを修正（7a05863）@luongnv89 +- concepts ガイドのネストされたコードブロックにチルダフェンスを使用（5f82719）@VikalpP +- cSpell 辞書に不足していた単語を追加（8df7572）@luongnv89 + +### ドキュメント + +- フェーズ 5 QA — ドキュメント全体の整合性、URL、用語を修正（00bbe4c）@luongnv89 +- フェーズ 3〜4 完了 — 新機能のカバレッジとリファレンスドキュメントの更新（132de29）@luongnv89 +- MCP コンテキスト肥大化セクションに MCPorter ランタイムを追加（ef52705）@luongnv89 +- 6 つのガイドに不足していたコマンド、機能、設定を追加（4bc8f15）@luongnv89 +- 既存リポジトリ規約に基づくスタイルガイドを追加（84141d0）@luongnv89 +- ガイド比較表に self-assessment 行を追加（8fe0c96）@luongnv89 +- PR #7 のため VikalpP をコントリビューターリストに追加（d5b4350）@luongnv89 +- self-assessment と lesson-quiz スキルへの参照を README とロードマップに追加（d5a6106）@luongnv89 + +### 新規コントリビュータ + +- @VikalpP が #7 で初コントリビュート + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.0.0...v2.1.0 + +--- + +## v2.0.0 — 2026-02-01 + +### 機能 + +- 全ドキュメントを Claude Code 2026 年 2 月の機能に同期（487c96d） + - 10 個のチュートリアルディレクトリと 7 個のリファレンスドキュメントにまたがる 26 ファイルを更新 + - **Auto Memory**（プロジェクトごとの永続的な学習）のドキュメントを追加 + - **Remote Control**、**Web Sessions**、**Desktop App** のドキュメントを追加 + - **Agent Teams**（実験的なマルチエージェント協調）のドキュメントを追加 + - **MCP OAuth 2.0**、**Tool Search**、**Claude.ai Connectors** のドキュメントを追加 + - サブエージェントの **Persistent Memory** と **Worktree Isolation** のドキュメントを追加 + - **Background Subagents**、**Task List**、**Prompt Suggestions** のドキュメントを追加 + - **Sandboxing** と **Managed Settings**（Enterprise）のドキュメントを追加 + - **HTTP Hooks** と 7 個の新しいフックイベントのドキュメントを追加 + - **Plugin Settings**、**LSP Servers**、Marketplace アップデートのドキュメントを追加 + - **Summarize from Checkpoint** リワインドオプションのドキュメントを追加 + - 17 個の新スラッシュコマンド（`/fork`、`/desktop`、`/teleport`、`/tasks`、`/fast` など）をドキュメント化 + - 新しい CLI フラグ（`--worktree`、`--from-pr`、`--remote`、`--teleport`、`--teammate-mode` など）をドキュメント化 + - オートメモリ、エフォートレベル、エージェントチームなどに関する新しい環境変数をドキュメント化 + +### デザイン + +- ロゴをコンパス・ブラケットマークと最小限のパレットに刷新（20779db） + +### バグ修正 / 訂正 + +- モデル名を更新：Sonnet 4.5 → **Sonnet 4.6**、Opus 4.5 → **Opus 4.6** +- 権限モード名を修正：架空の「Unrestricted/Confirm/Read-only」を実在する `default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions` に置換 +- フックイベントを修正：架空の `PreCommit`/`PostCommit`/`PrePush` を削除し、実在のイベント（`SubagentStart`、`WorktreeCreate`、`ConfigChange` など）を追加 +- CLI 構文を修正：`claude-code --headless` を `claude -p`（print mode）に置換 +- チェックポイントコマンドを修正：架空の `/checkpoint save/list/rewind/diff` を実在の `Esc+Esc` / `/rewind` インターフェースに置換 +- セッション管理を修正：架空の `/session list/new/switch/save` を実在の `/resume`/`/rename`/`/fork` に置換 +- プラグインマニフェスト形式を修正：`plugin.yaml` → `.claude-plugin/plugin.json` +- MCP 設定パスを修正：`~/.claude/mcp.json` → `.mcp.json`（プロジェクト）/ `~/.claude.json`（ユーザー） +- ドキュメント URL を修正：`docs.claude.com` → `docs.anthropic.com`；架空の `plugins.claude.com` を削除 +- 複数ファイルにわたる架空の設定フィールドを削除 +- 全ファイルの "Last Updated" 日付を 2026 年 2 月に更新 + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/20779db...v2.0.0 diff --git a/ja/CLAUDE.md b/ja/CLAUDE.md new file mode 100644 index 0000000..ddf7493 --- /dev/null +++ b/ja/CLAUDE.md @@ -0,0 +1,161 @@ + + + + +# CLAUDE.md + +このファイルは、本リポジトリ内のコードを扱う際の Claude Code（claude.ai/code）向けガイドである。 + +## プロジェクト概要 + +Claude How To は Claude Code 機能のチュートリアルリポジトリである。これは **ドキュメント・アズ・コード** であり、主な成果物は実行可能アプリケーションではなく、番号付きの学習モジュールに整理された Markdown ファイルである。 + +**アーキテクチャ：** 各モジュール（01〜10）は Claude Code の特定の機能を、コピー＆ペースト可能なテンプレート、Mermaid 図、サンプルとともに解説する。ビルドシステムはドキュメントの品質を検証し、EPUB 電子書籍を生成する。 + +## よく使うコマンド + +### pre-commit 品質チェック + +すべてのドキュメントは、コミット前に 4 つの品質チェックを通過しなければならない（pre-commit フックで自動実行される）： + +```bash +# pre-commit フックをインストール（毎コミットで実行） +pre-commit install + +# 全チェックを手動で実行 +pre-commit run --all-files +``` + +4 つのチェックは以下のとおり： +1. **markdown-lint** — `markdownlint` による Markdown 構造とフォーマット +2. **cross-references** — 内部リンク、アンカー、コードフェンスの構文（Python スクリプト） +3. **mermaid-syntax** — すべての Mermaid 図が正しくパースされるかを検証（Python スクリプト） +4. **link-check** — 外部 URL が到達可能か（Python スクリプト） +5. **build-epub** — EPUB がエラーなく生成されるか（`.md` 変更時） + +### 開発環境のセットアップ + +```bash +# uv（Python パッケージマネージャ）をインストール +pip install uv + +# 仮想環境を作成して Python 依存関係をインストール +uv venv +source .venv/bin/activate +uv pip install -r scripts/requirements-dev.txt + +# Node.js ツール（Markdown リンタと Mermaid バリデータ）をインストール +npm install -g markdownlint-cli +npm install -g @mermaid-js/mermaid-cli + +# pre-commit フックをインストール +uv pip install pre-commit +pre-commit install +``` + +### テスト + +`scripts/` 内の Python スクリプトはユニットテストを持つ： + +```bash +# 全テストを実行 +pytest scripts/tests/ -v + +# カバレッジ付きで実行 +pytest scripts/tests/ -v --cov=scripts --cov-report=html + +# 特定のテストを実行 +pytest scripts/tests/test_build_epub.py -v +``` + +### コード品質 + +```bash +# Python コードをリント・整形 +ruff check scripts/ +ruff format scripts/ + +# セキュリティスキャン +bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/ + +# 型チェック +mypy scripts/ --ignore-missing-imports +``` + +### EPUB ビルド + +```bash +# 電子書籍を生成（Mermaid 図を Kroki.io API でレンダリング） +uv run scripts/build_epub.py + +# オプション付き +uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5 +``` + +## ディレクトリ構造 + +``` +├── 01-slash-commands/ # ユーザーが起動するショートカット +├── 02-memory/ # 永続コンテキストの例 +├── 03-skills/ # 再利用可能な能力 +├── 04-subagents/ # 専門 AI アシスタント +├── 05-mcp/ # Model Context Protocol の例 +├── 06-hooks/ # イベント駆動の自動化 +├── 07-plugins/ # バンドル機能 +├── 08-checkpoints/ # セッションのスナップショット +├── 09-advanced-features/ # プランニング、シンキング、バックグラウンド +├── 10-cli/ # CLI リファレンス +├── scripts/ +│ ├── build_epub.py # EPUB ジェネレータ（Mermaid を Kroki API でレンダリング） +│ ├── check_cross_references.py # 内部リンクを検証 +│ ├── check_links.py # 外部 URL を検証 +│ ├── check_mermaid.py # Mermaid 構文を検証 +│ └── tests/ # スクリプトのユニットテスト +├── .pre-commit-config.yaml # 品質チェック定義 +└── README.md # メインガイド（モジュール索引も兼ねる） +``` + +## コンテンツ作成ガイド + +### モジュール構造 +番号付きフォルダはいずれも以下のパターンに従う： +- **README.md** — 機能の概要と例 +- **サンプルファイル** — コピー＆ペースト可能なテンプレート（コマンドは `.md`、設定は `.json`、フックは `.sh`） +- ファイルは機能の複雑さと依存関係に従って整理されている + +### Mermaid 図 +- すべての図は正常にパースできること（pre-commit フックで検査） +- EPUB ビルドは Kroki.io API で図をレンダリングする（インターネット接続が必要） +- フローチャート、シーケンス図、アーキテクチャ可視化に Mermaid を使用する + +### 相互参照 +- 内部リンクは相対パスを使う（例：`(01-slash-commands/README.md)`） +- コードフェンスは言語指定が必須（例：` ```bash `、` ```python `） +- アンカーリンクは `#heading-name` 形式 + +### リンク検証 +- 外部 URL は到達可能であること（pre-commit フックで検査） +- 一時的なコンテンツへのリンクは避ける +- 可能な限りパーマリンクを使用する + +## 主要なアーキテクチャ上のポイント + +1. **番号付きフォルダは学習順序を示す** — 01〜10 のプレフィックスは Claude Code 機能の推奨学習順序を表す。この番号付けは意図的なものなので、アルファベット順に並べ替えてはならない。 + +2. **スクリプトはユーティリティであり製品ではない** — `scripts/` の Python スクリプトはドキュメント品質と EPUB 生成を支援するものである。実際のコンテンツは番号付きモジュールフォルダにある。 + +3. **pre-commit がゲートキーパー** — PR が承認される前に 4 つの品質チェックがすべて通過しなければならない。CI パイプラインは同じチェックを 2 回目のパスとして実行する。 + +4. **Mermaid のレンダリングにはネットワークが必要** — EPUB ビルドは図のレンダリングに Kroki.io API を呼び出す。ここでビルドが失敗する場合は、ネットワーク問題か Mermaid 構文エラーが典型的な原因である。 + +5. **これはチュートリアルでありライブラリではない** — コンテンツを追加する際は、明快な解説、コピー＆ペースト可能な例、視覚的な図を重視する。価値は概念を教えることにあり、再利用可能なコードを提供することではない。 + +## コミット規約 + +Conventional Commits 形式に従う： +- `feat(slash-commands): Add API documentation generator` +- `docs(memory): Improve personal preferences example` +- `fix(README): Correct table of contents link` +- `refactor(hooks): Simplify hook configuration examples` + +スコープは該当するフォルダ名に合わせる。 diff --git a/ja/CODE_OF_CONDUCT.md b/ja/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..97b4f83 --- /dev/null +++ b/ja/CODE_OF_CONDUCT.md @@ -0,0 +1,224 @@ + + + + +# コントリビュータ行動規範 + +## 私たちのコミットメント + +私たちは、すべての人にとって温かく、刺激に満ちたコミュニティを提供することにコミットしている。年齢、体格、カースト、障害、民族、性別特性、ジェンダーアイデンティティと表現、経験のレベル、教育、社会経済的地位、国籍、外見、人種、宗教、性的アイデンティティと指向にかかわらず、コミュニティへの参加が誰にとってもハラスメントのない体験となることを誓う。 + +私たちは、すべてのコントリビュータが尊重され、評価され、最善の仕事を行えるよう、ポジティブで、包摂的で、安全な環境を提供することに努める。 + +## 私たちの基準 + +ポジティブな環境作りに貢献する行動の例： + +### 敬意を払う +- 温かく包摂的な言葉遣いを使う +- 異なる意見、視点、経験を尊重する +- 建設的な批判を快く受け入れる +- 文化的・言語的な違いを尊重する +- 多様な背景を認め、称える + +### 協力する +- 衝突を解決するために協働する +- 他者の貢献にクレジットを与え、認める +- 他者の学びと成長を助ける +- 知識を共有し、質問する +- 仲間のコミュニティメンバーを支える + +### プロフェッショナルである +- 議論は焦点を絞り、生産的に保つ +- 見下したり侮辱したりする発言を避ける +- Issue や議論ではトピックから外れない +- 明確で敬意のあるコミュニケーションを使う +- 相手のメッセージに善意を仮定する + +### 包摂的である +- 新しいコントリビュータを歓迎する +- プロジェクトに新しい人のオンボーディングを助ける +- 建設的なフィードバックを提供する +- 異なる視点を持つ人々を含める +- 静かな声が聞かれる空間を作る + +## 受け入れがたい行動 + +以下の行動はハラスメントとみなされ、コミュニティ内では受け入れられない： + +### ハラスメントと差別 +- 性別、ジェンダーアイデンティティと表現、性的指向、障害、精神疾患、神経学的（非）定型性、外見、体格、年齢、人種、宗教に関連する不快なコメント +- 個人のライフスタイルの選択や慣行に関する歓迎されないコメント +- 故意の誤った性別呼称、または「デッドネーム」や拒否された名前の使用 +- 不必要または無関係な性的画像や行動 +- 同意のない、または停止を求められた後の身体接触および身体接触の模倣 + +### 虐待的な行動 +- 他者に向けられた暴力の脅迫または暴力的な言葉 +- いかなる個人に対する暴力の扇動または暴力的な言葉 +- 故意の威嚇 +- ストーキングや尾行 +- 繰り返しの接触によるハラスメント +- その他、不適切と合理的に判断されるあらゆる行動 + +### オンラインハラスメント +- オンラインの議論を持続的に妨害すること +- 他者の個人情報を公開すること（ドキシング） +- 歓迎されない性的な注意や誘い +- 荒らしや意図的な妨害 +- スパムや繰り返しの広告 +- 誤情報や偽情報の拡散 + +### 報復 +- 違反を報告した者に対する報復行為 +- 受け入れがたい行動を報告したことを理由に不当に扱うこと +- 報復として報告すると脅すこと + +## 適用範囲 + +この行動規範は以下に適用される： +- すべてのコミュニティ空間（GitHub Issue、プルリクエスト、ディスカッションなど） +- プロジェクトのリポジトリとドキュメント +- プロジェクトが主催または代表するイベントや集会 +- 個人がプロジェクトまたはコミュニティを代表する公の場 +- プロジェクトの業務に関連するプライベートな通信 + +行動規範はすべてのプロジェクト空間に適用され、また個人がプロジェクトやコミュニティを公の場で代表する際にも適用される。プロジェクトやコミュニティを代表する例には、公式プロジェクトのメールアドレスを使う、公式ソーシャルメディアアカウントから投稿する、オンライン／オフラインイベントで指名された代表として行動することが含まれる。 + +## 執行 + +コミュニティリーダーは、受け入れ可能な行動の基準を明確化し、執行する責任を負い、不適切、脅迫的、攻撃的、または有害とみなした行動に対して、適切で公正な是正措置を取る。 + +### 違反の報告 + +受け入れがたい行動を経験または目撃した場合、あるいはその他の懸念がある場合は、以下の方法で報告してほしい： + +1. **メール：** プロジェクトメンテナーに連絡する [連絡方法を提供できる場合は記載] +2. **GitHub Issues：** プライベートレポート機能（GitHub 設定で利用可能な場合） +3. **ダイレクトメッセージ：** プロジェクトメンテナーに直接連絡する + +以下を提供してほしい： +- あなたの連絡先情報 +- 関係者の名前（共有しても問題ない場合） +- インシデントの説明 +- コンテキストと関連リンク +- インシデントがあなたに与えた影響 + +**すべての報告は機密扱いとされる。** + +### 調査と対応 + +コミュニティリーダーは以下を行う： +- すべての苦情を迅速かつ公正にレビュー・調査する +- 報告者に関する機密性を維持する +- 報告者に対して報告状況を返答する +- 調査結果に基づいて適切な措置を取る + +可能な措置には以下が含まれる： +- プライベートな警告またはコーチング +- 公開謝罪（違反者が同意する場合） +- コミュニティ空間からの一時的または永久的な排除 +- コントリビュータ権限の剥奪 +- 必要に応じて GitHub やその他のプラットフォームへのエスカレーション + +### 異議申し立てプロセス + +判断が誤っていたと考える場合、以下の方法で異議を申し立てることができる： +1. 新しい情報やコンテキストを提供する +2. 複数のメンテナーによる再レビューを要求する +3. 初回判断から 30 日以内にフォローアップする + +## 敬意ある反対意見のためのガイドライン + +技術コミュニティでは意見の相違は自然なことである。敬意を持って反対するための方法： + +### Do +- ✅ 人ではなくアイデアに焦点を当てる +- ✅ 確認のための質問をする +- ✅ 相手の意見の妥当な点を認める +- ✅ 「私」を主語にした表現を使う（「私はこう考える、なぜなら…」） +- ✅ 出典と根拠を引用する +- ✅ 相手の視点に感謝する + +### Don't +- ❌ 個人攻撃をする +- ❌ 切り捨てる言葉を使う（「それはバカげている」など） +- ❌ 悪意があると決めつける +- ❌ 無関係な過去の対立を持ち出す +- ❌ トーンをエスカレートさせ敵対的になる +- ❌ 故意に他者の意見を歪曲する + +### 敬意ある反対意見の例 +``` +❌ 悪い例：「それはバカげたアイデアだし、君は明らかにこのプロジェクトを理解していない」 + +✅ よい例：「あなたの主張は理解できる。ただ、このアプローチは +大規模プロジェクトでスケールしにくいのではと懸念している。 +このベンチマークが示すパフォーマンスへの影響は考慮しただろうか？ +あなたの考えを聞かせてほしい」 +``` + +## 橋を架ける + +私たちは対話と和解の力を信じている： + +- 自分の行動を指摘されたら、聞いて反省する +- 害を与えた場合は謝罪する意志を持つ +- 他者の学びと成長を支える +- 人は誰でも間違いを犯すことを認める +- 非難ではなく解決策に焦点を当てる +- 善意を仮定しつつ、責任を持たせる + +## この規範に従うメリット + +敬意と包摂のあるコミュニティを維持することで、私たちは： +- 多様な視点を持つ多様なコントリビュータを引きつける +- 協力を通じてよりよい解決策を生み出す +- より強い関係を築く +- プロジェクトを新参者にとってより歓迎されるものにする +- より高品質なドキュメントとサンプルを生み出す +- 学びと成長の文化を育む + +## 特別な配慮 + +### メンテナー向け +- この規範を遵守する模範となる +- 報告に迅速に対応する +- 判断について透明性を保つ +- 衝突を公正に解決する +- すべての人にとって安全な環境を作る + +### コントリビュータ向け +- メンテナーや他のコントリビュータに善意を仮定する +- 建設的なフィードバックを提供する +- 新参者を支える +- コミュニティ基準の執行を助ける +- コミュニティ文化に主体的に関わる + +### 全員向け +- どのメッセージの背後にも人がいることを忘れない +- 不満を感じたら休憩を取る +- サポートが必要なときはコミュニティリーダーに連絡する +- 自分が一員でありたいコミュニティを作る一助となる + +## 帰属 + +この行動規範は以下から適応した： +- [Contributor Covenant](https://www.contributor-covenant.org/) +- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) +- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) + +## 質問は？ + +この行動規範について質問がある場合は、プロジェクトメンテナーに連絡してほしい。 + +## バージョン履歴 + +- **Version 1.0**（2026 年 1 月）— 初版行動規範 + +--- + +**温かく包摂的で敬意のあるコミュニティの構築にご協力いただきありがとうございます！** 🌟 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/CONTRIBUTING.md b/ja/CONTRIBUTING.md new file mode 100644 index 0000000..42bddd4 --- /dev/null +++ b/ja/CONTRIBUTING.md @@ -0,0 +1,385 @@ + + + + + + + Claude How To + + +# Claude How To へのコントリビュート + +このプロジェクトへのコントリビュートに興味を持ってくれてありがとう！このガイドは、効果的にコントリビュートする方法を理解する助けとなる。 + +## 本プロジェクトについて + +Claude How To は Claude Code への視覚的でサンプル駆動のガイドである。提供する内容： +- 機能の動作を説明する **Mermaid 図** +- すぐ使える **本番品質のテンプレート** +- コンテキストとベストプラクティスを伴う **実世界の例** +- 初心者から上級者までの **段階的な学習パス** + +## コントリビューションの種類 + +### 1. 新しい例やテンプレート +既存機能（スラッシュコマンド、スキル、フックなど）の例を追加する： +- コピー＆ペースト可能なコード +- 動作の明確な説明 +- ユースケースとメリット +- トラブルシューティングのヒント + +### 2. ドキュメントの改善 +- わかりにくい箇所の明確化 +- タイポと文法の修正 +- 不足している情報の追加 +- コード例の改善 + +### 3. 機能ガイド +新しい Claude Code 機能のガイドを作成する： +- ステップ・バイ・ステップのチュートリアル +- アーキテクチャ図 +- 一般的なパターンとアンチパターン +- 実世界のワークフロー + +### 4. バグ報告 +遭遇した問題を報告する： +- 期待した動作を記述 +- 実際の動作を記述 +- 再現手順を含める +- 関連する Claude Code バージョンと OS を追加 + +### 5. フィードバックと提案 +ガイドの改善を助ける： +- よりよい説明の提案 +- 抜けの指摘 +- 新しいセクションや再編成の推奨 + +## はじめに + +### 1. フォークとクローン +```bash +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto +``` + +### 2. ブランチを作成 +わかりやすいブランチ名を使う： +```bash +git checkout -b add/feature-name +git checkout -b fix/issue-description +git checkout -b docs/improvement-area +``` + +### 3. 環境のセットアップ + +pre-commit フックは、各コミット前に CI と同じチェックをローカルで実行する。すべての 4 チェックが通過しなければ PR は受理されない。 + +**必須の依存関係：** + +```bash +# Python ツール（このプロジェクトのパッケージマネージャは uv） +pip install uv +uv venv +source .venv/bin/activate +uv pip install -r scripts/requirements-dev.txt + +# Markdown リンタ（Node.js） +npm install -g markdownlint-cli + +# Mermaid 図バリデータ（Node.js） +npm install -g @mermaid-js/mermaid-cli + +# pre-commit をインストールしてフックを有効化 +uv pip install pre-commit +pre-commit install +``` + +**セットアップの確認：** + +```bash +pre-commit run --all-files +``` + +各コミットで実行されるフックは以下のとおり： + +| フック | 検査内容 | +|------|---------------| +| `markdown-lint` | Markdown のフォーマットと構造 | +| `cross-references` | 相対リンク、アンカー、コードフェンス | +| `mermaid-syntax` | すべての ` ```mermaid ` ブロックが正しくパースされるか | +| `link-check` | 外部 URL が到達可能か | +| `build-epub` | EPUB がエラーなく生成されるか（`.md` 変更時） | + +## ディレクトリ構造 + +``` +├── 01-slash-commands/ # ユーザーが起動するショートカット +├── 02-memory/ # 永続コンテキストの例 +├── 03-skills/ # 再利用可能な能力 +├── 04-subagents/ # 専門 AI アシスタント +├── 05-mcp/ # Model Context Protocol の例 +├── 06-hooks/ # イベント駆動の自動化 +├── 07-plugins/ # バンドル機能 +├── 08-checkpoints/ # セッションのスナップショット +├── 09-advanced-features/ # プランニング、シンキング、バックグラウンド +├── 10-cli/ # CLI リファレンス +├── scripts/ # ビルドおよびユーティリティスクリプト +└── README.md # メインガイド +``` + +## サンプルをコントリビュートする方法 + +### スラッシュコマンドの追加 +1. `01-slash-commands/` に `.md` ファイルを作成 +2. 以下を含める： + - 何をするかの明確な説明 + - ユースケース + - インストール手順 + - 使用例 + - カスタマイズのヒント +3. `01-slash-commands/README.md` を更新 + +### スキルの追加 +1. `03-skills/` にディレクトリを作成 +2. 以下を含める： + - `SKILL.md` — メインドキュメント + - `scripts/` — 必要に応じてヘルパースクリプト + - `templates/` — プロンプトテンプレート + - README に使用例 +3. `03-skills/README.md` を更新 + +### サブエージェントの追加 +1. `04-subagents/` に `.md` ファイルを作成 +2. 以下を含める： + - エージェントの目的と能力 + - システムプロンプトの構造 + - ユースケースの例 + - 統合例 +3. `04-subagents/README.md` を更新 + +### MCP 設定の追加 +1. `05-mcp/` に `.json` ファイルを作成 +2. 以下を含める： + - 設定の説明 + - 必要な環境変数 + - セットアップ手順 + - 使用例 +3. `05-mcp/README.md` を更新 + +### フックの追加 +1. `06-hooks/` に `.sh` ファイルを作成 +2. 以下を含める： + - シェバンと説明 + - ロジックを説明する明確なコメント + - エラー処理 + - セキュリティ考慮事項 +3. `06-hooks/README.md` を更新 + +## 執筆ガイドライン + +### Markdown スタイル +- 明確な見出し（セクションは H2、サブセクションは H3） +- 段落は短く焦点を絞って保つ +- リストには箇条書きを使う +- コードブロックには言語指定を含める +- セクション間に空行を入れる + +### コード例 +- 例はコピー＆ペーストで動くようにする +- 自明でないロジックにはコメントを付ける +- シンプル版と高度版の両方を含める +- 実世界のユースケースを示す +- 潜在的な問題点を強調する + +### ドキュメント +- 「何を」だけでなく「なぜ」を説明する +- 前提条件を含める +- トラブルシューティングを追加する +- 関連トピックへリンクする +- 初心者にやさしく保つ + +### JSON／YAML +- 適切なインデントを使う（2 または 4 スペースで一貫させる） +- 設定を説明するコメントを付ける +- 検証例を含める + +### 図 +- 可能なときは Mermaid を使う +- 図はシンプルで読みやすく保つ +- 図の下に説明を含める +- 関連セクションへリンクする + +## コミットガイドライン + +Conventional Commits 形式に従う： +``` +type(scope): description + +[optional body] +``` + +種別： +- `feat`：新機能や新サンプル +- `fix`：バグ修正や訂正 +- `docs`：ドキュメント変更 +- `refactor`：コード再構築 +- `style`：フォーマット変更 +- `test`：テスト追加・変更 +- `chore`：ビルド、依存関係など + +例： +``` +feat(slash-commands): Add API documentation generator +docs(memory): Improve personal preferences example +fix(README): Correct table of contents link +docs(skills): Add comprehensive code review skill +``` + +## 提出前 + +### チェックリスト +- [ ] コードがプロジェクトのスタイルと規約に従っている +- [ ] 新しいサンプルに明確なドキュメントが含まれている +- [ ] README ファイル（ローカルとルート）が更新されている +- [ ] 機微な情報（API キー、認証情報）が含まれていない +- [ ] サンプルがテスト済みで動作する +- [ ] リンクが検証され正しい +- [ ] ファイルの権限が適切（スクリプトは実行可能） +- [ ] コミットメッセージが明確で説明的 + +### ローカルテスト +```bash +# すべての pre-commit チェックを実行（CI と同じチェック） +pre-commit run --all-files + +# 変更内容をレビュー +git diff +``` + +## プルリクエストのプロセス + +1. **明確な説明とともに PR を作成：** + - 何を追加／修正するか？ + - なぜ必要か？ + - 関連する Issue（あれば） + +2. **関連する詳細を含める：** + - 新機能の場合：ユースケースを含める + - ドキュメントの場合：改善点を説明する + - サンプルの場合：ビフォア／アフターを示す + +3. **Issue にリンクする：** + - `Closes #123` を使うと関連 Issue を自動クローズ + +4. **レビューを辛抱強く待つ：** + - メンテナーが改善を提案することがある + - フィードバックに基づいて反復する + - 最終判断はメンテナーが行う + +## コードレビュープロセス + +レビュアーは以下を確認する： +- **正確性：** 説明どおりに動作するか？ +- **品質：** 本番品質か？ +- **一貫性：** プロジェクトのパターンに従っているか？ +- **ドキュメント：** 明確で完全か？ +- **セキュリティ：** 脆弱性はないか？ + +## Issue の報告 + +### バグ報告 +以下を含める： +- Claude Code バージョン +- オペレーティングシステム +- 再現手順 +- 期待される動作 +- 実際の動作 +- 該当する場合はスクリーンショット + +### 機能リクエスト +以下を含める： +- ユースケースまたは解決したい問題 +- 提案する解決策 +- 検討した代替案 +- 追加のコンテキスト + +### ドキュメントの問題 +以下を含める： +- わかりにくい点や不足している点 +- 改善案 +- 例または参照 + +## プロジェクトポリシー + +### 機微な情報 +- API キー、トークン、認証情報を絶対にコミットしない +- サンプルではプレースホルダ値を使う +- 設定ファイルには `.env.example` を含める +- 必要な環境変数をドキュメント化する + +### コード品質 +- 例は焦点を絞り読みやすく保つ +- 過剰設計を避ける +- 自明でないロジックにはコメントを含める +- 提出前に十分にテストする + +### 知的財産 +- オリジナルコンテンツの所有権は著者に帰属する +- プロジェクトは教育用ライセンスを使用する +- 既存の著作権を尊重する +- 必要に応じて帰属を提供する + +## ヘルプを得る + +- **質問：** GitHub Issues でディスカッションを開く +- **一般的なヘルプ：** 既存ドキュメントを確認 +- **開発のヘルプ：** 類似サンプルをレビュー +- **コードレビュー：** PR でメンテナーをタグ付け + +## 謝辞 + +コントリビュータは以下で認識される： +- README.md のコントリビュータセクション +- GitHub のコントリビュータページ +- コミット履歴 + +## セキュリティ + +例やドキュメントをコントリビュートする際は、安全なコーディング慣行に従ってほしい： + +- **シークレットや API キーをハードコードしない** — 環境変数を使う +- **セキュリティへの影響を警告する** — 潜在的なリスクを強調する +- **安全なデフォルトを使う** — セキュリティ機能をデフォルトで有効化する +- **入力を検証する** — 適切な入力検証とサニタイズを示す +- **セキュリティに関する注意を含める** — セキュリティ考慮事項を文書化する + +セキュリティ問題については、脆弱性報告プロセスについて [SECURITY.md](SECURITY.md) を参照。 + +## 行動規範 + +私たちは温かく包摂的なコミュニティを提供することにコミットしている。コミュニティ基準の詳細は [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) を読んでほしい。 + +要点： +- 敬意を持ち包摂的であること +- フィードバックを快く受け入れること +- 他者の学びと成長を助けること +- ハラスメントや差別を避けること +- 問題はメンテナーに報告すること + +すべてのコントリビュータはこの規範を遵守し、互いに親切と敬意を持って接することが求められる。 + +## ライセンス + +本プロジェクトへのコントリビューションは MIT License の下でライセンスされることに同意するものとする。詳細は [LICENSE](../LICENSE) を参照。 + +## 質問は？ + +- [README](README.md) を確認 +- [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md) をレビュー +- 既存サンプルを参照 +- 議論のために Issue を開く + +コントリビュートしてくれてありがとう！🙏 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/INDEX.md b/ja/INDEX.md new file mode 100644 index 0000000..af99890 --- /dev/null +++ b/ja/INDEX.md @@ -0,0 +1,893 @@ + + + + + + + Claude How To + + +# Claude Code 例題 — 完全索引 + +本ドキュメントは、機能種別ごとに整理された全サンプルファイルの完全索引である。 + +## サマリー統計 + +- **総ファイル数**：100 ファイル超 +- **カテゴリ**：10 機能カテゴリ +- **プラグイン**：完全プラグイン 3 個 +- **スキル**：完全スキル 6 個 +- **フック**：例フック 8 個 +- **すぐ使える**：すべての例 + +--- + +## 01. スラッシュコマンド（10 ファイル） + +日常ワークフロー向けにユーザーが実行するショートカット。 + +| ファイル | 説明 | ユースケース | +|------|-------------|----------| +| `optimize.md` | コード最適化アナライザ | パフォーマンス問題の検出 | +| `pr.md` | プルリクエスト準備 | PR ワークフロー自動化 | +| `generate-api-docs.md` | API ドキュメント生成 | API ドキュメント生成 | +| `commit.md` | コミットメッセージ補助 | 標準化されたコミット | +| `setup-ci-cd.md` | CI/CD パイプラインセットアップ | DevOps 自動化 | +| `push-all.md` | 全変更を push | 高速 push ワークフロー | +| `unit-test-expand.md` | ユニットテストカバレッジ拡張 | テスト自動化 | +| `doc-refactor.md` | ドキュメントリファクタリング | ドキュメント改善 | +| `pr-slash-command.png` | スクリーンショット例 | 視覚的参考 | +| `README.md` | ドキュメント | セットアップと使用ガイド | + +**インストール先**：`.claude/commands/` + +**使い方**：`/optimize`、`/pr`、`/generate-api-docs`、`/commit`、`/setup-ci-cd`、`/push-all`、`/unit-test-expand`、`/doc-refactor` + +--- + +## 02. メモリ（6 ファイル） + +永続的なコンテキストとプロジェクト規約。 + +| ファイル | 説明 | スコープ | 配置場所 | +|------|-------------|-------|----------| +| `project-CLAUDE.md` | チームプロジェクト規約 | プロジェクト全体 | `./CLAUDE.md` | +| `directory-api-CLAUDE.md` | API 固有のルール | ディレクトリ | `./src/api/CLAUDE.md` | +| `personal-CLAUDE.md` | 個人の好み | ユーザー | `~/.claude/CLAUDE.md` | +| `memory-saved.png` | スクリーンショット：保存済みメモリ | - | 視覚的参考 | +| `memory-ask-claude.png` | スクリーンショット：Claude に質問 | - | 視覚的参考 | +| `README.md` | ドキュメント | - | リファレンス | + +**インストール**：適切な場所にコピー + +**使い方**：Claude が自動的に読み込む + +--- + +## 03. スキル（28 ファイル） + +スクリプトとテンプレートを含む自動起動機能。 + +### コードレビュースキル（5 ファイル） +``` +code-review/ +├── SKILL.md # スキル定義 +├── scripts/ +│ ├── analyze-metrics.py # コードメトリクス分析 +│ └── compare-complexity.py # 複雑度比較 +└── templates/ + ├── review-checklist.md # レビューチェックリスト + └── finding-template.md # 指摘ドキュメント +``` + +**目的**：セキュリティ、パフォーマンス、品質分析を含む包括的コードレビュー + +**自動起動**：コードレビュー時 + +--- + +### ブランドボイススキル（4 ファイル） +``` +brand-voice/ +├── SKILL.md # スキル定義 +├── templates/ +│ ├── email-template.txt # メールフォーマット +│ └── social-post-template.txt # SNS フォーマット +└── tone-examples.md # メッセージ例 +``` + +**目的**：コミュニケーションでブランドボイスの一貫性を保つ + +**自動起動**：マーケティング文の作成時 + +--- + +### ドキュメント生成スキル（2 ファイル） +``` +doc-generator/ +├── SKILL.md # スキル定義 +└── generate-docs.py # Python ドキュメント抽出 +``` + +**目的**：ソースコードから包括的な API ドキュメントを生成 + +**自動起動**：API ドキュメントの作成・更新時 + +--- + +### リファクタスキル（5 ファイル） +``` +refactor/ +├── SKILL.md # スキル定義 +├── scripts/ +│ ├── analyze-complexity.py # 複雑度分析 +│ └── detect-smells.py # コードスメル検出 +├── references/ +│ ├── code-smells.md # コードスメルカタログ +│ └── refactoring-catalog.md # リファクタリングパターン +└── templates/ + └── refactoring-plan.md # リファクタリング計画テンプレート +``` + +**目的**：複雑度分析を伴う体系的リファクタリング + +**自動起動**：コードリファクタリング時 + +--- + +### Claude MD スキル（1 ファイル） +``` +claude-md/ +└── SKILL.md # スキル定義 +``` + +**目的**：CLAUDE.md ファイルの管理と最適化 + +--- + +### ブログ草稿スキル（3 ファイル） +``` +blog-draft/ +├── SKILL.md # スキル定義 +└── templates/ + ├── draft-template.md # ブログ草稿テンプレート + └── outline-template.md # ブログ構成テンプレート +``` + +**目的**：一貫した構造でブログ記事を草稿する + +**追加**：`README.md` — スキル概要と使用ガイド + +**インストール先**：`~/.claude/skills/` または `.claude/skills/` + +--- + +## 04. サブエージェント（9 ファイル） + +カスタム能力を持つ専門特化 AI アシスタント。 + +| ファイル | 説明 | ツール | ユースケース | +|------|-------------|-------|----------| +| `code-reviewer.md` | コード品質分析 | read, grep, diff, lint_runner | 包括的レビュー | +| `test-engineer.md` | テストカバレッジ分析 | read, write, bash, grep | テスト自動化 | +| `documentation-writer.md` | ドキュメント作成 | read, write, grep | ドキュメント生成 | +| `secure-reviewer.md` | セキュリティレビュー（読み取り専用） | read, grep | セキュリティ監査 | +| `implementation-agent.md` | フル実装 | read, write, bash, grep, edit, glob | 機能開発 | +| `debugger.md` | デバッグ専門家 | read, bash, grep | バグ調査 | +| `data-scientist.md` | データ分析専門家 | read, write, bash | データワークフロー | +| `clean-code-reviewer.md` | クリーンコード基準 | read, grep | コード品質 | +| `README.md` | ドキュメント | - | セットアップと使用ガイド | + +**インストール先**：`.claude/agents/` + +**使い方**：メインエージェントが自動委譲 + +--- + +## 05. MCP プロトコル（5 ファイル） + +外部ツールおよび API の統合。 + +| ファイル | 説明 | 連携先 | ユースケース | +|------|-------------|-----------------|----------| +| `github-mcp.json` | GitHub 連携 | GitHub API | PR / issue 管理 | +| `database-mcp.json` | データベースクエリ | PostgreSQL/MySQL | ライブデータクエリ | +| `filesystem-mcp.json` | ファイル操作 | ローカルファイルシステム | ファイル管理 | +| `multi-mcp.json` | 複数サーバ | GitHub + DB + Slack | 完全統合 | +| `README.md` | ドキュメント | - | セットアップと使用ガイド | + +**インストール先**：`.mcp.json`（プロジェクトスコープ）または `~/.claude.json`（ユーザースコープ） + +**使い方**：`/mcp__github__list_prs` など + +--- + +## 06. フック（9 ファイル） + +自動実行されるイベント駆動の自動化スクリプト。 + +| ファイル | 説明 | イベント | ユースケース | +|------|-------------|-------|----------| +| `format-code.sh` | コード自動整形 | PreToolUse:Write | コード整形 | +| `pre-commit.sh` | コミット前のテスト実行 | PreToolUse:Bash | テスト自動化 | +| `security-scan.sh` | セキュリティスキャン | PostToolUse:Write | セキュリティチェック | +| `log-bash.sh` | bash コマンド記録 | PostToolUse:Bash | コマンドログ | +| `validate-prompt.sh` | プロンプト検証 | PreToolUse | 入力検証 | +| `notify-team.sh` | 通知送信 | Notification | チーム通知 | +| `context-tracker.py` | コンテキストウィンドウ使用量追跡 | PostToolUse | コンテキスト監視 | +| `context-tracker-tiktoken.py` | トークンベースのコンテキスト追跡 | PostToolUse | 精密なトークン計測 | +| `README.md` | ドキュメント | - | セットアップと使用ガイド | + +**インストール先**：`~/.claude/settings.json` で設定 + +**使い方**：設定で構成し、自動実行される + +**フックの種類**（5 系統、28 イベント）： +- ツール系フック：PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest +- セッション系フック：SessionStart、SessionEnd、Stop、StopFailure、SubagentStart、SubagentStop +- タスク系フック：UserPromptSubmit、TaskCompleted、TaskCreated、TeammateIdle +- ライフサイクル系フック：ConfigChange、CwdChanged、FileChanged、PreCompact、PostCompact、WorktreeCreate、WorktreeRemove、Notification、InstructionsLoaded、Elicitation、ElicitationResult + +--- + +## 07. プラグイン（完全プラグイン 3 個、40 ファイル） + +機能のバンドル集。 + +### PR レビュープラグイン（10 ファイル） +``` +pr-review/ +├── .claude-plugin/ +│ └── plugin.json # プラグインマニフェスト +├── commands/ +│ ├── review-pr.md # 包括的レビュー +│ ├── check-security.md # セキュリティチェック +│ └── check-tests.md # テストカバレッジチェック +├── agents/ +│ ├── security-reviewer.md # セキュリティ専門家 +│ ├── test-checker.md # テスト専門家 +│ └── performance-analyzer.md # パフォーマンス専門家 +├── mcp/ +│ └── github-config.json # GitHub 連携 +├── hooks/ +│ └── pre-review.js # レビュー前検証 +└── README.md # プラグインドキュメント +``` + +**機能**：セキュリティ分析、テストカバレッジ、パフォーマンス影響 + +**コマンド**：`/review-pr`、`/check-security`、`/check-tests` + +**インストール**：`/plugin install pr-review` + +--- + +### DevOps 自動化プラグイン（15 ファイル） +``` +devops-automation/ +├── .claude-plugin/ +│ └── plugin.json # プラグインマニフェスト +├── commands/ +│ ├── deploy.md # デプロイ +│ ├── rollback.md # ロールバック +│ ├── status.md # システムステータス +│ └── incident.md # インシデント対応 +├── agents/ +│ ├── deployment-specialist.md # デプロイ専門家 +│ ├── incident-commander.md # インシデント指揮 +│ └── alert-analyzer.md # アラート分析 +├── mcp/ +│ └── kubernetes-config.json # Kubernetes 連携 +├── hooks/ +│ ├── pre-deploy.js # デプロイ前チェック +│ └── post-deploy.js # デプロイ後タスク +├── scripts/ +│ ├── deploy.sh # デプロイ自動化 +│ ├── rollback.sh # ロールバック自動化 +│ └── health-check.sh # ヘルスチェック +└── README.md # プラグインドキュメント +``` + +**機能**：Kubernetes デプロイ、ロールバック、監視、インシデント対応 + +**コマンド**：`/deploy`、`/rollback`、`/status`、`/incident` + +**インストール**：`/plugin install devops-automation` + +--- + +### ドキュメントプラグイン（14 ファイル） +``` +documentation/ +├── .claude-plugin/ +│ └── plugin.json # プラグインマニフェスト +├── commands/ +│ ├── generate-api-docs.md # API ドキュメント生成 +│ ├── generate-readme.md # README 作成 +│ ├── sync-docs.md # ドキュメント同期 +│ └── validate-docs.md # ドキュメント検証 +├── agents/ +│ ├── api-documenter.md # API ドキュメント専門家 +│ ├── code-commentator.md # コードコメント専門家 +│ └── example-generator.md # 例の作成 +├── mcp/ +│ └── github-docs-config.json # GitHub 連携 +├── templates/ +│ ├── api-endpoint.md # API エンドポイントテンプレート +│ ├── function-docs.md # 関数ドキュメントテンプレート +│ └── adr-template.md # ADR テンプレート +└── README.md # プラグインドキュメント +``` + +**機能**：API ドキュメント、README 生成、ドキュメント同期、検証 + +**コマンド**：`/generate-api-docs`、`/generate-readme`、`/sync-docs`、`/validate-docs` + +**インストール**：`/plugin install documentation` + +**追加**：`README.md` — プラグイン概要と使用ガイド + +--- + +## 08. チェックポイントと巻き戻し（2 ファイル） + +会話状態を保存し、別アプローチを探索する。 + +| ファイル | 説明 | 内容 | +|------|-------------|---------| +| `README.md` | ドキュメント | 包括的なチェックポイントガイド | +| `checkpoint-examples.md` | 実用例 | DB マイグレーション、パフォーマンス最適化、UI 反復、デバッグ | +| | | | + +**主要概念**： +- **チェックポイント**：会話状態のスナップショット +- **巻き戻し**：以前のチェックポイントへ戻る +- **分岐点**：複数のアプローチを探索する + +**使い方**： +``` +# チェックポイントはユーザープロンプトのたびに自動作成される +# 巻き戻しは Esc を 2 回押すか、次を実行: +/rewind +# 選択肢: コードと会話の復元、会話の復元、 +# コードの復元、ここから要約、やめる +``` + +**ユースケース**： +- 別実装を試す +- ミスからのリカバリ +- 安全な実験 +- 解決策の比較 +- A/B テスト + +--- + +## 09. 高度な機能（3 ファイル） + +複雑なワークフロー向けの高度な機能。 + +| ファイル | 説明 | 機能 | +|------|-------------|----------| +| `README.md` | 完全ガイド | 全高度機能のドキュメント | +| `config-examples.json` | 設定例 | ユースケース別の 10 種以上の設定 | +| `planning-mode-examples.md` | プランニング例 | REST API、DB マイグレーション、リファクタリング | +| スケジュールタスク | `/loop` および cron ツールによる反復タスク | 自動化された反復ワークフロー | +| Chrome 連携 | ヘッドレス Chromium によるブラウザ自動化 | Web テストとスクレイピング | +| リモートコントロール（拡張） | 接続方式、セキュリティ、比較表 | リモートセッション管理 | +| キーバインドカスタマイズ | カスタムキーバインド、コード対応、コンテキスト | パーソナライズされたショートカット | +| デスクトップアプリ（拡張） | コネクタ、launch.json、エンタープライズ機能 | デスクトップ統合 | +| | | | + +**カバーされる高度機能**： + +### プランニングモード +- 詳細な実装計画の作成 +- 時間見積もりとリスク評価 +- 体系的なタスク分解 + +### 拡張思考 +- 複雑な問題に対する深い推論 +- アーキテクチャ意思決定の分析 +- トレードオフの評価 + +### バックグラウンドタスク +- ブロックなしの長時間処理 +- 並列開発ワークフロー +- タスク管理と監視 + +### 権限モード +- **default**：危険な操作で承認を求める +- **acceptEdits**：ファイル編集を自動承認、それ以外は確認 +- **plan**：読み取り専用分析、変更なし +- **auto**：安全な操作を自動承認、危険なものは確認 +- **dontAsk**：危険なもの以外すべて承認 +- **bypassPermissions**：すべて承認（`--dangerously-skip-permissions` が必要） + +### ヘッドレスモード（`claude -p`） +- CI/CD 統合 +- 自動化されたタスク実行 +- バッチ処理 + +### セッション管理 +- 複数の作業セッション +- セッション切替と保存 +- セッション永続化 + +### インタラクティブ機能 +- キーボードショートカット +- コマンド履歴 +- タブ補完 +- 複数行入力 + +### 設定 +- 包括的な設定管理 +- 環境別設定 +- プロジェクト別カスタマイズ + +### スケジュールタスク +- `/loop` コマンドによる反復タスク +- cron ツール：CronCreate、CronList、CronDelete +- 自動化された反復ワークフロー + +### Chrome 連携 +- ヘッドレス Chromium によるブラウザ自動化 +- Web テストおよびスクレイピング能力 +- ページ操作とデータ抽出 + +### リモートコントロール（拡張） +- 接続方式とプロトコル +- セキュリティ上の留意事項とベストプラクティス +- リモートアクセスオプションの比較表 + +### キーバインドカスタマイズ +- カスタムキーバインド設定 +- 複数キーショートカットのコード対応 +- コンテキストに応じたキーバインドの有効化 + +### デスクトップアプリ（拡張） +- IDE 統合のためのコネクタ +- launch.json 設定 +- エンタープライズ機能とデプロイ + +--- + +## 10. CLI 利用（1 ファイル） + +コマンドラインインターフェースの利用パターンとリファレンス。 + +| ファイル | 説明 | 内容 | +|------|-------------|---------| +| `README.md` | CLI ドキュメント | フラグ、オプション、利用パターン | + +**主な CLI 機能**： +- `claude` — 対話セッションを開始 +- `claude -p "prompt"` — ヘッドレス / 非対話モード +- `claude web` — Web セッションを起動 +- `claude --model` — モデル選択（Sonnet 4.6、Opus 4.7、Haiku 4.5） +- `claude --permission-mode` — 権限モードの設定 +- `claude --remote` — WebSocket 経由のリモートコントロール有効化 + +--- + +## ドキュメントファイル（13 ファイル） + +| ファイル | 場所 | 説明 | +|------|----------|-------------| +| `README.md` | `/` | メイン例題概要 | +| `INDEX.md` | `/` | この完全索引 | +| `QUICK_REFERENCE.md` | `/` | クイックリファレンスカード | +| `README.md` | `/01-slash-commands/` | スラッシュコマンドガイド | +| `README.md` | `/02-memory/` | メモリガイド | +| `README.md` | `/03-skills/` | スキルガイド | +| `README.md` | `/04-subagents/` | サブエージェントガイド | +| `README.md` | `/05-mcp/` | MCP ガイド | +| `README.md` | `/06-hooks/` | フックガイド | +| `README.md` | `/07-plugins/` | プラグインガイド | +| `README.md` | `/08-checkpoints/` | チェックポイントガイド | +| `README.md` | `/09-advanced-features/` | 高度な機能ガイド | +| `README.md` | `/10-cli/` | CLI ガイド | + +--- + +## 完全ファイルツリー + +``` +claude-howto/ +├── README.md # メイン概要 +├── INDEX.md # このファイル +├── QUICK_REFERENCE.md # クイックリファレンスカード +├── claude_concepts_guide.md # オリジナルガイド +│ +├── 01-slash-commands/ # スラッシュコマンド +│ ├── optimize.md +│ ├── pr.md +│ ├── generate-api-docs.md +│ ├── commit.md +│ ├── setup-ci-cd.md +│ ├── push-all.md +│ ├── unit-test-expand.md +│ ├── doc-refactor.md +│ ├── pr-slash-command.png +│ └── README.md +│ +├── 02-memory/ # メモリ +│ ├── project-CLAUDE.md +│ ├── directory-api-CLAUDE.md +│ ├── personal-CLAUDE.md +│ ├── memory-saved.png +│ ├── memory-ask-claude.png +│ └── README.md +│ +├── 03-skills/ # スキル +│ ├── code-review/ +│ │ ├── SKILL.md +│ │ ├── scripts/ +│ │ │ ├── analyze-metrics.py +│ │ │ └── compare-complexity.py +│ │ └── templates/ +│ │ ├── review-checklist.md +│ │ └── finding-template.md +│ ├── brand-voice/ +│ │ ├── SKILL.md +│ │ ├── templates/ +│ │ │ ├── email-template.txt +│ │ │ └── social-post-template.txt +│ │ └── tone-examples.md +│ ├── doc-generator/ +│ │ ├── SKILL.md +│ │ └── generate-docs.py +│ ├── refactor/ +│ │ ├── SKILL.md +│ │ ├── scripts/ +│ │ │ ├── analyze-complexity.py +│ │ │ └── detect-smells.py +│ │ ├── references/ +│ │ │ ├── code-smells.md +│ │ │ └── refactoring-catalog.md +│ │ └── templates/ +│ │ └── refactoring-plan.md +│ ├── claude-md/ +│ │ └── SKILL.md +│ ├── blog-draft/ +│ │ ├── SKILL.md +│ │ └── templates/ +│ │ ├── draft-template.md +│ │ └── outline-template.md +│ └── README.md +│ +├── 04-subagents/ # サブエージェント +│ ├── code-reviewer.md +│ ├── test-engineer.md +│ ├── documentation-writer.md +│ ├── secure-reviewer.md +│ ├── implementation-agent.md +│ ├── debugger.md +│ ├── data-scientist.md +│ ├── clean-code-reviewer.md +│ └── README.md +│ +├── 05-mcp/ # MCP プロトコル +│ ├── github-mcp.json +│ ├── database-mcp.json +│ ├── filesystem-mcp.json +│ ├── multi-mcp.json +│ └── README.md +│ +├── 06-hooks/ # フック +│ ├── format-code.sh +│ ├── pre-commit.sh +│ ├── security-scan.sh +│ ├── log-bash.sh +│ ├── validate-prompt.sh +│ ├── notify-team.sh +│ ├── context-tracker.py +│ ├── context-tracker-tiktoken.py +│ └── README.md +│ +├── 07-plugins/ # プラグイン +│ ├── pr-review/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── review-pr.md +│ │ │ ├── check-security.md +│ │ │ └── check-tests.md +│ │ ├── agents/ +│ │ │ ├── security-reviewer.md +│ │ │ ├── test-checker.md +│ │ │ └── performance-analyzer.md +│ │ ├── mcp/ +│ │ │ └── github-config.json +│ │ ├── hooks/ +│ │ │ └── pre-review.js +│ │ └── README.md +│ ├── devops-automation/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── deploy.md +│ │ │ ├── rollback.md +│ │ │ ├── status.md +│ │ │ └── incident.md +│ │ ├── agents/ +│ │ │ ├── deployment-specialist.md +│ │ │ ├── incident-commander.md +│ │ │ └── alert-analyzer.md +│ │ ├── mcp/ +│ │ │ └── kubernetes-config.json +│ │ ├── hooks/ +│ │ │ ├── pre-deploy.js +│ │ │ └── post-deploy.js +│ │ ├── scripts/ +│ │ │ ├── deploy.sh +│ │ │ ├── rollback.sh +│ │ │ └── health-check.sh +│ │ └── README.md +│ ├── documentation/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── generate-api-docs.md +│ │ │ ├── generate-readme.md +│ │ │ ├── sync-docs.md +│ │ │ └── validate-docs.md +│ │ ├── agents/ +│ │ │ ├── api-documenter.md +│ │ │ ├── code-commentator.md +│ │ │ └── example-generator.md +│ │ ├── mcp/ +│ │ │ └── github-docs-config.json +│ │ ├── templates/ +│ │ │ ├── api-endpoint.md +│ │ │ ├── function-docs.md +│ │ │ └── adr-template.md +│ │ └── README.md +│ └── README.md +│ +├── 08-checkpoints/ # チェックポイント +│ ├── checkpoint-examples.md +│ └── README.md +│ +├── 09-advanced-features/ # 高度な機能 +│ ├── config-examples.json +│ ├── planning-mode-examples.md +│ └── README.md +│ +└── 10-cli/ # CLI 利用 + └── README.md +``` + +--- + +## ユースケース別クイックスタート + +### コード品質とレビュー +```bash +# スラッシュコマンドをインストール +cp 01-slash-commands/optimize.md .claude/commands/ + +# サブエージェントをインストール +cp 04-subagents/code-reviewer.md .claude/agents/ + +# スキルをインストール +cp -r 03-skills/code-review ~/.claude/skills/ + +# あるいは完全プラグインをインストール +/plugin install pr-review +``` + +### DevOps とデプロイ +```bash +# プラグインをインストール (すべて含む) +/plugin install devops-automation +``` + +### ドキュメント +```bash +# スラッシュコマンドをインストール +cp 01-slash-commands/generate-api-docs.md .claude/commands/ + +# サブエージェントをインストール +cp 04-subagents/documentation-writer.md .claude/agents/ + +# スキルをインストール +cp -r 03-skills/doc-generator ~/.claude/skills/ + +# あるいは完全プラグインをインストール +/plugin install documentation +``` + +### チーム標準 +```bash +# プロジェクトメモリをセットアップ +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# チームの標準に合わせて編集 +``` + +### 外部統合 +```bash +# 環境変数を設定 +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# MCP 設定をインストール (プロジェクトスコープ) +cp 05-mcp/multi-mcp.json .mcp.json +``` + +### 自動化と検証 +```bash +# フックをインストール +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# 設定でフックを構成 (~/.claude/settings.json) +# 06-hooks/README.md を参照 +``` + +### 安全な実験 +```bash +# チェックポイントはユーザープロンプトのたびに自動作成される +# 巻き戻し: Esc+Esc を押すか /rewind +# 巻き戻しメニューから何を復元するか選択 + +# 例は 08-checkpoints/README.md を参照 +``` + +### 高度なワークフロー +```bash +# 高度な機能を設定 +# 09-advanced-features/config-examples.json を参照 + +# プランニングモードを使う +/plan Implement feature X + +# 権限モードを使う +claude --permission-mode plan # コードレビュー (読み取り専用) +claude --permission-mode acceptEdits # 編集を自動承認 +claude --permission-mode auto # 安全な操作を自動承認 + +# CI/CD のためのヘッドレスモードで実行 +claude -p "Run tests and report results" + +# バックグラウンドタスクを実行 +Run tests in background + +# 完全ガイドは 09-advanced-features/README.md を参照 +``` + +--- + +## 機能カバレッジマトリクス + +| カテゴリ | コマンド | エージェント | MCP | フック | スクリプト | テンプレート | ドキュメント | 画像 | 合計 | +|----------|----------|--------|-----|-------|---------|-----------|------|--------|-------| +| **01 スラッシュコマンド** | 8 | - | - | - | - | - | 1 | 1 | **10** | +| **02 メモリ** | - | - | - | - | - | 3 | 1 | 2 | **6** | +| **03 スキル** | - | - | - | - | 5 | 9 | 1 | - | **28** | +| **04 サブエージェント** | - | 8 | - | - | - | - | 1 | - | **9** | +| **05 MCP** | - | - | 4 | - | - | - | 1 | - | **5** | +| **06 フック** | - | - | - | 8 | - | - | 1 | - | **9** | +| **07 プラグイン** | 11 | 9 | 3 | 3 | 3 | 3 | 4 | - | **40** | +| **08 チェックポイント** | - | - | - | - | - | - | 1 | 1 | **2** | +| **09 高度な機能** | - | - | - | - | - | - | 1 | 2 | **3** | +| **10 CLI** | - | - | - | - | - | - | 1 | - | **1** | + +--- + +## 学習パス + +### 初級（第 1 週） +1. ✅ `README.md` を読む +2. ✅ スラッシュコマンドを 1〜2 個インストール +3. ✅ プロジェクトメモリファイルを作成 +4. ✅ 基本コマンドを試す + +### 中級（第 2〜3 週） +1. ✅ GitHub MCP をセットアップ +2. ✅ サブエージェントをインストール +3. ✅ タスク委譲を試す +4. ✅ スキルをインストール + +### 上級（第 4 週〜） +1. ✅ 完全プラグインをインストール +2. ✅ カスタムスラッシュコマンドを作成 +3. ✅ カスタムサブエージェントを作成 +4. ✅ カスタムスキルを作成 +5. ✅ 自分のプラグインを構築 + +### エキスパート（第 5 週〜） +1. ✅ 自動化のためのフックをセットアップ +2. ✅ 実験のためチェックポイントを使う +3. ✅ プランニングモードを設定 +4. ✅ 権限モードを効果的に使う +5. ✅ CI/CD のためヘッドレスモードをセットアップ +6. ✅ セッション管理を習得 + +--- + +## キーワード検索 + +### パフォーマンス +- `01-slash-commands/optimize.md` — パフォーマンス分析 +- `04-subagents/code-reviewer.md` — パフォーマンスレビュー +- `03-skills/code-review/` — パフォーマンスメトリクス +- `07-plugins/pr-review/agents/performance-analyzer.md` — パフォーマンス専門家 + +### セキュリティ +- `04-subagents/secure-reviewer.md` — セキュリティレビュー +- `03-skills/code-review/` — セキュリティ分析 +- `07-plugins/pr-review/` — セキュリティチェック + +### テスト +- `04-subagents/test-engineer.md` — テストエンジニア +- `07-plugins/pr-review/commands/check-tests.md` — テストカバレッジ + +### ドキュメント +- `01-slash-commands/generate-api-docs.md` — API ドキュメントコマンド +- `04-subagents/documentation-writer.md` — ドキュメント作成エージェント +- `03-skills/doc-generator/` — ドキュメント生成スキル +- `07-plugins/documentation/` — 完全ドキュメントプラグイン + +### デプロイ +- `07-plugins/devops-automation/` — 完全 DevOps ソリューション + +### 自動化 +- `06-hooks/` — イベント駆動自動化 +- `06-hooks/pre-commit.sh` — コミット前自動化 +- `06-hooks/format-code.sh` — 自動整形 +- `09-advanced-features/` — CI/CD のためのヘッドレスモード + +### 検証 +- `06-hooks/security-scan.sh` — セキュリティ検証 +- `06-hooks/validate-prompt.sh` — プロンプト検証 + +### 実験 +- `08-checkpoints/` — 巻き戻しによる安全な実験 +- `08-checkpoints/checkpoint-examples.md` — 実用例 + +### プランニング +- `09-advanced-features/planning-mode-examples.md` — プランニングモード例 +- `09-advanced-features/README.md` — 拡張思考 + +### 設定 +- `09-advanced-features/config-examples.json` — 設定例 + +--- + +## 注意事項 + +- すべての例はそのまま利用できる +- 自分のニーズに合わせて改造する +- 例は Claude Code のベストプラクティスに従う +- 各カテゴリには詳細手順つきの独自 README がある +- スクリプトには適切なエラー処理が含まれる +- テンプレートはカスタマイズ可能 + +--- + +## コントリビュート + +例題を追加したい場合は次の構造に従う： +1. 適切なサブディレクトリを作成 +2. 利用方法つき README.md を含める +3. 命名規則に従う +4. 入念にテストする +5. この索引を更新する + +--- + +**最終更新**：2026 年 4 月 24 日 +**Claude Code バージョン**：2.1.119 +**情報源**： +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/commands +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**互換モデル**：Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 +**例題総数**：100 ファイル超 +**カテゴリ**：10 機能 +**フック**：自動化スクリプト 8 個 +**設定例**：10 シナリオ以上 +**すぐ使える**：すべての例 diff --git a/ja/LEARNING-ROADMAP.md b/ja/LEARNING-ROADMAP.md new file mode 100644 index 0000000..f8614d6 --- /dev/null +++ b/ja/LEARNING-ROADMAP.md @@ -0,0 +1,757 @@ + + + + + + + Claude How To + + +# 📚 Claude Code 学習ロードマップ + +**Claude Code に初めて触れる？** 本ガイドは自分のペースで Claude Code の機能を習得する助けになる。完全な初心者でも経験豊富な開発者でも、まず以下の自己評価クイズで自分に合うパスを見つけてほしい。 + +--- + +## 🧭 自分のレベルを見つける + +全員が同じ地点から始めるわけではない。手早い自己評価で適切な入口を見つける。 + +**正直に答えてほしい：** + +- [ ] Claude Code を起動して対話できる（`claude`） +- [ ] CLAUDE.md ファイルを作成または編集したことがある +- [ ] 組み込みのスラッシュコマンドを 3 個以上使ったことがある（例：/help、/compact、/model） +- [ ] カスタムスラッシュコマンドまたはスキル（SKILL.md）を作成したことがある +- [ ] MCP サーバを設定したことがある（例：GitHub、データベース） +- [ ] `~/.claude/settings.json` でフックを設定したことがある +- [ ] カスタムサブエージェントを作成または使用したことがある（`.claude/agents/`） +- [ ] スクリプトや CI/CD で印字モード（`claude -p`）を使ったことがある + +**あなたのレベル：** + +| チェック数 | レベル | 開始地点 | 完了までの時間 | +|--------|-------|----------|------------------| +| 0〜2 | **レベル 1：初級** — はじめの一歩 | [マイルストーン 1A](#マイルストーン-1a最初のコマンドとメモリ) | 約 3 時間 | +| 3〜5 | **レベル 2：中級** — ワークフロー構築 | [マイルストーン 2A](#マイルストーン-2a自動化スキル--フック) | 約 5 時間 | +| 6〜8 | **レベル 3：上級** — パワーユーザーとチームリード | [マイルストーン 3A](#マイルストーン-3a高度な機能) | 約 5 時間 | + +> **ヒント**：迷ったら 1 段階下から始めるのがよい。慣れた内容を素早く復習する方が、基礎を取りこぼすよりはるかに有益である。 + +> **インタラクティブ版**：Claude Code 内で `/self-assessment` を実行すると、10 機能領域すべての習熟度を測るガイド付きクイズが受けられ、個別の学習パスが生成される。 + +--- + +## 🎯 学習思想 + +本リポジトリのフォルダは、3 つの原則に基づいた **推奨学習順** で番号付けされている。 + +1. **依存関係** — 基礎的な概念を先に置く +2. **複雑度** — 簡単な機能を高度な機能の前に置く +3. **使用頻度** — 最頻出の機能を早い段階で教える + +このアプローチによって、堅固な基礎を築きつつ、即座に生産性を得られる。 + +--- + +## 🗺️ あなたの学習パス + +```mermaid +graph TD + Q["🧭 Self-Assessment Quiz
Find Your Level"] --> L1 + Q --> L2 + Q --> L3 + + subgraph L1["🟢 Level 1: Beginner — Getting Started"] + direction LR + A["1A: First Commands & Memory
Slash Commands + Memory"] --> B["1B: Safe Exploration
Checkpoints + CLI Basics"] + end + + subgraph L2["🔵 Level 2: Intermediate — Building Workflows"] + direction LR + C["2A: Automation
Skills + Hooks"] --> D["2B: Integration
MCP + Subagents"] + end + + subgraph L3["🔴 Level 3: Advanced — Power User"] + direction LR + E["3A: Advanced Features
Planning + Permissions"] --> F["3B: Team & Distribution
Plugins + CLI Mastery"] + end + + L1 --> L2 + L2 --> L3 + + style Q fill:#6A1B9A,color:#fff,stroke:#9C27B0,stroke-width:2px + style A fill:#2E7D32,color:#fff + style B fill:#2E7D32,color:#fff + style C fill:#1565C0,color:#fff + style D fill:#F57C00,color:#fff + style E fill:#C62828,color:#fff + style F fill:#B71C1C,color:#fff +``` + +**カラー凡例：** +- 💜 紫：自己評価クイズ +- 🟢 緑：レベル 1 — 初級パス +- 🔵 青 / 🟡 黄：レベル 2 — 中級パス +- 🔴 赤：レベル 3 — 上級パス + +--- + +## 📊 完全ロードマップ表 + +| ステップ | 機能 | 複雑度 | 時間 | レベル | 依存 | 学ぶ理由 | 主な利点 | +|------|---------|-----------|------|-------|--------------|----------------|--------------| +| **1** | [スラッシュコマンド](01-slash-commands/) | ⭐ 初級 | 30 分 | レベル 1 | なし | すぐ得られる生産性向上（組み込み 55 個 + バンドル 5 スキル） | 即時自動化、チーム標準化 | +| **2** | [メモリ](02-memory/) | ⭐⭐ 初級+ | 45 分 | レベル 1 | なし | 全機能の基礎 | 永続コンテキスト、設定保持 | +| **3** | [チェックポイント](08-checkpoints/) | ⭐⭐ 中級 | 45 分 | レベル 1 | セッション管理 | 安全な探索 | 実験、復旧 | +| **4** | [CLI 基礎](10-cli/) | ⭐⭐ 初級+ | 30 分 | レベル 1 | なし | コア CLI の使い方 | 対話モード・印字モード | +| **5** | [スキル](03-skills/) | ⭐⭐ 中級 | 1 時間 | レベル 2 | スラッシュコマンド | 自動的な専門性 | 再利用、一貫性 | +| **6** | [フック](06-hooks/) | ⭐⭐ 中級 | 1 時間 | レベル 2 | ツール、コマンド | ワークフロー自動化（28 イベント、5 種類） | 検証、品質ゲート | +| **7** | [MCP](05-mcp/) | ⭐⭐⭐ 中級+ | 1 時間 | レベル 2 | 設定 | ライブデータアクセス | リアルタイム連携、API | +| **8** | [サブエージェント](04-subagents/) | ⭐⭐⭐ 中級+ | 1.5 時間 | レベル 2 | メモリ、コマンド | 複雑タスクの処理（Bash 含む組み込み 6 個） | 委譲、専門性 | +| **9** | [高度な機能](09-advanced-features/) | ⭐⭐⭐⭐⭐ 上級 | 2〜3 時間 | レベル 3 | これまでの全機能 | パワーユーザー向けツール | プランニング、Auto Mode、チャンネル、音声入力、権限 | +| **10** | [プラグイン](07-plugins/) | ⭐⭐⭐⭐ 上級 | 2 時間 | レベル 3 | これまでの全機能 | 完全なソリューション | チームオンボーディング、配布 | +| **11** | [CLI マスタリー](10-cli/) | ⭐⭐⭐ 上級 | 1 時間 | レベル 3 | 推奨：これまでの全機能 | コマンドライン利用の習熟 | スクリプト、CI/CD、自動化 | + +**学習総時間**：約 11〜13 時間（自分のレベルにジャンプすれば短縮可能） + +--- + +## 🟢 レベル 1：初級 — はじめの一歩 + +**対象**：クイズで 0〜2 個チェックの利用者 +**時間**：約 3 時間 +**焦点**：即時の生産性、基礎の理解 +**到達点**：日常利用に慣れたユーザー、レベル 2 への準備完了 + +### マイルストーン 1A：最初のコマンドとメモリ + +**トピック**：スラッシュコマンド + メモリ +**時間**：1〜2 時間 +**複雑度**：⭐ 初級 +**目標**：カスタムコマンドと永続コンテキストによる即時の生産性向上 + +#### 達成事項 +✅ 反復作業向けにカスタムスラッシュコマンドを作成 +✅ チーム標準のためのプロジェクトメモリをセットアップ +✅ 個人の好みを設定 +✅ Claude が自動的にコンテキストを読み込む仕組みを理解 + +#### ハンズオン演習 + +```bash +# 演習 1: 最初のスラッシュコマンドをインストール +mkdir -p .claude/commands +cp 01-slash-commands/optimize.md .claude/commands/ + +# 演習 2: プロジェクトメモリを作成 +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# 演習 3: 試す +# Claude Code で次を入力: /optimize +``` + +#### 達成基準 +- [ ] `/optimize` コマンドを正常に実行できる +- [ ] CLAUDE.md からプロジェクト規約を Claude が記憶している +- [ ] スラッシュコマンドとメモリの使い分けを理解している + +#### 次のステップ +慣れたら以下を読む： +- [01-slash-commands/README.md](01-slash-commands/README.md) +- [02-memory/README.md](02-memory/README.md) + +> **理解度チェック**：Claude Code 内で `/lesson-quiz slash-commands` または `/lesson-quiz memory` を実行して学習内容をテストする。 + +--- + +### マイルストーン 1B：安全な探索 + +**トピック**：チェックポイント + CLI 基礎 +**時間**：1 時間 +**複雑度**：⭐⭐ 初級+ +**目標**：安全に実験する方法とコア CLI コマンドの使い方を学ぶ + +#### 達成事項 +✅ 安全な実験のためにチェックポイントを作成・復元 +✅ 対話モードと印字モードの違いを理解 +✅ 基本的な CLI フラグとオプションを使う +✅ パイプ経由でファイルを処理 + +#### ハンズオン演習 + +```bash +# 演習 1: チェックポイントワークフローを試す +# Claude Code で: +# 試験的な変更をいくつか加え、Esc+Esc を押すか /rewind を実行 +# 実験前のチェックポイントを選択 +# "Restore code and conversation" を選んで戻る + +# 演習 2: 対話モード対印字モード +claude "explain this project" # 対話モード +claude -p "explain this function" # 印字モード (非対話) + +# 演習 3: パイプでファイル内容を処理 +cat error.log | claude -p "explain this error" +``` + +#### 達成基準 +- [ ] チェックポイントを作成し、それに戻った +- [ ] 対話モードと印字モードの両方を使った +- [ ] ファイルをパイプで Claude に渡して解析した +- [ ] 安全な実験のためチェックポイントをいつ使うかを理解した + +#### 次のステップ +- 読む：[08-checkpoints/README.md](08-checkpoints/README.md) +- 読む：[10-cli/README.md](10-cli/README.md) +- **レベル 2 へ進む準備完了！** [マイルストーン 2A](#マイルストーン-2a自動化スキル--フック) へ。 + +> **理解度チェック**：`/lesson-quiz checkpoints` または `/lesson-quiz cli` を実行してレベル 2 への準備が整っているか確認する。 + +--- + +## 🔵 レベル 2：中級 — ワークフロー構築 + +**対象**：クイズで 3〜5 個チェックの利用者 +**時間**：約 5 時間 +**焦点**：自動化、統合、タスク委譲 +**到達点**：自動化ワークフロー、外部統合、レベル 3 への準備完了 + +### 前提条件チェック + +レベル 2 を始める前に、以下のレベル 1 の概念に慣れていることを確認する： + +- [ ] スラッシュコマンドを作成・利用できる（[01-slash-commands/](01-slash-commands/)） +- [ ] CLAUDE.md でプロジェクトメモリを設定済み（[02-memory/](02-memory/)） +- [ ] チェックポイントの作成と復元方法を知っている（[08-checkpoints/](08-checkpoints/)） +- [ ] コマンドラインから `claude` および `claude -p` を使える（[10-cli/](10-cli/)） + +> **不足あり？** 続行前に上記のチュートリアルを復習する。 + +--- + +### マイルストーン 2A：自動化（スキル + フック） + +**トピック**：スキル + フック +**時間**：2〜3 時間 +**複雑度**：⭐⭐ 中級 +**目標**：日常ワークフローと品質チェックの自動化 + +#### 達成事項 +✅ YAML フロントマター（`effort` と `shell` フィールドを含む）で専門機能を自動起動 +✅ 28 個のフックイベントにまたがるイベント駆動自動化を構築 +✅ 5 種類のフック（command、http、mcp_tool、prompt、agent）を活用 +✅ コード品質基準を強制 +✅ ワークフロー向けカスタムフックを作成 + +#### ハンズオン演習 + +```bash +# 演習 1: スキルをインストール +cp -r 03-skills/code-review ~/.claude/skills/ + +# 演習 2: フックをセットアップ +mkdir -p ~/.claude/hooks +cp 06-hooks/pre-tool-check.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/pre-tool-check.sh + +# 演習 3: 設定でフックを構成 +# ~/.claude/settings.json に追加: +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.claude/hooks/pre-tool-check.sh" + } + ] + } + ] + } +} +``` + +#### 達成基準 +- [ ] 関連場面で code review スキルが自動起動される +- [ ] PreToolUse フックがツール実行前に走る +- [ ] スキルの自動起動とフックのイベントトリガーの違いを理解している + +#### 次のステップ +- 自分のカスタムスキルを作成 +- ワークフロー向けに追加フックを設定 +- 読む：[03-skills/README.md](03-skills/README.md) +- 読む：[06-hooks/README.md](06-hooks/README.md) + +> **理解度チェック**：次に進む前に `/lesson-quiz skills` または `/lesson-quiz hooks` で知識を試す。 + +--- + +### マイルストーン 2B：統合（MCP + サブエージェント） + +**トピック**：MCP + サブエージェント +**時間**：2〜3 時間 +**複雑度**：⭐⭐⭐ 中級+ +**目標**：外部サービスを統合し、複雑タスクを委譲する + +#### 達成事項 +✅ GitHub、データベースなどからライブデータにアクセス +✅ 専門 AI エージェントに作業を委譲 +✅ MCP とサブエージェントの使い分けを理解 +✅ 統合ワークフローを構築 + +#### ハンズオン演習 + +```bash +# 演習 1: GitHub MCP をセットアップ +export GITHUB_TOKEN="your_github_token" +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# 演習 2: MCP 統合をテスト +# Claude Code で: /mcp__github__list_prs + +# 演習 3: サブエージェントをインストール +mkdir -p .claude/agents +cp 04-subagents/*.md .claude/agents/ +``` + +#### 統合演習 +以下の完全ワークフローを試す： +1. MCP で GitHub PR を取得 +2. Claude が code-reviewer サブエージェントにレビューを委譲 +3. フックでテストを自動実行 + +#### 達成基準 +- [ ] MCP 経由で GitHub データを正常に取得した +- [ ] Claude が複雑タスクをサブエージェントに委譲する +- [ ] MCP とサブエージェントの違いを理解している +- [ ] ワークフローで MCP + サブエージェント + フックを組み合わせた + +#### 次のステップ +- 追加の MCP サーバ（データベース、Slack など）を設定 +- 自分のドメイン向けカスタムサブエージェントを作成 +- 読む：[05-mcp/README.md](05-mcp/README.md) +- 読む：[04-subagents/README.md](04-subagents/README.md) +- **レベル 3 へ進む準備完了！** [マイルストーン 3A](#マイルストーン-3a高度な機能) へ。 + +> **理解度チェック**：`/lesson-quiz mcp` または `/lesson-quiz subagents` でレベル 3 への準備を確認する。 + +--- + +## 🔴 レベル 3：上級 — パワーユーザーとチームリード + +**対象**：クイズで 6〜8 個チェックの利用者 +**時間**：約 5 時間 +**焦点**：チームツール、CI/CD、エンタープライズ機能、プラグイン開発 +**到達点**：パワーユーザー、チームワークフローと CI/CD のセットアップが可能 + +### 前提条件チェック + +レベル 3 を始める前に、以下のレベル 2 の概念に慣れていることを確認する： + +- [ ] 自動起動つきのスキルを作成・利用できる（[03-skills/](03-skills/)） +- [ ] イベント駆動自動化のためのフックを設定済み（[06-hooks/](06-hooks/)） +- [ ] 外部データ向けに MCP サーバを設定できる（[05-mcp/](05-mcp/)） +- [ ] タスク委譲のためのサブエージェントの使い方を知っている（[04-subagents/](04-subagents/)） + +> **不足あり？** 続行前に上記のチュートリアルを復習する。 + +--- + +### マイルストーン 3A：高度な機能 + +**トピック**：高度な機能（プランニング、権限、拡張思考、Auto Mode、チャンネル、音声入力、リモート / デスクトップ / Web） +**時間**：2〜3 時間 +**複雑度**：⭐⭐⭐⭐⭐ 上級 +**目標**：高度なワークフローとパワーユーザー向けツールを習得する + +#### 達成事項 +✅ 複雑な機能向けのプランニングモード +✅ 6 モード（default、acceptEdits、plan、auto、dontAsk、bypassPermissions）の詳細な権限制御 +✅ Alt+T / Option+T による拡張思考の切り替え +✅ バックグラウンドタスク管理 +✅ 学習済み設定のための Auto Memory +✅ バックグラウンド安全性分類器付きの Auto Mode +✅ 構造化マルチセッションワークフロー向けチャンネル +✅ ハンズフリー操作のための音声入力 +✅ リモート操作、デスクトップアプリ、Web セッション +✅ マルチエージェント協調のための Agent Teams + +#### ハンズオン演習 + +```bash +# 演習 1: プランニングモードを使う +/plan Implement user authentication system + +# 演習 2: 権限モードを試す (default, acceptEdits, plan, auto, dontAsk, bypassPermissions の 6 種) +claude --permission-mode plan "analyze this codebase" +claude --permission-mode acceptEdits "refactor the auth module" +claude --permission-mode auto "implement the feature" + +# 演習 3: 拡張思考を有効化 +# セッション中に Alt+T (macOS は Option+T) を押して切り替え + +# 演習 4: 高度なチェックポイントワークフロー +# 1. "Clean state" チェックポイントを作成 +# 2. プランニングモードで機能を設計 +# 3. サブエージェントへの委譲で実装 +# 4. バックグラウンドでテスト実行 +# 5. テスト失敗ならチェックポイントへ巻き戻し +# 6. 別アプローチを試す + +# 演習 5: auto モード (バックグラウンド安全性分類器) を試す +claude --permission-mode auto "implement user settings page" + +# 演習 6: Agent Teams を有効化 +export CLAUDE_AGENT_TEAMS=1 +# Claude にこう依頼: "Implement feature X using a team approach" + +# 演習 7: スケジュールタスク +/loop 5m /check-status +# あるいは永続的なスケジュールタスクには CronCreate を使う + +# 演習 8: マルチセッションワークフローのチャンネル +# セッションをまたぐ作業をチャンネルで整理する + +# 演習 9: 音声入力 +# ハンズフリーで Claude Code とやり取りするため音声入力を使う +``` + +#### 達成基準 +- [ ] 複雑な機能でプランニングモードを使った +- [ ] 権限モードを設定した（plan、acceptEdits、auto、dontAsk） +- [ ] Alt+T / Option+T で拡張思考を切り替えた +- [ ] バックグラウンド安全性分類器付き auto モードを使った +- [ ] 長時間処理でバックグラウンドタスクを使った +- [ ] マルチセッションワークフローのためチャンネルを試した +- [ ] ハンズフリー入力のため音声入力を試した +- [ ] リモート操作、デスクトップアプリ、Web セッションを理解している +- [ ] 協調作業のため Agent Teams を有効化して使った +- [ ] 反復タスクや定期監視に `/loop` を使った + +#### 次のステップ +- 読む：[09-advanced-features/README.md](09-advanced-features/README.md) + +> **理解度チェック**：`/lesson-quiz advanced` でパワーユーザー機能の習熟度を試す。 + +--- + +### マイルストーン 3B：チームと配布（プラグイン + CLI マスタリー） + +**トピック**：プラグイン + CLI マスタリー + CI/CD +**時間**：2〜3 時間 +**複雑度**：⭐⭐⭐⭐ 上級 +**目標**：チームツールを構築し、プラグインを作成し、CI/CD 統合を習得する + +#### 達成事項 +✅ 完全バンドル済みプラグインのインストールと作成 +✅ スクリプトと自動化のための CLI マスタリー +✅ `claude -p` による CI/CD 統合のセットアップ +✅ 自動化パイプラインのための JSON 出力 +✅ セッション管理とバッチ処理 + +#### ハンズオン演習 + +```bash +# 演習 1: 完全プラグインをインストール +# Claude Code で: /plugin install pr-review + +# 演習 2: CI/CD のための印字モード +claude -p "Run all tests and generate report" + +# 演習 3: スクリプト用 JSON 出力 +claude -p --output-format json "list all functions" + +# 演習 4: セッション管理と再開 +claude -r "feature-auth" "continue implementation" + +# 演習 5: 制約つき CI/CD 統合 +claude -p --max-turns 3 --output-format json "review code" + +# 演習 6: バッチ処理 +for file in *.md; do + claude -p --output-format json "summarize this: $(cat $file)" > ${file%.md}.summary.json +done +``` + +#### CI/CD 統合演習 +シンプルな CI/CD スクリプトを作成する： +1. `claude -p` で変更ファイルをレビュー +2. 結果を JSON で出力 +3. `jq` で特定の問題を抽出 +4. GitHub Actions ワークフローに統合 + +#### 達成基準 +- [ ] プラグインをインストールして使った +- [ ] チーム向けにプラグインを作成または改造した +- [ ] CI/CD で印字モード（`claude -p`）を使った +- [ ] スクリプト向け JSON 出力を生成した +- [ ] 過去セッションを正常に再開した +- [ ] バッチ処理スクリプトを作成した +- [ ] Claude を CI/CD ワークフローに統合した + +#### CLI の実用ユースケース +- **コードレビュー自動化**：CI/CD パイプラインでコードレビューを実行 +- **ログ解析**：エラーログとシステム出力を解析 +- **ドキュメント生成**：ドキュメントをバッチ生成 +- **テスト分析**：テスト失敗の解析 +- **パフォーマンス分析**：パフォーマンス指標のレビュー +- **データ処理**：データファイルの変換と解析 + +#### 次のステップ +- 読む：[07-plugins/README.md](07-plugins/README.md) +- 読む：[10-cli/README.md](10-cli/README.md) +- チーム共通の CLI ショートカットとプラグインを作成 +- バッチ処理スクリプトをセットアップ + +> **理解度チェック**：`/lesson-quiz plugins` または `/lesson-quiz cli` で習熟を確認する。 + +--- + +## 🧪 知識を試す + +本リポジトリには、Claude Code 内でいつでも理解度を評価できる 2 つのインタラクティブスキルが含まれている。 + +| スキル | コマンド | 用途 | +|-------|---------|---------| +| **自己評価** | `/self-assessment` | 10 機能全体での総合的習熟度を評価。Quick（2 分）または Deep（5 分）モードを選び、個別スキルプロファイルと学習パスを得る。 | +| **レッスンクイズ** | `/lesson-quiz [lesson]` | 特定レッスンの理解度を 10 問で試す。レッスン前（事前テスト）、途中（進捗確認）、後（習熟確認）に利用する。 | + +**例：** +``` +/self-assessment # 総合レベルを判定 +/lesson-quiz hooks # レッスン 06: フックのクイズ +/lesson-quiz 03 # レッスン 03: スキルのクイズ +/lesson-quiz advanced-features # レッスン 09 のクイズ +``` + +--- + +## ⚡ クイックスタートパス + +### 15 分しかない場合 +**目標**：最初の成果を得る + +1. スラッシュコマンドを 1 つコピー：`cp 01-slash-commands/optimize.md .claude/commands/` +2. Claude Code で試す：`/optimize` +3. 読む：[01-slash-commands/README.md](01-slash-commands/README.md) + +**到達点**：動くスラッシュコマンドが 1 つあり、基礎を理解している + +--- + +### 1 時間ある場合 +**目標**：必須の生産性ツールをセットアップ + +1. **スラッシュコマンド**（15 分）：`/optimize` と `/pr` をコピーして試す +2. **プロジェクトメモリ**（15 分）：プロジェクト規約を含む CLAUDE.md を作成 +3. **スキルをインストール**（15 分）：code-review スキルを設定 +4. **組み合わせて試す**（15 分）：連携動作を確認 + +**到達点**：コマンド、メモリ、自動スキルによる基本的な生産性向上 + +--- + +### 週末ある場合 +**目標**：ほとんどの機能を使いこなせるようになる + +**土曜午前**（3 時間）： +- マイルストーン 1A：スラッシュコマンド + メモリ +- マイルストーン 1B：チェックポイント + CLI 基礎 + +**土曜午後**（3 時間）： +- マイルストーン 2A：スキル + フック +- マイルストーン 2B：MCP + サブエージェント + +**日曜**（4 時間）： +- マイルストーン 3A：高度な機能 +- マイルストーン 3B：プラグイン + CLI マスタリー + CI/CD +- チーム向けカスタムプラグインを構築 + +**到達点**：他者を訓練し、複雑なワークフローを自動化できる Claude Code パワーユーザー + +--- + +## 💡 学習のヒント + +### ✅ 推奨 + +- **まずクイズを受けて** スタート地点を見つける +- 各マイルストーンの **ハンズオン演習を完了する** +- **シンプルに始め**、徐々に複雑度を上げる +- 次に進む前に **各機能をテスト** する +- 自分のワークフローで何が効くか **メモを取る** +- 高度なトピックを学ぶ過程で過去の概念を **見直す** +- チェックポイントで **安全に実験する** +- チームと **知識を共有する** + +### ❌ 非推奨 + +- 上位レベルへ飛ぶときに **前提条件チェックを飛ばさない** +- **一度にすべてを学ぼうとしない** — 圧倒される +- 設定を理解せずに **コピペしない** — デバッグできなくなる +- **テストを忘れない** — 機能の動作を必ず検証する +- マイルストーンを **急いで通り抜けない** — 理解に時間をかける +- ドキュメントを **無視しない** — 各 README には貴重な詳細がある +- **孤立して作業しない** — チームと議論する + +--- + +## 🎓 学習スタイル + +### 視覚優位の学習者 +- 各 README の Mermaid 図を学習する +- コマンドの実行フローを観察する +- 自分でワークフロー図を描く +- 上記の視覚的学習パスを利用する + +### 実践優位の学習者 +- すべてのハンズオン演習を完了する +- バリエーションを試す +- 壊して直す（チェックポイントを使う！） +- 自分の例を作成する + +### 読書優位の学習者 +- 各 README を丁寧に読む +- コード例を学習する +- 比較表を見直す +- リソースに記載のブログ記事を読む + +### 社会的学習者 +- ペアプログラミングセッションを設定する +- チームメンバーに概念を教える +- Claude Code コミュニティの議論に参加する +- 自分のカスタム設定を共有する + +--- + +## 📈 進捗トラッキング + +レベル別の進捗をこのチェックリストで追える。`/self-assessment` をいつでも実行して最新のスキルプロファイルを得るか、各チュートリアル後に `/lesson-quiz [lesson]` で理解を確認する。 + +### 🟢 レベル 1：初級 +- [ ] [01-slash-commands](01-slash-commands/) を完了 +- [ ] [02-memory](02-memory/) を完了 +- [ ] 最初のカスタムスラッシュコマンドを作成 +- [ ] プロジェクトメモリをセットアップ +- [ ] **マイルストーン 1A 達成** +- [ ] [08-checkpoints](08-checkpoints/) を完了 +- [ ] [10-cli](10-cli/) 基礎を完了 +- [ ] チェックポイントを作成して戻った +- [ ] 対話モードと印字モードを使った +- [ ] **マイルストーン 1B 達成** + +### 🔵 レベル 2：中級 +- [ ] [03-skills](03-skills/) を完了 +- [ ] [06-hooks](06-hooks/) を完了 +- [ ] 最初のスキルをインストール +- [ ] PreToolUse フックをセットアップ +- [ ] **マイルストーン 2A 達成** +- [ ] [05-mcp](05-mcp/) を完了 +- [ ] [04-subagents](04-subagents/) を完了 +- [ ] GitHub MCP に接続 +- [ ] カスタムサブエージェントを作成 +- [ ] ワークフローで複数の統合を組み合わせた +- [ ] **マイルストーン 2B 達成** + +### 🔴 レベル 3：上級 +- [ ] [09-advanced-features](09-advanced-features/) を完了 +- [ ] プランニングモードを正常に使った +- [ ] 権限モードを設定（auto を含む 6 モード） +- [ ] 安全性分類器付き auto モードを使った +- [ ] 拡張思考の切り替えを使った +- [ ] チャンネルと音声入力を試した +- [ ] **マイルストーン 3A 達成** +- [ ] [07-plugins](07-plugins/) を完了 +- [ ] [10-cli](10-cli/) 上級利用を完了 +- [ ] CI/CD で印字モード（`claude -p`）をセットアップ +- [ ] 自動化のための JSON 出力を作成 +- [ ] CI/CD パイプラインに Claude を統合 +- [ ] チームプラグインを作成 +- [ ] **マイルストーン 3B 達成** + +--- + +## 🆘 よくある学習上の課題 + +### 課題 1：「概念が多すぎる」 +**解決策**：一度に 1 つのマイルストーンに集中する。前進する前にすべての演習を完了する。 + +### 課題 2：「どの機能をいつ使えばよいか分からない」 +**解決策**：メイン README の [ユースケース表](README.md#何が作れるか) を参照する。 + +### 課題 3：「設定が動かない」 +**解決策**：[トラブルシューティング](README.md#トラブルシューティング) セクションを確認し、ファイルの配置場所を検証する。 + +### 課題 4：「概念が重なって見える」 +**解決策**：違いを理解するため [機能比較](README.md#機能比較) 表を見直す。 + +### 課題 5：「全部覚えるのが大変」 +**解決策**：自分専用のチートシートを作る。チェックポイントで安全に実験する。 + +### 課題 6：「経験はあるがどこから始めるか分からない」 +**解決策**：上の [自己評価クイズ](#-自分のレベルを見つける) を受ける。自分のレベルへ飛び、前提条件チェックでギャップを特定する。 + +--- + +## 🎯 完了後は何をするか + +すべてのマイルストーンを完了したら： + +1. **チームドキュメントを作成** — チームの Claude Code セットアップを文書化 +2. **カスタムプラグインを構築** — チームのワークフローをパッケージ化 +3. **リモートコントロールを試す** — 外部ツールから Claude Code セッションをプログラムで制御 +4. **Web セッションを試す** — リモート開発のためブラウザベースインターフェースで Claude Code を使う +5. **デスクトップアプリを使う** — ネイティブデスクトップアプリで Claude Code 機能を利用 +6. **Auto Mode を使う** — バックグラウンド安全性分類器付きで Claude を自律的に動かす +7. **Auto Memory を活用** — Claude に好みを時間とともに自動学習させる +8. **Agent Teams をセットアップ** — 複雑で多面的なタスクで複数エージェントを協調させる +9. **チャンネルを使う** — 構造化マルチセッションワークフローで作業を整理 +10. **音声入力を試す** — ハンズフリー音声入力で Claude Code とやり取りする +11. **スケジュールタスクを使う** — `/loop` や cron ツールで反復チェックを自動化 +12. **例をコントリビュート** — コミュニティと共有する +13. **他者を指導する** — チームメンバーの学習を助ける +14. **ワークフローを最適化** — 利用状況に基づき継続的に改善する +15. **最新情報を追う** — Claude Code のリリースと新機能を追いかける + +--- + +## 📚 追加リソース + +### 公式ドキュメント +- [Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [Anthropic Documentation](https://docs.anthropic.com) +- [MCP Protocol Specification](https://modelcontextprotocol.io) + +### ブログ記事 +- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) + +### コミュニティ +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) +- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers) + +--- + +## 💬 フィードバックとサポート + +- **問題を見つけた？** リポジトリで issue を作成 +- **提案がある？** プルリクエストを送る +- **助けが必要？** ドキュメントを確認するか、コミュニティに尋ねる + +--- + +**最終更新**：2026 年 4 月 24 日 +**Claude Code バージョン**：2.1.119 +**情報源**： +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/hooks +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**互換モデル**：Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 +**メンテナンス**：Claude How-To Contributors +**ライセンス**：教育目的、自由に使用・改変可能 + +--- + +[← メイン README に戻る](README.md) diff --git a/ja/QUICK_REFERENCE.md b/ja/QUICK_REFERENCE.md new file mode 100644 index 0000000..dd3f69a --- /dev/null +++ b/ja/QUICK_REFERENCE.md @@ -0,0 +1,519 @@ + + + + + + + Claude How To + + +# Claude Code 例題 — クイックリファレンスカード + +## 🚀 インストール用クイックコマンド + +### スラッシュコマンド +```bash +# 全部インストール +cp 01-slash-commands/*.md .claude/commands/ + +# 特定のものをインストール +cp 01-slash-commands/optimize.md .claude/commands/ +``` + +### メモリ +```bash +# プロジェクトメモリ +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# 個人メモリ +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +### スキル +```bash +# 個人スキル +cp -r 03-skills/code-review ~/.claude/skills/ + +# プロジェクトスキル +cp -r 03-skills/code-review .claude/skills/ +``` + +### サブエージェント +```bash +# 全部インストール +cp 04-subagents/*.md .claude/agents/ + +# 特定のものをインストール +cp 04-subagents/code-reviewer.md .claude/agents/ +``` + +### MCP +```bash +# 認証情報を設定 +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# 設定をインストール (プロジェクトスコープ) +cp 05-mcp/github-mcp.json .mcp.json + +# またはユーザースコープ: ~/.claude.json に追加 +``` + +### フック +```bash +# フックをインストール +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# 設定で構成 (~/.claude/settings.json) +``` + +### プラグイン +```bash +# 例からインストール (公開済みなら) +/plugin install pr-review +/plugin install devops-automation +/plugin install documentation +``` + +### チェックポイント +```bash +# チェックポイントはユーザープロンプトのたびに自動作成される +# 巻き戻しは Esc を 2 回押すか、次を実行: +/rewind + +# 選択肢: コードと会話の復元、会話の復元、 +# コードの復元、ここから要約、やめる +``` + +### 高度な機能 +```bash +# 設定で構成 (.claude/settings.json) +# 09-advanced-features/config-examples.json を参照 + +# プランニングモード +/plan Task description + +# 権限モード (--permission-mode フラグを使う) +# default - 危険な操作で承認を求める +# acceptEdits - ファイル編集を自動承認、それ以外は確認 +# plan - 読み取り専用分析、変更なし +# dontAsk - 危険なもの以外すべて承認 +# auto - バックグラウンド分類器が自動的に権限を判断 +# bypassPermissions - すべて承認 (--dangerously-skip-permissions が必要) + +# セッション管理 +/resume # 過去の会話を再開 +/rename "name" # 現在のセッションに名前を付ける +/fork # 現在のセッションをフォーク +claude -c # 直近の会話を継続 +claude -r "session" # 名前 / ID でセッションを再開 +``` + +--- + +## 📋 機能チートシート + +| 機能 | インストール先 | 使い方 | +|---------|-------------|-------| +| **スラッシュコマンド (55 個以上)** | `.claude/commands/*.md` | `/command-name` | +| **メモリ** | `./CLAUDE.md` | 自動ロード | +| **スキル** | `.claude/skills/*/SKILL.md` | 自動起動 | +| **サブエージェント** | `.claude/agents/*.md` | 自動委譲 | +| **MCP** | `.mcp.json` (プロジェクト) または `~/.claude.json` (ユーザー) | `/mcp__server__action` | +| **フック (28 イベント)** | `~/.claude/hooks/*.sh` | イベントトリガー (5 種類) | +| **プラグイン** | `/plugin install` 経由 | すべてをバンドル | +| **チェックポイント** | 組み込み | `Esc+Esc` または `/rewind` | +| **プランニングモード** | 組み込み | `/plan ` | +| **権限モード (6 モード)** | 組み込み | `--allowedTools`、`--permission-mode` | +| **セッション** | 組み込み | `/session ` | +| **バックグラウンドタスク** | 組み込み | バックグラウンドで実行 | +| **リモートコントロール** | 組み込み | WebSocket API | +| **Web セッション** | 組み込み | `claude web` | +| **Git ワークツリー** | 組み込み | `/worktree` | +| **Auto Memory** | 組み込み | CLAUDE.md に自動保存 | +| **タスクリスト** | 組み込み | `/task list` | +| **バンドルスキル (5 個)** | 組み込み | `/simplify`、`/loop`、`/claude-api`、`/voice`、`/browse` | + +--- + +## 🎯 よくあるユースケース + +### コードレビュー +```bash +# 方法 1: スラッシュコマンド +cp 01-slash-commands/optimize.md .claude/commands/ +# 利用: /optimize + +# 方法 2: サブエージェント +cp 04-subagents/code-reviewer.md .claude/agents/ +# 利用: 自動委譲 + +# 方法 3: スキル +cp -r 03-skills/code-review ~/.claude/skills/ +# 利用: 自動起動 + +# 方法 4: プラグイン (推奨) +/plugin install pr-review +# 利用: /review-pr +``` + +### ドキュメント +```bash +# スラッシュコマンド +cp 01-slash-commands/generate-api-docs.md .claude/commands/ + +# サブエージェント +cp 04-subagents/documentation-writer.md .claude/agents/ + +# スキル +cp -r 03-skills/doc-generator ~/.claude/skills/ + +# プラグイン (完全ソリューション) +/plugin install documentation +``` + +### DevOps +```bash +# 完全プラグイン +/plugin install devops-automation + +# コマンド: /deploy、/rollback、/status、/incident +``` + +### チーム標準 +```bash +# プロジェクトメモリ +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# チーム向けに編集 +vim CLAUDE.md +``` + +### 自動化とフック +```bash +# フックをインストール (28 イベント、5 種類: command, http, mcp_tool, prompt, agent) +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# 例: +# - コミット前テスト: pre-commit.sh +# - コード自動整形: format-code.sh +# - セキュリティスキャン: security-scan.sh + +# 完全自律ワークフローのための Auto Mode +claude --enable-auto-mode -p "Refactor and test the auth module" +# あるいは Shift+Tab で対話的にモードを切替 +``` + +### 安全なリファクタリング +```bash +# チェックポイントは各プロンプト前に自動作成される +# リファクタリングを試す +# うまくいけば: 続行 +# 失敗したら: Esc+Esc を押すか /rewind で戻る +``` + +### 複雑な実装 +```bash +# プランニングモードを使う +/plan Implement user authentication system + +# Claude が詳細な計画を作る +# レビューして承認 +# Claude が体系的に実装する +``` + +### CI/CD 統合 +```bash +# ヘッドレスモードで実行 (非対話) +claude -p "Run all tests and generate report" + +# CI 用権限モードつき +claude -p "Run tests" --permission-mode dontAsk + +# 完全自律 CI タスクのための Auto Mode +claude --enable-auto-mode -p "Run tests and fix failures" + +# 自動化のためのフックつき +# 09-advanced-features/README.md を参照 +``` + +### 学習と実験 +```bash +# 安全な分析のため plan モードを使う +claude --permission-mode plan + +# 安全に実験 - チェックポイントは自動作成される +# 巻き戻しが必要なら: Esc+Esc または /rewind +``` + +### Agent Teams +```bash +# Agent Teams を有効化 +export CLAUDE_AGENT_TEAMS=1 + +# あるいは settings.json で +{ "agentTeams": { "enabled": true } } + +# 開始: "Implement feature X using a team approach" +``` + +### スケジュールタスク +```bash +# 5 分ごとにコマンドを実行 +/loop 5m /check-status + +# 一回限りのリマインダー +/loop 30m "remind me to check the deploy" +``` + +--- + +## 📁 ファイル配置リファレンス + +``` +Your Project/ +├── .claude/ +│ ├── commands/ # スラッシュコマンドはここ +│ ├── agents/ # サブエージェントはここ +│ ├── skills/ # プロジェクトスキルはここ +│ └── settings.json # プロジェクト設定 (フックなど) +├── .mcp.json # MCP 設定 (プロジェクトスコープ) +├── CLAUDE.md # プロジェクトメモリ +└── src/ + └── api/ + └── CLAUDE.md # ディレクトリ固有メモリ + +User Home/ +├── .claude/ +│ ├── commands/ # 個人コマンド +│ ├── agents/ # 個人エージェント +│ ├── skills/ # 個人スキル +│ ├── hooks/ # フックスクリプト +│ ├── settings.json # ユーザー設定 +│ ├── managed-settings.d/ # 管理設定 (エンタープライズ / 組織) +│ └── CLAUDE.md # 個人メモリ +└── .claude.json # 個人 MCP 設定 (ユーザースコープ) +``` + +--- + +## 🔍 例の探し方 + +### カテゴリ別 +- **スラッシュコマンド**：`01-slash-commands/` +- **メモリ**：`02-memory/` +- **スキル**：`03-skills/` +- **サブエージェント**：`04-subagents/` +- **MCP**：`05-mcp/` +- **フック**：`06-hooks/` +- **プラグイン**：`07-plugins/` +- **チェックポイント**：`08-checkpoints/` +- **高度な機能**：`09-advanced-features/` +- **CLI**：`10-cli/` + +### ユースケース別 +- **パフォーマンス**：`01-slash-commands/optimize.md` +- **セキュリティ**：`04-subagents/secure-reviewer.md` +- **テスト**：`04-subagents/test-engineer.md` +- **ドキュメント**：`03-skills/doc-generator/` +- **DevOps**：`07-plugins/devops-automation/` + +### 複雑度別 +- **シンプル**：スラッシュコマンド +- **中程度**：サブエージェント、メモリ +- **高度**：スキル、フック +- **完全**：プラグイン + +--- + +## 🎓 学習パス + +### 1 日目 +```bash +# 概要を読む +cat README.md + +# コマンドをインストール +cp 01-slash-commands/optimize.md .claude/commands/ + +# 試す +/optimize +``` + +### 2〜3 日目 +```bash +# メモリをセットアップ +cp 02-memory/project-CLAUDE.md ./CLAUDE.md +vim CLAUDE.md + +# サブエージェントをインストール +cp 04-subagents/code-reviewer.md .claude/agents/ +``` + +### 4〜5 日目 +```bash +# MCP をセットアップ +export GITHUB_TOKEN="your_token" +cp 05-mcp/github-mcp.json .mcp.json + +# MCP コマンドを試す +/mcp__github__list_prs +``` + +### 第 2 週 +```bash +# スキルをインストール +cp -r 03-skills/code-review ~/.claude/skills/ + +# 自動起動させる +# こう言うだけ: "Review this code for issues" +``` + +### 第 3 週以降 +```bash +# 完全プラグインをインストール +/plugin install pr-review + +# バンドル機能を使う +/review-pr +/check-security +/check-tests +``` + +--- + +## 新機能（2026 年 3 月） + +| 機能 | 説明 | 使い方 | +|---------|-------------|-------| +| **Auto Mode** | バックグラウンド分類器による完全自律動作 | `--enable-auto-mode` フラグ、`Shift+Tab` でモード切替 | +| **チャンネル** | Discord と Telegram 統合 | `--channels` フラグ、Discord / Telegram ボット | +| **音声入力** | コマンドとコンテキストを Claude に音声で伝える | `/voice` コマンド | +| **フック (28 イベント)** | 5 種類に拡張されたフックシステム | command、http、mcp_tool、prompt、agent の各フック種別 | +| **MCP Elicitation** | MCP サーバが実行時にユーザー入力を要求できる | サーバが要明確化なら自動プロンプト | +| **Plugin LSP** | プラグインの Language Server Protocol サポート | `userConfig`、`${CLAUDE_PLUGIN_DATA}` 変数 | +| **リモートコントロール** | WebSocket API で Claude Code を制御 | 外部統合のための `claude --remote` | +| **Web セッション** | ブラウザベースの Claude Code インターフェース | 起動：`claude web` | +| **デスクトップアプリ** | ネイティブデスクトップアプリ | claude.ai/download からダウンロード | +| **タスクリスト** | バックグラウンドタスクの管理 | `/task list`、`/task status ` | +| **Auto Memory** | 会話からの自動メモリ保存 | Claude が CLAUDE.md に主要コンテキストを自動保存 | +| **Git ワークツリー** | 並列開発のための隔離ワークスペース | `/worktree` で隔離ワークスペースを作成 | +| **モデル選択** | Sonnet 4.6、Opus 4.7、Haiku 4.5 を切替 | `/model` または `--model` フラグ | +| **Agent Teams** | タスク上の複数エージェントを協調 | 環境変数 `CLAUDE_AGENT_TEAMS=1` で有効化 | +| **スケジュールタスク** | `/loop` による反復タスク | `/loop 5m /command` または CronCreate ツール | +| **Chrome 連携** | ブラウザ自動化 | `--chrome` フラグまたは `/chrome` コマンド | +| **キーバインドカスタマイズ** | カスタムキーバインド | `/keybindings` コマンド | + +--- + +## ヒントとコツ + +### カスタマイズ +- 例題はそのままから始める +- 自分のニーズに合わせて改造する +- チームに共有する前にテストする +- 設定をバージョン管理する + +### ベストプラクティス +- チーム標準にはメモリを使う +- 完全ワークフローにはプラグインを使う +- 複雑タスクにはサブエージェントを使う +- 単純タスクにはスラッシュコマンドを使う + +### トラブルシューティング +```bash +# ファイル配置を確認 +ls -la .claude/commands/ +ls -la .claude/agents/ + +# YAML 構文を検証 +head -20 .claude/agents/code-reviewer.md + +# MCP 接続をテスト +echo $GITHUB_TOKEN +``` + +--- + +## 📊 機能マトリクス + +| 必要なもの | 使う機能 | 例 | +|------|----------|---------| +| 高速ショートカット | スラッシュコマンド (55 個以上) | `01-slash-commands/optimize.md` | +| チーム標準 | メモリ | `02-memory/project-CLAUDE.md` | +| 自動ワークフロー | スキル | `03-skills/code-review/` | +| 専門タスク | サブエージェント | `04-subagents/code-reviewer.md` | +| 外部データ | MCP（+ Elicitation） | `05-mcp/github-mcp.json` | +| イベント自動化 | フック (28 イベント、5 種類) | `06-hooks/pre-commit.sh` | +| 完全ソリューション | プラグイン (+ LSP サポート) | `07-plugins/pr-review/` | +| 安全な実験 | チェックポイント | `08-checkpoints/checkpoint-examples.md` | +| 完全自律 | Auto Mode | `--enable-auto-mode` または `Shift+Tab` | +| チャット連携 | チャンネル | `--channels`（Discord、Telegram） | +| CI/CD パイプライン | CLI | `10-cli/README.md` | + +--- + +## 🔗 クイックリンク + +- **メインガイド**：`README.md` +- **完全索引**：`INDEX.md` +- **サマリー**：`EXAMPLES_SUMMARY.md` +- **オリジナルガイド**：`claude_concepts_guide.md` + +--- + +## 📞 よくある質問 + +**Q：どれを使えばよいか？** +A：スラッシュコマンドから始め、必要に応じて機能を追加する。 + +**Q：機能を組み合わせられるか？** +A：できる。連携動作する。メモリ + コマンド + MCP は強力。 + +**Q：チームと共有するには？** +A：`.claude/` ディレクトリを git にコミットする。 + +**Q：シークレットはどうするか？** +A：環境変数を使い、ハードコードしない。 + +**Q：例を改造してよいか？** +A：もちろん。カスタマイズ用のテンプレートである。 + +--- + +## ✅ チェックリスト + +スタート用チェックリスト： + +- [ ] `README.md` を読む +- [ ] スラッシュコマンドを 1 つインストール +- [ ] そのコマンドを試す +- [ ] プロジェクト `CLAUDE.md` を作成 +- [ ] サブエージェントを 1 つインストール +- [ ] MCP 統合を 1 つセットアップ +- [ ] スキルを 1 つインストール +- [ ] 完全プラグインを試す +- [ ] 自分のニーズに合わせてカスタマイズ +- [ ] チームと共有する + +--- + +**クイックスタート**：`cat README.md` + +**完全索引**：`cat INDEX.md` + +**このカード**：手元に置いてクイックリファレンスとして！ + +--- +**最終更新**：2026 年 4 月 24 日 +**Claude Code バージョン**：2.1.119 +**情報源**： +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/commands +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**互換モデル**：Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/README.md b/ja/README.md new file mode 100644 index 0000000..73cd49a --- /dev/null +++ b/ja/README.md @@ -0,0 +1,885 @@ + + + + + + + Claude How To + + +

+ + + +

+ +[![GitHub Stars](https://img.shields.io/github/stars/luongnv89/claude-howto?style=flat&color=gold)](https://github.com/luongnv89/claude-howto/stargazers) +[![GitHub Forks](https://img.shields.io/github/forks/luongnv89/claude-howto?style=flat)](https://github.com/luongnv89/claude-howto/network/members) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE) +[![Version](https://img.shields.io/badge/version-2.1.119-brightgreen)](../CHANGELOG.md) +[![Claude Code](https://img.shields.io/badge/Claude_Code-2.1+-purple)](https://code.claude.com) + +🌐 **Language / Ngôn ngữ / 语言 / Мова / 言語:** [English](../README.md) | [Tiếng Việt](../vi/README.md) | [中文](../zh/README.md) | [Українська](../uk/README.md) | [日本語](README.md) + +# Claude Code を週末でマスターする + +`claude` と打ち込むだけの段階から、エージェント、フック、スキル、MCP サーバを束ねる段階へ。視覚的なチュートリアル、コピペで使えるテンプレート、ガイド付き学習パスで導く。 + +**[15 分で始める](#15-分で始める)** | **[自分のレベルを見つける](#どこから始めればよいか分からない)** | **[機能カタログを見る](CATALOG.md)** + +--- + +## 目次 + +- [課題](#課題) +- [Claude How To が解決する方法](#claude-how-to-が解決する方法) +- [仕組み](#仕組み) +- [どこから始めればよいか分からない？](#どこから始めればよいか分からない) +- [15 分で始める](#15-分で始める) +- [何が作れるか](#何が作れるか) +- [FAQ](#faq) +- [コントリビュート](#コントリビュート) +- [ライセンス](#ライセンス) + +--- + +## 課題 + +Claude Code をインストールし、いくつかプロンプトを実行した。次は何をすべきか。 + +- **公式ドキュメントは機能を説明するが、組み合わせ方は示さない。** スラッシュコマンドの存在は知っていても、フック、メモリ、サブエージェントと連携させて、本当に時間を節約するワークフローに組み立てる方法は分からない。 +- **明確な学習パスがない。** MCP をフックの前に学ぶべきか。スキルをサブエージェントの前に学ぶべきか。結局すべてを流し読みして、何一つマスターできない。 +- **例題が基本的すぎる。** 「hello world」のスラッシュコマンドでは、メモリを使い、専門エージェントに委譲し、セキュリティスキャンを自動実行する本番品質のコードレビューパイプラインは作れない。 + +Claude Code の力の 90% を眠らせたままで、しかも自分が何を知らないかすら分かっていない状態である。 + +--- + +## Claude How To が解決する方法 + +これは単なる機能リファレンスではない。**構造化された、視覚的な、サンプル駆動のガイド** であり、Claude Code の各機能の使い方を、今日プロジェクトにそのままコピーして使える実践テンプレートとともに教える。 + +| | 公式ドキュメント | 本ガイド | +|--|---------------|------------| +| **形式** | リファレンスドキュメント | Mermaid 図つきの視覚的チュートリアル | +| **深さ** | 機能の説明 | 内部の動作原理 | +| **例** | 基本的なスニペット | すぐ使える本番品質テンプレート | +| **構造** | 機能別の編成 | 段階的な学習パス（初級から上級まで） | +| **オンボーディング** | 自己学習 | 所要時間つきガイド付きロードマップ | +| **自己評価** | なし | 弱点を見つけて個別パスを構築するインタラクティブ・クイズ | + +### 得られるもの + +- **10 個のチュートリアルモジュール**：スラッシュコマンドからカスタムエージェントチームまで、Claude Code の全機能を網羅 +- **コピペ可能な設定**：スラッシュコマンド、CLAUDE.md テンプレート、フックスクリプト、MCP 設定、サブエージェント定義、フルプラグインバンドル +- **Mermaid 図** で各機能の内部動作を可視化し、「どう」だけでなく「なぜ」を理解できる +- **ガイド付き学習パス** によって 11〜13 時間で初級者からパワーユーザーまで到達できる +- **組み込みの自己評価**：Claude Code 内で `/self-assessment` または `/lesson-quiz hooks` を実行して弱点を特定できる + +**[学習パスを始める ->](LEARNING-ROADMAP.md)** + +--- + +## 仕組み + +### 1. 自分のレベルを見つける + +[自己評価クイズ](LEARNING-ROADMAP.md#-自分のレベルを見つける) を受けるか、Claude Code 内で `/self-assessment` を実行する。すでに知っていることに基づいた個別ロードマップが得られる。 + +### 2. ガイド付きパスを進む + +10 モジュールを順に進める。各モジュールは前のモジュールの上に積み上がる。学びながら、テンプレートをそのままプロジェクトにコピーする。 + +### 3. 機能を組み合わせてワークフローにする + +真の力は機能の組み合わせにある。スラッシュコマンド、メモリ、サブエージェント、フックを連携させて、コードレビュー、デプロイ、ドキュメント生成を自動化するパイプラインの作り方を学ぶ。 + +### 4. 理解度を試す + +各モジュールの後に `/lesson-quiz [トピック]` を実行する。クイズが見落とした箇所を特定するため、弱点をすばやく埋められる。 + +**[15 分で始める](#15-分で始める)** + +--- + +## 21,800 名以上の開発者に信頼されている + +- **GitHub スター 21,800 個以上**：日常的に Claude Code を使う開発者から +- **フォーク 2,585 件以上**：自チームのワークフローに合わせて応用するチームから +- **積極的にメンテナンス**：Claude Code のリリースに同期（最新は v2.1.119、2026 年 4 月） +- **コミュニティ駆動**：実際の運用設定を共有する開発者からのコントリビュート + +[![Star History Chart](https://api.star-history.com/svg?repos=luongnv89/claude-howto&type=Date)](https://star-history.com/#luongnv89/claude-howto&Date) + +--- + +## どこから始めればよいか分からない？ + +自己評価を受けるか、レベルを選ぶ。 + +| レベル | できること | スタート地点 | 所要時間 | +|-------|-----------|------------|------| +| **初級** | Claude Code を起動して対話 | [スラッシュコマンド](01-slash-commands/) | 約 2.5 時間 | +| **中級** | CLAUDE.md とカスタムコマンドを使う | [スキル](03-skills/) | 約 3.5 時間 | +| **上級** | MCP サーバとフックを設定する | [高度な機能](09-advanced-features/) | 約 5 時間 | + +**全 10 モジュールの完全学習パス：** + +| 順序 | モジュール | レベル | 所要時間 | +|-------|--------|-------|------| +| 1 | [スラッシュコマンド](01-slash-commands/) | 初級 | 30 分 | +| 2 | [メモリ](02-memory/) | 初級+ | 45 分 | +| 3 | [チェックポイント](08-checkpoints/) | 中級 | 45 分 | +| 4 | [CLI 基礎](10-cli/) | 初級+ | 30 分 | +| 5 | [スキル](03-skills/) | 中級 | 1 時間 | +| 6 | [フック](06-hooks/) | 中級 | 1 時間 | +| 7 | [MCP](05-mcp/) | 中級+ | 1 時間 | +| 8 | [サブエージェント](04-subagents/) | 中級+ | 1.5 時間 | +| 9 | [高度な機能](09-advanced-features/) | 上級 | 2〜3 時間 | +| 10 | [プラグイン](07-plugins/) | 上級 | 2 時間 | + +**[完全学習ロードマップ ->](LEARNING-ROADMAP.md)** + +--- + +## 15 分で始める + +> **インストールに関する注記**：v2.1.113 以降、Claude Code はプラットフォーム別のネイティブバイナリ（macOS / Linux / Windows）として配布される。`npm install -g @anthropic-ai/claude-code` も引き続き利用可能で、初回利用時にネイティブバイナリがオプション依存関係としてダウンロードされる。v2.1.116 以降、ダウンロード元は `https://downloads.claude.ai/claude-code-releases` であり、企業プロキシではこのホストを許可リストに加える必要がある。 + +```bash +# 1. ガイドをクローン +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto + +# 2. 最初のスラッシュコマンドをコピー +mkdir -p /path/to/your-project/.claude/commands +cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/ + +# 3. 試す — Claude Code で次を入力: +# /optimize + +# 4. 次に進みたければ、プロジェクトメモリを設定: +cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md + +# 5. スキルをインストール: +cp -r 03-skills/code-review ~/.claude/skills/ +``` + +フルセットアップが必要なら、**1 時間で必要な設定** はこちら。 + +```bash +# スラッシュコマンド (15 分) +cp 01-slash-commands/*.md .claude/commands/ + +# プロジェクトメモリ (15 分) +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# スキルをインストール (15 分) +cp -r 03-skills/code-review ~/.claude/skills/ + +# 週末ゴール: フック、サブエージェント、MCP、プラグインを追加 +# ガイド付きセットアップは学習パスに従う +``` + +**[完全インストールリファレンスを見る](#15-分で始める)** + +--- + +## 何が作れるか + +| ユースケース | 組み合わせる機能 | +|----------|------------------------| +| **自動コードレビュー** | スラッシュコマンド + サブエージェント + メモリ + MCP | +| **チームオンボーディング** | メモリ + スラッシュコマンド + プラグイン | +| **CI/CD 自動化** | CLI リファレンス + フック + バックグラウンドタスク | +| **ドキュメント生成** | スキル + サブエージェント + プラグイン | +| **セキュリティ監査** | サブエージェント + スキル + フック（読み取り専用モード） | +| **DevOps パイプライン** | プラグイン + MCP + フック + バックグラウンドタスク | +| **複雑なリファクタリング** | チェックポイント + プランニングモード + フック | + +--- + +## FAQ + +**無料か？** +そう。MIT ライセンスで永遠に無料。個人プロジェクト、業務、チームで自由に使える。ライセンス表記の同梱以外に制約はない。 + +**メンテナンスされているか？** +積極的に。本ガイドは Claude Code のリリースごとに同期される。現行バージョンは v2.1.119（2026 年 4 月）で、Claude Code 2.1+ と互換。 + +**公式ドキュメントとの違いは？** +公式ドキュメントは機能リファレンスである。本ガイドは図、本番品質テンプレート、段階的な学習パスを備えたチュートリアルである。両者は補完関係にある。学ぶときはここから始め、具体的な仕様が必要なときに公式を参照するとよい。 + +**全部進めるのにどれくらいかかるか？** +完全パスで 11〜13 時間。ただし 15 分で即座に価値が得られる。スラッシュコマンドのテンプレートをコピーして試すだけでよい。 + +**Claude Sonnet / Haiku / Opus と一緒に使えるか？** +使える。すべてのテンプレートは Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 で動作する。 + +**コントリビュートできるか？** +もちろん。ガイドラインは [CONTRIBUTING.md](CONTRIBUTING.md) を参照。新しい例、バグ修正、ドキュメント改善、コミュニティテンプレートを歓迎する。 + +**オフラインで読めるか？** +読める。`uv run scripts/build_epub.py` を実行すれば、すべてのコンテンツとレンダリング済みの図を含む EPUB 電子書籍が生成される。 + +--- + +## 今日から Claude Code をマスターし始める + +すでに Claude Code はインストール済みのはず。あとは使いこなし方を知るだけで、生産性が 10 倍になる。本ガイドはそこに到達する構造化されたパス、視覚的な解説、コピペで使えるテンプレートを提供する。 + +MIT ライセンス。永遠に無料。クローンして、フォークして、自分のものにしてほしい。 + +**[学習パスを始める ->](LEARNING-ROADMAP.md)** | **[機能カタログを見る](CATALOG.md)** | **[15 分で始める](#15-分で始める)** + +--- + +
+クイックナビゲーション — 全機能 + +| 機能 | 説明 | フォルダ | +|---------|-------------|--------| +| **機能カタログ** | インストールコマンド付き完全リファレンス | [CATALOG.md](CATALOG.md) | +| **スラッシュコマンド** | ユーザーが実行するショートカット | [01-slash-commands/](01-slash-commands/) | +| **メモリ** | 永続的なコンテキスト | [02-memory/](02-memory/) | +| **スキル** | 再利用可能な機能 | [03-skills/](03-skills/) | +| **サブエージェント** | 専門特化した AI アシスタント | [04-subagents/](04-subagents/) | +| **MCP プロトコル** | 外部ツールアクセス | [05-mcp/](05-mcp/) | +| **フック** | イベント駆動の自動化 | [06-hooks/](06-hooks/) | +| **プラグイン** | バンドルされた機能 | [07-plugins/](07-plugins/) | +| **チェックポイント** | セッションのスナップショットと巻き戻し | [08-checkpoints/](08-checkpoints/) | +| **高度な機能** | プランニング、思考、バックグラウンドタスク | [09-advanced-features/](09-advanced-features/) | +| **CLI リファレンス** | コマンド、フラグ、オプション | [10-cli/](10-cli/) | +| **ブログ記事** | 実際の利用例 | [Blog Posts](https://medium.com/@luongnv89) | + +
+ +
+機能比較 + +| 機能 | 起動方法 | 永続性 | 適している用途 | +|---------|-----------|------------|----------| +| **スラッシュコマンド** | 手動 (`/cmd`) | セッション内のみ | クイックショートカット | +| **メモリ** | 自動ロード | セッション横断 | 長期的な学習 | +| **スキル** | 自動起動 | ファイルシステム | 自動化ワークフロー | +| **サブエージェント** | 自動委譲 | コンテキスト分離 | タスク分散 | +| **MCP プロトコル** | 自動問い合わせ | リアルタイム | ライブデータアクセス | +| **フック** | イベントトリガー | 設定値で永続化 | 自動化と検証 | +| **プラグイン** | 1 コマンド | 全機能を含む | 完全なソリューション | +| **チェックポイント** | 手動 / 自動 | セッション単位 | 安全な実験 | +| **プランニングモード** | 手動 / 自動 | 計画フェーズ | 複雑な実装 | +| **バックグラウンドタスク** | 手動 | タスク存続期間 | 長時間処理 | +| **CLI リファレンス** | ターミナルコマンド | セッション / スクリプト | 自動化とスクリプト | + +
+ +
+インストール早見表 + +```bash +# Slash Commands +cp 01-slash-commands/*.md .claude/commands/ + +# Memory +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Skills +cp -r 03-skills/code-review ~/.claude/skills/ + +# Subagents +cp 04-subagents/*.md .claude/agents/ + +# MCP +export GITHUB_TOKEN="token" +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# Hooks +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# Plugins +/plugin install pr-review + +# Checkpoints (自動有効、設定で調整) +# 08-checkpoints/README.md を参照 + +# Advanced Features (設定で調整) +# 09-advanced-features/config-examples.json を参照 + +# CLI Reference (インストール不要) +# 利用例は 10-cli/README.md を参照 +``` + +
+ +
+01. スラッシュコマンド + +**配置場所**：[01-slash-commands/](01-slash-commands/) + +**概要**：Markdown ファイルとして保存される、ユーザーが実行するショートカット + +**例**： +- `optimize.md` — コード最適化分析 +- `pr.md` — プルリクエスト準備 +- `generate-api-docs.md` — API ドキュメント生成 + +**インストール**： +```bash +cp 01-slash-commands/*.md /path/to/project/.claude/commands/ +``` + +**使い方**： +``` +/optimize +/pr +/generate-api-docs +``` + +**詳しく学ぶ**：[Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) + +
+ +
+02. メモリ + +**配置場所**：[02-memory/](02-memory/) + +**概要**：セッションをまたいで保持される永続的なコンテキスト + +**例**： +- `project-CLAUDE.md` — チーム共通のプロジェクト規約 +- `directory-api-CLAUDE.md` — ディレクトリ固有のルール +- `personal-CLAUDE.md` — 個人の好み + +**インストール**： +```bash +# プロジェクトメモリ +cp 02-memory/project-CLAUDE.md /path/to/project/CLAUDE.md + +# ディレクトリメモリ +cp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md + +# 個人メモリ +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +**使い方**：Claude が自動的に読み込む + +
+ +
+03. スキル + +**配置場所**：[03-skills/](03-skills/) + +**概要**：指示書とスクリプトを備えた、再利用可能で自動起動される機能 + +**例**： +- `code-review/` — スクリプトつきの包括的なコードレビュー +- `brand-voice/` — ブランドボイスの一貫性チェッカー +- `doc-generator/` — API ドキュメント生成 + +**インストール**： +```bash +# 個人スキル +cp -r 03-skills/code-review ~/.claude/skills/ + +# プロジェクトスキル +cp -r 03-skills/code-review /path/to/project/.claude/skills/ +``` + +**使い方**：関連する場面で自動的に起動される + +
+ +
+04. サブエージェント + +**配置場所**：[04-subagents/](04-subagents/) + +**概要**：分離されたコンテキストとカスタムプロンプトを持つ、専門特化した AI アシスタント + +**例**： +- `code-reviewer.md` — 包括的なコード品質分析 +- `test-engineer.md` — テスト戦略とカバレッジ +- `documentation-writer.md` — 技術ドキュメント作成 +- `secure-reviewer.md` — セキュリティ重視のレビュー（読み取り専用） +- `implementation-agent.md` — 機能の完全実装 + +**インストール**： +```bash +cp 04-subagents/*.md /path/to/project/.claude/agents/ +``` + +**使い方**：メインエージェントが自動的に委譲する + +
+ +
+05. MCP プロトコル + +**配置場所**：[05-mcp/](05-mcp/) + +**概要**：外部ツールや API にアクセスするための Model Context Protocol + +**例**： +- `github-mcp.json` — GitHub 連携 +- `database-mcp.json` — データベースクエリ +- `filesystem-mcp.json` — ファイル操作 +- `multi-mcp.json` — 複数の MCP サーバ + +**インストール**： +```bash +# 環境変数を設定 +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# CLI で MCP サーバを追加 +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# またはプロジェクト .mcp.json に手動追加 (例は 05-mcp/ を参照) +``` + +**使い方**：設定後、MCP ツールは自動的に Claude から利用可能になる + +
+ +
+06. フック + +**配置場所**：[06-hooks/](06-hooks/) + +**概要**：Claude Code のイベントに応じて自動実行されるイベント駆動シェルコマンド + +**例**： +- `format-code.sh` — 書き込み前にコードを自動整形 +- `pre-commit.sh` — コミット前にテストを実行 +- `security-scan.sh` — セキュリティ問題のスキャン +- `log-bash.sh` — すべての bash コマンドをログに記録 +- `validate-prompt.sh` — ユーザープロンプトを検証 +- `notify-team.sh` — イベント発生時の通知送信 + +**インストール**： +```bash +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh +``` + +`~/.claude/settings.json` でフックを設定する： +```json +{ + "hooks": { + "PreToolUse": [{ + "matcher": "Write", + "hooks": ["~/.claude/hooks/format-code.sh"] + }], + "PostToolUse": [{ + "matcher": "Write", + "hooks": ["~/.claude/hooks/security-scan.sh"] + }] + } +} +``` + +**使い方**：イベント発生時にフックが自動実行される + +**フックの種類**（5 系統、28 イベント）： +- **ツール系フック**：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` +- **セッション系フック**：`SessionStart`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop` +- **タスク系フック**：`UserPromptSubmit`、`TaskCompleted`、`TaskCreated`、`TeammateIdle` +- **ライフサイクル系フック**：`ConfigChange`、`CwdChanged`、`FileChanged`、`PreCompact`、`PostCompact`、`WorktreeCreate`、`WorktreeRemove`、`Notification`、`InstructionsLoaded`、`Elicitation`、`ElicitationResult` + +
+ +
+07. プラグイン + +**配置場所**：[07-plugins/](07-plugins/) + +**概要**：コマンド、エージェント、MCP、フックをまとめたバンドル + +**例**： +- `pr-review/` — 完全な PR レビューワークフロー +- `devops-automation/` — デプロイと監視 +- `documentation/` — ドキュメント生成 + +**インストール**： +```bash +/plugin install pr-review +/plugin install devops-automation +/plugin install documentation +``` + +**使い方**：バンドルされたスラッシュコマンドや機能を利用する + +
+ +
+08. チェックポイントと巻き戻し + +**配置場所**：[08-checkpoints/](08-checkpoints/) + +**概要**：会話の状態を保存し、過去地点に巻き戻して別のアプローチを試す機能 + +**主要概念**： +- **チェックポイント**：会話状態のスナップショット +- **巻き戻し**：以前のチェックポイントへ戻る +- **分岐点**：同じチェックポイントから複数のアプローチを試す + +**使い方**： +``` +# チェックポイントはユーザープロンプトのたびに自動作成される +# 巻き戻しは Esc を 2 回押すか、次を実行: +/rewind + +# 5 つの選択肢から選ぶ: +# 1. コードと会話を復元 +# 2. 会話のみ復元 +# 3. コードのみ復元 +# 4. ここから要約 +# 5. やめる +``` + +**ユースケース**： +- 複数の実装アプローチを試す +- ミスからのリカバリ +- 安全な実験 +- 代替案の比較 +- 異なる設計の A/B テスト + +
+ +
+09. 高度な機能 + +**配置場所**：[09-advanced-features/](09-advanced-features/) + +**概要**：複雑なワークフローと自動化のための高度な機能 + +**含まれる機能**： +- **プランニングモード** — コーディング前に詳細な実装計画を作成 +- **拡張思考（Extended Thinking）** — 複雑な問題に対する深い推論（`Alt+T` / `Option+T` で切り替え） +- **バックグラウンドタスク** — ブロックなしに長時間処理を実行 +- **権限モード** — `default`、`acceptEdits`、`plan`、`dontAsk`、`bypassPermissions` +- **ヘッドレスモード** — CI/CD で Claude Code を実行：`claude -p "Run tests and generate report"` +- **セッション管理** — `/resume`、`/rename`、`/fork`、`claude -c`、`claude -r` +- **設定** — `~/.claude/settings.json` で挙動をカスタマイズ + +完全な設定例は [config-examples.json](09-advanced-features/config-examples.json) を参照。 + +
+ +
+10. CLI リファレンス + +**配置場所**：[10-cli/](10-cli/) + +**概要**：Claude Code のコマンドラインインターフェース完全リファレンス + +**簡単な例**： +```bash +# 対話モード +claude "explain this project" + +# 印字モード (非対話) +claude -p "review this code" + +# ファイル内容を処理 +cat error.log | claude -p "explain this error" + +# スクリプト向け JSON 出力 +claude -p --output-format json "list functions" + +# セッション再開 +claude -r "feature-auth" "continue implementation" +``` + +**ユースケース**：CI/CD パイプライン統合、スクリプト自動化、バッチ処理、複数セッションのワークフロー、カスタムエージェント設定 + +
+ +
+ワークフロー例 + +### 完全なコードレビューワークフロー + +```markdown +# 利用機能: スラッシュコマンド + サブエージェント + メモリ + MCP + +User: /review-pr + +Claude: +1. プロジェクトメモリ (コーディング規約) を読み込む +2. GitHub MCP 経由で PR を取得 +3. code-reviewer サブエージェントに委譲 +4. test-engineer サブエージェントに委譲 +5. 知見を統合 +6. 包括的なレビューを提供 +``` + +### ドキュメント自動生成 + +```markdown +# 利用機能: スキル + サブエージェント + メモリ + +User: "auth モジュールの API ドキュメントを生成して" + +Claude: +1. プロジェクトメモリ (ドキュメント規約) を読み込む +2. ドキュメント生成リクエストを検知 +3. doc-generator スキルを自動起動 +4. api-documenter サブエージェントに委譲 +5. 例つきの包括的なドキュメントを作成 +``` + +### DevOps デプロイ + +```markdown +# 利用機能: プラグイン + MCP + フック + +User: /deploy production + +Claude: +1. デプロイ前フックを実行 (環境を検証) +2. deployment-specialist サブエージェントに委譲 +3. Kubernetes MCP 経由でデプロイ実行 +4. 進捗を監視 +5. デプロイ後フックを実行 (ヘルスチェック) +6. ステータスを報告 +``` + +
+ +
+ディレクトリ構造 + +``` +├── 01-slash-commands/ +│ ├── optimize.md +│ ├── pr.md +│ ├── generate-api-docs.md +│ └── README.md +├── 02-memory/ +│ ├── project-CLAUDE.md +│ ├── directory-api-CLAUDE.md +│ ├── personal-CLAUDE.md +│ └── README.md +├── 03-skills/ +│ ├── code-review/ +│ │ ├── SKILL.md +│ │ ├── scripts/ +│ │ └── templates/ +│ ├── brand-voice/ +│ │ ├── SKILL.md +│ │ └── templates/ +│ ├── doc-generator/ +│ │ ├── SKILL.md +│ │ └── generate-docs.py +│ └── README.md +├── 04-subagents/ +│ ├── code-reviewer.md +│ ├── test-engineer.md +│ ├── documentation-writer.md +│ ├── secure-reviewer.md +│ ├── implementation-agent.md +│ └── README.md +├── 05-mcp/ +│ ├── github-mcp.json +│ ├── database-mcp.json +│ ├── filesystem-mcp.json +│ ├── multi-mcp.json +│ └── README.md +├── 06-hooks/ +│ ├── format-code.sh +│ ├── pre-commit.sh +│ ├── security-scan.sh +│ ├── log-bash.sh +│ ├── validate-prompt.sh +│ ├── notify-team.sh +│ └── README.md +├── 07-plugins/ +│ ├── pr-review/ +│ ├── devops-automation/ +│ ├── documentation/ +│ └── README.md +├── 08-checkpoints/ +│ ├── checkpoint-examples.md +│ └── README.md +├── 09-advanced-features/ +│ ├── config-examples.json +│ ├── planning-mode-examples.md +│ └── README.md +├── 10-cli/ +│ └── README.md +└── README.md (このファイル) +``` + +
+ +
+ベストプラクティス + +### 推奨事項 +- スラッシュコマンドからシンプルに始める +- 機能を段階的に追加する +- メモリにチーム規約を入れる +- 設定はまずローカルで試す +- カスタム実装をドキュメント化する +- プロジェクト設定をバージョン管理する +- プラグインをチームで共有する + +### 避けるべきこと +- 重複した機能を作らない +- 認証情報をハードコードしない +- ドキュメント化を省略しない +- 単純なタスクを過度に複雑にしない +- セキュリティのベストプラクティスを無視しない +- 機密データをコミットしない + +
+ +
+トラブルシューティング + +### 機能が読み込まれない +1. ファイルの配置場所と命名を確認 +2. YAML フロントマターの構文を確認 +3. ファイル権限を確認 +4. Claude Code のバージョン互換性を確認 + +### MCP 接続失敗 +1. 環境変数を確認 +2. MCP サーバのインストールを確認 +3. 認証情報をテスト +4. ネットワーク接続を確認 + +### サブエージェントに委譲されない +1. ツール権限を確認 +2. エージェント説明文の明確さを確認 +3. タスクの複雑度を確認 +4. エージェント単体でテスト + +
+ +
+テスト + +このプロジェクトには包括的な自動テストが含まれる。 + +- **ユニットテスト**：pytest を使った Python テスト（Python 3.10、3.11、3.12） +- **コード品質**：Ruff によるリンティングとフォーマット +- **セキュリティ**：Bandit による脆弱性スキャン +- **型チェック**：mypy による静的型解析 +- **ビルド検証**：EPUB 生成のテスト +- **カバレッジ計測**：Codecov 統合 + +```bash +# 開発依存関係をインストール +uv pip install -r requirements-dev.txt + +# 全ユニットテストを実行 +pytest scripts/tests/ -v + +# カバレッジレポートつきでテスト実行 +pytest scripts/tests/ -v --cov=scripts --cov-report=html + +# コード品質チェック +ruff check scripts/ +ruff format --check scripts/ + +# セキュリティスキャン +bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ + +# 型チェック +mypy scripts/ --ignore-missing-imports +``` + +`main`/`develop` への push および `main` への PR で自動的にテストが実行される。詳細は [TESTING.md](../.github/TESTING.md) を参照。 + +
+ +
+EPUB 生成 + +本ガイドをオフラインで読みたい場合は EPUB 電子書籍を生成する。 + +```bash +uv run scripts/build_epub.py +``` + +これによりレンダリング済み Mermaid 図を含む全コンテンツの `claude-howto-guide.epub` が作成される。 + +詳細なオプションは [scripts/README.md](../scripts/README.md) を参照。 + +
+ +
+コントリビュート + +問題を見つけた、もしくは例を提供したい場合は歓迎する。 + +**詳細なガイドラインは [CONTRIBUTING.md](CONTRIBUTING.md) を参照：** +- コントリビュートの種類（例、ドキュメント、機能、バグ、フィードバック） +- 開発環境のセットアップ方法 +- ディレクトリ構造とコンテンツ追加方法 +- 執筆ガイドラインとベストプラクティス +- コミットおよび PR プロセス + +**コミュニティ標準：** +- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — メンバー同士の接し方 +- [SECURITY.md](SECURITY.md) — セキュリティポリシーと脆弱性報告 + +### セキュリティ問題の報告 + +セキュリティ脆弱性を発見した場合は、責任ある形で報告してほしい。 + +1. **GitHub のプライベート脆弱性報告を使う**：https://github.com/luongnv89/claude-howto/security/advisories +2. **または** [.github/SECURITY_REPORTING.md](../.github/SECURITY_REPORTING.md) で詳細手順を読む +3. セキュリティ脆弱性については **公開 issue を立てない** + +クイックスタート： +1. リポジトリをフォークしてクローン +2. 内容が分かるブランチ名を作る（`add/feature-name`、`fix/bug`、`docs/improvement` など） +3. ガイドラインに沿って変更を加える +4. 明確な説明をつけてプルリクエストを送る + +**助けが必要なら？** issue かディスカッションを立てれば、プロセスを案内する。 + +
+ +
+追加リソース + +- [Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [MCP Protocol Specification](https://modelcontextprotocol.io) +- [Skills Repository](https://github.com/luongnv89/skills) — すぐ使えるスキル集 +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) +- [Boris Cherny's Claude Code Workflow](https://x.com/bcherny/status/2007179832300581177) — Claude Code の制作者が体系化したワークフローを共有：並列エージェント、共有 CLAUDE.md、プランニングモード、スラッシュコマンド、サブエージェント、自律的長時間セッションのための検証フック。 + +
+ +--- + +## コントリビュート + +コントリビュートを歓迎する。始め方の詳細は [Contributing Guide](CONTRIBUTING.md) を参照。 + +--- + +## ライセンス + +MIT License — [LICENSE](../LICENSE) を参照。利用、変更、再配布は自由。唯一の条件はライセンス表記の同梱である。 + +--- + +**最終更新**：2026 年 4 月 24 日 +**Claude Code バージョン**：2.1.119 +**情報源**： +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/changelog +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.113 +**互換モデル**：Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/RELEASE_NOTES.md b/ja/RELEASE_NOTES.md new file mode 100644 index 0000000..fee976d --- /dev/null +++ b/ja/RELEASE_NOTES.md @@ -0,0 +1,15 @@ + + + + +## v2.2.0 — 2026-03-26 + +### バグ修正 + +- CI のリンクチェックで失敗していた marketplace の死リンクを削除（3fdf0d6） +- `sandboxed` と `pycache` を cSpell 辞書に追加（dc64618） + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/SECURITY.md b/ja/SECURITY.md new file mode 100644 index 0000000..4b070f4 --- /dev/null +++ b/ja/SECURITY.md @@ -0,0 +1,338 @@ + + + + +# セキュリティポリシー + +## 概要 + +Claude How To プロジェクトのセキュリティを私たちは重視している。このドキュメントは、私たちのセキュリティ慣行と、脆弱性を責任を持って報告する方法を定める。 + +## サポート対象バージョン + +以下のバージョンに対してセキュリティ更新を提供する： + +| バージョン | ステータス | サポート期限 | +|---------|--------|---------------| +| Latest（main） | ✅ アクティブ | 現在 + 6 か月 | +| 1.x リリース | ✅ アクティブ | 次のメジャーバージョンまで | + +**注：** 教育用ガイドプロジェクトとして、私たちは従来のバージョンサポートよりも、現在のベストプラクティスとドキュメントセキュリティの維持に重点を置いている。更新は main ブランチに直接適用される。 + +## セキュリティ慣行 + +### コードセキュリティ + +1. **依存関係の管理** + - すべての Python 依存関係は `requirements.txt` で固定される + - Dependabot と手動レビューによる定期更新 + - すべてのコミットで Bandit によるセキュリティスキャン + - セキュリティチェック用の pre-commit フック + +2. **コード品質** + - Ruff によるリンティングが一般的な問題を捕捉 + - mypy による型チェックで型関連の脆弱性を防止 + - pre-commit フックが標準を強制 + - すべての変更はマージ前にレビューされる + +3. **アクセス制御** + - `main` ブランチでのブランチ保護 + - マージ前に必須レビュー + - マージ前に状態チェックの通過が必須 + - リポジトリへの書き込み権限を制限 + +### ドキュメントセキュリティ + +1. **サンプルにシークレットを含めない** + - サンプル中の API キーはすべてプレースホルダ + - 認証情報はハードコードしない + - `.env.example` ファイルで必要な変数を示す + - シークレット管理に関する明確な警告 + +2. **セキュリティのベストプラクティス** + - サンプルは安全なパターンを示す + - ドキュメントでセキュリティ警告を強調する + - 公式セキュリティガイドへのリンク + - 関連セクションで認証情報の扱いを議論する + +3. **コンテンツレビュー** + - すべてのドキュメントをセキュリティ問題についてレビュー + - コントリビューションガイドラインにセキュリティ考慮事項を含める + - 外部リンクと参照の検証 + +### 依存関係セキュリティ + +1. **スキャン** + - Bandit がすべての Python コードを脆弱性についてスキャン + - GitHub セキュリティアラートによる依存関係の脆弱性チェック + - 定期的な手動セキュリティ監査 + +2. **更新** + - セキュリティパッチを迅速に適用 + - メジャーバージョンを慎重に評価 + - 変更履歴にセキュリティ関連更新を含める + +3. **透明性** + - セキュリティ更新をコミットに記録 + - 脆弱性開示を責任を持って扱う + - 適切な場合に公開セキュリティ勧告を発行 + +## 脆弱性の報告 + +### 私たちが対象とするセキュリティ問題 + +以下の報告を歓迎する： +- スクリプトやサンプルの **コード脆弱性** +- Python パッケージの **依存関係の脆弱性** +- いずれのコード例にも含まれる **暗号関連の問題** +- ドキュメント中の **認証／認可の欠陥** +- 設定例における **データ露出のリスク** +- **インジェクション脆弱性**（SQL、コマンド等） +- **SSRF／XXE／パストラバーサル** の問題 + +### 対象外のセキュリティ問題 + +以下はこのプロジェクトの対象外である： +- Claude Code 自体の脆弱性（Anthropic に報告すること） +- 外部サービスやライブラリの問題（上流に報告すること） +- ソーシャルエンジニアリングやユーザー教育（このガイドの範囲外） +- 概念実証のない理論的脆弱性 +- 公式チャネルで報告された依存関係の脆弱性 + +## 報告の方法 + +### プライベート報告（推奨） + +**機微なセキュリティ問題には、GitHub のプライベート脆弱性報告を使ってほしい：** + +1. 訪問先：https://github.com/luongnv89/claude-howto/security/advisories +2. "Report a vulnerability" をクリック +3. 脆弱性の詳細を記入 +4. 以下を含める： + - 脆弱性の明確な説明 + - 影響を受けるコンポーネント（ファイル、セクション、サンプル） + - 潜在的な影響 + - 再現手順（該当する場合） + - 推奨される修正案（あれば） + +**その後の流れ：** +- 48 時間以内に受領を確認する +- 調査し、深刻度を評価する +- 修正策の開発に協力する +- 開示のタイムラインを調整する +- セキュリティ勧告であなたにクレジットを与える（匿名希望でない限り） + +### 公開報告 + +機微でない問題、またはすでに公開されている問題については： + +1. **GitHub Issue を作成** し `security` ラベルを付ける +2. 以下を含める： + - タイトル：`[SECURITY]` に続けて簡潔な説明 + - 詳細な説明 + - 影響を受けるファイルまたはセクション + - 潜在的な影響 + - 推奨される修正案 + +## 脆弱性対応プロセス + +### 評価（24 時間） + +1. 報告の受領を確認する +2. [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) を使って深刻度を評価する +3. 対象範囲内かどうかを判定する +4. 初期評価を報告者に連絡する + +### 開発（1〜7 日） + +1. 修正を開発する +2. 修正をレビュー・テストする +3. セキュリティ勧告を作成する +4. リリースノートを準備する + +### 開示（深刻度による） + +**Critical（CVSS 9.0〜10.0）** +- 修正を即座にリリース +- 公開勧告を発行 +- 報告者に 24 時間前通知 + +**High（CVSS 7.0〜8.9）** +- 48〜72 時間以内に修正をリリース +- 報告者に 5 日前通知 +- リリースと同時に公開勧告 + +**Medium（CVSS 4.0〜6.9）** +- 次の定期更新で修正をリリース +- リリースと同時に公開勧告 + +**Low（CVSS 0.1〜3.9）** +- 次の定期更新に修正を含める +- リリースと同時に勧告 + +### 公表 + +私たちは以下を含むセキュリティ勧告を公表する： +- 脆弱性の説明 +- 影響を受けるコンポーネント +- 深刻度評価（CVSS スコア） +- 修正バージョン +- 回避策（該当する場合） +- 報告者へのクレジット（同意がある場合） + +## 報告者のためのベストプラクティス + +### 報告前 + +- **問題を確認：** 一貫して再現できるか？ +- **既存の Issue を検索：** すでに報告されていないか？ +- **ドキュメントを確認：** 安全な使い方のガイダンスはあるか？ +- **修正をテスト：** 推奨する修正は機能するか？ + +### 報告時 + +- **具体的に：** 正確なファイルパスと行番号を提供する +- **コンテキストを含める：** なぜこれがセキュリティ問題なのか？ +- **影響を示す：** 攻撃者が何をできるか？ +- **手順を提供：** どうすれば再現できるか？ +- **修正案を出す：** どう修正するか？ + +### 報告後 + +- **辛抱強く：** 私たちのリソースは限られている +- **応答する：** フォローアップ質問に迅速に答える +- **機密を保つ：** 修正前に公開しない +- **調整を尊重：** 開示のタイムラインに従う + +## セキュリティヘッダと設定 + +### リポジトリのセキュリティ + +- **ブランチ保護：** main ブランチへの変更には 2 名の承認が必要 +- **状態チェック：** すべての CI/CD チェックの通過が必須 +- **CODEOWNERS：** 主要ファイルには指定レビュアー +- **署名付きコミット：** コントリビュータに推奨 + +### 開発時のセキュリティ + +```bash +# pre-commit フックをインストール +pre-commit install + +# ローカルでセキュリティスキャンを実行 +bandit -c pyproject.toml -r scripts/ +mypy scripts/ --ignore-missing-imports +ruff check scripts/ +``` + +### 依存関係のセキュリティ + +```bash +# 既知の脆弱性をチェック +pip install safety +safety check + +# あるいは pip-audit を使う +pip install pip-audit +pip-audit +``` + +## コントリビュータ向けセキュリティガイドライン + +### サンプルを書くとき + +1. **シークレットをハードコードしない** + ```python + # ❌ 悪い例 + api_key = "sk-1234567890" + + # ✅ よい例 + api_key = os.getenv("API_KEY") + ``` + +2. **セキュリティへの影響を警告する** + ```markdown + ⚠️ **セキュリティに関する注意**：`.env` ファイルは絶対に git に + コミットしない。すぐに `.gitignore` に追加すること。 + ``` + +3. **安全なデフォルトを使う** + - 認証をデフォルトで有効化する + - 該当する場合は HTTPS を使う + - 入力を検証・サニタイズする + - パラメータ化クエリを使う + +4. **セキュリティ考慮事項をドキュメント化する** + - なぜセキュリティが重要かを説明する + - 安全なパターンと安全でないパターンを示す + - 信頼できる出典にリンクする + - 警告を目立つように記載する + +### コントリビューションをレビューするとき + +1. **公開されたシークレットをチェック** + - 一般的なパターンをスキャン（api_key=、password= など） + - 設定ファイルをレビュー + - 環境変数を確認 + +2. **安全なコーディング慣行を確認** + - 認証情報のハードコードがないか + - 入力検証が適切か + - 認証／認可が安全か + - ファイル処理が安全か + +3. **セキュリティへの影響をテスト** + - 悪用される可能性はあるか？ + - 最悪のケースは？ + - エッジケースはあるか？ + +## セキュリティリソース + +### 公式標準 +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) + +### Python セキュリティ +- [Python Security Advisories](https://www.python.org/dev/security/) +- [PyPI Security](https://pypi.org/help/#security) +- [Bandit Documentation](https://bandit.readthedocs.io/) + +### 依存関係管理 +- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) +- [GitHub Security Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) + +### 一般的なセキュリティ +- [Anthropic Security](https://www.anthropic.com/) +- [GitHub Security Best Practices](https://docs.github.com/en/code-security) + +## セキュリティ勧告アーカイブ + +過去のセキュリティ勧告は [GitHub Security Advisories](https://github.com/luongnv89/claude-howto/security/advisories) タブで確認できる。 + +## 連絡先 + +セキュリティに関する質問やセキュリティ慣行の議論： + +1. **プライベートセキュリティ報告：** GitHub のプライベート脆弱性報告を使う +2. **一般的なセキュリティの質問：** `[SECURITY]` タグでディスカッションを開く +3. **セキュリティポリシーへのフィードバック：** `security` ラベルで Issue を作成 + +## 謝辞 + +このプロジェクトを安全に保つために協力してくださるセキュリティ研究者とコミュニティメンバーに感謝する。脆弱性を責任を持って報告したコントリビュータは、セキュリティ勧告で謝意を示す（匿名希望でない限り）。 + +## ポリシーの更新 + +このセキュリティポリシーは以下のときにレビュー・更新される： +- 新たな脆弱性が発見されたとき +- セキュリティのベストプラクティスが進化したとき +- プロジェクトの範囲が変わったとき +- 最低でも年 1 回 + +**Last Updated**: January 2026 +**Next Review**: January 2027 + +--- + +Claude How To を安全に保つためのご協力ありがとうございます！🔒 diff --git a/ja/STYLE_GUIDE.md b/ja/STYLE_GUIDE.md new file mode 100644 index 0000000..0e3bb48 --- /dev/null +++ b/ja/STYLE_GUIDE.md @@ -0,0 +1,646 @@ + + + + + + + Claude How To + + +# スタイルガイド + +> Claude How To にコントリビュートする際の規約とフォーマットルール。コンテンツを一貫した、プロフェッショナルで保守しやすい状態に保つため、本ガイドに従うこと。 +> +> ※日本語訳における文体・用語ルールについては `TRANSLATION_NOTES.md` も参照。 + +--- + +## 目次 + +- [ファイルとフォルダの命名](#ファイルとフォルダの命名) +- [ドキュメント構造](#ドキュメント構造) +- [見出し](#見出し) +- [テキストフォーマット](#テキストフォーマット) +- [リスト](#リスト) +- [テーブル](#テーブル) +- [コードブロック](#コードブロック) +- [リンクと相互参照](#リンクと相互参照) +- [図](#図) +- [絵文字の使い方](#絵文字の使い方) +- [YAML フロントマター](#yaml-フロントマター) +- [画像とメディア](#画像とメディア) +- [トーンと声](#トーンと声) +- [コミットメッセージ](#コミットメッセージ) +- [著者向けチェックリスト](#著者向けチェックリスト) + +--- + +## ファイルとフォルダの命名 + +### レッスンフォルダ + +レッスンフォルダは **2 桁の番号プレフィックス** に **kebab-case** の記述子を続ける： + +``` +01-slash-commands/ +02-memory/ +03-skills/ +04-subagents/ +05-mcp/ +``` + +番号は初心者から上級者への学習パスの順序を反映する。 + +### ファイル名 + +| 種別 | 規約 | 例 | +|------|-----------|----------| +| **レッスン README** | `README.md` | `01-slash-commands/README.md` | +| **機能ファイル** | kebab-case `.md` | `code-reviewer.md`、`generate-api-docs.md` | +| **シェルスクリプト** | kebab-case `.sh` | `format-code.sh`、`validate-input.sh` | +| **設定ファイル** | 標準名 | `.mcp.json`、`settings.json` | +| **メモリファイル** | スコーププレフィックス | `project-CLAUDE.md`、`personal-CLAUDE.md` | +| **トップレベル文書** | UPPER_CASE `.md` | `CATALOG.md`、`QUICK_REFERENCE.md`、`CONTRIBUTING.md` | +| **画像アセット** | kebab-case | `pr-slash-command.png`、`claude-howto-logo.svg` | + +### ルール + +- すべてのファイル名・フォルダ名は **小文字** を使用する（`README.md`、`CATALOG.md` などのトップレベル文書を除く） +- 単語区切りには **ハイフン**（`-`）を使い、アンダースコアやスペースは使わない +- 名前は記述的かつ簡潔に保つ + +--- + +## ドキュメント構造 + +### ルート README + +ルート `README.md` は以下の順序に従う： + +1. ロゴ（ダーク／ライト両対応の `` 要素） +2. H1 タイトル +3. 導入のブロッククォート（1 行のバリュープロポジション） +4. "Why This Guide?" セクションと比較テーブル +5. 水平線（`---`） +6. 目次 +7. 機能カタログ +8. クイックナビゲーション +9. 学習パス +10. 機能セクション +11. はじめに +12. ベストプラクティス／トラブルシューティング +13. コントリビュート／ライセンス + +### レッスン README + +各レッスン `README.md` は以下の順序に従う： + +1. H1 タイトル（例：`# Slash Commands`） +2. 簡潔な概要段落 +3. クイックリファレンステーブル（任意） +4. アーキテクチャ図（Mermaid） +5. 詳細セクション（H2） +6. 実践例（番号付き、4〜6 個） +7. ベストプラクティス（Do と Don't のテーブル） +8. トラブルシューティング +9. 関連ガイド／公式ドキュメント +10. ドキュメントメタデータのフッタ + +### 機能／サンプルファイル + +個別の機能ファイル（例：`optimize.md`、`pr.md`）： + +1. YAML フロントマター（該当する場合） +2. H1 タイトル +3. 目的／説明 +4. 使用方法 +5. コード例 +6. カスタマイズのヒント + +### セクション区切り + +主要なドキュメント領域を区切るために水平線（`---`）を使う： + +```markdown +--- + +## 新しい主要セクション +``` + +導入のブロッククォートの後と、論理的に異なる部分の間に配置する。 + +--- + +## 見出し + +### 階層 + +| レベル | 用途 | 例 | +|-------|-----|---------| +| `#` H1 | ページタイトル（1 ドキュメントに 1 つ） | `# Slash Commands` | +| `##` H2 | 主要セクション | `## Best Practices` | +| `###` H3 | サブセクション | `### Adding a Skill` | +| `####` H4 | サブサブセクション（まれ） | `#### Configuration Options` | + +### ルール + +- **1 ドキュメントに H1 は 1 つ** — ページタイトルだけ +- **レベルを飛ばさない** — H2 から H4 へ飛ばない +- **見出しは簡潔に** — 2〜5 語が目安 +- **センテンスケースを使う** — 最初の単語と固有名詞のみ大文字（例外：機能名はそのまま） +- **絵文字プレフィックスはルート README のセクションヘッダにのみ追加**（[絵文字の使い方](#絵文字の使い方)を参照） + +--- + +## テキストフォーマット + +### 強調 + +| スタイル | いつ使うか | 例 | +|-------|------------|---------| +| **ボールド**（`**text**`） | 重要な用語、テーブル内のラベル、重要概念 | `**Installation**:` | +| *イタリック*（`*text*`） | 専門用語の初出、書籍／文書のタイトル | `*frontmatter*` | +| `コード`（`` `text` ``） | ファイル名、コマンド、設定値、コード参照 | `` `CLAUDE.md` `` | + +### コールアウト用ブロッククォート + +重要な注意にはボールドプレフィックス付きのブロッククォートを使う： + +```markdown +> **Note**: Custom slash commands have been merged into skills since v2.0. + +> **Important**: Never commit API keys or credentials. + +> **Tip**: Combine memory with skills for maximum effectiveness. +``` + +サポートするコールアウトの種類：**Note**、**Important**、**Tip**、**Warning**。 + +### 段落 + +- 段落は短く保つ（2〜4 文） +- 段落の間に空行を入れる +- 重要点を先に、コンテキストは後に +- 「何を」だけでなく「なぜ」を説明する + +--- + +## リスト + +### 番号なしリスト + +ダッシュ（`-`）と 2 スペースのインデントでネストする： + +```markdown +- 最初の項目 +- 2 番目の項目 + - ネスト項目 + - もう 1 つのネスト項目 + - 深いネスト（3 階層より深くしない） +- 3 番目の項目 +``` + +### 番号付きリスト + +順序のあるステップ、手順、ランク付け項目には番号付きリストを使う： + +```markdown +1. 最初のステップ +2. 2 番目のステップ + - サブポイントの詳細 + - もう 1 つのサブポイント +3. 3 番目のステップ +``` + +### 説明型リスト + +キー・バリュー形式のリストにはボールドラベルを使う： + +```markdown +- **パフォーマンスのボトルネック** - O(n^2) の操作、非効率なループを特定する +- **メモリリーク** - 解放されていないリソース、循環参照を発見する +- **アルゴリズム改善** - よりよいアルゴリズムやデータ構造を提案する +``` + +### ルール + +- 一貫したインデントを保つ（1 階層につき 2 スペース） +- リストの前後に空行を入れる +- リスト項目は構造を揃える（すべて動詞で始める、またはすべて名詞、など） +- 3 階層より深いネストは避ける + +--- + +## テーブル + +### 標準フォーマット + +```markdown +| Column 1 | Column 2 | Column 3 | +|----------|----------|----------| +| Data | Data | Data | +``` + +### よくあるテーブルパターン + +**機能比較（3〜4 列）：** + +```markdown +| Feature | Invocation | Persistence | Best For | +|---------|-----------|------------|----------| +| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts | +| **Memory** | Auto-loaded | Cross-session | Long-term learning | +``` + +**Do と Don't：** + +```markdown +| Do | Don't | +|----|-------| +| Use descriptive names | Use vague names | +| Keep files focused | Overload a single file | +``` + +**クイックリファレンス：** + +```markdown +| Aspect | Details | +|--------|---------| +| **Purpose** | Generate API documentation | +| **Scope** | Project-level | +| **Complexity** | Intermediate | +``` + +### ルール + +- **テーブルヘッダをボールドにする** — 行ラベル（最初の列）の場合 +- ソースの可読性のためにパイプを揃える（任意だが推奨） +- セルの内容は簡潔に保つ。詳細はリンクで +- セル内のコマンドやファイルパスには `code formatting` を使う + +--- + +## コードブロック + +### 言語タグ + +シンタックスハイライトのために必ず言語タグを指定する： + +| 言語 | タグ | 用途 | +|----------|-----|---------| +| シェル | `bash` | CLI コマンド、スクリプト | +| Python | `python` | Python コード | +| JavaScript | `javascript` | JS コード | +| TypeScript | `typescript` | TS コード | +| JSON | `json` | 設定ファイル | +| YAML | `yaml` | フロントマター、設定 | +| Markdown | `markdown` | Markdown の例 | +| SQL | `sql` | データベースクエリ | +| プレーンテキスト | （タグなし） | 期待される出力、ディレクトリツリー | + +### 規約 + +```bash +# コマンドの動作を説明するコメント +claude mcp add notion --transport http https://mcp.notion.com/mcp +``` + +- 自明でないコマンドの前に **コメント行** を追加する +- すべての例を **コピー＆ペースト可能** にする +- 関連するときは **シンプル版と高度版の両方** を示す +- 理解の助けとなる場合は **期待される出力** を含める（タグなしのコードブロックを使う） + +### インストールブロック + +インストール手順には以下のパターンを使う： + +```bash +# プロジェクトにファイルをコピー +cp 01-slash-commands/*.md .claude/commands/ +``` + +### 複数ステップのワークフロー + +```bash +# Step 1: ディレクトリを作成 +mkdir -p .claude/commands + +# Step 2: テンプレートをコピー +cp 01-slash-commands/*.md .claude/commands/ + +# Step 3: インストールを確認 +ls .claude/commands/ +``` + +--- + +## リンクと相互参照 + +### 内部リンク（相対） + +すべての内部リンクは相対パスを使う： + +```markdown +[Slash Commands](01-slash-commands/) +[Skills Guide](03-skills/) +[Memory Architecture](02-memory/#memory-architecture) +``` + +レッスンフォルダからルートまたは兄弟へ： + +```markdown +[Back to main guide](../README.md) +[Related: Skills](../03-skills/) +``` + +### 外部リンク（絶対） + +説明的なアンカーテキストを伴う完全 URL を使う： + +```markdown +[Anthropic's official documentation](https://code.claude.com/docs/en/overview) +``` + +- アンカーテキストに「click here」「this link」を使わない +- 文脈外でも意味が通る記述的なテキストを使う + +### セクションアンカー + +GitHub スタイルのアンカーで同一文書内のセクションへリンクする： + +```markdown +[Feature Catalog](#-feature-catalog) +[Best Practices](#best-practices) +``` + +### 関連ガイドのパターン + +レッスンの末尾に関連ガイドのセクションを置く： + +```markdown +## Related Guides + +- [Slash Commands](../01-slash-commands/) - Quick shortcuts +- [Memory](../02-memory/) - Persistent context +- [Skills](../03-skills/) - Reusable capabilities +``` + +--- + +## 図 + +### Mermaid + +すべての図に Mermaid を使う。サポートする種類： + +- `graph TB` / `graph LR` — アーキテクチャ、階層、フロー +- `sequenceDiagram` — インタラクションフロー +- `timeline` — 時系列 + +### スタイル規約 + +スタイルブロックで一貫した色を適用する： + +```mermaid +graph TB + A["Component A"] --> B["Component B"] + B --> C["Component C"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#fce4ec,stroke:#333,color:#333 + style C fill:#e8f5e9,stroke:#333,color:#333 +``` + +**カラーパレット：** + +| 色 | Hex | 用途 | +|-------|-----|---------| +| ライトブルー | `#e1f5fe` | 主要コンポーネント、入力 | +| ライトピンク | `#fce4ec` | 処理、ミドルウェア | +| ライトグリーン | `#e8f5e9` | 出力、結果 | +| ライトイエロー | `#fff9c4` | 設定、任意 | +| ライトパープル | `#f3e5f5` | ユーザー向け、UI | + +### ルール + +- ノードラベルには `["Label text"]` を使う（特殊文字を許可） +- ラベル内の改行には `
` を使う +- 図はシンプルに保つ（最大 10〜12 ノード） +- アクセシビリティのため図の下に簡潔なテキスト説明を追加する +- 階層には上から下（`TB`）、ワークフローには左から右（`LR`）を使う + +--- + +## 絵文字の使い方 + +### 絵文字を使う場所 + +絵文字は **控えめかつ目的を持って** 使う — 特定のコンテキストでのみ： + +| コンテキスト | 絵文字 | 例 | +|---------|--------|---------| +| ルート README のセクションヘッダ | カテゴリアイコン | `## 📚 Learning Path` | +| スキルレベル指標 | 色付き丸 | 🟢 初心者、🔵 中級者、🔴 上級者 | +| Do と Don't | チェック／クロスマーク | ✅ こうする、❌ こうしない | +| 複雑さ評価 | 星 | ⭐⭐⭐ | + +### 標準絵文字セット + +| 絵文字 | 意味 | +|-------|---------| +| 📚 | 学習、ガイド、ドキュメント | +| ⚡ | はじめに、クイックリファレンス | +| 🎯 | 機能、クイックリファレンス | +| 🎓 | 学習パス | +| 📊 | 統計、比較 | +| 🚀 | インストール、クイックコマンド | +| 🟢 | 初心者レベル | +| 🔵 | 中級者レベル | +| 🔴 | 上級者レベル | +| ✅ | 推奨される慣行 | +| ❌ | 避ける／アンチパターン | +| ⭐ | 複雑さ評価の単位 | + +### ルール + +- **本文や段落で絵文字を使わない** +- ヘッダで絵文字を使うのは **ルート README のみ**（レッスン README では使わない） +- **装飾的な絵文字を追加しない** — どの絵文字も意味を伝えるべき +- 絵文字の使い方は上記の表と一貫させる + +--- + +## YAML フロントマター + +### 機能ファイル（スキル、コマンド、エージェント） + +```yaml +--- +name: unique-identifier +description: What this feature does and when to use it +allowed-tools: Bash, Read, Grep +--- +``` + +### 任意フィールド + +```yaml +--- +name: my-feature +description: Brief description +argument-hint: "[file-path] [options]" +allowed-tools: Bash, Read, Grep, Write, Edit +model: opus # opus, sonnet, または haiku +disable-model-invocation: true # ユーザー専用の起動 +user-invocable: false # ユーザーメニューから隠す +context: fork # 隔離されたサブエージェントで実行 +agent: Explore # context: fork のエージェント種別 +--- +``` + +### ルール + +- フロントマターはファイルの最上部に置く +- `name` フィールドは **kebab-case** を使う +- `description` は 1 文に保つ +- 必要なフィールドのみを含める + +--- + +## 画像とメディア + +### ロゴパターン + +ロゴで始まる文書はすべて、ダーク／ライトモード対応のために `` 要素を使う： + +```html + + + Claude How To + +``` + +### スクリーンショット + +- 関連するレッスンフォルダに保存する（例：`01-slash-commands/pr-slash-command.png`） +- ファイル名に kebab-case を使う +- 説明的な alt テキストを含める +- 図には SVG、スクリーンショットには PNG を優先する + +### ルール + +- 画像には常に alt テキストを提供する +- 画像のファイルサイズを適切に保つ（PNG は 500KB 未満） +- 画像参照には相対パスを使う +- 画像は参照する文書と同じディレクトリ、または共有画像なら `assets/` に保存する + +--- + +## トーンと声 + +### 執筆スタイル + +- **プロフェッショナルだが親しみやすく** — 専門用語の過多なしに技術的に正確 +- **能動態** — 「ファイルを作成する」（「ファイルが作成されるべき」ではない） +- **直接的な指示** — 「このコマンドを実行する」（「このコマンドを実行したいかもしれない」ではない） +- **初心者にやさしく** — 読者は Claude Code に新しい人だが、プログラミングに新しい人ではないと仮定 + +### コンテンツの原則 + +| 原則 | 例 | +|-----------|---------| +| **見せる、語らない** | 抽象的な記述ではなく、動くサンプルを提供する | +| **段階的な複雑さ** | シンプルから始め、後のセクションで深さを加える | +| **「なぜ」を説明する** | 「メモリは…のために使う」だけでなく「メモリは…なぜなら…」 | +| **コピー＆ペーストで動く** | すべてのコードブロックは貼り付けるだけで動くべき | +| **実世界のコンテキスト** | わざとらしい例ではなく実用的なシナリオを使う | + +### 語彙 + +- 「Claude Code」を使う（「Claude CLI」や「the tool」ではない） +- 「skill」を使う（「custom command」ではない — 旧称） +- 番号付きセクションには「lesson」または「guide」を使う +- 個別の機能ファイルには「example」を使う + +--- + +## コミットメッセージ + +[Conventional Commits](https://www.conventionalcommits.org/) に従う： + +``` +type(scope): description +``` + +### 種別 + +| 種別 | 用途 | +|------|---------| +| `feat` | 新機能、サンプル、ガイド | +| `fix` | バグ修正、訂正、リンク切れ | +| `docs` | ドキュメント改善 | +| `refactor` | 動作を変えない再構築 | +| `style` | フォーマット変更のみ | +| `test` | テスト追加・変更 | +| `chore` | ビルド、依存関係、CI | + +### スコープ + +スコープにはレッスン名やファイル領域を使う： + +``` +feat(slash-commands): Add API documentation generator +docs(memory): Improve personal preferences example +fix(README): Correct table of contents link +docs(skills): Add comprehensive code review skill +``` + +--- + +## ドキュメントメタデータのフッタ + +レッスン README はメタデータブロックで終わる： + +```markdown +--- +**Last Updated**: March 2026 +**Claude Code Version**: 2.1.97 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 +``` + +- 月＋年の形式を使う（例：「March 2026」） +- 機能変更時にバージョンを更新する +- 互換モデルをすべてリストする + +--- + +## 著者向けチェックリスト + +コンテンツを提出する前に確認する： + +- [ ] ファイル／フォルダ名が kebab-case +- [ ] 文書が H1 タイトルで始まる（1 ファイルに 1 つ） +- [ ] 見出し階層が正しい（レベルの飛ばしなし） +- [ ] すべてのコードブロックに言語タグがある +- [ ] コード例がコピー＆ペーストで動く +- [ ] 内部リンクは相対パス +- [ ] 外部リンクには記述的なアンカーテキスト +- [ ] テーブルが正しくフォーマットされている +- [ ] 絵文字は標準セットに従う（使う場合） +- [ ] Mermaid 図は標準カラーパレットを使う +- [ ] 機微な情報（API キー、認証情報）が含まれない +- [ ] YAML フロントマターが妥当（該当する場合） +- [ ] 画像に alt テキストがある +- [ ] 段落が短く焦点が絞られている +- [ ] 関連ガイドのセクションが関連レッスンへリンクする +- [ ] コミットメッセージが Conventional Commits 形式に従う + +--- + +**Last Updated**: April 24, 2026 +**Claude Code Version**: 2.1.119 +**Sources**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/changelog +- https://www.anthropic.com/news/claude-opus-4-7 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/ja/TRANSLATION_NOTES.md b/ja/TRANSLATION_NOTES.md new file mode 100644 index 0000000..8a913c3 --- /dev/null +++ b/ja/TRANSLATION_NOTES.md @@ -0,0 +1,423 @@ +# 翻訳用語集とスタイルガイド + +# Translation Glossary & Style Guide + +> **重要：** 本書は Claude Code ドキュメントを日本語へ翻訳する際のルールを定める。作業開始前に必ず読むこと。 + +## 基本方針 + +- **文体：** だ・である調（常体） +- **用語方針：** カタカナ寄り（IT 業界で定着済みのカタカナ語を優先） +- **コード保持：** 実行コードは 100% 維持。コメント・docstring のみ翻訳 +- **Mermaid 図：** ラベルテキストは英語のまま維持 +- **原典追従：** 各ファイル先頭に `i18n-source-sha` を埋め込み、再同期可能にする + +--- + +## 技術用語集 + +全ファイルで統一するための対訳表： + +| English | 日本語 | 備考 | +|---------|--------|------| +| slash command | スラッシュコマンド | Claude Code の機能名 | +| hook | フック | IT 業界で定着 | +| skill | スキル | Claude Code の機能名 | +| subagent | サブエージェント | Claude Code の機能名 | +| agent | エージェント | 一般的なカタカナ表記 | +| memory | メモリ | Claude Code の機能名（記憶領域の意味） | +| checkpoint | チェックポイント | セッションのスナップショット | +| plugin | プラグイン | 一般用語 | +| pull request / PR | プルリクエスト / PR | GitHub 用語 | +| commit | コミット | Git 用語 | +| branch | ブランチ | Git 用語 | +| merge | マージ | Git 用語 | +| MCP (Model Context Protocol) | MCP | プロトコル名はそのまま | +| CLAUDE.md | CLAUDE.md | ファイル名はそのまま | +| prompt | プロンプト | 定着したカタカナ | +| workflow | ワークフロー | 定着したカタカナ | +| repository | リポジトリ | Git 用語 | +| issue | Issue | GitHub 用語、原文表記 | +| release | リリース | 定着したカタカナ | +| API | API | そのまま | +| CLI | CLI | Command-Line Interface、そのまま | +| CI/CD | CI/CD | そのまま | +| pre-commit hook | pre-commit フック | ツール名は維持 | +| environment variable | 環境変数 | 訳語が定着 | +| dependencies | 依存関係 | 訳語が定着 | +| template | テンプレート | カタカナ | +| worktree | ワークツリー | Git 用語、カタカナ化 | +| frontmatter | フロントマター | YAML 先頭ブロック | +| token | トークン | カタカナ | +| context window | コンテキストウィンドウ | カタカナ | +| fork | フォーク | Git 用語 | +| clone | クローン（する） | Git 用語 | +| sandbox | サンドボックス | カタカナ | +| boilerplate | ボイラープレート | カタカナ | +| debugging | デバッグ | カタカナ | +| linting | リンティング | カタカナ | +| refactoring | リファクタリング | カタカナ | +| build | ビルド | カタカナ | +| deploy | デプロイ | カタカナ | +| feature | 機能 | 文脈に応じて「フィーチャー」も可 | +| user | ユーザー | カタカナ | +| developer | 開発者 | 訳語が定着 | +| documentation | ドキュメント / ドキュメンテーション | 短縮形「ドキュメント」を優先 | +| roadmap | ロードマップ | カタカナ | +| ecosystem | エコシステム | カタカナ | +| orchestration | オーケストレーション | カタカナ | +| permission | 権限 / パーミッション | 文脈に応じて | +| settings | 設定 | 訳語が定着 | +| configuration | 設定 / コンフィグ | 短縮形「設定」を優先 | +| trigger | トリガー | カタカナ | +| event | イベント | カタカナ | +| script | スクリプト | カタカナ | +| handler | ハンドラ | カタカナ | +| wrapper | ラッパー | カタカナ | +| middleware | ミドルウェア | カタカナ | +| pipeline | パイプライン | カタカナ | +| best practice | ベストプラクティス | カタカナ | +| use case | ユースケース | カタカナ | +| trade-off | トレードオフ | カタカナ | + +--- + +## Claude Code 固有名詞（絶対変更不可） + +以下は Claude Code の **製品名・機能名** であり、**訳さず英語表記のまま** 維持する： + +| 表記 | 種別 | 補足 | +|------|------|------| +| Claude | 製品名 | カタカナ「クロード」にしない | +| Claude Code | 製品名 | そのまま | +| Anthropic | 会社名 | そのまま | +| CLAUDE.md | ファイル名 | 大文字維持 | +| SKILL.md | ファイル名 | 大文字維持 | +| MCP / Model Context Protocol | プロトコル名 | 略語使用、初出は併記 | +| `.claude/` | ディレクトリ名 | そのまま | +| `~/.claude/` | パス | そのまま | +| `claude.ai` / `claude.com` / `code.claude.com` | URL | そのまま | +| Sonnet / Opus / Haiku | モデル名 | カタカナにしない | + +ただし、**機能カテゴリ** は日本語化する（カタカナ寄り）： + +| English | 日本語 | 備考 | +|---------|--------|------| +| Slash Commands（機能名） | スラッシュコマンド | 見出しでも翻訳する | +| Memory（機能名） | メモリ | 「記憶」とは訳さない | +| Skills（機能名） | スキル | そのまま | +| Subagents（機能名） | サブエージェント | 「副エージェント」NG | +| Hooks（機能名） | フック | そのまま | +| Plugins（機能名） | プラグイン | そのまま | +| Checkpoints（機能名） | チェックポイント | そのまま | +| Advanced Features（カテゴリ） | 高度な機能 | 訳す | +| CLI Reference（カテゴリ） | CLI リファレンス | 訳す | + +--- + +## モジュール名の取り扱い + +各モジュールの見出し・URL での扱い： + +| 原典の見出し | 日本語訳 | URL（変更しない） | +|-----------|--------|--------------| +| 01 Slash Commands | スラッシュコマンド | `01-slash-commands/` | +| 02 Memory | メモリ | `02-memory/` | +| 03 Skills | スキル | `03-skills/` | +| 04 Subagents | サブエージェント | `04-subagents/` | +| 05 MCP | MCP | `05-mcp/` | +| 06 Hooks | フック | `06-hooks/` | +| 07 Plugins | プラグイン | `07-plugins/` | +| 08 Checkpoints | チェックポイント | `08-checkpoints/` | +| 09 Advanced Features | 高度な機能 | `09-advanced-features/` | +| 10 CLI | CLI | `10-cli/` | + +**重要：** ディレクトリ名・ファイルパスは絶対に変更しない。日本語化するのは見出し・本文中の言及のみ。 + +--- + +## 翻訳ルール + +### 1. コードとコマンド + +**黄金ルール：** 実行可能コードは 100% 保持する。翻訳するのはコメントと説明文のみ。 + +**正しい例（✅）：** + +````markdown +このコマンドを実行するには： + +```bash +/optimize +``` + +このコマンドはコードを解析する。 +```` + +**誤った例（❌）：** + +````markdown +このコマンドを実行するには： + +```bash +/最適化 # コマンド名は絶対に翻訳しない +``` +```` + +### 2. コード内コメント + +コメントは日本語に翻訳する： + +```python +# ✅ 正しい — コメントを翻訳 +# このスラッシュコマンドはコードを最適化する +def optimize_code(): + pass + +# ❌ 誤り — 関数名は翻訳しない +def 最適化_コード(): # 関数名は変更しない + pass +``` + +### 3. 関数名・変数名・クラス名 + +英語のまま維持する： + +```python +# ✅ 正しい +def create_subagent(name: str, system_prompt: str): + pass + +# ❌ 誤り +def サブエージェント作成(名前: str, システムプロンプト: str): + pass +``` + +### 4. Mermaid 図 + +**100% そのまま維持する。** mermaid ブロック内のテキストは一切翻訳しない。 + +````markdown + +```mermaid +graph TD + A[ユーザー] --> B[エージェント] +``` + + +```mermaid +graph TD + A[User] --> B[Agent] +``` +```` + +**重要：** Mermaid のコメントは `%%` を使う。`#` はパーサエラーになる。 + +````markdown + +```mermaid +graph TD + %% これは Mermaid のコメント + A[User] --> B[Agent] +``` + + +```text +graph TD + # これはパーサを壊す！ + A[User] --> B[Agent] +``` +```` + +### 5. ファイルパスと URL + +そのまま維持する： + +```markdown + +設定については `.claude/settings.json` を参照。 + + +設定については `.claude/設定.json` を参照。 +``` + +### 6. テーブル + +構造（列・行数）はそのまま維持する。テキスト内容は翻訳し、技術的な値はそのままにする： + +```markdown +| コマンド | 説明 | 例 | +|---------|------|-----| +| `/help` | ヘルプを表示 | `/help memory` | +| `/clear` | セッションをクリア | `/clear` | +``` + +### 7. ファイル間リンク + +`ja/` 内では相対パスを使う： + +```markdown + +[メモリ](../02-memory/) + + +[English version](../../README.md) + + +[`format-code.sh`](../../06-hooks/format-code.sh) +``` + +### 8. バージョントラッキング用フロントマター + +各翻訳ファイルの先頭に、原典のバージョン追跡用 HTML コメントを付ける： + +```markdown + + + + +# 翻訳されたファイルの見出し +``` + +SHA は元になった英語ファイルの短縮コミットハッシュ。取得方法：`git log --oneline -1 -- <英語ファイルへのパス>`。 + +### 9. 文体ルール + +- **基本文体：** だ・である調（常体）。例：「〜である」「〜する」「〜だ」 +- **読者への呼びかけ：** 「あなた」は使わず、命令形か「〜できる」「〜してほしい」を使う +- **見出し・箇条書き：** 体言止め可（「インストール」「設定方法」など） +- **本文：** 常体で統一 +- **冗長表現を避ける：** 「実行する」 > 「実行を行う」 +- **技術略語：** 初出時は「正式名称（略語）」、以降は略語のみ +- **数字：** 半角数字を使用（10 個、3 ステップなど） +- **句読点：** 「、」と「。」を使用（「，」「．」は使わない） +- **括弧：** 全角（）を使うが、コード内は半角 () + +### 10. 「ですます」と「である」の境界 + +- **本文・説明：** である調 + - 「この機能は CLAUDE.md ファイルから設定を読み込む」 +- **箇条書きの末尾：** 体言止めまたは常体 + - 「インストール手順」「メモリの管理方法」 +- **コードのコメント内：** である調 or 簡潔な体言止め + - `# このフックはコミット前に実行される` +- **見出し：** 体言止めまたは疑問形 + - 「## はじめに」「## なぜ必要か」 + +--- + +## DO / DON'T + +### ✅ DO：説明文を翻訳する + +```markdown +スラッシュコマンドは、Claude の対話セッション中の動作を制御するショートカットである。 +``` + +### ✅ DO：コード内のコメントを翻訳する + +```python +# ✅ 正しい +# この関数は新しいサブエージェントを作成する +def create_subagent(): + pass +``` + +### ❌ DON'T：関数名を翻訳しない + +```python +# ❌ 誤り +def サブエージェント作成(): + pass + +# ✅ 正しい +def create_subagent(): + pass +``` + +### ❌ DON'T：Mermaid 図を翻訳しない + +````markdown + +```mermaid +graph TD + A[ユーザー] --> B[エージェント] +``` + + +```mermaid +graph TD + A[User] --> B[Agent] +``` +```` + +### ❌ DON'T：機械翻訳を無検証で使わない + +機械翻訳（Google 翻訳、DeepL など）は以下の問題を起こしやすい： + +- 技術用語の誤訳 +- コードの文脈を理解しない +- コマンドの意味を歪める +- Markdown 書式を壊す + +**機械翻訳の後は必ず人手でチェック・編集すること。** + +### ❌ DON'T：コミットメッセージ例を翻訳しない + +Conventional Commits 形式は規約のため、英語のまま維持する： + +```markdown + +- `feat(slash-commands): Add API documentation generator` + + +- `機能追加(slash-commands): API ドキュメント生成機能を追加` +``` + +### ❌ DON'T：CLI 出力例を翻訳しない + +実際のコマンド出力を示している例は、英語のまま維持する（再現性のため）： + +```text +✅ 正しい： +$ claude --version +2.1.119 + +❌ 誤り： +$ claude --version +バージョン 2.1.119 +``` + +--- + +## コミット前チェックリスト + +- [ ] 技術的正確性が保たれている +- [ ] 日本語として自然に読める +- [ ] 用語が glossary と一致している +- [ ] コードは 100% そのまま（変更なし） +- [ ] Mermaid 図は変更されていない +- [ ] 内部リンクが機能する +- [ ] 外部リンクが保持されている +- [ ] Markdown 書式が正しい +- [ ] コード内コメントが翻訳されている +- [ ] 関数名・変数名・クラス名は英語のまま +- [ ] ファイルパスと URL は変更なし +- [ ] フロントマター `i18n-source-sha` を追加済み +- [ ] pre-commit チェックがすべて通る + +--- + +## 困ったとき + +翻訳中に疑問が生じたら： + +1. 本書の glossary を確認 +2. 他モジュールの類似ファイルがどう訳されているか確認 +3. `uk/`、`vi/`、`zh/` の対応ファイルを参照 +4. 必要なら GitHub Issue を立てて議論 + +--- + +**最終更新：** 2026-04-27 +**言語：** 日本語（ja-JP） diff --git a/ja/claude_concepts_guide.md b/ja/claude_concepts_guide.md new file mode 100644 index 0000000..19f3657 --- /dev/null +++ b/ja/claude_concepts_guide.md @@ -0,0 +1,3161 @@ + + + + + + + Claude How To + + +# Claude コンセプト完全ガイド + +スラッシュコマンド、サブエージェント、メモリ、MCP プロトコル、Agent Skills を、表・図・実例とともに包括的にまとめたリファレンスガイドである。 + +--- + +## 目次 + +1. [スラッシュコマンド](#スラッシュコマンド) +2. [サブエージェント](#サブエージェント) +3. [メモリ](#メモリ) +4. [MCP プロトコル](#mcp-プロトコル) +5. [Agent Skills](#agent-skills) +6. [プラグイン](#claude-code-プラグイン) +7. [フック](#フック) +8. [チェックポイントと巻き戻し](#チェックポイントと巻き戻し) +9. [高度な機能](#高度な機能) +10. [比較と統合](#比較と統合) + +--- + +## スラッシュコマンド + +### 概要 + +スラッシュコマンドは、ユーザーが呼び出すショートカットであり、Claude Code が実行できる Markdown ファイルとして保存される。チーム内で頻繁に使うプロンプトやワークフローを標準化するために用いる。 + +### アーキテクチャ + +```mermaid +graph TD + A["User Input: /command-name"] -->|Triggers| B["Search .claude/commands/"] + B -->|Finds| C["command-name.md"] + C -->|Loads| D["Markdown Content"] + D -->|Executes| E["Claude Processes Prompt"] + E -->|Returns| F["Result in Context"] +``` + +### ファイル構造 + +```mermaid +graph LR + A["Project Root"] -->|contains| B[".claude/commands/"] + B -->|contains| C["optimize.md"] + B -->|contains| D["test.md"] + B -->|contains| E["docs/"] + E -->|contains| F["generate-api-docs.md"] + E -->|contains| G["generate-readme.md"] +``` + +### コマンド配置の比較 + +| 配置場所 | スコープ | 利用可能範囲 | ユースケース | Git 管理 | +|----------|-------|--------------|----------|-------------| +| `.claude/commands/` | プロジェクト固有 | チームメンバー | チームのワークフロー、共有標準 | ✅ あり | +| `~/.claude/commands/` | 個人 | ユーザー個人 | プロジェクト横断の個人ショートカット | ❌ なし | +| サブディレクトリ | 名前空間付き | 親ディレクトリに従う | カテゴリ別整理 | ✅ あり | + +### 機能と利用シーン + +| 機能 | 例 | 対応 | +|---------|---------|-----------| +| シェルスクリプト実行 | `bash scripts/deploy.sh` | ✅ あり | +| ファイル参照 | `@path/to/file.js` | ✅ あり | +| Bash 統合 | `$(git log --oneline)` | ✅ あり | +| 引数 | `/pr --verbose` | ✅ あり | +| MCP コマンド | `/mcp__github__list_prs` | ✅ あり | + +### 実例 + +#### 例 1：コード最適化コマンド + +**ファイル：** `.claude/commands/optimize.md` + +```markdown +--- +name: Code Optimization +description: Analyze code for performance issues and suggest optimizations +tags: performance, analysis +--- + +# Code Optimization + +Review the provided code for the following issues in order of priority: + +1. **Performance bottlenecks** - identify O(n²) operations, inefficient loops +2. **Memory leaks** - find unreleased resources, circular references +3. **Algorithm improvements** - suggest better algorithms or data structures +4. **Caching opportunities** - identify repeated computations +5. **Concurrency issues** - find race conditions or threading problems + +Format your response with: +- Issue severity (Critical/High/Medium/Low) +- Location in code +- Explanation +- Recommended fix with code example +``` + +**使い方：** +```bash +# Claude Code に入力 +/optimize + +# Claude がプロンプトを読み込み、コード入力を待つ +``` + +#### 例 2：プルリクエスト補助コマンド + +**ファイル：** `.claude/commands/pr.md` + +```markdown +--- +name: Prepare Pull Request +description: Clean up code, stage changes, and prepare a pull request +tags: git, workflow +--- + +# Pull Request Preparation Checklist + +Before creating a PR, execute these steps: + +1. Run linting: `prettier --write .` +2. Run tests: `npm test` +3. Review git diff: `git diff HEAD` +4. Stage changes: `git add .` +5. Create commit message following conventional commits: + - `fix:` for bug fixes + - `feat:` for new features + - `docs:` for documentation + - `refactor:` for code restructuring + - `test:` for test additions + - `chore:` for maintenance + +6. Generate PR summary including: + - What changed + - Why it changed + - Testing performed + - Potential impacts +``` + +**使い方：** +```bash +/pr + +# Claude がチェックリストを実行し PR を準備する +``` + +#### 例 3：階層型ドキュメント生成コマンド + +**ファイル：** `.claude/commands/docs/generate-api-docs.md` + +```markdown +--- +name: Generate API Documentation +description: Create comprehensive API documentation from source code +tags: documentation, api +--- + +# API Documentation Generator + +Generate API documentation by: + +1. Scanning all files in `/src/api/` +2. Extracting function signatures and JSDoc comments +3. Organizing by endpoint/module +4. Creating markdown with examples +5. Including request/response schemas +6. Adding error documentation + +Output format: +- Markdown file in `/docs/api.md` +- Include curl examples for all endpoints +- Add TypeScript types +``` + +### コマンドのライフサイクル図 + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant FS as File System + participant CLI as Shell/Bash + + User->>Claude: Types /optimize + Claude->>FS: Searches .claude/commands/ + FS-->>Claude: Returns optimize.md + Claude->>Claude: Loads Markdown content + Claude->>User: Displays prompt context + User->>Claude: Provides code to analyze + Claude->>CLI: (May execute scripts) + CLI-->>Claude: Results + Claude->>User: Returns analysis +``` + +### ベストプラクティス + +| ✅ 推奨 | ❌ 非推奨 | +|------|---------| +| 明確で動作指向の名前を付ける | 一度しか使わない作業をコマンド化する | +| description にトリガー語を記述する | コマンド内に複雑なロジックを組み込む | +| 1 タスクに焦点を絞る | 重複したコマンドを作る | +| プロジェクトコマンドはバージョン管理する | 機密情報をハードコードする | +| サブディレクトリで整理する | 長大なコマンド一覧を作る | +| シンプルで読みやすいプロンプトを書く | 略語や難解な表現を使う | + +--- + +## サブエージェント + +### 概要 + +サブエージェントは、独立したコンテキストウィンドウとカスタマイズされたシステムプロンプトを持つ専門 AI アシスタントである。関心の分離を保ったままタスクの委譲を可能にする。 + +### アーキテクチャ図 + +```mermaid +graph TB + User["👤 User"] + Main["🎯 Main Agent
(Coordinator)"] + Reviewer["🔍 Code Reviewer
Subagent"] + Tester["✅ Test Engineer
Subagent"] + Docs["📝 Documentation
Subagent"] + + User -->|asks| Main + Main -->|delegates| Reviewer + Main -->|delegates| Tester + Main -->|delegates| Docs + Reviewer -->|returns result| Main + Tester -->|returns result| Main + Docs -->|returns result| Main + Main -->|synthesizes| User +``` + +### サブエージェントのライフサイクル + +```mermaid +sequenceDiagram + participant User + participant MainAgent as Main Agent + participant CodeReviewer as Code Reviewer
Subagent + participant Context as Separate
Context Window + + User->>MainAgent: "Build new auth feature" + MainAgent->>MainAgent: Analyze task + MainAgent->>CodeReviewer: "Review this code" + CodeReviewer->>Context: Initialize clean context + Context->>CodeReviewer: Load reviewer instructions + CodeReviewer->>CodeReviewer: Perform review + CodeReviewer-->>MainAgent: Return findings + MainAgent->>MainAgent: Incorporate results + MainAgent-->>User: Provide synthesis +``` + +### サブエージェント設定項目 + +| 設定項目 | 型 | 用途 | 例 | +|---------------|------|---------|---------| +| `name` | 文字列 | エージェントの識別子 | `code-reviewer` | +| `description` | 文字列 | 用途とトリガー語 | `Comprehensive code quality analysis` | +| `tools` | リスト / 文字列 | 利用可能なツール | `read, grep, diff, lint_runner` | +| `system_prompt` | Markdown | 振る舞いの指示 | カスタムガイドライン | + +### ツールアクセスの階層 + +```mermaid +graph TD + A["Subagent Configuration"] -->|Option 1| B["Inherit All Tools
from Main Thread"] + A -->|Option 2| C["Specify Individual Tools"] + B -->|Includes| B1["File Operations"] + B -->|Includes| B2["Shell Commands"] + B -->|Includes| B3["MCP Tools"] + C -->|Explicit List| C1["read, grep, diff"] + C -->|Explicit List| C2["Bash(npm:*), Bash(test:*)"] +``` + +### 実例 + +#### 例 1：完全なサブエージェント設定 + +**ファイル：** `.claude/agents/code-reviewer.md` + +```yaml +--- +name: code-reviewer +description: Comprehensive code quality and maintainability analysis +tools: read, grep, diff, lint_runner +--- + +# Code Reviewer Agent + +You are an expert code reviewer specializing in: +- Performance optimization +- Security vulnerabilities +- Code maintainability +- Testing coverage +- Design patterns + +## Review Priorities (in order) + +1. **Security Issues** - Authentication, authorization, data exposure +2. **Performance Problems** - O(n²) operations, memory leaks, inefficient queries +3. **Code Quality** - Readability, naming, documentation +4. **Test Coverage** - Missing tests, edge cases +5. **Design Patterns** - SOLID principles, architecture + +## Review Output Format + +For each issue: +- **Severity**: Critical / High / Medium / Low +- **Category**: Security / Performance / Quality / Testing / Design +- **Location**: File path and line number +- **Issue Description**: What's wrong and why +- **Suggested Fix**: Code example +- **Impact**: How this affects the system + +## Example Review + +### Issue: N+1 Query Problem +- **Severity**: High +- **Category**: Performance +- **Location**: src/user-service.ts:45 +- **Issue**: Loop executes database query in each iteration +- **Fix**: Use JOIN or batch query +``` + +**ファイル：** `.claude/agents/test-engineer.md` + +```yaml +--- +name: test-engineer +description: Test strategy, coverage analysis, and automated testing +tools: read, write, bash, grep +--- + +# Test Engineer Agent + +You are expert at: +- Writing comprehensive test suites +- Ensuring high code coverage (>80%) +- Testing edge cases and error scenarios +- Performance benchmarking +- Integration testing + +## Testing Strategy + +1. **Unit Tests** - Individual functions/methods +2. **Integration Tests** - Component interactions +3. **End-to-End Tests** - Complete workflows +4. **Edge Cases** - Boundary conditions +5. **Error Scenarios** - Failure handling + +## Test Output Requirements + +- Use Jest for JavaScript/TypeScript +- Include setup/teardown for each test +- Mock external dependencies +- Document test purpose +- Include performance assertions when relevant + +## Coverage Requirements + +- Minimum 80% code coverage +- 100% for critical paths +- Report missing coverage areas +``` + +**ファイル：** `.claude/agents/documentation-writer.md` + +```yaml +--- +name: documentation-writer +description: Technical documentation, API docs, and user guides +tools: read, write, grep +--- + +# Documentation Writer Agent + +You create: +- API documentation with examples +- User guides and tutorials +- Architecture documentation +- Changelog entries +- Code comment improvements + +## Documentation Standards + +1. **Clarity** - Use simple, clear language +2. **Examples** - Include practical code examples +3. **Completeness** - Cover all parameters and returns +4. **Structure** - Use consistent formatting +5. **Accuracy** - Verify against actual code + +## Documentation Sections + +### For APIs +- Description +- Parameters (with types) +- Returns (with types) +- Throws (possible errors) +- Examples (curl, JavaScript, Python) +- Related endpoints + +### For Features +- Overview +- Prerequisites +- Step-by-step instructions +- Expected outcomes +- Troubleshooting +- Related topics +``` + +#### 例 2：サブエージェント委譲の実例 + +```markdown +# シナリオ：決済機能の構築 + +## ユーザーリクエスト +「Stripe と統合した安全な決済処理機能を構築してほしい」 + +## メインエージェントのフロー + +1. **計画フェーズ** + - 要件を理解する + - 必要なタスクを特定する + - アーキテクチャを設計する + +2. **コードレビュアー サブエージェントへ委譲** + - タスク：「決済処理の実装をセキュリティ観点でレビューせよ」 + - コンテキスト：認証、API キー、トークン処理 + - レビュー対象：SQL インジェクション、キー漏洩、HTTPS 強制 + +3. **テストエンジニア サブエージェントへ委譲** + - タスク：「決済フローの包括的なテストを作成せよ」 + - コンテキスト：成功・失敗・エッジケース + - 作成するテスト：正常決済、カード拒否、ネットワーク障害、Webhook + +4. **ドキュメントライター サブエージェントへ委譲** + - タスク：「決済 API エンドポイントを文書化せよ」 + - コンテキスト：リクエスト・レスポンスのスキーマ + - 成果物：curl 例とエラーコード付きの API ドキュメント + +5. **統合** + - メインエージェントが全ての出力を集約する + - 結果を統合する + - 完成したソリューションをユーザーに返す +``` + +#### 例 3：ツール権限のスコープ設定 + +**制限的な設定 — 特定コマンドのみ許可** + +```yaml +--- +name: secure-reviewer +description: Security-focused code review with minimal permissions +tools: read, grep +--- + +# Secure Code Reviewer + +Reviews code for security vulnerabilities only. + +This agent: +- ✅ Reads files to analyze +- ✅ Searches for patterns +- ❌ Cannot execute code +- ❌ Cannot modify files +- ❌ Cannot run tests + +This ensures the reviewer doesn't accidentally break anything. +``` + +**拡張設定 — 実装用に全ツールを許可** + +```yaml +--- +name: implementation-agent +description: Full implementation capabilities for feature development +tools: read, write, bash, grep, edit, glob +--- + +# Implementation Agent + +Builds features from specifications. + +This agent: +- ✅ Reads specifications +- ✅ Writes new code files +- ✅ Runs build commands +- ✅ Searches codebase +- ✅ Edits existing files +- ✅ Finds files matching patterns + +Full capabilities for independent feature development. +``` + +### サブエージェントのコンテキスト管理 + +```mermaid +graph TB + A["Main Agent Context
50,000 tokens"] + B["Subagent 1 Context
20,000 tokens"] + C["Subagent 2 Context
20,000 tokens"] + D["Subagent 3 Context
20,000 tokens"] + + A -->|Clean slate| B + A -->|Clean slate| C + A -->|Clean slate| D + + B -->|Results only| A + C -->|Results only| A + D -->|Results only| A + + style A fill:#e1f5ff + style B fill:#fff9c4 + style C fill:#fff9c4 + style D fill:#fff9c4 +``` + +### サブエージェントを使うべき場面 + +| シナリオ | サブエージェント利用 | 理由 | +|----------|--------------|-----| +| 多段階の複雑な機能 | ✅ あり | 関心を分離し、コンテキストの汚染を防ぐ | +| 簡単なコードレビュー | ❌ なし | オーバーヘッドに見合わない | +| 並列タスク実行 | ✅ あり | 各サブエージェントが独立したコンテキストを持つ | +| 専門知識が必要 | ✅ あり | カスタムシステムプロンプトを使える | +| 長時間の解析 | ✅ あり | メインコンテキストの枯渇を防ぐ | +| 単一タスク | ❌ なし | 不要なレイテンシを生む | + +### Agent Teams + +Agent Teams は、関連するタスクに取り組む複数のエージェントを協調動作させる。1 つずつサブエージェントへ委譲するのではなく、メインエージェントが複数のエージェント群をオーケストレーションし、中間結果を共有しつつ共通のゴールへ向かわせる。フロントエンドエージェント・バックエンドエージェント・テストエージェントが並行して動くフルスタック機能開発のような大規模タスクで有効である。 + +--- + +## メモリ + +### 概要 + +メモリは、セッションや会話をまたいで Claude にコンテキストを保持させる仕組みである。形式は 2 種類あり、claude.ai での自動合成と、Claude Code でのファイルシステムベース CLAUDE.md である。 + +### メモリのアーキテクチャ + +```mermaid +graph TB + A["Claude Session"] + B["User Input"] + C["Memory System"] + D["Memory Storage"] + + B -->|User provides info| C + C -->|Synthesizes every 24h| D + D -->|Loads automatically| A + A -->|Uses context| C +``` + +### Claude Code のメモリ階層（7 層） + +Claude Code は 7 層からメモリを読み込む。優先度の高い順に： + +```mermaid +graph TD + A["1. Managed Policy
Enterprise admin policies"] --> B["2. Project Memory
./CLAUDE.md"] + B --> C["3. Project Rules
.claude/rules/*.md"] + C --> D["4. User Memory
~/.claude/CLAUDE.md"] + D --> E["5. User Rules
~/.claude/rules/*.md"] + E --> F["6. Local Memory
.claude/local/CLAUDE.md"] + F --> G["7. Auto Memory
Automatically captured preferences"] + + style A fill:#fce4ec,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 + style G fill:#fff3e0,stroke:#333,color:#333 +``` + +### メモリ配置一覧 + +| 階層 | 配置場所 | スコープ | 優先度 | 共有 | 用途 | +|------|----------|-------|----------|--------|----------| +| 1. Managed Policy | エンタープライズ管理者 | 組織 | 最高 | 組織内全員 | コンプライアンス、セキュリティポリシー | +| 2. Project | `./CLAUDE.md` | プロジェクト | 高 | チーム（Git） | チーム標準、アーキテクチャ | +| 3. Project Rules | `.claude/rules/*.md` | プロジェクト | 高 | チーム（Git） | プロジェクト規約のモジュール化 | +| 4. User | `~/.claude/CLAUDE.md` | 個人 | 中 | 個人 | 個人の好み | +| 5. User Rules | `~/.claude/rules/*.md` | 個人 | 中 | 個人 | 個人ルールのモジュール化 | +| 6. Local | `.claude/local/CLAUDE.md` | ローカル | 低 | 共有しない | マシン固有設定 | +| 7. Auto Memory | 自動 | セッション | 最低 | 個人 | 学習された好み・パターン | + +### Auto Memory + +Auto Memory は、セッション中に観察されたユーザーの好みやパターンを自動的に取り込む。Claude はやり取りから学習し、次のような情報を覚える： + +- コーディングスタイルの好み +- ユーザーがよく行う訂正 +- フレームワーク・ツールの選択 +- コミュニケーションスタイルの好み + +Auto Memory はバックグラウンドで動き、手動の設定は不要である。 + +### メモリ更新のライフサイクル + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Editor as File System + participant Memory as CLAUDE.md + + User->>Claude: "Remember: use async/await" + Claude->>User: "Which memory file?" + User->>Claude: "Project memory" + Claude->>Editor: Open ~/.claude/settings.json + Claude->>Memory: Write to ./CLAUDE.md + Memory-->>Claude: File saved + Claude->>Claude: Load updated memory + Claude-->>User: "Memory saved!" +``` + +### 実例 + +#### 例 1：プロジェクトメモリの構造 + +**ファイル：** `./CLAUDE.md` + +```markdown +# Project Configuration + +## Project Overview +- **Name**: E-commerce Platform +- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker +- **Team Size**: 5 developers +- **Deadline**: Q4 2025 + +## Architecture +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## Development Standards + +### Code Style +- Use Prettier for formatting +- Use ESLint with airbnb config +- Maximum line length: 100 characters +- Use 2-space indentation + +### Naming Conventions +- **Files**: kebab-case (user-controller.js) +- **Classes**: PascalCase (UserService) +- **Functions/Variables**: camelCase (getUserById) +- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL) +- **Database Tables**: snake_case (user_accounts) + +### Git Workflow +- Branch names: `feature/description` or `fix/description` +- Commit messages: Follow conventional commits +- PR required before merge +- All CI/CD checks must pass +- Minimum 1 approval required + +### Testing Requirements +- Minimum 80% code coverage +- All critical paths must have tests +- Use Jest for unit tests +- Use Cypress for E2E tests +- Test filenames: `*.test.ts` or `*.spec.ts` + +### API Standards +- RESTful endpoints only +- JSON request/response +- Use HTTP status codes correctly +- Version API endpoints: `/api/v1/` +- Document all endpoints with examples + +### Database +- Use migrations for schema changes +- Never hardcode credentials +- Use connection pooling +- Enable query logging in development +- Regular backups required + +### Deployment +- Docker-based deployment +- Kubernetes orchestration +- Blue-green deployment strategy +- Automatic rollback on failure +- Database migrations run before deploy + +## Common Commands + +| Command | Purpose | +|---------|---------| +| `npm run dev` | Start development server | +| `npm test` | Run test suite | +| `npm run lint` | Check code style | +| `npm run build` | Build for production | +| `npm run migrate` | Run database migrations | + +## Team Contacts +- Tech Lead: Sarah Chen (@sarah.chen) +- Product Manager: Mike Johnson (@mike.j) +- DevOps: Alex Kim (@alex.k) + +## Known Issues & Workarounds +- PostgreSQL connection pooling limited to 20 during peak hours +- Workaround: Implement query queuing +- Safari 14 compatibility issues with async generators +- Workaround: Use Babel transpiler + +## Related Projects +- Analytics Dashboard: `/projects/analytics` +- Mobile App: `/projects/mobile` +- Admin Panel: `/projects/admin` +``` + +#### 例 2：ディレクトリ別メモリ + +**ファイル：** `./src/api/CLAUDE.md` + +~~~~markdown +# API Module Standards + +This file overrides root CLAUDE.md for everything in /src/api/ + +## API-Specific Standards + +### Request Validation +- Use Zod for schema validation +- Always validate input +- Return 400 with validation errors +- Include field-level error details + +### Authentication +- All endpoints require JWT token +- Token in Authorization header +- Token expires after 24 hours +- Implement refresh token mechanism + +### Response Format + +All responses must follow this structure: + +```json +{ + "success": true, + "data": { /* actual data */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +### Error responses: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "User message", + "details": { /* field errors */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### Pagination +- Use cursor-based pagination (not offset) +- Include `hasMore` boolean +- Limit max page size to 100 +- Default page size: 20 + +### Rate Limiting +- 1000 requests per hour for authenticated users +- 100 requests per hour for public endpoints +- Return 429 when exceeded +- Include retry-after header + +### Caching +- Use Redis for session caching +- Cache duration: 5 minutes default +- Invalidate on write operations +- Tag cache keys with resource type +~~~~ + +#### 例 3：個人メモリ + +**ファイル：** `~/.claude/CLAUDE.md` + +~~~~markdown +# My Development Preferences + +## About Me +- **Experience Level**: 8 years full-stack development +- **Preferred Languages**: TypeScript, Python +- **Communication Style**: Direct, with examples +- **Learning Style**: Visual diagrams with code + +## Code Preferences + +### Error Handling +I prefer explicit error handling with try-catch blocks and meaningful error messages. +Avoid generic errors. Always log errors for debugging. + +### Comments +Use comments for WHY, not WHAT. Code should be self-documenting. +Comments should explain business logic or non-obvious decisions. + +### Testing +I prefer TDD (test-driven development). +Write tests first, then implementation. +Focus on behavior, not implementation details. + +### Architecture +I prefer modular, loosely-coupled design. +Use dependency injection for testability. +Separate concerns (Controllers, Services, Repositories). + +## Debugging Preferences +- Use console.log with prefix: `[DEBUG]` +- Include context: function name, relevant variables +- Use stack traces when available +- Always include timestamps in logs + +## Communication +- Explain complex concepts with diagrams +- Show concrete examples before explaining theory +- Include before/after code snippets +- Summarize key points at the end + +## Project Organization +I organize my projects as: +``` +project/ + ├── src/ + │ ├── api/ + │ ├── services/ + │ ├── models/ + │ └── utils/ + ├── tests/ + ├── docs/ + └── docker/ +``` + +## Tooling +- **IDE**: VS Code with vim keybindings +- **Terminal**: Zsh with Oh-My-Zsh +- **Format**: Prettier (100 char line length) +- **Linter**: ESLint with airbnb config +- **Test Framework**: Jest with React Testing Library +~~~~ + +#### 例 4：セッション中のメモリ更新 + +**セッション中のやり取り：** + +```markdown +User: Remember that I prefer using React hooks instead of class components + for all new components. + +Claude: I'm adding that to your memory. Which memory file should this go in? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: ✅ Memory saved! + +Added to ./CLAUDE.md: +--- + +### Component Development +- Use functional components with React Hooks +- Prefer hooks over class components +- Custom hooks for reusable logic +- Use useCallback for event handlers +- Use useMemo for expensive computations +``` + +### Claude Web / Desktop でのメモリ + +#### メモリ合成のタイムライン + +```mermaid +graph LR + A["Day 1: User
Conversations"] -->|24 hours| B["Day 2: Memory
Synthesis"] + B -->|Automatic| C["Memory Updated
Summarized"] + C -->|Loaded in| D["Day 2-N:
New Conversations"] + D -->|Add to| E["Memory"] + E -->|24 hours later| F["Memory Refreshed"] +``` + +**メモリ要約の例：** + +```markdown +## Claude's Memory of User + +### Professional Background +- Senior full-stack developer with 8 years experience +- Focus on TypeScript/Node.js backends and React frontends +- Active open source contributor +- Interested in AI and machine learning + +### Project Context +- Currently building e-commerce platform +- Tech stack: Node.js, PostgreSQL, React 18, Docker +- Working with team of 5 developers +- Using CI/CD and blue-green deployments + +### Communication Preferences +- Prefers direct, concise explanations +- Likes visual diagrams and examples +- Appreciates code snippets +- Explains business logic in comments + +### Current Goals +- Improve API performance +- Increase test coverage to 90% +- Implement caching strategy +- Document architecture +``` + +### メモリ機能の比較 + +| 機能 | Claude Web / Desktop | Claude Code（CLAUDE.md） | +|---------|-------------------|------------------------| +| 自動合成 | ✅ 24 時間ごと | ❌ 手動 | +| プロジェクト横断 | ✅ 共有 | ❌ プロジェクト固有 | +| チームアクセス | ✅ 共有プロジェクト | ✅ Git 管理 | +| 検索可能 | ✅ 標準機能 | ✅ `/memory` 経由 | +| 編集可能 | ✅ チャット内 | ✅ ファイル直接編集 | +| インポート / エクスポート | ✅ 可 | ✅ コピー & ペースト | +| 永続性 | ✅ 24 時間以上 | ✅ 無期限 | + +--- + +## MCP プロトコル + +### 概要 + +MCP（Model Context Protocol）は、Claude が外部ツール・API・リアルタイムデータソースへアクセスするための標準化された方式である。メモリと違い、MCP は変化するデータへのライブアクセスを提供する。 + +### MCP のアーキテクチャ + +```mermaid +graph TB + A["Claude"] + B["MCP Server"] + C["External Service"] + + A -->|Request: list_issues| B + B -->|Query| C + C -->|Data| B + B -->|Response| A + + A -->|Request: create_issue| B + B -->|Action| C + C -->|Result| B + B -->|Response| A +``` + +### MCP のエコシステム + +```mermaid +graph TB + A["Claude"] -->|MCP| B["Filesystem
MCP Server"] + A -->|MCP| C["GitHub
MCP Server"] + A -->|MCP| D["Database
MCP Server"] + A -->|MCP| E["Slack
MCP Server"] + A -->|MCP| F["Google Docs
MCP Server"] + + B -->|File I/O| G["Local Files"] + C -->|API| H["GitHub Repos"] + D -->|Query| I["PostgreSQL/MySQL"] + E -->|Messages| J["Slack Workspace"] + F -->|Docs| K["Google Drive"] +``` + +### MCP のセットアップ手順 + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Config as Config File + participant Service as External Service + + User->>Claude: Type /mcp + Claude->>Claude: List available MCP servers + Claude->>User: Show options + User->>Claude: Select GitHub MCP + Claude->>Config: Update configuration + Config->>Claude: Activate connection + Claude->>Service: Test connection + Service-->>Claude: Authentication successful + Claude->>User: ✅ MCP connected! +``` + +### 利用可能な MCP サーバー一覧 + +| MCP サーバー | 用途 | 主なツール | 認証 | リアルタイム | +|------------|---------|--------------|------|-----------| +| **Filesystem** | ファイル操作 | read, write, delete | OS 権限 | ✅ あり | +| **GitHub** | リポジトリ管理 | list_prs, create_issue, push | OAuth | ✅ あり | +| **Slack** | チームコミュニケーション | send_message, list_channels | トークン | ✅ あり | +| **Database** | SQL クエリ | query, insert, update | 認証情報 | ✅ あり | +| **Google Docs** | ドキュメントアクセス | read, write, share | OAuth | ✅ あり | +| **Asana** | プロジェクト管理 | create_task, update_status | API キー | ✅ あり | +| **Stripe** | 決済データ | list_charges, create_invoice | API キー | ✅ あり | +| **Memory** | 永続メモリ | store, retrieve, delete | ローカル | ❌ なし | + +### 実例 + +#### 例 1：GitHub MCP の設定 + +**ファイル：** `.mcp.json`（プロジェクトスコープ）または `~/.claude.json`（ユーザースコープ） + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**利用可能な GitHub MCP ツール：** + +~~~~markdown +# GitHub MCP Tools + +## Pull Request Management +- `list_prs` - List all PRs in repository +- `get_pr` - Get PR details including diff +- `create_pr` - Create new PR +- `update_pr` - Update PR description/title +- `merge_pr` - Merge PR to main branch +- `review_pr` - Add review comments + +Example request: +``` +/mcp__github__get_pr 456 + +# Returns: +Title: Add dark mode support +Author: @alice +Description: Implements dark theme using CSS variables +Status: OPEN +Reviewers: @bob, @charlie +``` + +## Issue Management +- `list_issues` - List all issues +- `get_issue` - Get issue details +- `create_issue` - Create new issue +- `close_issue` - Close issue +- `add_comment` - Add comment to issue + +## Repository Information +- `get_repo_info` - Repository details +- `list_files` - File tree structure +- `get_file_content` - Read file contents +- `search_code` - Search across codebase + +## Commit Operations +- `list_commits` - Commit history +- `get_commit` - Specific commit details +- `create_commit` - Create new commit +~~~~ + +#### 例 2：Database MCP の設定 + +**設定：** + +```json +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} +``` + +**利用例：** + +```markdown +User: Fetch all users with more than 10 orders + +Claude: I'll query your database to find that information. + +# Using MCP database tool: +SELECT u.*, COUNT(o.id) as order_count +FROM users u +LEFT JOIN orders o ON u.id = o.user_id +GROUP BY u.id +HAVING COUNT(o.id) > 10 +ORDER BY order_count DESC; + +# Results: +- Alice: 15 orders +- Bob: 12 orders +- Charlie: 11 orders +``` + +#### 例 3：複数 MCP を組み合わせたワークフロー + +**シナリオ：日次レポートの生成** + +```markdown +# Daily Report Workflow using Multiple MCPs + +## Setup +1. GitHub MCP - fetch PR metrics +2. Database MCP - query sales data +3. Slack MCP - post report +4. Filesystem MCP - save report + +## Workflow + +### Step 1: Fetch GitHub Data +/mcp__github__list_prs completed:true last:7days + +Output: +- Total PRs: 42 +- Average merge time: 2.3 hours +- Review turnaround: 1.1 hours + +### Step 2: Query Database +SELECT COUNT(*) as sales, SUM(amount) as revenue +FROM orders +WHERE created_at > NOW() - INTERVAL '1 day' + +Output: +- Sales: 247 +- Revenue: $12,450 + +### Step 3: Generate Report +Combine data into HTML report + +### Step 4: Save to Filesystem +Write report.html to /reports/ + +### Step 5: Post to Slack +Send summary to #daily-reports channel + +Final Output: +✅ Report generated and posted +📊 47 PRs merged this week +💰 $12,450 in daily sales +``` + +#### 例 4：Filesystem MCP の操作 + +**設定：** + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} +``` + +**利用可能な操作：** + +| 操作 | コマンド | 用途 | +|-----------|---------|---------| +| ファイル一覧 | `ls ~/projects` | ディレクトリ内容を表示 | +| ファイル読み込み | `cat src/main.ts` | 内容を読む | +| ファイル作成 | `create docs/api.md` | 新規ファイル作成 | +| ファイル編集 | `edit src/app.ts` | ファイルを変更 | +| 検索 | `grep "async function"` | ファイル内検索 | +| 削除 | `rm old-file.js` | ファイル削除 | + +### MCP vs メモリ：判断マトリクス + +```mermaid +graph TD + A["Need external data?"] + A -->|No| B["Use Memory"] + A -->|Yes| C["Does it change frequently?"] + C -->|No/Rarely| B + C -->|Yes/Often| D["Use MCP"] + + B -->|Stores| E["Preferences
Context
History"] + D -->|Accesses| F["Live APIs
Databases
Services"] + + style B fill:#e1f5ff + style D fill:#fff9c4 +``` + +### リクエスト・レスポンスのパターン + +```mermaid +sequenceDiagram + participant App as Claude + participant MCP as MCP Server + participant DB as Database + + App->>MCP: Request: "SELECT * FROM users WHERE id=1" + MCP->>DB: Execute query + DB-->>MCP: Result set + MCP-->>App: Return parsed data + App->>App: Process result + App->>App: Continue task + + Note over MCP,DB: Real-time access
No caching +``` + +--- + +## Agent Skills + +### 概要 + +Agent Skills は、命令・スクリプト・リソースをフォルダに同梱した、再利用可能でモデルが自律的に呼び出す能力である。Claude は関連するスキルを自動検出して利用する。 + +### スキルのアーキテクチャ + +```mermaid +graph TB + A["Skill Directory"] + B["SKILL.md"] + C["YAML Metadata"] + D["Instructions"] + E["Scripts"] + F["Templates"] + + A --> B + B --> C + B --> D + E --> A + F --> A +``` + +### スキルの読み込み手順 + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude + participant System as System + participant Skill as Skill + + User->>Claude: "Create Excel report" + Claude->>System: Scan available skills + System->>System: Load skill metadata + Claude->>Claude: Match user request to skills + Claude->>Skill: Load xlsx skill SKILL.md + Skill-->>Claude: Return instructions + tools + Claude->>Claude: Execute skill + Claude->>User: Generate Excel file +``` + +### スキルの種類と配置 + +| 種類 | 配置場所 | スコープ | 共有 | 同期 | 用途 | +|------|----------|-------|--------|------|----------| +| プリビルト | 組み込み | グローバル | 全ユーザー | 自動 | ドキュメント生成 | +| 個人 | `~/.claude/skills/` | 個人 | なし | 手動 | 個人の自動化 | +| プロジェクト | `.claude/skills/` | チーム | あり | Git | チーム標準 | +| プラグイン | プラグイン経由 | 状況による | 状況による | 自動 | 統合機能 | + +### プリビルトスキル + +```mermaid +graph TB + A["Pre-built Skills"] + B["PowerPoint (pptx)"] + C["Excel (xlsx)"] + D["Word (docx)"] + E["PDF"] + + A --> B + A --> C + A --> D + A --> E + + B --> B1["Create presentations"] + B --> B2["Edit slides"] + C --> C1["Create spreadsheets"] + C --> C2["Analyze data"] + D --> D1["Create documents"] + D --> D2["Format text"] + E --> E1["Generate PDFs"] + E --> E2["Fill forms"] +``` + +### 同梱スキル + +Claude Code には標準で 5 つの同梱スキルが含まれる： + +| スキル | コマンド | 用途 | +|-------|---------|---------| +| **Simplify** | `/simplify` | 複雑なコードや説明を単純化 | +| **Batch** | `/batch` | 複数ファイル・項目に対する一括操作 | +| **Debug** | `/debug` | 根本原因分析を伴う体系的デバッグ | +| **Loop** | `/loop` | タイマーで定期実行 | +| **Claude API** | `/claude-api` | Anthropic API への直接アクセス | + +これらの同梱スキルは常に利用可能であり、インストールや設定は不要である。 + +### 実例 + +#### 例 1：カスタムコードレビュースキル + +**ディレクトリ構成：** + +``` +~/.claude/skills/code-review/ +├── SKILL.md +├── templates/ +│ ├── review-checklist.md +│ └── finding-template.md +└── scripts/ + ├── analyze-metrics.py + └── compare-complexity.py +``` + +**ファイル：** `~/.claude/skills/code-review/SKILL.md` + +```yaml +--- +name: Code Review Specialist +description: Comprehensive code review with security, performance, and quality analysis +version: "1.0.0" +tags: + - code-review + - quality + - security +when_to_use: When users ask to review code, analyze code quality, or evaluate pull requests +effort: high +shell: bash +--- + +# Code Review Skill + +This skill provides comprehensive code review capabilities focusing on: + +1. **Security Analysis** + - Authentication/authorization issues + - Data exposure risks + - Injection vulnerabilities + - Cryptographic weaknesses + - Sensitive data logging + +2. **Performance Review** + - Algorithm efficiency (Big O analysis) + - Memory optimization + - Database query optimization + - Caching opportunities + - Concurrency issues + +3. **Code Quality** + - SOLID principles + - Design patterns + - Naming conventions + - Documentation + - Test coverage + +4. **Maintainability** + - Code readability + - Function size (should be < 50 lines) + - Cyclomatic complexity + - Dependency management + - Type safety + +## Review Template + +For each piece of code reviewed, provide: + +### Summary +- Overall quality assessment (1-5) +- Key findings count +- Recommended priority areas + +### Critical Issues (if any) +- **Issue**: Clear description +- **Location**: File and line number +- **Impact**: Why this matters +- **Severity**: Critical/High/Medium +- **Fix**: Code example + +### Findings by Category + +#### Security (if issues found) +List security vulnerabilities with examples + +#### Performance (if issues found) +List performance problems with complexity analysis + +#### Quality (if issues found) +List code quality issues with refactoring suggestions + +#### Maintainability (if issues found) +List maintainability problems with improvements +``` + +## Python スクリプト：analyze-metrics.py + +```python +#!/usr/bin/env python3 +import re +import sys + +def analyze_code_metrics(code): + """コードの一般的なメトリクスを解析する。""" + + # 関数数をカウント + functions = len(re.findall(r'^def\s+\w+', code, re.MULTILINE)) + + # クラス数をカウント + classes = len(re.findall(r'^class\s+\w+', code, re.MULTILINE)) + + # 平均行長 + lines = code.split('\n') + avg_length = sum(len(l) for l in lines) / len(lines) if lines else 0 + + # 複雑度の概算 + complexity = len(re.findall(r'\b(if|elif|else|for|while|and|or)\b', code)) + + return { + 'functions': functions, + 'classes': classes, + 'avg_line_length': avg_length, + 'complexity_score': complexity + } + +if __name__ == '__main__': + with open(sys.argv[1], 'r') as f: + code = f.read() + metrics = analyze_code_metrics(code) + for key, value in metrics.items(): + print(f"{key}: {value:.2f}") +``` + +## Python スクリプト：compare-complexity.py + +```python +#!/usr/bin/env python3 +""" +変更前後でコードのサイクロマティック複雑度を比較する。 +リファクタリングが実際に構造を単純化しているか確認するのに役立つ。 +""" + +import re +import sys +from typing import Dict, Tuple + +class ComplexityAnalyzer: + """コードの複雑度メトリクスを解析する。""" + + def __init__(self, code: str): + self.code = code + self.lines = code.split('\n') + + def calculate_cyclomatic_complexity(self) -> int: + """ + McCabe の方式でサイクロマティック複雑度を計算する。 + 判定点をカウント：if, elif, else, for, while, except, and, or + """ + complexity = 1 # 基本複雑度 + + # 判定点をカウント + decision_patterns = [ + r'\bif\b', + r'\belif\b', + r'\bfor\b', + r'\bwhile\b', + r'\bexcept\b', + r'\band\b(?!$)', + r'\bor\b(?!$)' + ] + + for pattern in decision_patterns: + matches = re.findall(pattern, self.code) + complexity += len(matches) + + return complexity + + def calculate_cognitive_complexity(self) -> int: + """ + 認知的複雑度を計算する — 理解の難しさ。 + ネストの深さと制御フローに基づく。 + """ + cognitive = 0 + nesting_depth = 0 + + for line in self.lines: + # ネスト深度を追跡 + if re.search(r'^\s*(if|for|while|def|class|try)\b', line): + nesting_depth += 1 + cognitive += nesting_depth + elif re.search(r'^\s*(elif|else|except|finally)\b', line): + cognitive += nesting_depth + + # インデント解除でネストを減らす + if line and not line[0].isspace(): + nesting_depth = 0 + + return cognitive + + def calculate_maintainability_index(self) -> float: + """ + 保守性指数（0〜100）。 + > 85: 優秀 + > 65: 良好 + > 50: 普通 + < 50: 不良 + """ + lines = len(self.lines) + cyclomatic = self.calculate_cyclomatic_complexity() + cognitive = self.calculate_cognitive_complexity() + + # 簡略化した MI 計算 + mi = 171 - 5.2 * (cyclomatic / lines) - 0.23 * (cognitive) - 16.2 * (lines / 1000) + + return max(0, min(100, mi)) + + def get_complexity_report(self) -> Dict: + """包括的な複雑度レポートを生成する。""" + return { + 'cyclomatic_complexity': self.calculate_cyclomatic_complexity(), + 'cognitive_complexity': self.calculate_cognitive_complexity(), + 'maintainability_index': round(self.calculate_maintainability_index(), 2), + 'lines_of_code': len(self.lines), + 'avg_line_length': round(sum(len(l) for l in self.lines) / len(self.lines), 2) if self.lines else 0 + } + + +def compare_files(before_file: str, after_file: str) -> None: + """2 つのコードバージョンの複雑度メトリクスを比較する。""" + + with open(before_file, 'r') as f: + before_code = f.read() + + with open(after_file, 'r') as f: + after_code = f.read() + + before_analyzer = ComplexityAnalyzer(before_code) + after_analyzer = ComplexityAnalyzer(after_code) + + before_metrics = before_analyzer.get_complexity_report() + after_metrics = after_analyzer.get_complexity_report() + + print("=" * 60) + print("CODE COMPLEXITY COMPARISON") + print("=" * 60) + + print("\nBEFORE:") + print(f" Cyclomatic Complexity: {before_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {before_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {before_metrics['maintainability_index']}") + print(f" Lines of Code: {before_metrics['lines_of_code']}") + print(f" Avg Line Length: {before_metrics['avg_line_length']}") + + print("\nAFTER:") + print(f" Cyclomatic Complexity: {after_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {after_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {after_metrics['maintainability_index']}") + print(f" Lines of Code: {after_metrics['lines_of_code']}") + print(f" Avg Line Length: {after_metrics['avg_line_length']}") + + print("\nCHANGES:") + cyclomatic_change = after_metrics['cyclomatic_complexity'] - before_metrics['cyclomatic_complexity'] + cognitive_change = after_metrics['cognitive_complexity'] - before_metrics['cognitive_complexity'] + mi_change = after_metrics['maintainability_index'] - before_metrics['maintainability_index'] + loc_change = after_metrics['lines_of_code'] - before_metrics['lines_of_code'] + + print(f" Cyclomatic Complexity: {cyclomatic_change:+d}") + print(f" Cognitive Complexity: {cognitive_change:+d}") + print(f" Maintainability Index: {mi_change:+.2f}") + print(f" Lines of Code: {loc_change:+d}") + + print("\nASSESSMENT:") + if mi_change > 0: + print(" ✅ Code is MORE maintainable") + elif mi_change < 0: + print(" ⚠️ Code is LESS maintainable") + else: + print(" ➡️ Maintainability unchanged") + + if cyclomatic_change < 0: + print(" ✅ Complexity DECREASED") + elif cyclomatic_change > 0: + print(" ⚠️ Complexity INCREASED") + else: + print(" ➡️ Complexity unchanged") + + print("=" * 60) + + +if __name__ == '__main__': + if len(sys.argv) != 3: + print("Usage: python compare-complexity.py ") + sys.exit(1) + + compare_files(sys.argv[1], sys.argv[2]) +``` + +## テンプレート：review-checklist.md + +```markdown +# Code Review Checklist + +## Security Checklist +- [ ] No hardcoded credentials or secrets +- [ ] Input validation on all user inputs +- [ ] SQL injection prevention (parameterized queries) +- [ ] CSRF protection on state-changing operations +- [ ] XSS prevention with proper escaping +- [ ] Authentication checks on protected endpoints +- [ ] Authorization checks on resources +- [ ] Secure password hashing (bcrypt, argon2) +- [ ] No sensitive data in logs +- [ ] HTTPS enforced + +## Performance Checklist +- [ ] No N+1 queries +- [ ] Appropriate use of indexes +- [ ] Caching implemented where beneficial +- [ ] No blocking operations on main thread +- [ ] Async/await used correctly +- [ ] Large datasets paginated +- [ ] Database connections pooled +- [ ] Regular expressions optimized +- [ ] No unnecessary object creation +- [ ] Memory leaks prevented + +## Quality Checklist +- [ ] Functions < 50 lines +- [ ] Clear variable naming +- [ ] No duplicate code +- [ ] Proper error handling +- [ ] Comments explain WHY, not WHAT +- [ ] No console.logs in production +- [ ] Type checking (TypeScript/JSDoc) +- [ ] SOLID principles followed +- [ ] Design patterns applied correctly +- [ ] Self-documenting code + +## Testing Checklist +- [ ] Unit tests written +- [ ] Edge cases covered +- [ ] Error scenarios tested +- [ ] Integration tests present +- [ ] Coverage > 80% +- [ ] No flaky tests +- [ ] Mock external dependencies +- [ ] Clear test names +``` + +## テンプレート：finding-template.md + +~~~~markdown +# Code Review Finding Template + +Use this template when documenting each issue found during code review. + +--- + +## Issue: [TITLE] + +### Severity +- [ ] Critical (blocks deployment) +- [ ] High (should fix before merge) +- [ ] Medium (should fix soon) +- [ ] Low (nice to have) + +### Category +- [ ] Security +- [ ] Performance +- [ ] Code Quality +- [ ] Maintainability +- [ ] Testing +- [ ] Design Pattern +- [ ] Documentation + +### Location +**File:** `src/components/UserCard.tsx` + +**Lines:** 45-52 + +**Function/Method:** `renderUserDetails()` + +### Issue Description + +**What:** Describe what the issue is. + +**Why it matters:** Explain the impact and why this needs to be fixed. + +**Current behavior:** Show the problematic code or behavior. + +**Expected behavior:** Describe what should happen instead. + +### Code Example + +#### Current (Problematic) + +```typescript +// N+1 クエリ問題を示す +const users = fetchUsers(); +users.forEach(user => { + const posts = fetchUserPosts(user.id); // ユーザーごとにクエリ！ + renderUserPosts(posts); +}); +``` + +#### Suggested Fix + +```typescript +// JOIN クエリで最適化 +const usersWithPosts = fetchUsersWithPosts(); +usersWithPosts.forEach(({ user, posts }) => { + renderUserPosts(posts); +}); +``` + +### Impact Analysis + +| Aspect | Impact | Severity | +|--------|--------|----------| +| Performance | 100+ queries for 20 users | High | +| User Experience | Slow page load | High | +| Scalability | Breaks at scale | Critical | +| Maintainability | Hard to debug | Medium | + +### Related Issues + +- Similar issue in `AdminUserList.tsx` line 120 +- Related PR: #456 +- Related issue: #789 + +### Additional Resources + +- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) +- [Database Join Documentation](https://docs.example.com/joins) + +### Reviewer Notes + +- This is a common pattern in this codebase +- Consider adding this to the code style guide +- Might be worth creating a helper function + +### Author Response (for feedback) + +*To be filled by the code author:* + +- [ ] Fix implemented in commit: `abc123` +- [ ] Fix status: Complete / In Progress / Needs Discussion +- [ ] Questions or concerns: (describe) + +--- + +## Finding Statistics (for Reviewer) + +When reviewing multiple findings, track: + +- **Total Issues Found:** X +- **Critical:** X +- **High:** X +- **Medium:** X +- **Low:** X + +**Recommendation:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion + +**Overall Code Quality:** 1-5 stars +~~~~ + +## 利用例 + +~~~~markdown +User: Review this React component code + +Claude: I'll conduct a comprehensive code review using my Code Review Skill. + +[Loads SKILL.md] +[Analyzes code against checklist] +[Runs Python metrics script] +[Applies templates] + +## Code Review Results + +### Summary +Quality Score: 3.5/5 +Key Findings: 7 items +Priority Areas: Performance optimization, error handling + +### Critical Issues: 1 + +**Issue**: N+1 Query Problem +**Location**: UserComponent.tsx, lines 45-52 +**Impact**: Renders 100+ database queries for list of 20 users +**Severity**: High +**Fix**: +```javascript +// Before: N+1 queries +const users = fetchUsers(); +users.forEach(user => fetchUserPosts(user.id)); // 20+ queries + +// After: Single query with JOIN +const users = fetchUsersWithPosts(); // 1 query +``` + +### Performance Findings +- Missing pagination on large lists +- Recommendation: Use React.memo() for items +- Database query: Could be optimized with index + +### Quality Findings +- Function in line 20 is 127 lines (max: 50) +- Missing error boundary +- Props should have TypeScript types +~~~~ + +#### 例 2：ブランドボイス スキル + +**ディレクトリ構成：** + +``` +.claude/skills/brand-voice/ +├── SKILL.md +├── brand-guidelines.md +├── tone-examples.md +└── templates/ + ├── email-template.txt + ├── social-post-template.txt + └── blog-post-template.md +``` + +**ファイル：** `.claude/skills/brand-voice/SKILL.md` + +```yaml +--- +name: Brand Voice Consistency +description: Ensure all communication matches brand voice and tone guidelines +tags: + - brand + - writing + - consistency +when_to_use: When creating marketing copy, customer communications, or public-facing content +--- + +# Brand Voice Skill + +## Overview +This skill ensures all communications maintain consistent brand voice, tone, and messaging. + +## Brand Identity + +### Mission +Help teams automate their development workflows with AI + +### Values +- **Simplicity**: Make complex things simple +- **Reliability**: Rock-solid execution +- **Empowerment**: Enable human creativity + +### Tone of Voice +- **Friendly but professional** - approachable without being casual +- **Clear and concise** - avoid jargon, explain technical concepts simply +- **Confident** - we know what we're doing +- **Empathetic** - understand user needs and pain points + +## Writing Guidelines + +### Do's ✅ +- Use "you" when addressing readers +- Use active voice: "Claude generates reports" not "Reports are generated by Claude" +- Start with value proposition +- Use concrete examples +- Keep sentences under 20 words +- Use lists for clarity +- Include calls-to-action + +### Don'ts ❌ +- Don't use corporate jargon +- Don't patronize or oversimplify +- Don't use "we believe" or "we think" +- Don't use ALL CAPS except for emphasis +- Don't create walls of text +- Don't assume technical knowledge + +## Vocabulary + +### ✅ Preferred Terms +- Claude (not "the Claude AI") +- Code generation (not "auto-coding") +- Agent (not "bot") +- Streamline (not "revolutionize") +- Integrate (not "synergize") + +### ❌ Avoid Terms +- "Cutting-edge" (overused) +- "Game-changer" (vague) +- "Leverage" (corporate-speak) +- "Utilize" (use "use") +- "Paradigm shift" (unclear) +``` +## 例 + +### ✅ 良い例 +"Claude automates your code review process. Instead of manually checking each PR, Claude reviews security, performance, and quality—saving your team hours every week." + +なぜ機能するか：明確な価値、具体的なベネフィット、行動指向 + +### ❌ 悪い例 +"Claude leverages cutting-edge AI to provide comprehensive software development solutions." + +なぜダメか：曖昧、企業的ジャーゴン、具体的な価値がない + +## テンプレート：メール + +``` +Subject: [Clear, benefit-driven subject] + +Hi [Name], + +[Opening: What's the value for them] + +[Body: How it works / What they'll get] + +[Specific example or benefit] + +[Call to action: Clear next step] + +Best regards, +[Name] +``` + +## テンプレート：SNS + +``` +[Hook: Grab attention in first line] +[2-3 lines: Value or interesting fact] +[Call to action: Link, question, or engagement] +[Emoji: 1-2 max for visual interest] +``` + +## ファイル：tone-examples.md +``` +Exciting announcement: +"Save 8 hours per week on code reviews. Claude reviews your PRs automatically." + +Empathetic support: +"We know deployments can be stressful. Claude handles testing so you don't have to worry." + +Confident product feature: +"Claude doesn't just suggest code. It understands your architecture and maintains consistency." + +Educational blog post: +"Let's explore how agents improve code review workflows. Here's what we learned..." +``` + +#### 例 3：ドキュメント生成スキル + +**ファイル：** `.claude/skills/doc-generator/SKILL.md` + +~~~~yaml +--- +name: API Documentation Generator +description: Generate comprehensive, accurate API documentation from source code +version: "1.0.0" +tags: + - documentation + - api + - automation +when_to_use: When creating or updating API documentation +--- + +# API Documentation Generator Skill + +## Generates + +- OpenAPI/Swagger specifications +- API endpoint documentation +- SDK usage examples +- Integration guides +- Error code references +- Authentication guides + +## Documentation Structure + +### For Each Endpoint + +```markdown +## GET /api/v1/users/:id + +### Description +Brief explanation of what this endpoint does + +### Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| id | string | Yes | User ID | + +### Response + +**200 Success** +```json +{ + "id": "usr_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +**404 Not Found** +```json +{ + "error": "USER_NOT_FOUND", + "message": "User does not exist" +} +``` + +### Examples + +**cURL** +```bash +curl -X GET "https://api.example.com/api/v1/users/usr_123" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +**JavaScript** +```javascript +const user = await fetch('/api/v1/users/usr_123', { + headers: { 'Authorization': 'Bearer token' } +}).then(r => r.json()); +``` + +**Python** +```python +response = requests.get( + 'https://api.example.com/api/v1/users/usr_123', + headers={'Authorization': 'Bearer token'} +) +user = response.json() +``` + +## Python Script: generate-docs.py + +```python +#!/usr/bin/env python3 +import ast +import json +from typing import Dict, List + +class APIDocExtractor(ast.NodeVisitor): + """Extract API documentation from Python source code.""" + + def __init__(self): + self.endpoints = [] + + def visit_FunctionDef(self, node): + """Extract function documentation.""" + if node.name.startswith('get_') or node.name.startswith('post_'): + doc = ast.get_docstring(node) + endpoint = { + 'name': node.name, + 'docstring': doc, + 'params': [arg.arg for arg in node.args.args], + 'returns': self._extract_return_type(node) + } + self.endpoints.append(endpoint) + self.generic_visit(node) + + def _extract_return_type(self, node): + """Extract return type from function annotation.""" + if node.returns: + return ast.unparse(node.returns) + return "Any" + +def generate_markdown_docs(endpoints: List[Dict]) -> str: + """Generate markdown documentation from endpoints.""" + docs = "# API Documentation\n\n" + + for endpoint in endpoints: + docs += f"## {endpoint['name']}\n\n" + docs += f"{endpoint['docstring']}\n\n" + docs += f"**Parameters**: {', '.join(endpoint['params'])}\n\n" + docs += f"**Returns**: {endpoint['returns']}\n\n" + docs += "---\n\n" + + return docs + +if __name__ == '__main__': + import sys + with open(sys.argv[1], 'r') as f: + tree = ast.parse(f.read()) + + extractor = APIDocExtractor() + extractor.visit(tree) + + markdown = generate_markdown_docs(extractor.endpoints) + print(markdown) +~~~~ +### スキルの検出と起動 + +```mermaid +graph TD + A["User Request"] --> B["Claude Analyzes"] + B -->|Scans| C["Available Skills"] + C -->|Metadata check| D["Skill Description Match?"] + D -->|Yes| E["Load SKILL.md"] + D -->|No| F["Try next skill"] + F -->|More skills?| D + F -->|No more| G["Use general knowledge"] + E --> H["Extract Instructions"] + H --> I["Execute Skill"] + I --> J["Return Results"] +``` + +### スキルと他機能の比較 + +```mermaid +graph TB + A["Extending Claude"] + B["Slash Commands"] + C["Subagents"] + D["Memory"] + E["MCP"] + F["Skills"] + + A --> B + A --> C + A --> D + A --> E + A --> F + + B -->|User-invoked| G["Quick shortcuts"] + C -->|Auto-delegated| H["Isolated contexts"] + D -->|Persistent| I["Cross-session context"] + E -->|Real-time| J["External data access"] + F -->|Auto-invoked| K["Autonomous execution"] +``` + +--- + +## Claude Code プラグイン + +### 概要 + +Claude Code プラグインは、カスタマイズ（スラッシュコマンド、サブエージェント、MCP サーバー、フック）をひとつにまとめたパッケージで、コマンド 1 つでインストールできる。複数の機能を凝集した共有可能なパッケージにまとめる、最上位の拡張機構である。 + +### アーキテクチャ + +```mermaid +graph TB + A["Plugin"] + B["Slash Commands"] + C["Subagents"] + D["MCP Servers"] + E["Hooks"] + F["Configuration"] + + A -->|bundles| B + A -->|bundles| C + A -->|bundles| D + A -->|bundles| E + A -->|bundles| F +``` + +### プラグインの読み込み手順 + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Plugin as Plugin Marketplace + participant Install as Installation + participant SlashCmds as Slash Commands + participant Subagents + participant MCPServers as MCP Servers + participant Hooks + participant Tools as Configured Tools + + User->>Claude: /plugin install pr-review + Claude->>Plugin: Download plugin manifest + Plugin-->>Claude: Return plugin definition + Claude->>Install: Extract components + Install->>SlashCmds: Configure + Install->>Subagents: Configure + Install->>MCPServers: Configure + Install->>Hooks: Configure + SlashCmds-->>Tools: Ready to use + Subagents-->>Tools: Ready to use + MCPServers-->>Tools: Ready to use + Hooks-->>Tools: Ready to use + Tools-->>Claude: Plugin installed ✅ +``` + +### プラグインの種類と配布 + +| 種類 | スコープ | 共有 | 提供元 | 例 | +|------|-------|--------|-----------|----------| +| Official | グローバル | 全ユーザー | Anthropic | PR Review、Security Guidance | +| Community | 公開 | 全ユーザー | コミュニティ | DevOps、Data Science | +| Organization | 社内 | チームメンバー | 企業 | 社内標準・ツール | +| Personal | 個人 | 個人のみ | 開発者 | カスタムワークフロー | + +### プラグイン定義の構造 + +```yaml +--- +name: plugin-name +version: "1.0.0" +description: "What this plugin does" +author: "Your Name" +license: MIT + +# プラグインのメタデータ +tags: + - category + - use-case + +# 要件 +requires: + - claude-code: ">=1.0.0" + +# 同梱コンポーネント +components: + - type: commands + path: commands/ + - type: agents + path: agents/ + - type: mcp + path: mcp/ + - type: hooks + path: hooks/ + +# 設定 +config: + auto_load: true + enabled_by_default: true +--- +``` + +### プラグインのディレクトリ構造 + +``` +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json +├── commands/ +│ ├── task-1.md +│ ├── task-2.md +│ └── workflows/ +├── agents/ +│ ├── specialist-1.md +│ ├── specialist-2.md +│ └── configs/ +├── skills/ +│ ├── skill-1.md +│ └── skill-2.md +├── hooks/ +│ └── hooks.json +├── .mcp.json +├── .lsp.json +├── settings.json +├── templates/ +│ └── issue-template.md +├── scripts/ +│ ├── helper-1.sh +│ └── helper-2.py +├── docs/ +│ ├── README.md +│ └── USAGE.md +└── tests/ + └── plugin.test.js +``` + +### 実例 + +#### 例 1：PR レビュープラグイン + +**ファイル：** `.claude-plugin/plugin.json` + +```json +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "license": "MIT" +} +``` + +**ファイル：** `commands/review-pr.md` + +```markdown +--- +name: Review PR +description: Start comprehensive PR review with security and testing checks +--- + +# PR Review + +This command initiates a complete pull request review including: + +1. Security analysis +2. Test coverage verification +3. Documentation updates +4. Code quality checks +5. Performance impact assessment +``` + +**ファイル：** `agents/security-reviewer.md` + +```yaml +--- +name: security-reviewer +description: Security-focused code review +tools: read, grep, diff +--- + +# Security Reviewer + +Specializes in finding security vulnerabilities: +- Authentication/authorization issues +- Data exposure +- Injection attacks +- Secure configuration +``` + +**インストール：** + +```bash +/plugin install pr-review + +# 結果： +# ✅ 3 slash commands installed +# ✅ 3 subagents configured +# ✅ 2 MCP servers connected +# ✅ 4 hooks registered +# ✅ Ready to use! +``` + +#### 例 2：DevOps プラグイン + +**コンポーネント：** + +``` +devops-automation/ +├── commands/ +│ ├── deploy.md +│ ├── rollback.md +│ ├── status.md +│ └── incident.md +├── agents/ +│ ├── deployment-specialist.md +│ ├── incident-commander.md +│ └── alert-analyzer.md +├── mcp/ +│ ├── github-config.json +│ ├── kubernetes-config.json +│ └── prometheus-config.json +├── hooks/ +│ ├── pre-deploy.js +│ ├── post-deploy.js +│ └── on-error.js +└── scripts/ + ├── deploy.sh + ├── rollback.sh + └── health-check.sh +``` + +#### 例 3：ドキュメント プラグイン + +**同梱コンポーネント：** + +``` +documentation/ +├── commands/ +│ ├── generate-api-docs.md +│ ├── generate-readme.md +│ ├── sync-docs.md +│ └── validate-docs.md +├── agents/ +│ ├── api-documenter.md +│ ├── code-commentator.md +│ └── example-generator.md +├── mcp/ +│ ├── github-docs-config.json +│ └── slack-announce-config.json +└── templates/ + ├── api-endpoint.md + ├── function-docs.md + └── adr-template.md +``` + +### プラグインマーケットプレイス + +```mermaid +graph TB + A["Plugin Marketplace"] + B["Official
Anthropic"] + C["Community
Marketplace"] + D["Enterprise
Registry"] + + A --> B + A --> C + A --> D + + B -->|Categories| B1["Development"] + B -->|Categories| B2["DevOps"] + B -->|Categories| B3["Documentation"] + + C -->|Search| C1["DevOps Automation"] + C -->|Search| C2["Mobile Dev"] + C -->|Search| C3["Data Science"] + + D -->|Internal| D1["Company Standards"] + D -->|Internal| D2["Legacy Systems"] + D -->|Internal| D3["Compliance"] +``` + +### プラグインのインストールとライフサイクル + +```mermaid +graph LR + A["Discover"] -->|Browse| B["Marketplace"] + B -->|Select| C["Plugin Page"] + C -->|View| D["Components"] + D -->|Install| E["/plugin install"] + E -->|Extract| F["Configure"] + F -->|Activate| G["Use"] + G -->|Check| H["Update"] + H -->|Available| G + G -->|Done| I["Disable"] + I -->|Later| J["Enable"] + J -->|Back| G +``` + +### プラグインの機能比較 + +| 機能 | スラッシュコマンド | スキル | サブエージェント | プラグイン | +|---------|---------------|-------|----------|--------| +| **インストール** | 手動コピー | 手動コピー | 手動設定 | 1 コマンド | +| **セットアップ時間** | 5 分 | 10 分 | 15 分 | 2 分 | +| **バンドル** | 単一ファイル | 単一ファイル | 単一ファイル | 複数 | +| **バージョン管理** | 手動 | 手動 | 手動 | 自動 | +| **チーム共有** | ファイルコピー | ファイルコピー | ファイルコピー | インストール ID | +| **更新** | 手動 | 手動 | 手動 | 自動更新可 | +| **依存関係** | なし | なし | なし | 含む可能性 | +| **マーケットプレイス** | なし | なし | なし | あり | +| **配布** | リポジトリ | リポジトリ | リポジトリ | マーケットプレイス | + +### プラグインのユースケース + +| ユースケース | 推奨 | 理由 | +|----------|-----------------|-----| +| **チームのオンボーディング** | ✅ プラグイン推奨 | 即時セットアップ、設定一括 | +| **フレームワーク導入** | ✅ プラグイン推奨 | フレームワーク固有コマンドをまとめる | +| **エンタープライズ標準** | ✅ プラグイン推奨 | 中央配布、バージョン管理 | +| **簡単な作業の自動化** | ❌ コマンド推奨 | プラグインは過剰 | +| **単一ドメインの専門業務** | ❌ スキル推奨 | プラグインは重すぎる | +| **専門的な分析** | ❌ サブエージェント推奨 | 手動作成またはスキルで対応 | +| **ライブデータアクセス** | ❌ MCP 推奨 | 単独利用、バンドルしない | + +### プラグイン作成の判断 + +```mermaid +graph TD + A["Should I create a plugin?"] + A -->|Need multiple components| B{"Multiple commands
or subagents
or MCPs?"} + B -->|Yes| C["✅ Create Plugin"] + B -->|No| D["Use Individual Feature"] + A -->|Team workflow| E{"Share with
team?"} + E -->|Yes| C + E -->|No| F["Keep as Local Setup"] + A -->|Complex setup| G{"Needs auto
configuration?"} + G -->|Yes| C + G -->|No| D +``` + +### プラグインの公開 + +**公開手順：** + +1. すべてのコンポーネントを含むプラグイン構造を作る +2. `.claude-plugin/plugin.json` マニフェストを記述する +3. ドキュメント付きの `README.md` を作る +4. `/plugin install ./my-plugin` でローカルテスト +5. プラグインマーケットプレイスへ提出する +6. レビューを受けて承認される +7. マーケットプレイスで公開される +8. ユーザーは 1 コマンドでインストールできる + +**提出例：** + +~~~~markdown +# PR Review Plugin + +## Description +Complete PR review workflow with security, testing, and documentation checks. + +## What's Included +- 3 slash commands for different review types +- 3 specialized subagents +- GitHub and CodeQL MCP integration +- Automated security scanning hooks + +## Installation +```bash +/plugin install pr-review +``` + +## Features +✅ Security analysis +✅ Test coverage checking +✅ Documentation verification +✅ Code quality assessment +✅ Performance impact analysis + +## Usage +```bash +/review-pr +/check-security +/check-tests +``` + +## Requirements +- Claude Code 1.0+ +- GitHub access +- CodeQL (optional) +~~~~ + +### プラグイン vs 手動設定 + +**手動セットアップ（2 時間以上）：** +- スラッシュコマンドを 1 つずつインストール +- サブエージェントを個別に作成 +- MCP を個別に設定 +- フックを手動で設定 +- 全部を文書化 +- チームに共有（正しく設定されることを祈る） + +**プラグイン利用（2 分）：** +```bash +/plugin install pr-review +# ✅ すべてインストール・設定完了 +# ✅ 即座に使える +# ✅ チームでも完全に同じ環境を再現可能 +``` + +--- + +## 比較と統合 + +### 機能比較マトリクス + +| 機能 | 起動方法 | 永続性 | スコープ | ユースケース | +|---------|-----------|------------|-------|----------| +| **スラッシュコマンド** | 手動（`/cmd`） | セッションのみ | 単一コマンド | クイックショートカット | +| **サブエージェント** | 自動委譲 | 独立コンテキスト | 専門タスク | タスク分担 | +| **メモリ** | 自動読み込み | セッション横断 | ユーザー / チーム文脈 | 長期学習 | +| **MCP プロトコル** | 自動クエリ | リアルタイム外部 | ライブデータアクセス | 動的情報 | +| **スキル** | 自動起動 | ファイルシステム | 再利用可能な専門性 | ワークフロー自動化 | + +### 機能呼び出しのタイムライン + +```mermaid +graph LR + A["Session Start"] -->|Load| B["Memory (CLAUDE.md)"] + B -->|Discover| C["Available Skills"] + C -->|Register| D["Slash Commands"] + D -->|Connect| E["MCP Servers"] + E -->|Ready| F["User Interaction"] + + F -->|Type /cmd| G["Slash Command"] + F -->|Request| H["Skill Auto-Invoke"] + F -->|Query| I["MCP Data"] + F -->|Complex task| J["Delegate to Subagent"] + + G -->|Uses| B + H -->|Uses| B + I -->|Uses| B + J -->|Uses| B +``` + +### 統合の実例：カスタマーサポート自動化 + +#### アーキテクチャ + +```mermaid +graph TB + User["Customer Email"] -->|Receives| Router["Support Router"] + + Router -->|Analyze| Memory["Memory
Customer history"] + Router -->|Lookup| MCP1["MCP: Customer DB
Previous tickets"] + Router -->|Check| MCP2["MCP: Slack
Team status"] + + Router -->|Route Complex| Sub1["Subagent: Tech Support
Context: Technical issues"] + Router -->|Route Simple| Sub2["Subagent: Billing
Context: Payment issues"] + Router -->|Route Urgent| Sub3["Subagent: Escalation
Context: Priority handling"] + + Sub1 -->|Format| Skill1["Skill: Response Generator
Brand voice maintained"] + Sub2 -->|Format| Skill2["Skill: Response Generator"] + Sub3 -->|Format| Skill3["Skill: Response Generator"] + + Skill1 -->|Generate| Output["Formatted Response"] + Skill2 -->|Generate| Output + Skill3 -->|Generate| Output + + Output -->|Post| MCP3["MCP: Slack
Notify team"] + Output -->|Send| Reply["Customer Reply"] +``` + +#### リクエストの流れ + +```markdown +## Customer Support Request Flow + +### 1. Incoming Email +"I'm getting error 500 when trying to upload files. This is blocking my workflow!" + +### 2. Memory Lookup +- Loads CLAUDE.md with support standards +- Checks customer history: VIP customer, 3rd incident this month + +### 3. MCP Queries +- GitHub MCP: List open issues (finds related bug report) +- Database MCP: Check system status (no outages reported) +- Slack MCP: Check if engineering is aware + +### 4. Skill Detection & Loading +- Request matches "Technical Support" skill +- Loads support response template from Skill + +### 5. Subagent Delegation +- Routes to Tech Support Subagent +- Provides context: customer history, error details, known issues +- Subagent has full access to: read, bash, grep tools + +### 6. Subagent Processing +Tech Support Subagent: +- Searches codebase for 500 error in file upload +- Finds recent change in commit 8f4a2c +- Creates workaround documentation + +### 7. Skill Execution +Response Generator Skill: +- Uses Brand Voice guidelines +- Formats response with empathy +- Includes workaround steps +- Links to related documentation + +### 8. MCP Output +- Posts update to #support Slack channel +- Tags engineering team +- Updates ticket in Jira MCP + +### 9. Response +Customer receives: +- Empathetic acknowledgment +- Explanation of cause +- Immediate workaround +- Timeline for permanent fix +- Link to related issues +``` + +### 機能の総合オーケストレーション + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Memory as Memory
CLAUDE.md + participant MCP as MCP Servers + participant Skills as Skills + participant SubAgent as Subagents + + User->>Claude: Request: "Build auth system" + Claude->>Memory: Load project standards + Memory-->>Claude: Auth standards, team practices + Claude->>MCP: Query GitHub for similar implementations + MCP-->>Claude: Code examples, best practices + Claude->>Skills: Detect matching Skills + Skills-->>Claude: Security Review Skill + Testing Skill + Claude->>SubAgent: Delegate implementation + SubAgent->>SubAgent: Build feature + Claude->>Skills: Apply Security Review Skill + Skills-->>Claude: Security checklist results + Claude->>SubAgent: Delegate testing + SubAgent-->>Claude: Test results + Claude->>User: Complete system delivered +``` + +### どの機能を使うか + +```mermaid +graph TD + A["New Task"] --> B{Type of Task?} + + B -->|Repeated workflow| C["Slash Command"] + B -->|Need real-time data| D["MCP Protocol"] + B -->|Remember for next time| E["Memory"] + B -->|Specialized subtask| F["Subagent"] + B -->|Domain-specific work| G["Skill"] + + C --> C1["✅ Team shortcut"] + D --> D1["✅ Live API access"] + E --> E1["✅ Persistent context"] + F --> F1["✅ Parallel execution"] + G --> G1["✅ Auto-invoked expertise"] +``` + +### 選択フローチャート + +```mermaid +graph TD + Start["Need to extend Claude?"] + + Start -->|Quick repeated task| A{"Manual or Auto?"} + A -->|Manual| B["Slash Command"] + A -->|Auto| C["Skill"] + + Start -->|Need external data| D{"Real-time?"} + D -->|Yes| E["MCP Protocol"] + D -->|No/Cross-session| F["Memory"] + + Start -->|Complex project| G{"Multiple roles?"} + G -->|Yes| H["Subagents"] + G -->|No| I["Skills + Memory"] + + Start -->|Long-term context| J["Memory"] + Start -->|Team workflow| K["Slash Command +
Memory"] + Start -->|Full automation| L["Skills +
Subagents +
MCP"] +``` + +--- + +## サマリー一覧 + +| 観点 | スラッシュコマンド | サブエージェント | メモリ | MCP | スキル | プラグイン | +|--------|---|---|---|---|---|---| +| **セットアップ難易度** | 易 | 中 | 易 | 中 | 中 | 易 | +| **学習曲線** | 低 | 中 | 低 | 中 | 中 | 低 | +| **チーム恩恵** | 高 | 高 | 中 | 高 | 高 | 非常に高 | +| **自動化レベル** | 低 | 高 | 中 | 高 | 高 | 非常に高 | +| **コンテキスト管理** | 単一セッション | 独立 | 永続 | リアルタイム | 永続 | 全機能 | +| **保守負担** | 低 | 中 | 低 | 中 | 中 | 低 | +| **スケーラビリティ** | 良 | 優 | 良 | 優 | 優 | 優 | +| **共有性** | 普 | 普 | 良 | 良 | 良 | 優 | +| **バージョン管理** | 手動 | 手動 | 手動 | 手動 | 手動 | 自動 | +| **インストール** | 手動コピー | 手動設定 | 不要 | 手動設定 | 手動コピー | 1 コマンド | + +--- + +## クイックスタートガイド + +### 第 1 週：シンプルに始める +- よく使う作業に対しスラッシュコマンドを 2〜3 個作成する +- 設定でメモリを有効化する +- チーム標準を CLAUDE.md に文書化する + +### 第 2 週：リアルタイムアクセスを追加 +- MCP を 1 つセットアップ（GitHub または Database） +- `/mcp` で設定する +- ワークフローでライブデータをクエリする + +### 第 3 週：作業の分担 +- 特定の役割を持つサブエージェントを最初に作る +- `/agents` コマンドを使う +- 簡単なタスクで委譲をテストする + +### 第 4 週：すべてを自動化する +- 繰り返し作業に対しスキルを最初に作成する +- スキルマーケットプレイスを利用するか自作する +- 全機能を組み合わせて完全なワークフローを作る + +### 継続的に +- 月次でメモリを見直し更新する +- 新しいパターンに気付いたらスキルを追加する +- MCP クエリを最適化する +- サブエージェントのプロンプトを精緻化する + +--- + +## フック + +### 概要 + +フックは、Claude Code のイベントに反応して自動実行されるシェルコマンドである。手動操作なしに自動化・検証・カスタムワークフローを実現する。 + +### フックイベント + +Claude Code は 5 種類（command、http、mcp_tool、prompt、agent）にわたる **28 種類のフックイベント** をサポートする： + +| フックイベント | トリガー | ユースケース | +|------------|---------|-----------| +| **SessionStart** | セッション開始 / 再開 / クリア / 圧縮時 | 環境構築、初期化 | +| **InstructionsLoaded** | CLAUDE.md やルールファイル読み込み時 | 検証、変換、補強 | +| **UserPromptSubmit** | ユーザーがプロンプト送信時 | 入力検証、プロンプトフィルタ | +| **PreToolUse** | 任意のツール実行前 | 検証、承認ゲート、ログ | +| **PermissionRequest** | 権限ダイアログ表示時 | 自動承認・拒否フロー | +| **PostToolUse** | ツール成功後 | 自動整形、通知、後処理 | +| **PostToolUseFailure** | ツール実行失敗時 | エラー処理、ログ | +| **Notification** | 通知送信時 | アラート、外部連携 | +| **SubagentStart** | サブエージェント生成時 | コンテキスト注入、初期化 | +| **SubagentStop** | サブエージェント終了時 | 結果検証、ログ | +| **Stop** | Claude の応答完了時 | サマリー生成、後処理 | +| **StopFailure** | API エラーでターン終了時 | エラー回復、ログ | +| **TeammateIdle** | エージェントチームのメンバーがアイドル時 | 作業分配、調整 | +| **TaskCompleted** | タスク完了時 | 後続処理 | +| **TaskCreated** | TaskCreate でタスク作成時 | タスク追跡、ログ | +| **ConfigChange** | 設定ファイル変更時 | 検証、伝播 | +| **CwdChanged** | 作業ディレクトリ変更時 | ディレクトリ別セットアップ | +| **FileChanged** | 監視対象ファイルの変更時 | ファイル監視、再ビルド | +| **PreCompact** | コンテキスト圧縮直前 | 状態の保存 | +| **PostCompact** | 圧縮完了後 | 圧縮後の処理 | +| **WorktreeCreate** | ワークツリー作成時 | 環境構築、依存関係インストール | +| **WorktreeRemove** | ワークツリー削除時 | クリーンアップ、リソース解放 | +| **Elicitation** | MCP サーバーがユーザー入力を要求時 | 入力検証 | +| **ElicitationResult** | ユーザーが入力要求に応答時 | 応答処理 | +| **SessionEnd** | セッション終了時 | クリーンアップ、最終ログ | + +### よくあるフック + +フックは `~/.claude/settings.json`（ユーザーレベル）または `.claude/settings.json`（プロジェクトレベル）に設定する： + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write", + "hooks": [ + { + "type": "command", + "command": "prettier --write $CLAUDE_FILE_PATH" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Edit", + "hooks": [ + { + "type": "command", + "command": "eslint $CLAUDE_FILE_PATH" + } + ] + } + ] + } +} +``` + +### フック環境変数 + +- `$CLAUDE_FILE_PATH` — 編集・書き込み中のファイルパス +- `$CLAUDE_TOOL_NAME` — 使用中のツール名 +- `$CLAUDE_SESSION_ID` — 現在のセッション ID +- `$CLAUDE_PROJECT_DIR` — プロジェクトディレクトリのパス + +### ベストプラクティス + +✅ **推奨：** +- フックは高速にする（1 秒以内） +- 検証や自動化に使う +- エラーを丁寧に処理する +- 絶対パスを使う + +❌ **非推奨：** +- フックを対話的にする +- 長時間タスクをフックで実行する +- 認証情報をハードコードする + +**詳細：** [06-hooks/](../06-hooks/) + +--- + +## チェックポイントと巻き戻し + +### 概要 + +チェックポイントは会話の状態を保存し、過去の地点へ巻き戻すことを可能にする。複数のアプローチを安全に試行・検討できる。 + +### 主要概念 + +| 概念 | 説明 | +|---------|-------------| +| **チェックポイント** | メッセージ、ファイル、コンテキストを含む会話状態のスナップショット | +| **巻き戻し** | 過去のチェックポイントへ戻り、それ以降の変更を破棄 | +| **分岐点** | 複数アプローチを試すための起点となるチェックポイント | + +### チェックポイントへのアクセス + +チェックポイントはユーザープロンプトのたびに自動作成される。巻き戻すには： + +```bash +# Esc を 2 回押すとチェックポイントブラウザが開く +Esc + Esc + +# または /rewind コマンド +/rewind +``` + +チェックポイントを選ぶと 5 つのオプションから選択できる： +1. **コードと会話を復元** — 両方をその時点へ戻す +2. **会話を復元** — メッセージを巻き戻し、現在のコードは保つ +3. **コードを復元** — ファイルを戻し、会話は保つ +4. **ここから要約** — 会話を要約に圧縮 +5. **キャンセル** — 取り消す + +### ユースケース + +| シナリオ | ワークフロー | +|----------|----------| +| **アプローチ比較** | 保存 → A 試行 → 保存 → 巻き戻し → B 試行 → 比較 | +| **安全なリファクタリング** | 保存 → リファクタ → テスト → 失敗時に巻き戻し | +| **A/B テスト** | 保存 → 設計 A → 保存 → 巻き戻し → 設計 B → 比較 | +| **ミス回復** | 問題発見 → 直前の正常状態へ巻き戻し | + +### 設定 + +```json +{ + "autoCheckpoint": true +} +``` + +**詳細：** [08-checkpoints/](../08-checkpoints/) + +--- + +## 高度な機能 + +### プラニングモード + +実装前に詳細な計画を作成する。 + +**起動：** +```bash +/plan Implement user authentication system +``` + +**メリット：** +- 工数見積もり付きの明確なロードマップ +- リスク評価 +- 体系的なタスク分割 +- レビューと修正の機会 + +### 拡張思考（Extended Thinking） + +複雑な問題に対する深い推論。 + +**起動：** +- セッション中に `Alt+T`（macOS では `Option+T`）でトグル +- プログラム制御には環境変数 `MAX_THINKING_TOKENS` を設定 + +```bash +# 環境変数で拡張思考を有効化 +export MAX_THINKING_TOKENS=50000 +claude -p "Should we use microservices or monolith?" +``` + +**メリット：** +- トレードオフを徹底分析 +- より良いアーキテクチャ判断 +- エッジケースの考慮 +- 体系的な評価 + +### バックグラウンドタスク + +会話をブロックせずに長時間処理を実行する。 + +**使い方：** +```bash +User: Run tests in background + +Claude: Started task bg-1234 + +/task list # 全タスク一覧 +/task status bg-1234 # 進捗確認 +/task show bg-1234 # 出力閲覧 +/task cancel bg-1234 # タスクキャンセル +``` + +### 権限モード + +Claude にできることを制御する。 + +| モード | 説明 | ユースケース | +|------|-------------|----------| +| **default** | 標準権限。機微な操作はプロンプト | 一般開発 | +| **acceptEdits** | ファイル編集を確認なく承認 | 信頼できる編集ワークフロー | +| **plan** | 解析・計画のみ、ファイル変更不可 | コードレビュー、アーキテクチャ計画 | +| **auto** | 安全な操作は自動承認、リスクのみ確認 | 安全性とのバランス自律性 | +| **dontAsk** | すべての操作を確認なく実行 | 経験者、自動化 | +| **bypassPermissions** | 制限なし、安全チェックなし | CI/CD、信頼できるスクリプト | + +**使い方：** +```bash +claude --permission-mode plan # 読み取り専用解析 +claude --permission-mode acceptEdits # 編集を自動承認 +claude --permission-mode auto # 安全な操作を自動承認 +claude --permission-mode dontAsk # 確認プロンプトなし +``` + +### ヘッドレスモード（Print Mode） + +`-p`（print）フラグで、対話入力なしの自動化や CI/CD 向けに Claude Code を実行する。 + +**使い方：** +```bash +# 特定タスクを実行 +claude -p "Run all tests" + +# 入力をパイプして解析 +cat error.log | claude -p "explain this error" + +# CI/CD 連携（GitHub Actions） +- name: AI Code Review + run: claude -p "Review PR changes and report issues" + +# スクリプト用 JSON 出力 +claude -p --output-format json "list all functions in src/" +``` + +### 定期タスク + +`/loop` コマンドで定期実行する。 + +**使い方：** +```bash +/loop every 30m "Run tests and report failures" +/loop every 2h "Check for dependency updates" +/loop every 1d "Generate daily summary of code changes" +``` + +定期タスクはバックグラウンドで実行され、完了時に結果を報告する。継続監視、定期チェック、自動メンテナンスのワークフローに有用である。 + +### Chrome 連携 + +Claude Code は Chrome ブラウザと連携できる。Web ページのナビゲーション、フォーム入力、スクリーンショット撮影、サイトからのデータ抽出など、開発ワークフロー内で Web 自動化が可能になる。 + +### セッション管理 + +複数の作業セッションを管理する。 + +**コマンド：** +```bash +/resume # 過去の会話を再開 +/rename "Feature" # 現在のセッションに名前を付ける +/fork # 新セッションへフォーク +claude -c # 直近の会話を継続 +claude -r "Feature" # 名前 / ID でセッションを再開 +``` + +### インタラクティブ機能 + +**キーボードショートカット：** +- `Ctrl + R` — コマンド履歴検索 +- `Tab` — 自動補完 +- `↑ / ↓` — コマンド履歴 +- `Ctrl + L` — 画面クリア + +**複数行入力：** +```bash +User: \ +> Long complex prompt +> spanning multiple lines +> \end +``` + +### 設定 + +完全な設定例： + +```json +{ + "planning": { + "autoEnter": true, + "requireApproval": true + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5 + }, + "permissions": { + "mode": "default" + } +} +``` + +**詳細ガイド：** [09-advanced-features/](../09-advanced-features/) + +--- + +## モデルと推論努力（Reasoning Effort） + +Claude Code は推論努力を調整可能な 3 モデルをサポートする： + +| モデル | コンテキストウィンドウ | 努力レベル | デフォルト努力（Claude Code） | +|-------|----------------|---------------|------------------------------| +| Claude Opus 4.7 | 1M トークン（ネイティブ） | `low`、`medium`、`high`、`xhigh`、`max` | `xhigh`（Opus 4.7 リリース時、2026-04-16 以降） | +| Claude Sonnet 4.6 | 1M トークン | `low`、`medium`、`high`、`max` | Pro/Max 加入者では `high`（v2.1.117 で `medium` から引き上げ） | +| Claude Haiku 4.5 | 200K トークン | `low`、`medium`、`high` | `medium` | + +> **注：** v2.1.117 では、Opus 4.7 セッションで `/context` がネイティブの 1M ではなく 200K に対して計算されていたバグが修正された。Opus 4.7 で本来の 1M コンテキストを使うには v2.1.117 以降にアップグレードすること。 + +> **注：** v2.1.118 で `/cost` と `/stats` は `/usage` に統合された。`/usage` がコスト・統計などのタブを持つ正規コマンドとなり、`/cost` と `/stats` は対応するタブを開くショートカット別名として残されている。 + +## 参考資料 + +- [Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [Claude Code Changelog](https://code.claude.com/docs/en/changelog) +- [MCP GitHub Servers](https://github.com/modelcontextprotocol/servers) +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) + +--- + +*最終更新：2026 年 4 月 24 日* +*対応：Claude Haiku 4.5、Sonnet 4.6、Opus 4.7* +*収録機能：フック、チェックポイント、プラニングモード、拡張思考、バックグラウンドタスク、権限モード（6 種）、ヘッドレスモード、セッション管理、Auto Memory、Agent Teams、定期タスク、Chrome 連携、Channels、音声入力、同梱スキル* + +--- +**最終更新：** 2026 年 4 月 24 日 +**Claude Code バージョン：** 2.1.119 +**出典：** +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/hooks +- https://www.anthropic.com/news/claude-opus-4-7 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 + +**対応モデル：** Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5 diff --git a/ja/clean-code-rules.md b/ja/clean-code-rules.md new file mode 100644 index 0000000..85f1669 --- /dev/null +++ b/ja/clean-code-rules.md @@ -0,0 +1,115 @@ + + + + +# AI コード生成のためのクリーンコードルール + +これらのルールは、保守可能でプロ品質のコードを生成するためのコード生成指針である。 + +## 意味のある名前 +- 何のために存在するかを示す、意図を明らかにする名前を使う +- 誤解を招く表現や、意味のない区別（例：`data`、`info`、`manager`）を避ける +- 発音可能で検索可能な名前を使う +- クラス名：名詞（例：`UserAccount`、`PaymentProcessor`） +- メソッド名：動詞（例：`calculateTotal`、`sendEmail`） +- 心理的マッピングやエンコーディング（ハンガリアン記法、プレフィックス）を避ける + +## 関数 +- 関数は小さく保つ（理想は 20 行未満） +- 1 つのことだけを行う — 単一責任原則 +- 1 関数につき 1 段階の抽象度 +- 引数を制限する：理想は 0〜2 個、最大 3 個、フラグ引数は避ける +- 副作用を作らない — 関数は名前どおりのことだけをする +- コマンド（状態を変える）とクエリ（情報を返す）を分離する +- エラーコードよりも例外を使う + +## コメント +- コードは自己説明的であるべき — できる限りコメントは避ける +- よいコメント：法的情報、警告、TODO、公開 API のドキュメント +- 悪いコメント：冗長、誤解を招く、または悪いコードの言い訳 +- コードをコメントアウトしない — 削除する（履歴はバージョン管理が保持する） +- コメントが必要だと感じたら、代わりにコードのリファクタリングを検討する + +## フォーマット +- ファイルは小さく、焦点を絞って保つ +- 縦のフォーマット：関連する概念は近くに、空行で概念を区切る +- 横のフォーマット：行長を制限する（80〜120 文字） +- 一貫したインデントとチームスタイルを使う +- 関連する関数を近くにまとめる + +## オブジェクトとデータ構造 +- オブジェクト：データを抽象化の背後に隠し、メソッド経由で振る舞いを公開する +- データ構造：データを公開し、振る舞いは最小限に抑える +- デメテルの法則：直接の友人にしか話しかけない（`a.getB().getC().doSomething()` を避ける） +- ゲッター／セッターによって内部構造を盲目的に公開しない + +## エラー処理 +- リターンコードやエラーフラグではなく、例外を使う +- 失敗の可能性があるコードは `try-catch-finally` を先に書く +- 例外メッセージにはコンテキストを含める +- `null` を返さない — 空のコレクションを返すか、Optional/Maybe を使う +- `null` を引数として渡さない + +## クラス +- 小さなクラス：行数ではなく責任の数で測る +- 単一責任原則：変更する理由が 1 つだけ +- 高い凝集度：多くのメソッドで使われるクラス変数 +- 低い結合度：クラス間の依存関係を最小化する +- 開放／閉鎖原則：拡張に対して開かれ、修正に対して閉じている + +## 単体テスト +- Fast、Independent、Repeatable、Self-validating、Timely（F.I.R.S.T.） +- 1 テストにつき 1 アサート（または 1 概念） +- テストコードの品質はプロダクションコードと等しい +- 何をテストしているかが分かる読みやすいテスト名 +- Arrange-Act-Assert パターン + +## コード品質の原則 +- **DRY（Don't Repeat Yourself）：** 重複を作らない +- **YAGNI（You Aren't Gonna Need It）：** 仮想の未来のために作らない +- **KISS（Keep It Simple）：** 不要な複雑さを避ける +- **ボーイスカウトルール：** 自分が見つけたときよりきれいな状態でコードを去る + +## 避けるべきコードスメル +- 長い関数やクラス +- 重複コード +- デッドコード（未使用の変数、関数、引数） +- フィーチャーエンビー（他クラスに過度に関心を持つメソッド） +- 不適切な親密さ（クラス同士が互いを知りすぎている） +- 長い引数リスト +- プリミティブ強迫（小さなオブジェクトの代わりにプリミティブを多用する） +- switch/case 文（ポリモーフィズムを検討する） +- 一時フィールド（時々しか使われないクラス変数） + +## 並行処理 +- 並行コードを他のコードから分離する +- 同期／ロック対象のデータのスコープを制限する +- スレッドセーフなコレクションを使う +- 同期セクションは小さく保つ +- 実行モデルとプリミティブを理解する + +## システム設計 +- 構築と利用を分離する（依存性注入） +- 複雑なオブジェクト生成にはファクトリやビルダーを使う +- 実装ではなくインターフェースに対してプログラミングする +- 継承よりコンポジションを優先する +- デザインパターンは見せびらかすためでなく、簡潔化に役立つときに適用する + +## リファクタリング +- 大きな塊ではなく、継続的にリファクタリングする +- 前後で常にテストが通る状態を維持する +- 小さなステップ：一度に 1 つの変更 +- 一般的なリファクタリング：Extract Method、Rename、Move、Inline + +## ドキュメント +- 自己説明的なコード ＞ コメント ＞ 外部ドキュメント +- 公開 API には明確なドキュメントが必要 +- ドキュメントには例を含める +- ドキュメントはコードに近く保つ（理想はコード内） + +--- + +**コア哲学：** コードは書かれる回数の 10 倍読まれる。賢さではなく、可読性と保守性を最適化する。 + +--- +**Last Updated**: April 9, 2026 diff --git a/ja/docs/ROADMAP-20260401.md b/ja/docs/ROADMAP-20260401.md new file mode 100644 index 0000000..6b432ae --- /dev/null +++ b/ja/docs/ROADMAP-20260401.md @@ -0,0 +1,156 @@ + + + +# ロードマップ: claude-howto 2026–2027 + +> 2026 年 4 月〜 2027 年 3 月 · デュアルレイヤー知識ベース | 全体計画: `TASKS-20260401.md` + +--- + +## ビジョン + +claude-howto を静的なチュートリアルリポジトリから **生きたデュアル対象向け知識システム** へ転換する： + +- **人間向け** — シナリオベースのインタラクティブ学習。難易度の段階付け、決定ツリー、エキスパートがブックマークする名前付きパターンを備える +- **AI エージェント向け** — エージェントが Claude Code タスク実行前に問い合わせる構造化メタデータインデックス。これによりリポジトリは単なるコンテンツではなくインフラとなる + +主要な対象として AI エージェントを据える競合は存在しない。これが本プロジェクトの参入障壁となる。 + +--- + +## 7 つの柱 + +| # | 柱 | 提供するもの | +|---|--------|-----------------| +| P1 | Fun Layer | 各モジュールにシナリオ導入と「Try It Now」ブロック | +| P2 | AI Agent Index | 自動生成 `agent-manifest.json` ＋ `AGENT-INDEX.md` ＋ ルックアップスキル | +| P3a | Expert Reference (in-module) | モジュールごとの決定ツリーと名前付きパターン | +| P3b | Expert Reference (cross-module) | `RECIPES.md` — 複数機能を組み合わせた複合ワークフロー | +| P4 | Newcomer Onboarding | `quickstart.sh` ＋ `QUICKSTART.md` ＋難易度バッジ | +| P5 | Community Showcase | `COMMUNITY-PROJECTS.md` — 厳選されたユーザープロジェクト | +| P6 | Content Quality | 弱いモジュールの拡充、プロジェクト用 `CLAUDE.md` | +| P7 | Living Curriculum | `WHATS-NEW.md` ＋バージョンバッジ＋週次の鮮度チェック CI | + +--- + +## タイムライン概観 + +``` +Apr 2026 May–Jun 2026 Jul–Aug 2026 Sep 2026 Oct–Nov 2026 Dec 2026–Mar 2027 + | | | | | | + [M1] [M2] [M3] [M4] [M5] [M6] +Infrastructure 6/10 modules 10/10 Agent layer Version audit Self-sustaining ++ hooks/checks complete complete + recipes complete system +``` + +--- + +## マイルストーン + +### M1 — インフラ稼働 · 2026 年 4 月末 + +**リリース内容:** +- `scripts/quickstart.sh` — 新規ユーザー向けのワンコマンドセットアップ（冪等） +- `QUICKSTART.md` — 「最初の 15 分」ビジュアルガイド +- 全 10 モジュールに難易度バッジと「What you'll build」プレビュー +- `WHATS-NEW.md` ＋全モジュールのバージョンバッジ +- `.github/workflows/staleness-check.yml` — モジュールが 30 日以上未検証なら毎週月曜に Issue を起票 +- ルート `CLAUDE.md` — プロジェクト自身の設定をベストプラクティス例として提示 +- `scripts/build-agent-index.py` — 全 10 モジュールを読み込み → `agent-manifest.json` ＋ `AGENT-INDEX.md` を出力するジェネレータ +- **06-hooks** — 全面深掘り: 完成された 5 つのフックスクリプト、決定ツリー、Try It Now、パターン +- **08-checkpoints** — 全面深掘り: 311 → 800 行超、3 つのワークフローテンプレート、決定ツリー、パターン + +**ここから始める理由:** インフラはすべての後続フェーズに恩恵をもたらす。Hooks と Checkpoints は最も弱いモジュールであり、新しい来訪者を最も逃しやすい。 + +--- + +### M2 — 10 モジュール中 6 つ完成 · 2026 年 6 月末 + +**リリース内容（モジュールごとに 1 回深掘り）:** +- **01-slash-commands** — シナリオ導入、決定ツリー、Try It Now、名前付きパターン +- **02-memory** — シナリオ導入、決定ツリー、Try It Now、名前付きパターン +- **03-skills** — シナリオ導入、決定ツリー、Try It Now、名前付きパターン +- **10-cli** — シナリオ導入、決定ツリー、Try It Now、名前付きパターン +- CI ステップ: プッシュごとに `agent-manifest.json` のスキーマを検証 + +各モジュールの深掘り終了時にジェネレータを実行し、有効なマニフェストが出力されることを確認する。 + +--- + +### M3 — 全 10 モジュール完成 · 2026 年 8 月末 + +**リリース内容:** +- **04-subagents** — 全面深掘り（「The Multi-Agent Review Pattern」を含む） +- **05-mcp** — 全面深掘り +- **07-plugins** — 全面深掘り +- **09-advanced-features** — 全面深掘り + +すべてのモジュールがシナリオ導入、2 つ以上の Try It Now ブロック、Mermaid 決定ツリー、2 つ以上の名前付きパターンを備える。 + +--- + +### M4 — エージェントレイヤー稼働 · 2026 年 9 月末 + +**リリース内容:** +- 最終的な `agent-manifest.json`（完成コンテンツから生成、全モジュールの 100% をカバー） +- `README.md` からリンクされる `AGENT-INDEX.md` +- `skills/claude-howto-lookup/SKILL.md` — マニフェストを問い合わせる軽量なエージェントスキル +- `RECIPES.md` — 5 つ以上の複合ワークフロー（スキーマ: name、modules-used、problem、solution、expected outcome） +- `COMMUNITY-PROJECTS.md` — PR ベースの投稿形式による静的な厳選リスト + +**9 月にする理由:** エージェントインデックスは 10 モジュールすべてのコンテンツが完成していて初めて意味を持つ。 + +--- + +### M5 — バージョン監査完了 · 2026 年 11 月末 + +**リリース内容:** +- 完全なバージョン監査: 全 10 モジュールを現行 Claude Code バージョンで検証 +- すべての箇所で `cc_version_verified` フロントマターとバージョンバッジを更新 +- 観察されたコミュニティパターンに基づき `RECIPES.md` を 8 件以上に拡張 +- ピン留め GitHub Discussion: 「Share your Claude Code workflows」 — エージェント利用シグナル収集用 + +--- + +### M6 — 自走するシステム · 2027 年 3 月末 + +**リリース内容／継続稼働:** +- `/docs-sync-claude-code` スキルが Claude Code リリースのたびに走る → `WHATS-NEW.md` が更新される +- エージェントマニフェストの CI 回帰テスト: 全モジュール 100% カバレッジを強制 +- `RECIPES.md` が 10 件以上 +- `COMMUNITY-PROJECTS.md` が有機的に成長 +- エージェント利用シグナルを評価 → 妥当性が検証されたらルックアップスキルを宣伝（マーケティング、asm レジストリ） + +--- + +## 成果物まとめ + +| 成果物 | 種別 | フェーズ | +|-------------|------|-------| +| `scripts/quickstart.sh` | スクリプト | P1 | +| `QUICKSTART.md` | ドキュメント | P1 | +| ルート `CLAUDE.md` | 設定 | P1 | +| `WHATS-NEW.md` | ドキュメント | P1 | +| `.github/workflows/staleness-check.yml` | CI | P1 | +| `scripts/build-agent-index.py` | スクリプト | P1 | +| 10 モジュール深掘り（シナリオ＋Try It Now＋決定ツリー＋パターン） | コンテンツ | P1–P3 | +| `agent-manifest.json`（自動生成） | データ | P4 | +| `AGENT-INDEX.md`（自動生成） | ドキュメント | P4 | +| `skills/claude-howto-lookup/SKILL.md` | スキル | P4 | +| `RECIPES.md`（5 → 8 → 10 件超） | ドキュメント | P4–P6 | +| `COMMUNITY-PROJECTS.md` | ドキュメント | P4 | + +--- + +## スコープ外 + +`TODOS.md` に先送り — これらが紛れ込まないようにする： + +- スキルマーケットプレイスやインストール可能なレジストリ +- 独自の Web サイトやダッシュボード +- 進捗トラッキング（cc-progress） +- コミュニティチュートリアルの CI 検証 +- 自動生成の CONTRIBUTORS.md +- 多言語翻訳 +- クイズ・アセスメント基盤 +- プロジェクトに対するコミュニティ投票 diff --git a/ja/docs/TASKS-20260401.md b/ja/docs/TASKS-20260401.md new file mode 100644 index 0000000..8b8e230 --- /dev/null +++ b/ja/docs/TASKS-20260401.md @@ -0,0 +1,294 @@ + + + +# タスク: デュアルレイヤー知識ベース — claude-howto + +> 作成日: 2026-04-01 + +--- + +## マイルストーン + +| # | マイルストーン | 目標期日 | 説明 | +|---|-----------|--------|-------------| +| M1 | インフラ稼働 | 2026 年 4 月末 | quickstart.sh、CLAUDE.md、鮮度チェック Action、エージェントインデックスジェネレータ稼働。最も弱い 2 モジュールを刷新 | +| M2 | 10 モジュール中 6 つ完成 | 2026 年 6 月末 | スラッシュコマンド、メモリ、スキル、CLI モジュールを完全刷新。ジェネレータが有効なマニフェストを出力 | +| M3 | 全 10 モジュール完成 | 2026 年 8 月末 | 全モジュールがシナリオ導入、Try It Now ブロック、決定ツリー、名前付きパターンを備える | +| M4 | エージェントレイヤー稼働 | 2026 年 9 月末 | agent-manifest.json と AGENT-INDEX.md が生成済み、リポジトリ内にルックアップスキルがある、RECIPES.md と COMMUNITY-PROJECTS.md が稼働 | +| M5 | バージョン監査完了 | 2026 年 11 月末 | 全 10 モジュールが現行 Claude Code バージョンで検証済み、RECIPES.md は 8 件以上 | +| M6 | 自走するシステム | 2027 年 3 月末 | エージェントマニフェストが全モジュールを 100% カバー（CI 検証）、RECIPES.md は 10 件以上、コミュニティページが有機的に成長 | + +--- + +## フェーズ 1 — インフラと弱いモジュール（2026 年 4 月） + +**対象マイルストーン: M1** + +### 柱 4: 新規ユーザーオンボーディング + +- [ ] **T-001** — `scripts/quickstart.sh` を作成 + - `~/.claude/` ディレクトリを検出（無い場合はユーザー確認のうえ作成） + - 最初のスラッシュコマンド＋CLAUDE.md＋スキルをユーザーのセットアップにコピー + - CLAUDE.md にエージェント発見用の行を追記し、AGENT-INDEX.md にリンク + - 冪等: 既存ファイルは警告を出してスキップし、上書きしない + - 完了時に次のステップを表示する + +- [ ] **T-002** — `QUICKSTART.md`（最初の 15 分ビジュアルガイド）を作成 + - 注釈付きターミナル手順をコードブロックとして記載（可能な限り PNG スクリーンショットを避け、ASCII か Mermaid を優先） + - 各ビジュアルを生成するコマンドを記録し、後から再撮影できるようにする + +- [ ] **T-003** — 全 10 モジュールの README に難易度バッジを追加 + - 形式: 各モジュール README の冒頭に `> 🟢 **Beginner** | ⏱ 30 minutes` + - バッジの下に「What you'll build」の箇条書きプレビューを追加 + +### 柱 7: 生きたカリキュラム + +- [ ] **T-004** — `WHATS-NEW.md` を作成 + - 形式: `## CC vX.X — DATE` に機能変更を箇条書き + - 現行 Claude Code バージョンのエントリを少なくとも 1 件追加 + +- [ ] **T-005** — 全 10 モジュールの README にバージョンバッジを追加 + - 形式: `> ✅ Verified against Claude Code **vX.X.X** · Last verified: YYYY-MM-DD` + - 各モジュールのフロントマターに `cc_version_verified` を追加 + +- [ ] **T-006** — `.github/workflows/staleness-check.yml` を作成 + - スケジュール: 毎週月曜 09:00 UTC + - 各モジュールのフロントマターから `last_verified` 日付を読む（`yq` または 10 行の Python スクリプトを使う） + - 30 日以上検証されていないモジュールに対して GitHub Issue を起票 + - 同じタイトルの Open Issue が既にあればスキップ + +### 柱 6: コンテンツ品質（CLAUDE.md） + +- [ ] **T-007** — プロジェクトのルート `CLAUDE.md` を作成 + - プロジェクト自身の設定としてベストプラクティスを示す + - 投稿規約、モジュール構造、メンテナンスワークフローを明文化 + +### 柱 2: AI エージェントインデックス（ジェネレータ） + +- [ ] **T-008** — `scripts/build-agent-index.py` を作成 + - 全 10 モジュールの README ファイルを読む + - 抽出: 見出し（→ トピック）、コードブロック（→ 言語タグ付きの例）、テーブル（→ 参照データ） + - CEO プランで定義したスキーマで `agent-manifest.json` を出力 + - `AGENT-INDEX.md`（人間可読サマリ）を出力 + - 参照が実在のファイルを指すか検証 + +### モジュール 08-checkpoints: 全面深掘り（311 → 800 行超） + +- [ ] **T-009** — モジュール導入を実例シナリオで書き直す + - 例: 「リファクタで 3 つ壊れた。チェックポイントが救う方法は…」 + +- [ ] **T-010** — チェックポイント戦略の決定ツリーを追加（Mermaid フローチャート） + - 「X したい」 → 矢印を追う → チェックポイントパターンに辿り着く + +- [ ] **T-011** — 3 つのワークフローテンプレートを追加 + - 安全なリファクタリングワークフロー + - チェックポイントを使った A/B テスト + - 災害復旧ワークフロー + +- [ ] **T-012** — プランニングモードとの統合セクションを追加 + +- [ ] **T-013** — チェックポイントライフサイクルの Mermaid 図を追加 + +- [ ] **T-014** — 検証可能なコマンドを伴う「Try It Now」ブロックを 2 つ以上追加 + - 各ブロック: 文脈の文章、実行コマンド、期待される出力の説明 + +- [ ] **T-015** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + - 各パターン: 課題、解決コード、適用すべき場面、適用すべきでない場面 + +### モジュール 06-hooks: 全面深掘り + +- [ ] **T-016** — モジュール導入を実例シナリオで書き直す + - 例: 「CI が 20 分後に lint エラーを検出した。フックなら 2 秒で…」 + +- [ ] **T-017** — フックの決定ツリーを追加（Mermaid フローチャート） + - 「Y が起きたとき X をトリガーしたい」 → 矢印を追う → フックタイプに辿り着く + +- [ ] **T-018** — 完全なスクリプト付きの 5 つのフック例を追加（各 80 行程度） + 1. 書き込み時の自動フォーマット（prettier／black） + 2. コミット時のセキュリティスキャン（trufflehog／bandit） + 3. ファイル変更時のテスト実行 + 4. セッション終了時の通知 + 5. プロンプトの検証（危険なパターンをブロック） + +- [ ] **T-019** — 検証可能なコマンドを伴う「Try It Now」ブロックを 2 つ以上追加 + +- [ ] **T-020** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + +**M1 チェックポイント: インフラ稼働、最も弱い 2 モジュールが完全刷新** + +--- + +## フェーズ 2 — 深掘り: 強モジュール バッチ 1（2026 年 5〜6 月） + +**対象マイルストーン: M2** + +### モジュール 01-slash-commands: 全面深掘り + +- [ ] **T-021** — シナリオで導入を書き直す（「同僚が 47 ファイルをプッシュしたばかり…」） +- [ ] **T-022** — 決定ツリー（Mermaid）を追加 +- [ ] **T-023** — 「Try It Now」ブロックを 2 つ以上追加 +- [ ] **T-024** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + +### モジュール 02-memory: 全面深掘り + +- [ ] **T-025** — 実例シナリオで導入を書き直す +- [ ] **T-026** — 決定ツリー（Mermaid）を追加 +- [ ] **T-027** — 「Try It Now」ブロックを 2 つ以上追加 +- [ ] **T-028** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + +### モジュール 03-skills: 全面深掘り + +- [ ] **T-029** — 実例シナリオで導入を書き直す +- [ ] **T-030** — 決定ツリー（Mermaid）を追加 +- [ ] **T-031** — 「Try It Now」ブロックを 2 つ以上追加 +- [ ] **T-032** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + +### モジュール 10-cli: 全面深掘り + +- [ ] **T-033** — 実例シナリオで導入を書き直す +- [ ] **T-034** — 決定ツリー（Mermaid）を追加 +- [ ] **T-035** — 「Try It Now」ブロックを 2 つ以上追加 +- [ ] **T-036** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + +### ジェネレータ検証 + +- [ ] **T-037** — 各モジュール刷新後に `scripts/build-agent-index.py` を実行し、有効なマニフェスト出力を確認 +- [ ] **T-038** — CI ステップを追加: プッシュごとに agent-manifest.json のスキーマを検証 + +**M2 チェックポイント: 6/10 モジュール完成、ジェネレータが有効なマニフェストを生成** + +--- + +## フェーズ 3 — 深掘り: 強モジュール バッチ 2（2026 年 7〜8 月） + +**対象マイルストーン: M3** + +### モジュール 04-subagents: 全面深掘り + +- [ ] **T-039** — 実例シナリオで導入を書き直す +- [ ] **T-040** — 決定ツリー（Mermaid）を追加 +- [ ] **T-041** — 「Try It Now」ブロックを 2 つ以上追加 +- [ ] **T-042** — 「Patterns & Recipes」セクション追加（例: 「The Multi-Agent Review Pattern」） + +### モジュール 05-mcp: 全面深掘り + +- [ ] **T-043** — 実例シナリオで導入を書き直す +- [ ] **T-044** — 決定ツリー（Mermaid）を追加 +- [ ] **T-045** — 「Try It Now」ブロックを 2 つ以上追加 +- [ ] **T-046** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + +### モジュール 07-plugins: 全面深掘り + +- [ ] **T-047** — 実例シナリオで導入を書き直す +- [ ] **T-048** — 決定ツリー（Mermaid）を追加 +- [ ] **T-049** — 「Try It Now」ブロックを 2 つ以上追加 +- [ ] **T-050** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + +### モジュール 09-advanced-features: 全面深掘り + +- [ ] **T-051** — 実例シナリオで導入を書き直す +- [ ] **T-052** — 決定ツリー（Mermaid）を追加 +- [ ] **T-053** — 「Try It Now」ブロックを 2 つ以上追加 +- [ ] **T-054** — 「Patterns & Recipes」セクションに 2 つ以上の名前付きパターンを追加 + +**M3 チェックポイント: 全 10 モジュールが完成し、一貫している** + +--- + +## フェーズ 4 — エージェントレイヤーとクロスモジュール（2026 年 9 月） + +**対象マイルストーン: M4** + +### 柱 2: AI エージェントインデックスの最終化 + +- [ ] **T-055** — 完成した全 10 モジュールに対して `scripts/build-agent-index.py` を実行 + - 全モジュール 100% カバレッジで最終 `agent-manifest.json` を生成 + - `AGENT-INDEX.md` を生成し、README.md からリンク + +- [ ] **T-056** — `skills/claude-howto-lookup/SKILL.md` を作成 + - `agent-manifest.json` を読み、関連モジュールを検索 + - `Read` で当該セクションを読み込む + - インストール: `cp -r claude-howto/skills/claude-howto-lookup ~/.claude/skills/` + +- [ ] **T-057** — quickstart.sh と QUICKSTART.md でルックアップスキルを任意機能として言及 + +### 柱 3b: クロスモジュール RECIPES.md + +- [ ] **T-058** — `RECIPES.md` を作成（複合ワークフロー 5 件以上） + - レシピごとのスキーマ: name、modules-used、problem、solution code block、expected outcome + - 例: スキル＋フック＋サブエージェント ＝ 自動レビューパイプライン + - 主要見出しすべてに HTML アンカーを付け、ディープリンクを可能にする + +### 柱 5: コミュニティショーケース + +- [ ] **T-059** — `COMMUNITY-PROJECTS.md` を作成 + - 投稿フォーマットを伴う静的 Markdown ページ: 名前、説明、リンク、使用機能 + - テンプレートエントリを含める + - PR ベースの投稿手順を記載 + +**M4 チェックポイント: エージェントインデックス、レシピ、コミュニティページが稼働** + +--- + +## フェーズ 5 — バージョン監査とレシピ拡張（2026 年 10〜11 月） + +**対象マイルストーン: M5** + +- [ ] **T-060** — 完全なバージョン監査を実施: 全 10 モジュールを現行 Claude Code バージョンで検証 + - 各モジュールの `cc_version_verified` フロントマターを更新 + - バージョンバッジを更新 + +- [ ] **T-061** — 観察されたコミュニティパターンに基づき `RECIPES.md` を 8 件以上に拡張 + +- [ ] **T-062** — 完成モジュールから新パターンが現れたら、エージェントマニフェストのスキーマを反復改善 + +- [ ] **T-063** — ピン留め GitHub Discussion を開設: 「Share your Claude Code workflows」 + - 実際のエージェント利用シグナルを集め、今後のレシピ拡張に反映 + +**M5 チェックポイント: 全モジュールが現行検証済み、レシピが拡大中** + +--- + +## フェーズ 6 — 複合化と維持（2026 年 12 月〜2027 年 3 月） + +**対象マイルストーン: M6** + +- [ ] **T-064** — Claude Code リリースのたびに `/docs-sync-claude-code` スキルを実行し、`WHATS-NEW.md` を更新 + +- [ ] **T-065** — エージェントマニフェストが全モジュールを 100% カバーすることを保証（CI 回帰テスト） + +- [ ] **T-066** — `RECIPES.md` を 10 件以上に拡大 + +- [ ] **T-067** — `COMMUNITY-PROJECTS.md` の有機的成長を監視し、新規エントリをキュレーション + +- [ ] **T-068** — GitHub Discussions のエージェント利用シグナルを評価。妥当なら、ルックアップスキルの宣伝に投資（マーケティング、asm レジストリ） + +**M6 チェックポイント: システムが自走している** + +--- + +## 先送り（TODOS.md） + +以下の項目は本計画のスコープ外。スコープクリープを避けるためにここに記録： + +- スキルマーケットプレイスとインストール可能なレジストリ +- 独自の Web サイトやダッシュボード +- 進捗トラッキング基盤（cc-progress） +- CI 検証付きのコミュニティチュートリアルテンプレート +- 自動生成 CONTRIBUTORS.md +- 多言語翻訳 +- クイズ・アセスメント基盤の刷新 +- COMMUNITY-PROJECTS.md のコミュニティ投票・レビュー機構 + +--- + +## フェーズ別タスクサマリ + +| フェーズ | タスク | 期間 | 対象モジュール | +|-------|-------|--------|-----------------| +| 1 — インフラと弱いモジュール | T-001 〜 T-020 | 2026 年 4 月 | 06-hooks、08-checkpoints ＋インフラ | +| 2 — バッチ 1 深掘り | T-021 〜 T-038 | 2026 年 5〜6 月 | 01、02、03、10 | +| 3 — バッチ 2 深掘り | T-039 〜 T-054 | 2026 年 7〜8 月 | 04、05、07、09 | +| 4 — エージェントレイヤーとクロスモジュール | T-055 〜 T-059 | 2026 年 9 月 | 全モジュール（マニフェスト）＋新規ファイル | +| 5 — バージョン監査とレシピ | T-060 〜 T-063 | 2026 年 10〜11 月 | 全モジュール（監査） | +| 6 — 維持 | T-064 〜 T-068 | 2026 年 12 月〜2027 年 3 月 | 継続 | diff --git a/ja/prompts/remotion-video.md b/ja/prompts/remotion-video.md new file mode 100644 index 0000000..36f4e74 --- /dev/null +++ b/ja/prompts/remotion-video.md @@ -0,0 +1,356 @@ + + + +あなたは **Remotion** を専門とするモーションデザイナーかつシニア React エンジニアである。製品の説明を受け取り、それを React コードを使った高エネルギーかつプロ品質のアニメーションビデオに仕上げることを目的とする。 + +**まず自律的に探索を始めること：** ユーザに質問する前に、ただちにコードベースを探索して製品情報を収集する。探索を終えてもなお重要な情報が欠落している、または不明瞭な場合に限り、ユーザに質問する。 + +7 フェーズのワークフローに従い、収集した情報に基づいて各ステップで賢明な判断を下す。 + +--- + +# 🔄 自動化されたワークフロー + +**主要原則：** + +- **探索が先：** 必ずコードベースの自動探索から始め、製品情報を収集する。製品についての質問から始めてはならない。 +- **計画前にヒアリング：** 探索を終えたら発見事項を提示し、計画を立てる **前に** ユーザにビデオの好み（サイズ・スタイル・尺・カスタマイズ）を尋ねる。 +- **製品 URL を優先：** 製品 URL が見つかった、または提示された場合、それを **最優先の真実の源** として扱う。製品ページの情報はコードベース由来の情報よりも優先する。 +- **技術より価値：** 技術仕様や実装の詳細ではなく、価値提案・顧客の利益・機能（ユーザが得るもの）に焦点を当てる。 +- **顧客中心：** 製品がいかに問題を解決し、生活を改善し、ユーザに利益をもたらすかを強調する。 +- **自律実行：** ユーザが好みを確認した後は、追加の承認を求めずに、計画と実装を自律的に進める。 + +## 📋 フェーズ 1：自律的な情報収集 + +**目的：** ユーザに尋ねず、コードベースを自動的に探索して、入手可能な製品情報をすべて収集する。 + +**アクション：** + +1. **まずコードベースを自動探索：** + - `README.md` を検索して製品説明と価値提案を取得 + - `package.json` から製品名・説明・ホームページ URL を確認 + - `/assets`、`/public`、`/static`、`/images` ディレクトリでブランド素材を探す + - CSS / Tailwind 設定ファイルからカラースキームを抽出 + - 既存のマーケティングコピーやドキュメントを探す + - 設定ファイル・環境変数・ドキュメントから製品 URL を探す + +2. **製品 URL が見つかったらただちに取得：** + - WebFetch を使って製品ページから情報を抽出する + - 製品ページの情報はコードベース由来のものより優先する + - 価値提案・機能・ブランド要素をすべて抽出する + +3. **収集した情報を統合：** + - 製品名と説明 + - 価値提案 + - 主要な機能と利益 + - ブランドカラーとスタイル + - ターゲット層（トーンから推測） + - 既存の素材やメディア + +4. **欠落情報には賢明なデフォルトを適用：** + - **ビデオ形式：** 横向き 1920x1080（YouTube・Web 向けに最適化） + - **尺：** 30 秒（多くのプラットフォームで理想的） + - **スタイル：** モダン・クリーン・プロフェッショナル（ブランドに沿う） + - **ブランドカラー：** 抽出済みの色、または相補的なモダンパレットを使用 + +5. **次の場合に限ってユーザに質問する（探索後に）：** + - 製品名や製品情報を一切特定できない + - 製品 URL が見つからない、またはアクセスできない + - 重大な曖昧さがある（例：B2B か B2C かでメッセージが大きく変わる） + - 矛盾する情報があり、明確化が必要 + +**重要：** この探索フェーズ全体を、無言で自律的に完了させる。「開始するために必要なもの」を尋ねたり、要件をリスト化したりしない。本当に必要なときに限ってユーザの作業を中断する。 + +**アウトプット：** 収集したすべての情報を持ってフェーズ 2 にただちに進む。 + +--- + +## 🔍 フェーズ 2：情報分析と深堀り + +**目的：** 収集情報を分析し、ビデオ制作に必要な要点を抽出する。 + +**アクション：** + +1. **フェーズ 1 で収集したすべての情報を見直す：** + - 製品ページの内容（URL が見つかり取得できた場合） + - コードベース由来の情報（README、package.json、素材など） + - ブランドガイドラインやマーケティング素材 + +2. **抽出して優先順位付け（技術ではなく価値に焦点）：** + - **価値提案**（最重要）— 顧客への主要な利益 + - **顧客の利益**（ユーザが得るもの）— 生活がどう改善されるか + - **主要機能**（技術仕様ではなく利益として記述） + - **ユニークな売り）**（USP）— 何が他と違う・優れているのか + - **ユースケース** — 実世界での適用例 + - **ブランドアイデンティティ**（色・フォント・スタイル・トーン） + - **ターゲット層の洞察**（誰のための製品か） + - **感情的訴求**とメッセージ（なぜ人々が気にかけるのか） + +3. **ギャップは賢明な推測で静かに埋める：** + - 価値提案が明示されていなければ、機能とターゲット層から推測する + - ターゲット層が不明確なら、製品タイプとメッセージのトーンから推測する + - ブランドカラーが欠落していれば、相補的なモダンパレットを生成する + - ユーザに見えない技術実装の詳細は避ける + +4. **次の場合に限り明確化を求める：** + - 矛盾する複数の価値提案が共存している + - B2B か B2C かを判定できない（メッセージに大きく影響する） + - 真にターゲット層が曖昧 + +**アウトプット：** ビデオ制作のための、製品の価値・利益・ブランドに関する明確な理解。 + +--- + +## ✅ フェーズ 3：発見の提示とユーザの好みの聴取 + +**目的：** 何を発見したかを共有し、計画を立てる前にビデオの好みについてユーザの入力を得る。 + +**アクション：** + +1. **発見した情報のサマリーを提示する：** + + ```text + 📊 発見した情報 + + 製品：[名称] + 価値提案：[顧客への主要な利益] + 主要機能：[2〜3 個の主要な利益] + ブランドカラー：[抽出または提案した色] + ターゲット層：[誰のための製品か] + ``` + +2. **ユーザに好みを尋ねる（先に進む前に必須）：** + + 明確で簡潔なフォーマットを使う： + + ```text + ビデオを作成する前に、好みを教えてください： + + 1. **ビデオサイズ／形式：** + - 横向き（1920x1080）— YouTube、Web サイト + - 縦向き（1080x1920）— TikTok、Instagram Reels + - 正方形（1080x1080）— Instagram フィード + + 2. **ビデオの尺：** + - 15 秒 — 短いソーシャルメディア広告 + - 30 秒 — 標準的なプロモーション動画 + - 60 秒 — 詳細な機能ショーケース + - カスタム尺 + + 3. **ビデオのスタイル：** + - モダン＆ミニマル — Apple 風のクリーンな美学 + - エネルギッシュ＆ボールド — テンポの速い SNS スタイル + - プロフェッショナル＆コーポレート — ビジネス向け + - カスタムスタイル（ビジョンを記述してください） + + 4. **その他、強調・カスタマイズしたい点はありますか？** + （特定の機能、メッセージ、色など） + ``` + +3. ユーザの応答を待ってからフェーズ 4 に進む。 + +4. **好みを確認・追認：** + - ユーザの選択を要約する + - カスタム要件があれば適用する + - 確定した方向性で構成設計に進む + +**アウトプット：** ユーザが確認した、計画フェーズ用のビデオ仕様。 + +--- + +## 📐 フェーズ 4：構成設計（確認後） + +**目的：** ユーザの好みに基づき、3 幕構成で魅力的なビデオ構成を設計する。 + +**アクション：** + +1. **ユーザが確認した好みをもとに、ビデオ構成を設計：** + + ```text + 🎬 ビデオ構成 + + 第 1 幕：フック（0〜5 秒） + - [注意を引くビジュアルコンセプト] + - [大胆なエントランスアニメーション] + - [魅力的な見出し／問いかけ] + + 第 2 幕：価値の提示（中盤） + - [主要な利益を実演] + - [顧客価値のビジュアルストーリーテリング] + - [2〜3 個の機能ハイライトを利益として表現] + + 第 3 幕：行動喚起（終盤） + - [ブランドを補強する明確な CTA] + - [印象に残るクロージングビジュアル] + - [滑らかなエグジットアニメーション] + ``` + +2. **ユーザの好みを反映：** + - 指定されたビデオサイズ／形式を使用 + - 選択されたスタイル（ミニマル／エネルギッシュ／プロフェッショナル）に合わせる + - 指定された尺にタイミングを調整 + - カスタム要件を組み込む + +3. **次に基づいてクリエイティブな判断を下す：** + - 製品の価値提案（何が魅力か） + - ターゲット層（彼らに響くもの） + - ユーザが指定したスタイル + - ブランドの個性（ビジュアルとトーンの一貫性） + +4. **構成を簡潔に提示**したら、自動的にフェーズ 5 に進む。 + +**アウトプット：** 実装計画に進める完全なビデオ構成。 + +--- + +## 🛠️ フェーズ 5：技術アーキテクチャ + +**目的：** 実装アーキテクチャを設計し、そのまま構築に進む。 + +**アクション：** + +1. コンポーネントアーキテクチャを **静かに** 設計する： + - ユーティリティ関数（イージング、アニメーションヘルパー、カラーユーティリティ） + - 再利用可能なコンポーネント（AnimatedTitle、FeatureHighlight など） + - シーンコンポーネント（Hook、Demo、CTA シーン） + - メインコンポジション構造（Video.tsx、Root.tsx） + +2. **技術的な詳細を計画：** + - アニメーションのタイミングとイージングカーブ + - カラーパレットの実装 + - タイポグラフィの階層 + - アイコンと素材の戦略 + - シーケンスのタイミング内訳 + +3. 承認を求めずにフェーズ 6 の実装にそのまま進む。 + +**アウトプット：** ただちに実装に移れる内部技術設計図。 + +--- + +## 💻 フェーズ 6：実装 + +**目的：** 完全な Remotion ビデオプロジェクトを自律的に構築する。 + +**制約と技術スタック：** + +1. **フレームワーク：** Remotion（React） +2. **スタイリング：** Tailwind CSS（`className` または標準のスタイルオブジェクト経由） +3. **アニメーション：** 滑らかな動きのために `spring`、`interpolate`、`useCurrentFrame` を使用 +4. **コードスタイル：** モジュール化されたコンポーネント。すべてを `Root.tsx` に詰め込まない +5. **ベストプラクティス：** + - 静的な要素を残さない。すべてに登場（不透明度／拡大／スライド）と退出のアニメーションを与える + - 必要に応じて Lucide-React のアイコンを使用 + - 標準フォントを使い、強くスタイリングする（ボールド、tracking-tight） + - プレースホルダ（例：`https://placehold.co/600x400`）またはユーザ提供素材を除き、外部画像は使用しない + +**アクション：** + +1. 以下の順序で **完全なプロジェクト構造を構築する：** + - ユーティリティ関数（イージング、アニメーションヘルパー、カラーユーティリティ） + - 再利用可能なコンポーネント（AnimatedTitle、FeatureHighlight、トランジション） + - シーンコンポーネント（HookScene、DemoScene、CTAScene） + - メインコンポジション（シーケンスを含む Video.tsx） + - ルート設定（適切な登録を含む Root.tsx） + +2. **静かに、かつ効率的に作業する：** + - 各ステップを逐一説明せずに、すべてのファイルを作成する + - 収集した情報に基づいて設計判断を下す + - プロのアニメーション原則を用いる + - シーン間の滑らかなトランジションを保証する + +3. 実装が完了したら自動的にフェーズ 7 に進む。 + +**アウトプット：** 本番投入可能な、完全な Remotion プロジェクトコード。 + +--- + +## 🎥 フェーズ 7：納品と次のステップ + +**目的：** レンダリング手順を提示し、プロジェクトを完了とする。 + +**アクション：** + +1. **レンダリング手順を提示：** + + ```bash + # ブラウザでビデオをプレビュー + npm run dev + + # 最終ビデオをレンダリング + npm run build + npx remotion render Video out/video.mp4 + + # 特定のコーデック／設定で + npx remotion render Video out/video.mp4 --codec h264 + ``` + +2. **サマリーを納品：** + - 何を作成したかの簡潔な説明 + - ビデオの主要な特徴 + - ビデオ仕様（尺・形式・寸法） + - 注目すべき設計判断 + +3. **必要ならユーザは変更を依頼できる：** + - タイミング調整 + - アニメーション修正 + - コンテンツ更新 + - スタイルの微調整 + +**アウトプット：** 明確なレンダリング手順を備え、すぐに使える完全な Remotion プロジェクト。 + +--- + +# 🎯 品質基準 + +すべてのフェーズを通じて、以下の基準を保つ： + +**ビジュアル品質：** + +- プロ品質のアニメーション（滑らか・目的的・ブランド整合） +- 一貫した余白とアラインメント +- 適切なコントラストの読みやすいタイポグラフィ +- 統一されたカラー使用 + +**技術品質：** + +- クリーンでモジュール化されたコードアーキテクチャ +- パフォーマンス最適化済み（30fps での滑らかな再生） +- Remotion API の適切な使用（spring、interpolate、Sequence） +- 型安全（TypeScript 使用時） + +**クリエイティブ品質：** + +- 明確なナラティブ構造 +- 注意を引くオープニング +- 強い CTA +- 印象に残るビジュアルモーメント + +--- + +# 🚀 はじめに + +あなたの製品向けにプロ品質の Remotion ビデオプロジェクトを作成する。ワークフローは以下： + +## フェーズ 1〜2：自律探索（自動で実行） + +1. 製品の詳細・ブランド素材・色についてコードベースを探索 +2. 製品ページを取得・分析（URL がある場合） +3. 価値提案と主要な利益を抽出 + +## フェーズ 3：あなたの入力（こちらが質問する） + +1. 発見した情報を提示 +2. ビデオの好みを尋ねる： + - ビデオサイズ／形式（横向き／縦向き／正方形） + - 尺（15 秒／30 秒／60 秒） + - スタイル（ミニマル／エネルギッシュ／プロフェッショナル） + - カスタマイズ事項 + +## フェーズ 4〜7：自律実行（自動で実行） + +1. 好みに基づいてビデオ構成を設計 +2. プロのアニメーションを備えた完全な Remotion プロジェクトを構築 +3. レンダリング手順を添えて、本番投入可能なコードを納品 + +さあ、素晴らしいものを作ろう！ diff --git a/ja/resources.md b/ja/resources.md new file mode 100644 index 0000000..5e65197 --- /dev/null +++ b/ja/resources.md @@ -0,0 +1,262 @@ + + + + + + + Claude How To + + +# 良質なリソース一覧 + +## 公式ドキュメント + +| リソース | 説明 | リンク | +|----------|-------------|------| +| Claude Code Docs | Claude Code の公式ドキュメント | [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview) | +| Anthropic Docs | Anthropic 公式の総合ドキュメント | [docs.anthropic.com](https://docs.anthropic.com) | +| MCP Protocol | Model Context Protocol 仕様 | [modelcontextprotocol.io](https://modelcontextprotocol.io) | +| MCP Servers | 公式 MCP サーバ実装 | [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | +| Anthropic Cookbook | コード例とチュートリアル | [github.com/anthropics/anthropic-cookbook](https://github.com/anthropics/anthropic-cookbook) | +| Claude Code Skills | コミュニティスキルのリポジトリ | [github.com/anthropics/skills](https://github.com/anthropics/skills) | +| Agent Teams | マルチエージェントの調整と協調 | [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) | +| Scheduled Tasks | `/loop` と cron による定期タスク | [code.claude.com/docs/en/scheduled-tasks](https://code.claude.com/docs/en/scheduled-tasks) | +| Chrome Integration | ブラウザ自動化 | [code.claude.com/docs/en/chrome](https://code.claude.com/docs/en/chrome) | +| Keybindings | キーボードショートカットのカスタマイズ | [code.claude.com/docs/en/keybindings](https://code.claude.com/docs/en/keybindings) | +| Desktop App | ネイティブのデスクトップアプリケーション | [code.claude.com/docs/en/desktop](https://code.claude.com/docs/en/desktop) | +| Remote Control | リモートセッション制御 | [code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control) | +| Auto Mode | 自動権限管理 | [code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) | +| Channels | マルチチャネル通信 | [code.claude.com/docs/en/channels](https://code.claude.com/docs/en/channels) | +| Voice Dictation | Claude Code の音声入力 | [code.claude.com/docs/en/voice-dictation](https://code.claude.com/docs/en/voice-dictation) | + +## Anthropic エンジニアリングブログ + +| 記事 | 説明 | リンク | +|---------|-------------|------| +| Code Execution with MCP | コード実行を使って MCP のコンテキスト肥大化を解決する方法 — 98.7% のトークン削減 | [anthropic.com/engineering/code-execution-with-mcp](https://www.anthropic.com/engineering/code-execution-with-mcp) | + +--- + +## Claude Code を 30 分でマスターする + +_動画_：https://www.youtube.com/watch?v=6eBSHbLKuN0 + +_**全 Tips**_ +- **高度な機能とショートカットを探求する** + - リリースノートで Claude の新しいコード編集・コンテキスト機能を定期的に確認する。 + - チャット、ファイル、エディタビュー間を素早く切り替えるキーボードショートカットを覚える。 + +- **効率的なセットアップ** + - 後で見つけやすいよう、明確な名前／説明を付けたプロジェクト固有セッションを作成する。 + - Claude がいつでもアクセスできるよう、よく使うファイルやフォルダをピン留めする。 + - Claude の連携機能（GitHub、人気 IDE など）を設定して、コーディングプロセスを合理化する。 + +- **効果的なコードベース Q&A** + - アーキテクチャ、デザインパターン、特定モジュールについて Claude に詳しく質問する。 + - 質問にファイルと行参照を使う（例：「`app/models/user.py` のロジックは何を達成するか？」）。 + - 大きなコードベースでは、Claude が焦点を絞れるようサマリやマニフェストを提供する。 + - **プロンプト例**：_「src/auth/AuthService.ts:45-120 で実装された認証フローを説明できる？src/middleware/auth.ts のミドルウェアとどう統合される？」_ + +- **コード編集とリファクタリング** + - インラインコメントやコードブロック内のリクエストで焦点を絞った編集を得る（「この関数を分かりやすくリファクタリングして」）。 + - 並列のビフォア／アフター比較を求める。 + - 大きな編集の後は、品質保証のため Claude にテストやドキュメントを生成させる。 + - **プロンプト例**：_「api/users.js の getUserData 関数を、Promise の代わりに async/await を使うようリファクタリングして。ビフォア／アフターの比較を見せ、リファクタ版の単体テストを生成して」_ + +- **コンテキスト管理** + - 貼り付けるコード／コンテキストは、現在のタスクに関係するものだけに限定する。 + - 構造化されたプロンプト（「ファイル A はこれ、関数 B はこれ、私の質問は X」）を使うと最高のパフォーマンスが出る。 + - コンテキスト制限を超えないよう、プロンプトウィンドウから大きなファイルを取り除くか折りたたむ。 + - **プロンプト例**：_「models/User.js の User モデルと utils/validation.js の validateUser 関数。私の質問：後方互換性を保ちつつメール検証を追加するにはどうすればいい？」_ + +- **チームツールと統合する** + - Claude セッションをチームのリポジトリやドキュメントに接続する。 + - 繰り返しのエンジニアリングタスクには組み込みテンプレートを使うか、独自のものを作る。 + - セッション記録やプロンプトをチームメイトと共有して協働する。 + +- **パフォーマンスを高める** + - Claude に明確で目標志向の指示を与える（例：「このクラスを 5 つの箇条書きで要約して」）。 + - コンテキストウィンドウから不要なコメントとボイラープレートを削る。 + - Claude の出力が外れている場合は、コンテキストをリセットするか質問を言い換えて整合性を高める。 + - **プロンプト例**：_「src/db/Manager.ts の DatabaseManager クラスを 5 つの箇条書きで要約して、主な責任と主要メソッドに焦点を当てて」_ + +- **実用的な利用例** + - デバッグ：エラーやスタックトレースを貼り付け、原因と修正案を尋ねる。 + - テスト生成：複雑なロジックに対するプロパティベース、単体、統合テストを依頼する。 + - コードレビュー：リスクのある変更、エッジケース、コードスメルを Claude に特定させる。 + - **プロンプト例**： + - _「'TypeError: Cannot read property 'map' of undefined at line 42 in components/UserList.jsx' というエラーが出ている。スタックトレースと該当コードはこれ。原因と修正方法は？」_ + - _「PaymentProcessor クラスの包括的な単体テストを生成して。失敗したトランザクション、タイムアウト、無効な入力のエッジケースを含めて」_ + - _「このプルリクエストの diff をレビューして、潜在的なセキュリティ問題、パフォーマンスのボトルネック、コードスメルを特定して」_ + +- **ワークフローの自動化** + - 反復タスク（フォーマット、クリーンアップ、繰り返しのリネームなど）を Claude のプロンプトでスクリプト化する。 + - コード差分から PR 説明文、リリースノート、ドキュメントを Claude に下書きさせる。 + - **プロンプト例**：_「git diff に基づいて、変更の要約、変更ファイル一覧、テスト手順、影響を含む詳細な PR 説明を作成して。バージョン 2.3.0 のリリースノートも生成して」_ + +**Tip**：最高の結果を得るには複数の慣行を組み合わせる — まず重要ファイルをピン留めして目標を要約し、次に焦点を絞ったプロンプトと Claude のリファクタリングツールを使ってコードベースと自動化を漸進的に改善する。 + + +**Claude Code 推奨ワークフロー** + +### Claude Code 推奨ワークフロー + +#### 新規リポジトリの場合 + +1. **リポジトリと Claude 連携の初期化** + - 必須構造（README、LICENSE、.gitignore、ルート設定）で新規リポジトリをセットアップする。 + - アーキテクチャ、ハイレベルな目標、コーディングガイドラインを記述した `CLAUDE.md` ファイルを作成する。 + - Claude Code をインストールしてリポジトリにリンクし、コード提案、テスト雛形作成、ワークフロー自動化を有効にする。 + +2. **プランモードと仕様を活用する** + - プランモード（`shift-tab` または `/plan`）を使って、機能実装の前に詳細な仕様を起草する。 + - Claude にアーキテクチャ提案と初期プロジェクトレイアウトを尋ねる。 + - 明確で目標志向のプロンプト連鎖を保つ — コンポーネントの概要、主要モジュール、責任を尋ねる。 + +3. **反復的に開発・レビューする** + - 中核機能を小さな塊で実装し、コード生成、リファクタリング、ドキュメント化を Claude に依頼する。 + - 各増分の後に単体テストと例を要求する。 + - CLAUDE.md に進行中のタスクリストを維持する。 + +4. **CI/CD とデプロイを自動化する** + - GitHub Actions、npm/yarn スクリプト、デプロイワークフローの雛形を Claude に作らせる。 + - CLAUDE.md を更新し、対応するコマンド／スクリプトを依頼することでパイプラインを容易に適応させる。 + +```mermaid +graph TD + A[Start New Repository] --> B[Initialize Repository Structure] + B --> C[Create README, LICENSE, .gitignore] + C --> D[Create CLAUDE.md] + D --> E[Document Architecture & Guidelines] + E --> F[Install & Link Claude Code] + + F --> G[Enter Plan Mode] + G --> H[Draft Feature Specification] + H --> I[Get Architecture Suggestions] + I --> J[Define Components & Modules] + + J --> K[Implement Feature Chunk] + K --> L[Generate Code with Claude] + L --> M[Request Unit Tests] + M --> N[Review & Refactor] + N --> O{More Features?} + O -->|Yes| K + O -->|No| P[Update Task List in CLAUDE.md] + + P --> Q[Setup CI/CD Pipeline] + Q --> R[Scaffold GitHub Actions] + R --> S[Create Deployment Scripts] + S --> T[Test Automation] + T --> U[Repository Ready] + + style A fill:#e1f5ff + style G fill:#fff4e1 + style K fill:#f0ffe1 + style Q fill:#ffe1f5 + style U fill:#90EE90 +``` + +#### 既存リポジトリの場合 + +1. **リポジトリとコンテキストのセットアップ** + - リポジトリ構造、コーディングパターン、主要ファイルを記録するために `CLAUDE.md` を追加または更新する。レガシーリポジトリでは、フレームワーク、バージョンマップ、手順、既知のバグ、アップグレードノートをカバーする `CLAUDE_LEGACY.md` を使う。 + - Claude が文脈に使うべきメインファイルをピン留めまたは強調表示する。 + +2. **文脈に応じたコード Q&A** + - 特定のファイル／関数を参照しながら、コードレビュー、バグ説明、リファクタリング、移行計画を Claude に依頼する。 + - Claude に明確な境界を与える（例：「これらのファイルだけを変更する」「新しい依存関係を追加しない」）。 + +3. **ブランチ、ワークツリー、マルチセッション管理** + - 複数の git ワークツリーを使って機能やバグ修正を隔離し、ワークツリーごとに別の Claude セッションを起動する。 + - ターミナルのタブ／ウィンドウをブランチや機能ごとに整理して並列ワークフローを作る。 + +4. **チームツールと自動化** + - `.claude/commands/` を介してカスタムコマンドを同期し、チーム全体の整合性を保つ。 + - Claude のスラッシュコマンドやフックで反復タスク、PR 作成、コード整形を自動化する。 + - 共同トラブルシューティングとレビューのために、セッションとコンテキストをチームメンバーと共有する。 + +```mermaid +graph TD + A[Start with Existing Repository] --> B{Legacy Codebase?} + B -->|Yes| C[Create CLAUDE_LEGACY.md] + B -->|No| D[Create/Update CLAUDE.md] + C --> E[Document Frameworks & Version Maps] + D --> F[Document Structure & Patterns] + E --> G[Pin Key Files for Context] + F --> G + + G --> H[Identify Task Type] + H --> I{Task Category} + I -->|Bug Fix| J[Ask Claude for Bug Analysis] + I -->|Code Review| K[Request Code Review] + I -->|Refactor| L[Plan Refactoring Strategy] + I -->|Migration| M[Create Migration Plan] + + J --> N[Set Explicit Boundaries] + K --> N + L --> N + M --> N + + N --> O{Multiple Features?} + O -->|Yes| P[Create Git Worktrees] + O -->|No| Q[Work on Main Branch] + P --> R[Launch Separate Claude Sessions] + R --> S[Organize Terminal Tabs] + Q --> S + + S --> T[Setup Team Automation] + T --> U[Sync .claude/commands/] + U --> V[Configure Slash Commands] + V --> W[Setup Hooks for Automation] + W --> X[Share Session Context with Team] + + X --> Y{More Tasks?} + Y -->|Yes| H + Y -->|No| Z[Workflow Complete] + + style A fill:#e1f5ff + style C fill:#ffecec + style D fill:#fff4e1 + style P fill:#f0ffe1 + style T fill:#ffe1f5 + style Z fill:#90EE90 +``` + +**Tips**： +- 新しい機能や修正は、仕様とプランモードのプロンプトから始める。 +- レガシーや複雑なリポジトリでは、詳細なガイダンスを CLAUDE.md／CLAUDE_LEGACY.md に保存する。 +- 明確で焦点を絞った指示を与え、複雑な作業を多段階の計画に分解する。 +- 散らかりを避けるため、定期的にセッションをクリーンアップし、コンテキストを整理し、完了したワークツリーを削除する。 + +これらのステップは、新規および既存のコードベースにおける Claude Code とのスムーズなワークフローのコア推奨事項を捉えている。 + +--- + +## 新機能と能力（2026 年 3 月） + +### 主要機能リソース + +| 機能 | 説明 | 詳細 | +|---------|-------------|------------| +| **Auto Memory** | Claude がセッションをまたいで好みを自動的に学習・記憶する | [メモリガイド](02-memory/) | +| **Remote Control** | 外部ツールやスクリプトから Claude Code セッションをプログラム的に制御 | [高度な機能](09-advanced-features/) | +| **Web Sessions** | リモート開発のためのブラウザ経由の Claude Code アクセス | [CLI リファレンス](10-cli/) | +| **Desktop App** | UI を強化した Claude Code のネイティブデスクトップアプリ | [Claude Code Docs](https://code.claude.com/docs/en/desktop) | +| **Extended Thinking** | `Alt+T`／`Option+T` または `MAX_THINKING_TOKENS` 環境変数による深い推論の切り替え | [高度な機能](09-advanced-features/) | +| **Permission Modes** | きめ細かい制御：default、acceptEdits、plan、auto、dontAsk、bypassPermissions | [高度な機能](09-advanced-features/) | +| **7-Tier Memory** | Managed Policy、Project、Project Rules、User、User Rules、Local、Auto Memory | [メモリガイド](02-memory/) | +| **Hook Events** | 28 イベント：PreToolUse、PostToolUse、PostToolUseFailure、Stop、StopFailure、SubagentStart、SubagentStop、Notification、Elicitation など | [フックガイド](06-hooks/) | +| **Agent Teams** | 複雑なタスクで複数のエージェントを協調させる | [サブエージェントガイド](04-subagents/) | +| **Scheduled Tasks** | `/loop` と cron ツールで定期タスクをセットアップ | [高度な機能](09-advanced-features/) | +| **Chrome Integration** | ヘッドレス Chromium によるブラウザ自動化 | [高度な機能](09-advanced-features/) | +| **Keyboard Customization** | コードシーケンスを含むキーバインドのカスタマイズ | [高度な機能](09-advanced-features/) | +| **Monitor Tool** | バックグラウンドコマンドの stdout ストリームを監視し、ポーリングではなくイベントに反応する（v2.1.98+） | [高度な機能](09-advanced-features/) | + +--- +**Last Updated**: April 24, 2026 +**Claude Code Version**: 2.1.119 +**Sources**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/changelog +- https://github.com/anthropics/claude-code/releases/tag/v2.1.119 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/ja/resources/DESIGN-SYSTEM.md b/ja/resources/DESIGN-SYSTEM.md new file mode 100644 index 0000000..5ca58ea --- /dev/null +++ b/ja/resources/DESIGN-SYSTEM.md @@ -0,0 +1,247 @@ + + + +# Claude How To — デザインシステム + +## ビジュアル・アイデンティティ + +### アイコンデザインのコンセプト：コードブラケット付きコンパス + +Claude How To のアイコンは **`>` コードブラケット付きのコンパス** で、コードを進む案内付きナビゲーションを表現する： + +``` + N (green) + ▲ + │ +W ───>─── E Compass = Guidance/Direction + │ > Bracket = Code/Terminal/CLI + ▼ + S (black) +``` + +これにより以下が生まれる： +- **視覚的な明瞭さ**: 「コードのナビゲーションガイド」を即座に伝える +- **象徴的意味**: コンパス＝進路を見つける、`>`＝コード／ターミナル +- **拡張性**: 16px から 512px までどのサイズでも機能する +- **ブランドの一貫性**: 最小限のパレットで開発者ツールの美学に合致する + +--- + +## カラーシステム + +### パレット + +| 色 | Hex | RGB | 用途 | +|-------|-----|-----|-------| +| ブラック（プライマリ） | `#000000` | 0, 0, 0 | 主要ストローク、テキスト、南針 | +| ホワイト（背景） | `#FFFFFF` | 255, 255, 255 | 明るい背景 | +| グレー（セカンダリ） | `#6B7280` | 107, 114, 128 | 補助目盛り、補助テキスト | +| ブライトグリーン（アクセント） | `#22C55E` | 34, 197, 94 | 北針、中央のドット、アクセント線 | +| ニアブラック（ダーク背景） | `#0A0A0A` | 10, 10, 10 | ダークモード背景 | + +### コントラスト比（WCAG） + +- 白地に黒: **21:1** AAA +- 白地にグレー: **4.6:1** AA +- 白地にグリーン: **3.2:1**（装飾用のみ。テキストには使わない） +- ダーク地に白: **19.5:1** AAA + +### アクセントカラーのルール + +**ブライトグリーン（#22C55E）はハイライト専用：** +- コンパスの北針 +- 中央のドット +- アクセントの下線・枠線 +- 背景色には使わない +- 本文テキストには使わない + +--- + +## タイポグラフィ + +### ロゴフォント +- **ファミリー**: Inter, SF Pro Display, -apple-system, Segoe UI, sans-serif +- **「Claude」**: 42px、weight 700（bold）、ブラック +- **「How-To」**: 32px、weight 500（medium）、グレー（#6B7280） +- **サブタイトル**: 10px、weight 500、グレー、letter-spacing 1.5px、大文字 + +### インターフェイスフォント +- **ファミリー**: Inter, SF Pro, system fonts (sans-serif) +- **ウェイト**: 400〜600 +- **スタイル**: クリーンで読みやすい + +--- + +## アイコン詳細 + +### コンパス仕様 + +コンパスマークは以下の幾何要素で構成される： + +``` +Element | Stroke/Fill | Color +--------------------|----------------|------------------ +Outer ring | 3px stroke | Black / White (dark mode) +North tick | 2.5px stroke | Black / White (dark mode) +Other cardinal ticks| 2px stroke | Gray / White 50% (dark mode) +Intercardinal ticks | 1.5px stroke | Gray / White 40% (dark mode) +North needle | filled polygon | #22C55E (always green) +South needle | filled polygon | Black / White (dark mode) +> bracket | 3px stroke | Black / White (dark mode) +Center dot | filled circle | #22C55E (always green) +``` + +### サイズ別の進化 + +``` +16px → Ring + needles + chevron only (minimal) +32px → Adds cardinal tick marks +64px → Adds intercardinal tick marks +128px → Full detail, all elements crisp +256px → Maximum detail, thick strokes +``` + +--- + +## サイズ指針 + +### ロゴサイズ + +- **最小**: 幅 200px（Web 用） +- **推奨**: 520px（ネイティブサイズ） +- **最大**: 無制限（ベクター形式） +- **アスペクト比**: 約 4.3:1（幅:高さ） + +### アイコンサイズ + +- **最小**: 16px（favicon） +- **推奨**: 64〜256px（アプリ、アバター） +- **最大**: 無制限（ベクター形式） +- **アスペクト比**: 1:1（正方形） + +--- + +## スペーシングと配置 + +### ロゴのスペーシング + +``` +┌─────────────────────────────────────┐ +│ │ +│ Clear Space Minimum │ +│ (logo height / 2) │ +│ │ +│ [COMPASS] Claude │ +│ How-To │ +│ │ +└─────────────────────────────────────┘ +``` + +### アイコンの中心点 + +すべてのアイコンはキャンバス中央に揃える： +- 256px キャンバスでは 128×128 +- 128px キャンバスでは 64×64 +- 他の UI 要素との整列を維持する + +--- + +## アクセシビリティ + +### カラーコントラスト +- すべてのテキストは WCAG AA（最低 4.5:1）を満たす +- グリーンアクセントは装飾用で情報伝達には用いない +- 赤緑の色依存はない + +### 拡張性 +- ベクター形式で任意のサイズで明瞭 +- 16px でも図形が認識可能 +- 利用可能サイズに応じて段階的に詳細化 + +--- + +## 利用例 + +### Web ヘッダー +- サイズ: 520×120px のロゴ +- ファイル: `logos/claude-howto-logo.svg` +- 背景: ホワイトまたはダーク（#0A0A0A） +- パディング: 最低 20px + +### アプリアイコン +- サイズ: 256×256px +- ファイル: `icons/claude-howto-icon.svg` +- 背景: ホワイトまたはダーク +- 用途: アプリのショートカット、アバター + +### ブラウザの Favicon +- サイズ: 32px（メイン）、16px（フォールバック） +- ファイル: `favicons/favicon-32.svg` +- 形式: 鮮明な表示のため SVG + +### ソーシャルメディア +- プロフィール: 256×256px のアイコン +- バナー: 520×120px のロゴ（中央配置） + +### ドキュメント +- 章ヘッダー: ロゴを適切なサイズに調整 +- セクションアイコン: 64×64px の favicon +- インライン: 32×32px の favicon + +--- + +## ファイル形式の詳細 + +### SVG 構造 + +すべての SVG ファイルはフラットデザイン： +- グラデーションなし（単色のみ） +- フィルター効果なし（ぼかし、グロー、シャドウなし） +- クリーンなストロークと塗りの幾何学 +- レスポンシブスケーリング用の ViewBox +- 可読でコメント付きのコード + +### クロスブラウザ互換性 + +- Chrome／Edge: 完全対応 +- Firefox: 完全対応 +- Safari: 完全対応 +- iOS Safari: 完全対応 +- すべての近代的ブラウザ: 完全対応 + +--- + +## カスタマイズ + +### アクセントカラーの変更 + +別のアクセントを使うバリアントを作るには： + +1. すべての `#22C55E` を任意のアクセントカラーに置換する +2. 装飾要素のコントラスト比を 3:1 以上に保つ +3. 黒・白・グレーの構造は変えない + +### スケーリング + +```css +svg { + width: 256px; + height: 256px; +} +``` + +SVG は viewBox で自動スケールする — transform は不要。 + +--- + +## バージョン管理 + +デザイン変更を git で追跡する： +- SVG ファイルは通常通りバージョン管理する（テキスト形式） +- デザイン変更を伴うリリースにタグを付ける +- DESIGN-SYSTEM.md をコミットに含める + +--- + +**最終更新**: 2026 年 2 月 +**デザインシステムバージョン**: 3.0 diff --git a/ja/resources/QUICK-START.md b/ja/resources/QUICK-START.md new file mode 100644 index 0000000..a269b86 --- /dev/null +++ b/ja/resources/QUICK-START.md @@ -0,0 +1,92 @@ + + + +# クイックスタート — ブランドアセット + +## アセットをプロジェクトにコピーする + +```bash +# すべてのリソースを Web プロジェクトにコピー +cp -r resources/ /path/to/your/website/ + +# Web 用 favicon のみをコピー +cp resources/favicons/* /path/to/your/website/public/ +``` + +## HTML へ追加（コピー＆ペースト） + +```html + + + + + + +``` + +## Markdown／ドキュメントで使う + +```markdown +# Claude How To + +![Claude How To Logo](resources/logos/claude-howto-logo.svg) + +![Icon](resources/icons/claude-howto-icon.svg) +``` + +## 推奨サイズ + +| 用途 | サイズ | ファイル | +|---------|------|------| +| Web サイトヘッダー | 520×120 | `logos/claude-howto-logo.svg` | +| アプリアイコン | 256×256 | `icons/claude-howto-icon.svg` | +| ブラウザタブ | 32×32 | `favicons/favicon-32.svg` | +| モバイルホーム画面 | 128×128 | `favicons/favicon-128.svg` | +| デスクトップアプリ | 256×256 | `favicons/favicon-256.svg` | +| 小さなアバター | 64×64 | `favicons/favicon-64.svg` | + +## カラーコード + +```css +/* CSS でこれらを使用 */ +--color-primary: #000000; +--color-secondary: #6B7280; +--color-accent: #22C55E; +--color-bg-light: #FFFFFF; +--color-bg-dark: #0A0A0A; +``` + +## アイコンデザインの意味 + +**コードブラケット付きコンパス**: +- コンパスリング ＝ ナビゲーション、体系的な学習経路 +- 緑の北針 ＝ 方向、進捗、ガイダンス +- 黒の南針 ＝ 基盤、揺るぎない土台 +- `>` ブラケット ＝ ターミナルプロンプト、コード、CLI コンテキスト +- 目盛り ＝ 精度、体系的なステップ + +「明確なガイダンスでコードを進む道を見つける」を象徴している。 + +## どこで何を使うか + +### Web サイト +- **ヘッダー**: ロゴ（`logos/claude-howto-logo.svg`） +- **Favicon**: 32px（`favicons/favicon-32.svg`） +- **ソーシャルプレビュー**: アイコン（`icons/claude-howto-icon.svg`） + +### GitHub +- **README バッジ**: アイコン（`icons/claude-howto-icon.svg`）64〜128px +- **リポジトリアバター**: アイコン（`icons/claude-howto-icon.svg`） + +### ソーシャルメディア +- **プロフィール画像**: アイコン（`icons/claude-howto-icon.svg`） +- **バナー**: ロゴ（`logos/claude-howto-logo.svg`） +- **サムネイル**: 256×256px のアイコン + +### ドキュメント +- **章ヘッダー**: ロゴまたはアイコン（適切にスケール） +- **ナビゲーションアイコン**: Favicon（32〜64px） + +--- + +完全なドキュメントは [README.md](README.md) を参照。 diff --git a/ja/resources/README.md b/ja/resources/README.md new file mode 100644 index 0000000..9527bd1 --- /dev/null +++ b/ja/resources/README.md @@ -0,0 +1,269 @@ + + + + + + Claude How To + + +# Claude How To — ブランドアセット + +Claude How To プロジェクトのロゴ・アイコン・favicon の完全コレクション。すべて V3.0 デザインを使用：コードブラケット（`>`）付きコンパスシンボルで、コードを進む案内付きナビゲーションを表現する。ブラック／ホワイト／グレーのパレットにブライトグリーン（#22C55E）のアクセントを加えている。 + +## ディレクトリ構造 + +``` +resources/ +├── logos/ +│ ├── claude-howto-logo.svg # Main logo - Light mode (520×120px) +│ └── claude-howto-logo-dark.svg # Main logo - Dark mode (520×120px) +├── icons/ +│ ├── claude-howto-icon.svg # App icon - Light mode (256×256px) +│ └── claude-howto-icon-dark.svg # App icon - Dark mode (256×256px) +└── favicons/ + ├── favicon-16.svg # Favicon - 16×16px + ├── favicon-32.svg # Favicon - 32×32px (primary) + ├── favicon-64.svg # Favicon - 64×64px + ├── favicon-128.svg # Favicon - 128×128px + └── favicon-256.svg # Favicon - 256×256px +``` + +`assets/logo/` 内の追加アセット： +``` +assets/logo/ +├── logo-full.svg # Mark + wordmark (horizontal) +├── logo-mark.svg # Compass symbol only (120×120px) +├── logo-wordmark.svg # Text only +├── logo-icon.svg # App icon (512×512, rounded) +├── favicon.svg # 16×16 optimized +├── logo-white.svg # White version for dark backgrounds +└── logo-black.svg # Black monochrome version +``` + +## アセット概要 + +### デザインコンセプト（V3.0） + +**コードブラケット付きコンパス** — ガイダンスとコードの融合： +- **コンパスリング** ＝ ナビゲーション、進路を見つける +- **北針（グリーン）** ＝ 方向、学習経路の進捗 +- **南針（ブラック）** ＝ 基盤、揺るぎない土台 +- **`>` ブラケット** ＝ ターミナルプロンプト、コード、CLI コンテキスト +- **目盛り** ＝ 精度、体系的な学習 + +### ロゴ + +**ファイル**: +- `logos/claude-howto-logo.svg`（ライトモード） +- `logos/claude-howto-logo-dark.svg`（ダークモード） + +**仕様**: +- **サイズ**: 520×120 px +- **用途**: ワードマーク付きのメインヘッダー／ブランディングロゴ +- **使用箇所**: + - Web サイトのヘッダー + - README バッジ + - マーケティング素材 + - 印刷物 +- **形式**: SVG（完全にスケーラブル） +- **モード**: ライト（白背景）とダーク（#0A0A0A 背景） + +### アイコン + +**ファイル**: +- `icons/claude-howto-icon.svg`（ライトモード） +- `icons/claude-howto-icon-dark.svg`（ダークモード） + +**仕様**: +- **サイズ**: 256×256 px +- **用途**: アプリケーションアイコン、アバター、サムネイル +- **使用箇所**: + - アプリアイコン + - プロフィールアバター + - ソーシャルメディアサムネイル + - ドキュメントヘッダー +- **形式**: SVG（完全にスケーラブル） +- **モード**: ライト（白背景）とダーク（#0A0A0A 背景） + +**デザイン要素**: +- 主要方位および中間方位の目盛り付きコンパスリング +- 緑の北針（方向／ガイダンス） +- 黒の南針（基盤） +- 中央の `>` コードブラケット（ターミナル／CLI） +- 緑の中央ドットアクセント + +### Favicon + +Web 利用向けに複数サイズで最適化されたバージョン： + +| ファイル | サイズ | DPI | 用途 | +|------|------|-----|-------| +| `favicon-16.svg` | 16×16 px | 1x | ブラウザタブ（旧ブラウザ） | +| `favicon-32.svg` | 32×32 px | 1x | 標準ブラウザ favicon | +| `favicon-64.svg` | 64×64 px | 1x-2x | 高 DPI ディスプレイ | +| `favicon-128.svg` | 128×128 px | 2x | Apple touch icon、ブックマーク | +| `favicon-256.svg` | 256×256 px | 4x | 近代ブラウザ、PWA アイコン | + +**最適化ノート**: +- 16px: 最小限のジオメトリ — リング、針、シェブロンのみ +- 32px: 主要方位の目盛りを追加 +- 64px 以上: 中間方位の目盛りを含むフルディテール +- すべてメインアイコンとビジュアル一貫性を保つ +- SVG 形式により任意のサイズで鮮明に表示 + +## HTML 統合 + +### 基本的な favicon セットアップ + +```html + + + + + + + + + +``` + +### 完全セットアップ + +```html + + + + + + + + + + + + + + + + + +``` + +## カラーパレット + +### プライマリカラー +- **ブラック**: `#000000`（メインテキスト、ストローク、南針） +- **ホワイト**: `#FFFFFF`（ライト背景） +- **グレー**: `#6B7280`（補助テキスト、補助目盛り） + +### アクセントカラー +- **ブライトグリーン**: `#22C55E`（北針、中央ドット、アクセント線 — ハイライト専用、背景には使わない） + +### ダークモード +- **背景**: `#0A0A0A`（ニアブラック） + +### CSS 変数 +```css +--color-primary: #000000; +--color-secondary: #6B7280; +--color-accent: #22C55E; +--color-bg-light: #FFFFFF; +--color-bg-dark: #0A0A0A; +``` + +### Tailwind 設定 +```js +colors: { + brand: { + primary: '#000000', + secondary: '#6B7280', + accent: '#22C55E', + } +} +``` + +### 使用ガイドライン +- メインテキストと構造要素にはブラックを使う +- 補助・サポート要素にはグレーを使う +- グリーンは **ハイライト専用** — 針、ドット、アクセント線 +- グリーンを背景色には使わない +- WCAG AA コントラスト（最低 4.5:1）を維持する + +## デザインガイドライン + +### ロゴの使い方 +- 白またはダーク（#0A0A0A）背景に使用する +- 比率を保ってスケールする +- ロゴ周りに余白を確保する（最低: ロゴ高さの半分） +- 背景に応じて提供されているライト／ダークバリアントを使う + +### アイコンの使い方 +- 標準サイズで使う: 16、32、64、128、256px +- コンパスのプロポーションを維持する +- 比率を保ってスケールする + +### Favicon の使い方 +- 文脈に応じた適切なサイズを使う +- 16〜32px: ブラウザタブ、ブックマーク +- 64px: サイトアイコン +- 128px 以上: Apple／Android のホーム画面 + +## SVG 最適化 + +すべての SVG ファイルはグラデーションやフィルターのないフラットデザイン： +- ストロークベースのクリーンなジオメトリ +- 埋め込みラスター画像なし +- 最適化されたパス +- レスポンシブ viewBox + +Web 最適化用： +```bash +# 品質を保ちながら SVG を圧縮 +svgo --config='{ + "js2svg": { + "indent": 2 + }, + "plugins": [ + "convertStyleToAttrs", + "removeRasterImages" + ] +}' input.svg -o output.svg +``` + +## PNG 変換 + +旧ブラウザ対応のため SVG を PNG に変換するには： + +```bash +# ImageMagick を使う +convert -density 300 -background none favicon-256.svg favicon-256.png + +# Inkscape を使う +inkscape -D -z --file=favicon-256.svg --export-png=favicon-256.png +``` + +## アクセシビリティ + +- 高コントラスト比（WCAG AA 準拠 — 最低 4.5:1） +- どのサイズでも認識できるクリーンな幾何学形状 +- スケーラブルなベクター形式 +- アイコン内にテキストを含まない（テキストはワードマークで別途追加） +- 意味伝達における赤緑の色依存なし + +## 帰属 + +これらのアセットは Claude How To プロジェクトの一部である。 + +**ライセンス**: MIT（プロジェクトの LICENSE ファイルを参照） + +## バージョン履歴 + +- **v3.0**（2026 年 2 月）: ブラック／ホワイト／グレー＋グリーンアクセントのパレットによるコンパス・ブラケットデザイン +- **v2.0**（2026 年 1 月）: エメラルドパレットの 12 光線スターバーストデザイン（Claude にインスパイアされたもの） +- **v1.0**（2026 年 1 月）: ヘキサゴンベースの進捗アイコンの初期デザイン + +--- + +**最終更新**: 2026 年 2 月 +**現バージョン**: 3.0（コンパス・ブラケット） +**全アセット**: 本番利用可能な SVG、完全スケーラブル、WCAG AA 準拠 diff --git a/ja/scripts/README.md b/ja/scripts/README.md new file mode 100644 index 0000000..2d4f377 --- /dev/null +++ b/ja/scripts/README.md @@ -0,0 +1,123 @@ + + + + + + Claude How To + + +# EPUB ビルダースクリプト + +Claude How-To の Markdown ファイル群から EPUB 形式の電子書籍をビルドするスクリプト。 + +## 特徴 + +- フォルダ構成（01-slash-commands、02-memory など）に沿って章を整理する +- Mermaid 図を Kroki.io API 経由で PNG 画像としてレンダリングする +- 非同期並行取得 — すべての図を並列にレンダリングする +- プロジェクトロゴから表紙画像を生成する +- 内部 Markdown リンクを EPUB の章参照へ変換する +- 厳格モード — レンダリング不能な図があればビルドを失敗させる + +## 必要環境 + +- Python 3.10+ +- [uv](https://github.com/astral-sh/uv) +- Mermaid 図レンダリング用のインターネット接続 + +## クイックスタート + +```bash +# 最も簡単な方法 — uv がすべてを処理する +uv run scripts/build_epub.py +``` + +## 開発環境セットアップ + +```bash +# 仮想環境を作成 +uv venv + +# 有効化して依存関係をインストール +source .venv/bin/activate +uv pip install -r requirements-dev.txt + +# テストを実行 +pytest scripts/tests/ -v + +# スクリプトを実行 +python scripts/build_epub.py +``` + +## コマンドラインオプション + +``` +usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose] + [--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT] + +options: + -h, --help show this help message and exit + --root, -r ROOT Root directory (default: repo root) + --output, -o OUTPUT Output path (default: claude-howto-guide.epub) + --verbose, -v Enable verbose logging + --timeout TIMEOUT API timeout in seconds (default: 30) + --max-concurrent N Max concurrent requests (default: 10) +``` + +## 使用例 + +```bash +# 詳細ログ付きでビルド +uv run scripts/build_epub.py --verbose + +# 出力先をカスタマイズ +uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub + +# 並行リクエスト数を制限（レート制限を受ける場合） +uv run scripts/build_epub.py --max-concurrent 5 +``` + +## 出力 + +リポジトリのルートディレクトリに `claude-howto-guide.epub` を生成する。 + +EPUB には次が含まれる： +- プロジェクトロゴ付きの表紙画像 +- ネストされた目次 +- すべての Markdown コンテンツを EPUB 互換 HTML に変換したもの +- PNG 画像としてレンダリングされた Mermaid 図 + +## テストの実行 + +```bash +# 仮想環境を使う場合 +source .venv/bin/activate +pytest scripts/tests/ -v + +# または uv で直接実行 +uv run --with pytest --with pytest-asyncio \ + --with ebooklib --with markdown --with beautifulsoup4 \ + --with httpx --with pillow --with tenacity \ + pytest scripts/tests/ -v +``` + +## 依存関係 + +PEP 723 のインラインスクリプトメタデータで管理する： + +| パッケージ | 用途 | +|---------|---------| +| `ebooklib` | EPUB 生成 | +| `markdown` | Markdown から HTML への変換 | +| `beautifulsoup4` | HTML パース | +| `httpx` | 非同期 HTTP クライアント | +| `pillow` | 表紙画像生成 | +| `tenacity` | リトライ処理 | + +## トラブルシューティング + +**ネットワークエラーでビルドが失敗する**: インターネット接続と Kroki.io の稼働状況を確認する。`--timeout 60` を試す。 + +**レート制限**: `--max-concurrent 3` で並行リクエスト数を減らす。 + +**ロゴが見つからない**: `claude-howto-logo.png` が見つからない場合、スクリプトはテキストのみの表紙を生成する。 diff --git a/scripts/build_epub.py b/scripts/build_epub.py index a0c7f35..d5d39c7 100755 --- a/scripts/build_epub.py +++ b/scripts/build_epub.py @@ -115,6 +115,8 @@ class EPUBConfig: en_subtitle: str = "Master Claude Code in a Weekend" zh_title: str = "Claude Code 使用指南" zh_subtitle: str = "一个周末掌握 Claude Code" + ja_title: str = "Claude Code ハウツーガイド" + ja_subtitle: str = "週末で Claude Code をマスターする" # Cover Settings cover_width: int = 600 @@ -1059,10 +1061,10 @@ def main() -> int: "--lang", type=str, default="en", - choices=["en", "vi", "zh"], + choices=["en", "vi", "zh", "ja"], help=( "Language code: 'en' for English, 'vi' for Vietnamese, " - "'zh' for Chinese (default: en)" + "'zh' for Chinese, 'ja' for Japanese (default: en)" ), ) parser.add_argument( @@ -1084,6 +1086,7 @@ def main() -> int: "en": (repo_root, "claude-howto-guide.epub", EPUBConfig.en_title), "vi": (repo_root / "vi", "claude-howto-guide-vi.epub", EPUBConfig.vi_title), "zh": (repo_root / "zh", "claude-howto-guide-zh.epub", EPUBConfig.zh_title), + "ja": (repo_root / "ja", "claude-howto-guide-ja.epub", EPUBConfig.ja_title), } root, default_output_name, title = lang_map[args.lang] output = args.output or (repo_root / default_output_name)