@k2works/claude-code-booster 2.7.1 → 3.1.0

package/lib/assets/docs/article/getting-start-tdd/scala/02-fake-it-and-triangulation.md

@@ -0,0 +1,107 @@
+# 第 2 章: 仮実装と三角測量
+
+## 2.1 はじめに
+
+第 1 章では、最小の 1 ケースを Green にしました。
+この章では、次の 2 つのテクニックで実装を育てます。
+
+- Fake It: まず動く最小のコードを書く
+- Triangulation: 複数ケースから一般ルールを導く
+
+## 2.2 仮実装（Fake It）
+
+まず `2` のケースを追加して、仮実装の限界を明確にします。
+
+```scala
+test("2 を渡すと文字列 2 を返す") {
+  assert(FizzBuzz.generate(2) === "2")
+}
+```
+
+このテストは失敗します。
+現在の実装は常に `"1"` を返すためです。
+
+ここで実装を一段だけ一般化します。
+
+```scala
+object FizzBuzz:
+  def generate(number: Int): String = number.toString
+```
+
+`1` と `2` のテストがともに通れば Green です。
+
+## 2.3 三角測量（Triangulation）
+
+Triangulation は、1 つの具体例だけで一般化せず、2 つ以上の点で法則を確定する手法です。
+
+実践手順は次の通りです。
+
+1. 具体的な新テストを 1 つ追加して失敗を作る
+2. 最小変更でテストを通す
+3. 既存テストも含めて一貫するルールか確認する
+
+この繰り返しにより、偶然通る実装ではなく、仕様に沿う実装へ近づけます。
+
+## 2.4 Fizz のテスト
+
+次に 3 の倍数ケースを追加します。
+
+```scala
+test("3 の倍数を渡すと Fizz を返す") {
+  assert(FizzBuzz.generate(3) === "Fizz")
+}
+```
+
+テストを通す最小実装の例です。
+
+```scala
+object FizzBuzz:
+  def generate(number: Int): String =
+    if number % 3 == 0 then "Fizz"
+    else number.toString
+```
+
+`if` でも `match` でも構いません。
+この時点では、可読性よりも小さなステップを優先します。
+
+## 2.5 Buzz のテスト
+
+続いて 5 の倍数ケースを追加します。
+
+```scala
+test("5 の倍数を渡すと Buzz を返す") {
+  assert(FizzBuzz.generate(5) === "Buzz")
+}
+```
+
+最小実装の例です。
+
+```scala
+object FizzBuzz:
+  def generate(number: Int): String =
+    if number % 3 == 0 then "Fizz"
+    else if number % 5 == 0 then "Buzz"
+    else number.toString
+```
+
+まだ 15 のケースは未対応なので、次章で仕上げます。
+
+## 2.6 TODO リストの更新
+
+ここまでの完了状態を反映します。
+
+- [x] `FizzBuzz.generate(1)` が `"1"` を返す
+- [x] `FizzBuzz.generate(2)` が `"2"` を返す
+- [x] `FizzBuzz.generate(3)` が `"Fizz"` を返す
+- [x] `FizzBuzz.generate(5)` が `"Buzz"` を返す
+- [ ] `FizzBuzz.generate(15)` が `"FizzBuzz"` を返す
+- [ ] `FizzBuzz.generateList(100)` が 100 件の結果を返す
+
+## 2.7 まとめ
+
+この章のポイントは次の 2 点です。
+
+- Fake It で、まず動く最小実装を作る
+- Triangulation で、複数のテストケースから実装を一般化する
+
+次章では、`15` と `generateList` を追加して実装を完成させます。

package/lib/assets/docs/article/getting-start-tdd/scala/03-obvious-implementation-and-refactoring.md

