コンテンツにスキップ

AI Session Notes - 2026-03-06

AIエージェント協業では「進捗の正本」を1つに固定する

学んだこと

  • AI実装を複数ツールで回すときは、進捗の正本を1つに固定しないと「どこまで終わったか」がすぐにズレる
  • Markdownの中間ファイルだけでは更新漏れが起こるため、Issueトラッカーのイベント（Start/Done）を主軸にした方が監視しやすい
  • 中間ファイルは補助情報として使い、必須更新項目（current/next/blocked）だけを絞ると運用が安定する

詳細

実運用で安定する最小ルール：

  1. 進捗の正本は Issue Tracker に固定
  2. 各タスクで Start と Done コメントを必須化
  3. 中間ファイルは補助（現在タスク、次タスク、blocker）に限定
  4. 長時間更新がない場合は blocked を明示

レビュー自動化の遅延対策は「タイムボックス + 再試行戦略」で設計する

学んだこと

  • 外部レビュー（MCP経由など）は遅延・タイムアウトが発生し得る前提で、待機時間を明文化しておくべき
  • 「何分待つか」「何回再試行するか」「失敗時にどう前進するか」を事前定義すると、実装が止まりにくい
  • モデル固定運用でも、再試行時のみ軽量モデルに切り替えるフォールバックを持つとスループットが改善する
  • 再試行回数は「合計実行回数」で管理すると判断がぶれにくい（例: 初回 + 再試行3回 = 最大4回）

詳細

実用的なポリシー例：

  • 初回レビュー待機: 5分
  • タイムアウト時: 最大3回再試行（合計最大4回）
  • 1回目: 高性能モデルのまま、差分限定 + blockerのみ
  • 2回目: 軽量モデルへフォールバック
  • 3回目: プロンプト最小化（blockerのみ・最大件数制限）
  • それでも失敗: review_skipped_timeout を記録して次へ進む

Codex CLI レビューは「ヘルプ表示」と「実挙動」の差分に注意する

学んだこと

  • CLIツールでは、ヘルプ上は可能に見える引数組み合わせでも、実行時に排他エラーになることがある
  • codex review の差分レビュー系オプション（--uncommitted など）は、バージョンによってプロンプト併用が失敗するケースがある
  • 設定の上書きキーを間違えると、モデルパラメータが意図どおりに反映されない
  • ドキュメントに「実際に通るコマンド例」を残すと、運用の再現性が上がる

詳細

実運用で有効だった対策：

  1. レビュー実行コマンドはテンプレ化して固定
  2. 失敗時は引数を1つずつ減らして最小再現を確認
  3. 設定キー名（例: model_reasoning_effort）を明示
  4. ツールバージョン依存の注意点を運用ドキュメントへ反映

並行作業中は「対象ファイル限定コミット」で衝突を避ける

学んだこと

  • 別エージェントが同じワークツリーで実装中のとき、ドキュメント更新を混ぜるとレビュー境界が壊れる
  • git add <対象ファイル> でコミット範囲を限定すれば、実装中変更を汚さずに運用ルールだけ先に反映できる
  • 「コミットは分離、pushタイミングは明示」という運用が、後続の差分管理を大きく楽にする

自動化コマンドが中断されたら「部分成功」を前提に再開する

学んだこと

  • ネットワーク系コマンドやCLI自動化は、中断されても一部だけ成功していることがある
  • 再実行前に「リモート状態」「ローカル状態」「副作用の有無」を確認しないと重複作成を招く
  • 再開手順を標準化しておくと、障害復旧の判断が速くなる

詳細

再開時チェックの基本順序：

  1. 認証/疎通確認
  2. 既存リソース確認（既に作られていないか）
  3. ローカル同期状態確認
  4. 不足分だけ再実行

テストの「空振り成功」パターンに注意する

学んだこと

  • テスト内で if (condition) { expect(...) } と書くと、条件を満たさない場合にアサーションが実行されずテストが成功扱いになる（vacuous success / false positive）
  • ランダム生成に依存するテストでは、前提条件が満たされたこと自体をアサーションで検証する
  • Codex CLI のコードレビューでこのパターンが検出された — 静的解析やレビューで発見できる典型的な落とし穴

