Wiki

WIKI

AIエージェントを使った開発で、実際に踏んだ挙動と対処をまとめています。公式ドキュメントの要約ではなく、手元で確認したことだけを書いています。

01

Claude Code

デザイン

/design でUIを作るClaude Code に入った /design スキルの使い方。アートボードとキャンバスの考え方、指示の出し方、実際に使って分かった向き不向きをまとめる。2026-08-29

プロンプト

指示書を1本にするClaude CodeのCLAUDE.mdとCodexのAGENTS.mdを1つの実体に寄せ、実行主体によって守られるルールが変わる事故を止める手順。シンボリックリンクと複製+点検の使い分けまで。2026-09-10制約がツールを封じるAIエージェントに出す禁止事項が、そのエージェントの持つツールを無効化して結果を悪化させることがある。出力形式の指定がツール選択を兼ねてしまう仕組みと、結果が悪いときに指示の精度ではなく制約そのものを疑うための切り分け手順。2026-09-10AIにテストを任せるなら実行と判定を分けるAIエージェントにE2Eテストを書かせて実行させると、テスト側の不備をアプリの不具合と取り違えたり、期待値をアプリの動きに合わせたりする。実行役と判定役を分け、期待値を先に固定し、差し戻しの理由を積み上げるための手順。2026-09-12伸び止まりを前提に組むモデルの性能が上がり続ける前提で運用を組むと、性能が横ばいになった瞬間に打つ手が無くなる。同じモデルから同じ結果を繰り返し出すためにこのリポジトリで実際に効いた仕掛けと、効かなかった指示のまとめ。2026-09-20歌入りAI曲の再現レシピ音楽生成モデルACE-Stepで、日本語の歌入りの曲を作るときの条件(プロンプト・歌詞・seed・guidance・steps・EQ)の表。当たりの探し方、SHA-256で再現を確かめる手順、簡易BPM推定の読み方、仕上げのEQ e1の定義を、手元の15曲で確かめた値つきで残す。2026-10-28

エージェント制御

鍵を渡さないpush設計自律エージェントにGitHubの鍵を渡さず、実装はコンテナ、pushはホストの固定スクリプトに分ける型。合図のファイル1枚とlaunchdのQueueDirectoriesでつなぐ。検査の順番と、一時ジョブで実測した起動の挙動。2026-10-04ガードが素通りする書き方自律エージェントの手前に置いた検査と止め方が、効いていなかった3つの実例。grepへのパイプ、git statusの未追跡ディレクトリ、launchdに届かない環境変数。再現の出力と直し方、ガードを壊して確かめる手順。2026-09-24署名付きURLで鍵を隠すエージェントに動画をcurlで取らせたいが、親トークンはシェルへ渡したくない。ジョブ・ショット・期限に紐づくHMAC署名付きURLを15分だけ発行する型。検証の順番と、改ざん6通りが401になる実測。2026-09-26MCPツール反映漏れopenclaw経由でMCPサーバーにツールを追加しても、稼働中のエージェントには反映されない。toolFilter.includeを書き換えただけで放置すると、エージェントは新しいツールを『無いもの』として扱い、しかも実行していない操作を『やった』と報告することがある。openclaw mcp reloadで作り直す手順と、実行結果をsha256で確かめる方法。2026-10-28auto判定とローカルLLMClaude Codeのautoモードは、Bashを実行するたびに判定役のモデルへ要求を送る。判定役の宛先が環境変数でローカルLLMに向くと、読み込みが60秒に間に合わず「判定できない」で止まる。宛先の決まり方、60秒で読める量の見積もり、ログでの見分け方、manualへの切り替えを、ミニ(Mac mini)のOllamaで確かめた値つきで残す。2026-10-23

トラブル対処

