【要約】手元では通るのに CI だけ落ちる — ruff format は Markdown の中の Python も整形していた [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
開発者が README.md を更新して GitHub に push した際、手元のチェックは成功したものの CI のみ失敗する問題に直面した。原因は Ruff の各コマンドが Markdown を扱う仕様の差異にある。具体的には以下の問題が発生していた。
- ・
ruff checkは Markdown 内の Python コードを無視する。 - ・
ruff formatは特定のタグ付きコードブロックを整形対象とする。 - ・この非対称性により、
ruff checkの成功がフォーマットの正当性を保証しなかった。
// Approach
開発者は、Ruff の挙動の差異を特定するために、Markdown の記述パターンを変えた最小再現環境で検証を行った。その結果に基づき、以下の解決策を提示している。
- ・CI と同一のコマンドを、手元でも同じ順序で実行する。
- ・
pre-commitを導入し、コミット時に自動でチェックを走らせる。 - ・
pyproject.tomlのextend-excludeを使い、Markdown を除外する。
// Result
調査の結果、Ruff の各コマンドが Markdown を扱う仕様の違いが明確になった。これにより、CI 失敗の根本原因が「実行したチェックの不足」であることを特定できた。
- ・
ruff formatはpythonまたはpyタグ付きのブロックを整形する。 - ・タグなしのコードブロックは整形対象外となる。
- ・CI と同じ手順を踏むことが、最も確実な回避策である。
Senior Engineer Insight
> ツール間の挙動の非対称性は、開発体験（DX）を著しく損なう。特に「手元では通る」という状況は、開発者の信頼を失わせる。大規模な開発現場では、CI の成功条件をローカルで完全に再現する仕組みが不可欠である。
pre-commit の導入は、単なる自動化ではなく、CI とローカルの乖離を防ぐための防衛策として極めて有効である。また、ドキュメント内のコードも資産と捉え、自動整形を有効に保つ運用が望ましい。