py-quality-setup

Python 品質ツールのセットアップ

Engineering Charter の基準に従って、Python 3.13 プロジェクト向けに包括的なリンティングと型チェックを設定します。

目標

1. リンティングとフォーマットに ruff を設定する
2. 厳格な型チェックに mypy を設定する
3. 追加の型解析に basedpyright を設定する
4. すべてのツールの対象を Python 3.13 以降にする
5. ツールを開発用依存関係に追加する

必須ツール

[dependency-groups] の dev に追加：「"ruff"」、「"mypy"」、「"basedpyright"」、「"pytest"」、「"pytest-cov"」

• ruff：高速なリンター兼フォーマッター（Rust ベースで、black、isort、flake8 を置き換えます）
• mypy：標準的な Python 型チェッカー
• basedpyright：追加の型解析機能を備えた Pyright の強化版フォーク

必須の設定ファイル

pyproject.toml（標準設定）

このスキルは、すべての品質ツールに適用する標準の pyproject.toml 設定を提供します。他のスキルはこの設定を参照します。

以下のセクションを含める必要があります。

[project]
requires-python = ">=3.13"

[dependency-groups]
dev = [
    "pytest>=8.0",
    "pytest-cov>=4.0",
    "ruff>=0.8.0",
    "mypy>=1.0",
    "basedpyright>=1.0",
    "pre-commit>=3.0",
    # Analysis tools (add as needed for py-* skills):
    # "radon", "vulture", "pylint", "bandit", "lizard",
    # "mutmut", "wily", "xenon", "pyupgrade", "coverage",
]

[tool.ruff]
line-length = 100  # or 140 for larger projects
target-version = "py313"
src = ["src"]  # adjust to your source directory

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors
    "W",   # pycodestyle warnings
    "F",   # pyflakes
    "I",   # isort
    "N",   # pep8-naming
    "UP",  # pyupgrade
    "B",   # flake8-bugbear
    "C4",  # flake8-comprehensions
    "SIM", # flake8-simplify
]
ignore = []

[tool.mypy]
python_version = "3.13"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_no_return = true
check_untyped_defs = true

# Add overrides for third-party packages without stubs
# [[tool.mypy.overrides]]
# module = "package_name"
# ignore_missing_imports = true

[tool.basedpyright]
pythonVersion = "3.13"
typeCheckingMode = "standard"  # or "recommended" for stricter
reportMissingTypeStubs = false
reportUnknownMemberType = false
reportUnknownArgumentType = false
reportUnknownVariableType = false

pyrightconfig.json（マルチパッケージプロジェクトでは任意）

A. マルチパッケージプロジェクトで pyrightconfig.json を使用する場合は、pyproject.toml から tool.basedpyright セクションを削除します。

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.*", "venv", ".venv"],
  "pythonVersion": "3.13",
  "typeCheckingMode": "recommended",
  "reportMissingImports": "error",
  "reportMissingTypeStubs": false,
  "reportUnknownMemberType": false,
  "reportUnknownVariableType": false,
  "reportUnknownArgumentType": false,
  "reportMissingParameterType": true,
  "reportUnusedVariable": true,
  "reportImplicitStringConcatenation": true,
  "reportUnnecessaryTypeIgnoreComment": true
}

セットアップの手順

1. 既存の設定を確認する

   • pyproject.toml を読み取ります
   • 開発用依存関係があるか確認します
   • Python のバージョン要件を確認します

2. 設定を更新または作成する

   • 開発用依存関係がない場合は追加します
   • [tool.ruff] セクションを追加または更新します
   • [tool.mypy] セクションを追加または更新します
   • [tool.basedpyright] セクションを追加または更新します
   • 必要に応じて（マルチパッケージプロジェクトの場合）pyrightconfig.json を作成します

3. 仮想環境にツールをインストールする

   # Using uv (recommended):
   uv sync                      # Creates venv and installs dev group automatically
   
   # Or manually:
   uv venv
   source .venv/bin/activate
   uv sync --group dev
   
   # Fallback if uv not available:
   # python -m venv venv
   # source venv/bin/activate
   # pip install -e ".[dev]"
   

4. インストールを確認する

   which ruff mypy basedpyright
   ruff --version
   mypy --version
   basedpyright --version
   

5. 初回チェックを実行する

   ruff check .
   mypy .
   basedpyright .
   

6. Claude Code の権限を設定する

   .claude/settings.local.json を作成し、すべての py-* スキルが権限の確認なしで実行できるようにします。ファイルがすでに存在する場合は、既存のユーザー設定を削除せずに、新しい項目を既存の allow リストに追加します。

   {
     "permissions": {
       "allow": [
         "Bash(ruff *)",
         "Bash(mypy *)",
         "Bash(basedpyright *)",
         "Bash(pytest *)",
         "Bash(vulture *)",
         "Bash(pylint *)",
         "Bash(radon *)",
         "Bash(lizard *)",
         "Bash(wily *)",
         "Bash(bandit *)",
         "Bash(mutmut *)",
         "Bash(pyupgrade *)",
         "Bash(scc *)",
         "Bash(pre-commit *)",
         "Bash(uv *)",
         "Bash(pip *)",
         "Bash(python3 *)",
         "Bash(python *)",
         "Bash(source *)",
         "Bash(which *)",
         "Bash(mkdir *)",
         "Bash(chmod *)",
         "Bash(ls *)",
         "Bash(ln *)",
         "Bash(git add *)",
         "Bash(git diff *)",
         "Bash(git status *)",
         "Bash(git log *)",
         "Bash(git ls-files *)",
         "Bash(git checkout *)",
         "Bash(git branch *)",
         "Bash(git commit *)"
       ],
       "deny": []
     }
   }
   

   マージ処理：既存ファイルを読み取り、JSON を解析し、allow リストを結合して書き戻します。必要に応じて .claude/ ディレクトリを作成します。

