pyfltr-usage

name	pyfltr-usage
description	pyfltrの使い方・JSONL出力解釈・特定ツール実行・トラブルシューティングのリファレンス。 コードベース横断の正規表現置換（キーワード書き換え・参照除去など）でgrep/replaceサブコマンドを使う場合も参照する。

pyfltrの使い方

pyfltrは各種コード品質ツール（formatter/linter/tester）を統合的に並列実行するツール。 Python・Rust・.NET・TypeScript/JSなどに対応する。

呼び出し方の基本

既存プロジェクトでの通常運用

• 通常運用はuvx pyfltr ...を使う。 v3.8以降、Python系ツール一式（ruff / mypy / pylint / pyright / ty / pytest / uv-sort等）が 本体依存に統合されたため、uvx pyfltr単発で揃う。 cwdにuv.lockがあれば{command}-runner = "uv"既定でプロジェクトvenvのツール版が優先される。
• pre-commit hookのentry:もuvx pyfltr fastに揃える。 uv run系を使う場合は--frozen必須（pre-commitは親環境のUV_FROZENを引き継がないため）。
• pyfltr公式Dockerイメージ（ghcr.io/ak110/pyfltr:latest）配下のCIジョブでは、 uvx pyfltr ciではなくイメージ同梱のpyfltr ciを直接呼び出すことを推奨する。
• pyfltr自身を開発・検証するときに限り、uv run --with-editable=. pyfltr ...を使う。

新規プロジェクトへの導入

pyfltr関連設定は、原則として下記の公式推奨例をそのまま採用する。 独自の順序やオプション構成は避け、推奨例との差分は必要最小限にとどめる。 推奨例はpyproject.toml・pre-commitフック・タスクランナー・GitHub Actionsを一貫した構成で揃える。 複数プロジェクト間の差分を抑えて保守コストを下げる目的がある。 既存プロジェクトで推奨例と乖離した設定を見つけた場合も、揃える方向の提案を優先する。

• Pythonプロジェクト: https://ak110.github.io/pyfltr/guide/recommended/index.md
• 非Pythonプロジェクト（TypeScript／JS・Rust・.NET）: https://ak110.github.io/pyfltr/guide/recommended-nonpython/index.md

サブコマンドの使い分け

用途に応じて以下のフローで選択する。

• LLMエージェントが呼び出す → run-for-agent
• CI環境で実行する → ci
• pre-commitフックで実行する → fast
• ローカル開発で手動実行する → run

サブコマンド	用途	fixステージ	formatter変更で失敗するか
ci	全チェック実行	なし	する（exit 1）
run	全チェック実行	あり	しない（exit 0）
fast	軽量チェック（mypy/pylint/pytestなど重いツールを除外）	あり	しない（exit 0）
run-for-agent	run --output-format=jsonlのエイリアス	あり	しない（exit 0）

run／fast／run-for-agentは前段で自動fixステージを実行する。 fixステージはruff check --fix（fix段）→ ruff format（formatter段）→ ruff check（linter段） の3段構成を一般化した仕組みである。 抑止したい場合は--no-fixを付ける。ciはfixステージを含まないため、修正済みを前提とした検証に使う。

grep&replace

pyfltr grepとpyfltr replaceは、コードベース横断のキーワード書き換え・参照除去のように 複数ファイルに跨る正規表現置換を扱うサブコマンド。 pyfltr grepでマッチを確認し、必要に応じてファイル単位の除外を加えてからpyfltr replaceで実行する。 JSONL出力でコンテキスト効率に優れる。 エージェント環境ではAI_AGENT常時設定によりgrep／replaceもJSONL出力が既定値となる。

代表的なワークフロー:

1. pyfltr grep PATTERN [paths...]でマッチを確認する。 --output-file=matches.jsonlを付けると後続のreplaceへ渡せる
2. 誤爆や除外対象が混在する場合は次のいずれかで対象を限定する
   • pyfltr replace PATTERN REPLACEMENT --exclude-file=path/to/skip.py [paths...]でファイル単位除外
   • matches.jsonlから残したいファイル集合のみに編集した上で pyfltr replace PATTERN REPLACEMENT --from-grep=matches.jsonlに渡す。 --from-grepはマッチを含むファイル集合への限定のため、 同一ファイル内の一部マッチだけを除外したい場合は適用しない。 その場合は検索パターン側を限定するか手動編集で対処する
3. 適用前に--dry-runまたは--show-changesで差分を確認する
4. 結果に問題があればpyfltr replace --list-history／--undo IDで取り消す

オプションの全容はpyfltr grep --help／pyfltr replace --helpで確認する。

JSONL出力

