@k2works/claude-code-booster 2.7.1 → 3.1.0

package/lib/assets/docs/article/getting-start-tdd/clojure/04-version-control-and-conventional-commits.md

@@ -0,0 +1,88 @@
+# 第 4 章: バージョン管理と Conventional Commits
+
+## 4.1 はじめに
+
+第 1 部では TDD の基本サイクル（RED → GREEN → REFACTOR）を体験しました。第 2 部では **ソフトウェア開発の三種の神器** を整備します。
+
+> 今日のソフトウェア開発の世界において絶対になければならない 3 つの技術的な柱があります。
+>
+> - バージョン管理
+> - テスティング
+> - 自動化
+>
+> — https://t-wada.hatenablog.jp/entry/clean-code-that-works
+
+## 4.2 バージョン管理
+
+### Git によるバージョン管理
+
+プロジェクトでは Git を使ってソースコードを管理します。作業の区切りごとにコミットを行い、変更履歴を追跡できるようにします。
+
+```bash
+$ git init
+$ git add .
+$ git commit -m "feat: FizzBuzz の基本実装を完了"
+```
+
+### Conventional Commits
+
+コミットメッセージには **Conventional Commits** の規約を使います。
+
+```
+<タイプ>(<スコープ>): <タイトル>
+```
+
+主要なタイプ:
+
+| タイプ | 説明 |
+|--------|------|
+| `feat` | 新機能の追加 |
+| `fix` | バグ修正 |
+| `docs` | ドキュメントの変更のみ |
+| `style` | コードの意味に影響しない変更 |
+| `refactor` | バグ修正でも機能追加でもないコード変更 |
+| `test` | テストの追加や既存テストの修正 |
+| `chore` | ビルドプロセスや補助ツールの変更 |
+
+### コミットの粒度
+
+TDD のリズムに合わせてコミットします。
+
+```bash
+# RED → GREEN → REFACTOR の 1 サイクルごとにコミット
+$ git add -A
+$ git commit -m "feat(clojure): 数を文字列にして返す fizzbuzz 関数を追加"
+
+# リファクタリングは別コミット
+$ git commit -m "refactor(clojure): divisible-by? ヘルパー関数を抽出"
+```
+
+## 4.3 .gitignore の設定
+
+Clojure プロジェクトでは以下のファイルをバージョン管理から除外します。
+
+```gitignore
+# Leiningen
+target/
+.lein-*
+.nrepl-port
+.lein-repl-history
+
+# Java
+*.jar
+*.class
+pom.xml
+pom.xml.asc
+
+# OS
+.DS_Store
+```
+
+## 4.4 まとめ
+
+この章では以下のことを学びました。
+
+- Git によるバージョン管理の基本
+- **Conventional Commits** 規約に従ったコミットメッセージの書き方
+- `.gitignore` による不要ファイルの除外設定
+- TDD サイクルに合わせたコミットの粒度

package/lib/assets/docs/article/getting-start-tdd/clojure/05-package-management-and-static-analysis.md