@@ -0,0 +1,99 @@
+# 第 3 章: 明白な実装とリファクタリング
+
+## 3.1 はじめに
+
+この章では、残っている仕様を満たして実装を完成させます。
+
+- Obvious Implementation: 仕様が明確なら、素直で読みやすい実装を選ぶ
+- Refactoring: 振る舞いを変えずに構造を整理する
+
+## 3.2 FizzBuzz のテスト
+
+まず 15 の倍数ケースを追加します。
+
+```scala
+test("15 の倍数を渡すと FizzBuzz を返す") {
+  assert(FizzBuzz.generate(15) === "FizzBuzz")
+}
+```
+
+ここで重要なのは判定順序です。
+`3` と `5` を先に判定すると `15` が `Fizz` または `Buzz` になってしまうため、`15` を最初に判定する必要があります。
+
+## 3.3 明白な実装
+
+仕様が揃った段階で、`match` を使って読みやすく整理します。
+
+```scala
+object FizzBuzz:
+  def generate(number: Int): String =
+    number match
+      case n if n % 15 == 0 => "FizzBuzz"
+      case n if n % 3 == 0  => "Fizz"
+      case n if n % 5 == 0  => "Buzz"
+      case n                => n.toString
+```
+
+この実装は仕様との対応が 1 対 1 で追いやすく、将来の拡張時にも安全です。
+
+## 3.4 リストの生成
+
+続いて `generateList` を追加します。
+
+```scala
+def generateList(count: Int): List[String] =
+  (1 to count).map(generate).toList
+```
+
+対応するテストを追加します。
+
+```scala
+test("1 から 100 までのリストを生成する") {
+  val result = FizzBuzz.generateList(100)
+  assert(result.length === 100)
+  assert(result.head === "1")
+  assert(result(2) === "Fizz")
+  assert(result(4) === "Buzz")
+  assert(result(14) === "FizzBuzz")
+}
+```
+
+`length` と代表値を確認することで、リスト全体の生成と変換ロジックを同時に検証できます。
+
+## 3.5 リファクタリング
+
+この実装では Scala の特性を活かせます。
+
+- Pattern matching により条件分岐の意図が明確になります。
+- `Range` と `map` により副作用のない関数型スタイルで記述できます。
+
+振る舞いを変えない範囲で、命名や重複の整理を行います。
+
+## 3.6 プログラムの実行
+
+手元で確認するために `main` メソッドを追加します。
+
+```scala
+@main def runFizzBuzz(): Unit =
+  FizzBuzz.generateList(100).foreach(println)
+```
+
+実行は `sbt run` です。
+`1` から `100` までの結果が順に出力されます。
+
+## 3.7 まとめ
+
+3 章を通じて、FizzBuzz を題材に TDD の基本サイクルを完走しました。
+
+- Red: 仕様ごとに失敗するテストを追加
+- Green: 最小実装で段階的に通過
+- Refactor: 明白で読みやすい形に整理
+
+TODO リストの最終状態です。
+
+- [x] `FizzBuzz.generate(1)` が `"1"` を返す
+- [x] `FizzBuzz.generate(2)` が `"2"` を返す
+- [x] `FizzBuzz.generate(3)` が `"Fizz"` を返す
+- [x] `FizzBuzz.generate(5)` が `"Buzz"` を返す
+- [x] `FizzBuzz.generate(15)` が `"FizzBuzz"` を返す
+- [x] `FizzBuzz.generateList(100)` が 100 件の結果を返す

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

