エージェントスキルの「知識」と「ロジック」を分離してreferencesに蓄積する

写真現像エージェントで「ペットポートレートは5500K推奨」のようなドメイン知識をスキルのプロンプトに直書きしていたが、知識が増えるたびにプロンプトが肥大化する問題があった。

仕組み:

• スキルのプロンプト（ロジック層）には「referencesを読んで過去の好みを参考にせよ」とだけ書く
• ドメイン知識は references/ ディレクトリにファイルとして蓄積する
• フィードバック結果から自動で新しいリファレンスを追加・更新する

skills/
  arw-improve/
    SKILL.md          # ロジック: 手順と判断基準
    references/
      wb-preferences.md   # 知識: シーン別WB傾向
      exposure-tips.md     # 知識: 露出調整の学び

やってみてどうだったか:

• スキルのプロンプトが安定する。知識が増えてもロジック部分は変わらない
• リファレンスはフィードバックのたびに追記されるので、使うほど精度が上がる
• 知識が構造化されているのでエージェントが「似たシーンの過去実績」を引きやすい
• 逆に、リファレンスが増えすぎるとコンテキストを圧迫するので、定期的に要約・統合する仕組みも必要になりそう

スケジュールタスクで開発作業を自動駆動する

AIエージェントの実装作業をスケジュールタスクとして登録し、バックログから自動的にissueを拾って実装→PR作成まで走らせるパターン。人間はレビューとフィードバックに集中できる。

仕組み:

• story-dev スキルをスケジュールタスクとして登録。定期的に自動起動
• 起動するとバックログからReady状態のissueを1件選び、worktreeを作って実装し、PRを作成
• PRのCI（テスト、スクリーンショット差分等）が落ちたら、ユーザーが結果を伝えて修正を指示

scheduled-task (story-dev)
  → Ready issue を選択
  → worktree 作成
  → 実装 + テスト
  → PR 作成
  → CI結果待ち → 必要に応じてfix

1日で7件のissue（ラベルCRUD、ブロッカー管理、タイムライン、フィールドエラー表示、オーナー管理等）をこのフローで処理できた。

やってみてどうだったか:

• issueに ## Plan / DoD / verify を事前に整備しておくと、エージェントが迷わず実装に入れる。issue品質が開発速度に直結する
• CI失敗時の修正は人間がエラー内容を伝えるだけでよく、修正自体はエージェントが行う。「テストとスクリーンショット差分が落ちています」のような一言で十分
• 複数issueを直列でこなすので、途中のissueで入れた変更が次のissueのベースになる。ブランチ戦略（前のPRからブランチを切る等）の考慮が必要

AIの提案精度をフィードバックループで育てる

AIに創作パラメータ（写真の現像設定、デザインのトーン等）を提案させるとき、一発で好みに合うことは少ない。提案→評価→学習のループを仕組みとして組み込むと、回を重ねるごとに精度が上がる。

仕組み:

1. 提案スキル — 過去のリファレンスを全読みしてからパラメータを生成する。リファレンスがなければ一般的なベストプラクティスで提案
2. 適用 — 提案されたパラメータをツール（darktable-cli等）で適用し、結果を出力
3. フィードバックスキル — ユーザーが5段階評価 + 良かった点/改善点/好みの方向性をテキストで入力
4. リファレンス蓄積 — フィードバックを「学び」として抽象化し、references/ ディレクトリにMarkdownで保存。シーンタイプ・条件等のタグ付き

/propose → params.json → /apply → output
                                     ↓
                               /feedback → references/ に蓄積
                                     ↓
             次回の /propose で references/ を参照 ←─┘

ポイントは、フィードバックを生のスコアではなく抽象化された学びとして保存すること。「この写真にはexposure +0.5が良かった」ではなく「暗所の室内写真ではシャドウの持ち上げが効果的」のように、別のシーンにも転用できる形にする。

やってみてどうだったか:

• スキルの references/ をコンテキストとして読むだけなので、ベクトルDB等の追加インフラが不要。ファイルベースで十分機能する
• フィードバックのフォーマットを揃えておくと、AIが傾向を読み取りやすい
• 数回のフィードバックで「彩度はカメラJPEG並みにほしい」「シャドウの持ち上げは効果的」等の好みが反映されるようになった

