npm - @k2works/claude-code-booster - Versions diffs - 2.7.1 → 3.1.0 - Mend

@k2works/claude-code-booster 2.7.1 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (527) hide show

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

@@ -0,0 +1,87 @@
+# 第 4 章: バージョン管理と Conventional Commits
+## 4.1 はじめに
+第 1 部では、TDD の基本サイクルで FizzBuzz プログラムを完成させました。第 2 部では、ソフトウェア開発の **三種の神器** を整備し、開発環境を強化していきます。
+> ソフトウェア開発の三種の神器
+>
+> - バージョン管理
+> - テスティング
+> - 自動化
+>
+> — 和田卓人
+## 4.2 コミットメッセージの重要性
+チーム開発において、コミットメッセージの書き方がバラバラだと、変更履歴から「何が変わったか」を追跡するのが困難になります。一貫性のあるルールを設けることで、変更の意図が明確になり、レビューやデバッグが効率化されます。
+## 4.3 Conventional Commits
+[Conventional Commits](https://www.conventionalcommits.org/) は、コミットメッセージに統一的なフォーマットを与える規約です。
+### フォーマット
+```
+<type>(<scope>): <subject>
+<body>
+<footer>
+```
+- **Header**（必須）: `<type>(<scope>): <subject>`（50 文字以内）
+- **Body**（任意）: 変更の詳細
+- **Footer**（任意）: Breaking Changes、Issue への参照
+### コミットタイプ
+| タイプ | 説明 | 例 |
+|--------|------|-----|
+| feat | 新機能の追加 | `feat(fizzbuzz): リスト生成機能を追加` |
+| fix | バグ修正 | `fix(fizzbuzz): 15 の判定順序を修正` |
+| docs | ドキュメントのみの変更 | `docs: README にセットアップ手順を追加` |
+| style | コードの意味に影響しない変更 | `style: フォーマットを適用` |
+| refactor | バグ修正でも機能追加でもないコード変更 | `refactor: マジックナンバーを定数化` |
+| test | テストの追加・修正 | `test: FizzBuzz の境界値テストを追加` |
+| chore | ビルドやツールの変更 | `chore: Ruff の設定を追加` |
+### 実践例
+第 1 部で作成したコードに適用すると、以下のようなコミット履歴になります。
+```bash
+# 章 1: 仮実装
+$ git commit -m "test(fizzbuzz): 1 を渡したら文字列 1 を返す"
+# 章 2: 三角測量
+$ git commit -m "test(fizzbuzz): 三角測量で数を文字列に変換する処理を一般化"
+# 章 2: 明白な実装
+$ git commit -m "feat(fizzbuzz): Fizz/Buzz/FizzBuzz の判定ロジックを実装"
+# 章 3: リスト生成とプリント
+$ git commit -m "feat(fizzbuzz): 1 から 100 までのリスト生成とプリント機能を追加"
+```
+## 4.4 TDD とコミットのタイミング
+TDD サイクルにおけるコミットの推奨タイミングは以下の通りです。
+```
+Red（テスト失敗）→ Green（テスト成功）→ コミット → Refactor → コミット
+```
+- **Green 後**: テストが通った時点でコミットし、動作する状態を記録する
+- **Refactor 後**: リファクタリングが完了した時点でコミットし、設計改善を記録する
+## 4.5 まとめ
+| 項目 | 内容 |
+|------|------|
+| フォーマット | `<type>(<scope>): <subject>` |
+| タイプ | feat, fix, docs, style, refactor, test, chore |
+| コミット単位 | 1 コミット = 1 論理的変更 |
+| タイミング | Green 後、Refactor 後 |
+次の章では、パッケージ管理と静的解析ツール（Ruff、mypy、pytest-cov）を導入します。

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

@@ -0,0 +1,274 @@
+# 第 5 章: パッケージ管理と静的解析
+## 5.1 はじめに
+この章では、Python プロジェクトにパッケージ管理ツールと静的解析ツールを導入し、コードの品質を自動的にチェックする仕組みを整えます。
+## 5.2 uv によるパッケージ管理
+[uv](https://docs.astral.sh/uv/) は、高速な Python パッケージマネージャです。pip や poetry を置き換え、依存関係の管理と仮想環境の操作を統合的に行えます。
+### pyproject.toml の設定
+開発に必要なツールを追加します。
+```toml
+# pyproject.toml
+[project]
+name = "fizzbuzz"
+version = "0.1.0"
+description = "FizzBuzz TDD project for Python"
+requires-python = ">=3.11"
+[tool.pytest.ini_options]
+testpaths = ["test"]
+pythonpath = ["."]
+addopts = "--cov=lib --cov-report=term-missing"
+[tool.coverage.run]
+source = ["lib"]
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.",
+]
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "ruff>=0.8",
+    "mypy>=1.13",
+]
+```
+```bash
+$ uv sync
+```
+## 5.3 静的コード解析 — Ruff
+[Ruff](https://docs.astral.sh/ruff/) は、Python 用の高速なリンター兼フォーマッターです。flake8、pylint、black を 1 つのツールに統合しています。
+### Ruff の設定
+```toml
+# .ruff.toml
+line-length = 88
+target-version = "py311"
+[lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = []
+[format]
+quote-style = "double"
+indent-style = "space"
+[lint.per-file-ignores]
+"test/**/*.py" = ["E501"]
+[lint.mccabe]
+max-complexity = 7
+```
+### リンターの実行
+```bash
+# コードチェック
+$ uv run ruff check .
+# 自動修正
+$ uv run ruff check . --fix
+```
+### フォーマッターの実行
+```bash
+# フォーマットチェック
+$ uv run ruff format --check .
+# 自動フォーマット
+$ uv run ruff format .
+```
+## 5.4 コード複雑度のチェック
+静的コード解析では、コーディング規約やバグパターンだけでなく、**コードの複雑度** もチェックできます。Ruff には McCabe 複雑度チェッカーが組み込まれており、メソッドの複雑度を制限できます。
+### 循環的複雑度（Cyclomatic Complexity）
+> 循環的複雑度（サイクロマティック複雑度）とは、ソフトウェア測定法の一つであり、コードがどれぐらい複雑であるかをメソッド単位で数値にして表す指標。
+本プロジェクトでは、循環的複雑度を **7 以下** に制限しています。
+| 複雑度の範囲 | 意味 |
+|-------------|------|
+| 1〜10 | 低複雑度：管理しやすく、問題なし |
+| 11〜20 | 中程度の複雑度：リファクタリングを検討 |
+| 21〜50 | 高複雑度：リファクタリングが強く推奨される |
+| 51 以上 | 非常に高い複雑度：コードを分割する必要がある |
+### 認知的複雑度（Cognitive Complexity）
+> 認知的複雑度（Cognitive Complexity）は、プログラムを読む人の認知負荷を測るための指標。コードの構造が「どれだけ頭を使う必要があるか」を定量的に評価する。循環的複雑度とは異なり、制御構造のネストやコードの流れの読みやすさに重点を置いている。
+| 複雑度の範囲 | 意味 |
+|-------------|------|
+| 0〜4 | 理解が非常に容易：リファクタリング不要 |
+| 5〜14 | 中程度の難易度：改善が必要な場合もある |
+| 15 以上 | 理解が困難：コードの簡素化を検討するべき |
+### Ruff の McCabe 設定
+`.ruff.toml` の `[lint.mccabe]` セクションで循環的複雑度の上限を設定します。
+```toml
+# .ruff.toml（抜粋）
+[lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "C90", # mccabe（循環的複雑度）
+]
+[lint.mccabe]
+max-complexity = 7
+```
+`select` に `"C90"` を追加すると、McCabe 複雑度チェックが有効になります。`max-complexity = 7` で、循環的複雑度が 7 を超える関数に対して警告が出ます。
+### 複雑度チェックの実行
+```bash
+$ uv run ruff check .
+```
+### 複雑度チェックの効果
+コード複雑度の制限により、以下の効果が得られます。
+- **可読性向上** — 小さな関数は理解しやすい
+- **保守性向上** — 変更の影響範囲が限定される
+- **テスト容易性** — 個別機能のテストが簡単
+- **自動品質管理** — 複雑なコードの混入を自動防止
+現在の FizzBuzz の `generate` メソッドは循環的複雑度が 4 で、制限値 7 以内に収まっています。第 3 部でオブジェクト指向設計を進める際も、この制限を意識してコードを書いていきます。
+## 5.5 マジックナンバーのリファクタリング
+第 1 部で作成した FizzBuzz のコードには、`3`、`5`、`15` というマジックナンバーが含まれています。定数として抽出しましょう。
+### リファクタリング前
+```python
+class FizzBuzz:
+    def generate(self, number: int) -> str:
+        if number % 15 == 0:
+            return "FizzBuzz"
+        if number % 3 == 0:
+            return "Fizz"
+        if number % 5 == 0:
+            return "Buzz"
+        return str(number)
+```
+### リファクタリング後
+```python
+class FizzBuzz:
+    MAX_NUMBER: int = 100
+    _FIZZ_NUMBER: int = 3
+    _BUZZ_NUMBER: int = 5
+    _FIZZ_BUZZ_NUMBER: int = 15
+    def generate(self, number: int) -> str:
+        """数を FizzBuzz ルールに従って文字列に変換する。"""
+        if number % self._FIZZ_BUZZ_NUMBER == 0:
+            return "FizzBuzz"
+        if number % self._FIZZ_NUMBER == 0:
+            return "Fizz"
+        if number % self._BUZZ_NUMBER == 0:
+            return "Buzz"
+        return str(number)
+    def generate_list(self, count: int) -> list[str]:
+        """1 から count までの FizzBuzz リストを生成する。"""
+        return [self.generate(i) for i in range(1, count + 1)]
+    def print_fizzbuzz(self, count: int) -> None:
+        """FizzBuzz の結果をプリントする。"""
+        result = self.generate_list(count)
+        for item in result:
+            print(item)
+```
+リファクタリング後もテストがすべて通ることを確認します。
+```bash
+$ uv run pytest -v
+```
+## 5.6 コードカバレッジ — pytest-cov
+[pytest-cov](https://pytest-cov.readthedocs.io/) は、pytest と連携してコードカバレッジを計測するプラグインです。
+```bash
+$ uv run pytest --cov=lib --cov-report=term-missing
+```
+```
+Name                  Stmts   Miss  Cover   Missing
+-----------------------------------------------------
+lib/__init__.py           0      0   100%
+lib/fizzbuzz.py          14      0   100%
+-----------------------------------------------------
+TOTAL                    14      0   100%
+```
+## 5.7 型チェック — mypy
+[mypy](https://mypy-lang.org/) は、Python の型ヒントに基づいて静的型チェックを行うツールです。
+```bash
+$ uv run mypy lib test
+```
+```
+Success: no issues found
+```
+Python は動的型付け言語ですが、型ヒントと mypy を組み合わせることで、コンパイル言語に近い型安全性を実現できます。
+## 5.8 まとめ
+| ツール | 用途 | コマンド |
+|--------|------|---------|
+| uv | パッケージ管理 | `uv sync` |
+| Ruff | リンター + フォーマッター | `uv run ruff check .` / `uv run ruff format .` |
+| pytest-cov | コードカバレッジ | `uv run pytest --cov=lib` |
+| mypy | 静的型チェック | `uv run mypy lib test` |
+次の章では、タスクランナー（tox）と CI/CD パイプラインを構築します。

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

@@ -0,0 +1,190 @@
+# 第 6 章: タスクランナーと CI/CD
+## 6.1 はじめに
+前章までに、Ruff（リンター + フォーマッター）、mypy（型チェック）、pytest-cov（カバレッジ）を個別に導入しました。しかし、これらを毎回手動で実行するのは手間がかかります。この章では **タスクランナー** を導入して品質チェックを自動化し、さらに CI/CD パイプラインを構築します。
+## 6.2 タスクランナー — tox
+[tox](https://tox.wiki/) は、Python プロジェクト向けのタスクランナーです。複数の環境でテストを実行したり、品質チェックを束ねて一括実行したりできます。
+### tox.ini の設定
+```ini
+# tox.ini
+[tox]
+envlist = test,lint,type
+skipsdist = true
+[testenv:test]
+deps =
+    pytest
+    pytest-cov
+commands =
+    pytest --cov=lib --cov-report=term-missing --verbose
+[testenv:lint]
+deps = ruff
+commands =
+    ruff check .
+    ruff format --check .
+[testenv:format]
+deps = ruff
+commands =
+    ruff format .
+[testenv:type]
+deps =
+    mypy
+    pytest
+commands =
+    mypy lib test
+```
+### タスクの実行
+```bash
+# 全タスクを一括実行
+$ uv run tox
+# 個別タスクの実行
+$ uv run tox -e test      # テストのみ
+$ uv run tox -e lint      # リンティングのみ
+$ uv run tox -e type      # 型チェックのみ
+$ uv run tox -e format    # フォーマット適用
+```
+### 全品質チェックの実行例
+```bash
+$ uv run tox
+```
+```
+test: commands succeeded
+lint: commands succeeded
+type: commands succeeded
+congratulations :)
+```
+すべてのチェックが成功すれば、コードの品質が保証された状態です。
+## 6.3 タスクの自動化
+### ファイル監視による自動テスト
+pytest には `--watch` オプションはありませんが、`pytest-watch` パッケージを使うか、IDE のファイル保存時自動テスト機能を利用できます。
+```bash
+# pytest-watch を使う場合
+$ uv add --dev pytest-watch
+$ uv run ptw
+```
+ファイルを変更するたびにテストが自動実行され、TDD サイクルが加速します。
+## 6.4 GitHub Actions による CI/CD
+プッシュやプルリクエスト時に自動で品質チェックを実行する CI/CD パイプラインを構築します。
+### ワークフロー設定
+```yaml
+# .github/workflows/python-ci.yml
+name: Python CI
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - "apps/python/**"
+      - ".github/workflows/python-ci.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "apps/python/**"
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/python
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Nix
+        uses: cachix/install-nix-action@v30
+      - name: Cache Nix store
+        uses: actions/cache@v4
+        with:
+          path: /nix/store
+          key: nix-${{ runner.os }}-${{ hashFiles('flake.lock') }}
+      - name: Run tests
+        run: nix develop .#python --command bash -c "cd apps/python && uv sync && uv run tox -e test"
+        working-directory: .
+      - name: Run lint
+        run: nix develop .#python --command bash -c "cd apps/python && uv run tox -e lint"
+        working-directory: .
+      - name: Run type check
+        run: nix develop .#python --command bash -c "cd apps/python && uv run tox -e type"
+        working-directory: .
+```
+### CI パイプラインの流れ
+```
+git push → GitHub Actions → Nix 環境構築 → テスト → リンティング → 型チェック
+```
+## 6.5 三種の神器と CI/CD
+第 2 部で整備した開発環境の全体像です。
+| 神器 | ツール | 目的 |
+|------|--------|------|
+| バージョン管理 | Git + Conventional Commits | 変更履歴の追跡 |
+| テスティング | pytest + pytest-cov | 品質の保証 |
+| 自動化 | tox + GitHub Actions | 反復作業の自動化 |
+### 利用可能なコマンド一覧
+| コマンド | 説明 |
+|---------|------|
+| `uv run pytest -v` | テスト実行 |
+| `uv run ruff check .` | リンティング |
+| `uv run ruff format .` | フォーマット適用 |
+| `uv run mypy lib test` | 型チェック |
+| `uv run pytest --cov=lib` | カバレッジ計測 |
+| `uv run tox` | 全品質チェック一括実行 |
+| `uv run tox -e test` | テストのみ |
+| `uv run tox -e lint` | リンティングのみ |
+| `uv run tox -e type` | 型チェックのみ |
+## 6.6 まとめ
+| 章 | テーマ | 導入したツール |
+|----|--------|--------------|
+| 4 | バージョン管理 | Conventional Commits |
+| 5 | パッケージ管理と静的解析 | uv、Ruff、mypy、pytest-cov |
+| 6 | タスクランナーと CI/CD | tox、GitHub Actions |
+### TDD 開発ワークフロー
+1. テストを書く（Red）
+2. 最小限のコードを実装（Green）
+3. `uv run pytest -v` でテストを確認
+4. リファクタリング
+5. `uv run tox` で全品質チェック
+6. `git commit` で変更を記録
+次の第 3 部では、オブジェクト指向設計（カプセル化、ポリモーフィズム、デザインパターン）を FizzBuzz に適用していきます。