コンテンツにスキップ

はじめに

pyfltrを設定して実行するまでの導入手順。 インストール・設定・実行・コーディングエージェント連携・次のステップの順に並ぶ。 既にpyfltrを使っている場合はCLIコマンドや設定項目を参照。

インストール

uvx pyfltrで実行する。事前インストールやdev依存への追加なしで最新版を取得して実行する。

uvx pyfltr --help

uvでバージョン管理する場合はuv add --dev pyfltrまたはuv add --dev "pyfltr[python]"で追加し、 uv run pyfltr ...で呼び出す。 pip環境ではpip install pyfltrを使う。

呼び出し方の使い分けは呼び出し方の使い分けを参照。

設定

pyfltrの実行内容はpyproject.tomlの[tool.pyfltr]セクションで指定する。 プリセットと言語カテゴリゲートの2行で設定が完結する。

[tool.pyfltr]
preset = "latest"
python = true

各設定の役割。

  • preset = "latest": 各時点での推奨ツール構成のスナップショット。 Python系一式（ruff-format / ruff-check / mypy / pylint / pyright / pytest / uv-sortなど）を取り込む
  • python = true: Python系ツールの言語カテゴリゲートを開ける。 プリセットでtrueになっているツールはこのゲートを通過した分だけ実際に有効化される

JS/TS・Rust・.NETを併用する場合は対応する言語カテゴリキー（javascript / rust / dotnet）を追加する。

[tool.pyfltr]
preset = "latest"
python = true
javascript = true

ドキュメント系（textlint / markdownlint / actionlint / typos / pre-commit）は言語カテゴリゲートに属さず、 プリセットでtrueになっているものがそのまま有効化される。

プリセット・言語カテゴリゲートの詳細は設定項目を参照。

実行

カレントディレクトリ配下のファイルを対象にチェックを実行する。

# ローカル開発用：自動修正あり、formatter差分は成功扱い
uvx pyfltr run

# CI・コミット前用：自動修正なし、formatter差分も失敗扱い
uvx pyfltr ci

# pre-commitフック向け軽量チェック：重いツール（mypy / pylint / pytest等）を除外
uvx pyfltr fast

特定ツールだけ実行したい場合は--commandsで限定する。

uvx pyfltr run --commands=ruff-check src/
uvx pyfltr run --commands=mypy,pyright path/to/file.py

サブコマンドの違いと全オプションはCLIコマンドを参照。

コーディングエージェントから使う

JSON Lines出力（--output-format=jsonl）とMCPサーバー（pyfltr mcp）でコーディングエージェント運用に対応する。

直接呼び出し（推奨）

エージェントがシェルコマンドを実行できる環境ではpyfltr run-for-agentを直接呼ぶ。 JSONL出力をそのまま読み込める。

uvx pyfltr run-for-agent

MCP経由

pyfltr mcpでMCPサーバーを起動すると、エージェントがrun_for_agent等のMCPツールとして呼び出せる。

# Claude Codeへの登録例
claude mcp add pyfltr -- uvx pyfltr mcp

提供するMCPツールやJSONL出力の解釈方法はCLIコマンドの「コーディングエージェント連携」を参照。

次のステップ

利用シナリオに応じて次のページを参照。