@k2works/claude-code-booster 6.2.0 → 6.3.0

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

@@ -1,191 +0,0 @@
----
-type: Article
-title: "第 4 章: バージョン管理と Conventional Commits"
-description: "ソフトウェア開発では、変更履歴を安全に管理し、チームで追跡可能にする仕組みが重要です。"
-tags: [article, getting-start-tdd, haskell]
-status: stable
-generated: { by: human:kakimomokuri, at: 2026-03-24T05:22:28Z }
----
-
-# 第 4 章: バージョン管理と Conventional Commits
-
-## 4.1 はじめに
-
-ソフトウェア開発では、変更履歴を安全に管理し、チームで追跡可能にする仕組みが重要です。
-Git による版管理とコミットメッセージ規約を整えることで、TDD の小さな変更を確実に積み上げられます。
-この章では、Haskell プロジェクトにおける Git の基本操作と Conventional Commits の実践方法を学びます。
-
-## 4.2 Git によるバージョン管理
-
-Haskell プロジェクト（`apps/haskell`）では、次の基本フローで変更を記録します。
-
-```bash
-cd apps/haskell
-git init
-git add .
-git commit -m "chore(haskell): initialize Stack project"
-```
-
-`git init` でリポジトリを初期化し、`git add` でステージング、`git commit` で履歴を確定します。
-TDD では Red → Green → Refactor の小さな単位でコミットすると、変更意図を追いやすくなります。
-
-### 基本操作のループ
-
-日常的な作業は次のコマンドの繰り返しです。
-
-```bash
-# 変更確認
-git status
-
-# 差分確認
-git diff
-
-# ステージング
-git add src/FizzBuzz.hs test/FizzBuzz/FizzBuzzSpec.hs
-
-# コミット
-git commit -m "test(fizzbuzz): 15 の倍数に対する失敗テストを追加"
-
-# 履歴確認
-git log --oneline --decorate -n 10
-```
-
-### .gitignore の設定
-
-`apps/haskell/.gitignore` には、ビルド成果物と中間ファイルを含めます。
-
-```gitignore
-.stack-work/
-dist-newstyle/
-*.cabal
-*.hi
-*.o
-*.dyn_hi
-*.dyn_o
-.hpc/
-.hsenv/
-.HTF/
-```
-
-最低限として、次の項目は必ず除外します。
-
-- `.stack-work/` -- Stack のビルド成果物とキャッシュ
-- `dist-newstyle/` -- Cabal v2 ビルドの成果物
-- `*.hi` / `*.o` -- GHC が生成するインターフェースファイルとオブジェクトファイル
-- `*.dyn_hi` / `*.dyn_o` -- 動的リンク用の中間ファイル
-
-`*.cabal` は `package.yaml` から自動生成されるため、Stack プロジェクトでは除外するのが一般的です。
-
-## 4.3 Conventional Commits
-
-Conventional Commits は、Angular Convention に由来するコミットメッセージ規約です。
-基本フォーマットは次の通りです。
-
-```text
-<type>(<scope>): <subject>
-```
-
-- `type`: 変更種別
-- `scope`: 変更対象（任意）
-- `subject`: 変更内容の要約（命令形・簡潔）
-
-### type の種類
-
-| type | 用途 |
-|------|------|
-| `feat` | 新機能の追加 |
-| `fix` | バグ修正 |
-| `docs` | ドキュメント変更 |
-| `style` | 振る舞いに影響しない整形 |
-| `refactor` | 振る舞いを変えない構造改善 |
-| `test` | テスト追加・修正 |
-| `chore` | ビルドや設定などの雑務 |
-
-### scope と subject の書き方
-
-- `scope` はモジュール単位で短く書きます（例: `haskell`, `fizzbuzz`, `ci`）。
-- `subject` は 50 文字前後を目安に、何をしたかを明確に書きます。
-- 末尾の句点は付けません。
-
-### コミットメッセージの例
-
-```text
-test(fizzbuzz): 15 の倍数に対する失敗テストを追加
-feat(fizzbuzz): generateList で 1 から n までのリストを生成
-refactor(fizzbuzz): ガード式の条件順序を整理
-docs(haskell): パッケージ管理と静的解析の章を追加
-chore(ci): Haskell CI ワークフローを追加
-```
-
-## 4.4 TDD でのコミット戦略
-
-TDD の各段階でコミットすることで、変更の意図を明確に保てます。
-
-### Red -- 失敗するテストを追加
-
-```bash
-git add test/FizzBuzz/FizzBuzzSpec.hs
-git commit -m "test(fizzbuzz): generateList の失敗テストを追加"
-```
-
-テストファイルのみをコミットし、テストが失敗することを確認した状態を記録します。
-
-### Green -- テストを通す最小実装
-
-```bash
-git add src/FizzBuzz.hs
-git commit -m "feat(fizzbuzz): generateList を実装"
-```
-
-実装ファイルのみをコミットし、全テストが通過する状態を記録します。
-
-### Refactor -- 振る舞いを変えない整理
-
-```bash
-git add src/FizzBuzz.hs test/FizzBuzz/FizzBuzzSpec.hs
-git commit -m "refactor(fizzbuzz): パターンマッチの可読性を向上"
-```
-
-テストが通り続けていることを確認した上で、コードの改善をコミットします。
-
-ポイントは、1 コミット 1 意図です。`feat` と `refactor` を同一コミットに混ぜないことで、レビューしやすくなります。
-
-## 4.5 ブランチ戦略
-
-### Git Flow の基本概念
-
-Git Flow では、主に次のブランチを使います。
-
-- `main`: リリース済みの安定コード
-- `develop`: 開発統合ブランチ
-- `feature/*`: 機能開発ブランチ
-- `release/*`: リリース準備ブランチ
-- `hotfix/*`: 緊急修正ブランチ
-
-学習用プロジェクトでは、まず `main` と `feature/*` の運用から始めると実践しやすいです。
-
-### feature ブランチの作成と運用
-
-```bash
-git switch main
-git pull origin main
-git switch -c feature/haskell-chapter-04
-```
-
-運用ポイントは次の通りです。
-
-- 1 ブランチ 1 テーマに絞ります。
-- Red / Green / Refactor の区切りで小さくコミットします。
-- 完了後に Pull Request を作成し、レビュー後に `main` へマージします。
-
-## 4.6 まとめ
-
-この章では、Haskell の TDD 開発を支える版管理の基礎を整理しました。
-
-- Git の基本操作で変更履歴を安全に管理する
-- `.gitignore` で `.stack-work/` や `*.hi` などの不要ファイルを除外する
-- Conventional Commits で履歴を読みやすくする
-- TDD の Red → Green → Refactor の各段階でコミットする
-- `feature` ブランチ運用で変更を分離する
-
-次章では、Stack と HLint を中心にパッケージ管理と静的解析を整備します。

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