エージェントが止まるとき自律エージェントに長い作業を任せたとき、実行できなかった検証を成功扱いさせないための指示の書き方と、実際に踏んだ環境エラーの切り分け。2026-08-30SSE再接続を止める開いた直後に閉じるSSE接続が再試行を繰り返すとき、接続成功と継続可能な応答を分けて調べ、未対応の要求を速く終える手順。2026-09-05worktreeで分ける共有ルートに未コミット変更があるとき、既存作業を動かさずに専用worktreeへ分離し、差分の所属を最後まで保つ手順。2026-09-07PDFのフォント欠落PDFに埋め込む日本語フォントに字形がない文字は、エラーも警告も出ずに「☒」で出力される。丸数字・△・※・□・全角チルダの置き換え表と、ソースの文字列をフォントと照合して再発を防ぐテストの作り方。2026-10-04OpenClawの切り分けOpenClawが動かないとき、どの層で起きているかを先に決める手順。無反応、生成が止まらない、ツール呼び出しの途中停止、報告のずれ、PRにならない、の5症状について、見るコマンドと原因、効いた直し方を残す。Mac miniにコンテナで置いた構成で、実際に踏んだものだけ。2026-10-23bash 3.2の変数と日本語macOS標準のbash 3.2で、変数の直後に日本語を書くと、変数が空になり日本語も壊れる。UTF-8のロケールで起き、ASCII以外のすべての文字が対象になる。set -uを付けても、ヒアドキュメントの中では止まらない。実際に再現した結果と、検出する静的検査、直し方を残す。2026-10-17
02

実装

Next.js

デザインを実装に落とす/design で決めたトップページを実際のNext.jsに落とすまでの手順。何を先に決めると手戻りが減るか。2026-08-29日本語パスとISRの500generateStaticParams(ISR)を書いた動的ルートで、パスに日本語などU+0100以上の文字が入ると、本番だけ全件500になる。x-next-cache-tagsに文字が入り、Node.jsのヘッダー検証が拒否する。最小アプリでの再現、4つの書き方の比較、見分け方、直し方、デプロイ直後の全件確認を残す。2026-10-21

デプロイ

公開されたか確かめるマージしただけでは本番へ反映されない構成で、記事やページが実際に公開されたかを確かめる手順。本番URL・画像の実体・sitemapの3点をどの順で見るか、突き合わせをどこまで自動にするか。2026-10-21
03

技術スタック

ブラウザ内AI

ブラウザ内でAIを動かすサーバへ送らずに端末側で推論する構成。ONNX Runtime Web + WebGPU と WebLLM を2つのプロダクトで使った記録。2026-08-29

データストア

データストアの使い分けSupabase・Turso・Vercel Blob を3つのプロダクトでどう使い分けているか。選んだ理由と、無料枠で運用するための制約。2026-09-09SQLiteを1経路で作る中継のクラウドDBを挟まず、データレイクからSQLiteファイルを直接生成する構成の手順と注意点。マイグレーションの適用先が抜けたときの症状、0件で静かに完了する破損の防ぎ方、ゼロから作り直すときのコマンド。2026-09-09RLSとアプリ側の絞り込みSupabaseの行レベルセキュリティを使うテーブルで、アプリ側にも同じ絞り込みを書いたときに起きること。二重条件の落とし穴と、実ポリシー越しに検証するテストの置き方。2026-09-02Advisor警告の潰し方Supabase の Security Advisor が出す大量の警告を、画面ではなくSQLで出所と危険度に切り分ける手順。function_search_path_mutable と extension_in_public の扱い、拡張をextensionsスキーマへ移すときの注意点。2026-09-04取消は追記、削除じゃない監査目的でレコードを物理削除せず「取消リビジョンの追記」で表現する設計のとき、一覧・件数クエリ側でそのリビジョン種別を除外し忘れると、書き込みは成功しているのに画面から消えない。Supabaseでの除外クエリの書き方と、抜けを踏んだ箇所を洗い出す手順。2026-09-15

配信基盤

配信基盤の使い分けVercel と Cloudflare Pages を4つのプロダクトでどう使い分けているか。無料枠の上限に当たったときに何が起きるかまで。2026-08-29

UIの土台

準備中