@@ -0,0 +1,123 @@
+# 第 4 章: バージョン管理と Conventional Commits
+
+## 4.1 はじめに
+
+ソフトウェア開発では、変更履歴を安全に管理し、チームで追跡可能にする仕組みが重要です。
+Git による版管理とコミットメッセージ規約を整えることで、TDD の小さな変更を確実に積み上げられます。
+
+## 4.2 Git によるバージョン管理
+
+Scala プロジェクト（`apps/scala`）では、次の基本フローで変更を記録します。
+
+```bash
+cd apps/scala
+git init
+git add .
+git commit -m "chore(scala): initialize sbt project"
+```
+
+`git init` でリポジトリを初期化し、`git add` でステージング、`git commit` で履歴を確定します。
+TDD では Red → Green → Refactor の小さな単位でコミットすると、変更意図を追いやすくなります。
+
+### .gitignore の設定
+
+`apps/scala/.gitignore` には、ビルド成果物と IDE 補助ファイルを含めます。
+
+```bash
+target/
+.bsp/
+.metals/
+.bloop/
+.idea/
+*.class
+*.log
+*.jar
+.DS_Store
+project/metals.sbt
+project/project/
+```
+
+最低限として、次の 4 つは必ず除外します。
+
+- `target/`
+- `.bsp/`
+- `.metals/`
+- `.bloop/`
+
+## 4.3 Conventional Commits
+
+Conventional Commits は、Angular Convention に由来するコミットメッセージ規約です。
+基本フォーマットは次の通りです。
+
+```text
+<type>(<scope>): <subject>
+```
+
+- `type`: 変更種別
+- `scope`: 変更対象（任意）
+- `subject`: 変更内容の要約（命令形・簡潔）
+
+### type の種類
+
+- `feat`: 新機能の追加
+- `fix`: バグ修正
+- `docs`: ドキュメント変更
+- `style`: 振る舞いに影響しない整形
+- `refactor`: 振る舞いを変えない構造改善
+- `test`: テスト追加・修正
+- `chore`: ビルドや設定などの雑務
+
+### scope と subject の書き方
+
+- `scope` はモジュール単位で短く書きます（例: `scala`, `fizzbuzz`, `ci`）。
+- `subject` は 50 文字前後を目安に、何をしたかを明確に書きます。
+- 末尾の句点は付けません。
+
+### コミットメッセージの例
+
+```text
+test(fizzbuzz): add failing test for multiples of 15
+feat(fizzbuzz): implement generateList for 1 to n
+refactor(fizzbuzz): simplify rule matching order
+docs(scala): add chapter about sbt and scalafmt
+chore(ci): add scala-ci workflow for pull requests
+```
+
+## 4.4 ブランチ戦略
+
+### Git Flow の基本概念
+
+Git Flow では、主に次のブランチを使います。
+
+- `main`: リリース済みの安定コード
+- `develop`: 開発統合ブランチ
+- `feature/*`: 機能開発ブランチ
+- `release/*`: リリース準備ブランチ
+- `hotfix/*`: 緊急修正ブランチ
+
+学習用プロジェクトでは、まず `main` と `feature/*` の運用から始めると実践しやすいです。
+
+### feature ブランチの作成と運用
+
+```bash
+git switch main
+git pull origin main
+git switch -c feature/scala-chapter-04
+```
+
+運用ポイントは次の通りです。
+
+- 1 ブランチ 1 テーマに絞ります。
+- Red / Green / Refactor の区切りで小さくコミットします。
+- 完了後に Pull Request を作成し、レビュー後に `main` へマージします。
+
+## 4.5 まとめ
+
+この章では、Scala の TDD 開発を支える版管理の基礎を整理しました。
+
+- Git の基本操作で変更履歴を安全に管理する
+- `.gitignore` で不要ファイルを除外する
+- Conventional Commits で履歴を読みやすくする
+- `feature` ブランチ運用で変更を分離する
+
+次章では、`sbt` を中心にパッケージ管理と静的解析を整備します。

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

