Zero-Shot Log

Codex の experimental な Hooks を有効化して活用する

Sun, 22 Mar 2026 12:00:00 GMT

TL;DR

Codex には「under development」（開発中）ステータスの Hooks 機能があり、codex features enable codex_hooks で有効化できる
対応イベントは SessionStart / UserPromptSubmit / Stop の3つ

はじめに

本記事の内容は Codex v0.115.0（2026年3月時点）で検証しています。開発中の機能のため、今後のバージョンで仕様が変更される可能性があります。

Codex には公式にはまだ Hooks 機能がありません。公式ドキュメントにも記載はなく、Changelog に「experimental hooks engine」という一行が載っている程度です。

ところが、実は「under development」ステータスで すでに動く Hooks が実装されています。codex features list を実行してみたところ codex_hooks というフィーチャーフラグが見つかり、有効化すると実際にフックが発火することを確認しました。

ただし設定の JSON 構造や対応イベントの詳細はどこにも書かれていないため、OSS として公開されている openai/codex リポジトリ（Apache License 2.0）の Rust ソースコード（codex-rs/hooks/）を読んで仕様を特定しました。本記事ではその調査結果をまとめます。

1. 発見と有効化

フィーチャーフラグの確認

Codex には codex features list というフィーチャーフラグの一覧を表示するコマンドがあります。Hooks の存在を知ったのもこのコマンドがきっかけで、実行してみたところ codex_hooks が「under development」として表示されました。

$ codex features list
codex_hooks    under development  false

デフォルトは無効です。

有効化

# config.toml に永続化される
codex features enable codex_hooks

有効化すると起動時に以下の警告が表示されます。

⚠ Under-development features enabled: codex_hooks. Under-development features are incomplete
  and may behave unpredictably.

2. 設定ファイル

ファイルパスと形式

項目	値
グローバル設定	`~/.codex/hooks.json`
プロジェクト設定	`<project>/.codex/hooks.json`
形式	JSON

Codex の一般設定は ~/.codex/config.toml（TOML 形式）ですが、Hooks 設定は hooks.json（JSON 形式） という別ファイルです。config.toml に hooks を書いても読まれません。

~/.codex/
├── config.toml      ← 一般設定・feature flags
└── hooks.json       ← hooks 設定（JSON）

JSON 構造

構造がやや独特で、イベント名の配列にハンドラを直接並べるのではなく、一段ラッパーを挟む必要があります。ソースコード（codex-rs/hooks/src/engine/config.rs）では MatcherGroup という構造体で定義されており、matcher（正規表現フィルタ）と hooks（ハンドラ配列）を持ちます。

hooks.<EventName>[].matcher  → フィルタ条件（省略可）
hooks.<EventName>[].hooks[]  → 実行するハンドラの配列

具体的な JSON は以下のようになります。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'session started'",
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'session stopped'",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

timeout はオプションで、デフォルトは600秒です。

動かない書き方

この入れ子構造を知らずに、イベント配列に直接ハンドラを並べる書き方をすると動きません。

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo 'session started'"
      }
    ]
  }
}

実際にこの書き方で動かず、ソースコードを読んで入れ子が必要なことに気づきました。公式ドキュメントがないため、ソースコードが唯一の正確な情報源です。

3. 対応イベント

サポートされている3イベント

イベント	発火タイミング
`SessionStart`	セッション開始・再開時
`UserPromptSubmit`	ユーザーがプロンプトを送信した時
`Stop`	エージェント応答完了時

ツール実行やサブエージェント関連のイベントは未実装です。

ハンドラタイプ

ハンドラタイプは「フックが発火したときに何を実行するか」の種類です。ソースコード（codex-rs/hooks/src/engine/config.rs）上は command・prompt・agent の3タイプが定義されていますが、現時点で実際に動作するのは command（シェルコマンド実行）のみです。

タイプ	内容	状態
`command`	シェルコマンドを実行する	動作する
`prompt`	エージェントのコンテキストにプロンプトを注入する	未実装（`"skipping prompt hook"` とログに表示される）
`agent`	別のエージェントを起動して処理させる	未実装

async: true（非同期実行）も定義はありますが未実装です。prompt が使えるようになれば「プロンプト送信時に毎回追加の指示を注入する」、agent なら「応答完了後に別のエージェントでレビューを走らせる」といった使い方が考えられますが、現状は「イベント発火 → シェルコマンド実行」の一択です。

stdin に渡される JSON ペイロード

hook コマンドは $SHELL -l -c "<command>" で実行され、stdin に JSON ペイロード が渡されます。

{
  "session_id": "019d07b0-...",
  "cwd": "/Users/user/project",
  "hook_event_name": "SessionStart",
  "model": "o3-pro",
  "permission_mode": "default",
  "source": "startup",
  "transcript_path": null
}

フィールド	説明
`session_id`	セッションID（UUID v7）
`cwd`	作業ディレクトリ
`hook_event_name`	イベント名
`model`	使用中のモデル
`permission_mode`	承認ポリシー
`source`	開始種別（SessionStart のみ）
`transcript_path`	会話履歴ファイルのパス（現状 null）

イベントごとに追加されるフィールドがあります。

フィールド	イベント	説明
`source`	SessionStart	`startup` / `resume` / `clear`
`prompt`	UserPromptSubmit	ユーザー入力テキスト
`turn_id`	UserPromptSubmit / Stop	会話ターンの識別子
`last_assistant_message`	Stop	最後のアシスタント応答
`stop_hook_active`	Stop	Stop フックがアクティブか

session_id、cwd、hook_event_name、model、permission_mode は全イベント共通です。

4. 活用事例: 複数エージェントセッションの一元管理

自作のデスクトップアプリで、AI コーディングエージェントの Hooks を利用して複数セッションの状態を一元管理しています。SessionStart / Stop イベントを受け取ってセッション一覧を更新する仕組みです。

Codex でもこの Hooks が使えることがわかったので、同じアプリで Codex のセッションも管理できるように拡張しました。

hooks.json で何を設定しているか

hooks.json にイベントとコマンドを書いておくと、そのイベントが発火したときにコマンドが実行されます。逆に言うと、hooks.json が空だったり存在しなければ、フィーチャーフラグを有効にしても何も起きません。

以下の設定例では、全イベントで同じことをしています。stdin に渡される JSON ペイロードを $(cat) で読み取り、curl で自作アプリの API にそのまま転送するだけです。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://localhost:3000/api/hook -H 'Content-Type: application/json' -d \"$(cat)\"",
            "timeout": 10
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://localhost:3000/api/hook -H 'Content-Type: application/json' -d \"$(cat)\"",
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://localhost:3000/api/hook -H 'Content-Type: application/json' -d \"$(cat)\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

受け取る側のアプリは、JSON 内の session_id と hook_event_name を見てセッションの状態を更新します。この仕組みは他のツールの Hooks とも共通なので、同じ API エンドポイントで複数のエージェントツールを一元管理できています。

5. 制限事項と今後の展望

現時点の制限

開発中ステータス: API が変更される可能性がある
イベント粒度が粗い: ツール実行単位のフックがないため、作業中のリアルタイム進捗は取得できない
command タイプのみ: prompt、agent、async タイプのハンドラは未サポート
公式ドキュメントがない: ソースコードを読まないと正確な仕様がわからない

OSS ならではの利点

制限が多い一方で、Codex は Apache License 2.0 の OSS であるため、Hooks の実装を直接ソースコードで確認できます。本記事の内容も codex-rs/hooks/src/ のソースを読んで特定したものです。仕様が不明な場合にソースコードが読めるのは大きな安心感があります。

今後の可能性

GitHub の Discussion #2150 では、Hooks 機能のリクエストスレッドに多数のコメントが寄せられており、コミュニティの関心の高さがうかがえます。今後ツールイベントの追加やハンドラタイプの拡充が期待されます。

まとめ

Codex の Hooks はまだ開発中で機能も限定的ですが、フィーチャーフラグを有効にすれば今すぐ使えます。セッションの開始・終了を検知してコマンドを実行する程度の用途であれば、十分活用できそうです。

参考

Codex Changelog - hooks engine 追加のアナウンス
openai/codex - GitHub - ソースコード（Apache License 2.0）
Discussion #2150: Hook would be a great feature - コミュニティのリクエストスレッド

Claude Code の /loop 機能を触ってみた

Wed, 11 Mar 2026 12:00:00 GMT

TL;DR

Claude Code の /loop を使うと、自然言語で定期実行ジョブを作れる
API の定期チェックや issue 監視など、開発フローの軽量な自動化に便利
自動コンパクト中は定期実行が止まるため、コンテキスト消費量を意識した間隔設計が大事

はじめに

Claude Code の /loop 機能は段階的にロールアウト中で、自分のアカウントでも使えるようになっていたので触ってみました。

1. /loop の基本

構文

/loop [間隔] <プロンプト>

間隔を省略すると デフォルト10分 で実行されます。

間隔の指定パターン（3通り）

# パターン1: 先頭に間隔を記述
/loop 5m git status を確認して

# パターン2: 末尾に "every" で記述
/loop デプロイ状況を確認して every 20m

# パターン3: 間隔なし（デフォルト10分）
/loop テスト結果を確認して

指定できる単位は s（秒）、m（分）、h（時間）、d（日）です。ただし cron の最小粒度は1分なので、秒指定は繰り上げられます。

内部の仕組み

ユーザーが /loop を実行すると、裏側では以下の3つのツールが動いています。

ツール	役割
`CronCreate`	ジョブの作成
`CronList`	ジョブの一覧表示
`CronDelete`	ジョブの削除

とはいえ、これらのツール名を直接知っている必要はありません。自然言語で十分操作できます。

「今動いてるジョブある？」 → CronList が呼ばれる
「ループ止めて」           → CronDelete が呼ばれる

このあたりの体験は正直かなり良くて、「ジョブ管理を自然言語でできる」という点だけでも触ってみる価値があると感じました。

2. 実用ユースケース

ユースケース1: API エンドポイントの定期チェック

外部 API のレスポンスを定期的にチェックして、変化があれば報告してもらうパターンです。

/loop 5m https://api.example.com/v1/status を確認して、前回と変化があれば報告して

ステータス監視やレスポンス内容の変化検知など、シンプルな API チェックに向いています。

ユースケース2: GitHub issue 監視

/loop 5m gh issue list --label "bug" で新しいissueがないか確認して、
あれば内容を分析して対応方針を提案して

issue をトリガーにした開発フローとの相性が良さそうです。たとえば、新しい issue が立ったら自動で内容を分析して対応ブランチを作る、といった使い方もできるかもしれません。

3. 自動コンパクトと間隔設計

認識しておくべきこと

/loop で情報取得系の処理を回すと、ループのたびに取得結果がコンテキストに蓄積されていきます。Claude Code では、会話履歴が長くなると古い内容を要約して圧縮する自動コンパクトが走ります（/compact で手動実行もできます）。

この自動コンパクト自体は通常の Claude Code 利用でも発生するものですが、/loop と組み合わせると少し気になる点があります。

自動コンパクト中は処理がブロックされるため、その間のloop間隔がずれる
自動コンパクト中に溜まった cron イベントが、完了後にまとめて発火することがある

特に情報取得系の処理はコンテキスト消費が大きいため、短い間隔で回すとすぐに自動コンパクトが発生しやすいようです。/loop にそこまで正確なタイミングを求めるものではないと思いますが、認識しておくと間隔設計の参考になりそうです。

間隔設計の目安

ユースケース	推奨間隔	理由
軽量チェック（`git fetch` 等）	3〜5分	コンテキスト消費が少ない
API レスポンス監視	5〜10分	レスポンスサイズによる
テスト実行	10〜30分	実行時間自体が長く、結果も大きい

間隔の設定は「どれくらいの頻度で確認したいか」だけでなく、「1回のチェックでどれくらいコンテキストを消費するか」 も意識しておくと良さそうです。

また、プロンプトに「変化がなければ『変化なし』とだけ報告して」と明記すると、無駄なコンテキスト消費を抑えられます。

/loop 5m サイトを確認して、変化がなければ「変化なし」とだけ報告して

4. Hooks との連携

問題: cron トリガーと手動入力を区別できない