darktable-cliでRAW現像を自動化してみた

RAWファイルにAI提案のパラメータを自動適用したくて、CLIからRAW現像できるツールを検討した。選択肢はdarktable-cli、rawtherapee-cli、Rust(libraw-rs)の3つ。darktable-cliを採用した。

使ってみた感想:

• 良かった点 — darktable-cli input.ARW output.jpg --xmp sidecar.xmp の一行で、露出・コントラスト・ハイライト/シャドウ・シャープネス・NR・カラーグレーディング等の全パラメータを適用してJPEG出力できる。GUIなしのヘッドレス動作なのでCI/スクリプトに組み込みやすい
• 気になった点 — XMPのパラメータ形式がdarktable独自のバイナリエンコーディング（C構造体をhexエンコード）で、プログラムからXMPを生成するのが一手間。Lightroom互換のXMLベースではない
• 向いている場面 — AIや機械学習で現像パラメータを提案し、結果をプレビューするパイプライン。人間がGUIを操作せずにRAW→JPEG変換を回したいケース

代替案との比較:

• rawtherapee-cli — PP3プロファイル形式でテキストベースなので生成しやすいが、パラメータ体系が独自
• libraw-rs (Rust) — WB・露出・明るさの4パラメータ程度しかカバーできず、コントラストやトーンカーブは自前実装が必要。RAW現像の本領を発揮するには不足
• darktable-cli — パラメータ網羅性が圧倒的。XMP生成の手間はPythonスクリプトで吸収できる

# macOSでのパス例
/Applications/darktable.app/Contents/MacOS/darktable-cli \
  input.ARW output.jpg \
  --xmp sidecar.xmp \
  --width 2048 --height 2048

refs: https://docs.darktable.org/usermanual/4.8/en/special-topics/program-invocation/darktable-cli/

PreToolUse hookでAIエージェントの望まないコマンドパターンを禁止する

Claude Codeのエージェントがバックグラウンドタスクの完了を sleep && grep でポーリングし始めた。許可プロンプトが出るたびにユーザーが判断する必要があり、作業の邪魔になる。

PreToolUse hookを設定すると、特定のコマンドパターンをエージェントが実行する前にブロックできる。

// .claude/settings.local.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'sleep.*grep'; then echo 'BLOCK: sleep+grep polling is not allowed' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

仕組み:

• PreToolUse はツール実行前に発火するフック
• matcher でツール名を指定（Bash でシェルコマンドを対象に）
• exit code 2 でツール実行をブロックし、エラーメッセージがエージェントに返る
• エージェントは別のアプローチを試みるようになる

ポーリング以外にも、rm -rf や git push --force など危険なパターンの防止に使える。エージェントの行動を事後チェックでなく事前にゲートする仕組みとして便利。

refs: https://docs.anthropic.com/en/docs/claude-code/hooks

AIエージェントでプラクティスのギャップ分析→バックログ自動追加を行う

開発ツールやCI/CD周りのベストプラクティスを定期的に棚卸ししたいが、手動だと「何が足りないか」のリストアップだけで時間が溶ける。AIエージェントに既存構成の分析→Web上のプラクティスとの比較→不足分のIssue化までを一気通貫で任せてみた。

仕組み:

• エージェントにリポジトリの既存構成（スキル一覧、CI設定、フック設定等）を読ませる
• 「未適用のプラクティス」をWeb検索も交えてリストアップさせる
• 既存バックログとの重複チェックを行い、新規分だけIssue化する

# エージェントへの指示（概要）
1. ハーネスエンジニアリングにおいて、未適用のプラクティスを調べてリストアップ
2. 既存バックログと重複するものは除外
3. 残りをIssue化する

やってみてどうだったか:

