codese
プロダクト
WIKI
開発日記
Sukenobu
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-10
AIにテストを任せるなら実行と判定を分ける
AIエージェントにE2Eテストを書かせて実行させると、テスト側の不備をアプリの不具合と取り違えたり、期待値をアプリの動きに合わせたりする。実行役と判定役を分け、期待値を先に固定し、差し戻しの理由を積み上げるための手順。
2026-09-12
伸び止まりを前提に組む
モデルの性能が上がり続ける前提で運用を組むと、性能が横ばいになった瞬間に打つ手が無くなる。同じモデルから同じ結果を繰り返し出すためにこのリポジトリで実際に効いた仕掛けと、効かなかった指示のまとめ。
2026-09-20
エージェント制御
鍵を渡さない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-26
MCPツール反映漏れ
openclaw経由でMCPサーバーにツールを追加しても、稼働中のエージェントには反映されない。toolFilter.includeを書き換えただけで放置すると、エージェントは新しいツールを『無いもの』として扱い、しかも実行していない操作を『やった』と報告することがある。openclaw mcp reloadで作り直す手順と、実行結果をsha256で確かめる方法。
2026-09-29
トラブル対処
エージェントが止まるとき
自律エージェントに長い作業を任せたとき、実行できなかった検証を成功扱いさせないための指示の書き方と、実際に踏んだ環境エラーの切り分け。
2026-08-30
SSE再接続を止める
開いた直後に閉じるSSE接続が再試行を繰り返すとき、接続成功と継続可能な応答を分けて調べ、未対応の要求を速く終える手順。
2026-09-05
worktreeで分ける
共有ルートに未コミット変更があるとき、既存作業を動かさずに専用worktreeへ分離し、差分の所属を最後まで保つ手順。
2026-09-07
PDFのフォント欠落
PDFに埋め込む日本語フォントに字形がない文字は、エラーも警告も出ずに「☒」で出力される。丸数字・△・※・□・全角チルダの置き換え表と、ソースの文字列をフォントと照合して再発を防ぐテストの作り方。
2026-10-04
02
実装
Next.js
デザインを実装に落とす
/design で決めたトップページを実際のNext.jsに落とすまでの手順。何を先に決めると手戻りが減るか。
2026-08-29
デプロイ
公開されたか確かめる
マージしただけでは本番へ反映されない構成で、記事やページが実際に公開されたかを確かめる手順。本番URL・画像の実体・sitemapの3点をどの順で見るか、突き合わせをどこまで自動にするか。
2026-09-05
03
技術スタック
ブラウザ内AI
ブラウザ内でAIを動かす
サーバへ送らずに端末側で推論する構成。ONNX Runtime Web + WebGPU と WebLLM を2つのプロダクトで使った記録。
2026-08-29
データストア
データストアの使い分け
Supabase・Turso・Vercel Blob を3つのプロダクトでどう使い分けているか。選んだ理由と、無料枠で運用するための制約。
2026-09-09
SQLiteを1経路で作る
中継のクラウドDBを挟まず、データレイクからSQLiteファイルを直接生成する構成の手順と注意点。マイグレーションの適用先が抜けたときの症状、0件で静かに完了する破損の防ぎ方、ゼロから作り直すときのコマンド。
2026-09-09
RLSとアプリ側の絞り込み
Supabaseの行レベルセキュリティを使うテーブルで、アプリ側にも同じ絞り込みを書いたときに起きること。二重条件の落とし穴と、実ポリシー越しに検証するテストの置き方。
2026-09-02
Advisor警告の潰し方
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の土台
準備中