Hooks と組み合わせて「cron 発火時だけ特定の処理を走らせたい」と考えるのは自然な発想です。しかし現状、UserPromptSubmit イベントのペイロードにはトリガーソースを示すフィールドがありません。

{
  "session_id": "abc123",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "送信されたテキスト"
  // trigger_source のようなフィールドはない
}

cron が自動で発火したのか、ユーザーが手動入力したのか、Hook 側では判別できません。

回避策: プレフィックス方式

プロンプトにプレフィックスを付ける ことで区別できるかもしれません。

/loop 5m [CRON] git fetch して新しいissueがあれば分析して

Hook 側では [CRON] の有無で分岐します。

# check_cron.py
import json, sys

data = json.load(sys.stdin)
prompt = data.get("prompt", "")

if "[CRON]" in prompt:
    # cron トリガーの場合の処理
    print("Cron-triggered prompt detected", file=sys.stderr)
else:
    # 手動入力の場合の処理
    pass

正式にトリガーソースフィールドが追加されるまでは、こういった方法で対処することになりそうです。

5. 制約と棲み分け

/loop の制約

制約	詳細
セッション依存	セッション（ターミナル）を閉じると全ジョブが停止する
3日間の期限切れ	ジョブは作成から3日後に自動削除される
承認プロンプト	`git push` 等の破壊的操作は確認ダイアログが出る
間隔精度	cron ベースのため最小粒度は1分。実行時間分の遅延もある
同時実行上限	1セッションあたり最大50ジョブ

GitHub Actions 等との棲み分け

この制約を踏まえると、/loop は 「軽量・一時的な自動化」 向きだと感じました。

用途	/loop	GitHub Actions / 従来 cron
数時間だけ状況を見守りたい	向いている	オーバーキル
PR のマージまで監視したい	向いている	セットアップが面倒
本番環境の継続的な監視	向いていない	こちらが適切
チーム全体で共有する自動化	向いていない	こちらが適切

個人の開発フローの中で一時的に自動化したい場面では、外部 CI/CD なしで完結する手軽さが魅力的でした。

まとめ

/loop の良いところ

手軽さ: 自然言語でジョブの作成・管理ができる
柔軟さ: API チェック、issue 監視、テスト実行など多様な用途に対応
完結性: 外部ツール不要で GitHub 操作まで自動化できそう

少し触ってみただけでも、「ちょっとした自動化を爆速で組める」便利さを感じました。間隔設計はコンテキスト消費量とセットで考えておくのが良さそうです。

参考

Claude Code Agent Teams: 既存のスキル・エージェントのナレッジ活用法

Fri, 13 Feb 2026 12:00:00 GMT

TL;DR

Agent Teamsは複数のClaude Codeインスタンスをチームとして協調動作させる仕組み。従来のサブエージェント（Task tool）とはアーキテクチャが異なる
既存のスキルやエージェント定義のナレッジをAgent Teamsで活用するには、プロンプト内でファイルパスを明示的に指定して読み込ませる必要がある（構造的な指定方法は未提供）
トークン消費はスキル方式の数倍。スキル方式で十分な作業はスキルで、並列実行の価値が明確な場合にAgent Teamsを試すのが現実的

Agent Teamsの概要

2026年2月5日、Claude Opus 4.6と同時に公開された実験的プレビュー機能です。複数のClaude Codeインスタンスが「チーム」として並列で動きます。

Claude Codeの拡張機構にはいくつかのレイヤーがあります。

スキル（Skill tool）
  └── メインセッション内で展開・実行
       └── 内部でTask toolを使うこともある

サブエージェント（Task tool）
  └── 独立インスタンスとして起動
  └── subagent_type でカスタムエージェント定義を指定可能

Agent Teams（TeamCreate + SendMessage + TaskList等）
  └── チームメイト起動 = Task tool + チーム間通信・タスク共有

