feat(i18n): Add Japanese (ja/) translation (#105)

- 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).
2026-04-30 07:16:46 +09:00
parent 32212292df
commit 1d1df9235b
118 changed files with 30380 additions and 3 deletions
--- a/ja/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/ja/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,46 @@
+<!-- i18n-source: .github/ISSUE_TEMPLATE/bug_report.md -->
+<!-- i18n-source-sha: 5fd984a -->
+<!-- i18n-date: 2026-04-27 -->
+---
+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 など）
+
+## サンプルコード
+該当する場合、動作しないサンプルコードを記載してほしい。
+```
+[ここにコードを挿入]
+```
+
+## スクリーンショット
+該当する場合、問題を示すスクリーンショットを添付してほしい。
+
+## 補足情報
+問題の理解に役立つその他の情報があれば。
+
+## 解決案
+修正方法の案があれば共有してほしい。
--- a/ja/.github/ISSUE_TEMPLATE/documentation.md
+++ b/ja/.github/ISSUE_TEMPLATE/documentation.md
@@ -0,0 +1,47 @@
+<!-- i18n-source: .github/ISSUE_TEMPLATE/documentation.md -->
+<!-- i18n-source-sha: 59a87f1 -->
+<!-- i18n-date: 2026-04-27 -->
+---
+name: Documentation Issue
+about: 不明瞭なドキュメント、誤字、情報の欠落を報告する
+title: "[DOCS] "
+labels: documentation
+assignees: ''
+
+---
+
+## 問題の種類
+- [ ] 誤字または文法ミス
+- [ ] 説明が不明瞭
+- [ ] 情報の欠落
+- [ ] リンク切れまたは参照切れ
+- [ ] 内容が古い
+- [ ] より良い例が必要
+
+## 場所
+どのセクションに問題があるか。
+- **ファイル**: （例: README.md、03-skills/README.md）
+- **セクション**: （例: 「Installation Quick Reference」）
+- **行・領域**: （特定できる場合）
+
+## 現在の内容
+現状はどう書かれているか。
+```
+[現在の文章をここに貼り付け]
+```
+
+## 問題の説明
+何が問題か。
+
+## 改善案
+どう改善・明確化できるか。
+```
+[改善後の文章や提案をここに記載]
+```
+
+## なぜ重要か
+この問題がユーザーにどう影響するか。
+
+## 関連ドキュメント
+関連セクションへのリンク。
+- 関連ガイド: <!-- ここにリンクを追加 -->
--- a/ja/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/ja/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,49 @@
+<!-- i18n-source: .github/ISSUE_TEMPLATE/feature_request.md -->
+<!-- i18n-source-sha: 59a87f1 -->
+<!-- i18n-date: 2026-04-27 -->
+---
+name: Feature Request
+about: 新しいサンプル、ガイド、改善案を提案する
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+
+---
+
+## 概要
+追加してほしい機能や改善内容を記述する。
+
+## 解決する課題
+どのような課題やギャップに対応するか。
+
+例：
+- X 機能のサンプルがない
+- Y のドキュメントが不明瞭
+- Z のユースケースのガイドが必要
+- 構造を以下のように改善できる…
+
+## ユースケース
+いつ・どのように使うか。実際のシナリオを含める。
+
+## 解決案
+どのように実装・ドキュメント化すべきか。
+
+## 例
+該当する場合、想定する例を記載してほしい。
+```
+[ここに例を挿入]
+```
+
+## 関連サンプル
+既存の関連サンプルやガイドへのリンク。
+- 既存ガイド: <!-- ここにリンクを追加 -->
+- 機能: （例: Skills、Hooks、Subagents）
+
+## 補足情報
+他に役立つ情報があれば。
+
+## 受け入れ基準
+この機能が完成したと判断する基準は何か。
+- [ ] 基準 1
+- [ ] 基準 2
+- [ ] 基準 3
--- a/ja/.github/ISSUE_TEMPLATE/question.md
+++ b/ja/.github/ISSUE_TEMPLATE/question.md
@@ -0,0 +1,43 @@
+<!-- i18n-source: .github/ISSUE_TEMPLATE/question.md -->
+<!-- i18n-source-sha: 5fd984a -->
+<!-- i18n-date: 2026-04-27 -->
+---
+name: Question
+about: Claude Code または本ガイドに関する質問をする
+title: "[QUESTION] "
+labels: question
+assignees: ''
+
+---
+
+## 質問
+何を知りたいか。
+
+## 背景
+質問の背景・文脈を記載してほしい。
+- 何を実現しようとしているか
+- すでに何を試したか
+- どのサンプル・ガイドを参照したか
+
+## 関連トピック
+どのトピックに関する質問か。
+- [ ] スラッシュコマンド
+- [ ] メモリ
+- [ ] スキル
+- [ ] サブエージェント
+- [ ] MCP プロトコル
+- [ ] フック
+- [ ] プラグイン
+- [ ] チェックポイント
+- [ ] 高度な機能
+- [ ] CLI リファレンス
+- [ ] その他
+
+## 試したこと
+すでに試したことがあれば、その結果を記載してほしい。
+
+## 期待する成果
+何があれば解決に役立つか。
+
+## 関連リソース
+関連しそうなリンクやリソースがあれば。
--- a/ja/.github/SECURITY_REPORTING.md
+++ b/ja/.github/SECURITY_REPORTING.md
@@ -0,0 +1,312 @@
+<!-- i18n-source: .github/SECURITY_REPORTING.md -->
+<!-- i18n-source-sha: 6d1e0ae -->
+<!-- i18n-date: 2026-04-27 -->
+# セキュリティ脆弱性の報告
+
+このファイルは、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)
+
+---
+
+本プロジェクトのセキュリティ向上に協力してくれてありがとう！🔒
--- a/ja/.github/TESTING.md
+++ b/ja/.github/TESTING.md
@@ -0,0 +1,344 @@
+<!-- i18n-source: .github/TESTING.md -->
+<!-- i18n-source-sha: 728bd50 -->
+<!-- i18n-date: 2026-04-27 -->
+# テストガイド
+
+本ドキュメントは 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 を開いてほしい。
--- a/ja/.github/pull_request_template.md
+++ b/ja/.github/pull_request_template.md
@@ -0,0 +1,60 @@
+<!-- i18n-source: .github/pull_request_template.md -->
+<!-- i18n-source-sha: 5fd984a -->
+<!-- i18n-date: 2026-04-27 -->
+## 概要
+この PR が何をするのかを簡潔にまとめる。
+
+## 変更の種類
+- [ ] 新しいサンプルまたはテンプレート
+- [ ] ドキュメント改善
+- [ ] バグ修正
+- [ ] 機能ガイド
+- [ ] その他（記述してほしい）
+
+## 関連 Issue
+Closes #(issue 番号)
+
+## 変更内容
+- 変更 1
+- 変更 2
+- 変更 3
+
+## レビューの観点
+レビュアーが特に注目すべき点は何か。
+
+## 変更ファイル
+- `path/to/file1.md`
+- `path/to/file2.md`
+
+## テスト
+どのようにテストしたか。
+- [ ] Claude Code でローカルにテスト済み
+- [ ] サンプルが動作することを確認済み
+- [ ] リンク・参照を確認済み
+- [ ] 誤字・読みやすさを確認済み
+
+## チェックリスト
+- [ ] プロジェクトの構造・規約に従っている
+- [ ] 明確なドキュメント・サンプルを含む
+- [ ] コード・サンプルがコピペで利用可能
+- [ ] すべてのリンクが検証済みで動作する
+- [ ] 機密情報を含まない（鍵、トークン、認証情報など）
+- [ ] 関連する README を更新済み
+- [ ] コミットメッセージが Conventional Commits に従っている
+- [ ] 大きいファイル（1MB 超）を追加していない
+
+## スクリーンショット・例
+該当する場合、追加内容を提示してほしい。
+```
+[サンプルコードまたは前後比較]
+```
+
+## 破壊的変更
+既存のコンテンツや動作を変更するか。
+- [ ] 破壊的変更なし
+- [ ] あり、下記に記載
+
+ある場合、内容を記載してほしい。
+
+## 補足
+レビュアー向けの追加情報があれば。