AI Session Notes - 2026-03-07

AI協業でのセッションノート運用: 抽出対象の線引き

学んだこと

AIが自律的に遭遇・解決した問題をセッションノートに含めると、ユーザーにとって文脈のない知識になり追いきれなくなる
セッションノートの抽出対象は「ユーザーの発言がトリガーになっているか？」で判断するとシンプルに線引きできる
ユーザーが疑問を投げかけて -> 会話の中で一緒に解決したトピックのみが、後から読み返して意味のあるノートになる
技術知識だけでなく、プロセス改善やワークフローの知見もセッションノートの対象として有効

詳細

AIコーディングツールとの協業では、AIが自律的にテスト修正やレビュー指摘対応を行うことが多い。これらは作業ログとしては有用だが、ユーザーが関与していない解決過程の知見をノートに残しても、背景が分からず読み返せない。

判断基準をスキル定義に明記しておくことで、抽出時のブレを防げる:

OK: ユーザーが質問・課題提起 -> 解決過程で得た学び
OK: ユーザーとAIが対話して改善したプロセス・ルール
NG: AIがビルドエラーに遭遇して自分で修正した
NG: AIがテスト失敗を検知して自分でモック設定を調整した
NG: AIがレビュー指摘を受けて自分でリファクタリングした

SPAのルーティング設計と History API の使い分け

学んだこと

path routing は自然な URL を作れるが、ディープリンクやリロードを成立させるには配信側で unknown path -> index.html の SPA fallback が必要になる
hash routing は URL はやや不自然でも、ホスティング側の rewrite 設定を触れないときの実用策として今も有効
URL は問題番号や一時状態ではなく、安定した「機能入口」を表す方が扱いやすい場合がある
通常遷移は pushState、不正 URL の補正は replaceState と使い分けると、戻る操作で履歴ループを起こしにくい

詳細

単一ページアプリで「直接URLアクセスしたい」という要件が出たときは、まず hash と path の違いを配信要件込みで整理すると判断しやすい。

hash はフロントエンドだけで完結しやすく、静的配信でも壊れにくい
path は URL が自然だが、ホスティング側が存在しない path でも index.html を返せる必要がある

また、クイズや設定画面のような機能では、URL を細かい進行状態に合わせるよりも、/feature のような入口 path に固定し、内部状態として 設定 -> 開始 -> 結果 を進める方が UX と実装の両方で安定しやすい。

SPAの不具合調査では stale な開発サーバも先に疑う

学んだこと

SPA で「直接URLアクセスは正しいのに、ボタン遷移だけ変だ」と見える場合、コードバグの前に dev server やコンテナが最新コードを見ているか確認するとよい
Docker 経由の開発環境では、再起動前の bundle やキャッシュを見ていてルーティングバグに見えることがある
make down -> make up のような再起動で再現が消えるなら、まず実装ではなく実行中プロセスの状態差分を疑うべき

詳細

ルーティングや画面遷移の不具合は、実装上の state 遷移だけが原因とは限らない。とくに Vite などの開発サーバをコンテナ越しに動かしている場合は、ホットリロードの取りこぼしや古い bundle の参照で、UI だけが過去の状態に見えることがある。

そのため、以下の順で切り分けると無駄が少ない。

直アクセスとボタン遷移の両方を比較する
実行中コンテナや dev server が最新コードを見ているかを確認する
再起動で解消するかを試す
それでも再現する場合に初めて実装バグを深掘る

Web 楽器音の段階的改善とサンプル音源のライセンス判断

学んだこと

ブラウザで楽器っぽい音を改善したいときは、最初からサンプル音源に行かず、まず合成音で方向性を作ると軽く進めやすい
物理モデル寄りや pluck 系の synth は、「今より少し楽器らしくしたい」段階の改善に向いている
サンプル音源は音のリアリティを上げやすい一方で、容量管理・初期化・再配布ライセンスの確認コストが増える
「royalty-free」や「商用利用可」は、そのままアプリ同梱・再配布可を意味しないため、利用規約は再配布観点で別途確認が必要

詳細

Web Audio 系の機能では、リアルさと実装コストのバランスを段階的に取るのが有効だった。

第1段階: synth ベースで音の立ち上がりや減衰を改善する
第2段階: 必要ならサンプル音源へ進む

この順にすると、まず UX 改善を素早く確認できる。サンプル音源を使う段階では、音質だけでなくライセンス、配布方法、アセットサイズ、ロード戦略まで合わせて判断する必要がある。

主観評価が必要な音色調整は独立ハーネスで比較すると速い

学んだこと

