From 1d1df9235bf552adeb0e22e0f6ee82e901535481 Mon Sep 17 00:00:00 2001 From: JiangCheng <99238517+Foxsunshine@users.noreply.github.com> Date: Thu, 30 Apr 2026 07:16:46 +0900 Subject: [PATCH] feat(i18n): Add Japanese (ja/) translation (#105) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Translate all 101 markdown files: P1 core, all 10 modules, examples, auxiliary docs (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CLAUDE.md, etc.), peripheral docs (.github/, docs/, resources/, scripts/) - Translate comments and user-facing messages in 06-hooks/*.sh examples - Copy 05-mcp/*.json examples (standard JSON, no comments) - Update root README.md language switcher to include 日本語 - Add ja/TRANSLATION_NOTES.md (glossary + style guide) All translations pass pre-commit quality gates (markdown-lint, cross-references, mermaid-syntax, link-check, build-epub). --- .pre-commit-config.yaml | 41 + README.md | 2 +- ja/.github/ISSUE_TEMPLATE/bug_report.md | 46 + ja/.github/ISSUE_TEMPLATE/documentation.md | 47 + ja/.github/ISSUE_TEMPLATE/feature_request.md | 49 + ja/.github/ISSUE_TEMPLATE/question.md | 43 + ja/.github/SECURITY_REPORTING.md | 312 ++ ja/.github/TESTING.md | 344 ++ ja/.github/pull_request_template.md | 60 + ja/01-slash-commands/README.md | 618 ++++ ja/01-slash-commands/commit.md | 33 + ja/01-slash-commands/doc-refactor.md | 31 + ja/01-slash-commands/generate-api-docs.md | 26 + ja/01-slash-commands/optimize.md | 26 + ja/01-slash-commands/pr.md | 33 + ja/01-slash-commands/push-all.md | 160 + ja/01-slash-commands/setup-ci-cd.md | 32 + ja/01-slash-commands/unit-test-expand.md | 32 + ja/02-memory/README.md | 1212 +++++++ ja/02-memory/directory-api-CLAUDE.md | 68 + ja/02-memory/personal-CLAUDE.md | 67 + ja/02-memory/project-CLAUDE.md | 95 + ja/03-skills/README.md | 832 +++++ ja/03-skills/blog-draft/SKILL.md | 278 ++ .../blog-draft/templates/draft-template.md | 71 + .../blog-draft/templates/outline-template.md | 101 + ja/03-skills/brand-voice/SKILL.md | 76 + ja/03-skills/brand-voice/tone-examples.md | 17 + ja/03-skills/claude-md/SKILL.md | 215 ++ ja/03-skills/code-review/SKILL.md | 74 + .../code-review/templates/finding-template.md | 116 + .../code-review/templates/review-checklist.md | 51 + ja/03-skills/doc-generator/SKILL.md | 80 + ja/03-skills/refactor/SKILL.md | 429 +++ .../refactor/references/code-smells.md | 672 ++++ .../references/refactoring-catalog.md | 1027 ++++++ .../refactor/templates/refactoring-plan.md | 287 ++ ja/04-subagents/README.md | 1251 +++++++ ja/04-subagents/clean-code-reviewer.md | 76 + ja/04-subagents/code-reviewer.md | 72 + ja/04-subagents/data-scientist.md | 106 + ja/04-subagents/debugger.md | 89 + ja/04-subagents/documentation-writer.md | 107 + ja/04-subagents/implementation-agent.md | 89 + ja/04-subagents/performance-optimizer.md | 140 + ja/04-subagents/secure-reviewer.md | 84 + ja/04-subagents/test-engineer.md | 83 + ja/05-mcp/README.md | 1124 ++++++ ja/05-mcp/database-mcp.json | 11 + ja/05-mcp/filesystem-mcp.json | 8 + ja/05-mcp/github-mcp.json | 11 + ja/05-mcp/multi-mcp.json | 29 + ja/06-hooks/README.md | 1369 +++++++ ja/06-hooks/dependency-check.sh | 156 + ja/06-hooks/format-code.sh | 49 + ja/06-hooks/log-bash.sh | 31 + ja/06-hooks/notify-team.sh | 68 + ja/06-hooks/pre-commit.sh | 50 + ja/06-hooks/pre-tool-check.sh | 128 + ja/06-hooks/security-scan.sh | 78 + ja/06-hooks/session-end.sh | 94 + ja/06-hooks/validate-prompt.sh | 54 + ja/07-plugins/README.md | 1048 ++++++ ja/07-plugins/devops-automation/README.md | 120 + .../agents/alert-analyzer.md | 18 + .../agents/deployment-specialist.md | 18 + .../agents/incident-commander.md | 18 + .../devops-automation/commands/deploy.md | 19 + .../devops-automation/commands/incident.md | 20 + .../devops-automation/commands/rollback.md | 18 + .../devops-automation/commands/status.md | 19 + ja/07-plugins/documentation/README.md | 132 + .../documentation/agents/api-documenter.md | 18 + .../documentation/agents/code-commentator.md | 18 + .../documentation/agents/example-generator.md | 18 + .../commands/generate-api-docs.md | 19 + .../documentation/commands/generate-readme.md | 19 + .../documentation/commands/sync-docs.md | 18 + .../documentation/commands/validate-docs.md | 18 + .../documentation/templates/adr-template.md | 43 + .../documentation/templates/api-endpoint.md | 105 + .../documentation/templates/function-docs.md | 54 + ja/07-plugins/pr-review/README.md | 104 + .../pr-review/agents/performance-analyzer.md | 17 + .../pr-review/agents/security-reviewer.md | 17 + .../pr-review/agents/test-checker.md | 17 + .../pr-review/commands/check-security.md | 18 + .../pr-review/commands/check-tests.md | 18 + ja/07-plugins/pr-review/commands/review-pr.md | 18 + ja/08-checkpoints/README.md | 338 ++ ja/08-checkpoints/checkpoint-examples.md | 346 ++ ja/09-advanced-features/README.md | 2179 ++++++++++++ .../planning-mode-examples.md | 540 +++ ja/10-cli/README.md | 887 +++++ ja/CATALOG.md | 544 +++ ja/CHANGELOG.md | 192 + ja/CLAUDE.md | 161 + ja/CODE_OF_CONDUCT.md | 224 ++ ja/CONTRIBUTING.md | 385 ++ ja/INDEX.md | 893 +++++ ja/LEARNING-ROADMAP.md | 757 ++++ ja/QUICK_REFERENCE.md | 519 +++ ja/README.md | 885 +++++ ja/RELEASE_NOTES.md | 15 + ja/SECURITY.md | 338 ++ ja/STYLE_GUIDE.md | 646 ++++ ja/TRANSLATION_NOTES.md | 423 +++ ja/claude_concepts_guide.md | 3161 +++++++++++++++++ ja/clean-code-rules.md | 115 + ja/docs/ROADMAP-20260401.md | 156 + ja/docs/TASKS-20260401.md | 294 ++ ja/prompts/remotion-video.md | 356 ++ ja/resources.md | 262 ++ ja/resources/DESIGN-SYSTEM.md | 247 ++ ja/resources/QUICK-START.md | 92 + ja/resources/README.md | 269 ++ ja/scripts/README.md | 123 + scripts/build_epub.py | 7 +- 118 files changed, 30380 insertions(+), 3 deletions(-) create mode 100644 ja/.github/ISSUE_TEMPLATE/bug_report.md create mode 100644 ja/.github/ISSUE_TEMPLATE/documentation.md create mode 100644 ja/.github/ISSUE_TEMPLATE/feature_request.md create mode 100644 ja/.github/ISSUE_TEMPLATE/question.md create mode 100644 ja/.github/SECURITY_REPORTING.md create mode 100644 ja/.github/TESTING.md create mode 100644 ja/.github/pull_request_template.md create mode 100644 ja/01-slash-commands/README.md create mode 100644 ja/01-slash-commands/commit.md create mode 100644 ja/01-slash-commands/doc-refactor.md create mode 100644 ja/01-slash-commands/generate-api-docs.md create mode 100644 ja/01-slash-commands/optimize.md create mode 100644 ja/01-slash-commands/pr.md create mode 100644 ja/01-slash-commands/push-all.md create mode 100644 ja/01-slash-commands/setup-ci-cd.md create mode 100644 ja/01-slash-commands/unit-test-expand.md create mode 100644 ja/02-memory/README.md create mode 100644 ja/02-memory/directory-api-CLAUDE.md create mode 100644 ja/02-memory/personal-CLAUDE.md create mode 100644 ja/02-memory/project-CLAUDE.md create mode 100644 ja/03-skills/README.md create mode 100644 ja/03-skills/blog-draft/SKILL.md create mode 100644 ja/03-skills/blog-draft/templates/draft-template.md create mode 100644 ja/03-skills/blog-draft/templates/outline-template.md create mode 100644 ja/03-skills/brand-voice/SKILL.md create mode 100644 ja/03-skills/brand-voice/tone-examples.md create mode 100644 ja/03-skills/claude-md/SKILL.md create mode 100644 ja/03-skills/code-review/SKILL.md create mode 100644 ja/03-skills/code-review/templates/finding-template.md create mode 100644 ja/03-skills/code-review/templates/review-checklist.md create mode 100644 ja/03-skills/doc-generator/SKILL.md create mode 100644 ja/03-skills/refactor/SKILL.md create mode 100644 ja/03-skills/refactor/references/code-smells.md create mode 100644 ja/03-skills/refactor/references/refactoring-catalog.md create mode 100644 ja/03-skills/refactor/templates/refactoring-plan.md create mode 100644 ja/04-subagents/README.md create mode 100644 ja/04-subagents/clean-code-reviewer.md create mode 100644 ja/04-subagents/code-reviewer.md create mode 100644 ja/04-subagents/data-scientist.md create mode 100644 ja/04-subagents/debugger.md create mode 100644 ja/04-subagents/documentation-writer.md create mode 100644 ja/04-subagents/implementation-agent.md create mode 100644 ja/04-subagents/performance-optimizer.md create mode 100644 ja/04-subagents/secure-reviewer.md create mode 100644 ja/04-subagents/test-engineer.md create mode 100644 ja/05-mcp/README.md create mode 100644 ja/05-mcp/database-mcp.json create mode 100644 ja/05-mcp/filesystem-mcp.json create mode 100644 ja/05-mcp/github-mcp.json create mode 100644 ja/05-mcp/multi-mcp.json create mode 100644 ja/06-hooks/README.md create mode 100755 ja/06-hooks/dependency-check.sh create mode 100644 ja/06-hooks/format-code.sh create mode 100644 ja/06-hooks/log-bash.sh create mode 100644 ja/06-hooks/notify-team.sh create mode 100644 ja/06-hooks/pre-commit.sh create mode 100644 ja/06-hooks/pre-tool-check.sh create mode 100644 ja/06-hooks/security-scan.sh create mode 100755 ja/06-hooks/session-end.sh create mode 100644 ja/06-hooks/validate-prompt.sh create mode 100644 ja/07-plugins/README.md create mode 100644 ja/07-plugins/devops-automation/README.md create mode 100644 ja/07-plugins/devops-automation/agents/alert-analyzer.md create mode 100644 ja/07-plugins/devops-automation/agents/deployment-specialist.md create mode 100644 ja/07-plugins/devops-automation/agents/incident-commander.md create mode 100644 ja/07-plugins/devops-automation/commands/deploy.md create mode 100644 ja/07-plugins/devops-automation/commands/incident.md create mode 100644 ja/07-plugins/devops-automation/commands/rollback.md create mode 100644 ja/07-plugins/devops-automation/commands/status.md create mode 100644 ja/07-plugins/documentation/README.md create mode 100644 ja/07-plugins/documentation/agents/api-documenter.md create mode 100644 ja/07-plugins/documentation/agents/code-commentator.md create mode 100644 ja/07-plugins/documentation/agents/example-generator.md create mode 100644 ja/07-plugins/documentation/commands/generate-api-docs.md create mode 100644 ja/07-plugins/documentation/commands/generate-readme.md create mode 100644 ja/07-plugins/documentation/commands/sync-docs.md create mode 100644 ja/07-plugins/documentation/commands/validate-docs.md create mode 100644 ja/07-plugins/documentation/templates/adr-template.md create mode 100644 ja/07-plugins/documentation/templates/api-endpoint.md create mode 100644 ja/07-plugins/documentation/templates/function-docs.md create mode 100644 ja/07-plugins/pr-review/README.md create mode 100644 ja/07-plugins/pr-review/agents/performance-analyzer.md create mode 100644 ja/07-plugins/pr-review/agents/security-reviewer.md create mode 100644 ja/07-plugins/pr-review/agents/test-checker.md create mode 100644 ja/07-plugins/pr-review/commands/check-security.md create mode 100644 ja/07-plugins/pr-review/commands/check-tests.md create mode 100644 ja/07-plugins/pr-review/commands/review-pr.md create mode 100644 ja/08-checkpoints/README.md create mode 100644 ja/08-checkpoints/checkpoint-examples.md create mode 100644 ja/09-advanced-features/README.md create mode 100644 ja/09-advanced-features/planning-mode-examples.md create mode 100644 ja/10-cli/README.md create mode 100644 ja/CATALOG.md create mode 100644 ja/CHANGELOG.md create mode 100644 ja/CLAUDE.md create mode 100644 ja/CODE_OF_CONDUCT.md create mode 100644 ja/CONTRIBUTING.md create mode 100644 ja/INDEX.md create mode 100644 ja/LEARNING-ROADMAP.md create mode 100644 ja/QUICK_REFERENCE.md create mode 100644 ja/README.md create mode 100644 ja/RELEASE_NOTES.md create mode 100644 ja/SECURITY.md create mode 100644 ja/STYLE_GUIDE.md create mode 100644 ja/TRANSLATION_NOTES.md create mode 100644 ja/claude_concepts_guide.md create mode 100644 ja/clean-code-rules.md create mode 100644 ja/docs/ROADMAP-20260401.md create mode 100644 ja/docs/TASKS-20260401.md create mode 100644 ja/prompts/remotion-video.md create mode 100644 ja/resources.md create mode 100644 ja/resources/DESIGN-SYSTEM.md create mode 100644 ja/resources/QUICK-START.md create mode 100644 ja/resources/README.md create mode 100644 ja/scripts/README.md 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)