@@ -0,0 +1,196 @@
+# 第 5 章: パッケージ管理と静的解析
+
+## 5.1 はじめに
+
+Scala 開発では、依存関係の管理とコード品質の維持を仕組み化することが重要です。
+この章では、`sbt` によるパッケージ管理と `scalafmt`、`WartRemover`、コンパイラオプションによる品質管理を扱います。
+
+## 5.2 sbt によるパッケージ管理
+
+### build.sbt の構成
+
+`apps/scala/build.sbt` では、プロジェクトの基本情報と依存関係を定義します。
+
+```scala
+lazy val root = (project in file("."))
+  .settings(
+    name := "fizzbuzz",
+    version := "0.1.0",
+    scalaVersion := "3.3.4",
+    libraryDependencies ++= Seq(
+      "org.scalatest" %% "scalatest" % "3.2.18" % Test
+    )
+  )
+```
+
+- `name`: プロジェクト名
+- `version`: アプリケーションのバージョン
+- `scalaVersion`: 使用する Scala バージョン
+- `libraryDependencies`: 利用ライブラリ
+
+### プラグインの追加（project/plugins.sbt）
+
+`sbt` プラグインは `apps/scala/project/plugins.sbt` に追加します。
+
+```scala
+addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.5.2")
+addSbtPlugin("org.wartremover" % "sbt-wartremover" % "3.2.5")
+```
+
+### 依存関係の管理（`%` と `%%` の違い、Test スコープ）
+
+- `%`: Java など Scala バージョンに依存しない Artifact に使います。
+- `%%`: Scala バージョン接尾辞（例: `_3`）を自動付与します。
+- `% Test`: テスト時だけ必要な依存関係に付けます。
+
+例:
+
+```scala
+"org.scalatest" %% "scalatest" % "3.2.18" % Test
+```
+
+この指定により、本番 Artifact には `ScalaTest` が含まれません。
+
+## 5.3 scalafmt によるコードフォーマット
+
+`apps/scala/.scalafmt.conf` は次の設定です。
+
+```scala
+version = 3.7.17
+runner.dialect = scala3
+maxColumn = 100
+```
+
+整形コマンド:
+
+```bash
+cd apps/scala
+sbt scalafmt
+sbt scalafmtCheck
+```
+
+- `sbt scalafmt`: 自動整形
+- `sbt scalafmtCheck`: 未整形コードを検出（CI 向け）
+
+## 5.4 WartRemover による静的解析
+
+`WartRemover` は危険な記述をコンパイル時に検出する静的解析ツールです。
+
+### build.sbt への設定追加
+
+`build.sbt` に次のような設定を追加します。
+
+```scala
+wartremoverErrors ++= Seq(
+  Wart.Null,
+  Wart.Var,
+  Wart.Return
+)
+```
+
+### 検出される問題の種類
+
+- `Null`: `null` 利用による `NullPointerException` リスク
+- `Var`: 可変変数による状態変化の複雑化
+- `Return`: 早期 return による制御フローの可読性低下
+
+### 警告と推奨事項
+
+- まずは `Errors` を最小セットで導入します。
+- 既存コードが多い場合は段階的にルールを増やします。
+- `Option`、不変 `val`、式指向の記述に置き換えると改善しやすいです。
+
+## 5.5 コード複雑度チェック
+
+コードの循環複雑度（Cyclomatic Complexity）は、メソッド内の分岐数に基づいてコードの複雑さを数値化する指標です。複雑度が高いメソッドはテストが困難で、バグが混入しやすくなります。
+
+### 循環複雑度の計算ルール
+
+| ルール | 説明 |
+|--------|------|
+| 基本複雑度 | 各メソッドの初期値は 1 |
+| `if` / `else if` | 条件分岐ごとに +1 |
+| `match` / `case` | 各 case 分岐ごとに +1（`case class` / `case object` 定義は除外） |
+| `while` / `for` | ループごとに +1 |
+| `&&` / `\|\|` | 短絡評価の論理演算子ごとに +1 |
+| `try` / `catch` | 例外処理ごとに +1 |
+
+一般的な目安として、1 メソッドあたり複雑度 **10 以下** が推奨されます。
+
+### カスタム複雑度チェッカー
+
+Scala には標準的な複雑度チェックツールがないため、`scripts/complexity.sh` にカスタムスクリプトを用意しています。
+
+```bash
+# 実行（デフォルト閾値: 7）
+bash scripts/complexity.sh src
+
+# 閾値を指定して実行
+bash scripts/complexity.sh --threshold 10 src
+```
+
+実行結果の例:
+
+```
+=== Scala 循環複雑度チェック (閾値: 10) ===
+
+  OK generate                    (FizzBuzz.scala) 複雑度: 8
+  OK generateList                (FizzBuzz.scala) 複雑度: 1
+  OK create                      (Type.scala)     複雑度: 5
+
+関数数: 22, 違反: 0
+
+OK すべての関数が複雑度閾値以内です。
+```
+
+### Makefile への統合
+
+`Makefile` の `check` タスクに複雑度チェックを組み込んでいます。
+
+```makefile
+complexity:
+	bash scripts/complexity.sh --threshold 10 src
+
+check: fmt-check lint complexity test
+```
+
+`make check` を実行すると、フォーマットチェック → コンパイル → 複雑度チェック → テスト の順に品質ゲートが走ります。
+
+### 複雑度が高い場合の対処
+
+複雑度が閾値を超えた場合は、以下のリファクタリングを検討します。
+
+1. **メソッド分割**: 長い `match` 式を小さなメソッドに分解
+2. **ポリモーフィズムの活用**: 条件分岐を `sealed trait` + `case object` のパターンマッチに置き換え
+3. **高階関数の利用**: `if` / `for` をコレクション操作（`map` / `filter`）に置き換え
+4. **ガード条件の簡略化**: 複雑な条件を別メソッドとして抽出
+
+## 5.6 コンパイラオプション
+
+`apps/scala/build.sbt` では次の `scalacOptions` を設定しています。
+
+```scala
+scalacOptions ++= Seq(
+  "-deprecation",
+  "-feature",
+  "-unchecked",
+  "-Xfatal-warnings"
+)
+```
+
+- `-deprecation`: 非推奨 API 使用時に警告
+- `-feature`: 明示が必要な言語機能使用時に警告
+- `-unchecked`: 型検査が不十分な箇所を警告
+- `-Xfatal-warnings`: 警告をエラー扱いにして品質を強制
+
+## 5.7 まとめ
+
+この章では、Scala プロジェクトの品質基盤を整えました。
+
+- `sbt` で依存関係とプラグインを管理する
+- `scalafmt` でフォーマットを統一する
+- `WartRemover` で危険な記述を早期検出する
+- カスタムスクリプトでコード複雑度をチェックする
+- `scalacOptions` でコンパイル時の品質ゲートを強化する
+
+次章では、これらを `Makefile` と GitHub Actions で自動実行する方法を扱います。

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