@@ -1,322 +0,0 @@
----
-type: Article
-title: "第 5 章: パッケージ管理と静的解析"
-description: "Haskell 開発では、依存関係の管理とコード品質の維持を仕組み化することが重要です。"
-tags: [article, getting-start-tdd, haskell]
-status: stable
-generated: { by: human:kakimomokuri, at: 2026-03-24T05:22:28Z }
----
-
-# 第 5 章: パッケージ管理と静的解析
-
-## 5.1 はじめに
-
-Haskell 開発では、依存関係の管理とコード品質の維持を仕組み化することが重要です。
-この章では、Stack と `package.yaml` によるパッケージ管理、HLint による静的解析、GHC コンパイラオプションによる品質管理を扱います。
-
-## 5.2 Stack によるパッケージ管理
-
-### Stack の役割
-
-Stack は Haskell のビルドツール兼パッケージマネージャです。主に次の機能を提供します。
-
-- プロジェクトのビルドとテスト実行
-- 依存パッケージの解決とインストール
-- GHC コンパイラのバージョン管理
-- Stackage スナップショットによる依存関係の一貫性保証
-
-### package.yaml の構成
-
-`apps/haskell/package.yaml` では、プロジェクトの基本情報と依存関係を定義します。
-
-```yaml
-name:                fizzbuzz
-version:             0.1.0.0
-synopsis:            FizzBuzz TDD implementation in Haskell
-description:         A FizzBuzz implementation using Test-Driven Development
-license:             BSD-3-Clause
-author:              k2works
-maintainer:          k2works@example.com
-
-dependencies:
-  - base >= 4.7 && < 5
-
-ghc-options:
-  - -Wall
-  - -Wcompat
-  - -Widentities
-  - -Wincomplete-record-updates
-  - -Wincomplete-uni-patterns
-  - -Wmissing-export-lists
-  - -Wmissing-home-modules
-  - -Wpartial-fields
-  - -Wredundant-constraints
-
-library:
-  source-dirs: src
-  exposed-modules:
-    - FizzBuzz
-
-executables:
-  fizzbuzz:
-    main: Main.hs
-    source-dirs: app
-    dependencies:
-      - fizzbuzz
-
-tests:
-  fizzbuzz-test:
-    main: Spec.hs
-    source-dirs: test
-    dependencies:
-      - fizzbuzz
-      - hspec
-    build-tools:
-      - hspec-discover
-```
-
-各セクションの役割は次の通りです。
-
-| セクション | 説明 |
-|-----------|------|
-| `name` / `version` | パッケージ名とバージョン |
-| `dependencies` | 全体で共通の依存パッケージ |
-| `ghc-options` | コンパイラに渡す警告オプション |
-| `library` | ライブラリとして公開するモジュール |
-| `executables` | 実行可能ファイルの定義 |
-| `tests` | テストスイートの定義 |
-
-`package.yaml` は hpack 形式で、Stack がビルド時に自動的に `.cabal` ファイルへ変換します。そのため `.cabal` ファイルは `.gitignore` に含めています。
-
-### stack.yaml と LTS リゾルバ
-
-`apps/haskell/stack.yaml` では、使用する Stackage スナップショットを指定します。
-
-```yaml
-snapshot: lts-23.20
-
-packages:
-- .
-```
-
-- `snapshot`: Stackage LTS（Long Term Support）のバージョンを指定します。LTS は GHC バージョンと互換性のあるパッケージ群を一式まとめたものです。
-- `packages`: ビルド対象のパッケージディレクトリを指定します。
-
-LTS を固定することで、チーム全員が同じ GHC バージョンと同じパッケージバージョンを使えます。`lts-23.20` は GHC 9.8.4 に対応しています。
-
-### 依存関係の追加方法
-
-テストフレームワーク HSpec を例に、依存関係の追加手順を示します。
-
-**1. package.yaml に依存を追加**
-
-`tests` セクションの `dependencies` に `hspec` を追加します。
-
-```yaml
-tests:
-  fizzbuzz-test:
-    main: Spec.hs
-    source-dirs: test
-    dependencies:
-      - fizzbuzz
-      - hspec
-    build-tools:
-      - hspec-discover
-```
-
-`hspec-discover` は `build-tools` に指定します。これにより、テストファイルの自動検出が有効になります。
-
-**2. テストのエントリポイントを設定**
-
-`test/Spec.hs` に hspec-discover のプラグマを記述します。
-
-```haskell
-{-# OPTIONS_GHC -F -pgmF hspec-discover #-}
-```
-
-この 1 行で、`test/` 配下の `*Spec.hs` ファイルが自動的にテストスイートに組み込まれます。
-
-**3. 依存解決とビルド**
-
-```bash
-stack build --test --no-run-tests
-```
-
-Stack は `stack.yaml` で指定した LTS スナップショットから `hspec` を解決し、ダウンロードします。LTS に含まれるパッケージは `extra-deps` への追記が不要です。
-
-## 5.3 HLint による静的解析
-
-HLint は Haskell の静的解析ツールで、コードの改善提案を行います。
-
-### 基本的な使い方
-
-```bash
-hlint src/ test/ app/
-```
-
-このコマンドで `src/`、`test/`、`app/` 配下の `.hs` ファイルを解析します。
-
-### 検出される問題の例
-
-HLint は次のような改善を提案します。
-
-| カテゴリ | 元のコード | 提案 |
-|---------|-----------|------|
-| 冗長な括弧 | `(f x)` | `f x` |
-| リスト操作 | `head xs` | パターンマッチ `(x:_)` |
-| 関数合成 | `f (g x)` | `(f . g) x` |
-| eta 簡約 | `\x -> f x` | `f` |
-| 不要な `do` | `do { return x }` | `return x` |
-
-実行結果の例:
-
-```
-src/FizzBuzz.hs:8:3: Suggestion: Use otherwise
-Found:
-  generate n | True = show n
-Perhaps:
-  generate n | otherwise = show n
-
-No hints
-```
-
-`No hints` と表示されれば、HLint が検出する問題はありません。
-
-### .hlint.yaml による設定カスタマイズ
-
-`apps/haskell/.hlint.yaml` でルールのカスタマイズが可能です。
-
-```yaml
-# HLint configuration
-# https://github.com/ndmitchell/hlint
-
-- ignore: {name: "Redundant bracket"}
-- ignore: {name: "Use head", within: ["FizzBuzz.FizzBuzzSpec"]}
-```
-
-主な設定項目は次の通りです。
-
-| 設定 | 説明 |
-|------|------|
-| `ignore` | 特定のルールを無効化 |
-| `warn` | 特定のルールを警告として追加 |
-| `error` | 特定のルールをエラーとして追加 |
-| `within` | 適用範囲をモジュール単位で限定 |
-
-テストコードでは `!!` 演算子（リストのインデックスアクセス）を使うことがあるため、`Use head` ルールをテストモジュール内で無効化しています。
-
-## 5.4 コード複雑度チェック
-
-コードの循環複雑度（Cyclomatic Complexity）は、関数内の分岐数に基づいてコードの複雑さを数値化する指標です。複雑度が高い関数はテストが困難で、バグが混入しやすくなります。
-
-### 循環複雑度の計算ルール
-
-| ルール | 説明 |
-|--------|------|
-| 基本複雑度 | 各関数の初期値は 1 |
-| ガード式 `\|` | 各ガードごとに +1 |
-| `if` 式 | 条件分岐ごとに +1 |
-| `case ... of` | case 式の出現ごとに +1 |
-| パターンマッチ分岐 | コンストラクタパターンごとに +1 |
-
-一般的な目安として、1 関数あたり複雑度 **10 以下** が推奨されます。
-
-### カスタム複雑度チェッカー
-
-Haskell には標準的な複雑度チェックツールがないため、`scripts/complexity.sh` にカスタムスクリプトを用意しています。
-
-```bash
-# 実行（デフォルト閾値: 10）
-bash scripts/complexity.sh --threshold 10 src
-
-# 閾値を指定して実行
-bash scripts/complexity.sh --threshold 7 src
-```
-
-実行結果の例:
-
-```
-Checking Haskell complexity (threshold: 10)...
-
-Total functions checked: 2
-Violations: 0
-PASSED: All functions within complexity threshold
-```
-
-### 複雑度が高い場合の対処
-
-複雑度が閾値を超えた場合は、以下のリファクタリングを検討します。
-
-1. **関数分割**: 長いガード式を小さな関数に分解
-2. **パターンマッチの活用**: 条件分岐を代数的データ型のパターンマッチに置き換え
-3. **高階関数の利用**: `if` / ループ的な再帰をコレクション操作（`map` / `filter`）に置き換え
-4. **ガード条件の抽出**: 複雑な条件を `where` 節の補助関数として抽出
-
-## 5.5 GHC コンパイラオプションによる品質管理
-
-`package.yaml` の `ghc-options` セクションで、コンパイル時の警告を設定しています。
-
-```yaml
-ghc-options:
-  - -Wall
-  - -Wcompat
-  - -Widentities
-  - -Wincomplete-record-updates
-  - -Wincomplete-uni-patterns
-  - -Wmissing-export-lists
-  - -Wmissing-home-modules
-  - -Wpartial-fields
-  - -Wredundant-constraints
-```
-
-各オプションの役割は次の通りです。
-
-| オプション | 説明 |
-|-----------|------|
-| `-Wall` | 一般的な警告をすべて有効化 |
-| `-Wcompat` | 将来の GHC バージョンとの互換性警告 |
-| `-Widentities` | 不要な型変換の警告 |
-| `-Wincomplete-record-updates` | レコード更新の網羅性チェック |
-| `-Wincomplete-uni-patterns` | パターンマッチの網羅性チェック |
-| `-Wmissing-export-lists` | エクスポートリスト未指定の警告 |
-| `-Wmissing-home-modules` | モジュール依存の整合性チェック |
-| `-Wpartial-fields` | 部分的なレコードフィールドの警告 |
-| `-Wredundant-constraints` | 不要な型制約の警告 |
-
-特に `-Wall` は Haskell 開発の基本です。型シグネチャの欠落、未使用インポート、パターンマッチの非網羅性など、多くの潜在的問題を検出します。
-
-### 型シグネチャの重要性
-
-`-Wall` を有効にすると、トップレベル関数に型シグネチャがない場合に警告が出ます。
-
-```haskell
--- 型シグネチャなし（警告が出る）
-generate n
-  | n `mod` 15 == 0 = "FizzBuzz"
-  | n `mod` 3 == 0  = "Fizz"
-  | n `mod` 5 == 0  = "Buzz"
-  | otherwise        = show n
-
--- 型シグネチャあり（推奨）
-generate :: Int -> String
-generate n
-  | n `mod` 15 == 0 = "FizzBuzz"
-  | n `mod` 3 == 0  = "Fizz"
-  | n `mod` 5 == 0  = "Buzz"
-  | otherwise        = show n
-```
-
-型シグネチャを明示することで、意図しない型推論を防ぎ、コードの可読性が向上します。
-
-## 5.6 まとめ
-
-この章では、Haskell プロジェクトの品質基盤を整えました。
-
-- Stack と `package.yaml` で依存関係を宣言的に管理する
-- `stack.yaml` の LTS リゾルバでパッケージバージョンを統一する
-- HLint で Haskell 固有のイディオムに沿った改善提案を受ける
-- `.hlint.yaml` でプロジェクト固有のルールをカスタマイズする
-- カスタムスクリプトでコード複雑度をチェックする
-- GHC の `-Wall` オプションで型安全性と網羅性を強制する
-
-次章では、これらを Makefile と GitHub Actions で自動実行する方法を扱います。