claude-howto/ja/STYLE_GUIDE.md

スタイルガイド

Claude How To にコントリビュートする際の規約とフォーマットルール。コンテンツを一貫した、プロフェッショナルで保守しやすい状態に保つため、本ガイドに従うこと。

※日本語訳における文体・用語ルールについては TRANSLATION_NOTES.md も参照。

---

目次

• ファイルとフォルダの命名
• ドキュメント構造
• 見出し
• テキストフォーマット
• リスト
• テーブル
• コードブロック
• リンクと相互参照
• 図
• 絵文字の使い方
• 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. ロゴ（ダーク／ライト両対応の <picture> 要素）
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. カスタマイズのヒント

セクション区切り

主要なドキュメント領域を区切るために水平線（---）を使う：

---

## 新しい主要セクション

導入のブロッククォートの後と、論理的に異なる部分の間に配置する。

---

見出し

階層

レベル	用途	例
# 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`

コールアウト用ブロッククォート

重要な注意にはボールドプレフィックス付きのブロッククォートを使う：

> **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 スペースのインデントでネストする：

- 最初の項目
- 2 番目の項目
  - ネスト項目
  - もう 1 つのネスト項目
    - 深いネスト（3 階層より深くしない）
- 3 番目の項目

番号付きリスト

順序のあるステップ、手順、ランク付け項目には番号付きリストを使う：

1. 最初のステップ
2. 2 番目のステップ
   - サブポイントの詳細
   - もう 1 つのサブポイント
3. 3 番目のステップ

説明型リスト

キー・バリュー形式のリストにはボールドラベルを使う：

- **パフォーマンスのボトルネック** - O(n^2) の操作、非効率なループを特定する
- **メモリリーク** - 解放されていないリソース、循環参照を発見する
- **アルゴリズム改善** - よりよいアルゴリズムやデータ構造を提案する

ルール

• 一貫したインデントを保つ（1 階層につき 2 スペース）
• リストの前後に空行を入れる
• リスト項目は構造を揃える（すべて動詞で始める、またはすべて名詞、など）
• 3 階層より深いネストは避ける

---

テーブル

標準フォーマット

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |

よくあるテーブルパターン

機能比較（3〜4 列）：

| Feature | Invocation | Persistence | Best For |
|---------|-----------|------------|----------|
| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
| **Memory** | Auto-loaded | Cross-session | Long-term learning |

Do と Don't：

| Do | Don't |
|----|-------|
| Use descriptive names | Use vague names |
| Keep files focused | Overload a single file |

クイックリファレンス：

| 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	データベースクエリ
プレーンテキスト	（タグなし）	期待される出力、ディレクトリツリー

規約

# コマンドの動作を説明するコメント
claude mcp add notion --transport http https://mcp.notion.com/mcp

• 自明でないコマンドの前に コメント行 を追加する
• すべての例を コピー＆ペースト可能 にする
• 関連するときは シンプル版と高度版の両方 を示す
• 理解の助けとなる場合は 期待される出力 を含める（タグなしのコードブロックを使う）

インストールブロック

インストール手順には以下のパターンを使う：

# プロジェクトにファイルをコピー
cp 01-slash-commands/*.md .claude/commands/

複数ステップのワークフロー

# Step 1: ディレクトリを作成
mkdir -p .claude/commands

# Step 2: テンプレートをコピー
cp 01-slash-commands/*.md .claude/commands/

# Step 3: インストールを確認
ls .claude/commands/

---

リンクと相互参照

内部リンク（相対）

すべての内部リンクは相対パスを使う：

[Slash Commands](01-slash-commands/)
[Skills Guide](03-skills/)
[Memory Architecture](02-memory/#memory-architecture)

レッスンフォルダからルートまたは兄弟へ：

[Back to main guide](../README.md)
[Related: Skills](../03-skills/)

外部リンク（絶対）

説明的なアンカーテキストを伴う完全 URL を使う：

[Anthropic's official documentation](https://code.claude.com/docs/en/overview)

• アンカーテキストに「click here」「this link」を使わない
• 文脈外でも意味が通る記述的なテキストを使う

セクションアンカー

GitHub スタイルのアンカーで同一文書内のセクションへリンクする：

[Feature Catalog](#-feature-catalog)
[Best Practices](#best-practices)

関連ガイドのパターン

レッスンの末尾に関連ガイドのセクションを置く：

## 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 — 時系列

スタイル規約

スタイルブロックで一貫した色を適用する：

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"] を使う（特殊文字を許可）
• ラベル内の改行には <br/> を使う
• 図はシンプルに保つ（最大 10〜12 ノード）
• アクセシビリティのため図の下に簡潔なテキスト説明を追加する
• 階層には上から下（TB）、ワークフローには左から右（LR）を使う

---

絵文字の使い方

絵文字を使う場所

絵文字は 控えめかつ目的を持って 使う — 特定のコンテキストでのみ：

コンテキスト	絵文字	例
ルート README のセクションヘッダ	カテゴリアイコン	## 📚 Learning Path
スキルレベル指標	色付き丸	🟢 初心者、🔵 中級者、🔴 上級者
Do と Don't	チェック／クロスマーク	✅ こうする、❌ こうしない
複雑さ評価	星	⭐⭐⭐

標準絵文字セット

絵文字	意味
📚	学習、ガイド、ドキュメント
⚡	はじめに、クイックリファレンス
🎯	機能、クイックリファレンス
🎓	学習パス
📊	統計、比較
🚀	インストール、クイックコマンド
🟢	初心者レベル
🔵	中級者レベル
🔴	上級者レベル
✅	推奨される慣行
❌	避ける／アンチパターン
⭐	複雑さ評価の単位

ルール

• 本文や段落で絵文字を使わない
• ヘッダで絵文字を使うのは ルート README のみ（レッスン README では使わない）
• 装飾的な絵文字を追加しない — どの絵文字も意味を伝えるべき
• 絵文字の使い方は上記の表と一貫させる

---

YAML フロントマター

機能ファイル（スキル、コマンド、エージェント）

---
name: unique-identifier
description: What this feature does and when to use it
allowed-tools: Bash, Read, Grep
---

任意フィールド

---
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 文に保つ
• 必要なフィールドのみを含める

---

画像とメディア

ロゴパターン

ロゴで始まる文書はすべて、ダーク／ライトモード対応のために <picture> 要素を使う：

<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>

スクリーンショット

• 関連するレッスンフォルダに保存する（例：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 に従う：

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 はメタデータブロックで終わる：

---
**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