Claude CodeでGradleビルドを回す — 出力を絞る-qと--console=plain

Claude CodeにGradleビルドを任せるなら、ログの量は先に絞っておくのが安全です。柱は3つあります。ログの詳しさを決める-q、画面の装飾を切る--console=plain、そしてこの2つを毎回打たせないためのgradle.propertiesです。この記事では、それぞれが何を変えるのかと、CLAUDE.mdへの書き方を扱います。

3つの調整軸は別々に効く

Gradleの出力に効くオプションは、役割が重ならない3系統です。混ぜて覚えると、どれを足せば何が減るのかが分からなくなります。

ログレベルは、Gradleのログ解説に載る6段階（ERROR、QUIET、WARNING、LIFECYCLE、INFO、DEBUG）のどこまで出すかを決めます。何も指定しない既定はLIFECYCLEで、進捗の情報が出ます。-qにするとQUIET以上だけになり、コマンドラインオプションの一覧では「エラーのみを記録」と説明されています。

コンソール表示は別の軸です。--console=plainは色やリッチな出力をすべて止め、プレーンテキストだけを出します。ログレベルは変えません。

Claude Codeが受け取る出力には上限がある

ログを絞る理由は、Claude CodeのBashツールの仕様にあります。コマンドの出力は、成功と失敗で渡り方が変わります。

失敗の扱いが厳しい点に注意が要ります。終了コード1を正常な結果として扱うのはgrepやfind、diffなど一部のコマンドだけです。Gradleのビルドが失敗して終了コード1を返せば、失敗として扱われます。

つまり、ビルドが落ちたときに限って、詳細なログの途中が抜粋で切られます。落ちた原因を読ませたい場面でログが長いほど、情報の欠ける余地が広がります。

出力の上限そのものを上げる設定にはbashOutputMaxCharsがあります。詳しくはbashOutputMaxCharsの解説にまとめています。この設定は出力の読み戻し範囲を広げるものです。失敗時のインライン上限(約10,000字)がこの設定で変わるとは、tools-referenceに書かれていません。ログを増やしてから上限を上げるより、ログを減らすほうが筋の良い順序です。

-qと--console=plainをどう使い分けるか

状況別に選ぶと、次のようになります。

コンソール表示のモードにはplainのほかにauto（既定）、colored、rich、verboseがあります。richは端末に接続されていなくてもANSI制御文字で進捗バーを描くモードです。ログに制御文字が混じるなら、richが指定されていないかをまず疑えます。

Claude CodeのBashツールが、Gradleから見て端末に接続された状態になるのかどうかは、Claude Code側のドキュメントに記載がありません。そこで、--console=plainを書いて表示を固定するほうが確実です。

実行例

最小の形は次の2行です。

./gradlew build -q --console=plain
echo "exit code: $?"

-qは成功時にほぼ何も出さないので、終了コードを一緒に見る習慣が要ります。何も出ないのは成功のしるしですが、Claudeに「出力が空＝成功」と読ませるなら、終了コードの確認を指示に含める必要があります。

失敗したときだけ詳しく読む二段運用

毎回-qだと、失敗したときに原因が足りません。逆に毎回詳細だと、成功のたびにコンテキストを消費します。折衷として、通常は静かに回し、失敗したらログをファイルに残して必要な範囲だけ読ませる運用が使えます。

./gradlew build --console=plain > build/gradle.log 2>&1; \
  echo "exit code: $?"; tail -n 60 build/gradle.log

標準出力と標準エラーをファイルに流し、終了コードと末尾60行だけを返します。抜粋が必要なら、Claudeはgrepでログを検索できます。ログの全量がインラインで渡るわけではないので、成功時も失敗時も大量のテキストを抱え込みません。

ログの出力先をbuild/にしている点は、プロジェクトの慣習に合わせて変えてください。.gitignoreの対象になっているディレクトリを選べば、ログが差分に混じりません。

失敗を調べるときは、--continueを足す手もあります。Gradleは既定で、タスクが1つ失敗すると実行を打ち切ります。--continueを付けると、失敗したタスクに依存しないタスクを最後まで実行し、遭遇した失敗をビルドの終わりにまとめて出します。何度も再実行して原因を1つずつ掘るより、1回の実行で全体を見渡せるぶん、往復するログの量を抑えられます。ただしコンパイルエラーがあれば、それに依存するテストは走りません。

gradle.propertiesに寄せるか、CLAUDE.mdに書くか

オプションを毎回Claudeに打たせると、書き忘れが出ます。Gradleには、同じ設定をgradle.propertiesに置く方法があります。

