ツールの入れ方・使い分け

プロジェクト依存として入れる
- コマンド: uv add --group dev <pkg>
- 目的: チーム全員・CI で同じバージョンを再現
グローバルにツールとして入れる
- コマンド: uv tool install <pkg>
- 目的: どのリポでも同じツールを手元で使う。個人環境向け
一時実行で使う（インストール不要）
- コマンド: uvx <tool> [args...]
- 目的: 試し使い、単発の実行。環境を汚さない

ヒント: 重要な品質管理ツール（ruff/mypy/pytest など）は基本「プロジェクト依存」で固定。個人用の便利ツールは uvx/uv tool を活用。

まずは開発基盤

uv add --group dev ruff pytest pytest-cov coverage[toml] mypy pre-commit pip-audit

ruff: 超高速リンター兼フォーマッター（isort 相当の import 整理も内包）。Black 互換の整形も可能
pytest/pytest-cov/coverage: シンプルで強力なテスト + カバレッジ
mypy: 段階導入しやすい静的型チェッカー（pyright は代替/併用候補）
pre-commit: Git フックでコミット前に自動整形・静的検査を実行。うっかり防止に効く
pip-audit: 依存ライブラリの既知脆弱性を検出。CI 連携が容易

pre-commit の導入:

uv run pre-commit install

例: .pre-commit-config.yaml

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.9
    hooks:
      - id: ruff
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.2
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]

pyproject.toml に開発グループを明示:

[tool.uv.dependency-groups]
dev = [
  "ruff",
  "pytest",
  "pytest-cov",
  "coverage[toml]",
  "mypy",
  "pre-commit",
  "pip-audit",
]

Lint/Format（コード品質）

ruff の使い所
- 高速で、flake8/pycodestyle/pyflakes/isort/pep8-naming 等のルールを網羅
- 既存プロジェクトはまず ruff check --fix で段階導入、整形は ruff format
- 実行: uv run ruff check . / uv run ruff format .

設定例（pyproject.toml）

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B"]
ignore = ["E501"]

[tool.ruff.format]
indent-style = "space"
quote-style = "double"

互換/代替
- black: 組織ポリシーが Black 固定なら併用可（ruff の format を無効化）
- isort: import 整理にこだわりがある場合のみ。通常は ruff に一本化で十分

型チェック（mypy / pyright）

mypy
- 長年の実績と豊富なガイド。段階的に厳格化しやすい
- 実行: uv run mypy .

設定例（pyproject.toml）

[tool.mypy]
python_version = "3.11"
ignore_missing_imports = true
warn_unused_ignores = true
warn_redundant_casts = true
strict_optional = true
disallow_untyped_defs = true

pyright
- 高速・厳密。VS Code の Pylance と同系で相性良い
- 一時実行: uvx pyright、プロジェクト導入: uv add --group dev pyright
- pyproject.toml ではなく pyrightconfig.json を使う運用が一般的

ヒント: 新規プロジェクトは mypy で開始し、VS Code では Pylance（pyright）で補完を効かせる構成が扱いやすいです。

テスト（pytest）

プラグイン
- pytest-xdist: 並列実行で高速化（-n auto）
- pytest-asyncio: 非同期テストを自然に書ける
- hypothesis: 仕様の抜け漏れを探索的に検出

実行例

uv run pytest --maxfail=1 -q --cov=. --cov-report=term-missing

設定例（pyproject.toml）

[tool.pytest.ini_options]
addopts = "-ra -q"
testpaths = ["tests"]

[tool.coverage.run]
branch = true
source = ["src"]

[tool.coverage.report]
show_missing = true
skip_covered = true

セキュリティ/メンテ

脆弱性の検査
- pip-audit: PyPI の脆弱性 DB を利用。CI で定期実行を推奨
```
uv run pip-audit
```
- 代替: safety。商用 DB/ポリシー運用の都合で選択
依存の棚卸し
- uv tree: 依存ツリーの把握、重複と競合の可視化
- uv export --format requirements.txt > requirements.txt: ピン留め一覧の生成

GitHub Actions 例（監査 + テスト）:

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv python install 3.12
      - run: uv sync --group dev
      - run: uv run pip-audit
      - run: uv run ruff check .
      - run: uv run mypy .
      - run: uv run pytest -q

uv 運用の Tips

依存の固定と同期
- uv lock → uv sync で完全同期（不要パッケージは除去）
- 開発用ツールは --group dev に集約し、CI では必要グループのみインストール
ツール実行の選択肢
- 一時実行: uvx <tool>（例: uvx ruff check ., uvx pyright）
- グローバル管理: uv tool install <tool>（例: uv tool install ruff）
ネットワーク/プロキシ・私設インデックス
- HTTP_PROXY/HTTPS_PROXY を設定
- 私設リポジトリ利用時は --index-url などのオプションや PIP_INDEX_URL の活用を検討

まとめ

品質ツールはプロジェクト依存で固定し、uv lock をコミット
日常運用は uv run で統一
重い/任意ツールはグループ化し、CI に含めない判断をする
迷ったら「ruff + pytest + mypy + pre-commit + pip-audit」から開始すれば十分