code-quality

コード品質スキル

有効にするタイミング

次の場合にこのスキルを有効にしてください：

• Python コードをフォーマットするとき
• リンターを実行するとき
• 型注釈を追加するとき
• コードスタイルの問題を修正するとき
• 品質ツールをセットアップするとき

クイックコマンド

# Format with Black
uv run black .
uv run black --check .  # Dry run

# Lint with Ruff
uv run ruff check .
uv run ruff check --fix .  # Auto-fix

# Type check with mypy
uv run mypy .

# All checks
uv run black . && uv run ruff check . && uv run mypy .

ツールの概要

ツール	目的	速度	自動修正
Black	コードフォーマット	高速	はい
Ruff	リンティングとインポート	非常に高速	ほとんどのルール
mypy	型チェック	中程度	いいえ

インストール

uv add --dev black ruff mypy

Black - コードフォーマット

一貫したスタイルで、設定不要のフォーマットを実現します。

uv run black .                # Format all
uv run black --check .        # Dry run
uv run black --diff .         # Show changes

設定

[tool.black]
line-length = 88
target-version = ['py311']

Ruff - 高速リンティング

Rust ベースのリンターで、flake8、isort、pylint、その他 50 以上のツールを置き換えます。

uv run ruff check .               # Check
uv run ruff check --fix .         # Auto-fix
uv run ruff check --show-source . # Show context

設定

[tool.ruff]
line-length = 88
target-version = "py311"
select = ["E", "W", "F", "I", "B", "SIM"]
ignore = ["E501"]  # Black handles line length

[tool.ruff.per-file-ignores]
"__init__.py" = ["F401"]
"tests/*" = ["S101"]

よくある問題

• F401：未使用のインポート（自動修正可能）
• F841：未使用の変数
• I001：インポートの並べ替え（自動修正可能）
• B008：ミュータブルなデフォルト引数

mypy - 型チェック

Python 用の静的型チェッカーです。

def greet(name: str) -> str:
    return f"Hello, {name}"

greet(123)  # mypy error: incompatible type "int"

設定

[tool.mypy]
python_version = "3.11"
warn_return_any = true
disallow_untyped_defs = false  # Enable gradually
check_untyped_defs = true

よく使う型ヒント

from typing import Optional, List, Dict

def find_user(user_id: int) -> Optional[Dict[str, str]]:
    return database.get(user_id)

def process_items(items: List[str]) -> int:
    return len(items)

統一設定

# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py311']

[tool.ruff]
line-length = 88
target-version = "py311"
select = ["E", "W", "F", "I", "B", "SIM"]

[tool.mypy]
python_version = "3.11"
warn_return_any = true

ルールのスキップ

import os  # noqa: F401       # Ignore Ruff rule

# fmt: off                     # Disable Black
matrix = [[1, 2, 3], [4, 5, 6]]
# fmt: on

ワークフローのベストプラクティス

開発（コミット前）

uv run black . && uv run ruff check --fix . && uv run mypy .

CI/CD（厳格、自動修正なし）

uv run black --check . && uv run ruff check . && uv run mypy --strict .

段階的な導入

1. Black から始める - 設定不要で、すぐにメリットが得られます
2. Ruff を追加する - まず基本ルールから始め、徐々に拡張します
3. mypy を導入する - 最初は寛容な設定にし、厳格さを高めていきます

コードスタイルの原則

独創性より明瞭さ

# ❌ Clever but unclear
result = [x for x in range(10) if x % 2 == 0 if x > 5]

# ✅ Clear and readable
even_numbers = [x for x in range(10) if x % 2 == 0]
result = [x for x in even_numbers if x > 5]

意味のある名前

# ❌ Unclear
def proc(d, x):
    return d[x] if x in d else None

# ✅ Clear
def get_user_by_id(users_dict, user_id):
    return users_dict.get(user_id)

早期リターン

# ❌ Nested
def process(amount, user):
    if amount > 0:
        if user.has_payment():
            return charge(user, amount)

# ✅ Early returns
def process(amount, user):
    if amount <= 0:
        return "Invalid amount"
    if not user.has_payment():
        return "No payment method"
    return charge(user, amount)

関連リソース

AgentUsage/code_quality.md と AgentUsage/code_style_guide.md を参照してください：

• IDE との連携
• Pre-commit フックのセットアップ
• 包括的なスタイルガイドライン
• エラー処理のパターン