音色の良し悪しのような主観評価が必要な調整は、本体アプリに直接入れ替え続けるより、独立した比較用ページで同じフレーズを聞き比べる方が判断しやすい
低音域の聞こえ方を調べたいときは、コード全体ではなく 5弦・6弦のような対象帯域だけを抜き出したフレーズを用意すると差分が分かりやすい
低音は「音量」だけでなく、ローパス、胴鳴りのピーク、減衰時間、アタックの組み合わせで 太さ と 音程の分かりやすさ の両方が変わる
ノートPCやスマホのスピーカーでは低音の半音差が知覚しづらいため、低音強調と輪郭維持はトレードオフとして扱う必要がある

詳細

音色調整では、同じコードやフレーズを異なるプリセットで即座に再生できる小さなハーネスを先に作ると、方向性の合意が速くなる。これは視覚調整でデザインカンプを先に作るのと同じで、実装本体のコードを何度も書き換えずに済む。

特に低音域は、コード全体で聞くと後続の高音弦にマスクされやすく、「本当に変わったか」が分かりにくい。そういう場合は 5弦・6弦の音だけを単独フレーズとして比較し、違いが見えたあとで全体コードに戻すと、判断精度が上がる。

用語メモ: stale と独立ハーネス

学んだこと

stale は「古いまま」「最新が反映されていない」という意味で、コードではなく実行中の開発サーバやキャッシュが古い状態を指すことがある
独立ハーネス は、本体とは別に切り出した比較・検証専用の小さな実験環境を指す
UI や音のような主観評価が必要な調整では、本体の画面を何度も触るより独立ハーネスを先に作る方が比較しやすい

詳細

stale は、ソースコード自体は直っていても、ブラウザや dev server やコンテナが古い bundle や古い状態を見ているために「まだ直っていないように見える」状態を表す。とくに SPA の開発では、ルーティング不具合のように見えても、まず実行中プロセスが最新コードを見ているかを確認すると切り分けが速い。

独立ハーネス は、比較や実験のためだけに切り出した専用環境を意味する。たとえば音色比較のために、本体アプリとは別の簡単な HTML やスクリプトを用意して、同じフレーズを複数プリセットで再生できるようにする。これにより本体ロジックを何度も差し替えずに、差分の評価だけに集中できる。

長い CLI 本文はファイル経由で渡すと安定しやすい

学んだこと

CLI に長い複数行本文を直接埋め込むと、シェル quoting や実行環境側の解釈差分で不安定になりやすい
一時ファイルに本文を書き出し、--body-file のようなオプションで渡すと、コマンド自体が単純になり失敗要因を減らせる
サンドボックスや承認付き実行のある環境では、引数構造を単純にした方が通しやすい場合がある

詳細

マルチライン文字列をそのままコマンド引数に埋め込む方法は便利だが、引用符・改行・シェル拡張・実行ラッパーの扱いが絡むと壊れやすい。長文を扱う CLI では、本文を先にファイル化し、CLI 側の --body-file や --file 系オプションを使う方が、再現性と可搬性が高くなる。

AIレビューCLIではモデル指定を実行コマンドに明示する

学んだこと

AIレビューCLIで高品質モデルを使う方針を文書やメモに書くだけでは不十分で、実行コマンド側でも model=... を明示しないと確実なモデル選択にならない
--uncommitted のようにレビュー対象をコミット前差分へ限定すると、品質ゲートとしてのレビュー範囲がぶれにくい
fallback model は 1 回のコマンドに自動で付く機能ではなく、失敗時に別モデルで再試行する運用ポリシーを指すことがある
reasoning effort のような追加設定を明示すると、レビューの深さを一定に保ちやすい

詳細

CLI ベースのレビュー運用では、レビューで使いたいモデル、実際に実行したコマンド、失敗時の再試行ポリシー を分けて考えると誤解が減る。たとえば「高品質モデルを使う」とプロンプトや運用文書に書かれていても、実行コマンドにモデル指定がなければ、実際にどのモデルで動いたかは曖昧になりやすい。

そのため、レビュー用途では次の 3 点を明示すると確認しやすい。

レビュー対象範囲: 例 --uncommitted
使用モデル: 例 model=...
推論の深さ: 例 reasoning effort = high

また、fallback model は「同じコマンドの中で自動的に切り替わる」という意味ではなく、「指定モデルで失敗したら、別モデル指定で再実行する」という運用ルールである場合がある。実際の自動フォールバック可否は、ツールの仕様と実行方法を分けて確認する必要がある。

参考リンク

MDN: Hash routing - hash routing の位置づけ
MDN: Working with the History API - pushState と replaceState の基礎
Tone.js PluckSynth - pluck 系 synth の仕様
Creative Commons CC0 FAQ - CC0 の扱いと attribution 要否

メタ情報

ツール: Claude Code, Codex
関連技術: AI協業プロセス, セッションノート運用, SPA routing, History API, Docker, 開発サーバ, Web Audio, 音色設計, UXプロトタイピング, 用語整理, Tone.js, ソフトウェアライセンス, GitHub CLI