• 24スキル・6スケジュールタスク・3レビューエージェントの構成を分析し、5件の未適用プラクティスを特定してくれた
• 既存バックログ（4件）との重複除外も正しく動いた
• 「エージェントが知っているベストプラクティス」の範囲に依存するので、ドメイン固有のプラクティスは拾えない。汎用的なプラクティス（セキュリティ監査、PR自動レビュー等）の漏れ検出に向いている
• 定期実行（週次・月次）にすると、ツールのアップデートで新しく使えるようになったプラクティスも拾える可能性がある

CSS columnsで手軽にMasonryレイアウトを実現する

カード一覧をMasonryレイアウト（Pinterest風の段違いグリッド）にしたいとき、CSS columns プロパティで簡単に実現できる。JavaScriptライブラリなしでレスポンシブ対応もできる。

.masonry-grid {
  columns: 3 300px; /* 最大3列、1列の最小幅300px */
  column-gap: 1rem;
}

.masonry-grid > * {
  break-inside: avoid; /* カードが列をまたがないようにする */
  margin-bottom: 1rem;
}

Tailwind CSSなら columns-3 と break-inside-avoid だけで済む。

<div class="columns-1 sm:columns-2 lg:columns-3 gap-4">
  <div class="break-inside-avoid mb-4">カード1（高さ可変）</div>
  <div class="break-inside-avoid mb-4">カード2</div>
  <div class="break-inside-avoid mb-4">カード3</div>
</div>

注意点:

• CSS columnsは上から下に流れるので、並び順がグリッドと異なる（左→右ではなく上→下→次の列）
• カード高さが固定の場合はMasonryにする意味が薄い。コンテンツの高さがバラつくときに効果的
• break-inside: avoid を忘れるとカードが列の境界で分断される

Cloudflare D1のテスト環境はCREATE TEMP TABLEを拒否する

D1のテスト環境（miniflare）でマイグレーションSQLを実行したら SQLITE_AUTH エラーになった。原因は CREATE TEMP TABLE 文。

D1はSQLiteベースだが、セキュリティポリシーで一部のSQLite機能を制限している。CREATE TEMP TABLE はその一つで、テスト環境でもプロダクション環境でも使えない。

マイグレーションで一時テーブルが必要な場合の代替手段:

1. 通常テーブルを使って最後にDROPする — CREATE TABLE tmp_xxx → 処理 → DROP TABLE tmp_xxx で同じことができる
2. CTEやサブクエリで完結させる — 一時テーブルなしで書き換え可能なケースも多い

-- NG: D1では SQLITE_AUTH エラー
CREATE TEMP TABLE migration_data AS SELECT ...;

-- OK: 通常テーブルを使って最後にDROP
CREATE TABLE migration_data AS SELECT ...;
-- ... 処理 ...
DROP TABLE migration_data;

lefthookで既存マイグレーションファイルの変更をブロックする

AIエージェントにDB機能の実装を任せたら、既存のマイグレーションファイルを直接書き換えてしまった。CREATE TEMP TABLE → CREATE TABLE のような「テストを通すための修正」をマイグレーションに入れてしまうパターン。マイグレーションファイルは一度適用したら変更禁止が鉄則なので、ハーネス（ガードレール）として仕組み化した。

仕組み:

• lefthookのpre-commitフックで、既存マイグレーションファイルがstagingされていたらエラーにする
• CLAUDE.mdにルールを明記して、AIがそもそも編集しないよう指示する
• 新規マイグレーションの追加は許可、既存ファイルの変更のみブロック

# hook-migration-guard.sh の要点
MIGRATION_DIR="migrations"
CHANGED=$(git diff --cached --name-only -- "$MIGRATION_DIR/" | while read f; do
  git show "HEAD:$f" 2>/dev/null && echo "$f"  # HEADに存在する = 既存ファイル
done)
if [ -n "$CHANGED" ]; then
  echo "ERROR: 既存マイグレーションファイルの変更は禁止です"
  exit 1
fi

やってみてどうだったか:

• lefthookフックは人間・AI両方に効くので、CLAUDE.mdだけに頼るより確実
• 「テストを通すためにマイグレーションを変える」というAIの判断は合理的に見えるので、ルール明記だけだと突破されがち。仕組みでブロックするのが大事
• 次はCI側にも同様のチェックを入れたい