mirror of https://github.com/luongnv89/claude-howto.git synced 2026-08-17 00:10:22 +02:00

Files

T

Luong NGUYEN 4f3fa85d7e docs: follow-ups from the v2.1.220 accuracy review (#161 )

* fix(ci): move the EPUB build out of pre-commit into CI

The build-epub hooks called scripts/build_epub.py, which raises when the
mmdc binary is missing, while check_mermaid.py skips with a warning in the
same situation. On arm64 — where @mermaid-js/mermaid-cli has no working
build — that made 'pre-commit run --all-files' impossible to satisfy for a
docs-only change without --no-verify.

Remove the build-epub, vietnamese-build-epub and japanese-build-epub hooks
and widen the CI build-epub job to a language matrix so PR-time coverage is
not reduced: it previously built en only, and now builds en, vi, zh and ja.
zh was covered by neither the hooks nor this job, so a broken zh diagram
could only surface at release time.

Closes #156

* docs: replace the stale Kroki narrative with local mmdc rendering

Commit e76bbe4 swapped the Kroki HTTP dependency for local mmdc rendering
but left the docs describing the old design. The claim appeared in seven
live files, not the two originally reported: CLAUDE.md, scripts/README.md
and their ja/uk/vi copies.

Also corrects what the same staleness dragged along:
- scripts/README.md documented --timeout and --max-concurrent, which no
  longer exist, and omitted --mmdc-path, --lang and --puppeteer-config
- 'Async concurrent fetching' described a render_all() that is now a plain
  sequential loop with a dedupe cache
- the network-error/rate-limiting troubleshooting entries are replaced with
  the failures that actually occur now (missing mmdc, Chromium sandbox)

CHANGELOG entries recording the Kroki-to-mmdc switch are left alone; they
describe the past accurately.

Closes #157

* fix(scripts): make the ruff config match files that exist

Ruff resolves include/per-file-ignores patterns relative to the directory
holding pyproject.toml. Since the config lives in scripts/, the pattern
"scripts/**/*.py" meant scripts/scripts/**/*.py, which matches nothing —
'ruff check scripts/' printed 'warning: No Python files found under the
given path(s)' and then 'All checks passed!'. per-file-ignores had the same
mistake. Both are now relative to scripts/, so ruff sees all 14 files.

This silently disabled the pre-commit ruff hooks too, not just the
documented command, and two test files had drifted out of format as a
result. Reformatting them exposed a second problem: the pre-commit hook
pinned ruff v0.8.2 while the CI lint job installs unpinned latest and this
venv has 0.15.10. The versions disagree on formatting, so each reverted the
other's output, and CI would have started failing on a file the local hook
kept rewriting. Bump the hook pin and the requirements-dev floor to 0.15.10
so all three agree.

Verified: 'pre-commit run --all-files' is stable across consecutive runs,
'ruff format --check scripts/' and 'ruff check scripts/' both pass, 92
tests pass.

Closes #160

* docs: point localized module links at their own trees

Files at the root of a language directory used ../NN-module/, which from
uk/CATALOG.md resolves to the English 05-mcp/ at the repo root rather than
uk/05-mcp/. Readers following a count stated about the localized tree
landed in the English one. The link checker never caught it because the
English target does exist.

Files one level deeper (uk/04-subagents/README.md and friends) were already
correct — ../06-hooks/ from there resolves to uk/06-hooks/ — so this is
scoped to the 7 depth-1 files that actually escape: CATALOG.md in uk, vi,
ja and zh, LEARNING-ROADMAP.md in uk and vi, and ja/claude_concepts_guide.md.
119 links in total.

The ../NN- occurrences left in STYLE_GUIDE.md and TRANSLATION_NOTES.md are
inside fenced examples showing what a module page should contain, where the
../ form is the correct convention. All 119 rewritten targets were verified
to exist.

Closes #158

* docs(hooks): stop conflating hook types with hook event categories

'**Hook Types** (5 types, 31 events)' sat above four bullets, so the count
read as wrong. It was not — the two numbers describe different axes that
had been merged into one label.

06-hooks/README.md:126 documents five hook *types*: command, http, prompt,
mcp_tool and agent. Those describe how a hook runs. The four bullets are
event *categories* — Tool, Session, Task, Lifecycle — holding 31 events
(6+7+6+12), and describe when it runs.

Split the label so each number belongs to the axis it counts, in all nine
affected files: README.md and INDEX.md plus the ja, uk, vi and zh copies.
QUICK_REFERENCE.md and LEARNING-ROADMAP.md already stated '5 types' with
the handler names attached and needed no change.

Closes #159

* chore(scripts): drop the unused httpx dependency

httpx was the HTTP client for Kroki rendering. Nothing has imported it
since e76bbe4 moved diagram rendering to a local mmdc subprocess —
check_links.py, the only other network caller, uses stdlib urllib.request.
The PEP 723 blocks in build_epub.py and build_website.py had already
dropped it; only the manifests and docs still declared it.

Removes it from requirements.txt, pyproject.toml dependencies, the
dependency tables and uv --with lines in scripts/README.md and its ja/uk
copies, and the .cspell.json word list. Also drops the B113 bandit
suppression, which existed solely for an httpx timeout false positive —
bandit reports no issues without it.

Also corrects two Requirements lines missed in the previous pass: the ja
and uk script READMEs still listed an internet connection rather than mmdc.

Note: tenacity is now dead for the same reason and is left in place.

* chore(scripts): drop the unused tenacity dependency

Nothing imports tenacity — the retry logic it was added for went away
with the Kroki HTTP fetching in e76bbe4. It was still declared in
requirements.txt, pyproject.toml, both `uv run --with` lines and all
three dependency tables.

* docs(i18n): sync the localized pre-commit check lists

The ja/uk/vi CLAUDE.md files still listed build-epub as pre-commit
check #5, stale since 6da8184 moved the EPUB build to CI. They also
omitted markdown-rendering, and the ja/uk stated counts disagreed with
their own lists. Now matches the English CLAUDE.md.

* fix(scripts): silence PLR0917 now stable in ruff 0.16

CI installs the latest ruff (uv pip install ruff, unpinned), and 0.16.1
promoted too-many-positional-arguments from preview to stable, hard-failing
the Code Quality check on build_epub.py's long-signature draw/helper
functions. These sit in the same family as PLR0913, which is already
ignored. Add PLR0917 so the local 0.15.10 pin and unpinned CI lint agree
again.

2026-08-06 07:58:46 +07:00

7.8 KiB

Raw Blame History

CLAUDE.md

このファイルは、本リポジトリ内のコードを扱う際の Claude Code（claude.ai/code）向けガイドである。

プロジェクト概要

Claude How To は Claude Code 機能のチュートリアルリポジトリである。これは ドキュメント・アズ・コード であり、主な成果物は実行可能アプリケーションではなく、番号付きの学習モジュールに整理された Markdown ファイルである。

アーキテクチャ： 各モジュール（01〜10）は Claude Code の特定の機能を、コピー＆ペースト可能なテンプレート、Mermaid 図、サンプルとともに解説する。ビルドシステムはドキュメントの品質を検証し、EPUB 電子書籍を生成する。

よく使うコマンド

pre-commit 品質チェック

すべてのドキュメントは、コミット前に 5 つの品質チェックを通過しなければならない（pre-commit フックで自動実行される）：

# pre-commit フックをインストール（毎コミットで実行）
pre-commit install

# 全チェックを手動で実行
pre-commit run --all-files

5 つのチェックは以下のとおり：

markdown-lint — markdownlint による Markdown 構造とフォーマット
cross-references — 内部リンク、アンカー、コードフェンスの構文（Python スクリプト）
mermaid-syntax — すべての Mermaid 図が正しくパースされるかを検証（Python スクリプト）
link-check — 外部 URL が到達可能か（Python スクリプト）
markdown-rendering — Markdown が壊れずにレンダリングされるか（Python スクリプト）

EPUB ビルドは pre-commit フック ではない — CI のみで実行される（.github/workflows/test.yml の build-epub ジョブ）。ローカルの mmdc バイナリが必要であり、arm64 で動作するビルドが存在しないためである。

開発環境のセットアップ

# uv（Python パッケージマネージャ）をインストール
pip install uv

# 仮想環境を作成して Python 依存関係をインストール
uv venv
source .venv/bin/activate
uv pip install -r scripts/requirements-dev.txt

# Node.js ツール（Markdown リンタと Mermaid バリデータ）をインストール
npm install -g markdownlint-cli
npm install -g @mermaid-js/mermaid-cli

# pre-commit フックをインストール
uv pip install pre-commit
pre-commit install

テスト

scripts/ 内の Python スクリプトはユニットテストを持つ：

# 全テストを実行
pytest scripts/tests/ -v

# カバレッジ付きで実行
pytest scripts/tests/ -v --cov=scripts --cov-report=html

# 特定のテストを実行
pytest scripts/tests/test_build_epub.py -v

コード品質

# Python コードをリント・整形
ruff check scripts/
ruff format scripts/

# セキュリティスキャン
bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/

# 型チェック
mypy scripts/ --ignore-missing-imports

EPUB ビルド

# 電子書籍を生成（Mermaid 図はローカルの mmdc CLI でレンダリング／ネットワーク不要）
uv run scripts/build_epub.py

# オプション付き
uv run scripts/build_epub.py --verbose --output custom-name.epub --lang ja

ディレクトリ構造

├── 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/
│   ├── build_epub.py           # EPUB ジェネレータ（Mermaid をローカル mmdc でレンダリング）
│   ├── check_cross_references.py   # 内部リンクを検証
│   ├── check_links.py          # 外部 URL を検証
│   ├── check_mermaid.py        # Mermaid 構文を検証
│   └── tests/                  # スクリプトのユニットテスト
├── .pre-commit-config.yaml    # 品質チェック定義
└── README.md               # メインガイド（モジュール索引も兼ねる）

コンテンツ作成ガイド

モジュール構造

番号付きフォルダはいずれも以下のパターンに従う：

README.md — 機能の概要と例
サンプルファイル — コピー＆ペースト可能なテンプレート（コマンドは .md、設定は .json、フックは .sh）
ファイルは機能の複雑さと依存関係に従って整理されている

Mermaid 図

すべての図は正常にパースできること（pre-commit フックで検査）
EPUB ビルドはローカルの mmdc CLI で図をレンダリングする（ネットワークは不要だが mmdc が必要）
フローチャート、シーケンス図、アーキテクチャ可視化に Mermaid を使用する

相互参照

内部リンクは相対パスを使う（例：(01-slash-commands/README.md)）
コードフェンスは言語指定が必須（例：```bash、```python）
アンカーリンクは #heading-name 形式

リンク検証

外部 URL は到達可能であること（pre-commit フックで検査）
一時的なコンテンツへのリンクは避ける
可能な限りパーマリンクを使用する

主要なアーキテクチャ上のポイント

番号付きフォルダは学習順序を示す — 01〜10 のプレフィックスは Claude Code 機能の推奨学習順序を表す。この番号付けは意図的なものなので、アルファベット順に並べ替えてはならない。
スクリプトはユーティリティであり製品ではない — scripts/ の Python スクリプトはドキュメント品質と EPUB 生成を支援するものである。実際のコンテンツは番号付きモジュールフォルダにある。
pre-commit がゲートキーパー — PR が承認される前に 5 つの品質チェックがすべて通過しなければならない。CI パイプラインは同じチェックを 2 回目のパスとして実行する。
Mermaid のレンダリングにはローカルの mmdc が必要 — EPUB ビルドは図のレンダリングにローカルの mmdc CLI を呼び出す（ネットワークは不要）。ここでビルドが失敗する場合は、mmdc が未インストールか、Mermaid 構文エラーが典型的な原因である。EPUB ビルド自体は pre-commit では実行されず、CI のみで実行される。
これはチュートリアルでありライブラリではない — コンテンツを追加する際は、明快な解説、コピー＆ペースト可能な例、視覚的な図を重視する。価値は概念を教えることにあり、再利用可能なコードを提供することではない。

コミット規約

Conventional Commits 形式に従う：

feat(slash-commands): Add API documentation generator
docs(memory): Improve personal preferences example
fix(README): Correct table of contents link
refactor(hooks): Simplify hook configuration examples

スコープは該当するフォルダ名に合わせる。

7.8 KiB Raw Blame History Unescape Escape