CLAUDE.md

1<!-- i18n-source: CLAUDE.md -->
2<!-- i18n-source-sha: a70777e -->
3<!-- i18n-date: 2026-04-27 -->
4 
5# CLAUDE.md
6 
7このファイルは、本リポジトリ内のコードを扱う際の Claude Code（claude.ai/code）向けガイドである。
8 
9## プロジェクト概要
10 
11Claude How To は Claude Code 機能のチュートリアルリポジトリである。これは **ドキュメント・アズ・コード** であり、主な成果物は実行可能アプリケーションではなく、番号付きの学習モジュールに整理された Markdown ファイルである。
12 
13**アーキテクチャ：** 各モジュール（01〜10）は Claude Code の特定の機能を、コピー＆ペースト可能なテンプレート、Mermaid 図、サンプルとともに解説する。ビルドシステムはドキュメントの品質を検証し、EPUB 電子書籍を生成する。
14 
15## よく使うコマンド
16 
17### pre-commit 品質チェック
18 
19すべてのドキュメントは、コミット前に 5 つの品質チェックを通過しなければならない（pre-commit フックで自動実行される）：
20 
21```bash
22# pre-commit フックをインストール（毎コミットで実行）
23pre-commit install
24 
25# 全チェックを手動で実行
26pre-commit run --all-files
27```
28 
295 つのチェックは以下のとおり：
301. **markdown-lint** — `markdownlint` による Markdown 構造とフォーマット
312. **cross-references** — 内部リンク、アンカー、コードフェンスの構文（Python スクリプト）
323. **mermaid-syntax** — すべての Mermaid 図が正しくパースされるかを検証（Python スクリプト）
334. **link-check** — 外部 URL が到達可能か（Python スクリプト）
345. **markdown-rendering** — Markdown が壊れずにレンダリングされるか（Python スクリプト）
35 
36EPUB ビルドは pre-commit フック **ではない** — CI のみで実行される（`.github/workflows/test.yml` の `build-epub` ジョブ）。ローカルの `mmdc` バイナリが必要であり、arm64 で動作するビルドが存在しないためである。
37 
38### 開発環境のセットアップ
39 
40```bash
41# uv（Python パッケージマネージャ）をインストール
42pip install uv
43 
44# 仮想環境を作成して Python 依存関係をインストール
45uv venv
46source .venv/bin/activate
47uv pip install -r scripts/requirements-dev.txt
48 
49# Node.js ツール（Markdown リンタと Mermaid バリデータ）をインストール
50npm install -g markdownlint-cli
51npm install -g @mermaid-js/mermaid-cli
52 
53# pre-commit フックをインストール
54uv pip install pre-commit
55pre-commit install
56```
57 
58### テスト
59 
60`scripts/` 内の Python スクリプトはユニットテストを持つ：
61 
62```bash
63# 全テストを実行
64pytest scripts/tests/ -v
65 
66# カバレッジ付きで実行
67pytest scripts/tests/ -v --cov=scripts --cov-report=html
68 
69# 特定のテストを実行
70pytest scripts/tests/test_build_epub.py -v
71```
72 
73### コード品質
74 
75```bash
76# Python コードをリント・整形
77ruff check scripts/
78ruff format scripts/
79 
80# セキュリティスキャン
81bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
82 
83# 型チェック
84mypy scripts/ --ignore-missing-imports
85```
86 
87### EPUB ビルド
88 
89```bash
90# 電子書籍を生成（Mermaid 図はローカルの mmdc CLI でレンダリング／ネットワーク不要）
91uv run scripts/build_epub.py
92 
93# オプション付き
94uv run scripts/build_epub.py --verbose --output custom-name.epub --lang ja
95```
96 
97## ディレクトリ構造
98 
99```
100├── 01-slash-commands/      # ユーザーが起動するショートカット
101├── 02-memory/              # 永続コンテキストの例
102├── 03-skills/              # 再利用可能な能力
103├── 04-subagents/           # 専門 AI アシスタント
104├── 05-mcp/                 # Model Context Protocol の例
105├── 06-hooks/               # イベント駆動の自動化
106├── 07-plugins/             # バンドル機能
107├── 08-checkpoints/         # セッションのスナップショット
108├── 09-advanced-features/   # プランニング、シンキング、バックグラウンド
109├── 10-cli/                 # CLI リファレンス
110├── scripts/
111│   ├── build_epub.py           # EPUB ジェネレータ（Mermaid をローカル mmdc でレンダリング）
112│   ├── check_cross_references.py   # 内部リンクを検証
113│   ├── check_links.py          # 外部 URL を検証
114│   ├── check_mermaid.py        # Mermaid 構文を検証
115│   └── tests/                  # スクリプトのユニットテスト
116├── .pre-commit-config.yaml    # 品質チェック定義
117└── README.md               # メインガイド（モジュール索引も兼ねる）
118```
119 
120## コンテンツ作成ガイド
121 
122### モジュール構造
123番号付きフォルダはいずれも以下のパターンに従う：
124- **README.md** — 機能の概要と例
125- **サンプルファイル** — コピー＆ペースト可能なテンプレート（コマンドは `.md`、設定は `.json`、フックは `.sh`）
126- ファイルは機能の複雑さと依存関係に従って整理されている
127 
128### Mermaid 図
129- すべての図は正常にパースできること（pre-commit フックで検査）
130- EPUB ビルドはローカルの `mmdc` CLI で図をレンダリングする（ネットワークは不要だが `mmdc` が必要）
131- フローチャート、シーケンス図、アーキテクチャ可視化に Mermaid を使用する
132 
133### 相互参照
134- 内部リンクは相対パスを使う（例：`(01-slash-commands/README.md)`）
135- コードフェンスは言語指定が必須（例：` ```bash `、` ```python `）
136- アンカーリンクは `#heading-name` 形式
137 
138### リンク検証
139- 外部 URL は到達可能であること（pre-commit フックで検査）
140- 一時的なコンテンツへのリンクは避ける
141- 可能な限りパーマリンクを使用する
142 
143## 主要なアーキテクチャ上のポイント
144 
1451. **番号付きフォルダは学習順序を示す** — 01〜10 のプレフィックスは Claude Code 機能の推奨学習順序を表す。この番号付けは意図的なものなので、アルファベット順に並べ替えてはならない。
146 
1472. **スクリプトはユーティリティであり製品ではない** — `scripts/` の Python スクリプトはドキュメント品質と EPUB 生成を支援するものである。実際のコンテンツは番号付きモジュールフォルダにある。
148 
1493. **pre-commit がゲートキーパー** — PR が承認される前に 5 つの品質チェックがすべて通過しなければならない。CI パイプラインは同じチェックを 2 回目のパスとして実行する。
150 
1514. **Mermaid のレンダリングにはローカルの `mmdc` が必要** — EPUB ビルドは図のレンダリングにローカルの `mmdc` CLI を呼び出す（ネットワークは不要）。ここでビルドが失敗する場合は、`mmdc` が未インストールか、Mermaid 構文エラーが典型的な原因である。EPUB ビルド自体は pre-commit では実行されず、CI のみで実行される。
152 
1535. **これはチュートリアルでありライブラリではない** — コンテンツを追加する際は、明快な解説、コピー＆ペースト可能な例、視覚的な図を重視する。価値は概念を教えることにあり、再利用可能なコードを提供することではない。
154 
155## コミット規約
156 
157Conventional Commits 形式に従う：
158- `feat(slash-commands): Add API documentation generator`
159- `docs(memory): Improve personal preferences example`
160- `fix(README): Correct table of contents link`
161- `refactor(hooks): Simplify hook configuration examples`
162 
163スコープは該当するフォルダ名に合わせる。
164