こんにちは、エンジニアのオオバです。

お悩みさん
お悩みさん
  • claude -pでスクリプトからClaude Codeを夜間に動かしたい
  • --json-schemaで指摘を構造化して受け取りたい
  • 既定のSonnetが途中で切り上げてしまう
  • オオバ
    オオバ
    本記事ではこれらの悩みを解決します。

    Mac miniで毎晩、ゲームのリポジトリ(約2,000ファイル)を点検させています。
    見てもらうのは、リファクタできそうな箇所と、ドキュメントと実装のズレです。

    Slackに流すと長くなるので、専用ページに積んでおきます。
    朝に1件ずつ、OKにするかタスク管理アプリへ送るかを選ぶ運用です。

    既定のSonnetは全部読まずに切り上げたので、全部読む指示を足してOpusとeffort highにしたら夜間で回せた

    先に結論をまとめます。

    claude -pで夜間に点検を回すときの要点

    ①構造化出力は --output-format json と --json-schema で受け取り、structured_output を読む

    ②許可するツールは Read・Grep・Glob と git diff などの参照系だけにする

    ③既定のSonnetは対象を読み切らずに返すことがあるので、全部読む指示を入れ、Opusとeffort highにする

    ④指摘には実在するファイルと行を必須にし、存在しないパスを指す指摘は捨てる

    では本編に入っていきます。

    →11万文字で徹底解説した「DOTweenの教科書」Unityアニメーションの超効率化ツールはこちら

    やりたかったこと:毎晩、コードの弱いところを一周読んでもらう

    ゲームのコードは、作っているうちに少しずつ古くなっていきます。
    直したい場所は分かっていても、毎日は手が回りません。

    そこで夜のうちにAIに読んでもらい、朝に候補を見て判断する形にしたかったわけです。

    ただ、2,000ファイルを毎晩まるごと読ませるのは、時間もお金も重いです。
    なので、点検を2つに分けました。

    差分は変化があった場所を逃さないためです。区画は差分に出てこない古い場所も、順番に一周させるためにあります。

    やったこと:構造化出力と参照系だけの許可

    claude -p に --output-format json --json-schema を付けると、結果が structured_output に入ります。
    指摘の形をスキーマで決めておけば、あとの処理でそのまま扱えます。

    ツールは --allowedTools で絞りました。
    Read・Grep・Glob と、Bash(git diff:*) のような参照系だけです。
    書き込みにつながるものは渡していません。

    指摘の質も守らせました。
    指摘には実在するファイルと行を必須にし、存在しないパスを指す指摘は捨てる、というルールです。

    既知の指摘はプロンプトに渡し、重複するものは sameAs で同じ指摘を指させました。
    OKにしたものを出し直させないためです。

    Codexを非対話で呼んだときの落とし穴は、@mySimpleLink:ai-runner-claude-and-codex-switch にまとめています。

    claude -pのフックで起きた話は、@mySimpleLink:ai-usage-log-dedup-pitfalls に書きました。

    結果:Sonnetは38秒で0件、Opusは7分で112ファイル

    最初はCLIの既定のSonnetで回しました。
    差分の80件を見きれないまま切り上げ、38秒で「確証のある指摘は0件」と返してきました。

    0件という結果は、点検が済んだ証拠になりません。
    読み切ったのか、途中で止まったのかが、出力だけでは見分けられないからです。

    そこでプロンプトに「対象は全部読む」「gitは単体で、検索はGrepツール」を足しました。
    読んだファイルを reviewed で返させ、モデルをOpus、effort を high にしています。

    結果はこうでした。

    その日のログです。1回目(10:02、既定のモデル)は、差分の点検を始めて40秒ほどで「0件の返事」。2回目(10:05、Opus・effort high)は、差分が7分で112ファイル、巡回が6分で70ファイルを読んでいます。

    夜間コード点検のログ(10/21)。区画・文書の名前と点検ページのURLは伏せ字にしています

    1回目は39秒で0件、2回目は7分で112ファイル読んだ点検のログ

    夜間コード点検のページ。指摘ごとにOKか、タスクへ送るかを選ぶ(未公開のゲームのファイル名・クラス名・指摘の本文は塗りつぶしています)

    夜間コード点検のページ。指摘ごとにOKかタスクへ送る

    タブの「未判定 23」は、1回目の4件と2回目の19件の合計です(ログの最後の行と同じ数)。

    10件のうち、本物の不具合候補が1件ありました。
    古い集約を保存する処理が、ほかの経路での変更を上書きして消しうる、という指摘です。

    費用は定価換算で一晩約10ドルでした。

    ハマった点と寄り道

    ひとつめは、複合コマンドの許可です。
    cd ...; git diff ... | head のように書くと、Bash(git diff:*) の許可パターンに合わず、permission_denials に積まれていました。
    gitは単体で呼ぶ形に直しました。

    ふたつめは寄り道です。
    launchctl bootout の直後に bootstrap すると Input/output error(5) で失敗します。
    停止が終わるのを待ってから起動し直す必要がありました。

    macOS標準のSQLiteは persistent WAL にしていると -shm ファイルを残すので、そこも覚えておくとよさそうです。

    まとめ

    夜間にAIへ全部読ませると、人がやらない範囲まで見てくれます。
    ただ、0件という結果をそのまま信じると危ないのが、今回の学びです。

    読んだ範囲を返させて、読み切れたかを確かめるところまでが点検だと思っています。
    朝に1件ずつ判断する運用は、この形で続けています。

    オススメ記事
    検証環境