psAIDopagaki 開発ナレッジ

Appearance

Claude Code を使いこなすための学び ​

3 日間の運用から抽出した、再利用できる知見です。

A. 長時間走らせるための設計 ​

  1. /goal は「完了条件」を書く — 「〜まで進めて」「PR は自動でよい」「役割はこう」まで一文に含めると、Stop フックがそのまま判定基準になる。
  2. 重い処理は Workflow に出し、親は判定だけする — 親のコンテキストにツール出力を入れないことが、3 日間動き続けられた最大の理由（親 ≈1M トークン、サブ ≈25M）。
  3. 待ちは Monitor / background Bash でイベント化 — journal.jsonl の新規行だけを通知にすると、check-in ごとの確認は 1 コマンドで済む。
  4. resume 可能にしておく — resumeFromRunId と自前の resume 引数（PR から再開）を最初から用意すると、上限・再起動・エスカレーションが「やり直し」にならない。
  5. 上限リセット時刻はタイマーで待つ — sleep を background Bash にして通知で復帰。待っている間は別経路（Codex 直接運転）で前進する。

B. マルチエージェントの品質を保つ ​

  1. ゲートは 2 系統（E2E + レビュー）にし、両方 ✅ でだけマージ — 片方だけだと「テストを緩めて通す」変更が入る。実際に 4 件を Opus レビューが止めた。
  2. レビュー担当に「独立に裏取り」させる — 差分だけでなく前後コミットのキャプチャや git diff -- tools/run_emu.sh を見させると、ゲート緩和・退行・メッセージと実装の食い違いを検出できる。
  3. StructuredOutput で契約を固定 — verdict / merge / fix_instructions を JSON で受けると、スクリプト側の分岐が壊れない。
  4. fix 指示は judge に書かせる — E2E とレビューの生指摘をそのまま渡すより、Fable が優先順位と受入条件番号を付けた fix_instructions に変換した方が修正ラウンドの収束が早い。
  5. ラウンド上限で親に返す — 3 ラウンドで収束しない案件は設計判断が必要なことが多い（glow の透過、BAD の歪み定義）。親が設計判断をして追加ラウンドに戻す。
  6. 正典ファイルを「読め」と名指しする — .agent/workflows/*.md、設計書の節番号、SDK の例ファイル名まで指定すると、エージェント間の解釈ブレが減る。

C. Codex CLI と組み合わせるとき ​

  1. 運転手（Claude）+ 作業者（Codex）に分ける — Codex は git index / GitHub API に触れないことが多い。git・PR・エビデンス投稿は Claude が担当。
  2. プロンプトはファイル経由 + < /dev/null — 長い引数だと stdin 待ちでハングする。"$(cat task.md)" < /dev/null に固定。
  3. pkill -f "codex exec …" は並走中の他プロセスも殺す — PID を限定するか、殺す前に pgrep -fl で確認。
  4. クォータ切れの検出と切替を事前にプロンプト化 — 「1 回だけ試し、usage limit なら自分で実装（3-6 フォールバック）」を ENV に入れておくと、パイプラインが止まらない。
  5. 途中で切れた Codex の成果を検証せずにコミットしない — #8 で「コミットメッセージだけ先行し実装が伴わない」状態を作った。make test が通っても E2E とレビューを通す。

D. エミュレータ E2E のコツ ​

  1. GUI ではなく CLI + Lua — PCSX-Redux -no-ui -softgpu -run -exe … -exec "dofile(...)"、PCSX.GPU.takeScreenShot() → raw → PNG。screencapture は使わない（権限で黒画像）。
  2. ゴールデンは「意図した差分」を理由つきで更新 — UPDATE_GOLDEN=1 の標準経路だけを使い、PR コメントに before/after を残す。直接 cp は分類器にもブロックされる。
  3. 合否はメトリクスで — frame_skips、cpu_max_ms、GTE 棄却数、OT 予算、キャラ固有色率。枚数や「何か描けている」では退行を見逃す。
  4. エミュレータ自体のクラッシュとゲートの失敗を区別 — PASS / GATE_FAIL / EMU_CRASH の 3 分類にし、EMU_CRASH だけリトライ。

E. 権限・安全の線引き ​

  1. 外向き操作はユーザーの明示許可の範囲で — リポジトリ作成・自動マージは指示があった。マスターの GitHub 保存は「取っておいて」の解釈として実施し報告。
  2. 分類器にブロックされた操作は肩代わりしない — 標準経路（UPDATE_GOLDEN=1）で通るならそれを使い、通らなければ代替エビデンスで判定してユーザーに報告する。
  3. レースを前提に「状態を見てから動く」 — 親の指示が古い場合（既にマージ済み）に、エージェントが gh pr view で確認して「追加作業不要」と判断できたのは、指示に「状態確認」を含めていたから。

F. アセット生成（higgsfield） ​

  1. 参照画像 + 用途を明示したプロンプト — 「正面 A ポーズ、白背景、フラット塗り、16 色程度、パーツ切り出し用」のように 後工程の制約 を書くと、そのまま使える素材になる。
  2. 減色は専用前処理を噛ませる — PixelRefiner（Oklab 量子化 + ディザ + AA 除去）を png2tim の前段に入れ、透明キーはリサイズ前にマスク化する。加算合成素材は透過キー不要。

次に同じことをするなら ​

  • Workflow スクリプトに 「テストを弱める変更の自動検出」（run_emu.sh / emu_shot_to_png.py の閾値・フラグ差分を PR に自動添付）を入れる
  • judge が 設計判断を要する差戻し を early-escalate できるよう、fix_instructions に needs_design_decision: true を追加する
  • Codex / Claude の クォータ残量を事前チェック するステップを implement の前に置く

aieo-product 内部ナレッジ

2026 AIEO