従来のサブエージェントはTask toolで起動される独立インスタンスで、親→子のハブ&スポーク型です。子同士は会話できず、結果を親に返すだけ。Task toolにはビルトインで Bash / general-purpose / Explore / Plan の4タイプがあり、さらに subagent_type でカスタムエージェント定義（.claude/agents/*.md）を指定すると、定義に書かれたナレッジが自動的に読み込まれます。

Agent TeamsはこのTask toolの上にチーム間通信やタスク共有の仕組みを追加したオーケストレーション層です。チームメイト同士が直接メッセージを送り合えるのが大きな違いです。

【サブエージェント方式】
  親エージェント
    ├── Task → 子A（結果を親に返却）
    ├── Task → 子B（結果を親に返却）
    └── Task → 子C（結果を親に返却）
  ※ 子同士は会話できない。subagent_typeで定義を指定可能

【Agent Teams方式】
  Team Lead
    ├── Teammate A ←→ Teammate B
    ├── Teammate B ←→ Teammate C
    └── Teammate A ←→ Teammate C
  ※ チームメイト同士がメッセージを送り合える

なお、チームメイトも独立したClaude Codeインスタンスなので、仕組み上はTask toolでサブエージェントを呼び出せるはずです（公式の制限は「ネストチーム不可」であり、Task tool単体の利用は制限されていません）。しかし実際に試したところうまく動作しませんでした。これができれば既存のカスタムエージェント定義をそのまま活用できるので、今後の改善に期待したいところです。

以下は7人のレビュアーがtmux split panesで並列動作している様子です。

チーム全体で共有するタスクリストがあり、タスクの状態管理や依存関係の定義ができます。ブロックが解消されると空いたチームメイトが次のタスクを自律的にクレームする仕組みです。ただしファイルレベルのロック機構はないので、同じファイルへの同時書き込みには注意が必要です。

有効化と使い方

settings.jsonで有効化します。

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "auto"
}

teammateMode の "auto" はtmux内ならsplit panes、それ以外ではin-process（Shift+Up/Downで切替）を自動選択します。使い方は自然言語で指示するだけです。

このプロジェクトのPR #42をレビューするチームを作って。
3人のレビュアーをスポーンして:
- セキュリティ担当
- パフォーマンス担当
- テストカバレッジ担当
それぞれレビューして結果を報告させて。

前提として、Max 5x ($100/月) 以上のプランを推奨します。Proプラン ($20/月) では制限に達しやすいです。

既存ナレッジの活用: 自然言語プロンプトの現状

Agent Teamsを使ううえで知っておくべき点があります。

Claude Codeにはスキル（SKILL.md）やカスタムエージェント（.claude/agents/*.md）といった既存の拡張機構があります。単体セッションでは自動的に読み込まれますし、Task toolのサブエージェントでも subagent_type で名前を指定するだけで使えます。

ところが、Agent Teamsではチームメイトに「このスキルを使え」「このエージェント定義で動け」といった構造的な指定方法が現時点では提供されていません。チームメイトに既存の定義ファイルを活用させたい場合、プロンプト内でファイルパスを書いて「このファイルを読め」と自然言語で指示する形になります。

パスを細かく指定するしかない

たとえば、コードレビュー用のエージェント定義を ~/.claude/agents/ に用意しているとします。Agent Teamsでこれを活用するには、ディレクトリ構造とファイルパスをプロンプトに書き出して、各チームメイトに「どのファイルを読み、どう使うか」を伝える必要があります。

### ディレクトリ構造

~/.claude/
├── agents/                       # レビュー観点の定義
│   ├── review-architecture.md
│   ├── review-naming.md
│   └── review-frontend.md
└── knowledge/                    # 参考ナレッジ
    ├── architecture/
    │   ├── patterns.md
    │   └── anti-patterns.md
    └── naming/
        └── conventions.md

### チームメイトの読み込み手順

1. `~/.claude/agents/review-{自分の担当}.md` を読み、
   レビュー観点・出力形式を把握する
2. 定義内に参照ファイルがあれば、対応するナレッジを読み込む
3. ナレッジの内容をレビューの根拠として活用する

スキル方式やTask tool方式なら、エージェント定義のパスや読み込み順は仕組み側が処理してくれます。Agent Teamsではプロンプトの中で自分で書くしかないのが現状です。

スキル方式との比較

観点	スキル / Task tool	Agent Teams
エージェント定義の指定	`subagent_type` で名前指定	プロンプト内でファイルパスを記述
ナレッジの読み込み	定義ファイル内の参照で自動	プロンプト内で手順を記述
出力先の管理	スキル内で定義済み	プロンプト内で個別に指定
実行制御	スキルのフローに従う	Phase構造などをプロンプトで設計

つまり、スキルやエージェント定義として蓄積してきたナレッジがあっても、Agent Teamsで活用するにはその内容を自然言語プロンプトに変換する作業が必要です。将来的にAgent Teamsからスキルやエージェント定義を直接参照できるようになれば解消されるはずですが、2026年2月時点ではまだその段階にありません。

プロンプト設計のポイント

Agent Teamsの公式ドキュメントとコミュニティの知見から、押さえておくべきポイントをまとめます。

チームメイトへのコンテキスト共有

チームメイトはリーダーの会話履歴を引き継がず、独立したインスタンスとして起動します。CLAUDE.mdやMCPサーバーは自動で読み込まれますが、それ以外の情報はスポーン時のプロンプトに含めるか、ファイル経由で渡す必要があります。

出力ファイルの分離

ファイルレベルのロック機構がないので、各チームメイトが異なるファイルセットを担当するように設計してください。

Phase構造による段階制御

プロンプトをPhaseに分けて「準備 → 並列実行 → 統合 → 完了」の流れを明示すると、Team Leadの動きを制御しやすくなります。

Delegate Mode（Shift+Tab） も有効です。リーダーのツール実行権限を制限して、コーディネーションに専念させるモードですが、2026年2月時点でチームメイトがツールアクセスを失うバグが報告されています（GitHub Issue #24073）。

サンプル: Agent Teamsでコードレビューするプロンプト

上記のポイントを反映した、Agent Teams版コードレビュープロンプトのサンプルです。既存のエージェント定義ファイルをチームメイトに読み込ませる構成例になっています。

前提: ~/.claude/agents/ にエージェント定義ファイルを配置していることを想定しています。定義ファイルがなくてもチームは起動しますが、レビューの観点や出力形式は定義の内容に依存します。

<details open> <summary>エージェント定義ファイルの雛形（簡易サンプル）</summary>

review-architecture.md（アーキテクチャ担当）

# Architecture Reviewer

## 役割
アーキテクチャ・設計レベルのコードレビューを行う。

## レビュー観点
- ディレクトリ構造とレイヤー分離の妥当性
- 依存関係の方向
- 単一責任の原則の遵守
- 過度な抽象化や不要な複雑性

## スコアリング
各指摘に重要度タグを付与:
- [Critical]: 重大な問題
- [Warning]: 改善が望ましい懸念
- [Suggestion]: より良い設計への提案

## 出力形式
- **[重要度]** ファイル名:行番号 - 指摘内容
  - 理由: なぜ問題か
  - 改善案: どう修正すべきか

review-naming.md（命名規約担当）

# Naming Reviewer

## 役割
変数・関数・クラス・ファイル名の命名規約をレビューする。

## レビュー観点
- 言語別の命名規約（camelCase / snake_case / PascalCase）の遵守
- 名前から役割が推測できるか（意味の明確さ）
- 略語の一貫性（例: btn vs button の混在）
- Boolean変数のプレフィックス（is / has / should）

review-frontend.md（フロントエンド担当）

# Frontend Reviewer

## 役割
React/Vue等のフロントエンド固有パターンをレビューする。

## レビュー観点
- コンポーネント分割の粒度とProps設計
- 状態管理パターンの適切性
- パフォーマンス（不要な再レンダリング、メモ化の過不足）
- アクセシビリティ（セマンティックHTML、ARIA属性）

</details>

プロンプト全文

このリポジトリでエージェントチームを使ってコードレビューを実行してください。
手順に従い、自律的に進めてください。判断に迷う場合のみユーザーに確認してください。

## 参照ファイルガイド

レビューに必要な定義ファイルとナレッジが `~/.claude/` 配下にあります。
各チームメイトは自分の担当に対応するファイルを読み込んで活用してください。

### ディレクトリ構造

~/.claude/
├── agents/                       # レビュー観点の定義（観点・出力形式）
│   ├── review-architecture.md    # アーキテクチャレビュー
│   ├── review-naming.md          # 命名規約レビュー
│   └── review-frontend.md        # フロントエンド固有（条件付き）
│
└── knowledge/                    # 参考ナレッジ
    ├── architecture/
    │   ├── patterns.md
    │   └── anti-patterns.md
    ├── naming/
    │   └── conventions.md
    └── frontend/
        └── best-practices.md

### チームメイトの読み込み手順

1. `~/.claude/agents/review-{自分の担当}.md` を読み、
   レビュー観点・出力形式を把握する
2. 定義内に参照ファイルがあれば、
   `~/.claude/knowledge/` から対応するファイルを読み込む
3. ナレッジの内容をレビューの根拠として活用する

---

## 手順

### Phase 0: レビュー対象の確認

ユーザーに以下を確認してください:

1. **レビュー対象**: 特定ファイル / 直近コミット / プロジェクト全体
2. **レビュー深度**: フル（デフォルト） / クイック（Criticalのみ）

### Phase 1: 準備（Team Lead が実行）

1. スクラッチディレクトリを作成:
   `.claude/code-review-team/.scratch/{YYYY-MM-DD-HHmm}/`

2. 「直近コミット」が選ばれた場合のみ差分コンテキストを生成:
   - `git diff HEAD~N` の結果を `{スクラッチ}/diff-context.md` に保存

3. テックスタック検出を実行:
   `package.json`、`requirements.txt` 等からフレームワークを特定し、
   結果を `{スクラッチ}/stack-detection.md` に出力

4. 検出結果を読み、Phase 2 のチーム構成を決定

### Phase 2: チーム作成 & 並列レビュー

チーム名 "code-review" でチームを作成し、
以下のチームメイトを並列でスポーンしてください。

#### 必須メンバー（常に起動）

1. **architecture-reviewer**
   - 役割: アーキテクチャ・設計レベルのレビュー
   - 定義: `~/.claude/agents/review-architecture.md`
   - 出力先: `{スクラッチ}/architecture-review.md`

2. **naming-reviewer**
   - 役割: 命名規約のレビュー
   - 定義: `~/.claude/agents/review-naming.md`
   - 出力先: `{スクラッチ}/naming-review.md`

#### 条件付きメンバー（スタック検出結果に基づき追加）

- **frontend-reviewer** — React/Vue等の検出時
  定義: `~/.claude/agents/review-frontend.md`
  出力先: `{スクラッチ}/frontend-review.md`

#### 全チームメイト共通ルール

- まず `{スクラッチ}/stack-detection.md` を読み込むこと
- 自分のエージェント定義を読み、観点・出力形式に従うこと
- 定義内に参照ファイルがあれば `~/.claude/knowledge/` から読み込むこと
- レビュー結果はインクリメンタルに出力先ファイルに書き込むこと
- 各指摘に重要度タグを付与: [Critical] / [Warning] / [Suggestion]
- 完了したら Team Lead にメッセージで報告:
  「レビュー完了。Critical: X件, Warning: Y件。詳細は {出力先} を参照」

### Phase 3: レポート統合

全チームメイトの完了を確認したら:

1. `{スクラッチ}/` 配下の全レビューファイルを読み込み、
   重複を排除し優先度を統一して統合レポートを生成
   **注意**: 統合対象は今回のスクラッチ内のファイルのみ
2. 出力先: `docs/code-review-team/{YYYY-MM-DD-HHmm}-review.md`

### Phase 4: 完了

1. チーム "code-review" を削除
2. レポートをユーザーに提示し、修正方針を確認:
   - 全指摘を一括修正
   - Critical/Warning のみ修正
   - 修正は自分で行う（レポートのみ）

このサンプルのポイントは、プロンプト冒頭にディレクトリ構造を記載し、各チームメイトに読み込むべきファイルのパスを明示している点です。スキル方式なら不要な記述ですが、Agent Teamsでは現状これが必要です。

トークン消費について

Agent Teamsのトークン消費はかなり大きいです。各チームメイトが独立したClaude Codeインスタンスとして動作するので、チーム人数に比例してコストが増えます。

Max 20x（$200/月）プランで、5人以上のチームメイトを含むチームを1時間に2-3回実行した場合、Max使用量の約4%を消費しました。各チームメイトが独立したインスタンスなので、人数が増えるほどコストは膨らみます。

正直なところ、スキル方式（Task tool）とAgent Teamsで最終的なアウトプットの品質にどれだけ差が出るかは、数回使った程度では測りきれていません。並列実行による速度面の利点は体感できますが、その差に見合う品質向上が得られるかは継続的な検証が必要です。

チームメイトにSonnetを指定すればコストは抑えられますが、Proプラン ($20/月) では現実的に厳しく、Max ($100-200/月) が最低ラインだと思います。

週次リセットの活用

Claude Codeの使用量制限は7日間のローリングウィンドウでリセットされます。/usage コマンドで次のリセットタイミングを確認できるので、余裕がある時期にAgent Teamsを試すと計画的に組み込みやすくなります。

制限事項（2026年2月時点）

Agent Teamsは実験的プレビュー段階です。主な制限をまとめておきます。

制限	影響
セッション再開不可	`/resume`でチームメイトが復元されない
ファイルロックなし	同じファイルの同時編集で上書きが発生しうる
1セッション1チーム	複数チームの同時運用不可
ネストチーム不可	チームメイトがサブチームを作れない
split panesの制約	VS Code統合ターミナル、Windows Terminal、Ghostty非対応
シャットダウンが遅い	チームメイトが現在のリクエストやツール呼び出しを完了するまで待つため時間がかかる
既存ナレッジの直接参照なし	スキルやエージェント定義をAgent Teamsから構造的に指定する方法がない

まとめ

Agent Teamsは、チームメイト間の直接通信と共有タスクリストによる自律的な連携を実現する仕組みです。

ただ、現時点ではチーム構成のすべてを自然言語プロンプトで記述する必要があり、既存のスキルやエージェント定義を活用するにはファイルパスを細かく指定するしかありません。スキル方式なら仕組み側がやってくれていたことを、プロンプトの中で自分で書くことになります。

トークン消費も大きく、スキル方式との明確な効果の差はまだ十分に検証できていません。今後スキルやエージェント定義との統合が進むことに期待しつつ、現時点では「スキル方式で十分な作業はスキルで、並列実行の価値が明確な場合にAgent Teamsを試す」という使い分けが現実的だと思います。

参考

Lost in the Middle — LLMの位置バイアスを克服するプロンプト設計

Wed, 04 Feb 2026 12:00:00 GMT

TL;DR

LLMは長いプロンプトの中間部分の情報を見落としやすい（Lost in the Middle問題）
主要な原因の一つはRoPE（Rotary Position Embedding）の長期減衰効果にあり、因果的注意マスクや学習データの偏りなど複数の構造的要因が関与している
対策として末尾チェックリストパターン、サンドイッチ戦略、XMLタグ構造化など複数の手法が存在する
手法ごとにトークンコストや適用場面が異なるため、状況に応じた使い分けが重要

1. Lost in the Middle問題とは

LLMの位置バイアス

LLMを使ったアプリケーション開発で、「プロンプトに書いた指示が無視される」という経験はないでしょうか。特に、システムプロンプトが数百行に及ぶ複雑なアプリケーションでは、この問題が頻繁に発生します。

これはLost in the Middleと呼ばれる現象です。Liu et al. (2023) の研究 "Lost in the Middle: How Language Models Use Long Contexts" で体系的に報告されました。

この研究の核心的な発見は、LLMがU字型の性能曲線を示すことです。

性能
 ▲
 │  ★                                    ★
 │   ★                                 ★
 │    ★★                            ★★
 │      ★★★                     ★★★
 │         ★★★★★★★★★★★★★
 │
 └──────────────────────────────────────► 情報の位置
   先頭        中間（性能低下）        末尾

具体的な数値として、複数の文書を参照して質問に回答させるタスクにおいて、中間に配置された情報の利用性能は先頭・末尾と比較して30%以上低下するケースが報告されています（Liu et al., 2023。低下幅はモデルやタスクにより異なります）。

なぜ中間の情報が失われるのか — RoPEの長期減衰効果

この現象の主要な原因の一つは、多くのLLMで採用されているRoPE（Rotary Position Embedding）の長期減衰効果にあると考えられています。なお、位置バイアスはRoPEだけでなく、因果的注意マスク——各トークンが自分より後ろのトークンを参照できないよう制限する三角行列状のマスク——の構造や、学習データにおける位置分布の偏りなど、複数の要因が複合的に関与していると指摘されています。

RoPEは、トークン間の相対位置に基づいて注意（Attention）の強度を調整する仕組みです。通常のTransformerは「このトークンが入力の何番目にあるか」を絶対位置として記憶しますが、RoPEは代わりに「2つのトークンがどれだけ離れているか」という相対的な距離を、ベクトルの回転角度として表現します。この回転角度は距離が離れるほど大きくなり、結果として遠いトークン同士の注意スコアが自然に減衰します。

プロンプトの先頭の指示は直近の生成トークンからは「遠い」位置にあります。しかし、因果的言語モデル（causal language model）——つまり左から右へ1トークンずつ順に生成し、各トークンはそれより前のトークンしか参照できないモデル——の特性により、先頭のトークンは後続の全てのトークンの処理に繰り返し参照されます。この累積的な影響により、結果的に先頭と末尾の情報は強く保持されます。

一方で、中間のトークンは先頭ほどの累積的な影響力を持たず、かつ末尾ほど生成トークンに近くもないため、いわば「注意の谷間」に陥ります。

2. 実務で遭遇する具体例

どのくらいの長さで問題になるのか

最新のモデルでは、数十行程度のプロンプトでこの問題が顕在化することはほぼありません。筆者の体感では、数百行規模のシステムプロンプト——たとえばRAGで大量のコンテキストを注入するケースや、複雑なルールセットを持つエージェント型アプリケーション——で初めて影響が目立ち始めます。

この問題は最新モデルでも解消されていません。Modarressi et al. (2025) の研究 "NoLiMa: Long-Context Evaluation Beyond Literal Matching"（ICML 2025）では、GPT-4oやGemini 1.5 Pro、Claude 3.5 Sonnetを含む13モデル中11モデルが、32Kトークンのコンテキストにおいて短文時のベースライン性能の50%未満にまで低下しました。その後の追加評価ではGPT-4.1やGemini 2.5 Flashでも同様の傾向が確認されています。

また、Chroma Researchの研究 "Context Rot: How Increasing Input Tokens Impacts LLM Performance"（2025年7月）では、18モデルを対象に長文コンテキストでの性能劣化が検証されています。興味深いのはモデルファミリーごとに劣化パターンが異なる点で、GPTモデルは誤った回答を自信を持って返す（ハルシネーション）傾向が強いのに対し、Claudeモデルは不確実な場合に回答を控える（棄権する）傾向が見られました。なお、同研究ではLiu et al.が報告したU字型の検索パターンは一貫しては観察されなかったとも報告されており、位置バイアスの現れ方はタスクやモデルによって異なる可能性があります。

筆者もGPT-4.1 miniで同様の現象を確認しており、モデルの世代が進んでも位置バイアスは緩和されつつあるが根本的には解消されていないのが現状です。

以下に示す例は構造を理解するために簡略化したものですが、実際にはこうしたセクションが何十個も並び、全体で数百行〜数千トークンに膨らんだときに問題が発生します。

システムプロンプトでの中間ルール無視

たとえば、以下のようなセクション構成を持つシステムプロンプトが数百行に及ぶ場合を考えます。

あなたはカスタマーサポートアシスタントです。   ← 先頭付近: 遵守される

## 基本ルール
- 丁寧な言葉遣いで応答してください
- ユーザーの名前を使って応答してください

... （数十セクションが続く）

## 応答フォーマット                               ← 中間に埋もれる
- 回答は3文以内にまとめてください
- 箇条書きを使用してください

## データ参照ガイド                               ← 中間に埋もれる
- 価格情報は必ずデータベースを参照すること

... （さらに多数のセクションが続く）

## 禁止事項                                       ← 末尾付近: 遵守される
- 競合他社の製品を推奨しないでください
- 個人情報を聞き出さないでください

先頭の「基本ルール」と末尾の「禁止事項」は遵守されるのに、中間に埋もれた「応答フォーマット」や「データ参照ガイド」のセクションが無視される——プロンプトが長くなるほど、このパターンに遭遇しやすくなります。

コード生成タスクでの要件欠落

コード生成タスクでも、要件セクションが多い場合に同様の問題が発生します。先頭の技術スタック指定や末尾のレスポンス形式は遵守されるのに、中間に記載したバリデーション要件やエラーハンドリング要件が丸ごと抜け落ちるケースです。プロンプト全体が短ければ問題にならないものの、コンテキストや例示が増えて全体が長くなると影響が出始めます。

3. 末尾チェックリストパターン

パターンの概要

Lost in the Middle問題に対する最も実践的な対策が、末尾チェックリストパターンです。プロンプトの末尾にチェックリスト形式で重要な指示を再掲し、LLMに「二重確認」を促します。

Before / After

以下は数百行のシステムプロンプトの構造を簡略化したものです。実際には各セクションがさらに詳細で、間に多くのルールやコンテキストが挟まります。

Before（中間の指示が埋もれる構成）:

あなたはコードレビューアシスタントです。

## レビュー観点
...（5項目）

... （多数のセクション: コーディング規約、言語別ルール、例外ケース...）

## 出力フォーマット                    ← 中間に埋もれる
- 重要度を「高/中/低」で分類
- 各指摘に修正案のコード例を添付
- 影響範囲を明記

... （さらにセクションが続く）

## レビュー対象
{code}

After（末尾にチェックリストを追加）:

あなたはコードレビューアシスタントです。

## レビュー観点
...（5項目）

... （多数のセクション: コーディング規約、言語別ルール、例外ケース...）

## 出力フォーマット
- 重要度を「高/中/低」で分類
- 各指摘に修正案のコード例を添付
- 影響範囲を明記

... （さらにセクションが続く）

## レビュー対象
{code}

---
## 出力前の最終チェックリスト           ← ここを追加
回答を出力する前に、以下の全項目を確認してください:
- [ ] 5つの観点全てに言及したか
- [ ] 各指摘に重要度（高/中/低）を付与したか
- [ ] 各指摘に修正案のコード例を添付したか
- [ ] 影響範囲を明記したか

末尾にチェックリストを配置することで、LLMは生成直前にこれらの条件を「再認識」します。U字型性能曲線の特性を逆手に取り、末尾という最も注意が向きやすい位置に確認項目を置くわけです。

筆者の経験では、このパターンを導入してから中間部の指示が無視される頻度は体感的にかなり減りました。特に「出力フォーマット」のようなプロンプト中間部に記載しがちな指示に対して効果を感じています。

実体験: 構造化JSON出力での改善

筆者が実際にこの問題に直面したのは、LangChainでOpenAIモデルを使い、ユーザーの自由入力テキストから構造化されたJSONを抽出するタスクでした。LangChainの with_structured_output を使用しており、Pydanticモデルの Field(description=...) でスキーマとフィールドの説明を定義しつつ、プロンプト側にも各フィールドの抽出ルール（必須/任意の区別、デフォルト値、フォーマット指定など）を別途記載する構成です。

フィールド数が多くなるにつれて、プロンプト中間部に記載した特定フィールドの抽出精度が目に見えて落ちていきました。先頭付近に書いたフィールドのルールと、末尾付近のルールは問題なく適用されるのに、中間に埋もれたフィールドだけが null や不正確な値で返ってくる——まさにU字型曲線の通りの挙動です。

この問題に対して、プロンプト末尾（ユーザー入力の後）にリマインダーを追加したところ、該当フィールドの抽出精度が明確に改善しました。

from langchain_core.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field

# Pydanticスキーマ定義（descriptionもLLMに渡される）
class TaskSchema(BaseModel):
    category: str = Field(description="定義済みカテゴリから選択")
    priority: int = Field(description="1-5の整数")
    due_date: str | None = Field(description="ISO 8601形式の日付、不明ならnull")

prompt = ChatPromptTemplate.from_messages([
    ("system", """あなたはタスク情報を抽出するアシスタントです。
ユーザーの入力から構造化データを抽出してください。"""),
    ("human", """{user_input}

## 出力前の確認
以下のフィールドが正しく抽出されていることを確認してから出力してください:
- "category": 必ず定義済みカテゴリから選択すること（推測しない）
- "priority": 1-5の整数であること
- "due_date": ISO 8601形式であること（入力に日付がなければnull）"""),
])

structured_llm = llm.with_structured_output(TaskSchema)
messages = prompt.format_messages(user_input=user_input)
result = structured_llm.invoke(messages)

この末尾リマインダーの追加で注目すべきは、他のフィールド（もともと正しく抽出できていたもの）の出力にほとんど影響がなかった点です。同じ指示をプロンプト中間部の該当フィールド定義を強調する形で追記した場合は、周辺フィールドの抽出にも微妙なブレが生じることがありましたが、末尾への配置ではそういった副作用がほぼ見られませんでした。末尾チェックリストは、既存の出力を壊さずにピンポイントで弱い箇所を補強できるという利点があります。

ここで一つ注意点があります。プロンプト側の抽出ルールを修正したとき、Pydanticモデルの Field(description=...) も合わせて更新しないと、プロンプトとスキーマ定義で矛盾が生じ、せっかくの修正の精度が落ちることがありました。with_structured_output はスキーマの description もLLMに渡すため、プロンプトとスキーマの両方を同期して更新する必要があります。地味ですが実務では見落としやすいポイントです。

なお、LangChainにおけるドメイン固有知識のプロンプト注入に関しては、LangChainブログの記事 "Incorporating domain specific knowledge in SQL-LLM solutions" でも、静的なプロンプトではなく動的にFew-shot exampleを検索して注入するアプローチが紹介されています。

A more powerful approach is to have a robust dataset of good examples, and dynamically include those which are relevant to the user question.

（より強力なアプローチは、良質なexampleの堅牢なデータセットを用意し、ユーザーの質問に関連するものを動的に含めることである。）

具体的には、ベクトルデータベースを活用したカスタムRetriever Toolを作成し、ユーザーの質問に意味的に類似したexampleを動的に取得する方法が示されています。フィールド数が多い構造化出力タスクでは、全ルールを静的に並べるよりも、入力内容に応じて関連するフィールドの抽出ルールを動的に選択・配置する方がLost in the Middleの影響を受けにくいかもしれません。

末尾チェックリストが効きにくいケース

ただし、この手法にも限界があります。

チェック項目が多すぎると効果が低下する: 研究 "Curse of Instructions"（ManyIFEval, 2024; ICLR 2025）によれば、個別の指示に90%従えるLLMでも、10個の指示を同時に満たす成功率は理論上 0.9^10 ≒ 約35% にまで低下します（実際の値はモデルにより異なります）。チェックリストが長くなると、リスト内で再び「Lost in the Middle」が発生するリスクもあります
指示が曖昧な場合: 「適切に処理すること」のような曖昧なチェック項目はLLMが解釈を揺らす原因になる
生成タスクが創造的な場合: 自由度の高い文章生成では、チェックリストが制約として機能しすぎて出力品質が低下することがある

実装上のポイント

末尾チェックリストパターンを効果的に使うためのポイントをまとめます。

1. チェックリストは「本文の繰り返し」ではなく「確認事項」として書く
   - NG: 同じ文章をそのままコピー
   - OK: 確認すべきポイントを簡潔にリスト化

2. 項目数は5〜10個に絞る
   - 多すぎると逆効果（チェックリスト自体のLost in the Middle）

3. 「回答の前に確認してください」と明示する
   - LLMに確認プロセスを促す

4. 最も見落とされやすい項目を優先する
   - 全てを再掲するのではなく、実績として漏れやすい指示を重点的に

4. その他のアプローチ

末尾チェックリストは手軽で効果的ですが、プロンプトの構造自体を改善するアプローチや、RAGパイプラインなどプロンプト外の仕組みで対策するアプローチもあります。

サンドイッチ戦略

最も重要な情報をプロンプトの先頭と末尾の両方に配置する方法です。

## 最重要ルール
出力は必ずJSON形式で返してください。

## コンテキスト情報
{大量のコンテキスト...}

## 補足情報
{追加のコンテキスト...}

## リマインダー: 出力は必ずJSON形式で返してください。

U字型曲線の両端、つまり性能が最も高い位置に重要な指示を配置するため、シンプルながら効果的です。ただし、「最重要」を1つに絞る必要があるため、複数の指示を同時に強調したい場合には不向きです。

XMLタグによる構造化とセクション分割

XMLタグやMarkdownのヘッダーを使ってプロンプトを明確にセクション分割し、LLMがパースしやすい構造にします。

Anthropicのプロンプトエンジニアリングチュートリアルでは、XMLタグによるデータと指示の分離が推奨されています。<sentences>...</sentences> のようなタグで入力データを明確に区切ることで、LLMがデータ領域と指示領域を区別しやすくなり、中間情報の見落としを軽減できる可能性があります。ただし、XMLタグ構造化は位置バイアスそのものを解消するものではなく、他の手法と組み合わせて使用することが推奨されます。

<system>
あなたはデータ分析アシスタントです。
</system>

<rules>
<rule priority="high">数値は必ず出典を明記すること</rule>
<rule priority="high">推測値には「推定」と明記すること</rule>
<rule priority="medium">グラフの説明には軸ラベルを含めること</rule>
</rules>

<context>
{分析対象のデータ}
</context>

<output_format>
{出力フォーマットの指定}
</output_format>

priority 属性を付与することで、LLMが重要度を判断する補助にもなります。構造化によって「どこに何が書かれているか」を明示的にすることで、中間部の情報が埋もれるリスクを下げる効果が期待できます。

RAGにおける戦略的ドキュメント配置

RAG（Retrieval-Augmented Generation）パイプラインでは、検索されたドキュメントの配置順序が回答精度に直結します。

def reorder_documents(docs: list[str], scores: list[float]) -> list[str]:
    """
    Lost in the Middle対策として、
    関連度の高いドキュメントを先頭と末尾に配置する。

    例: スコア順 [A(0.9), B(0.8), C(0.7), D(0.6), E(0.5)]
    結果: [A(0.9), C(0.7), E(0.5), D(0.6), B(0.8)]
           ^^^^^^                           ^^^^^^
           先頭に高スコア              末尾に高スコア
    """
    scored_docs = list(zip(docs, scores))
    scored_docs.sort(key=lambda x: x[1], reverse=True)

    head = []  # 先頭側（偶数インデックス: 1位, 3位, 5位...）
    tail = []  # 末尾側（奇数インデックス: 2位, 4位, 6位...）

    for i, (doc, score) in enumerate(scored_docs):
        if i % 2 == 0:
            head.append(doc)
        else:
            tail.append(doc)

    # 末尾側は逆順にして、高スコアが末尾端に来るようにする
    return head + tail[::-1]

この手法は、関連度スコアの高いドキュメントを先頭と末尾に配置し、中間にはスコアの低いドキュメントを置くことで、重要な情報が見落とされるリスクを軽減します。

情報位置と精度の定量的検証

Lost in the Middle問題は、Few-shot promptingの文脈でも影響を及ぼします。Anthropicのブログ記事 "Prompt engineering for Claude's long context window" では、長文コンテキストからの情報検索精度を高めるテクニックとして、質問に関連する引用を先に抽出させる手法や、正しく回答されたQ&Aの例をプロンプトに追加する手法が定量的に検証されています。

自分のプロンプトで位置バイアスの影響度合いを確認したい場合、このようなベンチマークを参考に検証パイプラインを構築することが有効です。

5. まとめ

手法の比較

手法	適用場面	トークンコスト	実装難易度
末尾チェックリスト	システムプロンプト全般	低（リスト追加分のみ）	低
サンドイッチ戦略	最重要ルールが1つの場合	低（1文の再掲）	低
XMLタグ構造化	複数種類の情報を扱う場合	中（タグ分の増加）	中
RAGドキュメント配置	RAGパイプライン	なし（並び替えのみ）	中

情報の配置に気を配る

最も重要な指示は先頭と末尾に配置します
中間に配置せざるを得ない場合は、末尾で再掲します
プロンプトが長くなるほど、Lost in the Middleのリスクは高まります

末尾チェックリストで二重確認する

プロンプト末尾に「出力前の最終チェックリスト」を設けます
過去に見落とされた指示を優先的にリストアップします
チェック項目は5〜10個に絞ります

継続的にプロンプトの精度をモニタリングする

プロンプトの変更前後で精度を比較する仕組みを設けます
特定の入力パターンで失敗が集中していないか定期的に確認します
Lost in the Middleの影響度はモデルのバージョンアップで変動する可能性があるため、モデル更新時にも確認します

学んだこと

LLMの位置バイアスはアーキテクチャに起因する構造的な問題であり、プロンプトの書き方だけでは根本解決できない。しかし、構造を理解した上で対策を講じることで実用上の精度は大幅に改善できる
2025年時点の最新モデルでもこの問題は解消されておらず、さらにモデルファミリーによって劣化パターンが異なる（ハルシネーション vs 棄権）。使用モデルに応じた検証が欠かせない

参考

Liu et al. (2023) "Lost in the Middle: How Language Models Use Long Contexts" - arXiv:2307.03172
Su et al. (2021) "RoFormer: Enhanced Transformer with Rotary Position Embedding" - arXiv:2104.09864
Anthropic "Prompt Engineering: Use XML Tags" - docs.anthropic.com
LangChain Blog "Incorporating domain specific knowledge in SQL-LLM solutions" - blog.langchain.com
Anthropic "Prompt engineering for Claude's long context window" - anthropic.com
Modarressi et al. (2025) "NoLiMa: Long-Context Evaluation Beyond Literal Matching" - arXiv:2502.05167
Chroma Research (2025) "Context Rot: How Increasing Input Tokens Impacts LLM Performance" - research.trychroma.com
"Curse of Instructions: Large Language Models Cannot Follow Multiple Instructions at Once" (2024; ICLR 2025) - OpenReview

AIが生成する「紫グラデーション」から脱却した話

Sun, 18 Jan 2026 12:00:00 GMT

import { Tweet } from 'astro-embed';

TL;DR

AIに何も指示せずにUIを作らせると、高確率で「紫グラデーション」になる
Claude Code + Playwright MCP + デザインAI（Stitch）でリニューアルを実行
新カラーは amber-500（琥珀色）、ターミナル/コード風のデザインへ

紫グラデーション問題

このブログ「Zero-Shot Log」は、元々AIでデザインを生成していました。

見た目は悪くない。でも、どこかで見たことがある気がする。

原因は「紫のグラデーション」です。

この現象について、Xで興味深いポストを見かけました。

このポストへのリプライでは「TailwindのBg-indigo-500の影響を大きく受けている」という指摘がありました。

AIが学習データからindigo/purple系のグラデーションを「最適なデフォルト」として学習した結果では、とのことです。

脱却することにしました。

リニューアルのワークフロー

今回のリニューアルでは、3つのAIツールを組み合わせました。

1. 現状把握: Claude Code + Playwright MCP

まず、Claude CodeにPlaywright MCPを接続して現行サイトのスクリーンショットを取得。デスクトップ・モバイルそれぞれのトップページと記事ページを撮影しました。

これにより、デザイナーAIへの依頼時に「現状」を正確に伝えられます。

2. デザイン依頼書の作成

取得したスクリーンショットをもとに、デザイナーAIへの依頼書（design-brief.md）を作成。含めた内容は以下の通りです。

サイト情報（名前、コンセプト、ページ構成）
現在のカラースキームと問題点の洗い出し
避けたいデザイン要素（紫グラデーション、派手なグロー等）
期待する方向性（ミニマル、ウォームダーク、ターミナル/Vibe Coding風等）

「何が嫌か」を明確に伝えることで、AIの出力をコントロールしようという狙いです。

3. デザインAI（Stitch）への依頼

StitchはGoogle Labsが提供するUI生成AIツール。Gemini 2.5 Proを搭載し、テキストや画像からUIデザインを生成できます。現在ベータ版で無料利用可能。

このStitchにスクリーンショットと依頼書を渡し、新しいデザイン案を受け取りました。

出てきたのはHTMLファイルとプレビュー画像。amber系のウォームな配色で、依頼内容は反映されています。

4. 実装

Stitchの成果物にはHTMLも含まれていますが、これは画像では伝わらない詳細情報を補完するためのもの。既存のAstroコンポーネントにそのまま適用できるわけではないので、カラーパレットやフォント選定などのコンセプトを参考にしながら、Claude Codeでスタイルを書き直しました。

まとめ

AI生成デザインの「紫グラデーション」問題は、明示的な指示で回避できる
「スクショ＋依頼書→デザインAI→実装」の流れでリニューアルがスムーズに進む

デザインのリニューアルがAIでここまで手軽にできる、良い時代になりました。

プロンプト拡張ツール「Query Expander」を作った

Mon, 12 Jan 2026 12:00:00 GMT

TL;DR

LLMへの依頼内容を明確に拡張するツール「Query Expander」を作った
Claude Artifactとして動作するため、Claudeにログインしていればいつでも使える
3段階の詳細レベル（Concise / Standard / Detailed）で出力を調整可能
日本語・英語を自動判定して出力

2026年2月更新: v1.1.1にアップデートしました。コピーボタンが機能しない不具合を修正しています。

作った経緯

Claude Codeで調査や実装を依頼するとき、依頼内容を明確にしておくと精度が上がります。

RAGの文脈では、ユーザーの曖昧なクエリを検索に適した形に変換することを「クエリ拡張（Query Expansion）」と呼びます。これと同じ発想で、LLMへのプロンプトも拡張できないかと考えました。

以前は、依頼内容を拡張するためのルールをClaudeに設定して使っていました。例えば「〇〇について調べて」という曖昧な指示を、目的・対象・期待するフォーマットを含んだ明確なプロンプトに変換してもらう、といった具合です。

ただ、この作業の頻度がかなり高かった。仕事中も頻繁に使うので、毎回チャットを開くのがめんどくさくなってきました。

そこで、Claude Artifactとして独立したツールにしてみました。Claudeにログインしていれば使えるので、いつでも気軽にプロンプトを拡張できます。自分のプラン内で動作するため、APIのトークン消費を気にする必要もありません。

UIデザインにはGoogleのStitchを使いました。プロンプトからUIを生成してくれるツールで、ベースのデザインを素早く作れます。

Query Expanderとは

Query Expanderは、曖昧なプロンプトを明確で構造化されたプロンプトに変換するツールです。

主な機能:

3段階の詳細レベル: Concise（簡潔）/ Standard（標準）/ Detailed（詳細）
Refine Onlyモード: 元の構造を維持しつつ文章を洗練
言語自動判定: 入力が日本語なら日本語で、英語なら英語で出力
Markdown保持: 見出しやリスト構造を維持したまま拡張

使い方

テキストエリアに拡張したいプロンプトを入力
詳細レベル（Concise / Standard / Detailed）を選択
「ENHANCE QUERY」をクリック
拡張されたプロンプトをコピーして使用

詳細レベルの使い分け

レベル	出力量	用途
Concise	1〜2文	軽微な修正、誤字脱字の修正
Standard	2〜4文	一般的なプロンプト改善（デフォルト）
Detailed	3〜5項目	複雑なタスク、詳細な指示が必要な場合

Refine Onlyモード

通常モードはプロンプトを「拡張」しますが、Refine Onlyモードは元の構造を維持したまま「洗練」します。

通常モードとの違い:

モード	動作
通常	目的・対象・フォーマットなどを追加して拡張
Refine Only	元の構造を維持しつつ、表現を洗練

Refine Onlyが向いているケース:

既に構造化されたプロンプトの文章を磨きたい
元のフォーマットを崩したくない
トーンだけ調整したい（カジュアル→フォーマルなど）

使用例

入力:

Reactのstate管理について調べて

Standard出力（イメージ）:

Reactにおけるstate管理の主要なアプローチについて調査してください。
対象として、useState、useReducer、Context API、および外部ライブラリ（Redux、Zustand、Jotai等）を含めてください。
それぞれの特徴、適切なユースケース、パフォーマンス面での考慮点を比較形式でまとめてください。

曖昧な「調べて」が、目的・対象・期待するフォーマットを含んだ明確なプロンプトに変換されます。

リンク

Query Expander - Claude Artifactへのリンク
ドキュメント - 詳細な使い方

まとめ

プロンプトを明確にする作業は地味ですが、LLMの出力精度に直結します。Query Expanderを使えば、この作業を手軽に行えます。

Claudeにログインしていれば無料で使えるので、日常的にLLMを使う方はぜひ試してみてください。

Antigravityが重くなった時の会話引き継ぎ方法

Sat, 03 Jan 2026 10:00:00 GMT

TL;DR

Antigravityで長時間作業すると動作が重くなる現象に遭遇
セッション分割で改善するが、コンテキストの引き継ぎが課題
Antigravityに引き継ぎ方法を聞いたことがきっかけで「brainディレクトリ」を発見
brainを活用すれば、新しいセッションでもスムーズに作業を継続できる

何が起きたか

長い会話で動作が重くなる

Antigravityを使っていたときのことです。

あるプロジェクトで長めの実装作業を任せていたら、徐々にレスポンスが遅くなり始めました。UIの反応が鈍くなり、エージェントの応答も明らかに遅延している。アクティビティモニタを確認すると、メモリ使用量がかなり高くなっていました。

原因はトークン予算の圧迫

調べてみると、Antigravityには1会話あたり約200,000トークンの予算があるとのこと。会話が長くなると、このトークン予算を消費していき、処理負荷が上がっていくようです。

また、会話履歴が増えるとローカルのストレージも圧迫されます。Antigravityはスクリーンショットや録画などの「Artifacts（成果物）」をローカルに保存するため、これも動作に影響している可能性がありました。

セッション分割で改善

基本的な対策

パフォーマンス問題の対策として、以下が有効でした。

1. 古い会話ログを削除する

Agent Managerの履歴から、不要になった会話を削除します。数十セッション以上溜まっていると、IDE全体のレスポンスに影響することがあります。

2. 長い作業はセッションを分割する

1つの会話で長時間作業を続けるのではなく、キリの良いところで新しい会話に切り替えます。トークン予算がリセットされ、動作が軽快になります。

残った課題：コンテキストの引き継ぎ

セッション分割で動作は改善しました。しかし、新しい問題が生まれました。

新しいセッションに、前の作業のコンテキストをどう引き継ぐか？

毎回「前回はここまでやった」「この方針で進めていた」と説明し直すのは面倒です。特に複雑な実装の途中だと、説明漏れも起きやすい。

AntigravityにはKnowledge Itemsという自動学習の仕組みがあり、蓄積された知識は自動的に引き継がれます。ただ、どの範囲（ワークスペース単位？ディレクトリ単位？）でどれだけ引き継がれるのか、ドキュメントを見ても明確にはわかりませんでした。特定の会話のタスクやファイルを明示的に引き継ぎたい場面もあります。

偶然の発見：Antigravityの回答

セッションを切り替える前に、Antigravityにこう聞いてみました。

「新しい会話に引き継ぐにはどうすればいい？」

すると、こんな回答が返ってきました：

「別の会話を開始する際に、「前回の会話（a1b2c3d4-...）の続きから」と伝えていただければ、これらのドキュメントを参照して作業を継続できます。特に current_issues.md には、次のセッションで対応すべき内容を詳細にまとめています。」

え、そんな機能あるの？

current_issues.md とは何か。どこにあるのか。気になって調べてみると、ホームディレクトリに見慣れないフォルダがありました。

ls ~/.gemini/antigravity/brain/

ここに、セッションごとのArtifactsが保存されていたのです。

brainディレクトリとは

概要

brainディレクトリ（~/.gemini/antigravity/brain/）は、Antigravityのエージェントが作業中に生成する記録の保存場所です。

~/.gemini/antigravity/brain/
├── a1b2c3d4-5678-90ab-cdef-1234567890ab/
│   ├── task.md
│   ├── implementation_plan.md
│   ├── walkthrough.md
│   ├── current_issues.md
│   ├── uploaded_image_1234567890123.png
│   └── uploaded_image_1234567890456.png
├── b2c3d4e5-6789-01bc-def0-2345678901bc/
│   └── ...
└── ...

各フォルダ名のUUIDが、それぞれの会話セッションに対応しています。

保存されるファイル

ファイル	内容
`task.md`	タスクの進捗管理（チェックリスト形式）
`implementation_plan.md`	実装計画の技術的詳細
`walkthrough.md`	実装完了後の変更サマリー
`current_issues.md`	次セッションで対応すべき課題
`uploaded_image_*.png`	会話中にアップロードした画像

特に current_issues.md が引き継ぎに重要です。未解決の課題や、次回やるべきことがまとまっています。

brainを活用した会話引き継ぎ方法

方法1: UUIDを指定して引き継ぐ

新しい会話を開始し、前回のセッションIDを伝えます。

前回の会話（a1b2c3d4-5678-90ab-cdef-1234567890ab）の続きから作業してください。

エージェントはbrainディレクトリ内の該当Artifactsを参照し、コンテキストを理解した上で作業を継続します。

方法2: current_issues.mdを直接参照させる

より確実に引き継ぎたい場合は、ファイルパスを直接指定します。

~/.gemini/antigravity/brain/a1b2c3d4-.../current_issues.md を確認して、
未解決の課題から作業を再開してください。

会話IDの確認方法

会話IDは、Antigravityに直接以下のように聞くことで確認できます。

この会話の会話ID（UUID）教えて

回答例：

「この会話のIDは a1b2c3d4-5678-90ab-cdef-1234567890ab です。」

※ PlanningモードでGemini 3 Proを使用した際に確認。モデルや状況によっては回答が異なる可能性があります。

実践的なワークフロー

Antigravity単体での運用

作業開始: 新しい会話でタスクを指示
作業中: エージェントがtask.md、implementation_plan.mdなどを自動生成
区切り: 動作が重くなってきたら、エージェントに「Artifactsを最新の状態にして」と依頼。task.md、implementation_plan.md、current_issues.mdなどが更新される
UUID確認: 「この会話のUUID教えて」と聞いてメモしておく
引き継ぎ: 新しい会話を開始し、「前回の会話（UUID）の続きから」と伝える

ポイント: 引き継ぎ前にArtifactsを最新にしておくことが重要です。古い状態のまま引き継ぐと、新しいセッションで認識のズレが生じます。

Claude Codeとの併用

brainのファイルはMarkdown形式なので、Claude Codeなど他のAIツールからも読み取れます。

# Claude Codeでbrainの内容を確認
cat ~/.gemini/antigravity/brain/a1b2c3d4-.../implementation_plan.md

Antigravityで作成したimplementation_plan.mdをClaude Codeに読ませて「この計画をレビューして」と頼んだりできます。

注意点

brainには会話全文は保存されない

brainに保存されるのはArtifacts（成果物）のみで、会話のやり取り全文は保存されません。細かいニュアンスや議論の経緯は失われる可能性があるため、重要な決定事項はエージェントにArtifactsへ明示的に記録させましょう。

なお、~/.gemini/antigravity/conversations/ には .pb（Protocol Buffers）形式のファイルがあり、バイナリ形式で会話データが保存されているようです。直接読むことはできませんが、会話履歴はここに残っていそうです。

ストレージ容量

brainディレクトリ以外にも、Antigravityは browser_recordings/ ディレクトリなどに証跡ファイルを生成します。スクリーンショットやブラウザ録画が蓄積すると、ディスク容量を圧迫することがあります。不要なセッションは定期的に削除することをおすすめします。

# 古いセッションの確認
ls -la ~/.gemini/antigravity/brain/

# 不要なセッションの削除
rm -rf ~/.gemini/antigravity/brain/<不要なUUID>/

まとめ

Antigravityが重くなる問題は、セッション分割で解決できます。そして、会話の引き継ぎには brainディレクトリのUUIDを指定する という方法が使えます。

問題: 長い会話でトークン予算を消費し、動作が重くなる
解決策: 新しいセッションに切り替え、brainのArtifactsを参照して引き継ぐ
隠し機能: 「前回の会話（UUID）の続きから」と伝えるだけで、brainのArtifactsを参照してくれる

この機能は、Antigravityに会話引き継ぎ方法を聞いたことで偶然発見しました。Antigravityの回答がハルシネーションだった可能性もありますが、実際にbrainディレクトリは存在しますし、ファイルを参照させることで引き継ぎできるのは確かです。公式ドキュメントにも記載が見当たらないので、ちょっとした裏技として使えそうです。

パフォーマンス問題で困っている方は、ぜひbrainを活用したセッション管理を試してみてください。

参考

macOSでNeovimを快適に使うための設定入門

Tue, 30 Dec 2025 11:00:00 GMT

TL;DR

macOSでのIME問題は im-select.nvim + macism で解決できる
Neovim 0.11ではプラグインの互換性に注意が必要（Telescopeは0.1.xタグを使用）
Nerd Fontなしでもシンプルな設定で十分実用的な環境が作れる
LSP/補完は mason.nvim + nvim-cmp の組み合わせが初心者にも扱いやすい

はじめに

この記事では、macOSでNeovimを快適に使うための設定を解説します。Vimの基本操作（モード切り替え、カーソル移動、保存・終了など）は知っているが、Neovimのプラグイン設定は初めてという方を想定しています。

以下の4つのトピックを扱います：

macOS IME問題の解決 - 日本語入力で最もハマりやすいポイント
Neovim 0.11のプラグイン互換性 - 最新版を使う際の注意点
Nerd Font不要のミニマル設定 - フォント設定なしで使える環境
LSP/補完の基本設定 - 定義ジャンプや自動補完を実現

前提環境

この記事の設定は以下の環境で動作確認しています：

項目	バージョン
macOS	Sonoma 14.x 以降
Neovim	0.11.3 以降（LSP新APIに必要）
Homebrew	インストール済み
ターミナル	iTerm2（Terminal.appでも可）

まだNeovimをインストールしていない場合は、以下のコマンドでインストールできます：

brew install neovim

1. macOS IME問題の解決

問題の概要

macOSでNeovim（Vim）を使う際、多くの人がつまずくのがIME（日本語入力）の問題です。

具体的には: 日本語入力モードのままノーマルモードに戻ると、jやkなどのコマンドが効かなくなる。

これは、InsertモードからNormalモードに戻っても、macOSのIME状態がそのままになるためです。日本語で文章を書いた後、Escでノーマルモードに戻ると、IMEが日本語入力のままなので、jjj...と入力しても「っっっ...」と日本語が入力されてしまいます。

解決策: im-select.nvim + macism

この問題を解決するには、2つのコンポーネントを組み合わせます：

im-select.nvim（Neovimプラグイン）
- モード切り替え（Insert→Normal等）を検知
- 外部のCLIツールを呼び出してIMEを切り替え
macism（CLIツール）
- 実際にmacOSのIMEを切り替えるコマンド
- im-select.nvimから呼び出される

つまり、im-select.nvimがNeovim内でモード変更を監視し、変更を検知したらmacismコマンドを実行してIMEを英数に切り替える、という仕組みです。

なぜmacismなのか

im-select.nvimはmacOS上でIMEを切り替えるCLIツールを呼び出します。macOS用のツールは複数ありますが、im-select.nvimの公式READMEではmacismを推奨しています。

Please install macism, this is the only one CLI tool can switch CJK and English input methods in macOS correctly. — im-select.nvim README

macismは、日本語などのCJK入力ソースを確実に切り替えられます。他のツール（input-source-switcher等）ではmacOSのバグにより、メニューバーのアイコンは変わっても実際には切り替わらない問題が発生することがあるようです。

インストール手順

macismは公式のHomebrew tapにないため、サードパーティのtapを追加する必要があります：

# tapの追加
brew tap laishulu/homebrew

# macismのインストール
brew install laishulu/homebrew/macism

インストール後、動作確認をしてみましょう：

# 現在の入力ソースを確認
macism

# 出力例: com.apple.inputmethod.Kotoeri.RomajiTyping.Japanese
# または: com.apple.keylayout.ABC

Neovimの設定

im-select.nvimプラグインを使って、モード切り替え時の動作を設定します。

-- プラグインマネージャー（lazy.nvim）での設定例
{
  "keaising/im-select.nvim",
  config = function()
    require("im_select").setup({
      -- 切り替え先の入力ソース（英数キーボード）
      default_im_select = "com.apple.keylayout.ABC",

      -- macismの絶対パス（Intel Macの場合は /usr/local/bin/macism）
      default_command = "/opt/homebrew/bin/macism",

      -- 英数に切り替えるタイミング
      set_default_events = {
        "VimEnter",       -- Neovim起動時
        "FocusGained",    -- ウィンドウにフォーカスが戻った時
        "InsertLeave",    -- Insertモードを抜けた時
        "CmdlineLeave"    -- コマンドラインモードを抜けた時
      },

      -- InsertEnter時に前のIMEに戻す設定（空にして無効化）
      set_previous_events = {},
    })
  end,
}

設定のポイント: なぜ `set_previous_events = {}` にしたか

デフォルトでは、set_previous_events = { "InsertEnter" } となっており、Insertモードに入ると直前のIME状態に戻ります。

しかし、この設定を空にして無効化しました。理由は以下の通りです：

トレードオフの比較:

設定	メリット	デメリット
`{ "InsertEnter" }`（デフォルト）	日本語の連続入力に便利	英語コードを書く際に毎回切り替えが必要
`{}`（無効化）	常に英数から始まるので予測しやすい	日本語を続けて書く際は手動切り替え

プログラミングでは英語入力が圧倒的に多いため、「常に英数に戻る」動作の方が快適でした。日本語を書く際は、手動で日本語入力に切り替えれば済みます。

もし日本語でドキュメントを書く機会が多い場合は、デフォルトの { "InsertEnter" } の方が便利かもしれません。

2. Neovim 0.11のプラグイン互換性

問題の概要

2025年3月にリリースされたNeovim 0.11では、LSP関連のAPIが大きく変更されました。この影響で、一部のプラグインがそのままでは動作しない場合があります。

Telescope.nvimの互換性問題

最も多くのユーザーが遭遇するのが、Telescope.nvim（ファジーファインダー）の問題です。

症状: Telescopeを開くとエラーが発生する、または表示がおかしい

原因: Telescope.nvimの安定版ブランチ（0.1.x）がNeovim 0.11のAPI変更に追従していない

解決策: 0.1.xタグを使用する（最新版では修正済み）

-- Neovim 0.11対応版
{
  "nvim-telescope/telescope.nvim",
  tag = "0.1.x",  -- 安定版タグ（Neovim 0.11対応済み）
  dependencies = { "nvim-lua/plenary.nvim" },
}

バージョン選択のポイント

2025年末時点では、Telescope v0.2.0もリリースされています。

指定方法	特徴	推奨度
`tag = "0.1.x"`	安定版、Neovim 0.11対応済み	推奨
`tag = "0.1.8"` 等	特定バージョン固定	再現性重視なら
`branch = "master"`	最新開発版	新機能を試したい場合

以前は0.1.xブランチがNeovim 0.11非対応でしたが、現在は修正されています。特に理由がなければtag = "0.1.x"を使えば問題ありません。

その他の互換性確認方法

プラグインが動作しない場合は、以下の手順で調査できます：

GitHubのIssuesを確認: [プラグイン名] Neovim 0.11で検索
READMEのRequirementsを確認: 対応するNeovimバージョンが明記されていることが多い
最新版に更新: :Lazy syncでプラグインを最新化

3. Nerd Font不要のミニマル設定

Nerd Fontとは

多くのNeovim設定記事では「Nerd Fontをインストールしてください」と書かれています。Nerd Fontは、通常のフォントにアイコン（ファイルタイプ、Git状態、フォルダなど）を追加したフォントファミリーです。

しかし、Nerd Fontの導入には以下のステップが必要です：

Nerd Fontのダウンロード
システムへのインストール
ターミナルのフォント設定変更
設定の反映確認

なぜNerd Fontなしを選んだか

Nerd Fontを使わない選択をした理由は以下の通りです：

メリット:

ターミナルのフォント設定をいじらなくて済む
複数マシン間で設定を共有しやすい（フォントのインストール不要）
シンプルで軽量な見た目

デメリット:

ファイルタイプが視覚的に分かりにくい
見た目が地味

プログラミング中はファイル名を見ればファイルタイプは分かるため、アイコンがなくても実用上の問題はありませんでした。

アイコンを無効化する設定

主要なプラグインでアイコンを無効化する方法を紹介します。

nvim-tree（ファイルエクスプローラー）

{
  "nvim-tree/nvim-tree.lua",
  config = function()
    require("nvim-tree").setup({
      renderer = {
        icons = {
          show = {
            file = false,        -- ファイルアイコン非表示
            folder = false,      -- フォルダアイコン非表示
            folder_arrow = true, -- 展開/折りたたみの矢印は表示
            git = false,         -- Git状態アイコン非表示
          },
          glyphs = {
            folder = {
              arrow_closed = ">",  -- 折りたたみ時の矢印
              arrow_open = "v",    -- 展開時の矢印
            },
          },
        },
      },
    })
  end,
}

lualine（ステータスライン）

{
  "nvim-lualine/lualine.nvim",
  config = function()
    require("lualine").setup({
      options = {
        icons_enabled = false,       -- アイコン全体を無効化
        section_separators = "",     -- セクション区切りなし
        component_separators = "|",  -- 区切り文字をシンプルに
      },
    })
  end,
}

見た目の比較

Nerd Fontあり:

  init.lua    main   lua  utf-8  100%  42:1

Nerd Fontなし:

NORMAL | main | init.lua | lua | utf-8 | 100% | 42:1

アイコンの代わりにテキストで情報が表示されます。慣れれば十分読みやすいです。

4. LSP/補完の基本設定

LSPとは

LSP（Language Server Protocol）は、エディタと言語サーバーの間の通信プロトコルです。これを使うことで、以下の機能が実現できます：

定義ジャンプ: 関数や変数の定義元にジャンプ
参照検索: 関数や変数がどこで使われているか一覧表示
自動補完: 入力中に候補を表示
診断: エラーや警告をリアルタイムで表示
リネーム: シンボル名を一括変更

プラグイン構成の全体像

LSP/補完を実現するために、以下のプラグインを組み合わせます：

mason.nvim              # 言語サーバーのインストーラー
  └── mason-lspconfig   # masonとlspconfigの橋渡し
        └── nvim-lspconfig  # 言語サーバーの設定

nvim-cmp                # 補完エンジン
  ├── cmp-nvim-lsp      # LSPからの補完ソース
  ├── cmp-buffer        # バッファ内の単語を補完
  ├── cmp-path          # ファイルパスを補完
  └── LuaSnip           # スニペット展開

なぜこの構成を選んだか

観点	選択	理由
LSPインストール	mason.nvim	GUIで管理でき、初心者に分かりやすい
補完エンジン	nvim-cmp	最も広く使われており、情報が豊富
スニペット	LuaSnip	nvim-cmpとの連携がスムーズ

mason.nvimによる言語サーバーの自動インストール

mason.nvimを使うと、:MasonコマンドでGUIから言語サーバーを管理できます。また、mason-lspconfigを使えば、必要な言語サーバーを自動でインストールできます。

{
  "neovim/nvim-lspconfig",
  dependencies = {
    "williamboman/mason.nvim",
    "williamboman/mason-lspconfig.nvim",
  },
  config = function()
    -- masonの初期化（:Masonコマンドが使えるようになる）
    require("mason").setup()

    -- 自動インストールする言語サーバーを指定
    require("mason-lspconfig").setup({
      ensure_installed = {
        "lua_ls",   -- Lua
        "ts_ls",    -- TypeScript/JavaScript
        "pyright",  -- Python
      },
    })
  end,
}

初回起動時に、指定した言語サーバーが自動でインストールされます。

Neovim 0.11の新しいLSP設定API

Neovim 0.11では、LSPの設定方法が大きく変わりました。

旧来の方法（nvim-lspconfig依存）:

local lspconfig = require("lspconfig")
lspconfig.lua_ls.setup({
  settings = {
    Lua = {
      diagnostics = { globals = { "vim" } },
    },
  },
})

新しい方法（Neovim 0.11.3+ネイティブ）:

-- 言語サーバーごとの設定
vim.lsp.config('lua_ls', {
  settings = {
    Lua = {
      diagnostics = { globals = { "vim" } },
    },
  },
})

-- 言語サーバーを有効化
vim.lsp.enable({ "lua_ls", "pyright", "ts_ls" })

Note: nvim-lspconfigは廃止されていません。内部的にvim.lsp.configを呼び出すラッパーとして機能するため、従来のlspconfig.xxx.setup({})形式も引き続き使えます。新規で設定する場合は、プラグイン依存を減らせる新APIがおすすめです。

新しいAPIを使うメリット：

Neovimのビルトイン機能なので、将来的に安定
シンプルで分かりやすい記述
ファイルベースの設定も可能（~/.config/nvim/lsp/配下）

LSPキーマップの設定

LSPの機能をキーに割り当てます。LspAttachイベントを使うと、LSPが有効なバッファでのみキーマップが設定されます。

vim.api.nvim_create_autocmd("LspAttach", {
  callback = function(args)
    local bufnr = args.buf
    local opts = { buffer = bufnr, silent = true }

    -- 定義・宣言・実装へのジャンプ
    vim.keymap.set("n", "gd", vim.lsp.buf.definition, opts)
    vim.keymap.set("n", "gD", vim.lsp.buf.declaration, opts)
    vim.keymap.set("n", "gi", vim.lsp.buf.implementation, opts)

    -- ドキュメント表示・編集操作
    vim.keymap.set("n", "K", vim.lsp.buf.hover, opts)
    vim.keymap.set("n", "<leader>rn", vim.lsp.buf.rename, opts)
    vim.keymap.set("n", "<leader>ca", vim.lsp.buf.code_action, opts)

    -- 診断の移動
    vim.keymap.set("n", "[d", vim.diagnostic.goto_prev, opts)
    vim.keymap.set("n", "]d", vim.diagnostic.goto_next, opts)
    vim.keymap.set("n", "<leader>e", vim.diagnostic.open_float, opts)
  end,
})

なぜLspAttachイベントを使うか

キーマップの設定方法には複数の選択肢があります：

方法	説明	問題点
グローバルキーマップ	全バッファで有効	LSPがないファイルでもキーが有効
lspconfig.on_attach	lspconfig経由で設定	lspconfigに依存
LspAttachイベント	LSPアタッチ時に設定	なし

LspAttachはNeovimのビルトインイベントなので、プラグインに依存せず、確実に動作します。

nvim-cmpによる補完設定

補完エンジンnvim-cmpの基本設定です。

{
  "hrsh7th/nvim-cmp",
  dependencies = {
    "hrsh7th/cmp-nvim-lsp",   -- LSP補完ソース
    "hrsh7th/cmp-buffer",     -- バッファ補完
    "hrsh7th/cmp-path",       -- パス補完
    "L3MON4D3/LuaSnip",       -- スニペットエンジン
    "saadparwaiz1/cmp_luasnip", -- スニペット補完
  },
  config = function()
    local cmp = require("cmp")
    local luasnip = require("luasnip")

    cmp.setup({
      -- スニペット展開の設定
      snippet = {
        expand = function(args)
          luasnip.lsp_expand(args.body)
        end,
      },

      -- キーマップ
      mapping = cmp.mapping.preset.insert({
        ["<C-Space>"] = cmp.mapping.complete(),   -- 手動で補完を開く
        ["<C-e>"] = cmp.mapping.abort(),          -- 補完をキャンセル
        ["<CR>"] = cmp.mapping.confirm({ select = true }), -- 確定
        ["<Tab>"] = cmp.mapping(function(fallback)
          if cmp.visible() then
            cmp.select_next_item()  -- 次の候補
          else
            fallback()
          end
        end, { "i", "s" }),
        ["<S-Tab>"] = cmp.mapping(function(fallback)
          if cmp.visible() then
            cmp.select_prev_item()  -- 前の候補
          else
            fallback()
          end
        end, { "i", "s" }),
      }),

      -- 補完ソースの優先順位
      sources = cmp.config.sources({
        { name = "nvim_lsp" },  -- LSP（最優先）
        { name = "luasnip" },   -- スニペット
      }, {
        { name = "buffer" },    -- バッファ内の単語
        { name = "path" },      -- ファイルパス
      }),
    })
  end,
}

補完ソースの優先順位は、最初のグループ（LSP、スニペット）が優先され、該当がなければ次のグループ（バッファ、パス）から候補が表示されます。

設定ファイルの構成について

この記事で紹介した設定は、すべて~/.config/nvim/init.lua一つにまとめています。

なぜ単一ファイルにしたか:

構成	メリット	デメリット
単一ファイル	全体が見渡せる、検索しやすい	長くなると見づらい
複数ファイル	責務が明確、大規模向き	ファイル間の依存関係が複雑

400行程度の設定であれば、単一ファイルで十分管理できます。設定が増えてきたら分割を検討すれば良いでしょう。

まとめ

この記事では、macOSでNeovimを快適に使うための4つの設定を解説しました。

IME問題: im-select.nvim + macismで解決。set_previous_events = {}で常に英数に戻す設定がプログラミング向き
Neovim 0.11互換性: Telescopeは0.1.xタグを使用（修正済み）
Nerd Font不要: 各プラグインでアイコンを無効化すればシンプルな環境が作れる
LSP/補完: mason.nvim + nvim-cmpの組み合わせで、GUIでの管理と豊富な補完が実現

これらの設定は、あくまで一つの選択肢です。使っていく中で、自分の好みや用途に合わせてカスタマイズしていってください。

参考資料

公式ドキュメント

プラグイン

im-select.nvim - IME自動切り替え
macism - macOS用IME制御CLI
nvim-lspconfig - LSP設定
mason.nvim - 言語サーバー管理
nvim-cmp - 補完エンジン
telescope.nvim - ファジーファインダー
lazy.nvim - プラグインマネージャー

GitとGitHub CLIの複数アカウントを、cdするだけで自動切り替えする

Tue, 30 Dec 2025 10:00:00 GMT

TL;DR

仕事用と個人用のGitHubアカウントを使い分けるには、3層の設定が必要
includeIf + insteadOf + gh関数ラッパーを組み合わせることで完全自動化
~/work/配下にcdするだけで、すべてが仕事用に切り替わる

2026年1月更新: 層3のghコマンド切り替え方式を改善しました。以前のchpwdフック + gh auth switch方式から、関数ラッパー + GH_TOKEN環境変数方式に変更しています。複数ターミナルウィンドウでの並行作業に対応しました。

背景・課題

解決したかった問題

「仕事用と個人用のGitHubアカウントを使い分けたい」

これは多くの開発者が直面する課題です。手動で切り替えることもできますが、以下の問題がありました。

切り替え忘れ: 個人リポジトリに仕事用のメールアドレスでコミットしてしまう
操作の煩雑さ: git configやSSHキーを毎回手動で切り替えるのは面倒
gh CLIの存在: GitだけでなくGitHub CLI（gh）も別途切り替えが必要

理想の状態

「ディレクトリを移動するだけで、すべてが自動で切り替わる」

具体的には、~/work/配下に移動したら仕事用、それ以外は個人用として、以下がすべて自動で切り替わる状態を目指しました。

Gitのコミット情報（user.name、user.email）
SSHキー（GitHubへの認証）
GitHub CLI（ghコマンド）のアカウント

検討した選択肢

選択肢A: 手動で都度設定

各リポジトリで git config user.email を手動設定する方法です。

メリット:

追加の設定が不要

デメリット:

リポジトリを作るたびに設定が必要
設定し忘れると間違ったアカウントでコミットしてしまう
SSHキーやgh CLIは別途管理が必要

選択肢B: direnv + GH_TOKEN

direnvを使って、ディレクトリごとに環境変数を設定する方法です。

# ~/work/.envrc
export GH_TOKEN="ghp_xxxx"
export GIT_AUTHOR_EMAIL="work@example.com"

メリット:

環境変数で統一的に管理できる
direnvは広く使われているツール

デメリット:

direnvの追加インストールが必要
トークンをファイルに書く必要がある（セキュリティ懸念）
プロジェクトごとに.envrcが必要

選択肢C: includeIf + insteadOf + gh関数ラッパー（採用）

Gitの標準機能とシェル関数を組み合わせる方法です。

メリット:

追加ツール不要（Git/Zsh標準機能を使用）
設定は一度だけ、以降は自動
トークンをファイルに書く必要がない

デメリット:

設定項目が多い（3層の設定が必要）
仕組みの理解が必要

比較表

観点	手動設定	direnv	includeIf+α（採用）
初期設定の手間	なし	中	大
日常の手間	大	小	なし
追加ツール	不要	direnv	不要
セキュリティ	-	トークンをファイルに保存	OSキーチェーン
設定忘れのリスク	高	低	なし
複数ウィンドウでの並行作業	-	対応	対応

最終判断

採用: includeIf + insteadOf + gh関数ラッパー

決め手となった理由:

追加ツール不要: GitとZshの標準機能だけで実現できる
設定忘れがない: ディレクトリ構造に基づいて自動で判定される
セキュリティ: gh CLIのトークンはOSのキーチェーンに保存される
複数ウィンドウ対応: 環境変数でプロセスごとに認証するため、他のターミナルに影響しない

受け入れたトレードオフ:

初期設定は複雑になる（この記事で解説します）
仕組みを理解していないとトラブルシューティングが難しい

なぜ「3層」が必要なのか

ここからが本題です。GitとGitHubのアカウント切り替えには、3つの異なる設定が必要です。

┌─────────────────────────────────────────────────────┐
│                   あなたのPC                        │
├─────────────────────────────────────────────────────┤
│                                                     │
│  [層1] Gitのuser設定                                │
│    → コミットに記録される名前・メールアドレス       │
│    → .gitconfig の includeIf で切り替え            │
│                                                     │
│  [層2] SSHキー                                      │
│    → GitHubへpush/pullするときの認証               │
│    → SSH Hostエイリアス + insteadOf で切り替え     │
│                                                     │
│  [層3] gh CLIのアカウント                           │
│    → gh pr create などGitHub操作時のアカウント      │
│    → gh関数ラッパー + GH_TOKEN で切り替え          │
│                                                     │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │      GitHub         │
              │  (個人 or 仕事用)   │
              └─────────────────────┘

なぜ別々に設定が必要なのか

それぞれが異なるタイミングで使われるからです。

層	いつ使われるか	何を識別するか
層1	`git commit` 時	コミットの作者（Author）
層2	`git push/pull` 時	GitHubへの接続認証
層3	`gh pr create` 等	GitHub APIの操作者

例えば、層1だけ設定しても、push時に間違ったSSHキーが使われてしまいます。3層すべてを正しく設定して初めて、完全な切り替えが実現します。

各層の設定方法

以下、~/work/配下を仕事用、それ以外を個人用として設定する例を示します。

層1: includeIfによるuser設定の自動切り替え

includeIfは、条件に応じて別の設定ファイルを読み込むGitの機能です。

~/.gitconfig（メインの設定ファイル）

# デフォルト（個人用）の設定
[user]
    name = Your Personal Name
    email = personal@example.com

# ~/work/ 配下では仕事用設定を追加で読み込む
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

~/.gitconfig-work（仕事用の設定ファイル）

[user]
    name = Your Work Name
    email = work@company.com

解説

[includeIf "gitdir:~/work/"]: 現在のリポジトリが ~/work/ 配下にある場合に適用
path = ~/.gitconfig-work: この設定ファイルを読み込む

重要なポイント:

gitdir: の後のパスは末尾に / を付ける（~/work/ であって ~/work ではない）
末尾の / は **（任意のサブディレクトリ）として解釈される
後から読み込まれた設定が優先される（だから仕事用のuser.nameで上書きされる）

動作確認

# 個人用ディレクトリで確認
cd ~/personal/some-repo
git config user.email
# → personal@example.com

# 仕事用ディレクトリで確認
cd ~/work/some-project
git config user.email
# → work@company.com

設定が正しく読み込まれているかは、以下のコマンドで詳しく確認できます。

git config --list --show-origin

これにより、各設定がどのファイルから来ているかが表示されます。

層2: SSH Hostエイリアス + insteadOfによるSSHキー切り替え

SSHキーの切り替えは2つの設定を組み合わせます。

ステップ1: SSH設定ファイルでHostエイリアスを定義

~/.ssh/config に以下を追加します。

# 個人用（デフォルト）
Host github.com
    IdentityFile ~/.ssh/id_ed25519_personal

# 仕事用（エイリアス）
Host github-work
    HostName github.com
    IdentityFile ~/.ssh/id_ed25519_work

解説

Host github.com: github.comに接続するときの設定
Host github-work: github-workという架空のホスト名を定義
- 実際の接続先は HostName github.com（本物のGitHub）
- でも使うSSHキーは id_ed25519_work（仕事用）

これにより、git@github-work:org/repo.gitにアクセスすると、仕事用のSSHキーが使われます。

ステップ2: GitのinsteadOfでURLを自動変換

仕事用リポジトリでは、github.comへのアクセスを自動的にgithub-workに書き換えます。

~/.gitconfig-work に以下を追加します。

[user]
    name = Your Work Name
    email = work@company.com

# SSH形式のURLを変換
[url "git@github-work:"]
    insteadOf = git@github.com:

# HTTPS形式のURLも変換
[url "git@github-work:"]
    insteadOf = https://github.com/

解説

insteadOf: GitがURLを解決するとき、自動的に置換する
例えば git clone git@github.com:org/repo.git を実行すると
- 内部的には git@github-work:org/repo.git に変換される
- SSH設定により github-work は仕事用SSHキーで接続される

動作確認

# 仕事用リポジトリでリモートURLを確認
cd ~/work/some-project
git remote -v
# → origin  git@github.com:company/repo.git (fetch)
#    ↑ 表示はgithub.comのまま

# 実際に使われるURLを確認
git config --get-regexp 'url.*'
# → url.git@github-work:.insteadof git@github.com:

層3: gh関数ラッパーによるgh CLIアカウント切り替え

GitHub CLI（gh）は、v2.40.0から複数アカウントのサポートが追加されました。

事前準備: 両方のアカウントでログイン

# 1つ目のアカウントでログイン
gh auth login

# 2つ目のアカウントでログイン（追加される）
gh auth login

# ログイン状況を確認
gh auth status

gh auth statusを実行すると、ログイン済みの全アカウントと、現在アクティブなアカウントが表示されます。

~/.zshrcへの設定追加

########################################
# GitHub CLI アカウント切り替え（関数ラッパー方式）
# ~/work 配下では仕事用、それ以外は個人用
# アカウント名は ~/.zshrc.local で設定:
#   GH_PERSONAL_ACCOUNT="your-personal"
#   GH_WORK_ACCOUNT="your-work"
########################################
gh() {
  local token
  if [[ "$PWD" == "$HOME/work"* ]]; then
    token=$(command gh auth token --user "$GH_WORK_ACCOUNT" 2>/dev/null)
  else
    token=$(command gh auth token --user "$GH_PERSONAL_ACCOUNT" 2>/dev/null)
  fi

  if [[ -n "$token" ]]; then
    GH_TOKEN="$token" command gh "$@"
  else
    command gh "$@"
  fi
}

~/.zshrc.local でアカウント名を設定

# GitHubのユーザー名を設定
GH_PERSONAL_ACCOUNT="your-personal-username"
GH_WORK_ACCOUNT="your-work-username"

解説

関数ラッパー方式とは:

シェル関数でghコマンドをラップし、実行時にディレクトリをチェックして適切なトークンを使用します。

要素	説明
`gh auth token --user`	指定アカウントのトークンを取得
`GH_TOKEN="..." command gh`	環境変数をそのコマンドにのみ渡す（プロセスローカル）
`command gh`	関数ではなく実際の`gh`コマンドを呼ぶ

commandキーワードのポイント:

command gh "$@"

シェル関数内でghを呼ぶと再帰的に自分自身が呼ばれてしまいます。commandキーワードを使うことで、関数ではなく実際のコマンドを呼び出します。

なぜこの方式を採用したか:

以前はchpwdフック + gh auth switch方式を使用していましたが、複数のターミナルウィンドウで並行作業する際に問題がありました。

旧方式: gh auth switchはグローバル設定を変更するため、片方のウィンドウでの切り替えがもう片方にも影響する
新方式: GH_TOKEN環境変数はそのコマンドの実行時のみ有効（プロセスローカル）なので、他のウィンドウに影響しない

なぜ~/.zshrc.localにアカウント名を書くのか:

アカウント名は個人情報なので、dotfilesリポジトリには含めたくない
~/.zshrc.localはGit管理外のファイルとして運用する

動作確認

# 仕事用ディレクトリで確認
cd ~/work/some-project
gh api user --jq '.login'
# → work-username

# 個人用ディレクトリで確認
cd ~/personal/my-repo
gh api user --jq '.login'
# → personal-username

注意: gh auth statusはグローバル設定を表示するため、関数ラッパー方式では現在の状態を正確に反映しません。実際に使用されるアカウントを確認するには、上記のようにgh api userを使用してください。

全体の動作確認

設定が完了したら、以下の手順で確認します。

# 1. 個人用ディレクトリで確認
cd ~/personal/my-repo
git config user.email          # → personal@example.com
gh api user --jq '.login'      # → personal-username

# 2. 仕事用ディレクトリで確認
cd ~/work/company-project
git config user.email          # → work@company.com
gh api user --jq '.login'      # → work-username

# 3. 実際にpushできるか確認（仕事用リポジトリで）
git push --dry-run             # 仕事用SSHキーで認証される

採用後の結果

うまくいったこと

切り替え忘れがゼロに: ディレクトリ構造で自動判定されるので、意識する必要がない
作業開始の手間が消えた: 以前は毎回「どのアカウントだっけ」と確認していた
トラブルが減った: 間違ったアカウントでコミット/プッシュする事故がなくなった
複数ウィンドウでの並行作業が可能に: 関数ラッパー方式により、仕事用と個人用のターミナルを同時に開いて作業できるようになった

改善の経緯

当初はchpwdフック + gh auth switch方式を採用していましたが、複数のターミナルウィンドウで並行作業する際に問題が発生しました。gh auth switchはグローバル設定を変更するため、片方のウィンドウでの切り替えがもう片方にも影響してしまいます。

そこで関数ラッパー + GH_TOKEN環境変数方式に変更しました。この方式では：

環境変数はコマンド実行時のみ有効（プロセスローカル）
cd時のフックが不要でシンプル
グローバル設定（gh auth status）を変更しない

学んだこと

1. GitとGitHubの認証は別物

「Git設定を変えればOK」と思いがちですが、実際にはSSH認証、GitHub API認証など複数のレイヤーがあります。それぞれを理解して設定する必要があります。

2. 標準機能の組み合わせで実現できる

includeIf、insteadOf、シェル関数はすべて標準機能です。新しいツールを追加しなくても、既存の仕組みの組み合わせで目的を達成できました。

3. UXを追求する価値

「cdするだけ」という体験にこだわりました。設定は複雑ですが、日常の操作はシンプルになります。初期投資と日常のコストのバランスを考えて判断することが重要です。

参考

公式ドキュメント

Astroで技術ブログを構築しました

Tue, 30 Dec 2025 09:00:00 GMT

Zero-Shot Logへようこそ

このブログは Astro で構築されています。

なぜAstroなのか？

パフォーマンス: 不要なJavaScriptを排除し、静的サイトとしての最速のパフォーマンスを実現します。
DX (Developer Experience): React, Vue, Svelteなど好きなフレームワークのコンポーネントを利用できます。
Markdown重視: コンテンツをMarkdownで管理できるため、エンジニアにとって非常に扱いやすいです。

console.log("Hello, Astro!");

これから技術的な知見をどんどん発信していきます！