org.gradle.console=plain
org.gradle.logging.level=quiet
org.gradle.warning.mode=summary
org.gradle.console.interactive=false

コマンドラインの--console、-q、--warning-modeに対応するプロパティです。パフォーマンス系のオプションについても、gradle.propertiesに書けるためコマンドラインのフラグは不要だと案内されています。

最後のorg.gradle.console.interactive=falseは、Gradleがコンソールで入力を求めないようにする設定です。Gradleのドキュメントには、CIパイプラインやスクリプト、AIエージェントのような自動化環境で役立つと明記されています。同じ目的のコマンドラインオプションは--non-interactiveですが、こちらはIncubating（開発途上）の扱いです。

ただし、org.gradle.logging.level=quietをプロジェクトのgradle.propertiesに入れると、人間の開発者のビルドも静かになります。チームで共有するリポジトリでは、個人用のユーザーホーム側のgradle.propertiesに置くか、Claudeに渡すコマンドでだけ-qを付ける、といった分け方が現実的です。

CLAUDE.mdに書く内容

どちらを選んでも、ビルドの回し方はCLAUDE.mdに書いておきます。次は書き方の一例です。

## Gradleビルド
- ビルドは `./gradlew <task> --console=plain` で実行する
- 成功の確認は `-q` を付け、終了コードで判断する
- 失敗したら `-q` を外し、ログを `build/gradle.log` に保存して末尾60行を読む
- ログ全文を貼り直さない。必要な箇所は `grep` で探す

ここで大事なのは、「いつ静かにして、いつ詳しくするか」を条件つきで書くことです。「常に-q」と書くと、失敗の調査でもClaudeが情報を絞ったままにしかねません。

CLAUDE.mdは指示であり、設定ファイルのように強制力はありません。確実に効かせたい項目はgradle.propertiesに寄せ、CLAUDE.mdには判断の基準を書く、という分担が噛み合います。

デーモンと実行時間のつまずき

Gradleはデーモンと呼ぶ常駐プロセスでビルドを実行します。クライアントがビルドの要求を送り、デーモンがビルドを実行して、出力をクライアントに返す構造です。起動を省いて2回目以降を速くするための仕組みで、既定で有効です。

Claude Codeと組み合わせるときに押さえたい点は3つあります。

• デーモンはセッションが終わっても残る: アイドル状態が3時間続くまで生き続けます。gradle --statusで一覧でき、gradle --stopで同じバージョンのデーモンを止められます
• JVM引数が変わると別のデーモンが起動する: 既存のデーモンを再利用するのは、JavaのホームとJVM引数が同一の場合だけです。引数を変えるたびに新しいデーモンが増えます
• 最初のビルドは時間がかかる: Bashツールの前面実行の既定タイムアウトは2分です。長くなる場合、Claudeがtimeoutを指定して延ばします。上限は既定で10分で、BASH_MAX_TIMEOUT_MSで変えられます

動作が不安定なとき、デーモンを止めてやり直すのはGradle側で案内されている切り分け手順です。止めるコマンドをCLAUDE.mdに書いておくと、Claudeが原因の切り分けで迷いません。

ビルドを止めずに別の作業を進めたいときは、Claude側のバックグラウンド実行も使えます。Claudeがrun_in_background: trueでコマンドを起動し、/tasksで一覧と停止ができます。

よくあるつまずき

-qにしたら原因が分からなくなった: 失敗時は-qを外します。-w（WARN以上）が中間で、警告まで見えます。

非推奨機能の警告が大量に出る: 既定では警告を集めて最後に要約だけを出します。--warning-mode=allにすると全件が出るので、増えたと感じたら指定を確認してください。要約すら不要ならnoneです。

ログに制御文字が混じる: --console=plainで解消します。richを指定していないかも確認します。

環境変数NO_COLORは進捗バーを消さない: NO_COLORを設定するとGradleは色を止めますが、太字・下線や進捗バーといったリッチな機能は影響を受けません。装飾を丸ごと止めるのは--console=plainのほうです。

まとめ

量を減らすのは-q、形を整えるのは--console=plainで、効き方が違います。成功の確認は静かに、失敗の調査は詳しくという条件分けをCLAUDE.mdに書き、固定したい設定はgradle.propertiesに寄せると、ビルドのたびに出力を気にせず済みます。同じ発想はほかのビルドツールにも通じます。たとえばwestビルドを使うZephyrの開発でも、出力の量を絞る考え方は共通です。

CIのログから失敗を診断する流れは、ClaudeとCircleCIの連携も参考になります。