AI Session Notes - 2026-03-05

シェルスクリプトでのファイル mtime ベースキャッシュ

学んだこと

• 外部 API を定期的に呼ぶシェルスクリプトでは、ファイルの更新日時（mtime） を使った軽量キャッシュが有効
• JSON 内にタイムスタンプを持たせるよりシンプルで、stat コマンドだけで実装できる
• バックグラウンドでフェッチすればメインの処理をブロックしない

詳細

CACHE_FILE="/tmp/my-cache.json"
CACHE_TTL=360  # 秒

cache_age=$(( $(date +%s) - $(stat -f%m "$CACHE_FILE" 2>/dev/null || echo 0) ))
if [ "$cache_age" -ge "$CACHE_TTL" ]; then
  # バックグラウンドで再取得（メイン処理をブロックしない）
  ( fetch_data ) &
fi

# キャッシュファイルがあれば読む（古くても表示に使う）
if [ -f "$CACHE_FILE" ]; then
  DATA=$(cat "$CACHE_FILE")
fi

注意点： - stat -f%m は macOS 固有。Linux では stat -c%Y に変わる - キャッシュが古くても表示には使い、バックグラウンドで更新するパターン（stale-while-revalidate）が UX に良い

非公式 API 探索時の rate limit リスク

学んだこと

• 公式ドキュメントにないエンドポイントの認証方法を試行錯誤する際、短時間に複数パターンの認証を試すと rate limit で長時間ブロックされることがある
• 特に OAuth 系のエンドポイントは rate limit が厳しく、429 の retry-after が最大1時間近くになることもある
• 1回失敗したら手当たり次第に試すのではなく、ドキュメントや実装例を先に調べてから正しい方法で1回だけ叩くべき

Anthropic Usage API の実際のレスポンス構造

学んだこと

• Usage API (/api/oauth/usage) のレスポンスには、基本の five_hour / seven_day 以外にもモデル別・用途別の使用率が含まれる
• サブスクリプションプランによって返されるフィールドが異なる（null のフィールドは該当プランで未使用）

詳細

実際のレスポンス例：

{
  "five_hour": { "utilization": 3.0, "resets_at": "..." },
  "seven_day": { "utilization": 3.0, "resets_at": "..." },
  "seven_day_oauth_apps": null,
  "seven_day_opus": null,
  "seven_day_sonnet": { "utilization": 2.0, "resets_at": "..." },
  "seven_day_cowork": null,
  "extra_usage": {
    "is_enabled": true,
    "monthly_limit": 5000,
    "used_credits": 0.0,
    "utilization": null
  }
}

フィールド	内容
five_hour	5時間ウィンドウの総合使用率
seven_day	7日間ウィンドウの総合使用率
seven_day_sonnet / seven_day_opus	モデル別の7日間使用率
seven_day_oauth_apps	OAuthアプリ経由の使用率
seven_day_cowork	Cowork 機能の使用率
extra_usage	追加クレジット枠（月間上限と使用額）

JS動的レンダリングページからのデータ取得戦略

学んだこと

• SPA や JS で動的にレンダリングされるページは、単純な HTTP GET（WebFetch等）では HTML の骨格しか取得できず、実際のコンテンツが含まれない
• 対処の段階的アプローチ：
• API エンドポイント探索 - ページの JS ソースから fetch/axios/XMLHttpRequest の呼び出し先 URL を探す
• Web 検索で間接情報を収集 - ニュース記事やまとめサイトなど、同じ情報を静的に掲載しているページを探す
• 関連ページの探索 - 同一サイト内の別ページ（トップ、一覧ページ等）や、Filmarks・映画.com のような集約サイトを確認する
• ユーザーにページ内容の提供を依頼 - ブラウザで開いてもらい HTML を共有してもらう
• 最終的にはユーザーからページの HTML を直接もらうのが最も確実で速い

詳細

動的ページの調査で時間を浪費しがちなパターン： - WebFetch を何度も異なるプロンプトで試す → JS レンダリング問題なので何度やっても無駄 - API エンドポイントを推測して叩く → 認証やパスの問題でほぼ失敗する

早い段階で「このページは JS レンダリングだ」と判断し、代替手段に切り替えることが重要。

Codex CLI を Claude Code の MCP サーバーとして使う

学んだこと

• OpenAI の Codex CLI（v0.36.0〜）は codex mcp-server コマンドで MCP サーバーとして動作する
• Claude Code は MCP クライアントとして動作するため、Codex を MCP サーバーとして登録すれば、Claude Code から Codex（GPT-5-Codex）にタスクを委譲できる
• Claude Code 自体は MCP サーバーとしては動作しない（クライアント専用）
• Codex MCP サーバーはローカルプロセスとして動作し、ファイル操作やコマンド実行はローカルで行われる。AI 推論部分のみ OpenAI API にリモート送信される

アーキテクチャ

Claude Code (ローカル)
  ↓ MCP (stdio, JSON-RPC 2.0)
Codex MCP Server (ローカルプロセス)
  ↓ API 呼び出し (リモート)
OpenAI API (GPT-5-Codex)

設定方法

# Claude Code にユーザーレベルで MCP サーバーを追加
claude mcp add -s user codex codex mcp-server

これにより ~/.claude.json に以下が追加される：

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "codex",
      "args": ["mcp-server"]
    }
  }
}

