| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 29 | 8 | 3% |
| Commands | 15 | 0 | 0 | 100% |
| Section tags | 6 | 6 | 0 | 50% |
What each file covers
Sections
1 shared · 29 only in A · 8 only in B- − Tổng Quan Dự Án
- − Các Lệnh Thường Dùng
- − Kiểm Tra Chất Lượng Pre-commit
- − Cài đặt pre-commit hooks (chạy trên mỗi commit)
- − Chạy tất cả các kiểm tra thủ công
- − Thiết Lập Môi Trường Phát Triển
- − Cài đặt uv (Python package manager)
- − Tạo virtual environment và cài đặt Python dependencies
- − Cài đặt Node.js tools (markdown linter và Mermaid validator)
- − Cài đặt pre-commit hooks
- − Testing
- − Chạy tất cả tests
- − Chạy với coverage
- − Chạy test cụ thể
- − Chất Lượng Code
- − Lint và format Python code
- − Security scan
- − Type checking
- − Build EPUB
- − Tạo ebook (render Mermaid diagrams qua Kroki.io API)
- − Với các tùy chọn
- − Cấu Trúc Thư Mục
- − Hướng Dẫn Nội Dung
- − Cấu Trúc Module
- − Sơ Đồ Mermaid
- − Cross-References
- − Link Validation
- − Các Điểm Kiến Trúc Quan Trọng
- − Commit Conventions
- + コミット規約
- + pre-commit フックをインストール
- + uv（Python パッケージマネージャ）をインストール
- + Python コードをリント・整形
- + Node.js ツール（Markdown リンタと Mermaid バリデータ）をインストール
- + EPUB ビルド
- + 電子書籍を生成（Mermaid 図を Kroki.io API でレンダリング）
- + Mermaid 図
- CLAUDE.md
Commands
15 shared · 0 only in A · 0 only in B- 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
- pytest scripts/tests/ -v --cov=scripts --cov-report=html
- pytest scripts/tests/test_build_epub.py -v
- ruff check scripts/
- ruff format scripts/
- mypy scripts/ --ignore-missing-imports
- uv run scripts/build_epub.py
- uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
- python
Section tags
6 shared · 6 only in A · 0 only in B- − build
- − code-style
- − types
- − testing-strategy
- − security
- − dependencies
- setup
- test
- lint-format
- git-pr
- api
- agent-behaviour
Line diff
luongnv89/claude-howto · vi/CLAUDE.md
@@ −1 @@
1# CLAUDE.md
2
3File này cung cấp hướng dẫn cho Claude Code (claude.ai/code) khi làm việc với code trong repository này.
4
5## Tổng Quan Dự Án
6
7Claude How To là một repository tutorial về các tính năng của Claude Code. Đây là **documentation-as-code** — sản phẩm chính là các file markdown được tổ chức thành các module học tập đánh số (01-10), không phải một ứng dụng thực thi.
8
9**Kiến trúc**: Mỗi module (01-10) bao phủ một tính năng cụ thể của Claude Code với các template copy-paste, sơ đồ Mermaid, và ví dụ. Hệ thống build xác thực chất lượng documentation và tạo ebook EPUB.
10
11## Các Lệnh Thường Dùng
12
13### Kiểm Tra Chất Lượng Pre-commit
14
15Tất cả documentation phải vượt qua bốn kiểm tra chất lượng trước khi commit (các kiểm tra này chạy tự động qua pre-commit hooks):
16
17```bash
18# Cài đặt pre-commit hooks (chạy trên mỗi commit)
19pre-commit install
20
21# Chạy tất cả các kiểm tra thủ công
22pre-commit run --all-files
23```
24
25Bốn kiểm tra là:
261. **markdown-lint** — Cấu trúc và định dạng Markdown qua `markdownlint`
272. **cross-references** — Liên kết nội bộ, anchors, cú pháp code fence (Python script)
283. **mermaid-syntax** — Xác thực tất cả sơ đồ Mermaid parse đúng (Python script)
294. **link-check** — Các URL bên ngoài có thể truy cập được (Python script)
305. **build-epub** — EPUB tạo ra không có lỗi (khi có thay đổi `.md`)
31
32### Thiết Lập Môi Trường Phát Triển
33
34```bash
35# Cài đặt uv (Python package manager)
36pip install uv
37
38# Tạo virtual environment và cài đặt Python dependencies
39uv venv
40source .venv/bin/activate
41uv pip install -r scripts/requirements-dev.txt
42
43# Cài đặt Node.js tools (markdown linter và Mermaid validator)
44npm install -g markdownlint-cli
45npm install -g @mermaid-js/mermaid-cli
46
47# Cài đặt pre-commit hooks
48uv pip install pre-commit
49pre-commit install
50```
51
52### Testing
53
54Các script Python trong `scripts/` có unit tests:
55
56```bash
57# Chạy tất cả tests
58pytest scripts/tests/ -v
59
60# Chạy với coverage
61pytest scripts/tests/ -v --cov=scripts --cov-report=html
62
63# Chạy test cụ thể
64pytest scripts/tests/test_build_epub.py -v
65```
66
67### Chất Lượng Code
68
69```bash
70# Lint và format Python code
71ruff check scripts/
72ruff format scripts/
73
74# Security scan
75bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
76
77# Type checking
78mypy scripts/ --ignore-missing-imports
79```
80
81### Build EPUB
82
83```bash
84# Tạo ebook (render Mermaid diagrams qua Kroki.io API)
85uv run scripts/build_epub.py
86
87# Với các tùy chọn
88uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
89```
90
91## Cấu Trúc Thư Mục
92
93```
94├── 01-slash-commands/ # Các lối tắt do người dùng gọi
95├── 02-memory/ # Ví dụ về bối cảnh liên tục
96├── 03-skills/ # Các khả năng có thể tái sử dụng
97├── 04-subagents/ # Các tác nhân AI chuyên dụng
98├── 05-mcp/ # Ví dụ Model Context Protocol
99├── 06-hooks/ # Tự động hóa dựa trên sự kiện
100├── 07-plugins/ # Các tính năng được đóng gói
101├── 08-checkpoints/ # Các snapshot của phiên
102├── 09-advanced-features/ # Lập kế hoạch, suy nghĩ, background tasks
103├── 10-cli/ # Tham chiếu CLI
104├── scripts/
105│ ├── build_epub.py # EPUB generator (render Mermaid qua Kroki API)
106│ ├── check_cross_references.py # Xác thực liên kết nội bộ
107│ ├── check_links.py # Kiểm tra các URL bên ngoài
108│ ├── check_mermaid.py # Xác thực cú pháp Mermaid
109│ └── tests/ # Unit tests cho scripts
110├── .pre-commit-config.yaml # Định nghĩa các kiểm tra chất lượng
111└── README.md # Hướng dẫn chính (cũng là index của module)
112```
113
114## Hướng Dẫn Nội Dung
115
116### Cấu Trúc Module
117
118Mỗi thư mục đánh số tuân theo pattern:
119- **README.md** — Tổng quan về tính năng với các ví dụ
120- **Các file ví dụ** — Template copy-paste (`.md` cho commands, `.json` cho configs, `.sh` cho hooks)
121- Các file được tổ chức theo độ phức tạp của tính năng và dependencies
122
123### Sơ Đồ Mermaid
124- Tất cả sơ đồ phải parse thành công (được kiểm tra bởi pre-commit hook)
125- EPUB build render sơ đồ qua Kroki.io API (cần internet)
126- Sử dụng Mermaid cho flowcharts, sequence diagrams, và architecture visuals
127
128### Cross-References
129- Sử dụng relative paths cho internal links (ví dụ: `(01-slash-commands/README.md)`)
130- Code fences phải chỉ định ngôn ngữ (ví dụ: ` ```bash `, ` ```python `)
131- Anchor links sử dụng format `#heading-name`
132
133### Link Validation
134- Các URL bên ngoài phải có thể truy cập được (được kiểm tra bởi pre-commit hook)
135- Tránh link đến nội dung tạm thời
136- Sử dụng permalinks nếu có thể
137
138## Các Điểm Kiến Trúc Quan Trọng
139
1401. **Các thư mục đánh số thể hiện thứ tự học tập** — Prefix 01-10 thể hiện thứ tự được khuyến nghị để học các tính năng của Claude Code. Đánh số này có chủ đích; không tổ chức lại theo bảng chữ cái.
141
1422. **Scripts là các tiện ích, không phải sản phẩm** — Các script Python trong `scripts/` hỗ trợ chất lượng documentation và tạo EPUB. Nội dung thực tế nằm trong các thư mục module đánh số.
143
1443. **Pre-commit là người gác cổng** — Tất cả bốn kiểm tra chất lượng phải pass trước khi PR được chấp nhận. CI pipeline chạy các kiểm tra tương tự như lần thứ hai.
145
1464. **Mermaid rendering cần network** — EPUB build gọi Kroki.io API để render diagrams. Các lỗi build ở đây thường là vấn đề network hoặc cú pháp Mermaid không hợp lệ.
147
1485. **Đây là tutorial, không phải thư viện** — Khi thêm nội dung, tập trung vào giải thích rõ ràng, ví dụ copy-paste, và sơ đồ trực quan. Giá trị nằm ở việc dạy các khái niệm, không cung cấp code có thể tái sử dụng.
149
150## Commit Conventions
151
152Tuân theo format conventional commit:
153- `feat(slash-commands): Add API documentation generator`
154- `docs(memory): Improve personal preferences example`
155- `fix(README): Correct table of contents link`
156- `refactor(hooks): Simplify hook configuration examples`
157
158Scope nên khớp với tên thư mục khi áp dụng.
159
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−File này cung cấp hướng dẫn cho Claude Code (claude.ai/code) khi làm việc với code trong repository này.
7+このファイルは、本リポジトリ内のコードを扱う際の Claude Code（claude.ai/code）向けガイドである。
48
5−## Tổng Quan Dự Án
9+## プロジェクト概要
610
7−Claude How To là một repository tutorial về các tính năng của Claude Code. Đây là **documentation-as-code** — sản phẩm chính là các file markdown được tổ chức thành các module học tập đánh số (01-10), không phải một ứng dụng thực thi.
11+Claude How To は Claude Code 機能のチュートリアルリポジトリである。これは **ドキュメント・アズ・コード** であり、主な成果物は実行可能アプリケーションではなく、番号付きの学習モジュールに整理された Markdown ファイルである。
812
9−**Kiến trúc**: Mỗi module (01-10) bao phủ một tính năng cụ thể của Claude Code với các template copy-paste, sơ đồ Mermaid, và ví dụ. Hệ thống build xác thực chất lượng documentation và tạo ebook EPUB.
13+**アーキテクチャ：** 各モジュール（01〜10）は Claude Code の特定の機能を、コピー＆ペースト可能なテンプレート、Mermaid 図、サンプルとともに解説する。ビルドシステムはドキュメントの品質を検証し、EPUB 電子書籍を生成する。
1014
11−## Các Lệnh Thường Dùng
15+## よく使うコマンド
1216
13−### Kiểm Tra Chất Lượng Pre-commit
17+### pre-commit 品質チェック
1418
15−Tất cả documentation phải vượt qua bốn kiểm tra chất lượng trước khi commit (các kiểm tra này chạy tự động qua pre-commit hooks):
19+すべてのドキュメントは、コミット前に 4 つの品質チェックを通過しなければならない（pre-commit フックで自動実行される）：
1620
1721 ```bash
18−# Cài đặt pre-commit hooks (chạy trên mỗi commit)
22+# pre-commit フックをインストール（毎コミットで実行）
1923 pre-commit install
2024
21−# Chạy tất cả các kiểm tra thủ công
25+# 全チェックを手動で実行
2226 pre-commit run --all-files
2327 ```
2428
25−Bốn kiểm tra là:
26−1. **markdown-lint** — Cấu trúc và định dạng Markdown qua `markdownlint`
27−2. **cross-references** — Liên kết nội bộ, anchors, cú pháp code fence (Python script)
28−3. **mermaid-syntax** — Xác thực tất cả sơ đồ Mermaid parse đúng (Python script)
29−4. **link-check** — Các URL bên ngoài có thể truy cập được (Python script)
30−5. **build-epub** — EPUB tạo ra không có lỗi (khi có thay đổi `.md`)
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` 変更時）
3135
32−### Thiết Lập Môi Trường Phát Triển
36+### 開発環境のセットアップ
3337
3438 ```bash
35−# Cài đặt uv (Python package manager)
39+# uv（Python パッケージマネージャ）をインストール
3640 pip install uv
3741
38−# Tạo virtual environment và cài đặt Python dependencies
42+# 仮想環境を作成して Python 依存関係をインストール
3943 uv venv
4044 source .venv/bin/activate
4145 uv pip install -r scripts/requirements-dev.txt
4246
43−# Cài đặt Node.js tools (markdown linter và Mermaid validator)
47+# Node.js ツール（Markdown リンタと Mermaid バリデータ）をインストール
4448 npm install -g markdownlint-cli
4549 npm install -g @mermaid-js/mermaid-cli
4650
47−# Cài đặt pre-commit hooks
51+# pre-commit フックをインストール
4852 uv pip install pre-commit
4953 pre-commit install
5054 ```
5155
52−### Testing
56+### テスト
5357
54−Các script Python trong `scripts/` có unit tests:
58+`scripts/` 内の Python スクリプトはユニットテストを持つ：
5559
5660 ```bash
57−# Chạy tất cả tests
61+# 全テストを実行
5862 pytest scripts/tests/ -v
5963
60−# Chạy với coverage
64+# カバレッジ付きで実行
6165 pytest scripts/tests/ -v --cov=scripts --cov-report=html
6266
63−# Chạy test cụ thể
67+# 特定のテストを実行
6468 pytest scripts/tests/test_build_epub.py -v
6569 ```
6670
67−### Chất Lượng Code
71+### コード品質
6872
6973 ```bash
70−# Lint và format Python code
74+# Python コードをリント・整形
7175 ruff check scripts/
7276 ruff format scripts/
7377
74−# Security scan
78+# セキュリティスキャン
7579 bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
7680
77−# Type checking
81+# 型チェック
7882 mypy scripts/ --ignore-missing-imports
7983 ```
8084
81−### Build EPUB
85+### EPUB ビルド
8286
8387 ```bash
84−# Tạo ebook (render Mermaid diagrams qua Kroki.io API)
88+# 電子書籍を生成（Mermaid 図を Kroki.io API でレンダリング）
8589 uv run scripts/build_epub.py
8690
87−# Với các tùy chọn
91+# オプション付き
8892 uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
8993 ```
9094
91−## Cấu Trúc Thư Mục
95+## ディレクトリ構造
9296
9397 ```
94−├── 01-slash-commands/ # Các lối tắt do người dùng gọi
95−├── 02-memory/ # Ví dụ về bối cảnh liên tục
96−├── 03-skills/ # Các khả năng có thể tái sử dụng
97−├── 04-subagents/ # Các tác nhân AI chuyên dụng
98−├── 05-mcp/ # Ví dụ Model Context Protocol
99−├── 06-hooks/ # Tự động hóa dựa trên sự kiện
100−├── 07-plugins/ # Các tính năng được đóng gói
101−├── 08-checkpoints/ # Các snapshot của phiên
102−├── 09-advanced-features/ # Lập kế hoạch, suy nghĩ, background tasks
103−├── 10-cli/ # Tham chiếu CLI
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 リファレンス
104108 ├── scripts/
105−│ ├── build_epub.py # EPUB generator (render Mermaid qua Kroki API)
106−│ ├── check_cross_references.py # Xác thực liên kết nội bộ
107−│ ├── check_links.py # Kiểm tra các URL bên ngoài
108−│ ├── check_mermaid.py # Xác thực cú pháp Mermaid
109−│ └── tests/ # Unit tests cho scripts
110−├── .pre-commit-config.yaml # Định nghĩa các kiểm tra chất lượng
111−└── README.md # Hướng dẫn chính (cũng là index của module)
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 # メインガイド（モジュール索引も兼ねる）
112116 ```
113117
114−## Hướng Dẫn Nội Dung
118+## コンテンツ作成ガイド
115119
116−### Cấu Trúc Module
120+### モジュール構造
121+番号付きフォルダはいずれも以下のパターンに従う：
122+- **README.md** — 機能の概要と例
123+- **サンプルファイル** — コピー＆ペースト可能なテンプレート（コマンドは `.md`、設定は `.json`、フックは `.sh`）
124+- ファイルは機能の複雑さと依存関係に従って整理されている
117125
118−Mỗi thư mục đánh số tuân theo pattern:
119−- **README.md** — Tổng quan về tính năng với các ví dụ
120−- **Các file ví dụ** — Template copy-paste (`.md` cho commands, `.json` cho configs, `.sh` cho hooks)
121−- Các file được tổ chức theo độ phức tạp của tính năng và dependencies
126+### Mermaid 図
127+- すべての図は正常にパースできること（pre-commit フックで検査）
128+- EPUB ビルドは Kroki.io API で図をレンダリングする（インターネット接続が必要）
129+- フローチャート、シーケンス図、アーキテクチャ可視化に Mermaid を使用する
122130
123−### Sơ Đồ Mermaid
124−- Tất cả sơ đồ phải parse thành công (được kiểm tra bởi pre-commit hook)
125−- EPUB build render sơ đồ qua Kroki.io API (cần internet)
126−- Sử dụng Mermaid cho flowcharts, sequence diagrams, và architecture visuals
131+### 相互参照
132+- 内部リンクは相対パスを使う（例：`(01-slash-commands/README.md)`）
133+- コードフェンスは言語指定が必須（例：` ```bash `、` ```python `）
134+- アンカーリンクは `#heading-name` 形式
127135
128−### Cross-References
129−- Sử dụng relative paths cho internal links (ví dụ: `(01-slash-commands/README.md)`)
130−- Code fences phải chỉ định ngôn ngữ (ví dụ: ` ```bash `, ` ```python `)
131−- Anchor links sử dụng format `#heading-name`
136+### リンク検証
137+- 外部 URL は到達可能であること（pre-commit フックで検査）
138+- 一時的なコンテンツへのリンクは避ける
139+- 可能な限りパーマリンクを使用する
132140
133−### Link Validation
134−- Các URL bên ngoài phải có thể truy cập được (được kiểm tra bởi pre-commit hook)
135−- Tránh link đến nội dung tạm thời
136−- Sử dụng permalinks nếu có thể
141+## 主要なアーキテクチャ上のポイント
137142
138−## Các Điểm Kiến Trúc Quan Trọng
143+1. **番号付きフォルダは学習順序を示す** — 01〜10 のプレフィックスは Claude Code 機能の推奨学習順序を表す。この番号付けは意図的なものなので、アルファベット順に並べ替えてはならない。
139144
140−1. **Các thư mục đánh số thể hiện thứ tự học tập** — Prefix 01-10 thể hiện thứ tự được khuyến nghị để học các tính năng của Claude Code. Đánh số này có chủ đích; không tổ chức lại theo bảng chữ cái.
145+2. **スクリプトはユーティリティであり製品ではない** — `scripts/` の Python スクリプトはドキュメント品質と EPUB 生成を支援するものである。実際のコンテンツは番号付きモジュールフォルダにある。
141146
142−2. **Scripts là các tiện ích, không phải sản phẩm** — Các script Python trong `scripts/` hỗ trợ chất lượng documentation và tạo EPUB. Nội dung thực tế nằm trong các thư mục module đánh số.
147+3. **pre-commit がゲートキーパー** — PR が承認される前に 4 つの品質チェックがすべて通過しなければならない。CI パイプラインは同じチェックを 2 回目のパスとして実行する。
143148
144−3. **Pre-commit là người gác cổng** — Tất cả bốn kiểm tra chất lượng phải pass trước khi PR được chấp nhận. CI pipeline chạy các kiểm tra tương tự như lần thứ hai.
149+4. **Mermaid のレンダリングにはネットワークが必要** — EPUB ビルドは図のレンダリングに Kroki.io API を呼び出す。ここでビルドが失敗する場合は、ネットワーク問題か Mermaid 構文エラーが典型的な原因である。
145150
146−4. **Mermaid rendering cần network** — EPUB build gọi Kroki.io API để render diagrams. Các lỗi build ở đây thường là vấn đề network hoặc cú pháp Mermaid không hợp lệ.
151+5. **これはチュートリアルでありライブラリではない** — コンテンツを追加する際は、明快な解説、コピー＆ペースト可能な例、視覚的な図を重視する。価値は概念を教えることにあり、再利用可能なコードを提供することではない。
147152
148−5. **Đây là tutorial, không phải thư viện** — Khi thêm nội dung, tập trung vào giải thích rõ ràng, ví dụ copy-paste, và sơ đồ trực quan. Giá trị nằm ở việc dạy các khái niệm, không cung cấp code có thể tái sử dụng.
153+## コミット規約
149154
150−## Commit Conventions
151−
152−Tuân theo format conventional commit:
155+Conventional Commits 形式に従う：
153156 - `feat(slash-commands): Add API documentation generator`
154157 - `docs(memory): Improve personal preferences example`
155158 - `fix(README): Correct table of contents link`
156159 - `refactor(hooks): Simplify hook configuration examples`
157160
158−Scope nên khớp với tên thư mục khi áp dụng.
161+スコープは該当するフォルダ名に合わせる。
159162