@@ -0,0 +1,299 @@
+# 第 5 章: パッケージ管理と静的解析
+
+## 5.1 はじめに
+
+この章では Clojure プロジェクトのパッケージ管理と静的コード解析ツールについて学びます。
+
+## 5.2 Leiningen によるパッケージ管理
+
+### project.clj
+
+Leiningen のプロジェクト設定ファイル `project.clj` で依存関係やプラグインを管理します。
+
+```clojure
+(defproject fizzbuzz "0.1.0-SNAPSHOT"
+  :description "FizzBuzz - TDD practice in Clojure"
+  :dependencies [[org.clojure/clojure "1.11.1"]]
+  :plugins [[lein-cloverage "1.2.4"]
+            [lein-kibit "0.1.8"]
+            [jonase/eastwood "1.4.3"]]
+  :main ^:skip-aot fizzbuzz.core
+  :target-path "target/%s"
+  :profiles {:uberjar {:aot :all}})
+```
+
+### 依存関係の管理
+
+```bash
+# 依存関係の取得
+$ lein deps
+
+# 依存関係のツリー表示
+$ lein deps :tree
+```
+
+Leiningen は Maven リポジトリと Clojars から依存関係を自動的にダウンロードします。
+
+## 5.3 静的コード解析
+
+### Eastwood — 静的コード解析
+
+Eastwood はコードの潜在的な問題を検出する Linter です。
+
+```bash
+$ lein eastwood
+```
+
+検出する主な問題:
+
+- 未使用の変数や名前空間
+- 間違った関数呼び出し
+- 非推奨な構文の使用
+- リフレクション警告
+
+### Kibit — イディオム検査
+
+Kibit は Clojure らしい書き方を提案するツールです。
+
+```bash
+$ lein kibit
+```
+
+提案の例:
+
+```clojure
+;; Before（Kibit が改善を提案）
+(if (= x true) :yes :no)
+
+;; After（Clojure イディオム）
+(if x :yes :no)
+```
+
+```clojure
+;; Before
+(not (empty? coll))
+
+;; After
+(seq coll)
+```
+
+### cljfmt — コードフォーマッター
+
+cljfmt は Clojure コードのフォーマットを統一するツールです。
+
+```bash
+# フォーマットチェック
+$ lein cljfmt check
+
+# 自動フォーマット
+$ lein cljfmt fix
+```
+
+## 5.4 コードカバレッジ
+
+静的コード解析による品質の確認ができました。動的なテストに関しては **コードカバレッジ** を確認する必要があります。
+
+> コード網羅率（Code coverage）は、ソフトウェアテストで用いられる尺度の 1 つである。プログラムのソースコードがテストされた割合を意味する。
+>
+> — ウィキペディア
+
+Cloverage を使ってテストカバレッジを計測します。
+
+```bash
+$ lein cloverage
+```
+
+`project.clj` にプラグインを追加済みです。
+
+```clojure
+:plugins [[lein-cloverage "1.2.4"]]
+```
+
+テスト実行後に `target/coverage` フォルダが作成されます。その中の `index.html` を開くとカバレッジ状況を確認できます。
+
+## 5.5 コード複雑度のチェック
+
+静的コード解析では、コーディングスタイルやバグパターンだけでなく、**コードの複雑度** もチェックできます。Clojure プロジェクトでは、Bikeshed による品質チェックと独自の循環複雑度チェッカーを組み合わせて、関数の複雑度を制限します。
+
+### 循環的複雑度（Cyclomatic Complexity）
+
+> 循環的複雑度（サイクロマティック複雑度）とは、ソフトウェア測定法の一つであり、コードがどれぐらい複雑であるかを関数単位で数値にして表す指標。
+
+Clojure では以下のフォームが分岐を生み出し、複雑度を上げます。
+
+| フォーム | 説明 |
+|---------|------|
+| `cond` | 各分岐（`:else` 除く）で +1 |
+| `if` / `if-let` / `if-not` | 条件分岐で +1 |
+| `when` / `when-let` / `when-not` | 条件付き実行で +1 |
+| `case` | 各分岐（デフォルト除く）で +1 |
+| `and` / `or` | 短絡評価による分岐で +1 |
+| `loop` | 再帰ループで +1 |
+| `try` | 例外処理で +1 |
+
+本プロジェクトでは、循環的複雑度を **7 以下** に制限しています。
+
+| 複雑度の範囲 | 意味 |
+|-------------|------|
+| 1〜7 | 低複雑度：管理しやすく、問題なし |
+| 8〜15 | 中程度の複雑度：リファクタリングを検討 |
+| 16 以上 | 高複雑度：関数を分割する必要がある |
+
+```clojure
+;; 循環複雑度が低い例（複雑度: 1）
+(defn simple-function [x]
+  (+ x 1))
+
+;; 循環複雑度が中程度の例（複雑度: 5）
+(defn fizzbuzz [n]
+  (cond
+    (and (zero? (mod n 3)) (zero? (mod n 5))) "FizzBuzz"  ; cond +1, and +1
+    (zero? (mod n 3)) "Fizz"                               ; cond +1
+    (zero? (mod n 5)) "Buzz"                               ; cond +1
+    :else (str n)))                                        ; :else は加算なし
+;; 基本 1 + cond 3 分岐 + and 1 = 5
+```
+
+### Bikeshed — コード品質チェック
+
+[Bikeshed](https://github.com/dakrone/lein-bikeshed) は Clojure コードの品質を総合的にチェックするツールです。
+
+```bash
+$ lein bikeshed
+```
+
+チェック項目:
+
+- 行の長さ（100 文字制限）
+- 末尾の空白
+- ファイル末尾の空行
+- clojure.core 関数との名前衝突
+- docstring の記述率
+
+`project.clj` での設定:
+
+```clojure
+:plugins [[lein-bikeshed "0.5.2"]]
+:bikeshed {:verbose true
+           :max-line-length 100}
+```
+
+### 循環複雑度チェッカー
+
+Clojure には PMD のような循環複雑度チェッカーが標準で提供されていないため、プロジェクト固有のチェッカーを `dev/complexity_checker.clj` に作成しています。
+
+```clojure
+;; dev/complexity_checker.clj（抜粋）
+(def ^:private branching-forms
+  #{'if 'if-let 'if-not 'if-some
+    'when 'when-let 'when-not 'when-some 'when-first
+    'and 'or 'loop 'try})
+
+(defn- complexity-of-form
+  "S 式を再帰的に走査して循環複雑度を計算する"
+  [form]
+  (cond
+    (not (sequential? form)) 0
+    (empty? form) 0
+    :else
+    (let [head (first form)
+          children-complexity (reduce + (map complexity-of-form (rest form)))]
+      (+ children-complexity
+         (cond
+           (= head 'cond) (count-cond-branches form)
+           (= head 'case) (count-case-branches form)
+           (contains? branching-forms head) 1
+           :else 0)))))
+```
+
+このチェッカーは S 式を再帰的に走査し、分岐フォームの数を数えて循環複雑度を計算します。Clojure のホモイコニシティ（コードがデータ構造である性質）を活かしたアプローチです。
+
+### 複雑度チェックの実行
+
+`project.clj` にエイリアスを定義して簡単に実行できるようにします。
+
+```clojure
+:aliases {"complexity" ["run" "-m" "complexity-checker"]}
+:profiles {:dev {:source-paths ["dev"]}}
+```
+
+```bash
+$ lein complexity
+
+=== Clojure 循環複雑度チェック (閾値: 7) ===
+
+  [ok] fizzbuzz (core.clj)                      複雑度: 5
+  [ok] create-type (type.clj)                   複雑度: 3
+  [ok] fizz-buzz? (model.clj)                   複雑度: 2
+  [ok] fizzbuzz-list (core.clj)                 複雑度: 1
+  [ok] print-fizzbuzz (core.clj)                複雑度: 1
+  ...
+
+関数数: 10, 違反: 0
+
+複雑度チェック: 成功
+```
+
+Makefile でも実行できます。
+
+```bash
+$ make complexity
+```
+
+### 複雑度チェックの効果
+
+コード複雑度の制限により、以下の効果が得られます。
+
+- **可読性向上** — 小さな関数は理解しやすい
+- **保守性向上** — 変更の影響範囲が限定される
+- **テスト容易性** — 個別機能のテストが簡単
+- **自動品質管理** — 複雑なコードの混入を自動防止
+
+現在の FizzBuzz の `fizzbuzz` 関数は循環複雑度が 5 で、制限値 7 以内に収まっています。第 3 部でプロトコルとマルチメソッドによる設計を進める際も、この制限を意識してコードを書いていきます。
+
+## 5.6 名前空間と依存関理
+
+Clojure では `ns` マクロで名前空間を定義し、`:require` で依存関係を宣言します。
+
+```clojure
+(ns fizzbuzz.core
+  (:require [fizzbuzz.domain.model :as model]
+            [fizzbuzz.domain.type :as type])
+  (:gen-class))
+```
+
+名前空間の命名規則:
+
+| 名前空間 | ファイルパス | 役割 |
+|----------|-------------|------|
+| `fizzbuzz.core` | `src/fizzbuzz/core.clj` | 公開 API |
+| `fizzbuzz.domain.model` | `src/fizzbuzz/domain/model.clj` | 値オブジェクト |
+| `fizzbuzz.domain.type` | `src/fizzbuzz/domain/type.clj` | タイプ定義 |
+| `fizzbuzz.application.command` | `src/fizzbuzz/application/command.clj` | コマンド |
+
+## 5.7 まとめ
+
+この章では、パッケージ管理と静的コード解析を導入しました。
+
+| ツール | 用途 | コマンド |
+|--------|------|---------|
+| Leiningen | 依存関係管理・ビルド | `lein deps` |
+| Eastwood | 静的コード解析 | `lein eastwood` |
+| Kibit | イディオム検査 | `lein kibit` |
+| Bikeshed | コード品質チェック | `lein bikeshed` |
+| 循環複雑度チェッカー | 関数の複雑度計測 | `lein complexity` |
+| cljfmt | コードフォーマット | `lein cljfmt check` |
+| Cloverage | テストカバレッジ | `lein cloverage` |
+
+この章では以下のことを学びました。
+
+- **Leiningen** による依存関係管理と `project.clj` の構成
+- **Eastwood** による静的コード解析
+- **Kibit** による Clojure イディオムの検査
+- **cljfmt** によるコードフォーマット
+- **Cloverage** によるテストカバレッジ計測
+- **Bikeshed** によるコード品質チェック
+- **循環複雑度チェッカー** による関数複雑度の自動検出
+- `ns` マクロによる名前空間と依存関係の管理
+
+次の章では、これらのタスクをまとめて実行できるタスクランナーと、CI/CD パイプラインの構築について解説します。

package/lib/assets/docs/article/getting-start-tdd/clojure/06-task-runner-and-ci-cd.md

@@ -0,0 +1,241 @@
+# 第 6 章: タスクランナーと CI/CD
+
+## 6.1 はじめに
+
+前章では静的コード解析ツールとコード複雑度チェッカーを導入しました。テストの実行、静的解析、複雑度チェック、フォーマットチェックと、様々なコマンドを使えるようになりましたが、毎回それぞれのコマンドを覚えて実行するのは面倒です。
+
+この章では **タスクランナー** を使ってこれらのタスクをまとめて実行できるようにし、さらに **Nix** による再現可能な開発環境と **GitHub Actions** による **CI/CD** パイプラインを構築します。
+
+## 6.2 Nix による開発環境
+
+### Nix とは
+
+> Nix は再現可能なビルドと宣言的な環境管理を提供するパッケージマネージャです。`flake.nix` で開発環境を定義すると、チームメンバー全員が同じツールチェインを使えます。
+
+本プロジェクトでは `nix develop .#clojure` コマンドで Clojure 開発に必要なすべてのツールが揃った環境に入れます。
+
+```bash
+$ nix develop .#clojure
+Clojure development environment activated
+  - Clojure: Clojure 1.11.x
+  - Leiningen: Leiningen 2.x.x
+  - Babashka: x.x.x
+  - Clojure LSP: x.x.x
+```
+
+### Nix 環境の構成
+
+`ops/nix/environments/clojure/shell.nix` で環境を定義しています。
+
+```nix
+{ packages ? import <nixpkgs> {} }:
+let
+  baseShell = import ../../shells/shell.nix { inherit packages; };
+in
+packages.mkShell {
+  inherit (baseShell) pure;
+  buildInputs = baseShell.buildInputs ++ (with packages; [
+    clojure
+    leiningen
+    babashka
+    clojure-lsp
+  ]);
+  shellHook = ''
+    ${baseShell.shellHook}
+    echo "Clojure development environment activated"
+  '';
+}
+```
+
+| パッケージ | 用途 |
+|-----------|------|
+| `clojure` | Clojure ランタイム（JVM 上） |
+| `leiningen` | プロジェクト管理・ビルドツール |
+| `babashka` | スクリプティング用 Clojure |
+| `clojure-lsp` | Language Server Protocol 実装 |
+
+### Nix を使う利点
+
+- **再現性** — `flake.lock` でバージョンを固定し、誰がいつビルドしても同じ結果
+- **分離** — システムの Clojure や Java に依存せず、プロジェクト専用の環境を構築
+- **CI 統合** — ローカルと CI で同じ `nix develop` コマンドを使い、環境差異をゼロに
+
+## 6.3 Makefile によるタスク管理
+
+### Makefile とは
+
+> Makefile は Unix 系の定番ビルド/タスク管理ツールである make の設定ファイルです。ターゲット（タスク名）と依存関係、実行コマンドを定義し、`make <ターゲット>` で実行できます。
+
+### Makefile の定義
+
+```makefile
+.PHONY: test lint kibit fmt fmt-check complexity bikeshed coverage check build run clean
+
+test:
+	lein test
+
+lint:
+	lein eastwood
+
+kibit:
+	lein kibit
+
+fmt:
+	lein cljfmt fix || true
+
+fmt-check:
+	lein cljfmt check || true
+
+complexity:
+	lein complexity
+
+bikeshed:
+	lein bikeshed
+
+coverage:
+	lein cloverage
+
+check: lint kibit complexity test
+
+build:
+	lein uberjar
+
+run:
+	lein run
+
+clean:
+	lein clean
+```
+
+### 主要なタスク
+
+| タスク | コマンド | 説明 |
+|--------|---------|------|
+| `make test` | `lein test` | テスト実行 |
+| `make lint` | `lein eastwood` | Eastwood による静的解析 |
+| `make kibit` | `lein kibit` | Kibit によるイディオム検査 |
+| `make complexity` | `lein complexity` | 循環複雑度チェック |
+| `make bikeshed` | `lein bikeshed` | コード品質チェック |
+| `make fmt` | `lein cljfmt fix` | コードフォーマット |
+| `make coverage` | `lein cloverage` | テストカバレッジ計測 |
+| `make check` | lint → kibit → complexity → test | 全チェック実行 |
+
+### 実行例
+
+```bash
+# Nix 環境に入る
+$ nix develop .#clojure
+
+# 全チェック実行
+$ make check
+lein eastwood
+== Warnings: 0. Exceptions thrown: 0
+lein kibit
+lein complexity
+=== Clojure 循環複雑度チェック (閾値: 7) ===
+関数数: 10, 違反: 0
+複雑度チェック: 成功
+lein test
+Ran 10 tests containing 38 assertions.
+0 failures, 0 errors.
+```
+
+## 6.4 GitHub Actions による CI/CD
+
+### CI/CD とは
+
+> CI/CD（Continuous Integration / Continuous Delivery）は、コードの変更を自動的にビルド、テスト、デプロイするプラクティスです。
+
+### ワークフローの定義
+
+`.github/workflows/clojure-ci.yml` にワークフローを定義します。ローカル開発と同じ **Nix** 環境を CI でも使用し、環境差異をゼロにします。
+
+```yaml
+name: Clojure CI
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - "apps/clojure/**"
+      - ".github/workflows/clojure-ci.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "apps/clojure/**"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v30
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Cache Nix store
+        uses: actions/cache@v4
+        with:
+          path: /tmp/nix-cache
+          key: ${{ runner.os }}-nix-clojure-${{ hashFiles('flake.lock', 'ops/nix/environments/clojure/shell.nix') }}
+          restore-keys: |
+            ${{ runner.os }}-nix-clojure-
+
+      - name: Run linter (Eastwood)
+        run: nix develop .#clojure --command bash -c "cd apps/clojure && lein eastwood"
+
+      - name: Run complexity check
+        run: nix develop .#clojure --command bash -c "cd apps/clojure && lein complexity"
+
+      - name: Run tests
+        run: nix develop .#clojure --command bash -c "cd apps/clojure && lein test"
+```
+
+### CI パイプラインの流れ
+
+```
+Push / PR → Checkout → Nix インストール → Nix キャッシュ復元
+→ Eastwood 静的解析 → 循環複雑度チェック → テスト実行 → 結果通知
+```
+
+### Nix 統合のポイント
+
+1. **`cachix/install-nix-action@v30`** — GitHub Actions ランナーに Nix をインストール
+2. **`nix develop .#clojure --command bash -c "..."`** — Nix 環境内でコマンドを実行
+3. **Nix ストアキャッシュ** — `flake.lock` と `shell.nix` のハッシュでキャッシュキーを生成し、ビルド時間を短縮
+4. **環境の一致** — ローカルの `nix develop .#clojure` と CI の環境が完全に同一
+
+## 6.5 他言語との比較
+
+| 言語 | タスクランナー | CI 環境 | テスト | 静的解析 | 複雑度チェック |
+|------|-------------|---------|--------|---------|-------------|
+| Clojure | Makefile | Nix | lein test | Eastwood + Kibit | 循環複雑度チェッカー |
+| Rust | Makefile | Nix | cargo test | Clippy | Clippy cognitive_complexity |
+| Go | Makefile | Nix | go test | golangci-lint | golangci-lint gocyclo |
+| Java | Gradle | setup-java | JUnit | Checkstyle + PMD | PMD CyclomaticComplexity |
+| Python | tox | Nix | pytest | Ruff | Ruff McCabe |
+| Node | npm scripts | Nix | Vitest | ESLint | ESLint complexity |
+| Ruby | Rake | Nix | Minitest | RuboCop | RuboCop Metrics |
+| PHP | Composer scripts | Nix | PHPUnit | PHP_CodeSniffer + PHPStan | PHPMD |
+| C#/F# | Cake | Nix | xUnit | SonarAnalyzer | SonarAnalyzer |
+
+## 6.6 まとめ
+
+この章では以下を実現しました。
+
+| 項目 | 内容 |
+|------|------|
+| Nix | `nix develop .#clojure` で再現可能な開発環境を構築 |
+| Makefile | test / lint / kibit / complexity / check タスクを定義 |
+| `make check` | Eastwood → Kibit → 複雑度チェック → テストを一括実行 |
+| GitHub Actions | push / PR 時に Nix 環境で自動 CI を実行 |
+| Nix 統合 | CI でも `nix develop .#clojure` を使用しローカルと環境を統一 |
+
+第 2 部を通じて、ソフトウェア開発の三種の神器（バージョン管理、テスティング、自動化）を Clojure の開発環境に整備しました。次の第 3 部では、プロトコルとマルチメソッドによるポリモーフィズムに進みます。