詳細

悪い例：

// noteIndex === 1 が生成されなければ、テストは何も検証せず pass する
if (state.currentQuestion.noteIndex === 1) {
  expect(isCorrect(1, 1)).toBe(true);
}

良い例：

let found = false;
for (let i = 0; i < 500; i++) {
  // ... generate ...
  if (state.currentQuestion.noteIndex === 1) { found = true; break; }
}
expect(found).toBe(true);  // 前提条件自体を検証
expect(isCorrect(1, 1)).toBe(true);

「手動E2E」タスクでもドメインレベルの受け入れテストで代替できる

学んだこと

  • ブラウザ操作を伴う手動E2Eが難しい場合でも、受け入れ基準をreducer＋ドメイン層のテストとして表現すれば、ロジックの正しさは自動検証できる
  • 受け入れ基準の各項目をテストケース名に対応付ける（例: AC1:, AC6: プレフィックス）と、要件とテストのトレーサビリティが明確になる
  • UI層の見た目・操作感は別途確認が必要だが、「ビジネスロジックが正しいか」と「UIが正しいか」を分離して検証する戦略は効率的

READMEは「ツール別」でなく「タスク別」に構成する

学んだこと

  • 「セットアップ」と「開発コマンド」を別セクションに分けると、初めて触る人が手順を追えない
  • 「クイックスタート」としてゼロから動くまでの手順を1セクションにまとめ、最後にアクセスURLを明示する構成が最も伝わりやすい
  • Docker の sleep infinity パターンでは、コンテナ起動とdevサーバー起動が別ステップであることをドキュメントで明示しないとユーザーが混乱する

Docker開発では『毎回 install 実行』と『キャッシュ戦略』を分けて評価する

学んだこと

  • コンテナ起動時に pnpm install --frozen-lockfile を毎回実行しても、node_modules とパッケージストアを永続ボリューム化していれば多くの場合は高速なno-opで終わる
  • 起動ロジックを複雑化する前に、実ログ（Lockfile is up to date, Already up to date, 実行時間）で実測確認する方が安全
  • 依存更新の取りこぼしを避けたい場合は、条件付きスクリプトよりも『毎回 install + キャッシュ』の単純構成が運用しやすい

ドキュメントは『運用ルール』と『バージョン仕様』を分離すると保守しやすい

学んだこと

  • 変更頻度の低い開発プロセス文書と、リリースごとに変わる仕様文書はディレクトリを分けると更新責務が明確になる
  • 仕様変更時に新しいバージョンディレクトリを切る運用にすると、旧仕様を履歴として保持しやすい
  • README/索引のリンクを同時更新することで、構造変更後の参照切れを防げる

要望整理は『事実 -> 要件 -> タスク -> 決定事項固定』の順に進める

学んだこと

  • ユーザーの不満をまず事実として列挙し、優先度付き要件に変換してから実装タスクへ落とすと議論がぶれにくい
  • 未確定事項を先に明示し、意思決定後に仕様・トラッカー・個別タスクへ同時反映すると実装時の解釈差を減らせる
  • 方針決定だけを独立Issueで先に閉じると、後続Issueのスコープが安定する

図形UIの位置合わせは「セル境界」より「オブジェクト中心座標」が保守しやすい

学んだこと

  • 指板や鍵盤のような図形UIでは、テーブルセル + border で線を表現すると、ラベル・マーカー・余白の整列調整が局所最適になりやすい
  • 「弦」「フレット」「押弦マーカー」「背景面」を別レイヤーとして持ち、座標変数で配置すると意図した位置関係を維持しやすい
  • 見た目の微調整（上下端余白、ラベル中央合わせ、線太さ変更）が独立して行えるため、改修時の副作用が減る

音高処理は「音名クラス」と「絶対音高」を分離すると破綻しにくい