--output-format=jsonlを付けるとLLM向けの構造化出力が得られる。 stdoutにJSONLのみを書き、テキストログは抑止される。 エージェント環境ではAI_AGENTが常時設定されるため、--output-format未指定でも全サブコマンドが既定でjsonl出力になる。 text出力が必要な場合のみ--output-format=textを明示する（環境変数PYFLTR_OUTPUT_FORMAT=textでも同等）。 エージェントからの呼び出しは可読性のためrun-for-agentを推奨する。

注記: mypy / pyright / pylint / ty を併用していると、同じ型エラーが複数のdiagnostic行に 別ツール名で重複出力されることがある。 1件の問題に対する複数ツールの報告として扱い、修正計画を重複させない。 単一ツールに限定して実行したい場合は--commands=mypy等で指定する。

messageの切り詰め仕様

failedかつdiagnostics=0のとき、command.messageに生出力の抜粋が入る。 切り詰めは「先頭ブロック + ... (truncated) + 末尾ブロック」のハイブリッド方式で、 jsonl-message-max-chars（既定2000文字）をhead : tail = 1 : 4で配分する。 冒頭にエラー要約を表示するツール（editorconfig-checker等）と 末尾にスタックトレースを表示するツール（pytest／mypy等）の双方を取りこぼさない。

切り詰めが起きるとcommand.truncatedに{lines, chars, head_chars, tail_chars, archive}が入る。 archiveにはアーカイブ内の相対パスが入る。 具体的にはtools/<command>/output.logまたはtools/<command>/diagnostics.jsonlの形式で、 run_id配下のアーカイブディレクトリと組み合わせれば直接参照できる。 show-runサブコマンドを介した取得手順は次節「再実行・調査の手段」を参照。

messages[].fixフィールドの値

failedのmessages[]には各違反ごとにfixフィールドが付くことがある。値の意味は以下の通り。

値	意味
safe	自動fixが安全（副作用が予測可能）
unsafe	自動fixが可能だが意図と異なる修正になる可能性がある
suggested	自動fixの候補があるが適用は手動判断
none	ツールが自動fixを提供しない（手動修正が必要）
省略	ツールがfix情報を提供していない（手動修正が必要）

safe／unsafe／suggestedが並ぶ違反はrun-for-agentの自動fixステージで解消される場合が多い。 noneまたは省略の違反は内容に応じて手動修正する。

再実行・調査の手段

失敗ツールの再実行や全文ログの取得には以下の3手段がある。状況に応じて使い分ける。

command.retry_command で失敗ファイルだけ再実行

run-for-agentのJSONL出力では、失敗したcommandレコードにretry_commandフィールドが入る。 失敗ファイルだけに限定した再実行コマンドが文字列として格納されているため、そのままシェルで実行できる。 特定の失敗ツール1件のみを素早く再現したい場合に最も軽量。

--only-failed で失敗ツール全体を再実行

uvx pyfltr run-for-agent --only-failedで、直前runの失敗ツール・失敗ファイルのみをまとめて再実行する。 個別にretry_commandをコピーする手間を省きたい場合に使う。 参照runを明示する場合は--from-run RUN_IDを併用する（前方一致またはlatestを指定可）。

show-run でアーカイブから全文ログを取得

messageが切り詰められた場合や、確定したrunを後から再確認したい場合は実行アーカイブから取得する。 header.run_idまたはsummaryの前後に出るrun_idを控えておく。

# 単一ツールの output.log 全文を表示
uvx pyfltr show-run RUN_ID --commands=TOOL --output

# 複数ツールの diagnostics.jsonl をまとめて表示
uvx pyfltr show-run RUN_ID --commands=mypy,ruff-check

--commandsはカンマ区切りで複数指定可（旧 --tool は廃止）。 --outputとの併用は単一ツール指定のみ許容される。最新runを参照する場合はRUN_IDにlatestを指定できる。

statusフィールドの意味

status	意味	対応
succeeded	問題なし	不要
formatted	formatterがファイルを変更した	ciでは失敗扱い／run系では再実行不要（補足参照）
failed	エラーあり	diagnostic行で修正対象のファイル・行番号・メッセージを確認する
resolution_failed	ツール起動コマンドの解決失敗（bin-runner/js-runner未提供等）	「bin-runner未提供環境」節を参照
skipped	ツール未検出などでスキップ	通常は無視してよい

• formattedはrun系では正常終了するため看過されやすい。実行後はgit diffで変更内容を必ず確認してからコミットする
• formattedがrun系の繰り返しでも消えない場合はformatter/linter間の設定矛盾を疑い、 pyproject.tomlの[tool.ruff-format]と[tool.ruff-check]を突き合わせる

効率的なワークフロー

実行範囲の使い分け

コミット前検証は対象ファイルや対象ツールを必要に応じて限定して実行する（最終検証はCIに委ねる前提）。

uvx pyfltr run-for-agent --commands=mypy path/to/file

--commandsで特定ツールに限定する、または対象ファイルを指定することで出力量を抑え、 diagnostic行から修正対象を取得する。