注意点

• Codex の MCP インターフェースは experimental（実験的）ステータス。予告なく変更・削除される可能性がある
• Codex はコマンド実行時に applyPatchApproval / execCommandApproval という承認リクエストをクライアントに送る。Claude Code がこれに対応できるかは未検証
• 事前に codex login で OpenAI の認証を済ませておく必要がある
• 公式ドキュメント: codex_mcp_interface.md

MCP の役割整理

ツール	MCP クライアント	MCP サーバー
Claude Code	✅	❌
Claude Desktop	✅	❌
Codex CLI (v0.36.0〜)	✅	✅ (experimental)

pnpm グローバルパッケージの PATH 問題

学んだこと

• pnpm でグローバルインストールしたコマンドは ~/Library/pnpm/ に配置される（macOS の場合）
• .zshrc で PNPM_HOME を PATH に追加していても、一部のツール（Claude Code の Bash ツール等）ではシェル初期化が不完全で PATH が通らないことがある
• その場合、フルパスで指定するか source ~/.zshrc してから実行すれば動く
• MCP サーバーの command にはフルパスを書く方が安全だが、Claude Code の MCP サーバー起動はユーザーのシェル環境を引き継ぐため、通常は短いコマンド名で問題ない

Volta 管理下での npm グローバルパッケージ削除

学んだこと

• Volta を使っている環境では、npm uninstall -g でグローバルパッケージが削除できないことがある
• Volta は Node.js のバージョンごとに独立した node_modules を持つため、npm の通常のアンインストールが効かない場合がある
• volta uninstall <package> でも削除できない場合は、直接ファイルを削除する必要がある

詳細

# 通常の方法（効かないことがある）
npm uninstall -g @some/package
volta uninstall @some/package

# Volta の node_modules の場所を確認
npm root -g
# → ~/.volta/tools/image/node/<version>/lib/node_modules

# 直接削除（最終手段）
rm -rf ~/.volta/tools/image/node/<version>/lib/node_modules/@some/package

同じパッケージを pnpm と npm（Volta 管理下）の両方でグローバルインストールしてしまうと、どちらが使われるか PATH の優先順位次第で変わるため、パッケージマネージャーは1つに統一すべき。

AI 実装を自走させるための運用設計（Issue 駆動 + 単一進捗ソース）

学んだこと

• 小〜中規模の個人開発では、PR を必須にしなくても Issue 駆動 + 直接コミット で十分トレーサブルに運用できる
• AI エージェントに長時間自走させる場合は、進捗の単一ソース（例: EXECUTION_STATUS.md）を用意すると、セッション再開時のロスが減る
• 自走率を上げるには、依頼文で「停止条件」を明示し、通常時は次タスクへ自動継続させるルールが有効
• レビュー品質を安定させるため、レビュー観点・モデル指定・フォールバックモデルを固定しておくとブレにくい

詳細

実運用で効いた最小セット：

1. タスクを依存関係つき Issue に分解
2. 1Issueごとに「実装 -> テスト -> レビュー -> 修正 -> close」を固定化
3. 進捗ファイルに current / next / blocked を記録
4. コミット粒度（例: 1Issue 最大3コミット）を先に決める

CLI 自動化で中断・部分実行が起きたときの安全な再開手順

学んだこと

• 自動化コマンドが中断された場合、再実行前に現在状態を検証すると重複作成や不整合を防げる
• GitHub CLI では gh auth status だけでなく gh api user を併用すると、認証と API 疎通を切り分けやすい
• 作成系コマンド（repo/issue など）は途中で成功している場合があるため、view/list で存在確認してからリトライするのが安全

詳細

再開時のチェック順序の例：

# 1) 認証・疎通の確認
gh auth status
gh api user -q .login

# 2) 作成済みか確認
gh repo view <owner>/<repo>
gh issue list --repo <owner>/<repo>

# 3) ローカル側の整合確認
git remote -v
git status --short

モバイル対応仕様は「方針」ではなく「検証可能条件」で定義する

学んだこと

• 「モバイル対応する」だけでは実装者ごとの解釈差が大きい
• ブレークポイント、最小タップ領域、最小文字サイズ、検証ビューポートを数値で固定すると、実装とレビューの判断が一致しやすい
• 横スクロールを許可する要素を明示し、それ以外は横はみ出し禁止にすると UI 品質が安定する

詳細

仕様に入れておくと有効な項目：

• 例: 320x568, 375x812, 390x844, 768x1024, 1024x768 で操作完了可能
• タップ領域最小 44x44px 以上
• 横スクロール許可要素を限定（例: 指板ビューのみ）
• prefers-reduced-motion 対応

参考リンク

• Codex MCP Interface ドキュメント - Codex の MCP サーバーインターフェース仕様（experimental）
• Codex v0.36.0 リリースノート - MCP 対応を含むリリース
• gh auth login - GitHub CLI の認証手順
• gh repo create - GitHub CLI のリポジトリ作成
• gh issue create - GitHub CLI の Issue 作成

メタ情報

• ツール: Claude Code, Codex, GitHub CLI
• 関連技術: Shell Script, API Rate Limiting, Caching, OAuth, Anthropic API, Web Scraping, SPA, MCP, OpenAI Codex CLI, pnpm, Volta, npm, GitHub Issues, gh CLI, AI Workflow Design, Mobile-First UI Spec