@@ -0,0 +1,186 @@
+# 第 6 章: タスクランナーと CI/CD
+
+## 6.1 はじめに
+
+TDD を継続するには、テスト・整形・静的解析を毎回確実に実行できる仕組みが必要です。
+この章では、`Makefile`、`sbt` タスク、Nix 開発環境、GitHub Actions を使って開発タスクを自動化します。
+
+## 6.2 Nix による開発環境
+
+本プロジェクトでは Nix Flakes で開発環境を宣言的に管理しています。
+`ops/nix/environments/scala/shell.nix` に Scala 環境の定義があります。
+
+```nix
+{ packages ? import <nixpkgs> {} }:
+let
+  baseShell = import ../../shells/shell.nix { inherit packages; };
+in
+packages.mkShell {
+  inherit (baseShell) pure;
+  buildInputs = baseShell.buildInputs ++ (with packages; [
+    scala_3
+    sbt
+    metals
+    scala-cli
+  ]);
+  shellHook = ''
+    ${baseShell.shellHook}
+    echo "Scala development environment activated"
+  '';
+}
+```
+
+環境の起動:
+
+```bash
+nix develop .#scala
+```
+
+これにより、Scala 3、sbt、Metals、scala-cli が揃った環境に入れます。
+チーム全員が同じツールバージョンを使えるため、「自分のマシンでは動く」問題を防げます。
+
+## 6.3 Makefile によるタスク管理
+
+`apps/scala/Makefile` には、日常的に使うタスクが定義されています。
+
+```makefile
+.PHONY: test fmt fmt-check lint complexity check build run clean
+
+test:
+	sbt test
+
+fmt:
+	sbt scalafmt
+
+fmt-check:
+	sbt scalafmtCheck
+
+lint:
+	sbt compile
+
+complexity:
+	bash scripts/complexity.sh --threshold 10 src
+
+check: fmt-check lint complexity test
+```
+
+この構成の狙いは、`make check` 1 つで品質ゲートをまとめて実行できる点です。
+
+- `test`: 単体テスト実行
+- `fmt` / `fmt-check`: フォーマット適用と検証
+- `lint`: コンパイルによる静的チェック
+- `complexity`: コード複雑度チェック
+- `check`: CI と同等のローカル検証
+
+Nix 環境内で実行するのが前提です:
+
+```bash
+nix develop .#scala --command make check
+```
+
+## 6.4 sbt のカスタムタスク
+
+`sbt` では `build.sbt` に独自タスクを追加できます。
+たとえば、テストと整形確認をまとめたタスクは次のように定義できます。
+
+```scala
+lazy val verify = taskKey[Unit]("Run format check and tests")
+
+verify := {
+  (Compile / compile).value
+  (Test / test).value
+}
+```
+
+また、`~` prefix を使うとファイル変更を監視して自動実行できます。
+
+```bash
+nix develop .#scala --command sbt ~test
+```
+
+TDD の Red → Green を高速に回すときに有効です。
+
+## 6.5 GitHub Actions による CI/CD
+
+`.github/workflows/scala-ci.yml` では、Nix を活用して CI を実行しています。
+
+```yaml
+name: Scala CI
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - "apps/scala/**"
+      - ".github/workflows/scala-ci.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "apps/scala/**"
+
+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-scala-${{ hashFiles('flake.lock', 'ops/nix/environments/scala/shell.nix') }}
+          restore-keys: |
+            ${{ runner.os }}-nix-scala-
+
+      - name: Check formatting
+        run: nix develop .#scala --command bash -c "cd apps/scala && sbt scalafmtCheck"
+
+      - name: Compile (lint)
+        run: nix develop .#scala --command bash -c "cd apps/scala && sbt compile"
+
+      - name: Run complexity check
+        run: nix develop .#scala --command bash -c "cd apps/scala && bash scripts/complexity.sh --threshold 10 src"
+
+      - name: Run tests
+        run: nix develop .#scala --command bash -c "cd apps/scala && sbt test"
+```
+
+### Nix を CI で使う利点
+
+- **環境の再現性**: ローカルと CI で同じ Nix 環境を使うため、環境差異による失敗がない
+- **ツールバージョンの固定**: `flake.lock` でパッケージバージョンが固定される
+- **キャッシュの効率化**: `flake.lock` と `shell.nix` のハッシュでキャッシュキーを生成し、変更時のみ再構築
+- **統一的なパターン**: Clojure、.NET など他の言語と同じ CI パターンを使える
+
+## 6.6 開発ワークフロー
+
+Red-Green-Refactor を自動化で支える基本フローは次の通りです。
+
+1. 環境起動: `nix develop .#scala` で開発環境に入る
+2. Red: 失敗するテストを追加し、`make test` で失敗を確認
+3. Green: 最小実装で `make test` を通過
+4. Refactor: `make check` で整形・コンパイル・複雑度・テストを一括確認
+5. Push: GitHub Actions で Nix 環境内の同じチェックを再実行
+
+ローカルと CI で同じ Nix 環境・同じコマンドを使うことで、環境差分による失敗を防げます。
+
+## 6.7 まとめ
+
+この章では、Scala 開発の自動化基盤を整理しました。
+
+- Nix Flakes で開発環境を宣言的に管理し、再現性を確保する
+- `Makefile` で日常タスクを短いコマンドに集約する
+- `sbt` のタスクと監視実行で開発サイクルを高速化する
+- GitHub Actions で Nix 環境を使い、ローカルと同一の品質ゲートを適用する
+
+第 2 部の環境整備が完了したので、次章からはオブジェクト指向設計に進みます。