公開インターフェース（関数シグネチャ・型定義・モジュール構造など）を変更した場合や、 状況全体を把握したい場合は全体で実行する。

uvx pyfltr run-for-agent

末尾のsummary行でfailedの有無とdiagnostics数を確認する。 run-for-agentは前段で自動fixを適用するため、autofixで解消できる違反はここで消える。

--commandsオプション

カンマ区切りで実行するツールを指定する。全サブコマンドで使用可能。

uvx pyfltr run-for-agent --commands=mypy,ruff-check

以下のエイリアスも利用できる。

• format: 全formatter（pre-commit、ruff-format、prettier、uv-sort、shfmt、cargo-fmt、dotnet-format等）
• lint: 全linter（ruff-check、mypy、pylint、pyright、ty、markdownlint、textlint等。Rust／dotnet系も含む）
• test: 全tester（pytest、vitest、cargo-test、dotnet-test等）
• fast: fastサブコマンド対象のコマンド

主要なCLIオプション

オプション	説明
--commands=<list>	実行ツールをカンマ区切りで指定
--no-fix	run／fastで自動付与されるfixステージを抑止
--fail-fast	1ツールでもエラーが出た時点で残りを打ち切る
--only-failed	直前runの失敗ツール・失敗ファイルのみ再実行する
--from-run <RUN_ID>	--only-failedの参照runを明示指定（前方一致・latest対応）
--no-cache	ファイルhashキャッシュを無効化する
--human-readable	ツールの構造化出力（JSON等）を無効化し元のテキスト出力を使う
--no-exclude / --no-gitignore	ファイル除外設定を無効化

トラブルシューティング

• エラー内容がdiagnostic行だけでは把握しづらい場合、 uvx pyfltr run --output-format=text等でテキスト出力を得てツールの生出力を確認する
• --no-fixで自動fixを止めた状態でrun/fastを実行すると、autofixで解消できる違反がdiagnosticに残ることがある。 意図的に抑止する場合以外は付けずに実行する
• 特定ツールのみ再実行したい場合は--commands=<ツール名>で対象を限定する（全体再実行より早く原因切り分けできる）
• bin-runner未提供環境（Windows等でmise経由バイナリを提供しないツール、shellcheck・shfmtなど）: 対象ファイルが0件のときは解決処理自体を省略するためskippedで通過する。 対象ファイルがある状態で解決に失敗した場合はresolution_failedが出る。 回避策はbin-runnerをdirectに切り替えてシステムにインストール済みのバイナリを使うか、 当該ツールを{tool} = falseで無効化する
• 特定ツールの解決状況（enable/runner/executable）を実機で即座に確認したい場合は uvx pyfltr command-info --check <tool>を使う。 mise経由ツールでは mise install / mise trust の副作用が発生し得る点に注意する
• 特定ディレクトリがextend-exclude等で除外されている場合、uvx pyfltr run-for-agentの検査対象から外れる。 除外を一時的に無視して特定ファイルをチェックしたいときは--no-excludeオプションを使う （例: uvx pyfltr run-for-agent --no-exclude path/to/file）。 pyfltr自体の除外設定はpyproject.tomlの[tool.pyfltr]またはツール固有のextend-excludeを参照する
• コマンド実行のタイムアウトはpyproject.tomlの[tool.pyfltr]配下に command-timeout（グローバル既定値、秒単位。既定600秒、0で無効化）と {command}-timeout（per-tool値、-1で未設定sentinel・グローバル値にフォールバック、 0で当該per-toolを明示的に無効化）で調整できる。 pytest-xdist併用時のハング解析やLLMによる観測でtimeout調整が必要になった場合に活用する。 ハング由来の停止はJSONLのcommand.hintsのstatus.timeout注記で識別できる

詳細情報

pyfltrの設定リファレンス、カスタムコマンドの追加方法、pre-commit連携の設定例などの詳細情報が必要な場合は、 llms.txtをWebFetchで取得する。 llms.txtにはサブコマンド一覧・対応ツール・設定の基本が含まれており、各ページへのリンクから必要なページを個別に取得する。 主要なページは以下の構成。

• 設定（基本設定・プリセット・並列実行）: guide/configuration/index.md
• ツール別設定（直接実行 / js-runner / bin-runnerのカテゴリ別設定・2段階実行・カスタムコマンド）: guide/configuration-tools/index.md
• 推奨設定（Pythonプロジェクト・タスクランナー・CI）: guide/recommended/index.md
• 非Python推奨設定（TypeScript／JS・Rust・.NET）: guide/recommended-nonpython/index.md

カスタムコマンドを設定する際は、{command}-severity（"error" / "warning"）と {command}-hints（文字列配列）が指定できる。 severity = "warning"はパイプラインを止めずに警告通知する用途に使う。 {command}-path・{command}-args・{command}-fix-argsに含まれる~は、 subprocess引数組み立て直前にホームディレクトリへ展開される。