mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-06-05 22:36:34 +02:00
JiangCheng
1d1df9235b
- 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).
386 lines
13 KiB
Markdown
386 lines
13 KiB
Markdown
<!-- i18n-source: CONTRIBUTING.md -->
|
||
<!-- i18n-source-sha: 7f2e773 -->
|
||
<!-- i18n-date: 2026-04-27 -->
|
||
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
|
||
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
|
||
</picture>
|
||
|
||
# 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
|