学んだこと

  • 問題の正誤判定は12音クラス（C〜B相当）で十分でも、再生音は絶対音高を持たせないとオクターブ違和感が出る
  • 再生系は MIDI 番号などの絶対指標を基準にし、midi -> frequency 変換を一箇所に集約すると設計が明確になる
  • 楽器UIでは「開放弦」「隣接フレット」「12フレット(+12半音)」を境界条件テストとして固定すると回帰を検出しやすい

非対話環境での依存解決は「TTY前提の中断」を先に疑う

学んだこと

  • 自動化実行では、依存解決コマンドがTTY前提の確認プロンプトで中断されることがある
  • CI=true などの非対話モードを明示して再実行すると、同じコマンドでも安定して完走する場合がある
  • optional dependency 欠落エラーが出たときは、まず「ネットワーク到達性」と「非対話モード」で再インストールを試すのが有効

モジュールに export を追加したら既存のテストモックも更新する

学んだこと

  • vi.mock() でモジュール全体をモックしている場合、本体に新しい export を追加しても、モック定義にそれを含めないとテスト実行時に undefined になる
  • Codex CLI のレビューでこのパターンが P2 として検出された — 本体コードは正しくても、モックの更新漏れでテスト側が壊れるケース
  • 新しい関数を追加したら「この関数を import しているファイルのテストにモックがあるか」を確認する習慣が必要

詳細

// audio.ts に playMidiNote を追加した場合
// quiz-screen.test.ts のモックも更新が必要：
vi.mock('../../infra/audio', () => ({
  playNote: vi.fn(),
  playMidiNote: vi.fn(),  // ← 追加しないと undefined
  isSoundEnabled: vi.fn(() => true),
  setSoundEnabled: vi.fn(),
}));

CSS の table-layout: fixed で均等カラム幅を実現する

学んだこと

  • HTML テーブルのカラム幅はデフォルトでコンテンツに応じて可変（table-layout: auto）になるため、均等幅にしたい場合は table-layout: fixed を1行追加するだけで解決する
  • fixed レイアウトでは最初の行のセル幅（または <col> 指定）で全行の幅が決まるため、描画パフォーマンスも向上する
  • 特定カラムだけ固定幅にしたい場合は、そのカラムに width を指定し、残りが均等分配される

差分仕様ドキュメントは「合成手順」を明示しないと誤読される

学んだこと

  • バージョン仕様が差分ベースの場合、最新文書を「現行仕様」とだけ書くと単体完結の仕様書だと誤読されやすい
  • 索引側に「ベース仕様 + 差分適用順」を明記すると、実装者間の解釈ズレを減らせる
  • トップREADMEは入口リンクに限定し、詳細の履歴と読み順は docs 側の索引に集約すると肥大化を防ぎやすい

AI実装依頼は「Issue番号が埋まるまで着手禁止」をルール化すると安定する

学んだこと

  • 仕様文書だけで着手すると、実行順と依存関係の解釈が人やツールでずれやすい
  • 実装前提として「全タスクIssue化」「Trackerと依存関係の確定」「Issueリスト付き引き渡し」を必須にすると進行の再現性が上がる
  • 子Issueに依存先を明記し、Trackerにチェックリストを持たせる運用は、進捗管理と引き継ぎの両方に効く
  • 完了済みの旧Trackerを閉じ、アクティブなTrackerを1つに保つと運用ノイズが減る

権限制約付きCLIの失敗は「権限起因か」を先に切り分ける

学んだこと

  • Operation not permitted や lock file 作成失敗は、コマンド内容ではなく実行権限不足が原因になりやすい
  • この種の失敗は、同一コマンドを適切な権限で再実行するのが最短の復旧手順になる
  • 再実行前に git status などで部分実行の有無を確認しておくと、重複操作や取りこぼしを防げる

参考リンク

メタ情報

  • ツール: Codex, Claude Code, GitHub CLI
  • 関連技術: MCP, Codex CLI, AI Agent Workflow, Issue Driven Development, Issue Dependency Management, Requirements Engineering, Product Planning, Documentation Architecture, Timeout Handling, Retry Strategy, CLI Debugging, Git, Vitest, Testing Patterns, Docker, README Design, CSS Layout, UI Coordinate System Design, Web Audio API, MIDI