7. Stop フックのリンティングゲートをインストールする

   リンティングゲートのスクリプトをシンボリックリンクし、Claude Code がユーザーに応答を返す前に、変更されたファイルに対してリンティング一式（ruff、mypy、basedpyright）を実行するようにします。いずれかのリンターがエラーを報告した場合、Claude は処理を停止できず、先に修正する必要があります。

   mkdir -p ~/.claude/hooks
   ln -sf ~/.claude/skills/py-git-hooks/lint-gate.py ~/.claude/hooks/lint-gate.py
   

   ~/.claude/settings.json で Stop フックを設定します（既存のフックがある場合はマージします）。

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "python3 ~/.claude/hooks/lint-gate.py"
             }
           ]
         }
       ]
     }
   }
   

8. git フックを設定する（要求された場合）

   • リンターを実行する pre-commit フックを設定します
   • py-git-hooks スキルを参照してください

ツール固有の注意点

Ruff

• 最速の Python リンター（Rust ベース）
• black、isort、flake8、および多数のプラグインを置き換えます
• 自動修正：ruff check --fix .
• フォーマット：ruff format .

Mypy

• 標準的な Python 型チェッカー
• 厳格モードでは、ほとんどの型エラーを検出できます
• # type: ignore[error-code] は必要最小限に使用します
• スタブがないパッケージにはオーバーライドを追加します

Basedpyright

• より多くの機能を備えた Pyright のフォーク
• mypy が見逃す一部のエラーを検出します
• Pyright よりも柔軟に設定できます
• mypy と併用できます

よくある調整

モノレポ／マルチパッケージ：

• extraPaths を指定した pyrightconfig.json を使用します
• mypy で namespace_packages = true を設定します

レガシーコードベース：

• mypy の厳格さを抑えて（strict = false）開始します
• 厳格なチェックを段階的に有効にします
• モジュールごとに mypy のオーバーライドを使用します

スタブがないサードパーティパッケージ：

[[tool.mypy.overrides]]
module = "package_name"
ignore_missing_imports = true

検証チェックリスト

• pyproject.toml の requires-python が ">=3.13" に設定されている
• 開発用依存関係に ruff、mypy、basedpyright が含まれている
• [tool.ruff] の target-version が "py313" に設定されている
• [tool.mypy] の python_version が "3.13" に設定されている
• [tool.basedpyright] の pythonVersion が "3.13" に設定されている
• すべてのツールが venv にインストールされている
• ruff check が成功する（または想定されるエラーのみ）
• mypy . が成功する（または想定されるエラーのみ）
• basedpyright . が成功する（または想定されるエラーのみ）
• .claude/settings.local.json が存在し、すべての品質管理ツールに対する権限が設定されている
• ~/.claude/hooks/lint-gate.py がシンボリックリンクされ、Stop フックが ~/.claude/settings.json で設定されている

例

例：新しいプロジェクトのセットアップ

1. Create venv: uv venv && source .venv/bin/activate
2. Create pyproject.toml with [project], [tool.ruff], [tool.mypy], [tool.basedpyright]
3. Install: uv pip install -e ".[dev]"
4. Verify: ruff --version && mypy --version && basedpyright --version
5. Run initial checks: ruff check . && mypy . && basedpyright .
6. Fix issues or add ignores for false positives

例：既存のプロジェクトに品質管理ツールを追加

1. Activate venv: source .venv/bin/activate
2. Update pyproject.toml:
   - Add ruff, mypy, basedpyright to [project.optional-dependencies] dev
   - Add [tool.ruff], [tool.mypy], [tool.basedpyright] sections
3. Install: uv pip install -e ".[dev]"
4. Run checks: ruff check . (expect many errors initially)
5. Auto-fix: ruff check --fix . && ruff format .
6. Run type checkers: mypy . && basedpyright .
7. Add [[tool.mypy.overrides]] for third-party packages without stubs
8. Iterate until all checks pass

例：レガシーなコードベースへの段階的な導入

1. Start with minimal ruff rules: select = ["E", "F"]
2. Start mypy non-strict: strict = false
3. Fix errors incrementally, expand rules over time
4. Add per-module mypy overrides for problematic modules
5. Eventually enable strict mode project-wide

関連スキル

• 基盤：このスキルは、ほかのすべてのスキルの基盤です
• 次のステップ：py-git-hooks（設定したツールの適用を自動化）
• こちらも参照：py-modernize（uv への移行と構文のアップグレード）