| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 9 | 8 | 6% |
| Commands | 4 | 1 | 11 | 25% |
| Section tags | 5 | 2 | 1 | 63% |
What each file covers
Sections
1 shared · 9 only in A · 8 only in B- − Critical commands
- − Quality gate (also runs on commit via pre-commit hooks)
- − Tests
- − EPUB build (calls Kroki.io API to render Mermaid — needs network)
- − Python tooling
- − Architecture map
- − Hard rules
- − Workflow preferences
- − Token Efficiency
- + コミット規約
- + pre-commit フックをインストール
- + uv（Python パッケージマネージャ）をインストール
- + Python コードをリント・整形
- + Node.js ツール（Markdown リンタと Mermaid バリデータ）をインストール
- + EPUB ビルド
- + 電子書籍を生成（Mermaid 図を Kroki.io API でレンダリング）
- + Mermaid 図
- CLAUDE.md
Commands
4 shared · 1 only in A · 11 only in B- − ruff check scripts/ && ruff format scripts/
- + pip install uv
- + uv venv
- + uv pip install -r scripts/requirements-dev.txt
- + npm install -g markdownlint-cli
- + npm install -g @mermaid-js/mermaid-cli
- + uv pip install pre-commit
- + pytest scripts/tests/ -v --cov=scripts --cov-report=html
- + pytest scripts/tests/test_build_epub.py -v
- + ruff check scripts/
- + ruff format scripts/
- + uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
- pytest scripts/tests/ -v
- uv run scripts/build_epub.py
- mypy scripts/ --ignore-missing-imports
- python
Section tags
5 shared · 2 only in A · 1 only in B- − build
- − do-not
- + setup
- test
- lint-format
- git-pr
- api
- agent-behaviour
Line diff
luongnv89/claude-howto · CLAUDE.md
@@ −1 @@
1# CLAUDE.md
2
3Tutorial repo. Output is markdown in numbered modules `01-` through `10-`, not an app. Scripts in `scripts/` exist only to validate docs and build the EPUB.
4
5See also `.claude/CLAUDE.md` for stack/commands and `STYLE_GUIDE.md` for lesson structure.
6
7## Critical commands
8
9```bash
10# Quality gate (also runs on commit via pre-commit hooks)
11pre-commit run --all-files
12
13# Tests
14pytest scripts/tests/ -v
15
16# EPUB build (calls Kroki.io API to render Mermaid — needs network)
17uv run scripts/build_epub.py
18
19# Python tooling
20ruff check scripts/ && ruff format scripts/
21mypy scripts/ --ignore-missing-imports
22bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
23```
24
25Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-check, build-epub (on `.md` changes). All must pass.
26
27## Architecture map
28
29- `01-` … `10-` — tutorial modules. **Numbered prefix = learning order**, not alphabetical. Do not reorganize.
30- Each module: `README.md` + copy-paste templates (`.md`, `.json`, `.sh`).
31- `scripts/` — utilities (EPUB builder, link/mermaid/cross-ref validators). Not the product.
32- `02-memory/*.md` — CLAUDE.md templates users copy into their own projects. Don't confuse with this file.
33- `openspec/` — spec-driven change proposals.
34
35## Hard rules
36
37- **YOU MUST NOT commit or push without explicit user request.**
38- **YOU MUST NOT add `Co-Authored-By: Claude`** to any commit message.
39- Always activate `.venv` before running Python scripts (check `venv/`, `.venv/`, `env/`).
40- Internal links use **relative paths** (e.g. `01-slash-commands/README.md`); anchors use `#heading-name`.
41- Code fences **must** declare a language (`bash`, `python`, `json`, …) — the cross-reference check fails otherwise.
42- External URLs must be reachable and stable. No ephemeral links.
43- Mermaid diagrams must parse (validated pre-commit). Broken EPUB build is usually invalid Mermaid or no network to Kroki.
44- Commit format: `type(scope): subject` where `scope` matches the module folder (e.g. `feat(slash-commands):`, `docs(memory):`, `fix(README):`).
45- Do not reorganize the `01-`–`10-` numbering. The order is the curriculum.
46
47## Workflow preferences
48
49- For lesson edits, follow `STYLE_GUIDE.md` for structure/naming/diagrams.
50- Small fixes → minimal diff. Don't rewrite a section to fix a typo.
51- When adding a module page: README + templates first, then update root `README.md` index and `LEARNING-ROADMAP.md` if order/timing changes.
52- Tutorial > library: prioritize clear explanations and copy-paste examples over reusable abstractions.
53- If a quality check fails, fix the underlying issue. Don't bypass with `--no-verify`.
54
55## Token Efficiency
56- Never re-read files you just wrote or edited. You know the contents.
57- Never re-run commands to "verify" unless the outcome was uncertain.
58- Don't echo back large blocks of code or file contents unless asked.
59- Batch related edits into single operations. Don't make 5 edits when 1 handles it.
60- Skip confirmations like "I'll continue..." Just do it.
61- If a task needs 1 tool call, don't use 3. Plan before acting.
62- Do not summarize what you just did unless the result is ambiguous or you need additional input.
63
luongnv89/claude-howto · ja/CLAUDE.md
@@ +1 @@
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すべてのドキュメントは、コミット前に 4 つの品質チェックを通過しなければならない（pre-commit フックで自動実行される）：
20
21```bash
22# pre-commit フックをインストール（毎コミットで実行）
23pre-commit install
24
25# 全チェックを手動で実行
26pre-commit run --all-files
27```
28
294 つのチェックは以下のとおり：
301. **markdown-lint** — `markdownlint` による Markdown 構造とフォーマット
312. **cross-references** — 内部リンク、アンカー、コードフェンスの構文（Python スクリプト）
323. **mermaid-syntax** — すべての Mermaid 図が正しくパースされるかを検証（Python スクリプト）
334. **link-check** — 外部 URL が到達可能か（Python スクリプト）
345. **build-epub** — EPUB がエラーなく生成されるか（`.md` 変更時）
35
36### 開発環境のセットアップ
37
38```bash
39# uv（Python パッケージマネージャ）をインストール
40pip install uv
41
42# 仮想環境を作成して Python 依存関係をインストール
43uv venv
44source .venv/bin/activate
45uv pip install -r scripts/requirements-dev.txt
46
47# Node.js ツール（Markdown リンタと Mermaid バリデータ）をインストール
48npm install -g markdownlint-cli
49npm install -g @mermaid-js/mermaid-cli
50
51# pre-commit フックをインストール
52uv pip install pre-commit
53pre-commit install
54```
55
56### テスト
57
58`scripts/` 内の Python スクリプトはユニットテストを持つ：
59
60```bash
61# 全テストを実行
62pytest scripts/tests/ -v
63
64# カバレッジ付きで実行
65pytest scripts/tests/ -v --cov=scripts --cov-report=html
66
67# 特定のテストを実行
68pytest scripts/tests/test_build_epub.py -v
69```
70
71### コード品質
72
73```bash
74# Python コードをリント・整形
75ruff check scripts/
76ruff format scripts/
77
78# セキュリティスキャン
79bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
80
81# 型チェック
82mypy scripts/ --ignore-missing-imports
83```
84
85### EPUB ビルド
86
87```bash
88# 電子書籍を生成（Mermaid 図を Kroki.io API でレンダリング）
89uv run scripts/build_epub.py
90
91# オプション付き
92uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
93```
94
95## ディレクトリ構造
96
97```
98├── 01-slash-commands/ # ユーザーが起動するショートカット
99├── 02-memory/ # 永続コンテキストの例
100├── 03-skills/ # 再利用可能な能力
101├── 04-subagents/ # 専門 AI アシスタント
102├── 05-mcp/ # Model Context Protocol の例
103├── 06-hooks/ # イベント駆動の自動化
104├── 07-plugins/ # バンドル機能
105├── 08-checkpoints/ # セッションのスナップショット
106├── 09-advanced-features/ # プランニング、シンキング、バックグラウンド
107├── 10-cli/ # CLI リファレンス
108├── scripts/
109│ ├── build_epub.py # EPUB ジェネレータ（Mermaid を Kroki API でレンダリング）
110│ ├── check_cross_references.py # 内部リンクを検証
111│ ├── check_links.py # 外部 URL を検証
112│ ├── check_mermaid.py # Mermaid 構文を検証
113│ └── tests/ # スクリプトのユニットテスト
114├── .pre-commit-config.yaml # 品質チェック定義
115└── README.md # メインガイド（モジュール索引も兼ねる）
116```
117
118## コンテンツ作成ガイド
119
120### モジュール構造
121番号付きフォルダはいずれも以下のパターンに従う：
122- **README.md** — 機能の概要と例
123- **サンプルファイル** — コピー＆ペースト可能なテンプレート（コマンドは `.md`、設定は `.json`、フックは `.sh`）
124- ファイルは機能の複雑さと依存関係に従って整理されている
125
126### Mermaid 図
127- すべての図は正常にパースできること（pre-commit フックで検査）
128- EPUB ビルドは Kroki.io API で図をレンダリングする（インターネット接続が必要）
129- フローチャート、シーケンス図、アーキテクチャ可視化に Mermaid を使用する
130
131### 相互参照
132- 内部リンクは相対パスを使う（例：`(01-slash-commands/README.md)`）
133- コードフェンスは言語指定が必須（例：` ```bash `、` ```python `）
134- アンカーリンクは `#heading-name` 形式
135
136### リンク検証
137- 外部 URL は到達可能であること（pre-commit フックで検査）
138- 一時的なコンテンツへのリンクは避ける
139- 可能な限りパーマリンクを使用する
140
141## 主要なアーキテクチャ上のポイント
142
1431. **番号付きフォルダは学習順序を示す** — 01〜10 のプレフィックスは Claude Code 機能の推奨学習順序を表す。この番号付けは意図的なものなので、アルファベット順に並べ替えてはならない。
144
1452. **スクリプトはユーティリティであり製品ではない** — `scripts/` の Python スクリプトはドキュメント品質と EPUB 生成を支援するものである。実際のコンテンツは番号付きモジュールフォルダにある。
146
1473. **pre-commit がゲートキーパー** — PR が承認される前に 4 つの品質チェックがすべて通過しなければならない。CI パイプラインは同じチェックを 2 回目のパスとして実行する。
148
1494. **Mermaid のレンダリングにはネットワークが必要** — EPUB ビルドは図のレンダリングに Kroki.io API を呼び出す。ここでビルドが失敗する場合は、ネットワーク問題か Mermaid 構文エラーが典型的な原因である。
150
1515. **これはチュートリアルでありライブラリではない** — コンテンツを追加する際は、明快な解説、コピー＆ペースト可能な例、視覚的な図を重視する。価値は概念を教えることにあり、再利用可能なコードを提供することではない。
152
153## コミット規約
154
155Conventional Commits 形式に従う：
156- `feat(slash-commands): Add API documentation generator`
157- `docs(memory): Improve personal preferences example`
158- `fix(README): Correct table of contents link`
159- `refactor(hooks): Simplify hook configuration examples`
160
161スコープは該当するフォルダ名に合わせる。
162
@@ −1 +1 @@
1+<!-- i18n-source: CLAUDE.md -->
2+<!-- i18n-source-sha: a70777e -->
3+<!-- i18n-date: 2026-04-27 -->
4+
15 # CLAUDE.md
26
3−Tutorial repo. Output is markdown in numbered modules `01-` through `10-`, not an app. Scripts in `scripts/` exist only to validate docs and build the EPUB.
7+このファイルは、本リポジトリ内のコードを扱う際の Claude Code（claude.ai/code）向けガイドである。
48
5−See also `.claude/CLAUDE.md` for stack/commands and `STYLE_GUIDE.md` for lesson structure.
9+## プロジェクト概要
610
7−## Critical commands
11+Claude How To は Claude Code 機能のチュートリアルリポジトリである。これは **ドキュメント・アズ・コード** であり、主な成果物は実行可能アプリケーションではなく、番号付きの学習モジュールに整理された Markdown ファイルである。
812
13+**アーキテクチャ：** 各モジュール（01〜10）は Claude Code の特定の機能を、コピー＆ペースト可能なテンプレート、Mermaid 図、サンプルとともに解説する。ビルドシステムはドキュメントの品質を検証し、EPUB 電子書籍を生成する。
14+
15+## よく使うコマンド
16+
17+### pre-commit 品質チェック
18+
19+すべてのドキュメントは、コミット前に 4 つの品質チェックを通過しなければならない（pre-commit フックで自動実行される）：
20+
921 ```bash
10−# Quality gate (also runs on commit via pre-commit hooks)
22+# pre-commit フックをインストール（毎コミットで実行）
23+pre-commit install
24+
25+# 全チェックを手動で実行
1126 pre-commit run --all-files
27+```
1228
13−# Tests
29+4 つのチェックは以下のとおり：
30+1. **markdown-lint** — `markdownlint` による Markdown 構造とフォーマット
31+2. **cross-references** — 内部リンク、アンカー、コードフェンスの構文（Python スクリプト）
32+3. **mermaid-syntax** — すべての Mermaid 図が正しくパースされるかを検証（Python スクリプト）
33+4. **link-check** — 外部 URL が到達可能か（Python スクリプト）
34+5. **build-epub** — EPUB がエラーなく生成されるか（`.md` 変更時）
35+
36+### 開発環境のセットアップ
37+
38+```bash
39+# uv（Python パッケージマネージャ）をインストール
40+pip install uv
41+
42+# 仮想環境を作成して Python 依存関係をインストール
43+uv venv
44+source .venv/bin/activate
45+uv pip install -r scripts/requirements-dev.txt
46+
47+# Node.js ツール（Markdown リンタと Mermaid バリデータ）をインストール
48+npm install -g markdownlint-cli
49+npm install -g @mermaid-js/mermaid-cli
50+
51+# pre-commit フックをインストール
52+uv pip install pre-commit
53+pre-commit install
54+```
55+
56+### テスト
57+
58+`scripts/` 内の Python スクリプトはユニットテストを持つ：
59+
60+```bash
61+# 全テストを実行
1462 pytest scripts/tests/ -v
1563
16−# EPUB build (calls Kroki.io API to render Mermaid — needs network)
17−uv run scripts/build_epub.py
64+# カバレッジ付きで実行
65+pytest scripts/tests/ -v --cov=scripts --cov-report=html
1866
19−# Python tooling
20−ruff check scripts/ && ruff format scripts/
21−mypy scripts/ --ignore-missing-imports
67+# 特定のテストを実行
68+pytest scripts/tests/test_build_epub.py -v
69+```
70+
71+### コード品質
72+
73+```bash
74+# Python コードをリント・整形
75+ruff check scripts/
76+ruff format scripts/
77+
78+# セキュリティスキャン
2279 bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
80+
81+# 型チェック
82+mypy scripts/ --ignore-missing-imports
2383 ```
2484
25−Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-check, build-epub (on `.md` changes). All must pass.
85+### EPUB ビルド
2686
27−## Architecture map
87+```bash
88+# 電子書籍を生成（Mermaid 図を Kroki.io API でレンダリング）
89+uv run scripts/build_epub.py
2890
29−- `01-` … `10-` — tutorial modules. **Numbered prefix = learning order**, not alphabetical. Do not reorganize.
30−- Each module: `README.md` + copy-paste templates (`.md`, `.json`, `.sh`).
31−- `scripts/` — utilities (EPUB builder, link/mermaid/cross-ref validators). Not the product.
32−- `02-memory/*.md` — CLAUDE.md templates users copy into their own projects. Don't confuse with this file.
33−- `openspec/` — spec-driven change proposals.
91+# オプション付き
92+uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
93+```
3494
35−## Hard rules
95+## ディレクトリ構造
3696
37−- **YOU MUST NOT commit or push without explicit user request.**
38−- **YOU MUST NOT add `Co-Authored-By: Claude`** to any commit message.
39−- Always activate `.venv` before running Python scripts (check `venv/`, `.venv/`, `env/`).
40−- Internal links use **relative paths** (e.g. `01-slash-commands/README.md`); anchors use `#heading-name`.
41−- Code fences **must** declare a language (`bash`, `python`, `json`, …) — the cross-reference check fails otherwise.
42−- External URLs must be reachable and stable. No ephemeral links.
43−- Mermaid diagrams must parse (validated pre-commit). Broken EPUB build is usually invalid Mermaid or no network to Kroki.
44−- Commit format: `type(scope): subject` where `scope` matches the module folder (e.g. `feat(slash-commands):`, `docs(memory):`, `fix(README):`).
45−- Do not reorganize the `01-`–`10-` numbering. The order is the curriculum.
97+```
98+├── 01-slash-commands/ # ユーザーが起動するショートカット
99+├── 02-memory/ # 永続コンテキストの例
100+├── 03-skills/ # 再利用可能な能力
101+├── 04-subagents/ # 専門 AI アシスタント
102+├── 05-mcp/ # Model Context Protocol の例
103+├── 06-hooks/ # イベント駆動の自動化
104+├── 07-plugins/ # バンドル機能
105+├── 08-checkpoints/ # セッションのスナップショット
106+├── 09-advanced-features/ # プランニング、シンキング、バックグラウンド
107+├── 10-cli/ # CLI リファレンス
108+├── scripts/
109+│ ├── build_epub.py # EPUB ジェネレータ（Mermaid を Kroki API でレンダリング）
110+│ ├── check_cross_references.py # 内部リンクを検証
111+│ ├── check_links.py # 外部 URL を検証
112+│ ├── check_mermaid.py # Mermaid 構文を検証
113+│ └── tests/ # スクリプトのユニットテスト
114+├── .pre-commit-config.yaml # 品質チェック定義
115+└── README.md # メインガイド（モジュール索引も兼ねる）
116+```
46117
47−## Workflow preferences
118+## コンテンツ作成ガイド
48119
49−- For lesson edits, follow `STYLE_GUIDE.md` for structure/naming/diagrams.
50−- Small fixes → minimal diff. Don't rewrite a section to fix a typo.
51−- When adding a module page: README + templates first, then update root `README.md` index and `LEARNING-ROADMAP.md` if order/timing changes.
52−- Tutorial > library: prioritize clear explanations and copy-paste examples over reusable abstractions.
53−- If a quality check fails, fix the underlying issue. Don't bypass with `--no-verify`.
120+### モジュール構造
121+番号付きフォルダはいずれも以下のパターンに従う：
122+- **README.md** — 機能の概要と例
123+- **サンプルファイル** — コピー＆ペースト可能なテンプレート（コマンドは `.md`、設定は `.json`、フックは `.sh`）
124+- ファイルは機能の複雑さと依存関係に従って整理されている
54125
55−## Token Efficiency
56−- Never re-read files you just wrote or edited. You know the contents.
57−- Never re-run commands to "verify" unless the outcome was uncertain.
58−- Don't echo back large blocks of code or file contents unless asked.
59−- Batch related edits into single operations. Don't make 5 edits when 1 handles it.
60−- Skip confirmations like "I'll continue..." Just do it.
61−- If a task needs 1 tool call, don't use 3. Plan before acting.
62−- Do not summarize what you just did unless the result is ambiguous or you need additional input.
126+### Mermaid 図
127+- すべての図は正常にパースできること（pre-commit フックで検査）
128+- EPUB ビルドは Kroki.io API で図をレンダリングする（インターネット接続が必要）
129+- フローチャート、シーケンス図、アーキテクチャ可視化に Mermaid を使用する
130+
131+### 相互参照
132+- 内部リンクは相対パスを使う（例：`(01-slash-commands/README.md)`）
133+- コードフェンスは言語指定が必須（例：` ```bash `、` ```python `）
134+- アンカーリンクは `#heading-name` 形式
135+
136+### リンク検証
137+- 外部 URL は到達可能であること（pre-commit フックで検査）
138+- 一時的なコンテンツへのリンクは避ける
139+- 可能な限りパーマリンクを使用する
140+
141+## 主要なアーキテクチャ上のポイント
142+
143+1. **番号付きフォルダは学習順序を示す** — 01〜10 のプレフィックスは Claude Code 機能の推奨学習順序を表す。この番号付けは意図的なものなので、アルファベット順に並べ替えてはならない。
144+
145+2. **スクリプトはユーティリティであり製品ではない** — `scripts/` の Python スクリプトはドキュメント品質と EPUB 生成を支援するものである。実際のコンテンツは番号付きモジュールフォルダにある。
146+
147+3. **pre-commit がゲートキーパー** — PR が承認される前に 4 つの品質チェックがすべて通過しなければならない。CI パイプラインは同じチェックを 2 回目のパスとして実行する。
148+
149+4. **Mermaid のレンダリングにはネットワークが必要** — EPUB ビルドは図のレンダリングに Kroki.io API を呼び出す。ここでビルドが失敗する場合は、ネットワーク問題か Mermaid 構文エラーが典型的な原因である。
150+
151+5. **これはチュートリアルでありライブラリではない** — コンテンツを追加する際は、明快な解説、コピー＆ペースト可能な例、視覚的な図を重視する。価値は概念を教えることにあり、再利用可能なコードを提供することではない。
152+
153+## コミット規約
154+
155+Conventional Commits 形式に従う：
156+- `feat(slash-commands): Add API documentation generator`
157+- `docs(memory): Improve personal preferences example`
158+- `fix(README): Correct table of contents link`
159+- `refactor(hooks): Simplify hook configuration examples`
160+
161+スコープは該当するフォルダ名に合わせる。
63162
