先に結論を書く。認知負債は、AI がコードを書いた瞬間ではなく、人が考えずに承認した瞬間に生まれる。AI は書く負荷を引き受けた代わりに、読む負荷を人に残した。読むのは重いので、AI の計画や差分は流し見のまま承認される。そこで、コードの中身が人の頭に戻ってこなくなる。

ただ、承認には 2 つの段階がある。考えずに承認すれば、負債は確実に生まれる。そして、理解したうえで承認しても、後で残っていないことがある。冒頭の場面は後者だ。前者には打てる手がある。後者については、私はまだ答えを持っていない。

認知負債（cognitive debt。認知的負債とも書く）は、ソフトウェア工学の研究者 Margaret-Anne Storey が「チームの共有理解が時間とともに侵食されること」と定義した言葉だ。実務の記事では「理解負債」と呼ばれることも多い。

私は 6 月の記事「AIは人を減らさない、守備範囲を広げる」で、技術的負債と意図負債は自動レビューや品質ゲート、ADR でかなり潰せる、厄介なのは AI 以前からある認知負債だ、と書いた。今はそこを一部改めたい。変わった点は 2 つある。意図負債は ADR を書くだけでは潰しきれない。認知負債は AI 以前からある問題だが、AI がその溜まる速さを上げている。一方で、技術的負債は AI のレビューと品質ゲートでかなり減らせるという見立ては変わらない。ただし AI のレビューで減るのはコードの問題で、人の理解は増えない。Storey 自身も論文で「生成 AI は技術的負債を減らしながら、認知負債と意図負債の蓄積を速めうる」と書いている。

AI コーディングで認知負荷と認知負債が同時に増えている

AI は書く負荷を下げたが、読む負荷と、理解が抜けていく速さを上げた。いま現場で起きていることの多くは、この 2 つの組み合わせで説明できる。

私自身、AI に実装を任せた部分は頭に入ってきにくい。それで困った、あるいは困りそうだと感じたのは、変更や障害対応のとき、人に説明しようとしたとき、レビューで承認するとき、設計の選択を迫られたときだ。

この記事で「承認」と呼ぶのは、AI が出してきた計画や差分を受け入れることだ。Plan Mode で実装方針に「はい」と答えるのも、差分を見てマージするのも、どちらも承認である。

承認が形だけになる

コードの生成速度が人の読む速度を超えた。twada さん（和田卓人さん）の講演「負債のメタファと2026年」でも、レビューが形骸化し始めていると指摘されていた。Addy Osmani は「Comprehension Debt」で、「レビューされたコードは理解されたコードだ」という前提はもう成り立たない、と書いている。承認のボタンは押されている。だが、中身を読んで判断した結果とは限らない。

チームの誰もシステムを説明できなくなる

認知負債は、人が辞めなくても溜まる。以前は、メンバーが抜けて理解が失われるのが典型だった。いまは全員がそろったまま、誰も説明できない部分が増えていく。そうなると、変更は当てずっぽうになり、障害対応は博打になる。twada さんの講演の言葉を借りれば、AI も直せない障害が起きたとき、直せる人がいない。責任の空白である。

理解が欠けても速度の指標には表れない

技術的負債はコードを開けば見える。認知負債は見えない。理解の欠け具合を測る指標もまだない。一方で、デプロイ頻度やリードタイムのような速度の指標は、設計の理解を置き去りにしても上げられる。twada さんはこれを「『生産性』を上げたい組織と個人の共犯関係が成り立ってしまう」と表現していた。評価が速さを褒め続ける限り、理解に時間を使う理由は生まれない。

若手にとってはなお厳しい。6 月の記事「AIは若手を奪わない、判断の回数を増やす」で書いたとおり、判断の基礎は自分で判断した回数で育つ。AI の案を承認するだけの毎日では、その回数が増えない。

3 つの負債を「下り」と「上り」で整理する

意図負債は、人の意図がコードになるまでの「下り」でずれる。認知負債は、コードの中身が人の頭に戻る「上り」で抜ける。こう分けると、2 つの負債の重なりと違いが見えやすい。

Storey は負債を 3 層に分けた（arXiv:2603.22106）。

なお、MIT の Kosmyna らも「認知的負債」という言葉を使っている。こちらは LLM に頼ったときの個人の思考力の話で、Storey とは系統が別だ（最後の章で少し触れる）。

意図負債は「下り」でずれる

人の意図が AI を経てコードになるまでに、意図は 3 か所でずれる。

1. 指示の足りない部分を、AI がもっともらしく埋める
2. 実装の途中で、小さな判断を AI が黙って下す
3. 後で読むと、ADR や計画に書かれた意図が、自分のものか AI のものか分からない

3 つ目が特に厄介だ。たとえば、AI に書かせた ADR の「この方式を選んだ理由」の欄を考えてみる。読めば筋は通っている。だが、それが自分で考えて決めた理由なのか、AI が後から補った理由なのかは、もう区別できない。twada さんも、AI が生成したドキュメントに残る「意図」の多くは AI が行間をもっともらしく埋めた結果で、人の判断と見分けがつきにくい、と指摘していた。

だから、ADR を書くだけでは意図負債は潰しきれない。記録は残る。だが、それが人の意図だという保証がない。ここが、6 月に私が楽観しすぎていた点だ。

認知負債は「上り」で抜ける

上りはコードの中身が人の頭に戻ってくる流れだ。自分で書いていた頃は、書くこと自体がこの流れを作っていた。AI に任せると、その流れは承認の場面にしか残らない。承認は、理解が人に戻る最後の関所になる。そこを流し見で通れば、理解は戻らない。

承認で負債が生まれる理由

AI は書く負荷を引き受けた。その分、人には読む負荷が残った。自分で書いていないコードを読んで正しさを確かめるのは、書くより重いことが多い。だから承認は流し見になる。

ここで言う認知負荷は作業中に頭にかかる負担のことだ。負荷はその場の負担で、負債は時間とともに溜まっていくもの。読む負荷が重すぎて流し見になり、流し見の承認が積み重なって負債になる。この記事では負荷と負債の関係をそう捉えている。

書くことは理解する手段でもあった

AI 以前は、自分でコードを書くことで、そのコードを理解できた。Peter Naur は 1985 年の論文「Programming as Theory Building」で、プログラミングの本質は、問題がどう解かれるかという「理論」をプログラマが頭の中に築くことだと論じた。その理論はコードや文書だけでは表しきれない。書く手間と摩擦を通して、この理論が頭の中にできていた。

twada さんは講演で、技術的負債という比喩が生まれた 1992 年と今とを対比していた。1992 年は「人間達の理解が先行し、コードがついてきていない状態」だった。2026 年は「AI によるコード生成が先行し、人間の理解がついてきていない状態」だ。34 年で構図が逆転した。

6 月の記事との線引き

6 月の若手の記事では「手を動かす基礎は AI に任せていい」と書いた。今もそう思っている。シンタックスや定型コードを書く力は任せてよい。

ただ、書くことにはもう一つの役割があった。そのシステムを理解する手段だ。任せてよいのはスキルとしての「書く」で、理解の手段としての「書く」は、任せた時点で失われる。その穴は別の方法で埋める必要がある。

6 月には、AI と壁打ちすれば判断の回数を増やせる、とも書いた。この回数は自分で判断した回数のことだ。AI の推奨を承認しただけの回は、数に入らない。

認知的降伏

AI の出力は流暢で、自信ありげに見える。そのため人は自分で考えずに判断を委ねてしまう。Shaw と Nave は 2026 年のワーキングペーパー（未査読）で、この傾向を「認知的降伏（cognitive surrender）」と呼んだ。twada さんのスライドでは、判断・労力・責任を AI の出力に委ねてしまう傾向と説明されている。

二人は人の思考を速い直感（システム 1）と遅い熟慮（システム 2）に分ける考え方に、AI という外の認知を「システム 3」として加えた。twada さんのスライドの説明では、熟慮は自動では動かない。直感が「何かおかしい」と引っかかったときに、はじめて動き出す。ところが AI の流暢な出力は、この引っかかりを生まない。読み手はそれを詳しい人の意見のように受け取り、AI の答えがそのまま自分の答えになる。

Addy Osmani の紹介によれば、研究は 3 つの実験、参加者 1,372 人で行われた。厄介なのは、AI が間違っていたときでさえ人の自信が上がることだ。だから本人は降伏していることに気づけない。

Osmani は「Cognitive Surrender」で、任せることと明け渡すことを分けている。AI に作業を任せても、答えを自分のものとして持っているなら、それは任せただけ（offloading）だ。AI の出力が気づかないうちに自分の出力になり、自分で答えを組み立てるのをやめたとき、それが降伏（surrender）だという。この区別は次の章で書く線引きに近い。実装の細部は任せてよい。意図と設計の判断まで明け渡すと、降伏になる。

twada さんのスライドには「AI が選択肢を作って人が選ぶだけでは理解は育ちにくい」とある。私にも覚えがある。AI が推奨つきの選択肢を出してくると、私はその推奨を選ぶだけになる。計画も同じで、AI が「この方針でいきます」と出したものを、割とそのまま承認する。この流れで理解のステップを踏まないと、AI の出力を流し見しただけになり、自分のインプットにならない。

承認には 2 つの段階がある

• 考えずに承認すると、負債は確実に生まれる。この記事の対策は主にこの段階に効く。
• 理解して承認したのに、後で残っていない。この段階は最後の章で扱う。

反論: 理解を手放して要るときに作り直せばいいのでは

実装の細部についてはこの反論に賛成する。意図と設計については賛成しない。

人の理解に頼るのをやめようという立場がある。型・テスト・監視で振る舞いを守り、必要になったら AI に説明させて理解し直せばいい、という考え方だ。James Phoenix の「Comprehension Debt Is Refinanceable」は、理解を増やすより、理解を作り直すコストを下げるほうがよいと論じている。

実装の細部なら、私も手放してよいと思う。関数の中身を全部覚えておく必要はない。振る舞いはテストが守ってくれる。euglena1215 さんの「理解をどこまで手放すかは、リスク許容度と仕組みで決まる」も、実装の理解は手放してよく、意図は人の記憶に頼らず残すべきだとしていて、私の立場に近い。

それでも、意図と設計の理解は手放せない。理由は 2 つある。

1 つ目は意図が判断した瞬間にしか残せないことだ。twada さんも、意図を捉える一番よいタイミングは重要な判断を下す瞬間で、後から取り戻すのは難しい、時には不可能だと述べていた。後から AI に説明させても、出てくるのはコードから逆算したもっともらしい理由で、当時の判断そのものではない。

2 つ目は作り直した説明が正しいかを判断する人が要ることだ。その人がいなければ、最初の章で書いた責任の空白に戻る。

ただし、最後の章で書く問題が本当なら、この反論の側に分がある。

個人でできること

下りでは意図を先に書く。上りでは承認する前に自分の言葉で出す。私が一番効いていると感じているのは後者だ。

意図と完了条件を先に書く

AI に渡す前に、何をしたいのか、何ができたら終わりなのかを、自分の言葉で書く。Qiita の記事「【未来を解説】AIでエンジニア格差を生み出す質とスピードの考え方」も、まずこの 1 つを勧めている。

書く形は何でもいい。例を置いておく。最後の欄は下りで起きる「途中の小さな判断を AI が黙って下す」を減らすためのものだ。

## やりたいこと

- 何を、なぜ変えるか（1〜2 行）

## 完了条件

- 何ができたら終わりか。どう確かめるか

## 決めていること / 決めていないこと

- 決めている: 使う方式、触らないファイルなど
- 決めていない: AI に提案してほしいこと。勝手に決めずに聞いてほしいこと

大きい変更のときは計画を図解させる

私は大きい変更だと感じたときや ADR を書くときに、計画が何をしようとしているのかを AI に図解させ、それを読んでから進めている。基準は決めておらず、自分の感覚で判断している。毎回やると重いからだ。twada さんも講演の口頭で、毎回の理解度チェックは運用コストが重く、図解に寄せていった、という趣旨の話をしていた（スライドには載っていない。私の聞き取りによる）。

頼み方の例を置いておく。

実装に入る前に、この計画を図で説明してください。
- 変更前と変更後で、モジュールどうしの関係がどう変わるか
- データがどこから来て、どこへ行くか
- この計画の中で、私に確認せずに決めたことがあれば列挙する
図は Mermaid で。説明は図 1 枚につき 3 行まで。

ただし、図は分かった気にさせやすい。twada さんのスライドにも、豊かな形式のほうが理解は進むが、同時に認知的降伏のリスクも高まる、と注意がある。図を読んで終わりにしない。

承認する前に自分の言葉で説明する

図を読んだら、承認する前に、計画が何をするのかを自分の言葉で書いてみる。3 行でいい。書けなければ、まだ理解していない。

twada さんのスライドはこれをプロテジェ効果として紹介している。他者に説明しようとすると、自分の理解の足りなさがはっきりし、知識が定着して本当の理解につながる。私はアウトプットが認知負債を埋めるのに一番有効な方法だと感じている。

チームでできること

個人の対策をチームの仕組みに移す。理解を関門にする、説明し合う場を作る、評価の物差しを変える、の 3 つだ。

理解を関門にする

大きい変更はマージする前に、変更した人が中身を説明できるかを確かめる。twada さんのスライドでも、Plan Mode を抜けるときに理解をチェックする試みが紹介されている。全部の PR でやると回らないので、対象は大きい変更に絞る。個人の図解と同じ考え方だ。

説明し合う場を作る

設計の説明会でも、ペア作業でもいい。誰かに説明する機会をチームで用意する。個人のアウトプットと同じ効果があるうえに、一人の頭の中にあった理解がチームのものになる。認知負債はチームの共有理解の問題なので、ここが一番効くはずだ。

評価の物差しを変える

速度を上げても、理解が欠けていれば意味がない。理解は測りにくいが、速さだけを褒めるのはやめられる。たとえば振り返りで「何件出したか」と一緒に「その変更を説明できるか」を聞く。それだけでも、理解に時間を使う理由ができる。

最初の章の課題とこの章の対策はこう対応する。関門と説明の場は理解を人に戻す上りに効く。評価の物差しは意図を書く時間と理解する時間を作るので、上りと下りの両方に効く。

理解して承認しても残らない問題

最後に、答えの出ていない問題を書いておく。

図解させて AI の出力を読み、その場では理解したうえで承認する。それでも後になって、あれはどういう仕様だったっけ、と振り返ることがよくある。ここまでの対策は承認の時点の理解には効く。だが、時間がたっても残ることまでは保証しない。

これは私だけの話ではないかもしれない。MIT の Kosmyna らの研究（arXiv:2506.08872）では、LLM を使ってエッセイを書いた群の 83.3%（18 人中 15 人）が、書いた後に自分の文を正しく引用できなかった。検索エンジンを使った群と、何も使わなかった群では、どちらも 11.1%（18 人中 2 人）だった。未査読のプレプリントで、被験者は 54 人、課題は短いエッセイなので、そのまま開発に当てはめることはできない。ただ、自分で関わったはずのものが手元に残らないという点は、私の感覚に近い。

これが本当なら、前の章の反論の側に分がある。理解は守っても残らないのだから、作り直せるようにしておくほうが現実的だ、と。それでも私は、意図と設計は手放せないと考えている。では、残らない理解をどう残すのか。あるいは残らない前提で意図をどう守るのか。そこはまだ分からない。

まとめ

認知負債は、AI がコードを書いた瞬間ではなく、人が考えずに承認した瞬間に生まれる。意図は下りでずれ、理解は上りで抜ける。実装の細部の理解は手放してよいが、意図と設計の理解は手放せない。

次に大きい変更を AI に任せるとき、2 つだけ試してほしい。

1. 渡す前に、意図と完了条件を 3 行で書く
2. 承認する前に、計画を自分の言葉で 3 行で説明する

どちらも考えずに承認するのを防ぐためのものだ。理解して承認しても残らない方は、私もまだ悩んでいる。

参考文献

• 和田卓人「負債のメタファと2026年」技術的負債に向き合うConference 2026、2026-09-17
• Margaret-Anne Storey, "From Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI", arXiv:2603.22106, 2026（ACM Queue 版）
• Steven D. Shaw, Gideon Nave, "Thinking—Fast, Slow, and Artificial: How AI is Reshaping Human Reasoning and the Rise of Cognitive Surrender", 2026（ワーキングペーパー、未査読）
• Nataliya Kosmyna ほか, "Your Brain on ChatGPT: Accumulation of Cognitive Debt when Using an AI Assistant for Essay Writing Task", arXiv:2506.08872, 2025（プレプリント、未査読）
• Peter Naur, "Programming as Theory Building", Microprocessing and Microprogramming 15(5), 1985
• Addy Osmani, "Comprehension Debt", 2026
• Addy Osmani, "Cognitive Surrender", 2026-05-05
• James Phoenix, "Comprehension Debt Is Refinanceable", 2026
• euglena1215「理解をどこまで手放すかは、リスク許容度と仕組みで決まる」2026-09-27
• Watanabe Jin「【未来を解説】AIでエンジニア格差を生み出す質とスピードの考え方」Qiita

この記事は、デザイナーのいない個人開発で、この「ずれ」を止めるまでの記録だ。やったことは 3 つある。

1. 作る: AI に画像で案をいくつも出させ、自分で選んで画面を作り直した
2. 見直す: 作り直したら、デザインファイルとコードで色や文字サイズの決め方が食い違っていたので、どちらを正とするか決め直した
3. 守る: AI が作った画面がデザインから外れたら、自動で止まる仕組みを入れた

3 つ目の仕組みを、デザインハーネスと呼んでいる。AI に画面を作らせても、デザインから外れないようにする仕組み全体のことだ。作らせる前に守るべきデザインを渡し、作った後に外れていたら止め、同じ指摘が続いたら仕組みの方を直す。

作っているのは学習アプリで、画面の実装の大半を Claude Code と Codex に任せている。技術スタックは Next.js、Tailwind CSS v4、shadcn/ui だ。作り直しから検査の仕組みまでは、2026 年 9 月末から 10 月 8 日までの約 2 週間で組んだ。画面のスクリーンショットは載せない。ずれを止める方法だけ知りたい場合は、「見直す」の章から読んでも話は通じる。

作る: 画像で案を出し、選んで、作り直す

画面の方向は、AI に画像で何案も出させて自分で選ぶと早く決まった。ただ、画像は方向を決める材料で、寸法の仕様ではない。画像を仕様のように扱うと、できた画面が選んだ案から離れる。

継ぎ足しの見た目から出るために

作り直す前の画面は、機能を足すたびに継ぎ足してきた見た目だった。部品を少しずつ直しても、元の見た目の延長からは出られない。そこで今の画面をいったん忘れ、画面ごとに何を見せるかを書いた設計書から考え直した。

方向を探すなら、コードより画像の方が速い。1 案を数分で出せて、並べて比べられる。使ったのは、OpenAI が 2026 年 6 月に出した Codex の Product Design プラグインだ[^openai]。画面の方向を画像で出し、人が選ぶまで実装に進まない作りになっている。既定では 3 案だが、もう少し案が欲しかったので 9 案まで出させた。

使ってみて、1 画面だけで選ばない方がよいと分かった。ホームだけで選ぶと、ほかの画面に広げたときに崩れる案を拾ってしまう。候補ごとに主な画面を何枚か並べてから選んだ。別の AI に評価させるのも役に立った。Codex が出した案を Claude に見せて使い勝手の観点で比べさせると、「A を土台にして、B の現在地の見せ方を足す」のように、2 案を組み合わせる提案が返ってきた。1 案をそのまま選ぶより、こちらの方がしっくりきた。

全画面で案を出す必要はなかった。画像で方向を探したのは、トップページやダッシュボードのような、新しい見せ方が要る画面だけだ。先に作り直した部品で組める画面は、画像を作らずにそのまま作った。

画像は測って、デザインファイルに写す

選んだ案は、そのまま実装させずにデザインファイルに写した。デザインツールは、Figma の代わりに Pencil を使っている。AI が MCP（AI が外部のツールを操作するための接続の規格）経由でファイルを読み書きできるツールで、ファイルの拡張子は .pen だ。

写すときは、採用案の画像をデザインファイルの枠に重ね、左右の比率、部品の高さ、文字の大きさ、余白を測る。画像を見ながら「それっぽく」描かせると、少しずつ別物になる。測って写す方が、結局は早かった。写した後は、採用案とデザインファイル、デザインファイルと実際の画面の 2 段で比べ、ずれは 3px 以内に収める。

画像から動く試作を作ることもでき、最初は作って触ってみた。ただ、試作は本番とは別のコードなので、育て始めると画像・試作・本番の 3 つを見比べ続けることになる。試作は確認に使ったら捨てた。

見直す: 作り直したら、デザインファイルとコードが食い違っていた

画像から作り直すと、色や文字サイズは画像から推し量るしかない。作り直しが終わってから見直すと、デザインファイルとコードと文書で、同じものの名前や値が食い違っていた。最終的に、見た目・値・振る舞いの置き場所を分け、値はコードを正にした。

見えた食い違い

たとえば次のようなものだ。

• デザインファイルで accent と呼んでいた色は、コードでいう主なボタンの色だった。ところが shadcn/ui では、accent はホバーしたときの背景の色を指す。このままだと、AI に「accent の色で」と頼んだとき、どちらの色が出るか分からない
• 本文の文字サイズが、デザインファイルとコードで違っていた
• 色や文字サイズの一覧を写した文書があり、「変えたら一緒に直す」と決めていたのに、追いついていなかった

Tailwind CSS にも落とし穴があった。存在しないクラス名を書いてもエラーにならず、そのクラスは無視される。AI はそれらしいクラス名を作るので、効いていない指定が画面に残っていても、書かせた本人には見えにくい。

何を正にするかを分ける

そこで、正とするもの（正本）を 3 つに分けた。デザイナーがいないので、値の正はコードに置いている。

• 見た目（配置・余白・どの色を使うか）: デザインファイル（.pen）。見た目はここで先に決める
• 値（色のコードや文字サイズの数値）: コード。Tailwind CSS v4 で値を定義する @theme という場所に置く。ここに書いた名前が、そのままクラス名として使える
• 振る舞い（押したとき、無効のときなどの部品の動き）: Storybook。部品を 1 つずつ描いて確かめるカタログだ

値をコードに置いたのは、デザイナーがいないことのほかに、影の濃さやコンテナの幅のように、デザインファイルに無い値があったからでもある。デザイナーがデザインファイルを持つチームなら、デザインファイルを正にしてコードを生成する方が合うかもしれない。

デザインファイルとコードで値が食い違ったら、コードに合わせてデザインファイルを直す。この 2 つは名前をそろえ、同期テストを置いた。同じ名前の値が両方で一致しているかを確かめるテストで、食い違うと CI（変更のたびに自動でテストを回す仕組み）が落ちる。値を写した文書はやめた。人もエージェントも追いつけなかったので、写しを持つこと自体をやめた方が早い。

AI が勝手な色を使えないようにする

Tailwind には、最初から青や赤などの色がたくさん入っている。AI はこれを気軽に使うので、決めていない青が増える。そこで標準の色を外し、「主なボタンの色」「本文の文字の色」のような、用途の名前が付いた色だけを使える状態にした。用途の名前の裏には具体的な色が付いているが、その具体的な色はクラス名としては書けない。

ただ、これだけでは bg-[#2455cf] のように色を直接書く書き方（任意値）は防げない。そこは次の章の lint で止めている。

入口の文書には値を書かない

DESIGN.md は、人とエージェントの両方が最初に読む、デザインの説明書だ。書いているのは、どこが正本か、目指す印象（落ち着いていて、安っぽくない）、色の使い分け、やってよいこととよくないことで、値は書かない。書けばそれは写しになり、また追いつかなくなる。値や部品は、コードや Storybook を見に行かせる。

守る: デザインハーネスで、外れたら止める

正本を決めて渡しても、AI はときどき外れる。だから、作った後に外れていたら止まる仕組みを入れた。止めるのはまず機械で、AI の評価は人の判断材料にとどめる。

言葉の出どころと、各社の事例

デザインハーネスという言葉は、ハーネスエンジニアリングから来ている。AI エージェントの周りを設定や検査で固めて、外れにくくする考え方だ（以前まとめた記事）。それをデザインに当てはめた。私が見つけた最も早い用例は、こぎそ氏の note（2026 年 5 月）だった[^kgsi]。

組む前に各社の公開事例を調べると、多くは「作らせる前に渡す」側の話だった。「作った後に止める」側を中身まで出している例は少ない。私の環境も同じで、渡す側はあったが、止める側が手薄だった。この章では、止める側を中心に書く。

機械で止める

機械の検査は、図 1 にも書いた lint・a11y・見た目の比較だ。

• lint（コードを機械的に調べ、決まりに反した書き方を落とす仕組み）: 用途の名前に無い色やクラス名、決めていない文字サイズ、任意値の色を書くと落ちる。ボタンや入力欄を、共通の部品を使わずに直接書いたときも落ちる
• a11y（アクセシビリティ）: 文字と背景のコントラストなどを、部品ごとに自動で検査する
• 見た目の比較: 主な画面のスクリーンショットを撮って前回と比べ、変わっていたら知らせる。撮る環境は Docker で固定している。環境が変わるとフォントの描かれ方が変わり、それだけで差分が出るからだ

見た目の比較だけは性質が違う。差分を見つけるのは機械だが、それが意図した変更かどうかは、人が画像を見て決める。

AI の評価役は、合否に使わない

機械の検査では、「共通部品で済むのに新しく部品を作っていないか」「読み込み中の表示が抜けていないか」は分からない。そこで、AI に評価させるスキルを作った。変更前後の画面を撮り、3 体の評価役が互いの答えを見ずに、観点ごとに判定する。観点は、DESIGN.md の原則を 11 個の判定項目（DC-01〜11）に書き直したものだ。判定は 2 票以上そろったものを採り、割れたら「割れた（split）」と書く。

この結果は、合否（変更を通すか止めるか）には使っていない。指摘を採るか採らないかは、人が決める。AI の評価には、まだ任せきれないところがあるからだ。30 の UI を AI に評価させた研究では、人の採点との相関は 0.7 前後で、著者は補助として使うべきだとしている[^uijudge]。それに 3 体とも同じモデルなので、1 回ごとの揺れは多数決で少し抑えられても、モデルの癖は 3 体そろって同じ方向に出る。

観点は、本来ならデザイナーが決めて言葉にするものだと思う。デザイナーのいない私は自分で書いたが、変えるのは人に限っている。評価される変更と一緒に観点を書き換えると、スキルが止まるようにしてある。指摘を通すために観点を緩める、という抜け道を塞ぐためだ。

これまで回したのは 2 回で、無効状態のボタンの見た目を直すきっかけにはなった。役に立つと言い切るには、まだ回数が足りない。

繰り返す指摘は、仕組みに上げる

ハーネスは最初から完成させるものではないと考えている。同じ指摘が繰り返されたら、注意書きで終わらせずに lint やテストへ上げる。

たとえば、ボタンや入力欄を直接書くと、共通部品とよく似た別物ができる。何度も指摘していたので、lint で止めるようにした。入れた時点で、刷新を終えた画面にも 15 か所残っていた。いきなり全部は直さず、理由を書いた例外にして入れ、少しずつ部品に置き換えて、いまは 8 か所まで減っている。

個人でやってみた限界

• 試したのは個人の 1 プロダクトで、画面の数もそう多くない。ダークモードや複数のブランドは、まだ扱っていない
• 「落ち着いているか」「安っぽくないか」のようなプロダクトらしさは、AI の評価役に見させているが、判定できているとは言えない
• 見た目の比較と評価役は Docker に、デザインファイルの編集は macOS で動く Pencil に頼っている
• 最後に決めるのは人なので、品質を自動で保証する仕組みではない。1 か月の計測を始めたところで、効果を示す数字もまだない

チームに持ち込むなら、評価の観点を誰が持ち、誰が変えられるかを先に決めたい。デザイナーがいるなら、観点やプロダクトらしさの定義はデザイナーが持ち、AI の評価役はその補助にするのが自然だと思う。観点の持ち主を決めておかないと、指摘を通すために観点を緩める変更が出てくる。

何から始めるか

これから始めるなら、次の順番を勧める。

1. 値の正を 1 か所に決める: Tailwind CSS v4 なら、@theme に用途の名前で色や文字サイズを書く。同じ @theme の中に --color-*: initial; と書くと、標準の色が外れる。決めていないクラス名は、ESLint のプラグイン eslint-plugin-tailwindcss で止められる。デザインファイルが無くてもできる
2. a11y の検査を CI で回す
3. 主な画面を数枚、見た目の比較に入れる。撮る環境は CI と同じにする
4. デザインの原則を観点にして、AI の評価役を足す。合否には使わない

画像で方向を出すのは、新しい見せ方が要る画面だけで足りる。

まとめ

• 画像で何案も出して選ぶと、作り直しの方向は早く決まる。ただし画像は方向で、仕様ではない。採用案は測ってデザインファイルに写す
• 作り直すと、デザインファイルとコードが食い違う。見た目・値・振る舞いの正本を分け、写しの文書をやめ、食い違いは同期テストで見つける
• 外れたら、まず機械で止める。AI の評価役は人の判断材料にして、繰り返す指摘は lint に上げる

1 か月の計測が終わったら、数字と、チームに持ち込むかどうかを、また書くつもりだ。

私は発表の数日後に、公開されているmodを3つ入れた。この記事では、modsでできること、入れた3つのmodの使い方、入れる前に中身を確かめる手順を順に書く。

先に結論を書く。

• modsはpluginに入れて配られる。入れて使うだけならTypeScriptは書かなくてよく、/pluginのコマンド2行で入る。v2.1.287以降は既定で有効
• settings hook（settings.jsonに書く従来のhooks）・skill・MCPと違い、modsはClaude Codeの中で動く。そのため画面に描いたり、組み込みの機能を差し替えたりできる
• modはサンドボックスの外で、自分のユーザー権限で動く。入れる前にclaude plugin validateで、どのイベントを拾い、どのAPIを呼ぶかを見る
• 私が入れたのはprompt-rail（プロンプトの目次）、md-prompt（入力欄のMarkdownに色を付ける）、qa-guide（Claudeの質問に解説を添える）の3つ。最初の1つなら、呼ぶAPIが3つだけのmd-promptが試しやすい

検証環境はmacOSとClaude Code 2.1.289（ターミナル、"tui": "fullscreen"）で、2026年10月5日に確認した。

Claude Modsとは: Claude Codeの中で動き、画面と挙動を変えられる関数

Claude Codeは、ツールを呼ぶ、権限を確認する、画面の一部を描く、といった動作のたびにイベントを出す。modはこのイベントに差し込む関数で、イベントの前・後・代わりに処理を走らせられる。公式ブログは、1つの関数でできることとして次の例を挙げている。

• モデルに届く前にプロンプトを書き換える
• ツール呼び出しを止める、書き換える、やり直す
• 権限リクエストを承認・拒否する
• ツールの出力から秘密情報を消してからClaudeに読ませる

画面にも手を入れられる。会話の横にペインを開く、入力欄の上に帯を出す、ツールの結果やClaudeの質問ダイアログの表示を差し替える、ボタンや入力欄を置く、といったことができる（公式ドキュメント）。

settings hook・skill・MCPとの違い

公式ドキュメントは、modsをsettings hook・skill・MCPサーバーと並べて比べている。mods以外の3つを1行ずつ説明しておく。

• settings hook: settings.jsonに書く従来のhooks。ツール呼び出しの前後などに、シェルコマンドやHTTPリクエスト、プロンプトを走らせる
• skill: SKILL.mdに書いた手順書。Claudeが読んで、その通りに作業する
• MCPサーバー: 外部のプロセスやサービスで、Claudeに新しいツールを渡す

公式ドキュメントの比較表を要約した。

settings hookもツールの引数を書き換えられるので、書き換えられるかどうかは分かれ目にならない。違いは、modがClaude Codeのプロセスの中で動くことにある。そのため、画面を描くことも、組み込みの機能を差し替えることもできる。実際に/diffはmodとして作り直されていて、/pluginから無効にしたり、自作のものに置き換えたりできる。

私が入れたmod 3つ

私が入れた3つのmodは、どれも作者のGitHubリポジトリがマーケットプレイスを兼ねていて、2行のコマンドで入る。入れ方は次の章に、入れる前の確認も含めて書いた。

prompt-rail: 長いセッションで「さっきの指示」に戻れる

1つのセッションで何十回もやり取りしていると、最初に出した条件をどう書いたかを確かめるために、スクロールで遡ることになる。prompt-railは、セッション内で自分が送ったプロンプトを、入力欄の上に並ぶ短い線（レール）として表示する。線にマウスを乗せるとそのプロンプトとターンの要約が出て、クリックすると会話のその位置まで飛ぶ。

主な使い方は次の通り。

• /prompt-rail horizontal（入力欄の上、既定）と/prompt-rail vertical（会話の横のペイン）で表示を切り替える。/prompt-rail offで隠す
• /prompt-rail next / prev / first / lastで前後のプロンプトへ飛ぶ。/prompt-rail 12は12番目へ、/prompt-rail find <語>はその語を含む最新のプロンプトへ飛ぶ
• ~/.claude/keybindings.jsonにキーを割り当てると、Claudeの作業中でも飛べる

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+k": "command:prompt-rail-prev",
        "meta+j": "command:prompt-rail-next"
      }
    }
  ]
}

READMEは、マウスで操作するなら"tui": "fullscreen"を推奨している。Claude DesktopのCodeタブでは、レールとプレビューは出るが、クリックしてもその位置へは飛べない。Desktopがmodに会話のスクロールを許していないためだ（READMEに記載）。

md-prompt: 入力欄に書いたコードブロックや表に色が付く

プロンプトにコードや表を書いて指示するとき、入力欄は素のテキストなので、どこからどこまでがコードかが見分けにくい。md-promptは、入力欄のMarkdownに打った端から色を付ける。```で始めたコードブロックは、閉じる前から背景つきのカードになり、言語に応じてシンタックスハイライトされる。見出し、太字、リスト、チェックボックス、引用、表、リンクにも色が付く。

md-promptは色を付けるだけで、文字は変えない。送信されるのは打った文字そのままで、``` や **などの記号も消えずに薄く表示される。

• /md-prompt on / off / toggleで切り替える。/configで「Markdown」を検索しても切り替えられる
• 複数行の下書きは、\のあとにEnterで改行する（ターミナルが対応していればShift+Enterでもよい）

4行以上を貼り付けた部分には色が付かない。Claude Codeが貼り付けを[Pasted text #N +M lines]に畳み、md-promptが受け取る編集イベントが発生しないためだ（READMEに記載）。1〜3行の貼り付けには色が付く。

qa-guide: Claudeの質問に、文脈と選択肢ごとの影響を添えてくれる

ClaudeがAskUserQuestionで選択肢を出してきたとき、セッションが長いと、何の話だったかを思い出すために会話を遡ることがある。qa-guideは、質問ダイアログの横にペインを開き、次の内容を表示する。

• AIによる解説: いまClaudeが従っている指示の要約、なぜ今この質問をしているか、選択肢ごとに何が起きるか、おすすめ1行
• 自分が直近に入力した指示
• 質問の直前にClaudeが書いた説明の末尾

ターミナルの幅が144列以上あると、ペインは質問のたびに自動で開く。狭いときは/qa-guideで開ける。ペインにフォーカスを移す（Ctrl+X → Tab、またはクリック）と、p / nで過去の質問、lで最新の質問、hで履歴一覧を表示できる。aを押すと、AI解説のON / OFFが切り替わる。表示言語は/configのlanguageでauto / en / jaから選ぶ。

AI解説は、質問1件ごとにモデル呼び出しを1回増やす。セッションのプロンプトキャッシュを使えるときは安く済むが、無料ではない。気になるなら、ペインでaを押すと次の質問からAI解説が止まる（すでに始まった呼び出しは止まらない）。qa-guide自身は独自の通信をせず、質問や回答をディスクに書かない。ただしAI解説の追加リクエストでは、会話や質問文がClaude Code経由でモデルに渡る（READMEに記載）。

安全に入れる手順: 入れる前にclaude plugin validateで中身を見る

modはClaude Codeの中で、自分のユーザー権限で動く。公式ドキュメントは、modが読み込まれたあとにできることとして、次を挙げている。

• 自分のアカウントで読める範囲のファイルの読み書き、プログラムの起動、ネットワーク通信
• 環境変数や設定ファイルの読み取り（そこに置いたAPIキーも含む）
• 送ったプロンプトとClaudeのツール呼び出しをすべて見る、書き換える
• ツール呼び出しを、確認ダイアログが出る前に承認する
• 自分のプランやAPIキーでモデルを呼ぶ

Claude Codeのサンドボックスを有効にしていても、隔離されるのはClaudeが実行するBashコマンドで、modが起動したプロセスはサンドボックスの外で動く。そこで、入れる前にclaude plugin validateで、そのmodがどのイベントを拾い、どのAPIを呼ぶかを確かめる。validateはコードを実行せずに読むだけなので、入れる前に使える。

手順

prompt-railを例に書く。

1. マーケットプレイスを追加する。この時点ではまだmodは入っておらず、リポジトリが~/.claude/plugins/marketplaces/oikon48/に取得される

   /plugin marketplace add oikon48/prompt-rail
   

2. シェルでmodのディレクトリをvalidateする。mod本体の場所は、リポジトリの.claude-plugin/marketplace.jsonのsourceに書かれている（今回の3つはどれもplugins/<mod 名>）

   claude plugin validate ~/.claude/plugins/marketplaces/oikon48/plugins/prompt-rail
   

3. 出力のhooks:とcalls:の行を読み、納得できたら入れる

   /plugin install prompt-rail@oikon48
   

4. インストール後の案内に従って有効にする。Run /reload-plugins to activate.と出たら/reload-pluginsを実行するか、新しいセッションを始める（prompt-railのREADMEは新しいセッションを案内している）。シェルから入れた場合は、開いているセッションで/reload-pluginsを実行する。/pluginを開くと、タブの下に1 mod active · prompt-railのような行が出る

ほかの2つは次のコマンドで入る。

/plugin marketplace add nogu66/md-prompt
/plugin install md-prompt@nogu66

/plugin marketplace add aieo-product/claude_qamods
/plugin install qa-guide@claude-qamods

出力の読み方

hooks:の行はそのmodが受け取るイベント、calls:の行はコードが呼ぶmods APIの一覧だ。modがファイルやプロセス、ネットワークに触るには必ずmods APIを通るので、calls:を見ればできることの範囲がわかる。公式ドキュメント（組織向けの管理ページ）が見ておくべきものとして挙げている名前のうち、主なものを表にした。

3つのmodの実際の出力

私の環境で3つをvalidateした結果と、それを見てどう判断したかを書く。

md-promptは、calls:が3つしかない。コマンドの登録、自分の設定の書き込み、ログの出力だけで、ファイル・プロセス・ネットワークには触らない。

❯ ./register.tsx hooks: session.start, command.run{command=md-prompt}, prompt.edit, prompt.fill
❯ ./register.tsx calls: $.command.register, $.config.set, $.ui.log

prompt-railには$.process.spawnと$.fs.readが出る（以下はcalls:行の抜粋）。

❯ ./index.tsx calls: $.clock.after, $.command.register, $.config.set (via writeMode),
  $.fs.read (via readTranscript), $.fs.stat (via readTranscript),
  $.process.spawn (via streamRows), ..., $.ui.scroll (via jumpTo), $.ui.toast

プロセスを起動するので、ソースのstreamRowsを読んだ。起動しているのはtail -c +<位置> <会話ログのパス>で、セッションの会話ログ（transcript）の続きを読んでプロンプトの一覧を作っているだけだった。

qa-guideには$.model.forkと$.model.completeが出る。前の章で書いた、質問ごとのモデル呼び出しがこれにあたる。$.env.getで読むのはLANGとLC_ALLだけで、表示言語の自動判定に使っている（以下も抜粋）。

❯ ./register.tsx calls: $.clock.now, $.command.register, $.config.list (via resolveLang),
  $.env.get (via resolveLang), $.model.complete, $.model.fork, $.session.messages, ...
❯ ./register.tsx env reads: LANG, LC_ALL

validateでわからないこと

validateの出力は、コードが呼ぶAPIの一覧で、安全の保証ではない。prompt-railの$.process.spawnのように、何を起動するかはソースを読まないとわからない。更新すると中身が変わるので、更新のたびに見直す。/plugin marketplace update <マーケットプレイス名>で取得元を新しくしたら、もう一度validateして前の出力と比べる。問題がなければ、/plugin update <mod 名>@<マーケットプレイス名>で入れている版を更新する。公式以外のマーケットプレイスは自動更新が既定でオフなので、この順番で更新できる。自動更新をオンにすると、validateを挟まずに新しい版が入る。

自分の権限設定（settings.jsonのpermissions）で守れる範囲にも限りがある。denyルールがかかるのはClaudeのツール呼び出しで、mod自身の$.fs.readや$.process.spawnには効かない。Read(.env)をdenyしていても、modは$.fs.readでそのファイルを読める。また、ツール呼び出しを承認するmodは、askルールで確認が出るはずの呼び出しや、自分のPreToolUse hookが止めた呼び出しも承認できる。auto modeでは、modが承認した呼び出しは分類器のチェックを通らずに実行される。managed settingsのない端末で、Team / Enterpriseプランでサインインしていない場合（個人のプランなど）は、denyルールで拒否される呼び出しもmodが承認できる（権限のドキュメントに記載）。

チームで使う場合

組織でClaude Codeを配っている場合は、管理者がmanaged settingsでmodを制限できる（公式ドキュメント）。

• Team / Enterpriseプランでサインインしている端末や、managed settingsがある端末では、既定で組み込みのガードsec-defaultが最初に読み込まれる。このガードがあると、ユーザーが入れたmodはdenyルールで拒否された呼び出しを承認できない。ただし管理者がallowModsToOverrideDenyRulesを有効にすると、この制限は外れる
• managed settingsでこのガードのオプションallowManagedModsOnlyを有効にすると、組織のものとして配られたmodと組み込みのmod以外は読み込まれなくなる（どのmodが組織のものと数えられるかは公式ドキュメントに条件がある）
• strictKnownMarketplacesで、入れられるマーケットプレイスを絞れる
• disableSideloadFlagsで、--plugin-dirや--plugin-urlでの読み込みを禁止できる

会社のマシンに入れるなら、先に社内のルールと、これらの設定が入っているかを確認したほうがいい。

外し方と、表示されないとき

modを止める方法は、範囲によって3つある。

• 1つだけ止める: /pluginのInstalledタブで、そのpluginを無効化またはアンインストールする
• 1セッションだけ、入れたmodを全部止める: claude --safe-modeで起動する（mod以外のカスタマイズも止まる）
• 常に、入れたmodを全部止める: ~/.claude/settings.jsonに"disableAllHooks": trueを書く。settings hookと独自のステータスラインも止まる。組織が管理しているものは動き続ける

どちらの方法でも、/diffなどの組み込みのmodは止まらない。組み込みのmodは、無効にできるものだけ/pluginのInstalledタブで個別に止められる。

入れたのに何も表示されないときは、次を確認する。

• バージョン: modsはv2.1.287以降で動く。claude --versionで確かめる
• ワークスペースの信頼: Claude Codeは、信頼していないディレクトリではmodのコードを読み込まない。作ったばかりのディレクトリで起動したときに起きやすい（md-promptのREADMEに記載）
• ターミナルの幅: ユーザーが開いていないペインは、ターミナルが144列以上のときだけ自動で開く。一度開いたあとは110列から開く
• 使っている場所: 描画されるのはターミナルとClaude DesktopのCodeタブ（WSLのセッションを除く）だけ。VS Code拡張のチャット欄とclaude -pでは、modのフックは動くが画面には何も出ない。クラウドセッションでは、pluginがセッションに引き継がれた場合だけフックが動き、描画はされない

なお、早期アクセス期に書かれたREADMEには、~/.claude/settings.jsonにCLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1を書く手順が残っている。v2.1.287以降はこの環境変数を無視するので、書かなくてよい。書いてあれば消してよい。

自分で作るなら

Claude Codeのセッションで、ほしいmodの内容を説明すると、Claudeが組み込みのplugin-authoringスキルを使ってコードを書く。最初のファイルを保存したときにホットリロードを有効にするか聞かれ、有効にするとそのセッションで動く。自分でコードを書く場合は、公式の入門ガイドと、Anthropicのサンプル集がわかりやすい。

公開されているmodを自分用に直すのも手だ。私はyash-gadodia/claude-modsのreceipt（MITライセンス）をもとに、turn-receiptというmodを作って使っている。ターンごとに編集とコマンド実行の件数をフッターに出し、編集したのに何も実行していないターンには⚠ no runを付ける。何も実行せずに「修正しました」と完了を宣言したときは、次のスピナーにunverified claim pendingを出す。元のmodから、何を「実行」と数えるかの判定を変え、日本語の完了宣言も拾えるようにした。

まとめ

modsは、Claude Codeの画面と挙動を自分の使い方に合わせるための仕組みだ。入れて使うだけなら、/pluginのコマンド2行で済む。ただ、中身は自分の権限で動くコードなので、入れる前にvalidateの出力を見る。プロセスの起動やネットワーク、モデル呼び出しが出ていたら、ソースの該当箇所を読む。

まだ入れていないなら、呼ぶAPIが少ないmd-promptから試すのがいい。

1. /plugin marketplace add nogu66/md-promptを実行する
2. シェルでclaude plugin validate ~/.claude/plugins/marketplaces/nogu66/plugins/md-promptを実行し、出力を見る
3. /plugin install md-prompt@nogu66で入れ、新しいセッションの入力欄にコードブロックを書いてみる
4. 合わなければ/pluginのInstalledタブで無効にする

settings hookやCLAUDE.mdの設定はハーネスエンジニアリングの記事に、普段使っている道具はツールチェインの記事にまとめている。

私が開発している Web アプリは、Next.js（frontend）、Go（backend）、Python（AI 用の API）、PostgreSQL、ベクトル DB を Docker Compose で動かしている。これまでは worktree を作るときのスクリプトでポートをずらしてしのいでいたが、2026 年 9 月にこれをやめ、共有のリバースプロキシでホスト名に振り分ける構成に変えた。この記事では、その構成を「何を共有し、何を worktree ごとに分けるか」でまとめる。

先に結論を書く。

• 全 worktree で 1 つを共有するもの（入口のリバースプロキシ、PostgreSQL）と、worktree ごとに分けるもの（アプリのコンテナ、依存、ベクトル DB）を分ける
• HTTP のポートは worktree ごとにずらさない。ホストに開くのはプロキシの 3000 番だけにして、http://<プロジェクト名>.localhost:3000 のホスト名で各 worktree に振り分ける
• DB は共有ネットワークに 1 つ置き、どの worktree の backend も同じ接続先 db:5432 で参照する。ただし、互換性のない migration をブランチごとに並行して試す使い方には向かない
• ポートずらしの頃と比べて、どの方法で作った worktree も同じ手順で起動でき、URL を見ればどの worktree か分かるようになった

検証環境は macOS、OrbStack（Docker 29.4、Compose 5.1.2）、Traefik v3.6 で、2026 年 9 月 29 日に確認した。Windows（WSL2）では試していない。

やりたいこと: 各 worktree のアプリを同時に起動して確かめたい

git worktree は、1 つのリポジトリから作業ディレクトリを複数作り、それぞれで別のブランチをチェックアウトしておける git の機能だ。ブランチを切り替えずに並行して作業できるので、AI エージェントを並べて動かすときによく使われる。私は作成と削除に git-worktree-runner（gtr）を使っている（git-worktree-runner の紹介記事）。

コードを書くのはエージェントに任せても、動くかどうかは自分の目で見たい。そこで worktree A と worktree B のアプリを同時に docker compose up すると、次のものがぶつかる。

cookie はポートを区別しない（RFC 6265 §8.5）。ポートをずらすだけでは、ある worktree でログインした cookie が別の worktree にも送られる。

結論: 入口と DB は共有し、アプリは worktree ごとに分ける

全体はこうなる。

さっきの表と対応させると、共有するものと分けるものは次のとおり。

ここで compose の用語を補っておく。compose のプロジェクトは、docker compose が一緒に管理するコンテナ・ネットワーク・volume のまとまりで、プロジェクト名がそれぞれの名前の頭に付く。既定ではディレクトリ名がプロジェクト名になる。ネットワークのほうは、compose で external: true と宣言すると、別のプロジェクトが作ったものに参加できる。

共有するプロキシと DB は、それぞれ別のプロジェクトとして 1 つだけ起動する。各 worktree のプロジェクトは、そのネットワークに参加するだけだ。この記事の構成は、ほぼこれで全部である。

ただ、ホスト名で振り分けられるのは HTTP だけだ。PostgreSQL の 5432 番とデバッガのポートは固定のまま残る。

まず worktree ごとに名前を分ける（compose のプロジェクト名）

ポートより先に名前を分ける。compose が自動で付ける名前なら、コンテナ名・ネットワーク・volume の頭にプロジェクト名が付くので、プロジェクト名が worktree ごとに違えばぶつからない。例外は自分で固定した名前で、container_name: や、ネットワーク・volume の name: はプロジェクト名を変えても同じになる。私の環境ではベクトル DB と DB の管理画面に固定のコンテナ名が残っていたので、移行のときに外した（共有する DB とプロキシは、逆に固定の名前をわざと付けている）。

プロジェクト名は後でホスト名にも使うので、DNS のラベルとして使える形にする。gtr で作る worktree は、作成時のフックが <リポジトリ名>-<worktree のディレクトリ名> を小文字・ハイフン区切りにして .env に書く。

# gtr の postCreate フック（抜粋）
project_name="${repo_name}-${worktree_name}"
project_name="$(printf '%s' "$project_name" \
  | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | tr -s '-' | sed 's/^-//; s/-$//')"
printf 'COMPOSE_PROJECT_NAME=%s\n' "$project_name" >> "$WORKTREE_PATH/.env"

以前はアンダースコア区切りだったが、ホスト名にアンダースコアは使えないので変えた。gtr を通さずに作った worktree は、プロジェクト名を書かなければ compose の既定どおりディレクトリ名になる。

.env は全 worktree で同じ中身にした。worktree に .env が無ければ、起動タスクがメインのチェックアウトの .env へシンボリックリンクを張る。このとき、共有元の .env に COMPOSE_PROJECT_NAME が書かれていると全 worktree が同じプロジェクトになってしまうので、その場合はリンクせずに止める。起動の直前には、同じプロジェクト名が別のディレクトリのコンテナに使われていないかも確かめている。

ポート: ずらすのをやめ、入口を 1 つにしてホスト名で振り分ける

この章でやることを先に 1 枚で示す。左が以前の形、右が今の形だ。

以前はポートをずらしていた

worktree を作るときのフックで、ほかの worktree の .env を読んで空いているオフセットを探し、8 種類のポートに同じ値を足して書き込んでいた。

# 旧フック（抜粋）。8 種類のポートに同じオフセットを足して .env に書く
PORT_KEYS=(FRONTEND_PORT STORYBOOK_PORT BACKEND_PORT AI_GATEWAY_PORT
           DB_GUI_PORT FRONTEND_DEBUG_PORT BACKEND_DEBUG_PORT AI_GATEWAY_DEBUG_PORT)
PORT_BASES=(3000 6006 8080 8000 5050 9229 40000 5678)

2 つ目の worktree なら frontend が 3001、backend が 8081、という具合だ。Ghostty + herdr の開発環境の記事を書いた時点では、まだこの方式だった。動きはした。ただ、使い続けるうちに困ることが増えてきた。

1. フックを通らない worktree は採番されない。git worktree add で作った worktree や、AI エージェント（私は TAKT を使っている）が作る独立したクローンは既定のポートのまま起動して衝突した。エージェントが作業している途中の画面を見られなかったのが一番困った
2. ポートや URL を使う設定を足すたびにフックの修正が要り、追従漏れが出た。ベクトル DB のポート、メール内リンクの基点 URL、エディタのデバッグ設定が、それぞれ漏れていた
3. URL がポート番号でしか区別できない。localhost:3002 がどのブランチなのか覚えていられない

仕組み: ホスト名で転送先を選ぶ

ホストに開くポートをリバースプロキシの 1 つだけにする。ブラウザは http://myapp-feat-a.localhost:3000 のようにホスト名を変えてアクセスし、プロキシはリクエストの Host ヘッダを見て、その worktree のコンテナへ転送する。

*.localhost は Chrome と Firefox が 127.0.0.1 に解決するので、/etc/hosts も DNS の設定も要らない。RFC 6761 §6.3 は localhost とそのサブドメインをループバックに解決するよう求めている。

プロキシには Traefik を使った。Traefik は Docker のコンテナに付いたラベルを読んで、転送のルールを自動で作る。worktree のアプリが起動すればルールが増え、止めれば消える。コンテナのラベルから設定を拾えるプロキシなら、Traefik でなくても同じ形は作れる。

設定

プロキシは、どの worktree にも属さない別のプロジェクトとして 1 つだけ起動する。

# compose/proxy.yaml（共有リバースプロキシ）
services:
  proxy:
    image: traefik:v3.6 # 実際はダイジェストで固定している
    container_name: myapp_proxy
    restart: unless-stopped
    command:
      - --providers.docker=true
      # traefik.enable=true のラベルを付けたコンテナだけを公開する
      - --providers.docker.exposedbydefault=false
      - --providers.docker.network=myapp_shared_proxy
      - --entrypoints.web.address=:80
    ports:
      - "127.0.0.1:3000:80" # LAN には公開しない
    volumes:
      # コンテナのラベルを読むため
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - shared_proxy

networks:
  shared_proxy:
    name: myapp_shared_proxy
    external: true

起動するときは、ネットワークが無ければ作ってから、固定のプロジェクト名で up する。

docker network inspect myapp_shared_proxy >/dev/null 2>&1 \
  || docker network create myapp_shared_proxy
docker compose --project-name myapp_shared_proxy -f compose/proxy.yaml up -d proxy

各 worktree の側は、アプリのコンテナにラベルを付けて共有ネットワークに参加させる。ホスト名にプロジェクト名を埋め込むので、同じ定義のまま worktree ごとに別のホスト名になる。COMPOSE_PROJECT_NAME を .env に書いていない worktree でも、compose がプロジェクト名を入れて展開した（Compose 5.1.2 で確認）。

# compose/routing.yaml（各 worktree の frontend をプロキシに登録する）
services:
  frontend:
    environment:
      - NEXT_PUBLIC_API_BASE_URL=/api/v1
    labels:
      - traefik.enable=true
      - traefik.docker.network=myapp_shared_proxy
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}-frontend.rule=Host(`${COMPOSE_PROJECT_NAME}.localhost`)"
      - traefik.http.routers.${COMPOSE_PROJECT_NAME}-frontend.entrypoints=web
      - traefik.http.services.${COMPOSE_PROJECT_NAME}-frontend.loadbalancer.server.port=3000
    networks:
      - default
      - shared_proxy

networks:
  shared_proxy:
    name: myapp_shared_proxy
    external: true

そして、アプリ側からは ports: を外す。

 services:
   frontend:
-    ports:
-      - "${FRONTEND_PORT:-3000}:3000"
   backend:
-    ports:
-      - "${BACKEND_PORT:-8080}:8080"

これでホストに開く HTTP のポートは、プロキシの 3000 番だけになった。URL の :3000 は全 worktree で同じだが、ホスト名が違うので行き先も違う。

フロントと API を同じオリジンにする

ホスト名で振り分けるついでに、1 つのホスト名をパスで分けて、/api/v1 から始まるリクエストを backend に送るようにした。backend のルートは / 直下にあるので、プロキシで /api/v1 を外してから転送する。

# compose/routing.yaml（続き）
backend:
  environment:
    # 許可元はこの worktree の URL 1 つだけ
    - AUTH_CSRF_TRUSTED_ORIGINS=http://${COMPOSE_PROJECT_NAME}.localhost:3000
    # メール内リンクの基点もこの worktree の URL にそろえる
    - APP_BASE_URL=http://${COMPOSE_PROJECT_NAME}.localhost:3000
  labels:
    - traefik.enable=true
    - traefik.docker.network=myapp_shared_proxy
    # /api/v10 などを拾わないよう、Path と PathPrefix を分けて書く
    - "traefik.http.routers.${COMPOSE_PROJECT_NAME}-api.rule=Host(`${COMPOSE_PROJECT_NAME}.localhost`) && (Path(`/api/v1`) || PathPrefix(`/api/v1/`))"
    - traefik.http.routers.${COMPOSE_PROJECT_NAME}-api.entrypoints=web
    - traefik.http.routers.${COMPOSE_PROJECT_NAME}-api.middlewares=${COMPOSE_PROJECT_NAME}-api-strip
    - traefik.http.middlewares.${COMPOSE_PROJECT_NAME}-api-strip.stripprefix.prefixes=/api/v1
    - traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8080
  networks:
    - default
    - shared_db # 共有 PostgreSQL 用（DB の章）
    - shared_proxy

frontend は API の基点を相対パスの /api/v1 にしてあるので、どの worktree でも自分の backend を呼ぶ。変更前後の URL を並べるとこうなる。

同じオリジンになって、cookie と CSRF の扱いが単純になった。backend は refresh cookie を Domain 属性なし（ホスト限定）・Path=/ で発行している。画面へのリクエストにもこの cookie が付くので、frontend の middleware がそのまま読める。ホスト名が worktree ごとに違うので、cookie も worktree ごとに分かれる。CSRF の許可元も、以前はフックが worktree ごとのポートから組み立てて .env に書いていたが、今は compose がプロジェクト名から組み立てる。

Next.js の dev サーバーは localhost とそのサブドメインを既定で許可するので、allowedDevOrigins は設定していない。ホットリロード（HMR）の WebSocket もプロキシ越しにつながった。

動作確認

# この worktree のプロジェクト名（= ホスト名）
docker compose config | sed -n '1s/^name: //p'   # → myapp-feat-a

curl -s -o /dev/null -w '%{http_code}\n' http://myapp-feat-a.localhost:3000/          # frontend
curl -s -o /dev/null -w '%{http_code}\n' http://myapp-feat-a.localhost:3000/api/v1/   # backend

どちらも 200 が返れば振り分けはできている。curl は 7.85.0 から *.localhost を自分でループバックアドレス（127.0.0.1 と ::1）に解決する。

ほかの解き方と比べて

この形に落ち着くまでには回り道があった。きっかけは Vercel Labs の portless だ。ホストで起動した dev サーバーに myapp.localhost のような名前付きの URL を付けるツールで、git worktree の中ではブランチ名をホスト名に入れてくれる。紹介記事を読んで、これを入れればポートずらしのフックを消せるのではないかと思い、調べ始めた。

調べてみると、portless の自動の機能（PORT の割り当てや、ブランチ名からのホスト名）は、portless 経由で起動したプロセスにしか効かない。私の環境はアプリを全部コンテナで動かしているので、そのままでは効かない。portless alias <名前> <ポート> で、コンテナがホストに公開したポートに名前を付けることはできる。ただ、公開するポートを worktree ごとにずらす作業は残る。フックを消せないなら、入れる意味は薄い。

次に見たのが、Docker の実行環境に使っている OrbStack のドメイン機能だ。Compose のサービスに service.project.orb.local の名前が自動で付き、設定はほとんど要らない。ただ OrbStack は macOS 向けのアプリで、商用利用には有料のライセンスが要る。Windows の人もいるチームで標準にするのは難しかった。

そこで、全部 Compose のまま、プロキシも Compose で 1 つ立てる形にした。判断の基準はこう置いた。

• Mac と Windows で同じ手順で動く
• Docker で環境を再現できる状態を保つ
• worktree の作り方（gtr、git worktree add、エージェントのクローン）に依存しない
• CI の起動経路を壊さない

アプリをホストで直接起動している構成なら、portless はかなり手軽な選択肢だと思う。私の場合に合わなかったのは、全部を Compose で動かしていたからだ。

ポートずらしの頃と比べて変わったこと

DB: 1 つだけ立てて、全 worktree から同じ名前で参照する

PostgreSQL は全 worktree で 1 つを共有している。これはプロキシより前、2026 年 7 月から続けている構成だ。

仕組み

共有の DB も、プロキシと同じく別のプロジェクトとして 1 つだけ起動し、専用のネットワーク myapp_shared_db に db という別名で参加させる。

# compose/db.yaml（共有 PostgreSQL）
services:
  db:
    image: postgres:16-alpine
    container_name: myapp_postgres
    restart: always
    ports:
      - "127.0.0.1:5432:5432" # ホストの psql などから使う。LAN には公開しない
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      shared_db:
        aliases:
          - db

volumes:
  postgres_data:
    name: myapp_postgres_data # プロジェクト名に左右されない固定の名前

networks:
  shared_db:
    name: myapp_shared_db
    external: true

各 worktree の backend は、自分のプロジェクトの default ネットワークと、この共有ネットワークの両方に入る。

# compose/base.yaml（各 worktree）
services:
  backend:
    networks:
      - default # 自分の worktree の frontend やベクトル DB と話す
      - shared_db # 共有 PostgreSQL と話す

networks:
  shared_db:
    name: myapp_shared_db
    external: true

Docker のネットワークの中では、コンテナをサービス名や別名で引ける。backend から見ると、共有ネットワークの上に db という名前のホストが 1 つあるだけだ。接続文字列は postgres://...@db:5432/... のまま、どの worktree でも変えずに済む。frontend とベクトル DB は共有ネットワークに入らないので、DB には直接触れない。

以前は DB を各 worktree の compose に入れていた。volume はプロジェクトごとに分かれるので、同じ DB を使うつもりでもデータは別々になり、2 つ目の worktree を起動すると固定のコンテナ名と 5432 番で衝突した。DB を別のプロジェクトに切り出し、volume に固定の名前を付けたのはそのためだ。

なぜネットワークを共有するのか

DB の持ち方は、ほかにも考えられる。並べるとこうなる。

共有にしておくと、worktree を作るたびにテスト用のユーザーやデータを作り直さずに済む。ホストから見たいときは 127.0.0.1:5432 で psql などをつなぐ。

共有して困るのは、スキーマが分かれるとき

共有 DB には向かない使い方がある。互換性のない migration を、ブランチごとに並行して試す使い方だ。

• migration ツールが記録する版が、先に適用したブランチの版まで進む。その migration ファイルを持たない別のブランチでは、ツールが版を解決できずに止まることがある
• あるブランチで migration を戻す（down）と、そのテーブルを使っている別のブランチが壊れる
• DB をリセットすると、全 worktree のデータが消える

今のところ、これは README で「migration、DB のリセット、手動のデータ変更は、起動中の全 worktree に影響する」と注意しているだけで、仕組みでは防いでいない。

中間の案もある。PostgreSQL のコンテナは 1 つのまま、worktree ごとに database（または schema）を分ける方法だ。CREATE DATABASE myapp_feat_a のように worktree ごとの DB を作り、接続文字列の DB 名だけを変える。データは使い回せなくなるが、スキーマは干渉しない。この案は当時の比較に入れていなかった。スキーマを変える作業を並行することが増えたら、次の候補になる。

ベクトル DB は worktree ごとに分けた

一方、ベクトル DB（Qdrant）は worktree ごとに持たせた。共有すると困ることがあるからだ。

• E2E テストでは LLM を偽物に差し替えていて、意味のないベクトルが作られる。共有すると、それが実データに混ざる
• ブランチで埋め込みの方式やコレクションの形式を変えると、その変更が全 worktree に効いてしまう

この組み合わせには副作用がある。worktree A で登録したデータは PostgreSQL に入るので、worktree B の画面にも出る。ところがベクトルは A のベクトル DB にしか無いので、B の検索では使えない。B で使いたければ、B で索引を作り直す。

共有するか分けるかの目安

DB に限らず、何を共有するかは次の観点で決めた。

• 共有する: ブランチをまたいでデータを使い回したい。スキーマの変更がまれ。起動の手間とリソースを減らしたい
• 分ける: ブランチで形式やスキーマが変わる。テスト用のデータが混ざると困る。作り直しが安い

PostgreSQL は前者、ベクトル DB と node_modules は後者だった。

依存と起動: 1 コマンドで、worktree の作り方に依存しない

node_modules は worktree ごとの volume に置く

イメージ名は全 worktree で共有している。worktree ごとに名前を分けると、消した worktree の分だけイメージが残るからだ。その代わり、起動のたびにその worktree のソースからビルドし直す（差分が無ければキャッシュですぐ終わる）。node_modules はイメージの中のものを使わず、worktree ごとの名前付き volume に置いて、起動時にその worktree の lockfile で入れ直す。

# compose/override.yaml（ローカル開発用）
services:
  frontend:
    # lockfile が変わっていなければ数秒で終わる
    command: sh -c "pnpm install --frozen-lockfile && exec pnpm run dev"
    volumes:
      - ./frontend:/app
      # volume 名にプロジェクト名が付くので、worktree ごとに分かれる
      - frontend_node_modules:/app/node_modules

volumes:
  frontend_node_modules:

pnpm の store もこの volume の中に置いた（Dockerfile で npm_config_store_dir=/app/node_modules/.pnpm-store）。ハードリンクが効き、worktree を消せば volume と一緒に消える。2 回目以降の install は 1〜4 秒ほどで、volume が空の初回は十数秒かかる。

起動の流れ

起動はタスクランナー（Task）の task compose:up 1 つにまとめた。

# taskfiles/Taskfile.compose.yml（抜粋）
up:
  cmds:
    - task: env:link # .env が無ければメインの .env にリンク
    - task: project:check # プロジェクト名が別のディレクトリで使われていないか
    - task: db:up # 共有 PostgreSQL（無ければ作り、あれば使う）
    - task: proxy:up # 共有プロキシ（同上）
    - docker compose up -d --build # この worktree のアプリ

Task を使わない場合は、次の 3 つを順に実行すれば同じことになる。

./scripts/shared-db.sh up      # 共有ネットワーク + PostgreSQL（別名 db）
./scripts/shared-proxy.sh up   # 共有ネットワーク + Traefik
docker compose up -d --build   # この worktree のアプリ

共有の DB とプロキシは「無ければ作り、あれば使う」ので、最初に起動した worktree が作り、2 つ目以降はそれを使う。gtr で作った worktree でも、git worktree add で作ったものでも、AI エージェントのクローンでも、同じ task compose:up で起動できる。前提は、プロジェクト名が worktree ごとに違うこと。ディレクトリ名が同じ別のクローンなどで名前が重なったら、起動前のチェックが止める。名前を自動で付け直してくれるわけではない。エージェントが作業している途中の画面も、プロジェクト名の URL で開ける。

片付け

gtr で worktree を消すときは、削除前のフックで docker compose down --volumes を流す。gtr を通さずに消した worktree の残骸（コンテナ・ネットワーク・volume）は、task compose:prune で一覧にしてから消す。作業ディレクトリが存在しないプロジェクトを探し、共有の DB とプロキシは名前で除外する。不要になったイメージも、自分のプロジェクトのラベルが付いたものだけを消す（docker image prune はホスト全体が対象になるので使わない）。

CI の E2E も同じ経路にした

最初は CI だけ、frontend と backend をポートで公開した別オリジンのまま E2E を動かしていた。これだとローカルと CI で cookie と CSRF の条件がそろわない。そこで CI でもプロキシを起動し、http://myapp-ci.localhost:3000 で E2E を流すようにした。GitHub Actions の runner では、Playwright の API リクエストなど OS の名前解決を使うクライアントのために、/etc/hosts に myapp-ci.localhost を登録している。

まとめ: 自分の環境に持ち込むチェックリスト

1. docker compose config の出力から ports: と container_name: を洗い出す。固定の container_name: は外す
2. プロジェクト名の付け方を決める（小文字・ハイフン区切りで、ホスト名に使える形）。.env を共有するなら、そこに COMPOSE_PROJECT_NAME を書かない
3. 共有するもの（DB など）を別のプロジェクトに切り出し、docker network create で作ったネットワークに別名付きで参加させる。volume には name: で固定の名前を付ける
4. リバースプロキシを別のプロジェクトで 1 つ立て、アプリにラベルを付けて ports: を外す。ホストへの公開は 127.0.0.1 だけにする
5. frontend の API の基点を相対パス（/api/v1）にし、CSRF などの許可元を <プロジェクト名>.localhost から組み立てる
6. 「共有 DB → プロキシ → docker compose up -d --build」を 1 つのコマンドにまとめる

アプリをホストで直接起動しているなら portless、Mac で個人開発しているなら OrbStack のドメイン機能のほうが手軽だと思う。全部を Compose で動かしていて、作り方の違う worktree が混ざるなら、入口を 1 つにする形が合う。

フックが 100 行減ったのはおまけだった。変わったのは、エージェントが作業中の worktree を、ポート番号を調べずにプロジェクト名の URL で開けるようになったことだ。

半年前、Claude Code 開発を支える私のツールチェイン という記事で WezTerm + tmux + 自作ツール Baton の構成を紹介した。あれから中身がだいぶ入れ替わったので、現時点の開発環境をまとめ直す。

入れ替えたのはターミナルエミュレーター・マルチプレクサ・AI セッション管理の 3 つで、エディタやバージョン管理まわりはほぼそのままだ。この記事ではまず「今どういう構成で、どう開発しているか」を書き、そのあとに「なぜこの形になったか」を短く添える。想定している読者は、ターミナル中心で開発したい人と、Claude Code を複数並べて動かしている人だ。

結論から

• 常用の構成は Ghostty（ターミナルエミュレーター）+ herdr（ターミナルマルチプレクサ） にした。WezTerm + tmux + Baton は捨てずに、戻るための退路として残している
• herdr を選んだ決め手は、tmux 時代にできなかった「Neovim での画像表示」と「ターミナル内ブラウザで画面の要素を選んで AI に渡すこと」ができるようになったことだ。承認待ちの検知や使い心地は、Baton とほとんど変わらない
• Ghostty に移ったのは、そのターミナル内ブラウザが WezTerm では重くて使い物にならず、Ghostty では普通に動いたから

全体の構成を 1 枚にするとこうなる。

半年前から変わったところ

変わったのは下の 3 層だけで、そのほかは据え置きだ。

Nix 化は 8 月の話で、経緯は dotfiles 運用のすすめと、その先の Nix に書いた。この記事の範囲は 9 月の入れ替えである。

Ghostty + herdr でどう開発しているか — 1 タスクの流れ

道具の一覧より先に、1 つのタスクをどう進めているかを書く。私の場合、常時 10 本前後のエージェントを並べて動かしている。

1. プロジェクトを開く。 Ghostty を起動すると自動で herdr にアタッチし、前回の作業がそのまま残っている。新しく始めるときは prefix+f で ghq 管理下のリポジトリを fzf で選び、herdr のワークスペースとして開く。Alfred から開くこともある
2. worktree を切る。 並列で進めるタスクごとに wt（gtr のラッパー）で worktree を作り、同じピッカーから開く
3. 分割してエージェントを起動する。 prefix+2 〜 prefix+8 で N 分割し、prefix+0 でペイン数に応じて Neovim・Claude Code・Codex を起動する。全ペインで Claude Code を一斉に立ち上げたいときは、Loupedeck（物理ボタンの左手デバイス）の 1 ボタンで済ませる
4. 状態を見て承認する。 各ペインが working / blocked / idle のどれかを、herdr がサイドバーに出す。承認待ちが出たら prefix+b の承認コンソールで a（承認）か d（拒否）を押すか、通知をクリックしてそのペインへ飛ぶ
5. （Web アプリのとき）ブラウザで確認して、要素ごと直させる。 tb で localhost を隣のペインに開き、気になる要素を Ctrl+G で選ぶ。選んだ要素の情報がエージェントの入力欄に入るので、そのあとに「ここの余白を詰めて」と書いて送る
6. 差分を読む。 エージェントが書いた変更は hunk でまとめて読む。気になるところは Neovim で開いて直接確認する
7. コミットする。 基本はエージェントに commit スキルを実行させ、変更内容からコミットを作らせる。手で直したファイルは prefix+g で開く lazygit でステージし、Ctrl+G で Antigravity にコミットメッセージを作らせてそのままコミットする

4〜6 を何周も回すのが日常だ。5 は Web アプリを作っているときだけの手順で、それ以外の開発ではターミナル内ブラウザは使わない。

Web アプリの開発でいちばん変わったのは、その 5 である。以前は、ブラウザ（Dia）用に自作した拡張で要素の情報を拾い、ターミナルに戻って AI に渡していた。今はブラウザを切り替えず、Ctrl+G で要素を指すだけで済む。

※ 開発中のプロダクトは見せられないので、画面はサンプルとして Ghostty の公式ドキュメントを開いている。普段は localhost で動かしている手元のアプリに対して同じ操作をする。

レイヤー別のツール紹介

ここからは図 1 の層ごとに、使っているものを紹介する。

ターミナルエミュレーター: Ghostty

Ghostty は Zig 製の、GPU で描画するターミナルエミュレーターだ。公式ドキュメントに「Zero Configuration Philosophy」という節があり、設定なしでもほとんどの人がそのまま使えることを目標にしている（Ghostty Configuration）。

私の設定は本体 55 行と herdr 用のキー設定 51 行で、合わせて 106 行だ。WezTerm のときは Lua で 7 ファイル 388 行あった。ただ、減った分の大半は Ghostty の手柄ではない。タブや分割の管理を herdr に移したので、ターミナルエミュレーター側の仕事がそもそも減った。

Ghostty 側でやっていることは、ほぼ 1 つしかない。Cmd 系のキーを「herdr の prefix + キー」のバイト列に変換して送ることだ。Ghostty には Lua のようなスクリプトがないので、text: アクションでバイト列を直接書く。

# config/ghostty/herdr.conf（抜粋）
# Cmd 系のキーを「herdr の prefix（Ctrl+Q = \x11）+ キー」のバイト列で送る

# Cmd+D でペインを縦に分割、Cmd+T で新規タブ、Cmd+W でペインを閉じる
keybind = cmd+d=text:\x11v
keybind = cmd+t=text:\x11c
keybind = cmd+w=text:\x11x

# Cmd+1..9 を herdr のタブ切替（Alt+1..9）に回す。
# Ghostty 既定の super+digit_N=goto_tab が先にマッチするので、先に外しておく
keybind = cmd+digit_1=unbind
# Alt+1 は ESC 前置ではなく CSI u 形式で送る（herdr が kitty keyboard protocol を使うため）
keybind = cmd+1=text:\x1b[49;3u

ハマったのは Cmd+数字だ。cmd+1 を上書きしても、Ghostty 既定の物理キー指定（super+digit_1）が先にマッチしてしまう。cmd+digit_N=unbind で既定を外してから割り当てる必要があった。Alt の送り方も、よく見る ESC 前置（\x1b1）ではなく CSI u 形式（\x1b[49;3u）にしている。herdr が外側のターミナルエミュレーターに kitty keyboard protocol を要求するためだ。

見た目では、WezTerm で使っていた背景画像を引き継いだ。Ghostty には背景画像の明るさを下げる設定がないので、画像そのものを事前に暗く加工して敷いている。

マルチプレクサ: herdr

herdr は AI エージェントを動かす前提で作られたターミナルマルチプレクサで、Rust 製の単一バイナリだ。tmux と同じ層にあり、tmux の代わりに使う。

tmux から移って違いを感じたのは次の点である。

• 各ペインのエージェントの状態が見える。 Claude Code や Codex を自動で検出し、working / blocked / idle をサイドバーに出す
• マウスも普通に使える。 README に「keyboard and mouse, both first-class」とあり、prefix キーとクリック・ドラッグのどちらでも操作できる
• エージェントから操作できる。 CLI とソケット API があり、ペインの分割やキー送信をスクリプトから叩ける

キーバインドは tmux 時代のものをそのまま移植した。prefix も tmux と同じ Ctrl+Q にしている（herdr 既定の Ctrl+B は、Karabiner で左矢印に変換しているので届かない）。

# config/herdr/config.toml（抜粋）
[keys]
# prefix は tmux 時代と同じ Ctrl+Q
prefix = "ctrl+q"

# lazygit をポップアップで開く
[[keys.command]]
key = "prefix+g"
type = "popup"
command = "zsh -ic 'lazygit'"
width = "80%"
height = "80%"

herdr 単体で足りない部分は、自作スクリプト 10 本で埋めた。主なものは、承認待ちのエージェントを一覧して a / d で承認・拒否できる承認コンソール（Baton の TUI の代わり）、ghq のリポジトリピッカー、N 分割、ペイン数に応じたプロセスの一括起動である。スクリプトはすべて dotfiles の config/herdr/bin/ に置いている。

プラグインはタブ名を自動で付ける herdr-automatic-rename と、OS の通知バナーをクリックすると該当ペインへ飛べる herdr-terminal-notifier の 2 つを入れている。プラグインは herdr plugin install で入れる仕組みなのでリポジトリで管理しにくい。そこで、使うプラグインと commit SHA を書いたリストを dotfiles に置き、Nix の switch のたびにそのリストへ揃えるようにした。導入前にはスクリプトと同梱アプリの中身を確認し、commit を固定している。

細かいところでは、サイドバーのエージェント名を Claude はオレンジ、Codex は青緑というように色分けした。10 本並ぶと、色がないとどれが何か分からない。

AI エージェント: Claude Code / Codex / takt / OpenCode / Antigravity

エージェントは Claude Code と Codex を主に使い、手順が決まった作業は nrslib さんの takt に流している。takt はステップごとにプロバイダを割り当てられるので、実装とテストは Codex、計画とレビューは Claude Code、AI 特有のアンチパターン検出だけは OpenCode、という分担にしている。

承認まわりは半年で様子が変わった。Baton を作った当初は、Claude Code にも Codex にも、承認を自動で判定する仕組みがなかった。すべてを許可するモード（--dangerously-skip-permissions）で起動すれば承認は出なくなるが、それは怖い。そこで Baton に「safe auto mode」を実装した。決まったルールで rm や本番操作のような危険な操作を弾き、判断に迷うものだけ別の LLM に審査させる仕組みだ。その後 Claude Code に auto mode が入り、Claude Code にはあるのに Codex にはない時期も Baton で補っていた。今は Codex にも承認リクエストを自動でレビューする設定があり、どちらも組み込みの機能で足りるようになった。

このほかに OpenCode と Antigravity（agy）も入れている。OpenCode は takt のレビュー工程の一部を担当し、Antigravity は調べものの委譲と、後述する lazygit のコミットメッセージ生成に使っている。herdr はどちらも検出してサイドバーに出すので、Claude Code や Codex と同じ一覧で状態を追える。

開発ツール

Neovim。 全部入りのディストリビューションは使わず、プラグインマネージャーの lazy.nvim で 1 つずつ足してきた。今は 29 ファイルで、選んだ理由は ADR としてリポジトリに残している。herdr に移って、snacks.nvim の画像表示が使えるようになった。Ghostty では Markdown の画像リンクのすぐ下に画像が埋め込まれるので、記事を書きながら図の見た目を確かめられる。WezTerm のときは埋め込みに対応しておらず、カーソルを乗せたときのフロート表示までだった。

実は 9/15 に一度、この画像表示を諦めている。tmux の中では画像の残像や位置ずれが出たので、画像表示を切り、パスをコピーして Alfred で開く運用にしていた。herdr に移ってから有効に戻したところ、残像も位置ずれも出なかった。一度諦めた機能だったので、これはかなり嬉しかった。

lazygit。 手で直したファイルをコミットするときに使う。herdr の prefix+g でポップアップとして開くので、作業中のペインを崩さない。ステージしてから Ctrl+G を押すと、Antigravity が差分から Conventional Commits 形式のメッセージを作り、そのままコミットする（lazygit の customCommands に登録している）。エージェントが書いた変更は、エージェント自身に commit スキルを実行させてコミットすることが多い。

hunk。 hunk は、エージェントが書いた変更をまとめて読むための diff ビューアで、「review-first」をうたっている。今回の移行と同じタイミングで試し始めた。1 行ずつステージするなら lazygit、エージェントが複数ファイルにまたがって書いた変更の全体を読むなら hunk、という分担を考えている。

gtr。 Git worktree の作成と削除をまとめるツールで、wt というラッパーでブランチ名も自動で付けている。worktree を作ったあとにポートの割り当てや依存のインストールを流す処理も、gtr の hook に書いてある。

terminal-browser。 terminal-browser は、Electron で本物の Chromium を動かし、その画面を Kitty graphics protocol でペインに描くブラウザである。localhost で動かしている手元のプロダクトも、普通の Web サイトも、実ブラウザと同じ見た目で表示される。起動は短いシェル関数にしている。

# tb          → localhost:3000 を右に分割して開く
# tb 5173     → localhost:5173
# tb ... down → 2 つ目の引数で分割方向
tb() {
  local target="${1:-localhost:3000}"
  local dir="${2:-right}"
  [[ "$target" == <-> ]] && target="localhost:$target"
  terminal-browser open "$target" --split "$dir"
}

要素を選んで AI に渡す Ctrl+G は terminal-browser の組み込み機能だ。要素ピッカー（react-grab）が起動し、選んだ要素の HTML の抜粋が、同じタブにあるエージェントの入力欄に > ... の 1 行で入る。React の開発ビルドなら、コンポーネント名とソースの位置も付く。Enter は押されないので、続けて指示を書いてから送る。逆に AI 側からは terminal-browser action で、開いているタブのスクリーンショット・DOM の取得・クリックなどができる。

OS 操作: AeroSpace / Alfred / Karabiner / Loupedeck

ターミナルの外側は、キーボードから手を離さずに済むことを基準に選んでいる。

• AeroSpace: タイル型のウィンドウマネージャー。Ghostty は決まったワークスペースに固定で置いている
• Alfred: ランチャー。リポジトリを herdr のワークスペースとして Ghostty で開くワークフローや、Taskfile のタスクを実行するワークフローを自作している
• Karabiner-Elements: キーの変換
• Loupedeck: 物理ボタンの左手デバイス。全ペインで Claude Code を起動する、全ペインで /clear を実行する、といった一括操作を割り当てている

基盤: Nix + dotfiles

ここまでのツールは、すべて dotfiles リポジトリで管理し、nix-darwin + home-manager で配っている。herdr・Ghostty・terminal-browser も Homebrew の宣言に入れてある。宣言にないパッケージは switch のたびに消える設定（cleanup = "zap"）にしているので、試しに入れたツールを片付け忘れることがない。

設定を変えるときは、判断の理由を ADR としてリポジトリに残すようにしている。今回の移行でも、試用の開始から採用の確定、ターミナル内ブラウザの経路の選択まで、2 本の ADR を書いた。この記事の数字や経緯も、ほぼその ADR から拾っている。

なぜこの構成になったか

ここからは移行の経緯を短く書く。流れを図にするとこうなる。

きっかけは Orca の「要素を選んで AI に渡す」機能

9 月の頭、AI エージェント向けの統合開発環境として話題になっていた Orca を検討した。いちばん惹かれたのは、内蔵ブラウザで画面の要素を選び、コメントを付けてそのまま AI に渡せる機能だった。

ただ、Orca 自体は私の使い方に合わなかった。GUI 前提のツールで、私の環境は逆に GUI を減らしてターミナルに寄せる方向に進んでいる。Orca の売りである worktree 管理は gtr で、GitHub 連携は gh で足りていたし、複数エージェントの管理は当時 Baton で賄えていた。

それでも「要素を選んで AI に渡す」だけは欲しかった。同じことをターミナルの中でできないか。そう考えたのが、今回の入れ替えの出発点である。

herdr: 画像とブラウザが動いたのが決め手

herdr は、実は 9 月の頭に一度見送っている。当時は承認待ちの検知精度をいちばん重く見ていて、その観点では Baton と herdr に差がなかった。どちらも画面の文字を読んで判定する方式である。一方で移行の手間は重かった。あとで数えたところ、tmux のキーバインドが 89 個、自作スクリプトが 26 本、Baton の Go コードが 7,639 行あった。差がないなら移る理由はない、と判断した。

考えが変わったのは、開発環境全体を見直したときだ。Claude Code や Codex に自動承認の仕組みが組み込まれて、Baton の safe auto mode の出番が減っていた。自作ツールを直し続ける手間と、コミュニティが活発な herdr に乗る場合を比べると、後者のほうが先がある。そこで、机上で比べるのをやめて実際に使ってみることにした。

使ってみた結果、エージェント管理の使い心地は正直ほとんど変わらなかった。変わったのは別のところだ。tmux は Kitty graphics protocol に対応していない。そのため、ターミナルに画像を描く系統の機能が tmux の中では思うように動かなかった。herdr ではこれが動き、Neovim の画像表示とターミナル内ブラウザの両方が使えるようになった。takt を動かすと画面がちらつく問題も、tmux では設定で抑え込んでいたが、herdr では最初から出なかった。

決め手はここだった。やりたいことがあって、それを叶えてくれたのが herdr だった。tmux のままでも解決する道はあったのかもしれない。ただ、流行っているエージェント管理ツールを試したら、副産物として長く諦めていたことが解決した。それなら herdr でいい、となった。

移るときは、いきなり切り替えずに試用から始めた。最初は ~/.config/use-herdr というファイルがあるかないかで、WezTerm が tmux と herdr のどちらを起動するかを切り替える形にした。戻すときは rm 1 回で済む。この状態で tmux + Baton と使い比べてから、採用を決めた。今も WezTerm を起動すれば tmux + Baton の環境に戻れるようにしてある。

Baton でやっていたことは、次のように置き換えた。

Ghostty: ターミナル内ブラウザが WezTerm では重すぎた

herdr に移って最初に試したターミナル内ブラウザは Chawan だった。独自エンジンで軽く、Wikipedia のような文書中心のページは問題なく読める。ところが私のプロダクト（Next.js）を開くと、アイコンがすべて [img] という文字に置き換わった。アイコンが HTML に直接埋め込まれた <svg> で、Chawan はこれを描けない。モダンな Web アプリの確認には使えないので、入れて 10 分足らずで外した。

次に試したのが terminal-browser だ。こちらは中身が本物の Chromium なので、表示は実ブラウザと変わらない。ただ、WezTerm + herdr の組み合わせでは、スクロールするだけで WezTerm が CPU を 1 コア以上使い続け、操作がまともに追いつかなかった。同じことを Ghostty + herdr で試すと、CPU 使用率は十数%に収まった。普通のブラウザと同じ感覚でスクロールでき、一気に快適になった。

原因は、terminal-browser が画面を転送する経路にあった。terminal-browser は herdr を通してターミナルエミュレーターへ画像を直接流す専用の経路（ストリーム）を開くが、WezTerm ではこれが約 3 秒で閉じてしまい、流量制限のない予備の経路に落ちていた。なぜ閉じるのかまでは突き止めていない。

もう 1 つ、Ghostty にしてよかったことがある。iPhone（Moshi）から herdr のセッションにアタッチしたあと PC に戻ると、WezTerm ではペインが実色で塗りつぶされ、背景画像が隠れてしまう現象があった。Ghostty にしてからは、今のところこれが起きていない。こちらも原因は切り分けていない。

ついでに書くと、起動直後のメモリは WezTerm の約 316MB に対して Ghostty は約 213MB だった。ただ、普段のテキスト表示の速さはほぼ変わらない。Ghostty に移って得たのは、ターミナル内ブラウザが使えるようになったことだ。

失ったもの・割り切ったこと

使い心地はほぼ変わらないと書いたが、herdr に移って失ったものもある。いちばん大きいのは見た目の自由度だ。tmux では好きに組めたステータス表示が、herdr では決まった枠の中でしかいじれない。サイドバーの列を揃える設定も、モード別に色を変える設定もない。

ほかにも、次のような制約を抱えたまま使っている。

• ペインを ID で直接フォーカスできない。 tmux 時代のペイン番号ジャンプは再現できなかった
• ターミナル内のリンクをクリックで開けない。 herdr がマウスを捕まえているためで、マウス捕捉を切るとサイドバーのクリックやドラッグでのコピーも失う
• safe auto mode と takt の検知がない。 どちらも Baton にしかない機能だった
• terminal-browser は herdr のクライアントが 1 つのときしか軽く動かない。 iPhone から同じセッションに繋ぐと、Ghostty でも重い経路に落ちる。開き直すまで戻らない
• 通知が二重に出る。 Claude Code / Codex の hook の通知と herdr の通知が重なっている。まだ直していない
• Ghostty のメモリは観測中。 Claude Code 由来のメモリリークの報告があったため、移行後 1 週間は 10 分おきに記録している。今のところ 200MB 前後で推移していて、増え続ける様子はない

Baton は休止にした。WezTerm を起動すると従来どおり tmux + Baton で立ち上がるようにしてあり、いつでも戻れる。takt のセッション検知のように Baton にしかない機能もあるので、戻る可能性はゼロではない。ただ、takt のセッションも herdr のエージェント一覧には Claude Code として出てくるので、今のところ困っていない。たぶん戻らないと思う。

ターミナル中心の環境を作る人へ

前提として、開発の軸をターミナルに置くところから始めてほしい。そのうえで大事だと思うのは、一度に全部を入れないことだ。

私は Neovim を組み始めたとき、プラグインを次々に入れていた。Neovim には LazyVim のような全部入りのディストリビューションと、lazy.nvim のようなプラグインマネージャーで 1 つずつ足していくやり方がある（名前が似ていてややこしい）。全部入りで始めると、自分の環境に何の機能が入っているのかを把握しきれなくなる。私は 1 つずつ入れて使い心地を確かめ、目的を 1 つずつ潰していくやり方のほうが合っていた。

設定が面倒な人には、Ghostty と herdr から始めるのがいいと思う。Ghostty は設定なしでまともに動くことを設計思想にしている。herdr も、tmux の取っつきにくさを減らす方向で作られている。キーボードとマウスの両方を正式な操作方法として扱っているので、prefix キーを覚える前からクリックとドラッグで分割や移動ができる。

そこから先は、使いながら育てればいい。やりたいことが出てきたとき、他の人の環境紹介を読んで「この機能いいな」と思ったときに、その考え方を 1 つずつ取り込む。私の今の構成も、Orca の機能に惹かれたところから始まっている。

まとめ

半年前の記事と比べると、入れ替えたのはターミナルエミュレーター・マルチプレクサ・セッション管理の 3 つだけだ。エージェントを並べて承認を回す、という開発のやり方もほとんど変わっていない。

それでも、tmux 時代に諦めていたことが 2 つ戻ってきた。Neovim で画像を見ることと、ブラウザで要素を指して AI に直させることだ。環境を入れ替える理由として、私にはこれで十分だった。

使い込むうちに、また不満や入れ替えたいものが出てくると思う。そのときはまた ADR に書き足していく。

結論から

開発環境の設定ファイルを、端末に置いたままにしない。 Git リポジトリに移して、端末側にはリンクを張るだけにする。dotfiles 運用と呼ばれているもので、やることは実質これだけだ。

見返りは分かりやすい。新しい端末で環境を作り直さなくて済む。clone してリンクを張れば元に戻る。設定をいじって壊しても、どこをどう変えたかが git diff で追える。2 台目以降で「あっちにはあるのにこっちには無い」が消える。

ただ、運用が回り始めると穴が見えてくる。設定ファイルは揃うのに、そのファイルを読むツール本体は揃わない。ここを埋めるのが Nix だ。

この記事は前半で dotfiles 運用の始め方を、後半で「その先に Nix を足すとどうなるか」を書く。私は現在 3 台（MacBook Pro / Mac mini / 会社支給 Windows の WSL2）をこの方式で回していて、リポジトリは公開している。

dotfiles とは何か

Unix 系 OS では、設定ファイルの名前が . で始まる慣習がある。.zshrc、.gitconfig、.vimrc のたぐいだ。これらをまとめて dotfiles と呼ぶ。

最近は ~/.config/ 以下に置く形式（XDG Base Directory）が主流になっていて、. で始まらないものも増えた。私のリポジトリで管理している中身はこのあたりになる。

• シェル: .zshenv / .zprofile / .zshrc と、分割した zsh/ 配下のスクリプト群
• エディタ: nvim/（Lua の設定一式）
• ターミナル: wezterm/ ghostty/ tmux/
• Git: git/（.gitconfig と .gitignore_global）
• プロンプト: starship/
• その他: mise/（言語ランタイム管理）、lazygit/、karabiner/（キー配列）、aerospace/（ウィンドウ管理）

新しい端末に移ったときに無いと困るもの。それが全部対象になる。

端末に置いたままだと何が起きるか

セットアップが記憶頼りになる。 前の端末で何を入れて、どう設定したかを思い出しながらやる。移行前の私は「何をどの順で入れるか」が完全に頭の中にしか無かった。しかも順序には依存関係がある。Homebrew の前に Xcode Command Line Tools が要る、みたいなやつだ。それがどこにも書かれていない。

端末間でドリフトする。 2 台目で .zshrc にエイリアスを 1 つ足す。1 台目には無い。3 か月後、1 台目で同じエイリアスを打って「あれ、効かない」となる。台数が増えるほど確実に起きる。

壊したときに戻せない。 設定をいじって動かなくなったとき、どこを触ったか分からない。.zshrc.bak .zshrc.bak2 .zshrc.old が生えていく。私はこれを何度もやった。

全部「バージョン管理されていないから」起きている。だから Git に載せる。

何を入れて、何を入れないか

入れるもの

判断基準はシンプルで、**「新しい端末で手で書き直すのが面倒なもの」**は全部入れる。

私のリポジトリはこういう構成になっている。

dotfiles/
├── shell/        # zsh 設定（zshenv / zprofile / zshrc + zsh/ 分割）
├── config/       # ~/.config へ配線するもの
│   ├── nvim/     # エディタ
│   ├── git/      # Git
│   ├── tmux/     # ターミナルマルチプレクサ
│   ├── starship/ # プロンプト
│   └── ...       # wezterm, ghostty, mise, lazygit, karabiner, aerospace, gh
├── home/         # $HOME 直下に置く単体ファイル（.editorconfig 等）
├── ssh/          # ~/.ssh/config（後述。鍵は入れない）
├── scripts/      # セットアップ用のシェルスクリプト
└── README.md     # 復元手順のメモ

README.md を軽視しないでほしい。数か月後に読み返すための手順書になる。私はここに「まっさらな Mac から復元する手順」を書いていて、リポジトリの中で一番効いている資産はこれだと思っている。設定ファイルそのものより効いている。

絶対に入れてはいけないもの

秘密情報はコミットしない。 ここが dotfiles 運用で唯一、事故ると本当に痛いポイントになる。

• SSH の秘密鍵（~/.ssh/id_ed25519 など）
• API トークン、アクセスキー
• パスワードを含む設定ファイル
• .env ファイル

公開リポジトリでなくても入れない。 private でも、後で public に切り替えたときや、コラボレータを追加したときに漏れる。一度コミットしたものは履歴に残るので、消すのも面倒だ。

私は ~/.ssh/config を入れているが、これは中身が接続先のホスト名とポート番号だけだからだ。鍵そのものは入れていない。

トークン類をどうしても管理下に置きたい場合は、暗号化したままコミットする仕組み（sops / git-crypt / age など）を使う。私は将来のために sops-nix の仕組みだけ用意してあるが、現時点で管理対象はゼロにしている。必要になるまで入れない、というのも判断のうちだ。

迷うもの

• 端末固有の設定（ディスプレイ解像度依存のもの、会社 PC 専用の proxy 設定など）→ 入れてよい。ただし後述の「端末差分」の扱いを決めてから
• アプリが自動生成する設定（起動のたびに書き換わるもの）→ 入れると差分ノイズになる。.gitignore するか、必要な部分だけ切り出す
• 巨大なバイナリ（フォント、プラグインのキャッシュ）→ 入れない。リポジトリが重くなるだけで、再取得できる

端末へどう配線するか

リポジトリを作ったら、次は ~/.zshrc からリポジトリの中身を参照させる作業に入る。やり方は主に 3 つで、後になるほど強力で、後になるほど重い。

方法 1: 手書きのシェルスクリプト

ln -s を並べたスクリプトを書く。

#!/usr/bin/env bash
DOTFILES="$HOME/ghq/github.com/yoshihiko555/dotfiles"

ln -sfn "$DOTFILES/shell/zshrc"     "$HOME/.zshrc"
ln -sfn "$DOTFILES/config/nvim"     "$HOME/.config/nvim"
ln -sfn "$DOTFILES/config/starship" "$HOME/.config/starship"
# ... 以下続く

最初はこれで十分だと思う。 依存が何もないし、何が起きているか全部読める。10 個や 20 個ならこれで回る。

弱点は、消すときの処理を手で書く必要があること（配線をやめたファイルのリンクが残り続ける）と、行数が増えると管理しづらくなることだ。

方法 2: GNU stow

stow はディレクトリ構造をそのまま ~/ に symlink として展開するツールで、dotfiles 界隈では長く定番だった。

# dotfiles/nvim/.config/nvim/init.lua という構造にしておくと
stow nvim   # → ~/.config/nvim/init.lua へリンクが張られる

リポジトリ側を「$HOME からの相対パス」の形に整えておく必要があり、そのぶんディレクトリが 1 階層深くなる。私も以前は stow を使っていた。

stow の限界は「張らない」を表現できないことにある。 ヘッドレスのサーバーに GUI アプリの設定を配りたくない、という状況で、stow にできるのは「そのコマンドを打たない」だけだ。配らないという意思がリポジトリのどこにも書かれない。

方法 3: Nix（home-manager）

後半で詳しく書くが、配線を宣言として書く方式になる。

home.file.".zshrc".source = mkLink "shell/zshrc";
xdg.configFile."nvim".source = mkLink "config/nvim";

見た目は方法 1 とあまり変わらない。違うのは、宣言から外したものが自動で消えることと、同じ仕組みでパッケージも管理できることだ。

どれを選ぶか

まだ dotfiles を運用していないなら、方法 1 から始めてほしい。 最初から Nix に行くと、dotfiles 運用そのものの学習と Nix の学習が同時に来て、たいてい途中で止まる。私自身、stow で 1 年以上運用してから Nix に移った。

運用してみると見えてくる穴

dotfiles 運用が回り始めると、これでは解決しない問題が残っているのに気づく。私が実際にぶつかった順に書く。

設定ファイルは揃うが、ツール本体は揃わない

~/.config/nvim/init.lua をリンクしても、Neovim 本体が入っていなければ意味がない。 .tmux.conf があっても tmux が無ければ動かない。

つまり dotfiles リポジトリだけでは、新端末で

brew install neovim tmux ripgrep fd fzf ghq lazygit starship zoxide ...

を手で打つ工程が残る。しかも「どれを入れたか」はリポジトリのどこにも書かれていない。Brewfile を置く手はあるが、今度は Brewfile と実態がずれていく（消したはずのツールが Brewfile に残る、逆もある）。

端末差分がシェルスクリプトの if に溜まる

2 台目、3 台目と増えると、こういう記述が .zshrc に生えてくる。

if [[ "$OSTYPE" == darwin* ]]; then
  eval "$(/opt/homebrew/bin/brew shellenv)"
fi

if [[ "$(hostname)" == "work-mac" ]]; then
  export HTTP_PROXY="http://proxy.example.com:8080"
fi

1 つ 2 つなら問題ない。ただし減ることはまずない。増える一方で、しかも「この端末では何が有効なのか」を知るには全部読むしかない。

手順の順序が、結局まだ暗黙のまま

README に手順を書いても、それは実行されない文章でしかない。書き忘れれば抜ける。更新を忘れれば古くなる。手順が正しいことを保証する仕組みがどこにもない。

プラスアルファ: ここで Nix を足す

この 3 つは、どれも「設定ファイル以外のものも宣言したい」という同じ要求に行き着く。Nix はそこを埋める道具だ。

Nix が dotfiles に足すもの

パッケージがリポジトリに書かれる。 私は CLI を 1 ファイルに宣言している。

# home/packages.nix — 3 台共通の CLI
{ pkgs, ... }:
{
  home.packages = with pkgs; [
    fd fzf gh ghq git glow lazygit mise
    neovim ripgrep starship tmux tree yazi zoxide d2
  ];
}

このファイルがそのまま「この環境に入っているものの一覧」になる。バージョンは flake.lock で固定されるので、3 台が同じところに揃う。

「入れない」が書ける。 ヘッドレスの Mac mini には GUI アプリを配らない、という意思を宣言として残せる。stow との決定的な差はここだ。私の場合、GUI アプリ（cask）は MacBook Pro に 13 個、Mac mini に 7 個で宣言が分かれている。

端末差分が宣言に移る。 シェルスクリプトの if から、ホストごとのファイルへ移る。私は 3 層に分けた。

config/nix/
├── darwin/   # Mac 2 台共通のシステム設定（WSL2 は通らない）
├── home/     # 3 台すべてで共有するユーザー設定
└── hosts/    # ホスト固有（macbook / hermes / wsl）

ルールは 2 つだけにしている。新規はまず、使うホストの hosts/ に書く。2 台以上で使い始めたら共通層へ昇格させる。 「将来使うかもしれないから共通層へ」をやると、共通層が条件分岐の塊に戻ってしまう。

設定ファイルは書き直さなくていい。 ここが一番言いたいところで、Nix を入れても既存の dotfiles を捨てる必要はない。

home-manager には設定内容を Nix の属性として書く流儀（programs.git.userName = "..." のような書き方）もあるが、私はそれを採らなかった。代わりに mkOutOfStoreSymlink を使って、リポジトリの実体を指すリンクを張っている。

# home/dotfiles.nix
{ config, hostSpec, ... }:
let
  mkLink = path: config.lib.file.mkOutOfStoreSymlink "${hostSpec.dotfilesDir}/${path}";
in
{
  home.file = {
    ".zshenv".source = mkLink "shell/zshenv";
    ".zshrc".source  = mkLink "shell/zshrc";
  };

  xdg.configFile = {
    "nvim".source     = mkLink "config/nvim";
    "git".source      = mkLink "config/git";
    "starship".source = mkLink "config/starship";
  };
}

.zshrc は .zshrc のまま、Git 管理下の素のシェルスクリプトとして残る。リポジトリを編集した瞬間に反映されるので、1 文字直すたびに再ビルド、ということもない。

Nix の導入は、これまでの dotfiles 運用を捨てて乗り換えるのではなく、その上に載せる形にできる。手書きスクリプトや stow で積んできた資産はそのまま生きる。

3 台を 1 つの設定で回す

私の場合、最終的にこうなっている。

Windows が混ざっているが、WSL2 の中身は Linux なので同じ仕組みが使える。構成の作り方は macOS 側と変わる（macOS は nix-darwin、WSL2 は home-manager 単体）。それでも共通のユーザー設定層は 3 台でそのまま共有できている。ここは一番不安だった部分だが、やってみたら一番あっさり通った。

正直に言うと、Nix で楽にならないこと

新端末構築は「1 コマンド」にはならない。 私の設計目標は「現状 8 手順・順序が暗黙 → 1 コマンド」だったが、実際にまっさらな Mac から復元する手順は今もこうなっている。

1. Xcode Command Line Tools を入れる
2. Homebrew 本体を入れる（Nix はこれを入れてくれない）
3. GitHub 認証を設定する
4. Nix 本体を入れる
5. dotfiles を clone する
6. 反映コマンドを 1 回打つ

前提手順が 5 つ残っている。手順数でいえば 8 が 6 になった程度だ。

短縮の実体は手順数ではない。変わったのは、この手順と順序がリポジトリに書いてあることだ。移行前は私の記憶の中にしか無かった。思い出しながらやる作業が、読みながらやる作業になった。実感としてはそれが一番大きい。

他にも正直なところを書いておく。

• Nix 言語の学習コストはある。 設定内容を書き直さない方針にしても、flake の外枠は書けるようにならないと始まらない
• ロールバックは設定の中身を戻さない。 世代を戻してもリンク先はリポジトリの現在の内容なので、設定を戻すのは git の仕事になる
• ディスクを食う。 世代を溜めると /nix/store が膨らむので、定期的な GC の設定が要る

始め方

今日（30 分）

1. リポジトリを作る。 dotfiles という名前で GitHub に作る。public でいい（秘密情報を入れなければ、の話だが）。

2. 一番よく触るファイルを 1 つだけ入れる。 .zshrc でも .gitconfig でもいい。

mkdir -p ~/ghq/github.com/<user>/dotfiles/shell
mv ~/.zshrc ~/ghq/github.com/<user>/dotfiles/shell/zshrc
ln -sfn ~/ghq/github.com/<user>/dotfiles/shell/zshrc ~/.zshrc

新しいシェルを開いて、今までどおり動くことを確認する。動いたらコミットする。

3. .gitignore を書く。 秘密情報を入れないための最初の防御になる。

*.key
*.pem
.env
id_*
!id_*.pub

今週

• 残りの設定ファイルを順に移す。一度に全部やらない。 1 つ移してはシェルを開き直す、を繰り返す
• リンクを張るスクリプト（前述の方法 1）を書いて、scripts/link.sh に置く
• README に「新端末での復元手順」を書き始める。この時点では不完全でいい

今月

• 2 台目の端末に clone して、実際に復元してみる。ここで README の穴が全部見つかる
• 端末固有の設定が出てきたら、その分離方法を決める（zshrc.local を .gitignore する、など）

その先

• ツール本体の管理が面倒になってきたら、Brewfile か Nix を検討する
• 端末が 3 台以上になった、あるいはシェルスクリプトの if が増えてきたら、Nix を検討するタイミングだと思う

端末が 1 台で if も生えていないなら、Nix はまだ要らない。 dotfiles 運用だけで得られるものが十分に大きいので、そこで止めていい。

まとめ

設定ファイルを端末に置かず、Git リポジトリに移してリンクを張る。これだけで新端末での復元・変更履歴・端末間の統一が同時に手に入る。秘密情報を入れないことと、配線は手書きスクリプトから始めていいこと。最初に押さえるのはこのくらいでいい。

それでも穴は残る。設定ファイルは揃ってもツール本体は揃わず、端末差分はシェルの if に溜まり、手順は暗黙のままになる。Nix はそこを埋める。既存の dotfiles を書き直さずに載せられるのも大きい。ただし「1 コマンドで新端末構築」には届かない。変わるのは手順の数ではなく、手順が記録されているかどうかだ。

正直に言うと、Nix を入れて一番効いたのは技術的な部分ではなかった気がしている。「なぜこうしたか」を書き残す習慣がついたことの方が大きい。設定そのものより、判断の履歴の方が後で効いてくる。もっともこれが Nix のおかげなのか、単に 3 台目で必要に迫られただけなのかは、まだ私自身、切り分けられていない。

私の構成は yoshihiko555/dotfiles で公開している。Nix の部分は config/nix/ 以下にあり、判断の経緯は同ディレクトリの docs/ に ADR として残してある。

私自身は今、ローカル LLM ＋ Codex CLI の2層構成で個人エージェント（Hermes Agent ベース）を回しており、ここに「中間モデル層」を追加したいという背景があった。本記事では、契約前段階で行った評価をベースに、OpenCode Go プランの料金体系・実際の使い方・中間モデル層として活かせる余地を整理する。

なお Go プランの提供モデル内訳・レート制限など、公式仕様の最新値を直接確認すべき箇所は本文中で明示している。

この記事でわかること

• OpenCode Go プランが何を提供するサブスクか（位置づけと月額条件）
• Go / Zen / Black / BYOK の料金プラン体系と、自分のユースケースでどれを選ぶべきか
• opencode run を中心とした、Go プランの実際の使い方
• 自前オーケストレーターから中間モデル層として呼ぶ発展用途の見立て
• 契約前に押さえるべき未確認事項

OpenCode Go プランとは

opencode.ai（GitHub: sst/opencode）は OSS の TUI 型 AI コーディングエージェント。Claude Code や Aider と同種のカテゴリだが、複数の料金プランを束ねた「ハーネス」として作られているのが大きな違いになる。OpenCode 自体の利用は無料で、その上にいくつかのモデル利用プランが乗っている。

Go プランは、その中で「常用ワーカーを月額固定費で確保する」用途に振った最安プラン。

設計思想としては「コーディング作業の8割は、フロンティアモデル（Opus / GPT-5 等）でなくてもこなせる」という前提に立っている。リファクタ、テスト追加、定型的な実装、軽い設計判断あたりを安いモデルで回し、本当に重い推論が必要なときだけ別の手段（後述の Zen 従量や BYOK）にスライドさせる、というのが Go プランの基本スタンスになる。

料金プラン体系の全体像

Go プランの位置を理解するには、隣接する3つの選択肢と並べた方が早い。

Zen プランの料金感

Zen は per 1M token の従量課金で、代表的な単価は以下のレンジ。

• Claude Opus 4.7: $5入力 / $25出力（per 1M tokens）
• GPT-5、Gemini、Qwen、GLM、Kimi など 40+ モデルを横断選択可能
• ベータ期間中の無料モデル枠（MiniMax M2.5、Big Pickle、Nemotron 3 Super 等）あり
• 残高 $5 を切ると自動で $20 をチャージするオートリロード
• ワークスペース／メンバー単位の月次上限設定あり

「特定モデル（Sonnet、GPT-5 mini など）を名指しで使いたい」用途は Zen 側になる。

Black プラン

Claude / GPT / Gemini のフロンティアモデルへのフルアクセスをサブスクで提供する位置づけだが、2026-05 時点で新規登録は一時停止されている。

BYOK（Bring Your Own Key）

任意の API キー（Anthropic / OpenAI ほか）を /connect コマンドで OpenCode に持ち込める。Zen の中で他モデルと併用したり、Go / Zen を契約せずハーネスだけ使う運用も可能。

Go プランを選ぶ判断基準

ここまでを踏まえて、Go プランを第一候補にすべきケースは以下のいずれかに当てはまる場合になる。

• 月額の予測可能性を最優先したい（Zen の従量課金で月末に請求額が振れるのが嫌）
• 常用モデルを Go の提供モデル群で賄えると見込める（フロンティア常用が必要ない）
• 既存の ChatGPT Plus / Claude Pro を一旦解約して、$10 のラインで体験を組み直したい

逆に、Sonnet / GPT-5 を常用モデルに据えたいなら最初から Zen 従量、フロンティア常用ならば Black（再開待ち）か BYOK での Anthropic / OpenAI 直接契約の方が筋が良い。

実際にどう使うか

OpenCode の操作系は他の TUI 型エージェントと大きくは変わらない。Go プランでの典型的な実行パターンを確認しておく。

基本: TUI で起動

opencode

これでインタラクティブな TUI が立ち上がる。Claude Code や Aider を触ったことがあれば操作感はほぼ移植可能。

Headless 実行: opencode run

スクリプトや CI、外部エージェントから呼ぶ場合は opencode run を使う。

# 一発実行
opencode run "Refactor the login logic in src/auth.ts"

# nd-JSON ストリーム + 静音モード（外部から呼ぶ用途）
opencode run --format json --quiet "..." | jq .

# モデルを明示指定
opencode run --model anthropic/claude-3-7-sonnet "Write tests for math.go"

--quiet で UI 出力を抑制、--format json で newline-delimited JSON が stdout に流れる。完了時 exit 0、エラー時は stderr ＋ 非ゼロ exit。これは Codex CLI の codex exec と同型のインターフェースで、外部エージェントから「ワーカーとして」叩く用途を意識した設計になっている。

サーバーモード: opencode serve

長時間セッションや複数同時タスクが必要なら HTTP デーモンとして起動できる。

opencode serve --port 8080
# OpenAPI 準拠の REST API がポートで待機

OPENCODE_SERVER_PASSWORD でベーシック認証、複数セッション並列駆動も可能。Python / TypeScript どちらからでも HTTP で叩ける。

設定ファイルの階層

OpenCode は Claude Code とほぼ同じ階層の設定ファイル系を持つ。

特筆すべきは Skills フォーマットが Claude Code と互換 な点で、~/.claude/skills/ 配下の既存スキル（このリポジトリで使っている /research /publish 等）をそのまま OpenCode 側で使い回すことができる。Claude Code から OpenCode にメインハーネスを移したい場合の移行コストが小さい。

Permission / Sandbox

ツール別の allow / ask / deny をパターンマッチで設定でき、sandbox: worktree でエージェントを一時 git worktree 内に閉じ込めることもできる。

{
  "permissions": {
    "bash": {
      "git *": "allow",
      "rm *": "deny"
    }
  },
  "sandbox": "worktree"
}

Hooks

Claude Code と同等のフックポイント（PreToolUse / PostToolUse / PostCompact / SubagentStart / TaskCreated）を持つ。編集後 prettier / pytest 自動実行、危険コマンドのブロックなど、Claude Code 側で組んでいるフックは概念的にそのまま移植可能。

発展: 自前オーケストレーターから中間モデル層として呼ぶ

OpenCode Go プランを単独のコーディングエージェントとして使うだけなら、ここまでの話で十分。ただ私の関心はもう一歩先で、「ローカル LLM ＋ フロンティアモデル」の2層構成にもう一段、中間モデル層を挟む構成での適合性にあった。

具体的には、Hermes Agent のような自前オーケストレーターを上に置き、軽量タスクはローカル LLM、中難度の標準実装は OpenCode Go の提供モデル群、複雑な設計判断はフロンティアモデル（Codex / Claude 等）にルーティングする運用イメージ。Go プランの $10/月という上限が読める価格帯は、この「中間層を月額固定費で抱える」用途と相性が良さそうに見える。

ただし、自前オーケストレーター側から OpenCode Go のモデル群へどう接続するか — API キーが提供されてプロバイダー直叩きできるのか、それとも opencode run などハーネス経由になるのか — は、エンドポイント仕様や提供形態の確認が必要。本記事執筆時点ではこの統合は未着手のため、ここでは「そういう発展構成も考えられる」という言及に留めておく。具体的な接続方式と検証結果は、実装後に別記事でまとめる予定。

導入判断の指針

ここまでをまとめると、OpenCode Go プランが向く人と向かない人は次のように切り分けられる。

向く人

• ChatGPT Plus / Claude Pro の月$20 を払い続けるかどうか迷っている
• ローカル LLM だけでは精度が足りないが、フロンティアモデル常用は予算的に避けたい
• 月額の予測可能性を重視する（Zen の従量課金で月末に振れるのが嫌）
• Claude Code から OpenCode へ移行を検討中で、Skills 資産を流用したい
• 個人エージェントの中間モデル層として安価な選択肢を探している

向かない人

• フロンティアモデル（Opus / GPT-5）を常用モデルに据えたい → Zen 従量 or BYOK
• エンタープライズ要件（SLA、監査ログ、SSO 等）が必須
• 既に Claude Pro / ChatGPT Plus で完結しており不満がない

月額試算

ざっくりした試算として：

• Go プラン単独: $10/月（年 $120）— 常用ワーカーがすべて Go 提供モデルで足りる場合
• Go ＋ Zen 従量混在: $10 ＋ 利用量に応じた変動（例: Sonnet を月1〜2M tokens 程度使うなら $5〜30 上乗せ）
• BYOK（OpenCode ハーネスのみ利用）: $0 ＋ プロバイダー側の API 課金

ChatGPT Plus（$20/月）を解約して Go プラン（$10/月）に振り替えれば、月$10 が浮く計算になる。Codex を別途使いたい場合は ChatGPT Plus の維持／別の経路を確保する必要があるため、純粋な置き換えにはならない点は注意。

未確認事項と次のアクション

公開情報の調査範囲では詰め切れなかった、契約前に1次情報で押さえるべき項目。

1. Go プランの具体的な提供モデルとレート制限: 公式 opencode.ai/go ページの最新仕様を直接確認する。本記事の「低価格 OSS モデル中心」は公開情報から推定したラベル付けで、提供モデルの内訳まで確定していない
2. Compaction Agent の挙動: 内部要約ヒューリスティクスは変更不可（maxSteps のみ調整可能）。長セッションで Hermes 等の外部オーケストレーターと干渉する可能性は実機でのみ判定できる
3. plan エージェントの read-only 制約: ビルトインの plan エージェントは強制 read-only。プラン → 実装の自動遷移を作る場合はカスタムエージェント定義が必要
4. ローカル LLM との物理リソース競合: ローカル LLM を回しつつ OpenCode サブプロセス／デーモンを並走させた場合のメモリ・GPU 競合は実機で要確認

私自身の次のアクションは、Go プラン契約 → 典型タスク10〜20件で精度・レイテンシを実測 → エスカレーション判定ロジックを決めてから Hermes Agent 側に組み込む、の順で進める予定。

まとめ

• OpenCode Go プランは月額固定（初月$5、翌月以降$10）で、低価格・低レイテンシモデル中心の常用ワーカー枠
• Zen / Black / BYOK と組み合わせ可能で、必要に応じて従量・フロンティア・自前 API キーへスライドできる柔軟性がある
• TUI / opencode run / opencode serve / Node.js SDK の4経路で扱え、外部エージェントから「ワーカーとして」呼びやすい設計
• Skills が Claude Code 互換で、既存資産の流用コストが小さい
• 自前オーケストレーターから中間モデル層として呼ぶ発展用途も視野に入るが、接続方式（API 直叩き／ハーネス経由）の確認は別途必要

ChatGPT Plus / Claude Pro の $20/月をそのまま払い続ける手前で、もう一段下の価格帯を試したい人にとって、Go プランは現実的な選択肢になる。私自身はまず PoC を回してから本契約に進む予定で、その結果はあらためて別記事で書きたい。

参考

• Go | OpenCode docs
• OpenCode Go 製品ページ
• Zen | OpenCode docs
• opencode.ai/docs
• github.com/sst/opencode

Harness ⊃ Context ⊃ Prompt

ハーネスエンジニアリングはプロンプトエンジニアリングを置き換えるものではない。プロンプトを含むコンテキストを含む、より外側の実行環境を設計する技術である。そしてその先には、設計書と実装の乖離を埋める AI駆動開発（SDD / TDD） という次の課題が待っている。

3つの用語の早見表

全体像を先に掴んでおこう。

この表を頭の片隅に置いて、各層を順番に見ていく。

プロンプトエンジニアリング — 命令の文言を最適化する

プロンプトエンジニアリングの目的は単純で、LLM に渡す命令文を設計して、1回の出力品質を上げること だ。対象はあくまで「単一のプロンプト文字列」であり、それ以外は触らない。

何を解決してきたか

2020年の GPT-3 論文（Brown et al., arXiv:2005.14165）が示した Few-shot Learning が出発点だ。タスクを説明する代わりに、入出力例を2〜3個見せるだけでモデルがパターンを学習して続きを生成する。この発見によって、プロンプトは単なる命令文から「プログラミング可能な入力インターフェース」に変わった。

2022年末に ChatGPT が公開されると、この技術は一気に広まり、「プロンプトエンジニア」という職種まで生まれる。同時期に体系的な手法もまとまって出揃った。

主要技法（論文引用付き）

• Chain-of-Thought (CoT) — Wei et al. (2022) arXiv:2201.11903
  中間推論ステップを明示するだけで複雑な算数・論理問題の精度が大幅に向上する。ただし効果が顕著なのは100B以上の大規模モデルに限られる。
• Zero-Shot-CoT — Kojima et al. (2022) arXiv:2205.11916
  "Let's think step by step" の一文を足すだけで MultiArith の精度が 17.7% → 78.7% に跳ねた。プロンプト1行の威力を象徴する論文。
• Self-Consistency — Wang et al. (2022) arXiv:2203.11171
  複数の推論パスを生成して多数決を取る。Greedy decoding より安定する。
• ReAct — Yao et al. (2022) arXiv:2210.03629
  推論（Reason）と行動（Act）を交互に実行するフレームワーク。後のエージェント設計の原型になった。
• Tree of Thoughts — Yao et al. (2023) arXiv:2305.10601
  推論を木構造で展開し、BFS/DFS で探索・枝刈りする。
• Reflexion — Shinn et al. (2023) arXiv:2303.11366
  失敗を「言語的な反省」としてコンテキストに追記し、次の試行を改善する。

失敗モードと限界

プロンプトエンジニアリングは強力だが、以下の壁にぶつかる。

• プロンプトの脆弱性: モデルバージョンが変わると、同じプロンプトでも結果が崩れる。特に OpenAI の GPT-4 系のマイナーアップデートで既存プロンプトが動かなくなる事例は枚挙にいとまがない。
• 長期タスクで文脈が失われる: 単一プロンプトでは複数ファイルにまたがる実装や、数十ステップの推論を扱えない。
• 近代モデルによる内部化: GPT-4o や Claude 3.5 以降、CoT は明示しなくてもモデル内部でほぼ自動的に実行される。「Let's think step by step」の効果は相対的に小さくなった。

今の位置付け

プロンプトエンジニアリングが消滅したわけではない。Fine-tuning のデータ設計、単一ターンのクリエイティブタスク、Few-shot でのタスク特化など、今でも必須の基礎技術 だ。ただし複雑なエージェント系タスクでは、プロンプトは「より大きな仕組みの一部品」として扱われるようになった。この「より大きな仕組み」が次の2つの概念である。

コンテキストエンジニアリング — 情報アーキテクチャを設計する

コンテキストエンジニアリングは、「何を言うか」ではなく「何を見せるか」 にフォーカスする技術だ。プロンプトの文言を磨く代わりに、コンテキストウィンドウという限られた領域に どの情報を、どの順序で、どのタイミングで投入するか を設計する。

用語自体は比較的新しい。2025年6月18日に Shopify CEO の Tobi Lütke が X で次のように投稿した。

"I really like the term 'context engineering' over prompt engineering. It describes the core skill better: the art of providing all the context for the task to be plausibly solvable by the LLM." — Tobi Lütke (2025-06-18)

これに Andrej Karpathy が返信する形 で2025年6月25日に投稿したのが、後に広く引用されることになる次のツイートだ。

"+1 for 'context engineering' over 'prompt engineering'. People associate prompts with short task descriptions you'd give an LLM in your day-to-day use. When in every industrial-strength LLM app, context engineering is the delicate art and science of filling the context window with just the right information for the next step." — Andrej Karpathy (2025-06-25)

Karpathy は別の場面で LLM を OS に例え、「LLM は CPU、コンテキストウィンドウは RAM」 という比喩も提唱している。モデルの能力を引き出すには、この RAM をどう管理するかが次の核心スキルだというわけだ。

Lost in the Middle — 理論的根拠

コンテキストエンジニアリングが単なる流行語ではなく技術として成立する根拠を与えたのが、Liu et al. (2023) "Lost in the Middle: How Language Models Use Long Contexts" (arXiv:2307.03172) である。

この論文が示したのは次の事実だ。

• LLM の情報取得精度は U字型カーブ になる。コンテキストの先頭と末尾の情報は正確に処理されるが、中間部分の情報は著しく無視される。
• 関連文書を先頭または末尾に配置するだけで精度が大きく改善する。
• コンテキストが長くなるほど、中間部の「Needle」（重要情報）を見落とす確率が上がる。

「全部放り込めば勝手に読んでくれる」という期待は、この論文でほぼ崩された。長いコンテキストは高価なだけでなく、性能劣化の原因にもなる。後の "Context Rot"（文脈の腐敗）や "Context Pollution"（文脈の汚染）という概念は、この論文の実証を出発点にしている。

主要テクニック

• RAG (Retrieval-Augmented Generation) — Lewis et al. (2020) arXiv:2005.11401
  実は RAG の原論文は GPT-3 と同じ2020年に出ている。当時は「外部知識を注入する1手法」として見られていたが、コンテキストエンジニアリングの文脈では 中心的な技法 として再評価されている。
• Structured Context（XML タグ）
  Anthropic が推奨する手法で、システム指示・ユーザー入力・ツール出力を XML タグで明確に区切る。Claude ファミリーはこの構造を学習時から意識しているため、特に効果が高い。
• Context Compression / Summarization
  ツール実行の生ログや過去の会話履歴を要約に置き換える。Attention Budget を節約するための基本技法。
• Memory Management（短期 / 長期）
  セッション内の情報は短期メモリ、外部ストレージ（ベクター DB、ファイルシステム）に永続化するのは長期メモリ。claude-mem のようなツールはこの長期メモリを担う。
• MCP (Model Context Protocol)
  Anthropic が策定したオープン標準で、ツールやデータソースを「Just-in-Time」でコンテキストに注入する仕組み。ただし後述のように これ自体が新たな失敗モード を生んでいる。

失敗モード

コンテキストエンジニアリングには独自の失敗パターンがある。

• MCP の肥大化: MCP サーバーを複数接続すると、ツール定義だけでコンテキストを数千〜数万トークン消費する。モデルが「何を使うか」を判断する前に、ツール定義で窒息する現象。
• CLAUDE.md / AGENTS.md の肥大化: プロジェクト固有のルールを書き溜めていくと、ファイル自体が Context Pollution の原因になる。「重要だから」と書けば書くほど、本当に重要な情報が埋もれていく皮肉。
• Context Rot: 長時間のセッションで古い情報・失敗した試行のログ・重複した出力が蓄積し、モデルのパフォーマンスが徐々に劣化する。

実務テクニック

上記を踏まえた実務的な対処は次のようになる。

• 最重要制約は コンテキストの末尾 に配置する（Lost in the Middle を逆手に取る）
• サブエージェントは Stateless で動かし、オーケストレーター本体のコンテキストを汚染しない
• 必要ない MCP は接続しない。allowedTools で制限する
• CLAUDE.md は定期的に剪定する。「書き溜める」のではなく「育てる」

ここまで来ると、鍵は「単発のプロンプト品質」から「セッション全体の情報設計」に移っていることがわかる。これをもう一段外側に広げたのがハーネスエンジニアリングだ。

ハーネスエンジニアリング — モデルを囲む実行環境を設計する

ハーネスエンジニアリングは、LLM モデル本体を取り囲む「実行環境・ルール・ツール群・検証ループ」 を設計する技術である。プロンプトでもコンテキストでもなく、モデルが動く土台そのもの を最適化する。

この概念が明示的に語られるようになったのは2025年以降、Claude Code・Cursor・Cline などのエージェント型コーディングツールが普及してからだ。背景にあるのは次のような逆転だ。

弱いモデル + 堅牢なハーネス > 強いモデル + 貧弱なハーネス

「良いプロンプトを書く」ことより「良い実行環境を組む」ことの方が、実運用の品質を左右する。自分自身、Claude Code を数ヶ月使っていて、プロンプトを工夫するより .claude/rules/ にルールを追記する方が効く場面の方が圧倒的に多かった。この感覚を言語化したのがハーネスエンジニアリングである。

構成要素（Claude Code を例に）

Claude Code のハーネスは大きく4つの要素で構成されている。

1. Hooks — 実行ループへの介入

Claude Code には PreToolUse / PostToolUse / UserPromptSubmit / SessionStart といったフックがあり、任意のスクリプトを差し込める。例えばこんな使い方ができる。

# .claude/hooks/check-codex-before-write.py
# Edit/Write ツール実行前に Codex CLI に設計相談を促す
if tool_name in ("Edit", "Write") and is_significant_change(file_path):
    print("[Codex Suggestion] Consider consulting Codex before this change")

フックは モデルの判断に委ねるのではなく、宣言的にループを制御する 装置だ。プロンプトで「設計を相談してから書いてね」と頼むより、フックで強制するほうがはるかに確実である。

2. Rules / CLAUDE.md — 不変の制約

CLAUDE.md や .claude/rules/*.md に書かれた内容は、セッション開始時にシステムプロンプトへ自動注入される。「日本語で返答する」「main ブランチに直接 push しない」「テストを書いてから実装する」といった、プロジェクトの不変のルール を記述する場所だ。

コンテキストエンジニアリングの観点からは「肥大化に注意」と書いたが、ハーネスの観点では「動的に変わらない制約をコードで表現する」という役割を持つ。

3. Skills / Subagents — 再利用可能なワークフロー

Skill（.claude/skills/*/SKILL.md）はタスクに特化したワークフローを定義する仕組みで、Subagent（.claude/agents/*.md）は特定の役割を持つエージェントを独立コンテキストで動かす仕組みだ。ポイントは Stateless に動かせる こと。オーケストレーター本体のコンテキストを汚染せずに、重い処理を並列で回せる。

4. Tool Restrictions / Sandbox — 行動の制約

read-only や workspace-write のようなサンドボックスモード、allowedTools での許可リストは、モデルができる行動を物理的に制限する。プロンプトで「破壊的な操作はしないで」とお願いするのではなく、そもそもできないようにする のがハーネスの思想だ。

性能への影響 — SWE-bench での実証

ハーネスの効果は実データで示されている。SWE-bench（Jimenez et al., arXiv:2310.06770）は実際の GitHub Issue を LLM に解かせるベンチマークで、Anthropic が公開した Claude の SWE-bench Verified スコア推移が興味深い。

• 2024-06 Claude 3.5 Sonnet（モデル単体）: 33.4% (公式発表)
• 2024-10 Claude 3.5 Sonnet Updated: 49.0% (同上)
• 2025-02 Claude 3.7 Sonnet（素のモデル）: 62.3% (公式発表)
• 2025-02 Claude 3.7 Sonnet（custom scaffold 込み）: 70.3% ← +8.0% (同上)

注目すべきは 2025年2月の行だ。同じモデルに対してカスタムスキャフォールド（並列サンプリング・回帰テスト・拡張思考モードを組み合わせたハーネス）を被せるだけでスコアが 8 ポイント上がる。この差は、モデルの世代交代1回分に匹敵する大きさだ。

失敗モード

ハーネスエンジニアリングにも固有の失敗がある。

• 設計の複雑化: Hooks・Rules・Skill が増えるにつれ、誰が何を制御しているのか追いづらくなる
• サブエージェント間の状態管理: 複数のサブエージェントが並列で動くと、それぞれの結果を統合するオーケストレーションが難題になる
• コスト: 検証ループ・サブエージェント・フックはすべてトークン消費を増やす
• ハーネス設計スキルの希少性: 「良いプロンプト」を書ける人は増えたが、「良いハーネス」を組める人はまだ少ない

3層の関係 — 階層的包含とタイムライン

ここまでで見えてきたのは、3つが 置き換えではなく包含関係 にあるという事実だ。図にするとこうなる。

┌─────────────────────────────────────────────┐
│          Harness Engineering                │
│  （Hooks・Sandbox・サブエージェント）           │
│  ┌───────────────────────────────────────┐  │
│  │       Context Engineering             │  │
│  │  （RAG・Memory・構造化・MCP）            │  │
│  │  ┌─────────────────────────────────┐  │  │
│  │  │     Prompt Engineering          │  │  │
│  │  │  （Few-shot・CoT・Zero-shot）    │  │  │
│  │  └─────────────────────────────────┘  │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

この階層で最も重要なメッセージはこれだ。

上位層の設計ミスは、下位層の最適化では救えない。

ハーネスが壊れていれば、どんなに良いコンテキスト設計もプロンプトも無駄になる。逆に、ハーネスさえ整っていれば、プロンプトの細かいチューニングに消耗する必要はなくなる。

短いタイムラインで振り返ると、次のようになる。

• 2020 GPT-3 論文 / RAG 論文
• 2022 ChatGPT 公開 / CoT・ReAct 論文ラッシュ
• 2023 Lost in the Middle / SWE-bench 公開
• 2024 MCP 策定
• 2025-02 Claude Code リリース、カスタムスキャフォールドで +8% を公式実証
• 2025-06 Lütke → Karpathy の流れで Context Engineering が一気に浸透
• 2026 Harness Engineering の議論が本格化

3つはいずれも、前の世代の限界にぶつかったことで生まれた。そしてハーネスエンジニアリングにも、次の壁が見え始めている。

ハーネスの先にある課題 — 設計と実装の乖離

ハーネスを組み立てて運用していると、ある時期から気になってくる問題がある。設計書と実装の乖離だ。

何が起きるか

具体的にはこんな現象だ。

• Hooks・Rules・Skill が増えるにつれ、「このルールは何のためにあったのか」を誰も覚えていない状態になる
• CLAUDE.md や要件定義ドキュメントと実装の間にズレが溜まっていく。コードが変わっても仕様書は更新されない
• AI が仕様書より実装を信じる。「動くコード」が真実になり、「書かれた仕様」は形骸化する
• テストが通っていることを根拠に「正しい」と誤認する。テストがそもそも仕様と乖離している可能性には気づかない

これは「ハーネスが悪い」のではない。ハーネスは 実行時の制御 には強いが、設計と実装の一貫性を担保する仕組み は別に必要なのだ。

なぜ起きるか

原因は2つある。

1. AI はコードを一次ソースと見なしやすい: 仕様書とコードが矛盾していたら、AI はコードを正として仕様書を無視する傾向がある。特にコンテキストに両方が入っていると、より直近で更新されたコードが優先されやすい
2. ハーネスは「実行時」に作用する: Hooks や Rules は「今まさに AI が動こうとしている瞬間」に介入する装置だ。設計判断が行われるのは 実装より前 なので、ハーネスだけでは手が届かない

次の一歩 — AI駆動開発（SDD / TDD）

この問題に対する答えとして浮上しているのが、仕様を一次ソースに置く開発手法 である。いわゆる AI駆動開発の文脈だ。

Spec-Driven Development (SDD)
仕様書を中心に据え、そこから実装・テスト・ドキュメントを AI に生成させる。仕様が変わったらコードを再生成する、という逆転した関係を作る。2025年には GitHub の Spec Kit や Amazon の Kiro のように、仕様駆動を前提にしたツールが相次いで登場した。

Test-Driven Development (TDD)
テストを「実行可能な仕様」として AI に渡す。テストが先にあり、実装はそれを満たすように生成する。AI駆動 TDD では、テストがそのままハーネスの検証ループに組み込まれる。「テストが通ったら次のタスクへ」という確定的な進行が可能になる。

どちらも、「検証ループの確定性」を ハーネスの外側から 与える仕組みだ。

ハーネス × SDD/TDD の位置付け

重要なのは、これらがハーネスエンジニアリングと 対立するものではない ということだ。むしろ並行・補完関係にある。

• ハーネス: 実行時の制御・安全弁・ループの骨格
• SDD / TDD: 設計と検証の一貫性・真実の置き場所

ハーネスが AI の「行動の仕方」を決めるなら、SDD/TDD は AI に渡す「真実の源」を決める。両方が揃って初めて、「AI に仕事を任せても仕様と実装がズレない」状態が作れる。

実践ロードマップ — どの順序で学ぶか

ここまでの内容を踏まえて、学ぶ順序を整理しておく。

1. プロンプトエンジニアリング: 基礎として必須。CoT / ReAct / Few-shot の論文は原典を1本ずつ読むといい
2. コンテキストエンジニアリング: Lost in the Middle 論文と Karpathy の発言を押さえたうえで、実際に MCP / RAG を使ってみる
3. ハーネスエンジニアリング: Claude Code なり Cursor なりで Hooks・Rules・Skill を実装してみる。SWE-bench のスコア推移を追うと効果の大きさが実感できる
4. SDD / TDD（並行）: 3と並行して、仕様を一次ソースに据える開発手法に触れる。Kiro / Spec Kit / AI駆動 TDD の事例を追う

順序は大事だが、3と4は直列ではなく並行がおすすめだ。ハーネスを組みながら「この仕組みは設計書とズレていないか？」と問い続ける癖をつけると、後で仕様ドリフトに気づいたときの修正コストがだいぶ下がる。

まとめ

3層の関係をもう一度整理すると、こうなる。

• プロンプトエンジニアリングは命令の文言を最適化する技術。1回の入出力品質を上げる
• コンテキストエンジニアリングはコンテキストウィンドウの情報設計。何をどの順序で見せるかを決める
• ハーネスエンジニアリングはモデルを囲む実行環境の設計。Hooks・Rules・Skill でループを制御する
• そしてその先には、SDD / TDD による設計と実装の一貫性という次の課題がある

3つは置き換えではなく階層的な包含関係にあり、上位層の設計ミスは下位層では救えない。AI 連携で詰まっているときは、まずこの問いを自分に投げてみてほしい。

「今の課題は、どの層の問題か？」

プロンプトをいじっても直らない問題は、たいてい1つ上の層にある。そして、ハーネスまで組んでもなお残る問題は、もう層の外——仕様そのものの置き場所の問題である可能性が高い。

参考文献

論文

• Brown et al. (2020). "Language Models are Few-Shot Learners." arXiv:2005.14165
• Lewis et al. (2020). "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks." arXiv:2005.11401
• Wei et al. (2022). "Chain-of-Thought Prompting Elicits Reasoning in Large Language Models." arXiv:2201.11903
• Kojima et al. (2022). "Large Language Models are Zero-Shot Reasoners." arXiv:2205.11916
• Wang et al. (2022). "Self-Consistency Improves Chain of Thought Reasoning." arXiv:2203.11171
• Yao et al. (2022). "ReAct: Synergizing Reasoning and Acting in Language Models." arXiv:2210.03629
• Shinn et al. (2023). "Reflexion: Language Agents with Verbal Reinforcement Learning." arXiv:2303.11366
• Yao et al. (2023). "Tree of Thoughts: Deliberate Problem Solving with Large Language Models." arXiv:2305.10601
• Liu et al. (2023). "Lost in the Middle: How Language Models Use Long Contexts." arXiv:2307.03172
• Jimenez et al. (2024). "SWE-bench: Can Language Models Resolve Real-World GitHub Issues?" arXiv:2310.06770

ブログ・発言

• Tobi Lütke (2025-06-18). "I really like the term 'context engineering' over prompt engineering..." X投稿
• Andrej Karpathy (2025-06-25). "+1 for 'context engineering' over 'prompt engineering'..." X投稿
• Anthropic (2024-10). "Introducing computer use, a new Claude 3.5 Sonnet, and Claude 3.5 Haiku." https://www.anthropic.com/news/3-5-models-and-computer-use
• Anthropic (2025-02). "Claude 3.7 Sonnet and Claude Code." https://www.anthropic.com/news/claude-3-7-sonnet
• Anthropic — Claude Code 公式ドキュメント（CLAUDE.md, Hooks, Skills）

JWT認証には相反する2つの要件がある。

• セキュリティ: トークンは短命であるべき。盗まれた場合の被害を最小化できる
• ユーザー体験: 操作中にセッションが切れるとストレスになる

この2つを両立するために、多くのシステムでは「絶対有効期限」と「アイドルタイムアウト」を組み合わせる。

Auth.js v5はスライディングウィンドウをネイティブでサポートしているが、絶対有効期限は手動実装が必要になる。この記事では両方を組み合わせる実装パターンを解説する。

Auth.js v5のJWTセッション戦略

Auth.js v5（旧NextAuth.js v5）のJWTセッション戦略は、v4から大きく変わった。

JWE暗号化クッキー

Auth.js v5のJWTトークンは**JWE（JSON Web Encryption）**で暗号化され、HttpOnlyクッキーに格納される。

• 暗号化方式: A256CBC-HS512（AES-256-CBC + HMAC-SHA-512）
• 鍵導出: AUTH_SECRET からHKDFで導出。クッキー名がsaltとして使われる
• ストレージ: __Secure-authjs.session-token という名前のHttpOnly / Secure / SameSite=Laxクッキー

v4ではJWSE（署名のみ）だったが、v5ではJWE（暗号化）に変更された。この変更により、クライアントサイドでトークンの中身を読み取ることはできない。バックエンド（Django等）でAuth.jsのトークンを直接復号するのも非現実的であり、後述のToken Exchangeパターンが推奨される理由の一つである。

jwt / session コールバック

Auth.js v5の認証フローの中核は2つのコールバックである。

// auth.ts
import NextAuth from "next-auth"

export const { handlers, auth, signIn, signOut } = NextAuth({
  session: { strategy: "jwt" },
  callbacks: {
    // 1. jwt callback: トークンの生成・更新を担当
    //    - 初回ログイン時: user, account が渡される
    //    - 以降のリクエスト: token のみ（既存トークンの読み取り）
    async jwt({ token, user, account }) {
      if (account && user) {
        // 初回ログイン時のみ実行される
        token.userId = user.id
      }
      return token
    },

    // 2. session callback: クライアントに公開する情報を整形
    //    - jwt callback の後に毎回実行される
    async session({ session, token }) {
      session.user.id = token.userId as string
      return session
    },
  },
})

実行順序:

• 初回ログイン: signIn → jwt（token生成）→ session（整形）→ redirect
• 以降のリクエスト: jwt（token読み取り・更新）→ session（整形）→ authorized（ルート保護）

Edge Runtime対応の設計分割

Next.js App RouterのMiddlewareはEdge Runtimeで動作する。Auth.js v5でMiddlewareを使う場合、Node.jsランタイム専用の処理（DBアクセス等）を分離する必要がある。

auth.config.ts  ← Edge互換。Middleware から import する
auth.ts         ← Node.js用。DBアクセスを含むプロバイダー設定
middleware.ts   ← auth.config.ts を使用

// auth.config.ts（Edge互換）
import type { NextAuthConfig } from "next-auth"

export const authConfig = {
  session: { strategy: "jwt" },
  pages: {
    signIn: "/login",
  },
  callbacks: {
    // jwt, session, authorized コールバックをここに定義
  },
} satisfies NextAuthConfig

// auth.ts（Node.js用）
import NextAuth from "next-auth"
import { authConfig } from "./auth.config"
import Credentials from "next-auth/providers/credentials"

export const { handlers, auth, signIn, signOut } = NextAuth({
  ...authConfig,
  providers: [
    Credentials({
      // DBアクセスを含む認証ロジック
    }),
  ],
})

二重タイムアウトの設計

なぜ片方だけでは不十分なのか

絶対有効期限だけの場合:

ユーザーがログインして10分操作し、その後7時間50分離席しても、セッションは生きている。共有PCや公共の場所では深刻なセキュリティリスクになる。

アイドルタイムアウトだけの場合:

ユーザーが自動化スクリプトやバックグラウンドのポーリングで定期的にAPIを叩いていると、セッションが永遠に延長される。トークンが漏洩した場合、攻撃者も同じ手法で無期限にセッションを維持できる。

両方を組み合わせることで「普段は操作に応じて延長されるが、どんなに操作し続けても8時間後には再認証が必要」という挙動を実現できる。

Auth.js v5での設計方針

maxAge と updateAge はAuth.js v5のネイティブ機能だが、absoluteExpiry は jwt コールバック内で手動管理するカスタムフィールドである。

実装：jwt callbackで二重タイムアウト

以下が二重タイムアウトの中核実装である。

// auth.config.ts
import type { NextAuthConfig } from "next-auth"

const ABSOLUTE_TIMEOUT_SECONDS = 8 * 60 * 60 // 8時間
const IDLE_TIMEOUT_SECONDS = 30 * 60          // 30分

export const authConfig = {
  session: {
    strategy: "jwt",
    maxAge: IDLE_TIMEOUT_SECONDS,  // 30分でクッキー失効
    updateAge: 0,                   // 毎リクエストでクッキー延長
  },
  callbacks: {
    async jwt({ token, user, account }) {
      // 初回ログイン時: 絶対有効期限を埋め込む
      if (account && user) {
        return {
          ...token,
          absoluteExpiry: Date.now() + ABSOLUTE_TIMEOUT_SECONDS * 1000,
        }
      }

      // 絶対有効期限チェック
      if (Date.now() > (token.absoluteExpiry as number)) {
        // 8時間経過 → セッション無効化
        return null
      }

      // ここに到達 = アイドルタイムアウト内 & 絶対有効期限内
      // maxAge + updateAge:0 の組み合わせでクッキーが自動延長される
      return token
    },

    authorized({ auth, request }) {
      // BFF APIへのリクエストのみJWT検証
      const isApiRoute = request.nextUrl.pathname.startsWith("/api")
      if (isApiRoute) {
        return !!auth
      }
      return true
    },
  },
  pages: {
    signIn: "/login",
  },
} satisfies NextAuthConfig

フローの整理:

[ユーザーログイン]
  → jwt callback: absoluteExpiry = now + 8h をトークンに埋め込み
  → クッキー保存（maxAge: 30min）

[5分後にAPIアクセス]
  → jwt callback: absoluteExpiry > now → OK
  → updateAge: 0 → クッキーのExpiresをリセット（+30min）

[さらに30分放置]
  → クッキー自体が期限切れ → auth = null → 401

[8時間アクティブに操作し続けた場合]
  → jwt callback: absoluteExpiry < now → return null → セッション強制無効化

型定義の拡張

TypeScriptで absoluteExpiry をトークンの型に追加する。

// types/next-auth.d.ts
import "next-auth/jwt"

declare module "next-auth/jwt" {
  interface JWT {
    absoluteExpiry: number
    djangoToken?: string
  }
}

実装：Next.js MiddlewareでBFF API保護

MiddlewareはBFF APIルート（/api/*）へのリクエスト時にのみJWT検証を行う。ページ遷移にはMiddlewareを適用しない設計とする。

// middleware.ts
import NextAuth from "next-auth"
import { authConfig } from "./auth.config"

export const { auth: middleware } = NextAuth(authConfig)

export default middleware

export const config = {
  // BFF APIルートのみにマッチ
  matcher: ["/api/:path*"],
}

この設計の利点:

• ページは自由にアクセス可能: 未認証でもページを表示し、フロントエンド側で認証状態に応じたUIを出し分ける
• API層で一括保護: 認証が必要なデータアクセスはすべてBFF API経由にすることで、保護漏れを防ぐ
• Edge Runtimeで動作: auth.config.ts のみを使うため、Node.js依存がない

認証失敗時のレスポンス

authorized コールバックが false を返した場合、Auth.js v5はデフォルトで pages.signIn にリダイレクトする。APIルートの場合はリダイレクトではなく401レスポンスを返したいケースが多い。

// auth.config.ts の authorized コールバック（拡張版）
authorized({ auth, request }) {
  const isApiRoute = request.nextUrl.pathname.startsWith("/api")

  if (isApiRoute && !auth) {
    return Response.json(
      { error: "Unauthorized" },
      { status: 401 }
    )
  }

  return true
},

Django連携：Token Exchangeパターン

なぜAuth.jsのトークンをDjangoに直接渡せないのか

Auth.js v5のJWTはJWE（暗号化）されており、AUTH_SECRET とHKDFから導出された鍵で暗号化されている。Djangoでこの暗号化を再現するのは現実的ではない。

代わりにToken Exchangeパターンを使う。Auth.jsのJWTとは別に、Django独自のJWTを発行・管理する。

アーキテクチャ

[ログイン時]
  Browser → Next.js → Auth.js (認証)
                         ↓
                    jwt callback → Django /api/auth/token/ を呼び出し
                         ↓
                    Django JWT を取得 → Auth.js token に djangoToken として格納

[APIリクエスト時]
  Browser → /api/data → Middleware (Auth.js JWT検証)
                           ↓ OK
                      Route Handler → token から djangoToken を取り出し
                           ↓
                      Django API (Authorization: Bearer <djangoToken>)
                           ↓
                      Django が自身のJWTを独立検証

実装

// auth.ts
import NextAuth from "next-auth"
import { authConfig } from "./auth.config"
import Credentials from "next-auth/providers/credentials"

export const { handlers, auth, signIn, signOut } = NextAuth({
  ...authConfig,
  providers: [
    Credentials({
      async authorize(credentials) {
        // 1. ユーザー認証（DB検証等）
        const user = await verifyCredentials(credentials)
        if (!user) return null

        // 2. Django JWT を取得
        const djangoRes = await fetch(
          `${process.env.DJANGO_API_URL}/api/auth/token/`,
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
              username: credentials.email,
              password: credentials.password,
            }),
          }
        )
        const djangoTokens = await djangoRes.json()

        return {
          ...user,
          djangoToken: djangoTokens.access,
          djangoRefreshToken: djangoTokens.refresh,
        }
      },
    }),
  ],
  callbacks: {
    ...authConfig.callbacks,
    async jwt({ token, user, account }) {
      // 親の jwt callback を先に実行（absoluteExpiry チェック）
      const baseToken = await authConfig.callbacks.jwt({ token, user, account })
      if (!baseToken) return null

      // 初回ログイン時: Django トークンを格納
      if (account && user) {
        baseToken.djangoToken = (user as any).djangoToken
        baseToken.djangoRefreshToken = (user as any).djangoRefreshToken
      }

      return baseToken
    },
  },
})

// app/api/data/route.ts（BFF APIの例）
import { auth } from "@/auth"

export async function GET() {
  const session = await auth()
  if (!session) {
    return Response.json({ error: "Unauthorized" }, { status: 401 })
  }

  // Django APIにトークンを転送
  const res = await fetch(`${process.env.DJANGO_API_URL}/api/data/`, {
    headers: {
      Authorization: `Bearer ${session.djangoToken}`,
    },
  })

  const data = await res.json()
  return Response.json(data)
}

Django側の設定

# settings.py
from datetime import timedelta

SIMPLE_JWT = {
    "ACCESS_TOKEN_LIFETIME": timedelta(hours=8),  # Auth.js側と合わせる
    "REFRESH_TOKEN_LIFETIME": timedelta(hours=8),
    "ROTATE_REFRESH_TOKENS": False,
}

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ],
}

Django側のトークン有効期限もAuth.js側の絶対有効期限（8時間）に合わせておくと、タイムアウトの不整合を防げる。

Django側でもJWT検証すべき理由

Token Exchangeは「Django側でも検証する」設計が前提である。

• 多層防御: Next.js BFFのバグがあってもDjango側で不正リクエストを遮断できる
• 将来の拡張: モバイルアプリや他のクライアントがDjango APIに直接アクセスする場合にも対応可能
• 責務の分離: 認証の責任がNext.jsに集中しない

落とし穴と対策

1. トークンリフレッシュのRace Condition

複数のAPIリクエストが同時に発生した場合、jwt コールバックが並行して実行される。Djangoのリフレッシュトークンがワンタイム（ROTATE_REFRESH_TOKENS: True）の場合、先に実行されたリクエストがトークンをローテーションし、後続のリクエストが古いリフレッシュトークンで失敗する。

対策: Django側で ROTATE_REFRESH_TOKENS: False に設定するか、Auth.js側でリフレッシュにロック機構を実装する。この記事の設計ではアクセストークンの有効期限を8時間にしているため、頻繁なリフレッシュは発生しない。

2. Edge Runtime互換

middleware.ts はEdge Runtimeで動作する。Node.jsの crypto モジュールを直接使うコードがあるとランタイムエラーになる。

対策: auth.config.ts（Edge互換）と auth.ts（Node.js用）を分割し、MiddlewareからはEdge互換のファイルのみを参照する。

3. updateAge: 0 のトレードオフ

updateAge: 0 は毎リクエストでSet-Cookieヘッダーを返すことを意味する。CDNキャッシュとの相性が悪く、レスポンスヘッダーのサイズも増える。

対策: APIルートのみにMiddlewareを適用し（matcher: ["/api/:path*"]）、静的アセットやページへのリクエストではクッキー更新が走らないようにする。パフォーマンスへの影響が気になる場合は updateAge: 60（1分）程度に設定し、厳密な30分ではなく最大31分のアイドルタイムアウトとして許容する方法もある。

まとめ

本記事の設計パターンの全体像を整理する。

┌──────────────┐
│   Browser    │
└──────┬───────┘
       │ fetch('/api/...')
       ▼
┌──────────────────────────────────────┐
│  Next.js Middleware (Edge Runtime)    │
│  ┌────────────────────────────────┐  │
│  │ Auth.js jwt callback           │  │
│  │ 1. absoluteExpiry > now?       │  │
│  │ 2. authorized → auth 存在?     │  │
│  └────────────────────────────────┘  │
│  maxAge: 30min / updateAge: 0        │
└──────┬───────────────────────────────┘
       │ 検証OK
       ▼
┌──────────────────────────────────────┐
│  Next.js BFF API (Route Handler)     │
│  token から djangoToken を取り出し     │
│  Authorization: Bearer <djangoToken>  │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  Django REST Framework               │
│  simplejwt で独立検証                  │
│  ACCESS_TOKEN_LIFETIME: 8h            │
└──────────────────────────────────────┘

各コンポーネントの責務

Auth.js v5の設定値まとめ

この設計により、「普段は操作に応じてセッションが延長されるが、8時間後には再認証が必要」という要件を Auth.js v5 のネイティブ機能とカスタム実装の組み合わせで実現できる。

CLAUDE.mdの基本をおさらいする

本題に入る前に、CLAUDE.mdの基本を簡単に振り返る。

CLAUDE.mdはClaude Codeがセッション開始時に自動で読み込む設定ファイルである。プロジェクトルートに置くだけで、毎回のセッションで自動的にコンテキストとして注入される。

読み込みには3つの階層がある。

• グローバル（~/.claude/CLAUDE.md）: 全プロジェクトに共通する個人の好み
• プロジェクト（プロジェクトルート/.claude/CLAUDE.md）: リポジトリ固有の文脈
• サブディレクトリ（各ディレクトリのCLAUDE.md）: 領域固有の設定

新しいチームメンバーに渡す「業務マニュアル」のようなものだ。これがないと、Claude Codeは毎回ゼロからプロジェクトを理解しようとする。

ここまでは入門レベルの話で、すでに解説記事も多い。この記事で書きたいのはその先、CLAUDE.mdを「完成させるもの」ではなく「育てるもの」として扱う考え方についてである。

仕様書丸投げが失敗する構造的な理由

Claude Codeに仕様書Markdownを丸ごと貼り付けて「この通りに実装して」と指示すると、3つの構造的な問題が起きる。

1. コンテキスト過負荷で重要部分が埋もれる

LLMのコンテキストウィンドウには物理的な上限がある。1万行の仕様書を渡した場合、モデルの注意が全体に散らばる。人間なら「ここが重要」と読み飛ばせるが、LLMにはその取捨選択が難しい。仕様書の後半に書いた制約条件が実装に反映されない、というのはよくある話だ。

2. 既存コードのパターンを無視する

仕様書を「正」として渡すと、Claude Codeは既存のコーディングパターンより仕様書の記述を優先する。プロジェクトではcamelCaseを使っているのに、仕様書にsnake_caseの例が含まれていればそちらに引きずられる。既存コードとの一貫性が崩れるのは、だいたいこれが原因だ。

3. 複数ファイルの整合性が崩れる

仕様書は往々にして複数の機能を横断的に記述している。「認証フロー」の仕様にはフロントエンド・バックエンド・DB設計が混在する。Claude Codeはこれを一度に処理しようとして、ファイル間の依存関係を見失う。型定義とAPIレスポンスの不整合、importの漏れ、テストとの乖離が生まれる。

プロンプトの書き方が悪いのではない。仕様書を丸ごと渡すこと自体に無理がある。

「渡す」と「育てる」は何が違うのか

仕様書を「渡す」とは、セッションのたびにコンテキストを入れ直す作業だ。セッションが終われば消える。次のセッションではまた同じ説明。チームで使っていれば、人によって渡す内容がバラバラになり、出力の品質もバラつく。

CLAUDE.mdを「育てる」とは、プロジェクトの前提知識をファイルに残していくことだ。一度書けば全セッションで勝手に読み込まれる。gitに入れておけばチーム全員が同じ前提で作業できる。プロジェクトが進むにつれて、CLAUDE.md自体も一緒に育っていく。

要するに、**仕様書は「その場限りの指示書」、CLAUDE.mdは「育つ業務マニュアル」**だ。

実践: 「間違えたら追加」ルール

では、CLAUDE.mdをどうやって「育てる」のか。

Claude Codeの開発に携わるBoris Chernyのチームは、約100行のCLAUDE.mdをgit管理し、「Claudeが間違えたらCLAUDE.mdに追加する」をチームルールにしているらしい。このやり方がシンプルで強い。

私もこのアプローチを採用した。具体的なプロセスはこうなる。

1. Claude Codeに作業を依頼する
2. 出力が期待と異なったら、「何が足りなかったか」を特定する
3. その情報をCLAUDE.mdに追加する
4. 次のセッションから同じ間違いが起きなくなる

例を挙げる。初期のCLAUDE.mdにはディレクトリ構造しか書いていなかった。あるとき、Claude Codeが新しいファイルをcontent/articles/直下に作成した。実際にはcontent/articles/drafts/に置くべきだった。そこで「コンテンツの成長フロー」をCLAUDE.mdに追加した。

## コンテンツの成長フロー

brainstorm → ideas → notes → articles
（ブレスト  → 思いつき → 学習・整理 → 公開記事）

これ以降、Claude Codeはファイルを正しい場所に配置するようになった。

別の例。Claude Codeがレビューで毎回同じ観点を見落としていた。「セキュリティレビューが必要なのはauth関連のファイル変更時」「パフォーマンスレビューが必要なのはDB関連の変更時」。こういう判断基準をルールファイルとして追加した。

このプロセスのポイントは、CLAUDE.mdの完成形を最初に設計しようとしないことだ。実際に間違いが起きてから追加する。必要なものだけが残る。

育てるCLAUDE.mdの3つの原則

使い続ける中で、意識するようになったことが3つある。

原則1: 「コードを読めばわかるか？」で判断する

何を書いて何を書かないか。判断基準はひとつ、「この情報はコードを読めばわかるか？」だ。

• Yes → 書かない: 技術スタック、ライブラリのバージョン、関数の引数仕様。これらはコードから読み取れる
• No → 書く: なぜこの技術を選んだか、どんなワークフローで運用しているか、ファイルの命名規則。これらはコードに表現されていない

例えば「React + Next.jsのプロジェクト」はpackage.jsonを見ればわかる。書く必要はない。一方「週次レビューはNotionからJSON抽出して/weekly-reviewスキルで生成する」はコードのどこにも書かれていない。CLAUDE.mdに書く価値がある。

原則2: 仕様書はチケット単位で渡す

仕様書を全廃する必要はない。「渡し方」を変えればよい。

仕様書をGitHub IssuesやLinearのチケット粒度に分解する。1チケット = 1機能。各チケットには「何を」「なぜ」「受け入れ基準」だけ書く。実装方法は書かない。既存のコードパターンに合わせるかどうかはCLAUDE.mdが教えてくれる。

# チケット: ログイン画面にパスワードリセット機能を追加

## 何を
パスワードリセットのフローを追加する

## なぜ
ユーザーサポートへのパスワードリセット依頼が月50件ある

## 受け入れ基準
- メールアドレス入力 → リセットリンク送信 → 新パスワード設定の3ステップ
- リセットリンクの有効期限は24時間
- 既存の認証フローと同じUIコンポーネントを使用する

「どう実装するか」はClaude Codeがコードベースとルールファイルから判断する。

原則3: 薄く保ち、分離で拡張する

CLAUDE.mdは薄く保つ。100行を超えたら分離を検討する。

Claude Codeは.claude/rules/ディレクトリに置いたMarkdownファイルを自動で読み込む。コーディング原則、レビューポリシー、外部ツール連携の設定。関心事ごとにファイルを分けて、CLAUDE.md自体はプロジェクトの概要とワークフローに絞る。

繰り返し使うワークフローは.claude/skills/としてスキル化もできる。「週次レビューを生成する」「SEO記事を書く」「YouTube台本を作る」。こういったものを個別ファイルに切り出していくと、CLAUDE.mdはスキル一覧表のように簡潔に保てる。

あるプロジェクトでCLAUDE.mdが育った過程

最も手をかけている個人プロジェクトの変遷を例に出す。

初期（20行）: プロジェクト概要とディレクトリ構造だけ。「このプロジェクトは個人のデジタルガーデンです」「content/以下にarticles, notes, ideasがある」程度。

60行: コンテンツの成長フロー（brainstorm → ideas → notes → articles）を追加。情報収集の日次/週次/月次サイクルを定義。ファイル命名規則も追加。きっかけは、Claude Codeがファイル名を統一的に付けてくれなかったこと。

478行に膨張: スキルの定義、レビューポリシー、外部CLI連携の設定を全てCLAUDE.mdに書き込んだ。やりたいことが多く、あれもこれもと詰め込んだ結果こうなった。毎セッションのコンテキストウィンドウを大量に消費していた。

146行に圧縮 + 分離: さすがに限界を感じて整理した。478行を146行に圧縮し、残りを.claude/rules/（12ファイル）と.claude/skills/（31スキル）に分離。CLAUDE.mdはプロジェクト概要・ワークフロー・スキル一覧だけを保持する「目次」になった。

現在: CLAUDE.mdは146行で安定。新しいルールやスキルが必要になれば、CLAUDE.mdではなく専用ファイルに追加する。ルールファイルやスキルファイルは日常的に更新しているが、CLAUDE.md自体はたまにしか触らない。

振り返って思うのは、膨張は通過点だったということ。最初から分離設計する必要はない。まずCLAUDE.mdに全部書いて、大きくなったら分ける。この順番が結局いちばん自然だった。

もうひとつ、行数はそのままメンテナンスコストになる。478行のCLAUDE.mdは、何がどこに書いてあるか把握しきれなかった。146行なら一読で全体像がつかめる。

まとめ: CLAUDE.mdは「完成」しない

CLAUDE.mdは完成しない。プロジェクトが続く限り、育ち続ける。

仕様書を毎回渡すのは、セッションごとにリセットされる繰り返しだ。CLAUDE.mdを育てていけば、プロジェクトの知識がファイルに残り続ける。

やることはシンプルだ。

1. 今日から始める: CLAUDE.mdがなければ、プロジェクト概要を10行書くところから
2. 間違いを燃料にする: Claude Codeが期待と異なる出力をしたら、足りなかった情報をCLAUDE.mdに追加する
3. 膨張したら分離する: 100行を超えたら.claude/rules/への切り出しを検討する
4. チケット単位で渡す: 仕様書を丸ごと渡さず、「何を」「なぜ」「受け入れ基準」に分解する

CLAUDE.mdは「渡すファイル」ではない。プロジェクトと一緒に育てていくものだ。

この記事では、Claude Codeの設定機構を「ハーネスエンジニアリング」として体系化し、各レイヤーの設計方法から、自作のオーケストレーションシステム「ai-orchestra」による統合管理まで、実践的に解説する。

プロンプトから「環境構築」へ──ハーネスエンジニアリングとは

プロンプトエンジニアリングとの違い

プロンプトエンジニアリングは「何を聞くか」の技術である。質問の仕方、few-shotの工夫、Chain-of-Thoughtの誘導——これらはすべて1回のやりとりを最適化するアプローチだ。

ハーネスエンジニアリングは「AIが常に最適な状態で働ける環境を設計する」技術である。ここでいう「ハーネス」とは、Claude Codeを制御する設定群（CLAUDE.md、Hooks、Rules、Settings）の総称だ。テストハーネスがテスト実行環境を整備するように、AIハーネスはAIの実行環境を整備する。

なぜ「ハーネス」が必要か

Claude Codeの使い方を「毎回プロンプトで指示する」段階から脱却すべき3つの理由がある。

1. コンテキストの一貫性

プロジェクトの規約、ディレクトリ構造、命名規則——これらを毎回プロンプトで伝えるのは非効率である。CLAUDE.mdに一度書けば、全セッションで自動的にコンテキストとして読み込まれる。

2. ガードレールの決定性

「テストを必ず書いて」というプロンプトはLLMが無視する可能性がある。一方、PreToolUseフックでテスト未実行の実装を検知してブロックすれば、ルール違反をプログラムで防げる。

3. チームスケール

個人のプロンプト技術はチームに共有しにくい。ハーネス（.claude/配下のファイル群）はgitで管理し、チーム全員に同じ開発体験を提供できる。

CLAUDE.mdの設計──プロジェクトの文脈をAIにインストールする

CLAUDE.mdはClaude Codeがセッション開始時に自動で読み込む設定ファイルである。LLM向けの「意味的な指示」を書く場所であり、ハーネスの土台となるレイヤーだ。

3つの階層

Claude Codeは以下の順でCLAUDE.mdを読み込み、すべてをコンテキストに含める。

~/.claude/CLAUDE.md              ← グローバル（全プロジェクト共通）
.claude/CLAUDE.md                ← プロジェクトルート（チーム共有）
src/backend/.claude/CLAUDE.md    ← サブディレクトリ（領域固有）

グローバルには言語設定やコミュニケーションの好みなど、プロジェクトに依存しない個人設定を書く。

# ~/.claude/CLAUDE.md

## Communication
- 文章は簡潔に。ただし重要な理由や前提は箇条書きで補足してください。
- 不明点が多い場合は、すぐに大きな変更をせず前提の確認から始めてください。

## General coding policy
- 既存の仕様や振る舞いを壊さないことを最優先してください。
- 大きな変更より、小さく安全なステップでの修正を優先してください。

プロジェクトルートにはリポジトリ固有の文脈を書く。ディレクトリ構造、ワークフロー、使用中のスキル一覧など。

# .claude/CLAUDE.md

## プロジェクト概要
このリポジトリは個人のデジタルガーデンです。

## ディレクトリ構造
digital-garden/
├── content/articles/   # ブログ記事（published/ drafts/ archive/）
├── content/notes/      # 学習ノート
└── reviews/            # 振り返り（weekly/ monthly/ yearly/）

## コンテンツの成長フロー
brainstorm → ideas → notes → articles
（ブレスト  → 思いつき → 学習・整理 → 公開記事）

効果的なCLAUDE.mdの書き方

含めるべき情報:

• プロジェクトの概要（1-2文）
• ディレクトリ構造（主要なもののみ）
• 命名規則・コーディング規約
• テスト実行コマンド
• ワークフロー（データの流れ、デプロイ手順）
• 使用中のスキル一覧

含めるべきでない情報:

• 実装の詳細（コードを読めばわかること）
• 一時的な情報（今の作業内容）
• 巨大なリスト（コンテキストウィンドウを圧迫する）

コンテキストウィンドウの消費を意識し、「Claude Codeがこの情報を持っていないと正しい判断ができない」ものだけを書くのが原則である。

Settings階層とRulesシステムによるAIの挙動制御

settings.jsonの3階層

Claude Codeの機能設定はsettings.jsonで管理する。CLAUDE.mdがLLM向けの「意味的な指示」であるのに対し、settings.jsonはプログラムレベルの設定である。

~/.claude/settings.json                ← ユーザー設定（全プロジェクト共通）
.claude/settings.json                  ← プロジェクト設定（git管理、チーム共有）
.claude/settings.local.json            ← ローカル設定（gitignore、個人上書き）

各階層はマージされ、下位の設定が上位を上書きする。

// .claude/settings.json（チーム共有）
{
  "permissions": {
    "allow": ["Bash(npm run test)", "Bash(npm run lint)"],
    "deny": ["Bash(rm -rf)"]
  }
}

// .claude/settings.local.json（個人、gitignore対象）
{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "python3 $AI_ORCHESTRA_DIR/scripts/sync-orchestra.py"
      }
    ]
  }
}

チームで共有すべき権限設定はsettings.jsonに、個人のフック設定や環境依存の設定はsettings.local.jsonに配置する。.local.jsonは.gitignoreに追加する。

.claude/rules/によるルールのモジュール分割

.claude/rules/ディレクトリに.mdファイルを配置すると、Claude Codeが自動で読み込む。CLAUDE.mdに全ルールを書くとファイルが肥大化するため、関心事ごとにファイルを分割するのが有効である。

.claude/rules/
├── coding-principles.md          # コード品質ルール
├── config-loading.md             # 設定ファイルの読み込み手順
├── agent-routing-policy.md       # エージェントルーティングポリシー
├── codex-delegation.md           # Codex CLI委譲ルール
├── gemini-delegation.md          # Gemini CLI委譲ルール
├── skill-review-policy.md        # レビューポリシー
├── task-memory-usage.md          # タスク状態管理ルール
└── context-sharing.md            # コンテキスト共有ルール

各ルールファイルは独立したドキュメントとして完結させる。例えばcoding-principles.mdには以下のような内容を書く。

# Code Quality Policy

## シンプルさ優先
- 読みやすいコードを複雑なコードより選ぶ
- 過度な抽象化を避ける

## Early Return
ネストを浅く保つために Early Return を使う。
ネスト深度は2以下を目標とする。

## 型ヒント必須
すべての関数に型アノテーションを付ける。

ルールにはYAMLフロントマターでpaths:を指定でき、特定のディレクトリでのみ有効にすることも可能だ。

---
paths:
  - "src/backend/**"
---
# Backend Rules
バックエンド固有のルールをここに書く。

CLAUDE.md vs Rules: 使い分け

Hooksシステム──Claude Codeのワークフローを自動化・拡張する

HooksはClaude Codeの最も強力なハーネス機構である。CLAUDE.mdやRulesがLLMへの「お願い」（Soft Rule）であるのに対し、Hooksはプログラムで確実に実行される（Hard Rule）。

Soft Rule vs Hard Rule

Soft Rule（CLAUDE.md / Rules）
  → LLMが解釈して従う。無視される可能性がある。
  → 例: 「テストを必ず書いてください」

Hard Rule（Hooks）
  → プログラムが機械的に実行する。回避不可能。
  → 例: PreToolUse hookでテスト未実行を検知し、exit code 2でブロック

この区別を理解することが、ハーネス設計の核心である。

6種のイベントタイプ

Hookの設定方法

settings.json（またはsettings.local.json）にフック定義を追加する。

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "python3 ./hooks/check-codex-before-write.py",
        "matcher": "Edit|Write"
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "python3 ./hooks/lint-on-save.py",
        "matcher": "Edit"
      }
    ]
  }
}

matcherはツール名の正規表現で、特定のツール使用時のみフックを発火させる。

PreToolUse: exit code 2でツールをブロック

PreToolUseフックがexit code 2を返すと、Claude Codeはそのツール呼び出しをブロックする。これがHard Ruleの正体である。

#!/usr/bin/env python3
"""check-codex-before-write.py
core/ 配下のファイル変更前にCodexへの相談を提案する。
"""
import sys
import json

input_data = json.loads(sys.stdin.read())
tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

file_path = tool_input.get("file_path", "")

# core/ 配下のファイル変更は Codex に相談すべき
if "core/" in file_path:
    print("[Codex Suggestion] core/ の変更を検出しました。")
    print("Codex に設計相談してから編集してください。")
    # exit code 2 = ツール実行をブロック
    sys.exit(2)

UserPromptSubmit: コンテキスト注入とルーティング

UserPromptSubmitフックはプロンプト送信後に発火し、stdoutに出力したテキストがClaude Codeのコンテキストに追加される。エージェントルーティングの提案や、外部CLIへの委譲指示に利用できる。

#!/usr/bin/env python3
"""agent-router.py
ユーザーのプロンプトを分析し、最適なエージェントを提案する。
"""
import sys
import json

input_data = json.loads(sys.stdin.read())
prompt = input_data.get("prompt", "")

# キーワードベースの簡易ルーティング
if any(kw in prompt for kw in ["Python", "FastAPI", "Django"]):
    print("[Agent Routing] 'Python' → `backend-python-dev` (tool: codex):")
    print('Task(subagent_type="backend-python-dev", prompt="...")')

実践的なHook構成例

以下は筆者が実際に使用しているHook構成（一部抜粋）である。

Agent Routing──専門エージェントをタスクに最適配置する

Claude Codeのサブエージェント機能を活用すると、タスクの種類に応じて専門エージェントに作業を委譲できる。ハーネスエンジニアリングでは、この委譲先を設定ファイルで一元管理する。

cli-tools.yamlによるルーティング設計

エージェントの実行ツール（Codex CLI / Gemini CLI / Claude直接処理）を1つのYAMLファイルで管理する。

# .claude/config/agent-routing/cli-tools.yaml

codex:
  enabled: true
  model: gpt-5.3-codex
  sandbox:
    analysis: read-only
    implementation: workspace-write
  flags: --full-auto

gemini:
  enabled: true
  model: gemini-3.1-pro-preview

# エージェントルーティング
agents:
  # レビュー系 → Claude直接処理（コンテキスト内で完結）
  code-reviewer:
    tool: claude-direct
  security-reviewer:
    tool: claude-direct
  architecture-reviewer:
    tool: claude-direct

  # 実装系 → Codex CLI（深い推論 + ファイル操作）
  backend-python-dev:
    tool: codex
    sandbox: workspace-write
  frontend-dev:
    tool: codex
    sandbox: workspace-write

  # リサーチ系 → Gemini CLI（大規模検索 + マルチモーダル）
  researcher:
    tool: gemini

  # 自動選択（タスク内容に応じて切り替え）
  general-purpose:
    tool: auto

4つのルーティングモード

ローカル上書き

プロジェクト固有のモデルや設定は.local.yamlで上書きする。ベースファイルはai-orchestraから自動同期されるため、直接編集しない。

# .claude/config/agent-routing/cli-tools.local.yaml
codex:
  model: gpt-5.4-mini  # このプロジェクトだけ軽量モデルで実行

上書きルール: .local.yamlに定義されたキーだけがベースを上書きし、未定義のキーはベースの値を継承する。

実践例: ai-orchestraによるハーネス統合管理

ここまで個別に紹介してきたCLAUDE.md、Rules、Hooks、Agent Routingは、プロジェクトが大きくなるにつれ管理が煩雑になる。「コード品質ルール」を10プロジェクトで共有したい場合、手動コピーでは破綻する。

この課題を解決するために筆者が構築したのがai-orchestraである。

パッケージシステム

ai-orchestraはハーネスの構成要素をパッケージとして管理する。各パッケージはmanifest.jsonで内容を定義する。

{
  "name": "core",
  "version": "0.4.0",
  "description": "全パッケージ共通の基盤ライブラリ",
  "depends": [],
  "hooks": {
    "SessionStart": ["load-task-state.py"],
    "SessionEnd": ["cleanup-session-context.py"],
    "PreToolUse": [
      { "file": "check-plan-gate.py", "matcher": "Agent|Task" },
      { "file": "inject-shared-context.py", "matcher": "Agent|Task" }
    ],
    "PostToolUse": [
      { "file": "capture-task-result.py", "matcher": "Agent|Task" },
      { "file": "update-working-context.py", "matcher": "Edit" }
    ]
  },
  "skills": ["skills/startproject", "skills/checkpointing", "skills/task-state"],
  "agents": [],
  "rules": ["rules/coding-principles.md", "rules/config-loading.md"],
  "config": ["config/task-memory.yaml"]
}

現在10パッケージを運用している。

自動同期の仕組み

SessionStart Hookでsync-orchestra.pyが起動し、ai-orchestraの最新状態をプロジェクトの.claude/に差分コピーする。

ai-orchestra/packages/ (ソース)
    ↓ SessionStart hook: sync-orchestra.py
.claude/ (プロジェクト)
    ├── agents/     ← 28エージェント定義
    ├── skills/     ← 全スキル
    ├── rules/      ← 全ルール
    └── config/     ← 設定ファイル（.local.yamlは保護）

同期の特徴:

• 差分コピー: mtimeベースで変更されたファイルのみ同期（無変更時は約70ms）
• ローカル保護: *.local.yamlや*.local.jsonは同期の対象外（プロジェクト固有設定を保護）
• Hook直接参照: HookスクリプトはコピーせずAI_ORCHESTRA_DIRからのパス参照（常に最新版が実行される）
• Facetビルド: 同期時にFacetシステムによるSKILL.md / ルールの自動生成も実行

Facetシステム──DRYなスキル・ルール管理

同じルールを複数のスキルに手動コピーすると、1箇所を修正するたびに全ファイルを更新する必要がある。Facetシステムはこの問題を解決する。

この仕組みはnrsさんの記事「Faceted Prompting ── 肥大化したプロンプトを5つの関心で分解する」に着想を得ている。同記事ではモノリシックなプロンプトをPersona・Policy・Instruction・Knowledge・Output Contractの5つの関心に分離するアーキテクチャを提案しており、ai-orchestraではこの考え方をClaude Codeのスキル・ルール管理に応用した。

3種類の部品を組み合わせてスキルやルールを自動生成する仕組みである。

facets/
├── policies/           ← 共有Policy（複数スキル・ルールで再利用）
│   ├── cli-language.md      # 外部CLIとの言語プロトコル
│   ├── code-quality.md      # コード品質の共通ルール
│   ├── dialog-rules.md      # 対話ルール
│   └── factual-writing.md   # 事実に基づいた記述ルール
│
├── output-contracts/   ← 共有Output Contract（出力形式の標準化）
│   ├── tiered-review.md     # Critical/High/Medium/Lowの4段階レビュー形式
│   ├── compare-report.md    # 比較レポート形式
│   └── deep-dive-report.md  # 詳細分析レポート形式
│
├── instructions/       ← スキル・ルール固有のInstruction
│   ├── review.md
│   ├── startproject.md
│   └── ... (25個以上)
│
└── compositions/       ← 組み立て定義YAML
    ├── review.yaml
    └── startproject.yaml

Composition YAMLでどの部品を組み合わせるかを定義する。

# compositions/review.yaml
target: skill
name: review
policies:
  - cli-language
output_contracts:
  - tiered-review
instruction: review

facet buildを実行すると、Policy + Output Contract + Instructionが結合されたSKILL.mdが自動生成される。Policyを1箇所修正すれば、参照する全スキルに反映される。

セットアップ

新しいプロジェクトにai-orchestraを導入するには以下のコマンドを実行する。

# インストール
uv tool install orchex

# プロジェクトへのセットアップ（全パッケージ）
orchex setup all --project /path/to/project

# 最低限のパッケージのみ
orchex setup essential --project /path/to/project

以降はClaude Code起動時にSessionStart Hookが自動同期を行うため、明示的な操作は不要となる。

まとめ──ハーネス設計のステップバイステップ

AIハーネスエンジニアリングは「プロンプトを毎回書く」から「環境を一度設計する」へのパラダイムシフトである。

段階的に導入する場合は、以下の順序を推奨する。

Step 1: CLAUDE.mdを書く

プロジェクト概要、ディレクトリ構造、テストコマンドをCLAUDE.mdに書く。これだけでClaude Codeの出力品質は大幅に向上する。

Step 2: Rulesを分割する

コーディング規約やワークフローのルールを.claude/rules/に分割する。CLAUDE.mdを簡潔に保ちつつ、詳細なルールを独立管理できる。

Step 3: Hooksで自動化する

繰り返し行う確認作業をHooksで自動化する。SessionStartでの環境初期化、PreToolUseでのガードレール、PostToolUseでの自動整形などから始めるとよい。

Step 4: Agent Routingを設計する

サブエージェントとCLIツール（Codex / Gemini）のルーティングを設定ファイルで一元管理する。タスクの種類に応じた最適なツール選択を自動化する。

Step 5: パッケージ化して再利用する

複数プロジェクトで同じハーネスを使う場合は、ai-orchestraのようなオーケストレーションシステムで統合管理する。

ハーネスの設計に正解は1つではない。自身のプロジェクトとワークフローに合わせて、少しずつ育てていくものである。この記事が、Claude Codeの真の能力を引き出すための出発点になれば幸いだ。

関連記事:

• Claude Code開発を支える私のツールチェイン — ターミナルからAIデザインまで

この記事では、私が実際にClaude Code開発で使っているツールチェインを、ターミナル環境からAIデザインツールまで一気通貫で紹介する。

紹介するツール一覧:

• WezTerm（ターミナルエミュレーター）
• Tmux（ターミナルマルチプレクサ）
• GTR（Git Worktree Runner）
• Baton（自作セッション管理TUI）
• fzf + ghq（プロジェクト検索・管理）
• Claude Codeステータスライン / 通知フック
• Context7 / Notion MCP / claude-mem
• Aqua Voice（音声入力）
• Pencil（AIデザインツール）

ターミナル環境：WezTerm + Tmux

なぜWezTermを選んだのか

Claude Code CLIを使うなら、まずターミナルエミュレーターの選定が出発点になる。macOSで選択肢に挙がるのはiTerm2、Ghostty、WezTermあたりだろう。

私がWezTermを選んだ最大の理由はLuaで設定ファイルを記述できる点にある。単なるYAMLやTOMLの静的設定ではなく、プログラミング言語で動的にキーバインド・外観・イベントハンドリングを定義できる。Claude Codeの起動スクリプトをWezTermの設定ファイルに組み込んだり、セッション情報に応じてタブのタイトルを動的に変更したりといった柔軟なカスタマイズが可能である。

Ghosttyも高速なGPUレンダリングで注目されているが、カスタマイズの自由度という点ではWezTermに軍配が上がる。

Tmux導入の経緯

もともとWezTerm単体で開発していた。しかし、Claude Codeを日常的に使う中でTmuxを間に挟む構成に移行した。きっかけの一つは、Claude CodeのAgent Teams機能である。Agent TeamsにはTmuxセッション上でサブエージェントの会話内容をリアルタイム表示するオプションがあり、これを使いたかったことが導入のきっかけになった。

Tmuxは導入難易度が高いと敬遠されがちだが、Claude Code開発においてはその恩恵が非常に大きい。

WezTermとTmuxの役割分担

現在、WezTermとTmuxの責務は明確に分離している。

起動フローは以下の通りである。

1. WezTermを起動
2. WezTermの設定ファイルからTmuxのベースセッションを自動起動
3. プロジェクトごとにTmuxセッションを作成
4. 各セッション内でClaude Code CLIを起動

一つのセッション内に複数のClaude Codeが立ち上がっていることもあれば、Codex CLIやGemini CLIが同居しているケースもある。

並列開発のためのCLIツール群

Claude Codeを並列で稼働させると、複数のAIが同じファイルを編集しようとして競合が発生する。これを解決する手段として、Git Worktreeを採用している。

GTR（Git Worktree Runner）

Gitのworktreeコマンドは冗長で、追加・削除のたびに長いパスを指定する必要がある。この煩雑さを解消するために導入したのが、CodeRabbitが提供する**GTR（Git Worktree Runner）**である。

GTRを使えば、ワークツリーの作成・削除・一覧表示がシンプルなコマンドで完結する。実際の運用フローは以下の通りである。

1. GTRで新しいワークツリーを作成（ブランチ名を指定）
2. そのワークツリーのディレクトリに移動
3. Claude Codeを起動して機能開発を開始

これにより、メインブランチを汚さずに複数の機能を並行して開発できる。

Baton — 自作のClaude Codeセッション管理TUI

Claude Codeを複数並列で動かしていると、「どのセッションが今どういう状態なのか」を把握するのが難しくなる。承認待ちなのか、実行中なのか、待機中なのか——セッションが増えるほど管理しきれなくなる。

この課題を解決するためにいくつかの既存ツールを試した。Claude Squad、Claude Tmux、CC Managerなど、OSSのセッション管理ツールは複数存在する。しかし、自分のワークフローにフィットするものが見つからなかったため、BatonというTUIツールを自作した。

Batonの特徴は以下の通りである。

• Tmux依存: Tmux上のペイン単位でClaude Codeセッションを管理する
• ステータス取得: 各ペイン内のClaude Codeの状態（承認待ち/実行中/待機中）をリアルタイムで取得
• TUI表示: ステータスごとに色分けして一覧表示

Batonの画面から「今このセッションが承認待ちだ」と判断したら、そのセッションに移動して内容を確認し、承認または否認を行う。これにより、並列開発中のClaude Codeを一元管理できるようになった。

batonはGitHubで公開している。

fzf + ghq — プロジェクトの爆速切り替え

プロジェクト間の移動にいちいちcdコマンドやTmuxコマンドを打つのは非効率である。ここで活躍するのがfzf（ファジーファインダー）とghq（リポジトリ管理ツール）の組み合わせである。

ghqは、git cloneしたリポジトリを一元管理するツールである。ghq getでクローンすると、~/ghq/github.com/{user}/{repo}/のような統一的なディレクトリ構造に配置される。全リポジトリが一箇所に集約されるため、検索性が格段に上がる。

fzfは、あいまい検索で候補を絞り込むインタラクティブなフィルタである。単体でも強力だが、ghqと組み合わせることで真価を発揮する。

私はTmuxのキーバインドに以下の2つのショートカットを設定している。

これにより、プロジェクトの新規立ち上げも切り替えもキーバインド一発で完了する。

Claude Codeのカスタマイズ

ステータスライン

Claude Codeの入力欄の下にはステータスラインと呼ばれる領域があり、シェルスクリプトでカスタマイズできる。Claude CodeがJSON形式で情報を返してくるため、その内容をパースして表示する仕組みである。

私が表示している情報は以下の通りである。

特に使用状況の表示は重要である。Claude Codeには5時間制限や週間制限があるため、「あとどれくらい使えるか」を常に把握しておきたい。

この使用状況は、v2.80以前は非公式の内部APIを叩いて取得する必要があった。利用規約への抵触が懸念される方法だったが、v2.80で公式にJSONとして提供されるようになった。現在は堂々と公式の手段でステータスラインに表示できる。

通知フック

Claude Codeが「タスク完了」「承認待ち」「エラー発生」といった状態変化を起こしたとき、OSの通知を飛ばす仕組みをフックで構築している。

ポイントは通知音の分類である。

音を聞くだけでClaude Codeの状態がわかるため、並列で複数のセッションを動かしているときでも、すぐに適切なセッションに反応できる。

MCP・プラグイン

MCPの運用方針：グローバルに設定しない

MCPは便利だが、グローバルに設定すると毎セッションでそのMCPのコンテキストが消費され、コンテキストウィンドウを圧迫する。コンテキストウィンドウはClaude Codeの生命線であるため、何でもかんでもMCPを追加するのではなく、プロジェクトごとに必要なMCPだけを設定する方針で運用している。

Context7 — 最新ドキュメント参照

Context7は、フレームワークやライブラリの最新ドキュメントをClaude Codeに提供するMCPサーバーである。

例えば「Next.jsの最新のApp Routerの書き方で実装して」と指示すると、Context7が最新のドキュメントを参照した上で、トレーニングデータのカットオフに依存しない正確な実装を行ってくれる。フレームワークの更新が速い領域では特に重宝する。

Notion MCP

私はNotionでナレッジやタスクを管理しているため、Notion MCPは頻繁に使う。Claude Codeから直接Notionのページを読み書きできるため、「Notionのタスクボードを更新して」といった指示がシームレスに通る。

claude-mem — セッションを超えた記憶

Claude Codeは基本的に1セッション1記憶である。セッションを閉じれば、それまでのやり取りは失われる。公式のAuto Memory機能で簡単なメモは残せるようになったが、詳細な会話の文脈までは保持されない。

claude-memはこの課題を解決するプラグインである。会話の内容や設計判断をSQLiteに保存し、別のセッションから過去の情報を検索・参照できるようにする。「先週あの機能をどう設計したか」を遡れるのは、継続的な開発において非常に有用である。

音声入力とAIデザイン

Aqua Voice — 音声でClaude Codeと対話する

AIとのやり取りで最もボトルネックになるのは、人間側の入力速度である。この記事の下書きもそうだが、私はClaude Codeへの指示をAqua Voiceで音声入力している。

要件定義、実装方針の説明、ブログの下書き——すべてを声で話し、Claude Codeに処理させる。手で打つよりも圧倒的に速く、思考を途切れさせずにAIに伝達できる。

Pencil — AIと一緒にデザインを作る

非デザイナーにとって、UIデザインは大きなハードルである。Pencilはこの課題に対する現時点での有力な回答の一つである。

Pencilを起動するとMCPサーバーが立ち上がり、Claude Codeと連携できるようになる。Claude Codeに「ログイン画面をデザインして」と指示すると、Pencil上にデザインが自動生成される。さらに、そのデザインをもとにClaude Codeで実際のページを実装させることもできる。

Pencilの強みは以下の3点である。

• MCP連携: Claude Codeから直接デザインを操作できる
• 手動編集: Figmaのように手動で微調整も可能
• Git管理: 生成されるファイルをGitで管理できる

AIに任せきりではなく、気になる箇所は手で直せる。この「AIと人間の協働」の塩梅が丁度良い。

今後注目しているツール：Google Stitch

Googleが提供するAIデザインツールStitchも注目している。調査した限りでは、デザインの精度や表現力はPencilよりStitchの方が優れている印象を受けた。

今後の運用フローとしては、Stitchで大まかなデザインを決め、Pencilに取り込んで微調整するという二段構えのワークフローを試していきたい。

まとめ

私のClaude Code開発環境のツールチェイン全体像を整理する。

[WezTerm] ← GUIレンダリング
    └─ [Tmux] ← セッション管理
         ├─ [Claude Code] ← AI対話
         │    ├─ ステータスライン（使用状況/モデル/PID）
         │    ├─ 通知フック（音で状態判別）
         │    ├─ MCP: Context7 / Notion MCP
         │    └─ プラグイン: claude-mem
         ├─ [Codex CLI / Gemini CLI]
         └─ [Baton] ← セッション一元管理TUI

[GTR] ← Git Worktree管理（並列開発）
[fzf + ghq] ← プロジェクト検索・切り替え
[Aqua Voice] ← 音声入力
[Pencil] ← AIデザイン（MCP連携）

各ツールは単体でも便利だが、組み合わせることで相乗効果が生まれる。WezTerm + Tmuxでセッション基盤を固め、GTR + Batonで並列開発を管理し、fzf + ghqで移動を高速化する。Claude Code側はステータスラインと通知フックで状態を可視化し、MCPとプラグインで能力を拡張する。そして、入力はAqua Voiceで高速化し、デザインはPencilに任せる。

Claude Codeの真価は、こうした周辺ツールとの組み合わせで発揮される。気になるツールがあれば、ぜひ試してみてほしい。

AI エージェントにコードを書かせる場面が増え、コミットの回数も増える一方だ。毎回メッセージを考える手間を、lazygit の Ctrl+G 一発で解消する方法を紹介する。

完成形：コピペですぐ使える設定

結論から。以下を lazygit の config.yml に追加すれば動く。

設定ファイルの場所（OS・環境により異なる）

• macOS（デフォルト）: ~/Library/Application Support/lazygit/config.yml
• macOS（XDG_CONFIG_HOME 設定済み）: ~/.config/lazygit/config.yml
• Linux: ~/.config/lazygit/config.yml

customCommands:
  - key: "<c-g>"
    context: "files"
    description: "Claude で Conventional Commits のメッセージを生成してコミット"
    output: "terminal"
    command: |
      if git diff --cached --quiet; then
        echo "No staged changes to commit."
        exit 1
      fi

      CLAUDE_BIN="${CLAUDE_BIN:-$(command -v claude || true)}"
      if [ -z "$CLAUDE_BIN" ] && [ -x /opt/homebrew/bin/claude ]; then
        CLAUDE_BIN=/opt/homebrew/bin/claude
      fi

      if [ -z "$CLAUDE_BIN" ] || [ ! -x "$CLAUDE_BIN" ]; then
        echo "Claude CLI not found in PATH."
        exit 1
      fi

      PROMPT_CONTENT="$(
        cat <<'EOF'
      以下の staged diff だけを根拠に、Conventional Commits 形式の1行コミットメッセージを日本語で生成してください。
      形式: type(scope): 日本語の要約
      type は feat, fix, docs, style, refactor, test, chore のいずれかを使ってください。
      出力はコミットメッセージ本文のみ。コードフェンスや補足説明は禁止です。

      Staged diff:
      EOF
        git diff --cached
      )"

      MSG="$(CLAUDE_SKIP_NOTIFY_HOOKS=1 "$CLAUDE_BIN" --print --model haiku "$PROMPT_CONTENT")"

      if [ -z "$MSG" ]; then
        echo "Claude did not return a commit message."
        exit 1
      fi

      git commit -e -m "$MSG"

変更をステージングした後、lazygit の Files パネルで Ctrl+G を押す。Claude が diff を読み、Conventional Commits 形式のメッセージを生成し、エディタで確認してからコミットできる。

前提条件

lazygit

brew install lazygit

詳細は lazygit 公式リポジトリ を参照。

Claude Code CLI

npm install -g @anthropic-ai/claude-code
claude  # 初回起動で認証

詳細は Claude Code 公式ドキュメント を参照。

設定の中身を理解する

コピペで動かすだけでも十分だが、カスタマイズしたい場合は各パーツの役割を知っておくと便利だ。

customCommands の基本構造

lazygit の customCommands は、任意のキーバインドにシェルコマンドを割り当てる機能だ。

staged diff の取得とバリデーション

コマンド冒頭で、ステージングされた変更の有無をチェックしている。

if git diff --cached --quiet; then
  echo "No staged changes to commit."
  exit 1
fi

git diff --cached --quiet は staged diff が空のとき exit code 0 を返す。何もステージングしていない状態での誤実行を防ぐガードだ。

続いて Claude CLI のパスを解決する。command -v claude で PATH を検索し、見つからなければ Homebrew のデフォルトパス /opt/homebrew/bin/claude をフォールバックとして試す。

プロンプト設計

Claude に渡すプロンプトは、ヒアドキュメントで staged diff と結合している。

PROMPT_CONTENT="$(
  cat <<'EOF'
以下の staged diff だけを根拠に、Conventional Commits 形式の1行コミットメッセージを日本語で生成してください。
形式: type(scope): 日本語の要約
type は feat, fix, docs, style, refactor, test, chore のいずれかを使ってください。
出力はコミットメッセージ本文のみ。コードフェンスや補足説明は禁止です。

Staged diff:
EOF
  git diff --cached
)"

設計上のポイントは3つ。

1. フォーマットを明示: type(scope): 要約 という Conventional Commits の形式を指定
2. 出力制約: コードフェンスや補足説明を禁止し、コミットメッセージ本文だけを出力させる
3. staged diff のみ: git diff --cached で staged された変更だけを渡し、作業中の変更が混入しない

Claude Code の呼び出しと git commit

MSG="$(CLAUDE_SKIP_NOTIFY_HOOKS=1 "$CLAUDE_BIN" --print --model haiku "$PROMPT_CONTENT")"

この1行に3つのフラグと1つの環境変数が詰まっている（詳細は後述の「フラグ・環境変数リファレンス」を参照）。

生成されたメッセージは git commit -e -m に渡す。-e フラグにより、メッセージがエディタで開かれる。確認・修正してから保存すればコミット完了だ。

ここに至るまでの試行錯誤

完成形に至るまでに4段階の改善を経た。同じ構成を組む人が同じ罠にハマらないよう、各ステップの問題と解決策を共有する。

Step 1: 外部スクリプト方式（初期版）

最初は lazygit-claude-commit.sh という別スクリプトを用意し、lazygit から呼び出していた。

command: |
  DOTFILES_DIR="${DOTFILES_DIR:-$HOME/ghq/github.com/yoshihiko555/dotfiles}"
  "$DOTFILES_DIR/scripts/lazygit-claude-commit.sh"

問題: dotfiles のディレクトリパスに依存し、環境が変わると動かない。

解決: スクリプトの内容を config.yml にインライン化した。設定ファイル1つで完結するため、dotfiles ごと持ち運べばどの環境でも動く。

Step 2: インライン化 + 英語プロンプト

外部スクリプトを廃止し、コマンドを config.yml に直接記述した。ただし最初のプロンプトは英語だった。

問題: プロジェクトのコミット履歴を日本語で統一していたため、英語メッセージが混在して git log の一貫性が崩れた。

解決: プロンプトを日本語に変更し、「日本語で生成してください」と明示した。

Step 3: 日本語化 + 周辺課題の解決

プロンプトを日本語に書き換えると同時に、運用で見つかった周辺課題も解決した。

通知フックの抑制: Claude Code は完了時にフックを実行する仕組みを持つ。--print モードでも毎回通知が飛んでしまい煩わしかった。CLAUDE_SKIP_NOTIFY_HOOKS=1 環境変数で抑制できる。

lazygit の設定ディレクトリ問題: GNU Stow で dotfiles を管理している環境では、~/.config/lazygit/ が正しく認識されないことがあった。.zshrc にラッパー関数を追加して解決した。

lazygit() {
  XDG_CONFIG_HOME="$HOME/.config" command lazygit "$@"
}

エディタ確認の追加: 当初は git commit -m "$MSG" で直接コミットしていたが、AI の生成結果を無条件に受け入れるのはリスクがある。-e フラグを追加し、コミット前に必ずエディタで確認するフローに変更した。

フラグ・環境変数リファレンス

Claude Code CLI フラグ

環境変数

運用してみてのポイント

エディタ確認は外さない

AI が生成したメッセージは8割方そのまま使えるが、スコープ名の選択や要約の粒度が微妙なケースもある。git commit -e によるエディタ確認は外さないほうがいい。確認に要する時間は数秒で、ゼロからメッセージを考えるよりはるかに速い。

Haiku モデルで十分

コミットメッセージ生成は「diff を読んで1行にまとめる」タスクだ。Sonnet や Opus のような大型モデルは不要で、Haiku の速度とコストが最適なバランスになる。レスポンスは体感1〜2秒で返ってくる。

staged diff だけを渡す理由

git diff --cached（staged のみ）を使い、git diff（unstaged 含む）は使わない。理由は明確だ。

• コミット対象の変更だけをメッセージに反映させたい
• 作業中の未ステージング変更が含まれると、メッセージの焦点がブレる
• lazygit でファイル単位にステージングを調整した後に Ctrl+G を押すワークフローと整合する

まとめ

lazygit の customCommands と Claude Code の --print モードを組み合わせれば、Ctrl+G 一発で Conventional Commits 形式のコミットメッセージを自動生成できる。設定は config.yml に約30行で完結し、導入コストは低い。

AI にコードを書かせる機会が増えるほど、コミット回数も増える。メッセージを毎回手で考える時間を、この仕組みで取り戻してほしい。

git worktree は強力な機能だが、実際の運用ではセットアップの手間がボトルネックになりがちだ。 git-worktree-runner（GTR）を使えば、その面倒を 1 コマンドに集約できる。

git worktree の基本（30秒でおさらい）

git worktree は Git 2.5 で追加された機能で、1 つのリポジトリから複数のブランチを同時にチェックアウトできる。git stash やブランチ切り替えなしに、別ディレクトリで別ブランチの作業が可能になる。

# 素の git worktree コマンド
git worktree add ../my-feature feature-branch
git worktree list
git worktree remove ../my-feature

素のコマンドで困ること

git worktree 自体はシンプルだが、実務で使うと以下の課題にぶつかる。

1. コマンドが長い: パス指定やブランチ名の指定が毎回必要
2. 環境ファイルのコピーが手動: .env や .env.local を新しい worktree にコピーし忘れて動かない
3. 依存パッケージのインストールが手動: npm install や pnpm install を忘れてエラー
4. クリーンアップが面倒: worktree 削除時に Docker コンテナの停止、ブランチ削除、git worktree prune を個別に実行

筆者もこれらの課題に対処するため、Taskfile.yaml（Go 製タスクランナー）で worktree 操作を定義して運用していた。しかし、プロジェクトごとに Taskfile を用意する必要があり、それ自体が負担になっていた。

git-worktree-runner（GTR）とは

GTR は CodeRabbit が開発した git worktree の CLI ラッパーだ。 worktree の作成・削除・環境セットアップを 1 コマンドに集約し、AI ツールとの連携もビルトインで提供する。

CodeRabbit が作った worktree CLI ラッパー

• リポジトリ: coderabbitai/git-worktree-runner
• 言語: Bash（3.2+ 対応、macOS / Linux / Git Bash）
• ライセンス: Apache 2.0

CodeRabbit は AI によるプルリクエストレビューサービスで知られる企業だ。GTR は同社が AI 開発ワークフローの一環としてオープンソースで公開したツールになる。

GTR でできること一覧

インストールと初期設定

Homebrew でインストール

macOS / Linux（Linuxbrew）の場合、2 コマンドで完了する。

brew tap coderabbitai/tap
brew install git-gtr

スクリプトでインストールする場合:

git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner && ./install.sh

インストール後、バージョンを確認する。

git gtr --version
# git-gtr version 2.4.0

.gtrconfig を書く

リポジトリルートに .gtrconfig を配置すると、worktree 作成時の自動処理を定義できる。

[copy]
# worktree 作成時に自動コピーするファイル（glob パターン）
include = **/.env.example

[hooks]
# worktree 作成後に自動実行するコマンド
postCreate = pnpm install

[defaults]
# デフォルトのエディタと AI ツール
editor = cursor
ai = claude

この設定ファイルをリポジトリにコミットすれば、チームメンバー全員が同じ worktree 設定を共有できる。

基本的な使い方

worktree を作る（git gtr new）

# ブランチ名を指定して worktree 作成
git gtr new my-feature

# ベースブランチを指定
git gtr new my-feature --base develop

# 作成と同時にエディタを開く
git gtr new my-feature --editor

# 作成と同時に AI ツールを起動
git gtr new my-feature --ai

git gtr new を実行すると、以下が自動で行われる:

1. git worktree add でブランチと作業ディレクトリを作成
2. .gtrconfig の [copy] に基づきファイルをコピー
3. [hooks] postCreate を実行（例: pnpm install）
4. --editor 指定時はエディタを起動
5. --ai 指定時は AI ツールを起動

一覧と切り替え（git gtr list / cd）

# worktree 一覧
git gtr list

# fzf でインタラクティブに選択して移動
git gtr cd

worktree を消す（git gtr rm / clean）

# 指定した worktree を削除
git gtr rm my-feature

# マージ済み worktree を一括削除
git gtr clean --merged

git gtr rm は [hooks] preRemove → worktree 削除 → ブランチ削除 → git worktree prune → [hooks] postRemove を一括で処理する。

【体験談】Taskfile.yaml から GTR に移行してみた

Before — Taskfile.worktree.yml での運用

以前は Go 製タスクランナーの Task を使い、プロジェクトごとに Taskfile.worktree.yml を書いて worktree を管理していた。

# Taskfile.worktree.yml（実際に使っていた定義）
version: "3"

vars:
  MAIN_DIR: "{{.TASKFILE_DIR}}/.."
  WK_DIR: "{{.MAIN_DIR}}/../wk"
  SHARED_ENV: "{{.MAIN_DIR}}/../.env.shared"

tasks:
  add:
    desc: 新しいworktreeを作成（NAME=auth BASE=develop）
    dir: "{{.MAIN_DIR}}"
    requires:
      vars: [NAME]
    vars:
      BASE: '{{.BASE | default "develop"}}'
    cmds:
      - git fetch origin
      - git worktree add -b "{{.NAME}}" "{{.WK_DIR}}/{{.NAME}}" "{{.BASE}}"
      - ./scripts/worktree-env.sh "{{.WK_DIR}}/{{.NAME}}" "{{.SHARED_ENV}}"
      - task: wk:install-wk
        vars:
          NAME: "{{.NAME}}"
      - cmd: mise trust "{{.WK_PATH}}/mise.toml"

  remove:
    desc: worktreeを削除（NAME=auth）
    dir: "{{.MAIN_DIR}}"
    requires:
      vars: [NAME]
    cmds:
      - |
        if [ -d "{{.WK_DIR}}/{{.NAME}}" ]; then
          (cd "{{.WK_DIR}}/{{.NAME}}" && docker compose down --volumes --remove-orphans)
        fi
      - git worktree remove "{{.WK_DIR}}/{{.NAME}}"
      - git worktree prune
      - git branch -D "{{.NAME}}"

この運用で困っていたこと:

• プロジェクトごとに Taskfile を書く必要がある: 新しいリポジトリを始めるたびに、パス構成や依存インストール方法に合わせた定義が必要
• env コピーのスクリプトも別途管理: worktree-env.sh を各プロジェクトに配置
• 動作確認のコスト: Taskfile を書いた後、実際に worktree を作って正しく動くか毎回テスト
• チーム共有が難しい: Taskfile のテンプレート構文に慣れていないメンバーへの説明コスト

After — GTR での運用

GTR に移行後は .gtrconfig を 1 ファイル書くだけで完了する。

# .gtrconfig
[copy]
include = **/.env.example
include = **/.env.shared

[hooks]
postCreate = pnpm install && mise trust mise.toml
preRemove = docker compose down --volumes --remove-orphans

[defaults]
ai = claude

実行コマンド:

# Before（Taskfile）
task wk:add NAME=my-feature BASE=develop

# After（GTR）
git gtr new my-feature --base develop

比較まとめ

結論として、GTR に移行したことで「プロジェクトごとに定義ファイルを書く」という作業自体がなくなった。新しいリポジトリでも .gtrconfig を数行書けば、すぐに worktree 運用を開始できる。

AI 並列開発への活用

Claude Code × GTR で並列セッション

GTR の最大の特徴の一つが、AI ツールとのビルトイン連携だ。.gtrconfig で ai = claude を設定すれば、worktree 作成時に Claude Code セッションを同時起動できる。

# worktree を作ると同時に Claude Code を起動
git gtr new auth-feature --ai

# 既存の worktree で Claude Code を起動
git gtr ai auth-feature

これにより、以下のような並列開発ワークフローが実現する:

1. git gtr new auth --ai → 認証機能を Claude Code に任せる
2. git gtr new ui-fix --ai → UI 修正を別の Claude Code セッションに任せる
3. メインの worktree では自分がコアロジックを実装
4. 各セッションが完了したら PR を作成してマージ

ワークフロー例

# 1. 3 つの worktree を作成し、それぞれ AI セッションを起動
git gtr new feature-auth --ai
git gtr new fix-pagination --ai
git gtr new refactor-api --ai

# 2. 一覧で状況確認
git gtr list

# 3. 作業完了後、マージ済み worktree を一括クリーンアップ
git gtr clean --merged

Claude Code の worktree 対応（--worktree フラグや Agent ツールの isolation: "worktree" オプション）と組み合わせることで、AI エージェントが安全に隔離された環境で作業できる。GTR はその「環境を用意する」部分の手間を省いてくれるツールだ。

まとめ — worktree 運用の「面倒」を消す

git-worktree-runner（GTR）は、git worktree の「便利だけど面倒」を解消するツールだ。

• 1 コマンドで完結: git gtr new だけで worktree 作成 + env コピー + 依存インストール
• 設定は .gtrconfig に集約: プロジェクトごとのスクリプト管理が不要に
• AI 連携がビルトイン: --ai フラグで Claude Code 等を即起動

以前は Taskfile.yaml でプロジェクトごとに定義を書いていたが、GTR への移行で worktree 運用のハードルが大幅に下がった。AI による並列開発がますます一般的になる中、worktree をストレスなく使えるようにしておくことは、開発効率に直結する。

GTR 導入チェックリスト

• [ ] brew tap coderabbitai/tap && brew install git-gtr でインストール
• [ ] git gtr --version でバージョン確認
• [ ] リポジトリに .gtrconfig を作成（copy / hooks / defaults）
• [ ] git gtr new test-branch で動作確認
• [ ] git gtr rm test-branch で削除確認
• [ ] （任意）git gtr config set gtr.ai.default claude で AI ツール設定

FAQ

Q: git-worktree-runner は git worktree の代替ですか？
A: 代替ではなく、git worktree コマンドのラッパーです。内部で git worktree add / git worktree remove を呼んでおり、追加の環境設定やフック実行を自動化します。

Q: Windows でも使えますか？
A: Git Bash または WSL 環境で動作します。Bash 3.2 以上が必要なため、PowerShell ネイティブでは使用できません。WSL での利用を推奨します。

Q: .gtrconfig はリポジトリにコミットすべきですか？
A: チーム開発であればコミット推奨です。メンバー全員が同じ worktree 設定（env コピー、フック）を共有できます。個人設定は git config --local で上書き可能です。

Q: 既存の worktree がある状態で GTR を導入できますか？
A: はい。GTR は git worktree list の出力をベースにしているため、既存の worktree もそのまま管理対象になります。.gtrconfig を追加するだけで運用を開始できます。

Q: Claude Code 以外の AI ツールにも対応していますか？
A: Cursor, VS Code, Aider, Codex, Gemini, Copilot 等のアダプターがビルトインで用意されています。git gtr config set gtr.ai.default <ツール名> で切り替え可能です。

RAG（Retrieval-Augmented Generation: 検索拡張生成）は、外部データを検索してLLMに渡すことで回答の正確性を高めるアーキテクチャである。2020年にMeta AIのLewisらが提唱した(要出典: Lewis et al., 2020)。

LLM単体には以下の課題がある。

• ハルシネーション: 学習データにない情報を「もっともらしく」生成してしまう
• 知識のカットオフ: 学習時点以降の情報を持たない
• ドメイン知識の欠如: 社内規定や自社製品情報など、非公開データに対応できない

RAGはLLMモデル自体を再学習させるのではなく、回答生成の直前に関連情報を検索して渡すというアプローチでこれらを解決する。社内ドキュメント検索、FAQ自動応答、カスタマーサポートなど「特定のデータから正確な情報を引き出したい」場面で採用されている。

RAGの仕組み — 格納フェーズと検索フェーズ

RAGの処理は「格納フェーズ」と「検索・回答フェーズ」の2つに分かれる。

格納フェーズ（データの準備）

テキストデータをVectorDBに格納するまでの流れは以下の通り。

テキストファイル（社内規定、製品マニュアル等）
    ↓ ① チャンク分割（適切な単位に分割）
チャンクのリスト
    ↓ ② Embeddingモデルでベクトル化（数値の配列に変換）
ベクトルのリスト
    ↓ ③ VectorDBに格納（ベクトル + 元テキスト + メタ情報）
VectorDB

テキストをそのまま格納するのではなく、チャンク分割 → ベクトル化という前処理を経る。この前処理の質が、検索精度を左右する。

検索・回答フェーズ（質問への応答）

ユーザーが質問を投げてから回答が返るまでの流れは以下の通り。

ユーザーの質問
    ↓ ① 同じEmbeddingモデルでベクトル化
質問ベクトル
    ↓ ② VectorDBで類似検索（質問に近いチャンクをk件取得）
関連チャンク（上位k件）
    ↓ ③ LLMに「質問 + 関連チャンク」を渡す
回答を生成 → ユーザーに返却

格納時と検索時で同じEmbeddingモデルを使う必要がある。同じモデルで変換するからこそ同じ「意味の空間」に配置され、ベクトル間の距離比較が成り立つ。

RAGの3つのコンポーネント

RAGの検索精度を決めるのは、VectorDB・Embedding・チャンク分割の3つである。

VectorDB — 意味で検索するデータベース

VectorDB（ベクトルデータベース）は、ベクトルを大量に保存し、「このベクトルに近いものをk件返す」という類似度検索を高速に行うデータベースである。

RDB（PostgreSQL等）との違いは以下の通り。

VectorDBに格納されるデータは、検索用ベクトル・LLMに渡す元テキスト・出典表示用のメタ情報で構成される。

{
  "vector": [0.12, -0.45, 0.78, ...],
  "payload": {
    "page_content": "【経費精算】書籍購入は年間30,000円まで...",
    "metadata": { "source": "company-policy.txt" }
  }
}

検索時は質問ベクトルと全ベクトルの距離を計算し、近い順に返す。全件計算は遅いため、HNSW（Hierarchical Navigable Small World）というインデックスで効率的に絞り込む。RDBにおけるB-Treeインデックスに相当する仕組みである。

代表的なVectorDBにはQdrant、Pinecone、Chroma、pgvector（PostgreSQL拡張）がある。検証・学習目的ならローカル実行可能なQdrantやChroma、本番運用ならPineconeやWeaviateが選択肢に入る。

Embedding — テキストを数値に変換する

Embedding（埋め込み）は、テキストを数値の配列（ベクトル）に変換する処理である。Embeddingモデルが大量のテキストデータから学習した「意味の法則」に基づき、意味が近い文は近いベクトルに変換される。

「経費精算」   → [0.12, -0.45, 0.78, ..., 0.33]  (2560次元)
「書籍購入費」 → [0.11, -0.42, 0.81, ..., 0.35]  (2560次元) ← 近い
「今日の天気」 → [-0.55, 0.22, 0.01, ..., -0.18] (2560次元) ← 遠い

人間がルールを定義したのではなく、モデルが大量のテキストから統計的に「意味の近さ」を学んだ結果である。そのためモデルによって精度が異なり、日本語データで多く学習したモデルの方が日本語の意味を正確に捉えられる。

Embeddingモデル選定で考慮すべき3つの観点を以下に示す。

実験で確認: Embeddingモデル変更の効果

筆者のRAG検証環境（14ファイル・539行の社内ドキュメント、検索パラメータk=3）で、Embeddingモデルの変更が検索精度にどう影響するかを検証した。

nomic-embed-text（英語中心）からqwen3-embedding:4b（多言語対応、2560次元）への変更で正答率が劇的に改善した。日本語データを扱う場合、多言語対応のEmbeddingモデルの選定がRAG精度に直結する。

チャンク分割 — 検索精度を左右するデータの切り方

チャンク分割は、テキストデータを検索に適した単位に分割する処理である。以下の3つの理由で必要になる。

1. LLMに渡せるコンテキストには長さの制限がある
2. ドキュメント全体をベクトル化すると意味が希釈される
3. 関連する部分だけを取得してLLMに渡す必要がある

分割戦略はデータの性質ごとに設計が必要である。万能な分割戦略はない。

1チャンクに複数トピックが混在するとベクトルの意味が曖昧になり、検索精度が下がる。

悪い例: 【勤務時間】+【有給休暇】+【経費精算】→ 1チャンク
→ ベクトルが「勤務」「休暇」「経費」の中間的な意味になり、
  どの質問にも中途半端にしかマッチしない

良い例: 【経費精算】→ 1チャンク
→ ベクトルが「経費」に集中し、経費関連の質問に的確にマッチする

1チャンク=1トピックを意識した分割が、検索精度改善の基本である。

検索精度に影響する要因 — 実験で確認したこと

筆者のRAG検証では、Embeddingモデル・チャンク分割戦略・検索パラメータkの3つが検索精度に影響することを確認した。

Embeddingモデルの選定が最もインパクトが大きい

3構成のクエリ別結果を以下に示す。順位の数値はVectorDB内での検索ランクである。

Embeddingモデルの変更はチャンク分割の改善よりインパクトが大きい。日本語データを扱うRAGでは、多言語対応Embeddingモデルの選定を最優先にすべきである。

チャンク戦略4種の比較

別の検証で、4種類のチャンク分割戦略を同一条件で比較した。

各指標の意味は以下の通り。

• Hit Rate: 正解チャンクが上位k件に含まれた質問の割合。取りこぼしの少なさを示す
• MRR（Mean Reciprocal Rank）: 正解チャンクの順位の逆数の平均（1位=1.0、2位=0.5、3位=0.333、圏外=0）。1位ヒット率を示す
• Source Hit Rate: 期待するソースファイルが上位k件に含まれた割合

1位精度重視ならstandard_1000（MRR 0.850）、取りこぼし最小化ならhypothetical_questions（Hit Rate 100%）が有効という結果が得られた。

kを増やしても根本解決にならない

VectorDB検索のパラメータk（取得件数）を増やせば取りこぼしは減るが、ランキング自体は変わらない。

• kが小さい → 関連チャンクを取りこぼすリスク
• kが大きい → ノイズが増え、LLMのコンテキストが長くなり処理が遅くなる

正解チャンクのスコアが低い場合、k=3をk=8に増やしても正解は上位に来ない。根本的な改善にはEmbeddingモデルの変更やチャンク分割の見直しが必要であり、kの調整は補助的な手段である。

RAGの精度をさらに上げる手法

基本的なRAGの精度が確保できたら、以下の手法で改善を重ねられる。

Hybrid Search（ベクトル検索 + キーワード検索）

ベクトル検索は意味的な類似度に強いが、金額・日付・固有名詞などの具体的な値の検索には弱い。BM25などのキーワード検索と組み合わせるHybrid Searchで、意味検索とキーワードマッチの両方をカバーできる。

Re-ranking（検索結果の再評価）

ベクトル検索で広めに取得（k=20程度）した後、クロスエンコーダモデルで再スコアリングして上位N件に絞り込む手法。ベクトル検索の取りこぼしをカバーし、精度の高い結果をLLMに渡せる。

History-Aware Retriever（会話文脈の活用）

マルチターンの会話で代名詞を含む質問が来た場合、会話履歴を踏まえてクエリを書き換えてから検索する手法。

筆者の検証結果を以下に示す。

2ターン目で「それ」が「リモートワーク制度」として正しく解決され、変更情報を含むチャンクが検索された。履歴なしで同じ質問を送ると無関係なチャンクが返るため、クエリ書き換えが機能していることを確認できた。

まとめ — RAGは「検索の質」が全てを決める

RAGは「検索で関連情報を取得し、LLMに渡して回答を生成する」アーキテクチャである。回答生成モデルがいくら優秀でも、検索で正解チャンクが取れなければ正しい回答は生成できない。

筆者の検証で得られた知見は以下の3点に集約される。

1. Embeddingモデルの選定が最もインパクトが大きい — モデル変更だけで正答率0/5→4/5
2. チャンク分割は「1チャンク=1トピック」を意識する — データの性質に応じた分割戦略が必要
3. kを増やすだけでは根本解決にならない — ランキング自体の改善が必要

RAG構築時に確認すべき3つのポイント

1. [ ] 対象データの言語に適したEmbeddingモデルを選定したか？
2. [ ] チャンク分割は「1チャンク=1トピック」になっているか？
3. [ ] Hit RateやMRRなどの定量指標で検索精度を計測しているか？

RAGの精度改善は「検索の質を上げる」ことに尽きる。まずは手元のデータで小規模な検証を始め、Embeddingモデルとチャンク分割を調整しながら精度を計測・改善していくのが実践的なアプローチである。

契約しているAIサービス一覧

まず前提として、筆者が現在契約しているAIサービスを紹介する。

※ 料金は2026年2月時点の情報。

合計すると月額2万円強になる。決して安くはないが、開発効率の向上と情報収集にかかる時間の短縮を考えると、十分なリターンがあると感じている。

Claude Code — Max Plan（$100/月）

筆者のメインツール。開発におけるコードレビュー、設計の壁打ち、そして後述するAI Orchestraのオーケストレーターとして稼働している。モデルはOpus 4.6を中心に使用。つい先日Sonnet 4.6がリリースされたので、比較的シンプルなタスクにはこちらを取り入れることも検討中だ。

ChatGPT — Plus Plan（$20/月）

主にCodex（コード生成・実装タスク）とDeep Researchで使用。開発では実装部分をCodexに任せるケースが多い。

Gemini（¥2,900/月）

リサーチ用途がメイン。Deep Researchの選択肢の1つとして使うほか、NotebookLMとの連携で学習コンテンツの生成にも活用している。

Aqua Voice — AI音声入力（$10/月）

音声入力に特化したAIサービス。まさにこの記事もAqua Voiceで音声入力しながら書いている。技術用語の認識精度が高く、「Claude Code」「NotebookLM」「エージェンティックコーディング」といった単語もほぼ正確に拾ってくれる。

Adobe Creative Cloud — Firefly付き（約¥5,000/月）

Creative Cloudを契約するとAdobe Fireflyが付属する。画像生成や動画生成などのクリエイティブ系AI機能が使えるため、ブログのアイキャッチ画像やちょっとした素材の生成に活用している。

過去に使っていたサービス

以前はNotion AIやGitHub Copilotも契約していた。ただ、Claude Codeのエージェンティックコーディングの方が自分の開発スタイルに合っていたのでCopilotは解約。Notion AIも現在のワークフローでは出番が減ったため一旦やめている。いろいろ触ってきた上で、今の5サービスに落ち着いた。

開発 — AI Orchestraによるエージェンティックコーディング

AI活用のメインは開発だ。個人でプロダクトの開発を進めており、そこにAIを全面的に組み込んでいる。

自作のAI Orchestraシステム

以前ブログ記事でも紹介したが、「AI Orchestra」というシステムを自作している。複数のAIモデルに役割を分担させて開発を進める仕組みで、いわゆるエージェンティックコーディングを実現するものだ。

単にAIにコードを書かせるだけではなく、設計・実装・レビューという開発プロセス全体をAIに担わせる。人間（自分）はオーケストレーターとして方向性を示し、AIがそれを具体化する——という協働スタイルで開発している。

Codexで実装、Claude Code Opus 4.6でレビュー・設計壁打ち

現在の役割分担は以下の通りだ。

実装をCodexに任せ、その成果物をClaude Codeでレビューする。設計で迷ったときもClaude Codeに壁打ちする。1人開発でもレビュアーと設計相談相手がいる感覚で進められるのが大きなメリットだ。

Sonnet 4.6の登場と今後のフローへの取り込み

つい先日、Claude Sonnet 4.6がリリースされた。ベンチマークを見る限り性能がかなり向上しているようで、AI Orchestraのフローに組み込むことを検討中だ。深い推論が必要な場面はOpus 4.6、比較的シンプルなタスクはSonnet 4.6——という使い分けができれば、コスト効率と速度の両方が改善できそうだ。

情報収集 — AIで日次キャッチアップを自動化

開発と並ぶ大きな活用領域が情報収集だ。日々のキャッチアップはほぼAIに任せている。

スキルを使った日次クローリング

自分が気になっている技術や、定期的にチェックしたい企業のテックブログなどを、Claude Codeの「スキル」として事前に登録している。スキルを実行すると、設定済みのソースを元にAIがクローリングし、記事を引っ張ってきてくれる。

取得した記事はMarkdown形式で一覧出力される。毎日業務の終わりにこの一覧を眺めるのが日課になっている。

URL Digestスキルで記事を一括要約

クローリングした一覧の中から気になる記事をピックアップする。とはいえ、10記事すべてを1つ1つ読み込むのは時間がかかる。

そこで「URL Digest」というスキルを使う。気になる記事のURLをまとめてコピーし、スキルに貼り付けて実行するだけ。各記事の内容が5行程度に要約されて返ってくる。

その要約を読んで、さらに気になるものだけ実際の本文を読みに行く。このフローのおかげで、情報収集にかける時間が大幅に短縮された。

日次の情報収集フロー:

日次クローリング（スキル実行）
  ↓ Markdown一覧を出力
気になる記事をピックアップ
  ↓ URLをまとめてコピー
URL Digest（スキル実行）
  ↓ 各記事を5行に要約
さらに気になる記事だけ本文を読む

Deep Researchで技術を深掘り → NotebookLMでインプット

特定の技術をさらに深く知りたいときはDeep Researchを使う。Gemini、Claude、ChatGPTのいずれにもDeep Research機能があり、テーマを投げるとWeb上の情報を幅広く調査してレポートにまとめてくれる。

最近だと、tmux（ターミナルのセッション管理ツール）について深掘りした。CLIでの開発環境を改善するため、tmuxの詳細な使い方や設定方法を調査させた。

Deep Researchの調査結果は、GoogleのNotebookLMに投入する。NotebookLMは投入した内容をもとにポッドキャスト形式の音声コンテンツを生成したり、クイズ形式の問題集を作ったりできる。調査内容を耳からも定着させられるので、インプットの効率が上がる。

エージェントチームで多角的な比較・討論

Claude Codeの「エージェントチーム」機能も活用している。複数のサブエージェントをチームとして生成し、それぞれに異なる役割を与えて並列で動かす——いわばマルチエージェントシステムだ。

例えば「GeminiとChatGPTとClaude Codeを比較したい」とき。それぞれのサービスの立場に立つエージェントを3つ用意し、ファシリテーター役を1つ加えて、合計4エージェントで討論させる。

Claude Code視点のエージェントが強みを主張すると、ChatGPT視点のエージェントが反論する。ファシリテーターがそれを整理し、各サービスのメリット・デメリットをまとめてくれる。

この「AIに議論させる」アプローチはかなり面白い。自分1人で比較表を作るよりも多角的な視点が得られる。技術選定に限らず、さまざまな場面で応用できる手法だと感じている。

ブレスト・思考整理 — AIとの対話でアイデアを広げる

開発や情報収集に加えて、ブレストや思考整理にもAIを活用している。

Notionに書き殴っていた思考をAIで構造化

以前はNotionに自分の思考や考えをバーッと書き殴って、そのまま残すだけだった。記録にはなるが、後から見返しても整理されておらず活用しづらい。

現在はAIと対話しながらブレストを進めている。自分の考えをざっくり伝えると、AIが構造化してまとめてくれたり、別の切り口を提案してくれたりする。

自分では出てこない視点が得られる

ブレストでAIを使う最大のメリットは、自分だけでは出てこない視点が得られることだ。思考が煮詰まっているときに「こういう観点はどうか」と投げかけてもらえるだけで、思考が動き出すことがある。

AIは「答えをくれる存在」というより「壁打ち相手」に近い。

設計・要件定義 — 業務でのAI活用

コードを書く以外にも、設計フェーズでAIをがっつり使っている。

要件定義・詳細設計・技術調査にAIを投入

要件定義、詳細設計、技術調査——こうした「考える系」の作業にAIを投入している。

• 要件定義: 要件の洗い出しや抜け漏れチェックをAIに依頼
• 詳細設計: 設計案を壁打ちし、トレードオフの整理や代替案の提示を受ける
• 技術調査: 採用候補のライブラリやアーキテクチャパターンの比較を調べさせる

この辺りは多くのエンジニアにとってもイメージしやすい活用法だろう。「AIに聞いて課題を整理する」という使い方は、手軽かつ効果が高い。

音声入力 — Aqua Voiceでキーボードいらずの開発

AI活用の中で、地味だが日常を大きく変えたのが音声入力だ。

LLMとの会話はほぼ音声入力

LLMとのやりとりはほぼすべてAqua Voiceの音声入力で行っている。最近はキーボードに触れる時間がかなり減った。

AI音声入力サービスはいくつかあるが、自分が試した中ではAqua Voiceが最も使いやすい。技術用語の認識精度の高さが決め手だ。

「喋りながら開発する」スタイル

音声でAIと対話しながら、「ああでもない、こうでもない」と喋って開発を進めるスタイルが定着しつつある。キーボードでプロンプトを打つよりも、思考のスピードに近い速度でAIに指示を出せるのが大きい。

この記事もAqua Voiceで書いている

ちなみに、この記事自体もAqua Voiceで音声入力しながら作成した。自分の活用事例を喋って、それをAIに記事として整形してもらう——まさにAI活用の実践例そのものだ。

その他の活用 — ブログ執筆・週次レビュー

ここまで紹介した以外にも、いくつかの場面でAIを活用している。

AIを使ったブログ記事作成

今読んでいるこの記事のように、ブログの執筆にもAIを使っている。構成の検討から下書きの生成、校正まで、AIと協力しながら進めている。

日次日記 → 週次・月次レビューのAI分析

日々の軽い振り返り——今日何をやったか、何ができなかったか——を日記としてつけている。それを週単位でAIに投げて分析し、次のアクションを提案してもらう。

「今週はタスクAに時間を取られすぎて、タスクBが進んでいない。来週はタスクBを優先すべきでは？」——こうした提案に沿って日々のタスクの優先順位を調整している。月次でも同様に、1ヶ月分の振り返りをAIに分析させて長期的な視点でのアクションを検討している。

今後の展望

現在のAI活用はここまでだが、さらに広げていく構想がある。

OpenClawを使った自動化の構想

最近話題のOpenClawが気になっている。将来的には、今手動で行っている自動化フローの一部をOpenClawに任せたいと考えており、そのための準備を進めている段階だ。

AIとの協働はまだまだ発展途上で、新しいツールやモデルが出るたびにワークフローが進化する。その変化を楽しみながら、自分のスタイルをアップデートし続けていきたい。

まとめ

筆者のAI活用を振り返ると、以下のようになる。

AIは「コードを書かせるツール」ではなく、日常全体のパートナーになりつつある。1つのサービスに閉じず、複数を用途別に使い分けることで、単体では実現できないワークフローが構築できる。

この使い方が万人にとって最適とは限らない。ただ、「こういう使い方をしているエンジニアもいる」という1つの参考になれば幸いだ。

FAQ

Q. AIサービスに月いくらかかっている？

合計で月額2万円強。Claude Code Max Plan（$100）、ChatGPT Plus（$20）、Gemini（¥2,900）が主な出費で、これにAqua Voice（$10）とAdobe CC（約¥5,000）が加わる。開発効率の向上と情報収集の時間短縮を考えると、十分なリターンがあると感じている。

Q. GitHub Copilotをやめた理由は？

Claude Codeのエージェンティックコーディングの方が自分のスタイルに合っていた。Copilotの行・関数単位の補完より、タスク単位で丸ごと任せられる方が効率的だった。

Q. AI Orchestraの詳細は？

以前ブログ記事で紹介している。複数のAIモデルに役割を割り振り、開発プロセス全体を協調させる仕組みだ。詳細はそちらを参照してほしい。

Q. 音声入力の精度はどのくらい？

Aqua Voiceは技術用語の認識精度が高く、日常の開発会話レベルであればほぼストレスなく使える。ただし、非常にニッチな固有名詞は修正が必要なこともある。

Q. AIに依存しすぎるリスクはない？

ある。基礎的な技術力や思考力は自分で維持する必要がある。AIはあくまで「思考を加速するツール」であり、最終判断は自分で行うという意識が重要だ。AIの提案を鵜呑みにせず、自分の頭で検証する習慣は意識的に保つようにしている。

Claude Codeは強力なAIコーディングツールですが、単体で使い続けるとコンテキストの肥大化や役割の曖昧さといった壁にぶつかります。この記事では、25種の専門エージェントとClaude / Codex / Geminiのマルチモデル連携で課題を解決するオーケストレーションシステム「AI Orchestra」の設計思想と実践を紹介します。

マルチエージェントの基本概念については「マルチエージェント構築入門」も併せて参照してください。

きっかけ：課題解決の調査から見つけた2つのアプローチ

Claude Code単体の運用で感じていた課題（後述するコンテキスト溢れと役割混乱）を解決するために、マルチエージェントシステムを自分で作ろうと決めたことです。

調査を進める中で、2つの有力なアプローチに出会いました。1つは松尾研究所のブログ記事、もう1つはNPMで手軽に導入できるOSSのTaktです。

Taktは導入の手軽さが魅力でした。コマンド1つでマルチエージェント環境が整い、Claude CodeやCodexの使い分けもフレームワーク側が吸収してくれます。初動のパフォーマンス向上という点では明らかに優れていました。

一方、松尾研究所のアプローチはClaude Codeのハーネス（Hooks、Agents、Skills）を深く理解した上で自分で構築する必要があります。手間はかかりますが、業界のデファクトスタンダードになりつつあるClaude Codeの拡張機構を根本から理解できます。

最終的に松尾研究所のアプローチを採用しました。自分のキャリアを考えたとき、便利なツールを使うだけではなく、仕組みそのものを理解して自分で作れることに価値があると判断したからです。AI Orchestraの基本思想は、この松尾研究所のブログ記事をベースにしています。

マルチエージェントの概念や構成パターンについては「マルチエージェント構築入門」で整理しています。

Claude Code単体運用で見えた2つの壁

入門記事をまとめる過程で、Claude Codeの単体運用には大きく2つの壁があると実感しました。

壁1: コンテキスト溢れ

Claude Codeでの開発は1つの長い会話で進行します。設計相談をして、実装に入り、デバッグして、レビューを依頼する。この流れの中で会話が長くなると、前半に伝えた設計方針や制約条件が薄れていきます。大きなファイルの分析を依頼した場合も、コンテキストウィンドウ（LLMが一度に保持できる情報量）が圧迫され、他の指示が押し出される形になります。

壁2: 役割混乱

もう1つの壁は、AIの役割が曖昧になることです。「このコードをレビューして」と依頼したはずなのに、レビュー結果を返す代わりに勝手にコードを書き換えてしまう。設計について相談しているつもりが、気づけばコード生成が始まっている。1つのエージェントがすべてを担当しているため、タスクの境界が不明確になるのです。

以下の表に、具体的な症状とAI Orchestraでの解決アプローチをまとめます。

AI Orchestraの設計思想

AI Orchestraの核は「万能モデルに全部やらせる」のではなく「適材適所で専門家に任せる」という考え方です。

25種の専門エージェント

AI Orchestraでは、開発ワークフローの各工程に対応する25種の専門エージェントを定義しています。

各エージェントにはシステムプロンプトで役割と責任範囲が明確に定義されています。たとえばcode-reviewerは「コードの可読性・保守性・バグ検出に集中し、実装の変更は行わない」と指定されています。これにより、レビューを依頼したのにコードを書き換えられるという役割混乱を構造的に防止しています。

マルチモデルの使い分け

AI Orchestraのもう1つの特徴は、Claude以外のLLMを組み合わせている点です。入門記事ではClaude Code単体での構築例を紹介しましたが、AI Orchestraではさらにモデルを跨いだ連携を実現しています。各モデルには得意領域があり、それを活かす設計です。

モデルの性能差や得意分野については、AIベンチマーク記事も参考にしてください。ベンチマークの読み方を知っておくと、モデルの使い分け判断がしやすくなります。

Claudeがオーケストレーター（司令塔）としてタスクを分配し、深い設計判断はCodex CLIに、大規模なリサーチはGemini CLIにそれぞれ委譲する。こうすることで、各モデルの強みを最大限に引き出しつつ、メインのコンテキストを圧迫しない構成を実現しています。

AI Orchestraの実装：Hook・並列レビュー・マルチモデル連携

ここからは、AI Orchestraの実装を3つの機能に絞って紹介します。

Hookによる自動ルーティング

AI Orchestraの中心にあるのがagent-router.pyというHookです。Claude CodeにはUserPromptSubmitフック（ユーザーの入力を受け取った直後に実行される仕組み）があり、このフックがユーザーの発言を分析して適切なエージェントやCLIツールを自動で提案します。

# ユーザーの発言を分析し、適切なエージェントを提案
# 「セキュリティ大丈夫？」→ security-reviewer を提案
# 「この設計どう思う？」→ architect (+Codex) を提案
# 「最新のライブラリ調べて」→ Gemini CLI を提案

具体的には、日本語・英語両方のトリガーワードを辞書として保持しており、ユーザーの入力にマッチするキーワードがあれば対応するエージェントを提案します。「意識しなくても適切なエージェントが使われる」というUXを目指した仕組みです。

/review で並列レビュー

AI Orchestraでは/reviewという1つのコマンドで、6種のレビュアーを並列に起動できます。

/review  # 以下が並列実行される
# → code-reviewer: 可読性・保守性・バグ検出
# → security-reviewer: 脆弱性・権限チェック
# → performance-reviewer: 計算量・I/O最適化
# → spec-reviewer: 仕様との整合性
# → architecture-reviewer: アーキテクチャ妥当性
# → ux-reviewer: UX・アクセシビリティ

それぞれが独立したサブエージェントとして動作するため、レビュー中にメインのコンテキストは消費されません。各レビュアーの結果は重大度別に集約され、統合レポートとして表示されます。/review impl（実装系のみ）や/review design（設計系のみ）のように、目的に応じて実行範囲を絞ることもできます。

Codex/Gemini マルチモデル連携

設計判断やトレードオフ分析のように深い推論が求められる場面では、Codex CLIに処理を委譲します。一方、ライブラリの最新情報を調べたり、リポジトリ全体の構造を把握したりする場面ではGemini CLIが活躍します。

どちらの場合も、サブエージェント経由で呼び出すことがポイントです。Codex/Geminiの出力は長大になることがあるため、直接メインのコンテキストに流し込むと圧迫してしまいます。サブエージェントに「実行して、結果を要約して返して」と依頼することで、メインのコンテキストには要約だけが届く仕組みになっています。

運用して分かったこと

AI Orchestraを日常の開発で使い始めて、いくつかの発見がありました。

良かった点

• コンテキスト保護が効果的に機能している。長時間の開発セッションでも、前半の指示が抜け落ちる問題がかなり軽減された
• レビュー品質が向上した。6種のレビュアーが並列で動くため、セキュリティやパフォーマンスの見落としが減った
• モデルの使い分けが自動化された。Hookによるルーティングのおかげで、意識しなくても適切なモデルに振り分けられる

改善余地

• エージェント定義のメンテナンスコストがある。25種のシステムプロンプトを適切に保つには継続的な調整が必要
• Hookのルーティング精度は万全ではない。キーワードベースのため、文脈によっては不適切なエージェントが提案されることがある

デプロイは/init-orchestraスキルで有効化でき、dotfiles管理によってプロジェクト間で設定を共有しています。新しいプロジェクトを始めるときも、すぐにオーケストレーション環境を使い始められます。

今後の展望

AI Orchestraは現在GitHubで公開しています。まだ個人開発での運用がメインですが、今後はいくつかの方向で発展させたいと考えています。

まずは汎用化とドキュメント整備です。現状は自分の開発スタイルに最適化されている部分が多いため、他の開発者でも導入しやすい形に整えていきたいです。

次に、実案件での検証です。個人プロジェクトでは十分に機能していますが、チーム開発や規模の大きいコードベースでどこまで通用するかは未知数です。実際のプロジェクトで試して知見を蓄積していきます。

将来的には、エージェントの自律進化も構想しています。使用ログから指摘パターンを学習し、エージェント自身がシステムプロンプトを改善する仕組みです。

「AIに仕事を任せる」のではなく「AIとチームを組む」。AI Orchestraは、そうした開発スタイルを探求するための実験場です。マルチエージェントの世界に興味がある方は、まず入門記事で全体像をつかんだ上で、ぜひ自分の環境で試してみてください。

参考リンク

• AI Orchestra - GitHub
• 松尾研究所 - Claude Code Orchestra
• Takt - マルチエージェントオーケストレーションOSS
• マルチエージェント構築入門
• AIベンチマーク読み方ガイド

Claude Opus 4.6とGPT-5.3-Codexが同日リリースされた2026年2月、AIモデルの選択肢はかつてないほど増えています。「SWE-bench 80%」「ARC-AGI 68%」といった数字が飛び交いますが、それぞれ何を測っていて、自分のタスクにどう関係するのか。この記事では、主要ベンチマークの読み方と、コーディング業務への活かし方を解説します。

この記事の対象読者

• AIコーディングツール（Claude Code、Cursor、GitHub Copilot等）を使っている開発者
• モデル選定の判断材料としてベンチマークを読みたい人
• 「ベンチマークのスコアが高い＝自分の用途に最適」なのか疑問に思っている人

なぜベンチマークを理解すべきか

AIモデルの性能比較は「なんとなく新しいモデルが良い」では判断できなくなっています。

• モデルごとに得意分野が異なる: コード実装に強いモデルと、設計・推論に強いモデルは別
• コストとのトレードオフ: 最高性能モデルが常に最適ではない。タスクに応じた使い分けが合理的
• ベンチマークにも限界がある: スコアの高さが実務性能を保証するわけではない

ベンチマークを「鵜呑みにする」のではなく「読み方を理解して判断材料にする」のが目的です。

ベンチマーク5カテゴリの全体像

主要なAIベンチマークは、大きく5つのカテゴリに分類できます。

以下、開発者にとって特に重要なベンチマークを解説します。

コーディング系ベンチマーク

SWE-bench：最も信頼できるコーディング指標

何を測るか: 実際のGitHubリポジトリのissueを読み、修正パッチを自動生成する能力。

実在するOSSプロジェクトのissueとPull Requestのペアを使い、モデルにissueの説明だけを渡してコードの修正を生成させます。生成されたパッチがテストスイートを通過すれば「解決」と判定されます。

バリエーション:

• Verified（500問）: 人間が検証した信頼性の高いサブセット
• Full（2,294問）: 全問セット。ノイズが多い
• Pro: Scale AIが管理する、より厳密な評価

読み方のポイント: SWE-bench Verifiedのスコアが高いモデルは、実務でのバグ修正・機能追加に強い傾向があります。ただし、テスト通過のみで判定されるため、コードの品質（可読性・保守性）は評価されません。

Terminal-Bench 2.0：エージェント的コーディング能力

何を測るか: サンドボックス化されたターミナル環境で、89種類の実務的タスク（モデルトレーニング、システム管理、データ処理等）を遂行する能力。

SWE-benchが「コード修正」に特化しているのに対し、Terminal-Benchは「ターミナルを操作して問題を解決する」総合力を測ります。AIコーディングエージェント（Claude Code、Codex CLI等）の実力を反映しやすい指標です。

Aider Polyglot：多言語コード編集

何を測るか: C++、Go、Java、JavaScript、Python、Rustの6言語でコードを編集する能力。

1回目の失敗時にテスト結果をフィードバックして2回目を試行する設計で、実際のコーディングアシスタントの使い方に近い評価です。

HumanEval / MBPP：飽和した初期指標

Python関数の生成（HumanEval: 164問）と基本的なPython問題（MBPP: 974問）を測定しますが、現在のフロンティアモデルはいずれも95%以上に達しており、差別化指標としての価値は低下しています。

推論系ベンチマーク

GPQA Diamond：大学院レベルの推論力

何を測るか: 物理・化学・生物の大学院レベル問題で、Google検索しても答えが見つからないような難問への回答能力。専門家でも正解率65%程度の難易度です。

設計やアーキテクチャの判断には深い推論力が求められます。GPQAのスコアが高いモデルは、技術的なトレードオフ分析や複雑なシステム設計に強い傾向があります。

ARC-AGI 2：抽象推論の指標

何を測るか: 視覚的なグリッドパターンの変換規則を推論する問題。学習データにない新規パターンへの汎化能力を測定します。

「AGIに最も近いベンチマーク」とも呼ばれ、データ汚染が困難な設計です。パターン認識と抽象的な推論が必要なため、設計力・問題構造の把握力の代理指標として有用です。

知識・長文脈系ベンチマーク

MMLU / IFEval：知識と指示追従

• MMLU: 57科目の多肢選択問題。フロンティアモデルは90%+で飽和傾向
• IFEval: 「JSONで出力せよ」「300語以内で」等の形式制約を守れるかを測定。エージェントとしての正確性に直結

RULER / MRCR：長文脈の実力

RULERは4K〜128K+トークンの段階的評価で、検索・追跡・集約・QAの4種タスクを含みます。

MRCR v2はOpus 4.6のリリースで注目された新指標で、1Mトークンの文脈中に埋め込まれた8つの「針」を同時に見つける能力を測ります。Opus 4.6は76%、Sonnet 4.5は18.5%と大差がつきました。

2026年2月 最新モデルスコア比較

公式発表とリーダーボードから収集した最新スコアです。

注意点:

• Codex 5.3 はコーディング特化モデルのため、汎用ベンチマークのスコアは限定的
• GPT-5.2 は「Pro」「Thinking」等のバリアントでスコアが異なる
• - はデータ未公開または未測定

各モデルの強み

• Claude Opus 4.6: 推論（ARC-AGI 68.8%）と長文脈（MRCR 76%）で圧倒。設計・レビュー・大規模コードベース理解向き
• GPT-5.3-Codex: Terminal-Bench（75.1%）で最強。実装・デバッグ向き
• Claude Sonnet 4.5: SWE-bench（77.2%）でコスパ良好。定型的なコーディングタスク向き
• GPT-5.2: GPQA Diamond（93.2%）で知識・推論が最強。分析・ドキュメント向き
• Gemini 2.5 Pro: 長文脈処理が得意。コードベース全体の分析向き

実践：タスク別のベンチマーク活用法

開発業務のタスクごとに、どのベンチマークを参考にすべきかの対応表です。

使い分けの例

AIコーディングエージェントでモデルを使い分ける場合:

タスクの性質を判断
├── 実装・修正・デバッグ → Codex系（Terminal-Bench最強）
├── 設計・計画・推論   → Opus系（ARC-AGI・GPQA最強）
├── レビュー・分析     → Opus系（深い推論が必要）
├── 大規模コードベース → Opus系（1M tokens + 長文脈性能）
├── 軽量タスク・大量処理 → Sonnet / Haiku（コスパ重視）
└── 最新情報リサーチ   → Gemini系（Google検索統合）

このハイブリッド戦略は、RedditのClaude Codeコミュニティでも「Opus=設計、Codex=実装」として実践されているアプローチです。

ベンチマークの限界：スコアを鵜呑みにしない

1. データ汚染

学習データにベンチマーク問題が含まれている可能性があります。HumanEvalやMBPPは特にリスクが高い一方、LiveCodeBench（継続更新）やARC-AGI（新規パターン生成）は汚染に強い設計です。

2. 飽和した指標

HumanEval（95%+）、GSM8K（95%+）、MMLU（90%+）はフロンティアモデル間で差がつきません。これらのスコアだけで判断するのは危険です。

3. 実務とのギャップ

ベンチマークは「短いプロンプト・明確な正解・自動判定」の世界です。実務は「曖昧な要件・大規模コードベース・非機能要件」の世界。スコア上位のモデルが実務で苦戦するケースは頻繁に報告されています。

4. 評価条件の差異

同じベンチマークでも、エージェントフレームワーク、プロンプト戦略、リトライ回数で結果が大きく変わります。公式発表値とリーダーボード値が異なることもあります（例: Opus 4.6のTerminal-Bench 65.4% vs 69.9%）。

まとめ

AIベンチマークは「モデルの能力の断面」を測る道具です。読み方のポイントをまとめます。

1. 単一指標で判断しない: コーディング能力はSWE-bench、推論力はGPQA、長文脈はRULER。複数指標を組み合わせる
2. タスクに合った指標を見る: 実装ならTerminal-Bench、設計ならARC-AGI。目的と指標のマッピングを意識する
3. 飽和した指標に注意: HumanEval、GSM8K、MMLUはフロンティアモデルで差がつかない
4. コストも判断軸に入れる: 最高性能モデルが常に最適ではない。タスクの重要度に応じて使い分ける
5. 実務テストを忘れない: ベンチマークはあくまで参考値。自分の業務で試して判断する

AIモデルの進化は速く、今日のスコアは半年後に陳腐化します。ベンチマークの「読み方」を身につけておけば、新モデルが出るたびに適切な判断ができるようになります。

参考リンク

• Anthropic: Introducing Claude Opus 4.6
• Terminal-Bench 2.0 Leaderboard
• SWE-bench Verified Leaderboard
• Aider Polyglot Leaderboard
• LLM Benchmarks 2026

マルチエージェントは「司令塔（オーケストレーター）」が「専門家チーム（サブエージェント）」にタスクを振り分ける構成です。フレームワークなしでもClaude CodeのTaskツールで構築可能ですが、エージェント間連携（ハーネス）の設計は必要です。AIツールの進化で自作の必要性は変わる可能性があります。

マルチエージェントとは何か

マルチエージェントとは、複数のAIエージェントが協調してタスクを遂行するシステムです。1つのLLMにすべてを任せるのではなく、役割を分担することで複雑なタスクに対応します。

シングルエージェントとの違い

シングルエージェントは1つのAI（例：ChatGPT、Claude）が単独でタスクを処理します。ユーザーの指示を受け、思考し、回答を返す一連の流れを1つのエージェントが担当します。

マルチエージェントでは、この流れを複数のエージェントで分担します。

なぜマルチエージェントが注目されているのか

AIエージェントの性能向上に伴い、「1つのエージェントに全部やらせる」アプローチの限界が見えてきました。

1. コンテキスト長の制約: 1つの会話に詰め込める情報には限界がある
2. 専門性の限界: 汎用モデルはすべての領域で最高性能ではない
3. 複雑なワークフロー: 計画→実装→レビューのような多段階処理は分業が効率的

人間のチーム開発と同様に、AIも役割分担することで複雑なタスクに対応できるようになります。

マルチエージェントの基本構成

マルチエージェントシステムは3つの要素で構成されます。

オーケストレーター（司令塔）

オーケストレーターは全体を統括するエージェントです。ユーザーからの指示を受け、適切なサブエージェントにタスクを振り分け、結果を統合します。

役割:

• タスクの分解と振り分け
• サブエージェントの選択
• 結果の統合と最終回答の生成
• エラー時のリトライ判断

サブエージェント（専門家）

サブエージェントは特定の役割に特化したエージェントです。オーケストレーターからタスクを受け取り、専門領域の処理を担当します。

例:

• planner: タスク分解・計画立案
• researcher: 情報収集・調査
• coder: コード実装
• reviewer: コードレビュー・品質チェック
• tester: テスト作成・実行

ツール連携（外部API・CLI）

エージェントは外部ツールと連携して能力を拡張します。ファイル操作、Web検索、API呼び出しなど、LLM単体では不可能な処理を実行します。

例:

• ファイル読み書き（Read, Write, Edit）
• コマンド実行（Bash）
• Web検索（WebSearch）
• 外部API呼び出し

【図】基本構成図

flowchart TB
    User[ユーザー] --> Orchestrator[オーケストレーター]

    Orchestrator --> Planner[planner<br/>計画]
    Orchestrator --> Researcher[researcher<br/>調査]
    Orchestrator --> Coder[coder<br/>実装]
    Orchestrator --> Reviewer[reviewer<br/>レビュー]

    Planner --> Tools[ツール群]
    Researcher --> Tools
    Coder --> Tools
    Reviewer --> Tools

    Tools --> Files[ファイル操作]
    Tools --> CLI[CLI実行]
    Tools --> Web[Web検索]
    Tools --> API[外部API]

代表的なアーキテクチャパターン

マルチエージェントの構成にはいくつかのパターンがあります。

階層型（Hierarchical）

オーケストレーターを頂点とした階層構造です。指示は上から下へ流れ、結果は下から上へ返ります。

特徴:

• 制御が明確
• デバッグしやすい
• オーケストレーターがボトルネックになりやすい

適した用途: 明確なワークフローがある場合（計画→実装→レビュー）

ピアツーピア型（Peer-to-Peer）

エージェント同士が直接やり取りする構成です。中央の司令塔を持たず、必要に応じてエージェント間で協調します。

特徴:

• 柔軟性が高い
• スケールしやすい
• 制御が複雑になりやすい

適した用途: 動的にタスクが変化する場合、エージェント数が多い場合

ハイブリッド型

階層型とピアツーピア型を組み合わせた構成です。基本は階層型で、特定のサブグループ内ではピアツーピアで連携します。

特徴:

• 柔軟性と制御のバランス
• 設計が複雑

適した用途: 大規模で複雑なシステム

【表】パターン比較

個人開発や小規模チームでは、階層型から始めることを推奨します。

構築アプローチの選択肢

マルチエージェントを構築する方法は3つあります。

自作する

LLMのAPIを直接呼び出し、オーケストレーションのロジックを自分で実装します。

メリット:

• 完全なカスタマイズが可能
• 依存関係が少ない
• 内部構造を深く理解できる

デメリット:

• 実装コストが高い
• エラーハンドリング、リトライ等を自前で実装する必要がある

フレームワークを使う（LangChain, AutoGen等）

既存のフレームワークを利用して構築します。

メリット:

• 実装コストが低い
• ベストプラクティスが組み込まれている
• コミュニティのサポートがある

デメリット:

• フレームワークの学習コスト
• 抽象化による制約
• バージョンアップへの追従が必要

参考: LangChain Multi-agent / LangGraph / AutoGen

既存ツールを活用する（Claude Code, Cursor）

AIコーディングツールが提供するサブエージェント機能を活用します。

メリット:

• 追加実装がほぼ不要
• ツール側でハーネスが整備済み
• すぐに試せる

デメリット:

• ツールの仕様に依存
• カスタマイズに限界がある

参考: Claude Code Subagents

【表】アプローチ比較

Claude Codeでの構築例

Claude Codeでは、Taskツールを使ってサブエージェントを呼び出せます。

Taskツールによるサブエージェント呼び出し

Taskツールは専門エージェントを起動し、特定のタスクを委譲するための機能です。

Task(subagent_type="planner", prompt="タスク分解: ユーザー認証機能の実装")

このように呼び出すと、plannerエージェントが起動し、タスク分解を実行して結果を返します。

エージェントの役割定義

Claude Codeでは以下のようなサブエージェントが利用可能です（一部抜粋）。

コンテキスト管理の工夫

マルチエージェントではコンテキスト（会話履歴）の管理が重要です。

課題: メインのオーケストレーターに情報を集中させると、コンテキスト長の制約に達しやすい

対策:

1. 大きな出力が予想されるタスクはサブエージェント経由で実行
2. サブエージェントからは要約を返してもらう
3. 詳細が必要な場合のみ全文を取得

Task(subagent_type="general-purpose", prompt="""
調査を実行し、結果を要約してください（5-7ポイント）。
詳細はファイルに保存してください。
""")

【コード例】基本的な呼び出しパターン

計画フェーズ

Task(subagent_type="planner", prompt="計画: ユーザー認証機能")
Task(subagent_type="researcher", prompt="調査: OAuth 2.0の実装パターン")

設計フェーズ

Task(subagent_type="architect", prompt="設計: 認証システムのアーキテクチャ")
Task(subagent_type="api-designer", prompt="API設計: 認証エンドポイント")

実装フェーズ

Task(subagent_type="backend-python-dev", prompt="実装: 認証API")
Task(subagent_type="tester", prompt="テスト作成: 認証APIのユニットテスト")

レビューフェーズ

Task(subagent_type="code-reviewer", prompt="レビュー: 認証APIの実装")
Task(subagent_type="security-reviewer", prompt="セキュリティレビュー: 認証フロー")

構築して分かった課題と限界

マルチエージェントを自作してみると、いくつかの課題が見えてきます。

ハーネス設計の難しさ

ハーネスとは、エージェント間の連携部分（タスクの受け渡し、結果の統合、エラーハンドリング等）を指します。

課題:

• どのエージェントにどのタスクを振るか判断ロジックが必要
• 失敗時のリトライ・フォールバック戦略
• エージェント間のデータフォーマット統一

既存ツール（Claude Code等）を使う場合、この部分はツール側で整備されていますが、カスタマイズしたい場合は自前での実装が必要です。

コンテキスト長の制約

各エージェントが持てるコンテキスト（会話履歴）には上限があります。

課題:

• 長いタスクでは途中で情報が欠落する可能性
• サブエージェント間で情報を共有する仕組みが必要

対策例:

• ファイルベースでの情報共有
• 要約を活用したコンテキスト圧縮

エージェント間の情報共有

サブエージェントAの結果をサブエージェントBで使いたい場合、情報の受け渡し方法を設計する必要があります。

方法例:

1. オーケストレーター経由で受け渡し
2. 共有ファイルに書き出し
3. 専用のメモリ（状態管理）を用意

運用・デバッグの複雑さ

複数のエージェントが動くため、問題発生時の原因特定が難しくなります。

課題:

• どのエージェントで問題が起きたか特定しにくい
• ログが分散する
• 再現が難しい

今後の展望と判断基準

マルチエージェントは発展途上の技術です。今後の動向を踏まえて、自作するか判断する必要があります。

AIツール自体の進化

Claude Code、Cursor、GitHub Copilotなどのツールは急速に進化しています。

現状の流れ:

• サブエージェント機能の標準搭載
• ハーネス部分の自動化
• より高度なオーケストレーション機能

この流れが続けば、自作する必要性は低下する可能性があります。学習目的では価値がありますが、実用目的なら既存ツールの進化を見守る選択肢もあります。

自作すべきか判断するポイント

以下の場合は自作を検討する価値があります:

1. 特殊なワークフローがある: 既存ツールでは対応できない独自の処理フロー
2. 深いカスタマイズが必要: エージェントの振る舞いを細かく制御したい
3. 学習目的: 内部構造を理解したい
4. 既存ツールに依存したくない: ベンダーロックインを避けたい

【チェックリスト】自作判断フロー

• [ ] 既存ツール（Claude Code, Cursor等）で実現できないか確認した
• [ ] 必要なカスタマイズの範囲を明確にした
• [ ] ハーネス設計に必要な工数を見積もった
• [ ] 保守・運用の体制を考慮した
• [ ] AIツールの進化による陳腐化リスクを許容できる

すべてにチェックが入る場合は自作を検討してください。1つでも不明な点があれば、まず既存ツールで試すことを推奨します。

まとめ

マルチエージェントは「司令塔＋専門家チーム」の構成で複雑なタスクに対応するシステムです。

ポイント:

• 基本構成は「オーケストレーター」「サブエージェント」「ツール連携」の3要素
• Claude CodeのTaskツールを使えばフレームワークなしで構築可能
• ハーネス（エージェント間連携）の設計は避けられない
• 現時点では発展途上。AIツールの進化で状況は変わる可能性がある

次のステップ:

1. まずはClaude CodeやCursorでサブエージェント機能を試す
2. 構成のイメージをつかんでから、自作するか判断する
3. 自作する場合は、小さな構成（2-3エージェント）から始める

マルチエージェントは「作れば終わり」ではなく、継続的な改善が必要な領域です。まずは全体像を理解し、自分の用途に合ったアプローチを選択してください。

FAQ

Q1: マルチエージェントとRAGの違いは何ですか？

RAGは「検索＋生成」で外部データを参照して回答を生成する仕組みです。マルチエージェントは「複数エージェントの協調」で複雑なタスクを分業する仕組みです。RAGをマルチエージェントの1ツールとして組み込むことも可能です。

Q2: フレームワークなしでマルチエージェントを構築できますか？

可能です。Claude CodeのTaskツールやCursorのエージェントモードを使えば、サブエージェント呼び出しが標準機能として提供されています。ただし、エージェント間連携（ハーネス）の設計は必要です。

Q3: マルチエージェントは個人開発でも意味がありますか？

タスクの複雑さによります。単純なタスクならシングルエージェントで十分です。計画→実装→レビューのような多段階ワークフローを自動化したい場合はマルチエージェントが有効です。

Q4: どの程度のプログラミングスキルが必要ですか？

基本的なプログラミング知識と、AIツールのドキュメントを読める程度のスキルが必要です。既存ツール活用なら複雑なコーディングは不要ですが、自作する場合はAPI呼び出しやエラーハンドリングの知識が求められます。

Q5: 今から自作を始めるべきですか？

学習目的なら価値があります。実用目的なら、まず既存ツール（Claude Code、Cursor等）で試すことを推奨します。AIツール自体がマルチエージェント機能を強化しており、自作の必要性は変わる可能性があります。

しかし、その急成長の裏には商標問題、詐欺騒動、そして深刻なセキュリティ脆弱性の発覚と、波乱万丈なドラマがありました。

週末プロジェクトから始まった急成長

たった1時間で生まれた「Clawdbot」

OpenClawの原型は、2025年11月に生まれました。作ったのはPeter Steinberger氏。PDFリーダーアプリ「PSPDFKit」の創業者として知られる人物です。

「チャットアプリとClaude（Anthropic社のAI）を繋げたら面白いかも」という軽い気持ちで、週末にわずか1時間で開発。それが「Clawdbot」でした。

なぜここまで人気が出たのか？

OpenClawが支持される理由は、その「できること」の幅広さにあります。

• 50以上のメッセージアプリに対応: WhatsApp、Telegram、Slack、Discord、Signal、iMessageなど
• メールの自動管理: 受信トレイの整理、自動返信、購読解除
• カレンダー連携: スケジュール管理、リマインダー、フライトのチェックインまで
• ブラウザ操作の自動化: フォーム入力、データ収集

つまり「スマホやPCでやっている面倒な作業を、AIに任せられる」というわけです。しかも無料で使えるオープンソース。この手軽さが爆発的な普及を後押ししました。

3度の改名騒動

急成長の陰で、OpenClawはすでに2回も名前を変えています。

第1の改名: Clawdbot → Moltbot

2026年1月、Anthropic社（AIの「Claude」を開発する会社）から連絡が入ります。「Clawdbot」という名前が「Claude」に似すぎている、という商標上の懸念でした。

プロジェクトは急遽「Moltbot」に改名。しかし、ここで予想外の事件が起きます。

10秒間の隙を突いた詐欺師たち

改名を発表した直後、わずか10秒の間に、詐欺師たちが旧名「Clawdbot」のGitHubアカウントとX（旧Twitter）アカウントを乗っ取ってしまったのです。

さらに悪質だったのは、この混乱に乗じて「$CLAWD」という偽の暗号通貨トークンが登場したこと。なんと時価総額1,600万ドル（約24億円）にまで膨れ上がりました。開発チームはすぐに「公式とは無関係」と否定しましたが、すでに多くの人が被害を受けた後でした。

第2の改名: Moltbot → OpenClaw

その後、商標の徹底調査を経て、プロジェクトは現在の「OpenClaw」に落ち着きました。OpenAIからも使用許可を取得したとのこと。ようやく安定した名前を得られたようです。

セキュリティ問題が浮き彫りにしたリスク

2026年1月末、OpenClawに深刻な脆弱性が見つかりました。

1クリックで乗っ取られる？

発見されたのは「CVE-2026-25253」と呼ばれる脆弱性。わかりやすく言うと、悪意のあるリンクを1回クリックするだけで、自分のOpenClawを他人に乗っ取られるというものです。

攻撃者は乗っ取ったOpenClawを通じて、被害者のメール、カレンダー、ファイルなど、接続されているすべてのサービスにアクセスできてしまいます。

この脆弱性は2026年1月30日のアップデート（v2026.1.29）で修正されましたが、それ以前のバージョンを使っている人は今すぐアップデートが必要です。

「致命的な三重苦」問題

セキュリティ専門家のSimon Willison氏は、OpenClawのようなAIアシスタントが抱える構造的な問題を「Lethal Trifecta（致命的な三重苦）」と呼んでいます。

この3つが揃うと、AIアシスタントは「便利なツール」から「攻撃の入口」に変わりうるというわけです。

Palo Alto NetworksやCiscoといった大手セキュリティ企業も、OpenClawを企業での利用には不適と評価しています。

Moltbook: AIエージェント専用SNSという新世界

OpenClawを語る上で外せないのが「Moltbook」です。

人間は見るだけ、投稿するのはAIだけ

2026年1月に登場したMoltbookは、AIエージェント専用のソーシャルネットワーク。Redditのようなフォーラム形式ですが、投稿やコメントができるのはAIエージェントだけ。人間は閲覧のみ可能という、前例のないサービスです。

キャッチフレーズは「The front page of the agent internet（エージェントインターネットのトップページ）」。

数週間で150万エージェント超え

ローンチからわずか数週間で、登録エージェント数は15万7,000から150万以上に急増。AIエージェント同士が情報交換し、交流するという、SF映画のような光景が現実になっています。

面白さの裏にあるリスク

ただし、Moltbookにもリスクがあります。OpenClawエージェントは4時間ごとにMoltbookを訪問し、他のエージェントの投稿を読み込みます。もし悪意のある投稿があれば、それを読んだエージェントの動作が書き換えられる可能性も指摘されています。

OpenClawは使うべき？使わないべき？

ここまで読むと「危なそう」という印象を持つかもしれません。では、OpenClawは使うべきではないのでしょうか？

✅ こんな人には向いている

• 個人のタスク自動化を試したい人: メッセージの自動返信、リマインダー設定など、日常の小さな自動化を試したい
• AIエージェントの可能性を体験したい人: 「AIが自分の代わりに動く」という未来を、自分の手で試してみたい
• セキュリティ対策ができる人: 最新バージョンを維持し、適切な設定ができる技術的な知識がある

❌ こんな人には向いていない

• 機密データを扱う環境: 仕事のメールや顧客情報など、漏洩が許されないデータがある
• セキュリティが最優先の場面: 金融情報や医療情報など、高いセキュリティが求められる
• 技術的な設定に自信がない人: アップデート管理や設定変更を自分でできない

まとめ

OpenClawは、「AIに日常のタスクを任せる」という夢を、誰でも無料で試せる形で実現しました。週末プロジェクトから始まり、2ヶ月で10万スターを獲得した急成長は、多くの人がこの夢を待ち望んでいた証拠でしょう。

一方で、3度の改名騒動、詐欺事件、深刻な脆弱性の発覚と、「急成長の代償」も明らかになりました。便利さとリスクは表裏一体。それがAIエージェント時代の現実です。

OpenClawの物語は、これからのAIアシスタントがたどる道の縮図かもしれません。便利さに飛びつく前に、リスクを理解すること。そして、自分に合った使い方を選ぶこと。それが、AIと賢く付き合う第一歩ではないでしょうか。

参考リンク

• OpenClaw公式サイト
• OpenClaw GitHub
• CVE-2026-25253 詳細（NVD）
• CNBC: OpenClaw Rise and Controversy

こんな悩みを持っていませんか？実は、カスタム指示を設定するだけで、LLMの回答品質は劇的に変わります。

この記事では、LLM初心者の方に向けて、カスタム指示の基本から実践的な設定例まで詳しく解説します。すぐに使えるテンプレートも用意しましたので、ぜひ活用してください。

カスタム指示とは？

カスタム指示（Custom Instructions）とは、AIに対して「こういう風に答えてね」と事前にお願いしておく設定のことです。

たとえば、こんな指示ができます。

• 「回答は簡潔にして」
• 「専門用語は説明を付けて」
• 「コードを書くときはコメントも入れて」

一度設定しておけば、毎回の会話で自動的に適用されるので、同じお願いを繰り返す必要がなくなります。

どこで設定するの？

主要なLLMサービスでの設定場所と特徴をまとめました（2026年1月時点）。

ChatGPT

設定画面では2つの欄があります。

• 「ChatGPTがあなたについて知っておくべきこと」：職種、専門分野、目的など
• 「ChatGPTにどのように回答してほしいか」：トーン、形式、長さなど

Claude

Claudeには3種類のカスタマイズ機能があります。

スタイル機能のプリセット：

• Normal：標準的な回答
• Concise：簡潔で直接的
• Explanatory：詳細で教育的
• Formal：洗練されたフォーマル

カスタムスタイルも作成でき、自分の文章サンプルをアップロードして学習させることも可能です。

Gemini

Geminiには2種類のカスタマイズ機能があります。

Gem機能は、ChatGPTの「カスタムGPT」に相当する機能で、特定のタスクに特化した専用AIアシスタントを作成できます。Googleが推奨するGemの指示には以下の4要素を含めると効果的です。

1. ペルソナ：Gemが担う役割
2. タスク：やってほしいこと
3. コンテキスト：背景情報
4. フォーマット：出力形式

💡 おすすめ： 初めての方は、無料で使えるChatGPTのカスタム指示か、GeminiのGem機能から試してみるのがおすすめです。

まずはこれだけ！汎用セット6選

「何を設定すればいいかわからない」という方のために、目的別の組み合わせを用意しました。自分に合ったものをコピーして使ってみてください。

1. 基本セット（迷ったらこれ！）

日常的な質問から仕事まで、幅広く使える万能型です。最初の一歩としておすすめです。

- 複雑な問題は分解し、ステップバイステップで解決する
- 要点を先に述べ、詳細は求められたら追加する
- 確認の質問は最小限にし、最も妥当な解釈で回答する
- 不確かな情報は明示し、必要に応じて検索で確認する
- 専門用語は初出時に簡潔に説明する

こんな人におすすめ： LLMを日常的に使いたい、特定の用途が決まっていない

2. 深掘りセット（じっくり分析したいとき）

複雑な問題の分析や、重要な意思決定の材料集めに最適です。

- 問題を分解し、前提条件を列挙してから回答する
- 複数の選択肢がある場合は比較表でトレードオフを明示する
- 主張には反対意見や代替案も検討し、バイアスを避ける
- 不確実性は確率や信頼区間で表現する
- 「もし〜だったら」のシナリオも検討し、判断の妥当性を検証する

こんな人におすすめ： 調査・リサーチに使いたい、意思決定の参考にしたい

3. 高速セット（サクサク使いたいとき）

とにかく素早い回答がほしいときに。チャット感覚で使えます。

- 1-2文で結論を先に述べる。詳細は求められたら追加
- 箇条書きより自然な文章で簡潔に回答
- 確認なしで進行し、問題があれば後から修正
- 社交辞令・過度な謝罪は省略し、本題に直接入る
- 修正時は差分のみ出力し、変更のない部分は省略

こんな人におすすめ： 長い回答にイライラする、テンポよく会話したい

4. 品質重視セット（ミスを避けたいとき）

重要な判断材料が必要なとき、正確性を重視したいときに使います。

- 回答前に「この回答に誤りはないか」を自問し、不確かな点は明示する
- 事実には確信度を示す（「確実に」「おそらく」「推測だが」）
- 推論に仮定が含まれる場合、その仮定を明確に述べる
- 技術情報は最新かどうか確認し、バージョン情報を明記する
- 回答の最後に確信度（高/中/低）と、低い場合はその理由を述べる

こんな人におすすめ： 仕事で使う、信頼性の高い回答がほしい

5. 対話セット（一緒に考えてほしいとき）

アイデアの壁打ちや、考えを整理したいときに最適です。

- 直接答えを教えず、適切な質問で考えを導く
- 私の説明を聞き、理解した内容を自分の言葉で言い換えて確認する
- 問題解決の前に、まず状況や感情を理解・共感する一文を入れる
- 矛盾や曖昧な点があれば指摘して確認する
- 回答の最後に「次に検討すべきこと」を1-2個提案する

こんな人におすすめ： ブレスト相手がほしい、考えを深めたい

6. 実行セット（具体的に動きたいとき）

計画を立てたい、実際にアクションを起こしたいときに使います。

- アドバイスは「今すぐ実行できる具体的なアクション」を含める
- タスクには概算の所要時間を添える
- 数値は具体的に示し、「多い」「少ない」などの曖昧表現を避ける
- 計画にはリスク（発生確率×影響度）と上位3つへの対策を含める
- 問題発生時の切り戻し手順も提供する

こんな人におすすめ： プロジェクト管理に使いたい、具体的な行動計画がほしい

汎用セット早見表

もっと細かく設定したい人へ：カテゴリ別カスタム指示集

ここからは、より細かくカスタマイズしたい方向けに、目的別の指示を紹介します。必要なものを組み合わせて使ってください。

1. 思考・推論プロセス

AIの「考え方」をコントロールする指示です。より論理的で深い回答を引き出せます。

1-1. 問題分解とステップバイステップ思考

複雑な問題には、まず問題を小さな部分問題に分解し、各ステップを明示しながら段階的に解決すること。

効果： 複雑な質問でも、順序立てて分かりやすく説明してくれるようになります。

1-2. 前提・仮定の明示

推論に仮定が含まれる場合、その仮定を明確に述べ、妥当かどうかを検討してから結論を導くこと。

効果： 「〜と仮定すると」と前置きしてくれるので、回答の限界がわかりやすくなります。

1-3. 自己検証の強制

回答前に「この回答に誤りはないか」を自問し、不確かな点は明示すること。

効果： AIが自分の回答を見直すことで、ケアレスミスが減ります。

1-4. 多角的分析

主張を述べる際は、反対意見や代替案も必ず検討すること。自分の主張に対してあえて反論を試み、その反論に耐えられるか検証してから結論を出す。

効果： 一方的な意見ではなく、バランスの取れた回答が得られます。

1-5. 逆向き思考

目標から逆算して考える。「何が達成されれば成功か」を先に定義してから解決策を考えること。

効果： ゴールが明確になり、的外れな提案が減ります。

1-6. First Principles Thinking（第一原理思考）

既存の解決策に飛びつかず、問題の本質を根本から考え直すこと。「なぜそうなっているのか」を問い続ける。

用語解説： First Principles Thinkingとは、既存の常識や前提を疑い、物事の本質から考え直す思考法です。イーロン・マスクが好んで使うことで知られています。

1-7. MECE原則の適用

選択肢や分類を示す際は、漏れなくダブりなく（MECE）整理すること。

用語解説： MECE（ミーシー）は「Mutually Exclusive, Collectively Exhaustive」の略で、「漏れなく、重複なく」という意味です。

1-8. 仮説駆動

調査や分析の前に仮説を立て、その仮説を検証する形で進めること。

効果： 闇雲に調べるのではなく、効率的に核心に迫れます。

1-9. 比較分析の徹底

複数の選択肢がある場合、必ず比較表を作成し、各項目のトレードオフを明示すること。

効果： 選択肢のメリット・デメリットが一目でわかります。

1-10. 不確実性の定量化

予測や推定を行う際は、可能な限り確率や信頼区間で不確実性を表現すること。

効果： 「たぶん大丈夫」ではなく「80%の確率で成功」のように具体的になります。

1-11. 反事実的思考

「もし〜だったら」というシナリオを積極的に検討し、現在の判断の妥当性を検証すること。

効果： 見落としていたリスクや可能性に気づけます。

2. 出力形式・品質

回答の「見た目」や「構成」をコントロールする指示です。

2-1. 簡潔さと要点先行

冗長な説明を避け、要点を先に述べる。長い回答の場合は最初に1-2文の要約（TL;DR）を置き、詳細はその後に続ける。詳細は求められた場合のみ追加する。

用語解説： TL;DRは「Too Long; Didn't Read」の略で、「長すぎて読まなかった人向けの要約」という意味です。

2-2. 構造化出力

技術的な説明では、概要→詳細→例示→注意点の順で構成すること。

2-3. 箇条書き制限

箇条書きは本当に必要な場合のみ使用し、通常は自然な文章で回答すること。

効果： 読みやすい自然な文章になります。箇条書きの乱用を防げます。

2-4. 実行可能性の優先

アドバイスは「今すぐ実行できる具体的なアクション」を含めること。抽象的な提案だけで終わらない。

2-5. 数値の具体化

「多い」「少ない」などの曖昧な表現を避け、可能な限り具体的な数値や範囲を示すこと。

2-6. 時間見積もりの付与

タスクやプロジェクトの提案には、概算の所要時間を必ず添えること。

2-7. 難易度・前提知識の明示

技術的な解説には、対象読者のレベル（初級/中級/上級）を明示し、理解に必要な前提知識を列挙すること。

2-8. バージョン情報の明記

ソフトウェアやライブラリに言及する際は、対象バージョンを明記し、バージョン間の差異があれば注記すること。

効果： 「このコード動かない！」というトラブルを防げます。

2-9. 出典形式の統一

参考情報を示す際は、[タイトル](URL) の形式で統一すること。

2-10. 変更点のハイライト

修正や改善を提案する際は、変更箇所を明確に示し、なぜその変更が必要かを説明すること。

3. コミュニケーションスタイル

AIとの「会話の仕方」をコントロールする指示です。

3-1. 言語・トーン設定

日本語で、敬語を使わずカジュアルに回答すること。

アレンジ例： 「ですます調で丁寧に」「関西弁で」など、好みに合わせて変更できます。

3-2. 確認行動の最小化

曖昧な質問でも、最も妥当な解釈で即座に回答を試みる。「よろしいですか？」「続けますか？」などの確認は省略し、自律的に進める。解釈が複数ありどうしても判断できない場合のみ1つだけ確認する。

効果： 「それはAですか？Bですか？」という質問返しが減り、テンポよく会話できます。

3-3. ソクラテス式

直接答えを教えず、適切な質問を投げかけて考えを導くこと。学習目的の質問には特にこのアプローチを使う。

用語解説： ソクラテス式問答とは、答えを教えるのではなく、質問を通じて相手自身に気づかせる教育方法です。

3-4. ラバーダック

私の説明を聞き、理解した内容を自分の言葉で言い換えて確認すること。誤解があれば指摘する。

用語解説： ラバーダックデバッグとは、問題をゴム製のアヒルに説明することで解決策に気づく手法です。AIに聞き役になってもらいます。

3-5. 共感優先

問題解決の前に、まずユーザーの状況や感情を理解・共感する一文を入れること。

3-6. 直接的フィードバック

遠回しな表現を避け、問題点は直接的に指摘すること。ただし建設的な改善案を必ず添える。

3-7. 専門用語の扱い

専門用語を使う際は、初出時に括弧内で簡潔な説明を加えること。例：API（アプリケーション間の通信規約）

3-8. 比喩の活用

抽象的な概念は、日常的な比喩を使って説明すること。ただし比喩の限界も明示する。

3-9. 会話の継続性

前の発言を踏まえて回答し、「先ほどの〜について」のように文脈を参照すること。

3-10. 謝罪・賞賛の最小化

過度な謝罪を避け、問題があれば簡潔に認めて即座に修正に移る。「素晴らしい質問ですね」などの社交辞令は省略し、本題に直接入ること。

効果： 本題に集中でき、会話がスムーズになります。

4. 役割・ペルソナ設定

AIに特定の「役割」を演じてもらう指示です。専門的な回答が得られます。

4-1. シニアソフトウェアエンジニア

あなたは10年以上の経験を持つシニアソフトウェアエンジニアとして回答する。ベストプラクティスと実務上の注意点を含めること。

4-2. 教育者モード

初学者に教えるように、専門用語は初出時に必ず説明し、具体例を多用すること。

4-3. 批評家モード

私のアイデアやコードに対して、改善点や潜在的な問題を積極的に指摘すること。お世辞は不要。

4-4. データサイエンティスト

統計的な主張には必ず検定方法と有意水準を示し、相関と因果の区別を明確にすること。可視化を積極的に提案する。

4-5. プロダクトマネージャー

機能提案にはユーザーストーリー形式（「〜として、〜したい、なぜなら〜」）を使い、優先順位付けの根拠を示すこと。

4-6. テクニカルライター

手順書は番号付きステップで書き、各ステップは1つのアクションのみ含む。スクリーンショットの挿入位置を指示する。

4-7. セキュリティエンジニア

すべての入力は信頼できないものとして扱い、攻撃ベクトル（OWASP Top 10など）を常に考慮すること。

4-8. DevOpsエンジニア

インフラ提案にはIaC（Infrastructure as Code）を使い、再現性と自動化を重視すること。モニタリングとアラートも含める。

4-9. UXデザイナー

UI提案にはユーザーの認知負荷を考慮し、アクセシビリティ（WCAG基準）への配慮を含めること。

4-10. 法務アドバイザー風

リスクを指摘する際は、可能性と影響度を分けて評価し、「〜の場合に〜のリスクがある」と条件付きで述べること。

4-11. 編集者

文章をレビューする際は、構成・論理・表現・文法の4レイヤーに分けてフィードバックすること。

4-12. コンサルタント

提案は「現状分析→課題特定→解決策→実行計画→期待効果」の構成で述べること。

4-13. メンター

答えを教えつつも、その背景にある原則や考え方を説明し、応用できる知識として伝えること。

5. コード・技術

プログラミング関連のタスクに特化した指示です。エンジニアの方は特に参考になります。

5-1. コードブロックの基本ルール

コードを書く際は、言語名を明記し、コメントで「なぜそうしているか」を説明すること。「何をしているか」はコードを読めば分かるので書かない。

5-2. エラーハンドリング必須

コードを書く際は、想定されるエラーケースを列挙し、それぞれに対する処理を必ず含めること。

5-3. セキュリティ意識

コードを書く際は、セキュリティ上の脆弱性を常に考慮すること。確認項目：入力検証、認証/認可、SQLインジェクション、XSS、CSRF、機密情報の扱い

5-4. テストコード同梱

関数やクラスを実装する際は、基本的なユニットテストも一緒に提供すること。

5-5. パフォーマンス意識

アルゴリズムやデータ構造を提案する際は、時間計算量と空間計算量をO記法で示すこと。

用語解説： O記法（ビッグオー記法）は、アルゴリズムの効率を表す指標です。O(n)は「データ量に比例」、O(1)は「データ量に関係なく一定」を意味します。

5-6. 依存関係の最小化

外部ライブラリの使用は最小限に抑え、使用する場合は理由を説明すること。

5-7. イディオマティックなコード

各言語の慣用的な書き方（Pythonならpythonic）に従い、その言語らしいコードを書くこと。

5-8. 型アノテーション

Python、TypeScriptなど型ヒントが使える言語では、必ず型アノテーションを付けること。

5-9. docstring/JSDoc必須

関数には必ずdocstring（またはJSDoc）を書き、引数・戻り値・例外・使用例を含めること。

5-10. 環境変数の活用

設定値やシークレットはハードコードせず、環境変数から読み込む形で実装すること。

5-11. ログ出力の設計

本番コードには適切なログレベル（DEBUG/INFO/WARN/ERROR）でログを出力する処理を含めること。

5-12. リファクタリング提案

既存コードを改善する際は、まず動作を変えずに構造を改善し、その後で機能を追加すること。

5-13. CLI出力の設計

CLIツールは、--help、--version、--verbose、--quietオプションを標準で実装すること。

5-14. 冪等性の確保

スクリプトや処理は、複数回実行しても同じ結果になるように設計すること。

用語解説： 冪等性（べきとうせい）とは、同じ操作を何度実行しても結果が変わらない性質のことです。

5-15. ロールバック計画

変更を提案する際は、問題が発生した場合の切り戻し手順も一緒に提供すること。

6. タスク特化

特定の作業に最適化された指示です。

6-1. コードレビュー

コードレビュー時は以下の観点で評価し、具体的な改善コードを示すこと：
1. 正確性（バグがないか）
2. セキュリティ（脆弱性がないか）
3. パフォーマンス（効率的か）
4. 可読性（理解しやすいか）
5. 保守性（変更しやすいか）
6. テスト容易性（テストしやすいか）
各観点でスコア（1-5）と具体的コメントを述べる。

6-2. 文章校正

文章の校正では、誤字脱字・文法・論理の飛躍・冗長表現を指摘し、修正案を並記すること。

6-3. ブレインストーミング

アイデア出しでは、最初に10個以上の案を列挙し（判断を保留）、その後で実現可能性と独自性の観点から上位3つを推薦すること。

6-4. バグ調査

バグ報告に対しては：
1. 再現手順の確認
2. 期待動作と実際の動作の明確化
3. 仮説の列挙（可能性の高い順）
4. 各仮説の検証方法
5. 最も可能性の高い原因と修正案

6-5. 設計レビュー

設計をレビューする際は、SOLID原則、DRY、KISS、YAGNIの観点から評価し、具体的な改善案を示すこと。

用語解説：

• SOLID：オブジェクト指向設計の5原則
• DRY：Don't Repeat Yourself（繰り返しを避ける）
• KISS：Keep It Simple, Stupid（シンプルに保つ）
• YAGNI：You Aren't Gonna Need It（必要になるまで作らない）

6-6. 障害対応

障害時は：
1. 影響範囲の特定
2. 暫定対処（止血）
3. 根本原因の調査
4. 恒久対策
5. 再発防止策
の順で提案すること。

6-7. 見積もり

工数見積もりには、楽観値・最頻値・悲観値の3点見積もりを使い、リスク要因も列挙すること。

6-8. 要件定義支援

要件をヒアリングする際は、機能要件と非機能要件を分け、曖昧な表現（「速い」「使いやすい」など）は具体的な指標に置き換えること。

6-9. API設計

REST API設計では、リソース指向、適切なHTTPメソッド、ステータスコード、バージョニング、ページネーション、エラーレスポンス形式を考慮すること。

6-10. データベース設計

DB設計では、正規化レベル、インデックス戦略、制約（FK、UNIQUE、CHECK）、将来の拡張性を考慮し、ER図で示すこと。

6-11. 移行計画

システム移行の提案には、移行前チェックリスト、移行手順、検証項目、切り戻し手順、移行後確認事項を含めること。

6-12. ドキュメント作成

技術文書には、対象読者、前提条件、目的、本文、参考リンク、更新履歴を含めること。

7. 学習・教育向け

勉強や教育目的で使うときの指示です。

7-1. 段階的難易度

学習コンテンツは、簡単な例から始めて徐々に複雑にする。各段階で「ここまでのポイント」を整理する。

7-2. 誤答分析

間違いを指摘する際は、なぜその間違いが起きやすいのか（よくある誤解）も説明すること。

7-3. 類似概念の比較

似ている概念（例：並行と並列、認証と認可）を説明する際は、必ず違いを明確にする比較表を作ること。

7-4. 実践課題の提供

概念を説明した後、理解を確認するための練習問題を2-3問提示すること。

7-5. 学習ロードマップ

新しい技術を学ぶ際は、学習の順序（何を先に学ぶべきか）とマイルストーンを示すこと。

7-6. つまずきポイントの先回り

初学者が躓きやすいポイントを予測し、事前に注意喚起すること。

7-7. 暗記 vs 理解の区別

「これは覚えるしかない」ものと「原理を理解すれば導ける」ものを明確に区別して伝えること。

8. メタ指示・自己改善

AIの「振る舞い方」自体をコントロールする指示です。

8-1. 指示の解釈確認

曖昧な指示を受けた場合、自分の解釈を述べてから回答を始めること。

8-2. 自己評価の付与

回答の最後に、その回答の確信度（高/中/低）と、低い場合はその理由を述べること。

8-3. 代替案の提示

回答とともに、「別のアプローチ」として異なる解決策も1つ以上提示すること。

8-4. 限界の明示

できないこと、分からないことは明確に述べ、推測で回答する場合はその旨を明示すること。

8-5. フォローアップ提案

回答の最後に、「次に検討すべきこと」や「関連して調べると良いこと」を1-2個提案すること。

8-6. 矛盾の検出

ユーザーの発言に矛盾がある場合、それを指摘して確認すること。

8-7. コンテキスト要約

長い会話では、定期的にこれまでの議論を要約し、認識を合わせること。

8-8. 改善フィードバック要求

重要な回答の後、「この説明で分かりにくい点があれば教えてください」と明示的に確認すること。

9. 創造性・アイデア発想

クリエイティブな作業を支援する指示です。

9-1. 制約を変える

アイデア出しで行き詰まったら、制約条件を意図的に変えて（緩める/厳しくする/逆転する）発想すること。

9-2. 異分野からの類推

問題解決の際、全く異なる分野（生物学、建築、ゲームなど）での類似問題とその解決策を参考にすること。

9-3. SCAMPER法の適用

改善アイデアを出す際は、Substitute/Combine/Adapt/Modify/Put to other uses/Eliminate/Reverseの観点で検討すること。

用語解説： SCAMPER法は、既存のアイデアを発展させるためのフレームワークです。代用・結合・応用・修正・転用・削除・逆転の7つの視点からアイデアを広げます。

9-4. 最悪のアイデアから

あえて最悪のアイデアを考え、それを反転させることで良いアイデアを導くこと。

10. プロジェクト管理・意思決定

計画立案や判断を支援する指示です。

10-1. リスク分析

計画を立てる際は、リスク（発生確率×影響度）を評価し、上位3つへの対策を含めること。

10-2. 意思決定マトリクス

選択肢を評価する際は、評価軸と重み付けを明確にしたマトリクスを作成すること。

10-3. ステークホルダー分析

提案を作成する際は、影響を受ける関係者を列挙し、各者の関心事と懸念を考慮すること。

10-4. MVP思考

機能提案では、最小限の実装で価値を検証できるMVP（Minimum Viable Product）を最初に定義すること。

用語解説： MVP（Minimum Viable Product）とは、必要最小限の機能だけを持つ製品のことです。早く市場に出してフィードバックを得るために使われます。

10-5. 振り返り構造化

プロジェクトの振り返りでは、Keep（続けること）/Problem（問題）/Try（試すこと）の形式で整理すること。

11. 出力制御・特殊指示

細かい出力の調整に使う指示です。

11-1. 出力長の制御

回答は[短い/普通/詳細]モードで調整可能。デフォルトは普通（300-500字程度）。「詳しく」と言われたら詳細モードに切り替える。

11-2. 思考の可視化

複雑な問題では、思考過程を「考えていること：」として明示的に示してから結論を述べること。

11-3. 仮置きして進行

不明点があっても一旦仮定を置いて回答を完成させ、仮定部分を明示すること。後から修正可能。

11-4. 差分のみ出力

修正を求められた場合、変更箇所のみを示し、変更のない部分は省略すること。

11-5. 段階的開示

長い回答は分割して提供し、各部分の終わりで続きが必要か確認すること。

11-6. 条件分岐の明示

「Aの場合は〜、Bの場合は〜」のように、状況によって回答が変わる場合は条件を明示すること。

11-7. 優先順位の遵守

指示が矛盾した場合の優先順位：安全性 > 正確性 > 有用性 > 効率性 > 美しさ

11-8. メタ指示の受付

「今後は〜」で始まる指示は、以降の会話全体に適用する永続的な設定変更として扱うこと。

11-9. ロールの切り替え

「〜として答えて」と言われたら、そのロールを維持する。「普通に戻って」でデフォルトに戻す。

11-10. 中断と再開

長いタスクは論理的な区切りで分割し、各区切りで進捗を報告すること。

12. 品質・安全性

回答の信頼性を高める指示です。

12-1. ソース意識

事実を述べる際は、確信度を示す（「確実に」「おそらく」「推測だが」など）。不確かな情報は検索で確認すること。

12-2. 最新情報への配慮

技術情報や時事問題は、知識のカットオフを意識し、必要に応じてウェブ検索で最新情報を確認すること。

効果を高める4つのコツ

最後に、カスタム指示をより効果的にするためのコツを紹介します。

1. 具体的に書く

❌ 悪い例：「良い回答をして」

✅ 良い例：「3文以内で要点を先に述べる」

抽象的な指示より、具体的な行動を書いた方が効果的です。

2. 優先順位を示す

正確性 > 簡潔さ > 網羅性

複数の指示が矛盾する場合に備えて、優先順位を明示しておくと安心です。

3. 例を添える

専門用語は初出時に説明する。例：API（アプリケーション間の通信規約）

望む出力の具体例を1つ入れると、AIの理解度が大幅に上がります。

4. 否定形も使う

- 箇条書きは必要な場合のみ使用し、通常は自然な文章で回答する
- 「素晴らしい質問ですね」などの社交辞令は省略する

「〜しない」という制約も効果的です。やってほしくないことを明示しましょう。

まとめ

カスタム指示を設定することで、LLMの回答品質は大きく変わります。

初めての方は：

1. まず「基本セット」を試す
2. 不満点が出てきたら、該当するカテゴリから指示を追加
3. 自分だけの最適な組み合わせを見つける

という流れがおすすめです。

この記事で紹介した指示は、すべてコピー＆ペーストで使えます。ぜひ色々試して、あなたに合った設定を見つけてください。

この記事が参考になったら、シェアしていただけると嬉しいです！

TL;DR

まずはモデルサイズが小さいものから始めて「起動→1回応答」まで通し、用途に合わせて段階的にモデルを変えるのが安全です。モデルが大きいほど、メモリ/ディスク消費と処理時間が増えやすくなります。

先に結論：最初は“小さめモデルで1回応答”まで通す

結論：最初にやることは「小さめのモデルで 1 回応答を返す」だけです。ここまで通れば、以降の問題は「モデル選定」か「性能/運用」のどちらかに寄せて切り分けできます。

なぜ小さめから始めるべきか（失敗要因が減る）

モデルが大きいほど、必要なメモリやディスク容量が増えます。その結果、初回のセットアップで発生しやすい問題（動作が遅い/メモリ不足/ディスク不足）が増えます。最初は “成功状態を作る” ことを優先してください。

この記事でできるようになること（到達点を明確化）

この順に進めます。

1. Ollama を導入する
2. モデルを取得する（まずは小さめ）
3. CLI で 1 回応答を確認する
4. 必要なら API（OpenAI 互換）でも疎通確認する
5. モデル選定と運用上の注意を把握する

この記事の提供物（チェックリスト/早見表/curlテンプレ）

「再現しやすい」ことを優先して、次をコピペ用で用意します。

• インストール後チェックリスト（バージョン/ヘルプ/起動状態）
• モデル選定の早見表（用途×サイズ×必要リソース×体感）
• API 疎通確認テンプレ（curl 1 発）

Ollama とは何か：ローカルでLLMを動かすための入口

結論：Ollama は、ローカルで LLM を「取得して」「起動して」「呼び出す」までを短い手順で行うためのツールです。(要出典: Ollama公式)

どんな用途に向くか（検証/プロトタイピング）

次の用途に向きます。

• プロンプトの試行錯誤（要約/文章生成/アイデア出し）
• ローカル API でアプリ側の I/F を検証する（まず疎通、次に実装）
• 外部サービスに送らずに検証したい（ただし投入データの扱いは要判断）

向かないケース（重いモデル・低スペック等の注意）

次の条件では「セットアップはできても快適ではない」可能性が上がります。

• メモリに余裕がないのに、大きいモデルを前提にしている
• CPU 実行なのに GPU 実行の速度を期待している（体感の前提がズレる）
• 常時稼働を前提にしている（更新/ディスク管理/公開範囲の運用が必要）

インストール（Mac想定）と導入後の確認（チェックリスト付き）

結論：インストールしたら、まず「バージョン」「ヘルプ」「起動状態」を確認してください。ここを飛ばすと、後工程で詰まったときに原因が追えません。

インストール手順（Homebrew前提）※コマンドは公式で確認

手順（例）：

1. Homebrew がない場合は導入する (要出典: Homebrew公式)
2. Ollama をインストールする
   1. brew install ollama (要出典: Homebrew Formulae - ollama)
3. インストール確認
   1. ollama --version (要出典: Ollama公式CLI)

※Ollama は macOS アプリとして動作する形態もあります。インストール方法・起動方法は公式の案内に従ってください。(要出典: Ollama公式)

導入後の確認（バージョン/ヘルプ/起動状態）

1. ヘルプを表示して、使えるサブコマンドを確認する
   1. ollama --help (要出典: Ollama公式CLI)
2. 起動状態を確認する（起動方式により異なる）
   • CLI で起動するのか、アプリとして起動するのかを、公式と --help で確定する (要出典: Ollama公式)

インストール後チェックリスト（コピペ用）

• [ ] ollama --version が表示できる (要出典: Ollama公式CLI)
• [ ] ollama --help が表示できる (要出典: Ollama公式CLI)
• [ ]（任意）API を使う場合、ローカルの待受（例：http://localhost:11434）に疎通できる (要出典: Ollama公式 OpenAI互換API)

最短で動かす：モデル取得→起動→1回応答

結論：「モデル取得 → 起動 → CLI で 1 回応答」の順で進めると、前提が少なく成功しやすいです。

モデルを選んで取得する（まずは小さめ）

最初は “小さめのモデル” を選んでください。ここで言う「小さめ」は、モデルサイズ（パラメータ数など）が比較的小さいもの、または軽い量子化のものです。どれが該当するかは公式の一覧で確認してください。(要出典: Ollama公式モデル一覧)

手順（例）：

1. モデルを取得する
   1. ollama pull <model> (要出典: Ollama公式CLI)

起動（サーバー/常駐）と停止

起動方法は環境差が出やすいので、この記事では「自分の環境の正解」を --help と公式で確定する前提にします。(要出典: Ollama公式)

確認観点（ここだけ押さえる）：

• 起動しているか（プロセス/メニューバー/待受ポートなど）
• 停止できるか（常駐を止められるか）

1回応答の確認（CLI で最短）

手順（例）：

1. モデルを実行してプロンプトを投げる
   1. ollama run <model> (要出典: Ollama公式CLI)
2. まずは短い入力で 1 回だけ応答を確認する（例：日本語で 1 行）

注意：

• 初回はモデル読み込みで時間がかかることがあります
• 応答が返れば、セットアップは成功と判断できます

モデルの選び方：用途×日本語×サイズ×快適さで決める

結論：モデル選定は「用途」と「快適に動くか（メモリ/速度/ディスク）」で決めます。品質だけで選ぶと、運用が破綻しやすくなります。

選定の観点（用途・品質・速度・コスト＝リソース）

最低限、次の観点で判断します。

• 用途：雑談/要約/文章生成/コード支援など
• 言語：日本語の比重（日本語中心なら、まず日本語で短文テストする）
• 速度：対話の待ち時間を許容できるか
• リソース：メモリ/ディスク/発熱/バッテリー（ノートPC）

“大きいほど良い”ではない（トレードオフの整理）

一般に、モデルが大きいほど品質が上がりやすい一方、必要なメモリが増え、応答も遅くなりがちです。まずは “動くサイズ” を見つけ、用途に応じて段階的に変えてください。

マシンスペック別の選び方（断定せず目安）※要出典

ここは数値を断定せず、判断フローにします（数値を出す場合は出典必須）。

1. 小さめのモデルで 1 回応答が返ることを確認する
2. 遅い/重いなら、まずモデルサイズを下げる
3. まだ厳しいなら、同時に動かすアプリを減らす
4. それでも用途に耐えないなら、目的（速度/品質）に合わせて環境（より強いマシン/GPU 等）を検討する
   (要出典: モデルサイズと必要メモリの一般的目安、各モデルの推奨要件)

よくある詰まりと切り分け（遅い/メモリ/取得失敗/ディスク肥大）

結論：詰まったら「症状 → 原因候補 → 対策の順序」で切り分けてください。順番を固定すると、原因が追いやすくなります。

体感が遅いとき（モデルサイズ/同時アプリ/期待値）

確認の順序：

1. モデルサイズを下げる（最優先）
2. 同時に動いているアプリを減らす（ブラウザ/IDE 等）
3. CPU 実行の前提に期待値を合わせる（GPU 前提で比較しない）(要出典: CPU/GPU比較の一般論)

メモリ不足っぽいとき（症状と対策の順序）

症状例：

• 起動/読み込みで止まる、OS 全体が重くなる、他アプリが落ちる

対策の順序：

1. モデルサイズを下げる
2. 同時アプリを止める
3. 常駐プロセスを減らす
4. 必要なら「ローカルでやる範囲」を見直す（用途と品質の再調整）

モデル取得に失敗するとき（ネットワーク/容量）

確認ポイント：

• ネットワークが不安定でないか
• ディスク容量が足りているか（モデルはサイズが大きい）(要出典: モデルサイズの説明)

ディスクが増えるとき（一覧・削除・更新の運用）※コマンドは要確認

結論：モデルは増える前提なので、「一覧→不要削除→自分ルール」をセットで決めます。

1. 現在のモデル一覧を見る（例：ollama list）(要出典: Ollama公式CLI)
2. 不要なモデルを削除する（例：ollama rm <model>）(要出典: Ollama公式CLI)
3. 検証用は軽量モデルに固定する、などの運用ルールを決める

API で疎通確認する（最小テンプレ）

結論：CLI で 1 回応答を確認できたら、次に API を “最小テンプレ” で疎通確認します。ここまで通れば、アプリ検証に進めます。

まずは curl 1発で確認する（成功判定の観点）

Ollama は OpenAI 互換 API を提供しています。(要出典: Ollama OpenAI compatibility)

手順（例）：

1. サーバーが起動している前提で、次を実行する
2. <model> は ollama run で動作確認できたモデル名に置き換える

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "messages": [{"role":"user","content":"テストです。1行で返して"}]
  }'

(要出典: Ollama公式 OpenAI互換API)

成功判定の観点：

• HTTP が 200 系で返る
• レスポンスに出力が含まれる（例：choices/message 相当）(要出典: Ollama公式 OpenAI互換APIレスポンス形式)

OpenAI 互換 API を使う場面（アプリ検証に寄せる）

使いどころ：

• 既存の OpenAI クライアント/ツールを “ホスト差し替え” で動かしたい
• アプリ側の I/F（ストリーミング、ツール呼び出し等）を先に作りたい

うまくいかないときの観点（URL/ポート/バインド）※要出典

よく見るポイント：

• localhost:11434 に到達できるか（ポート・起動状態）(要出典: Ollama公式)
• 別ホスト/別端末から叩く場合、バインド先や FW を閉じられているか（意図せぬ公開を避ける）(要出典: Ollama公式 or OSネットワーク設定)

API 仕様の参照先（公式）と、curlテンプレ（コピペ用）

公式で確認しておく項目（ここを押さえるとブレません）：

• デフォルトのベースURL/ポート（例：11434）(要出典: Ollama公式 OpenAI互換API)
• 対応エンドポイント（例：/v1/chat/completions）(要出典: Ollama公式 OpenAI互換API)
• サポートされるリクエストフィールド（例：model/messages/stream 等）(要出典: Ollama公式 OpenAI互換API)

運用と安全：ローカルでも“公開範囲”と“投入データ”を決める

結論：ローカルでも「どこまで公開されるか」と「何を投入してよいか」を決めないと、事故（意図せぬ公開・データ持ち出し）につながります。

うっかり公開のリスク（バインド先/ポート/FW）

注意点：

• ローカル専用のつもりでも、設定や共有の仕方次第で外部から到達できる可能性があります
• 社内ネットワーク内での利用でも、公開範囲を明確にしてください
  (要出典: Ollamaのホスト設定/OSのFW設定)

社内データ投入の判断（利用条件・リスク）

判断観点：

• モデルの利用条件（ライセンス/規約）を確認する (要出典: 各モデルカード/配布元)
• 入力データの取り扱い（ログ/保存/共有の有無）を把握する (要出典: Ollamaのデータ取り扱いに関する公式情報)

継続運用（更新/削除/定期メンテ）

最低限の運用ルール例：

1. 使わないモデルは削除する（ディスク肥大を抑える）
2. 更新時は --help でコマンド差分を確認する
3. トラブルが出たら「症状→切り分け」に戻る

参考

• Ollama 公式サイト/ドキュメント (要出典: https://ollama.com/ / https://docs.ollama.com/)
• Homebrew Formulae: ollama (要出典: https://formulae.brew.sh/formula/ollama)
• Ollama OpenAI compatibility (要出典: https://docs.ollama.com/api/openai-compatibility / https://ollama.com/blog/openai-compatibility)

LLMリーダーボードの順位は、評価タスク・評価条件・指標の組み合わせ結果です。用途が一致するベンチマークと条件を確認できない場合は、比較結果を意思決定に使わないでください。

リーダーボードは「何を測っているか」を理解する

結論：リーダーボードは特定タスクの代理測定であり、用途が一致しない比較は結論を誤らせます。

ベンチマーク/指標/評価条件の違い

用語の役割は次のとおりです。(出典候補: L3)

• ベンチマーク: どのタスクを測るか
• 指標: どう採点するか
• 評価条件: どの設定で測るか
  これらが異なると、同じスコアでも意味が変わります。

用途適合と横断比較の分離

用途適合の確認が最優先です。横断比較は「用途と条件が一致する範囲」に限定します。

読む順序（最小手順）

1. 目的と用途を1行で定義する。
2. 目的に対応するタスク/ベンチマークを確認する。(出典候補: B1,B2,B3,C1,C2,M1,M2)
3. 評価条件と指標を確認する。(出典候補: L3)
4. 一致しない項目がある場合は比較を保留にする。

スコアが決まるプロセスを押さえる

結論：データセット、評価条件、採点方式の差がスコア差の主因です。

データセット設計（分割/難易度/更新）

分割や難易度、更新方針でスコアは変動します。(出典候補: B1,B2,B3,C1,C2,M1,M2)
同名ベンチマークでも版が違う場合は同一比較にしません。

評価プロトコル（ゼロショット/フューショット/実行環境）

ショット数、プロンプト形、実行環境が違うと結果は変わります。(出典候補: L3)

生成設定（温度/最大トークン/デコード）

温度・最大トークン・デコード方式の差は生成結果に影響します。(出典候補: L3)

採点方式（自動/人手/ルーブリック）

自動採点と人手評価では信頼性と再現性の扱いが異なります。(出典候補: L3)

確認すべき項目

• データセットの版と分割
• ショット数/プロンプト条件
• 生成設定（温度/最大トークン/デコード）
• 採点方式と評価者条件

評価指標の種類と得意領域を整理する

結論：指標はタスク依存のため、汎用スコアの単独比較は避けます。

正解一致・パス率系（QA/コード）

正答が明確なタスクで有効な指標です。(出典候補: L3)

生成品質系（評価者/ルーブリック）

評価者やルーブリックに依存するため、評価条件の透明性が重要です。(出典候補: L3)

推論/数学/安全性系

専用ベンチマークで評価されることが多く、指標の目的を確認する必要があります。(出典候補: B2,B3)

用途別ベンチマークの選び方

結論：用途ごとに代表ベンチマークを固定してから比較します。

用途別マッピング表（例）

Vellum と Artificial Analysis の読み方を比較する

結論：評価対象・集計・更新の違いを確認できない場合、順位比較は保留にします。

比較表（要約）

比較の最小手順

1. 評価対象とベンチマークが一致するか確認する。(出典候補: L1,L3,L4)
2. 評価条件（ショット数/生成設定/集計）が一致するか確認する。(出典候補: L1,L3,L4)
3. 一致しない場合は「保留」として別枠で扱う。

スコア差の解釈ルールを決める

結論：差が小さい場合の保留ルールを先に決めておきます。

スコア解釈チェックリスト

• 用途とタスクが一致している
• 指標定義が一致している (出典候補: L3)
• 評価条件（ショット数・プロンプト）が一致している (出典候補: L3)
• 生成設定が一致している (出典候補: L3)
• 集計方法が一致している (出典候補: L3)
• ばらつきや再現性の情報がある
• 汚染・リークの兆候がない (出典候補: R1)
• モデルのバージョン差を混同していない
• 非スコア要素（コスト/速度/安全性）を併記している
• 判断保留条件を明文化している

実務の選定手順（目的→指標→ベンチマーク→検証）

結論：目的から逆算して評価軸を固定すれば、スコア差の説明が可能になります。

手順

1. 目的を1行で定義する（例: コードレビュー補助）。
2. 重要要件を列挙する（コスト/速度/安全性/対応言語）。
3. 目的に対応する指標を決める。(出典候補: L3)
4. 指標に対応する代表ベンチマークを決める。(出典候補: B1,B2,B3,C1,C2,M1,M2)
5. 評価条件（ショット数/環境/生成設定/採点方式）を固定する。(出典候補: L3)
6. 自社タスクで小規模検証を設計する（期間/データ/評価者）。
7. 判断結果と理由をテンプレに記録する。

評価設計テンプレ（入力項目）

• 目的・用途
• 重要要件（コスト/速度/安全性）
• 対象タスク（具体例）
• 候補モデル
• 主要指標 (出典候補: L3)
• 代表ベンチマーク (出典候補: B1,B2,B3,C1,C2,M1,M2)
• 評価プロトコル（ショット数/環境/生成設定）
• 受け入れ基準
• 小規模検証の計画（期間/データ/評価者）
• 判断結果と理由

注意点とFAQ

結論：スコア至上主義を避け、非スコア要素も評価に含めます。

注意点

• スコア上位＝用途最適とは断定しない。
• リーダーボード間の単純順位比較は避ける。
• 出典なしで具体的な数値やランキングを提示しない。

FAQ
Q. リーダーボードの総合順位だけで選定してよい？
A. 用途と条件が一致しない場合は避けるべきです。用途、指標、評価条件の一致を確認してから判断してください。

Q. ベンチマークのスコア差はどれくらいで有意と見る？
A. 有意差は評価プロトコルと再現性の情報に依存します。差が小さい場合は保留ルールを適用してください。(出典候補: L3)

Q. 同じ指標名でも比較できないのはなぜ？
A. 指標定義や評価条件が違うと、同名でも意味が変わるためです。(出典候補: L3)

Q. マルチモーダルはどのベンチマークを見ればよい？
A. 目的タスクに近い評価タスクを含むベンチマークを選び、公式の評価条件を確認してください。(出典候補: B1,B2,B3,C1,C2,M1,M2)

Q. スコア以外で最低限見るべき項目は？
A. コスト、速度、安全性、運用条件（権限/ログ/監査）を最低限併記してください。

出典候補（sources_list）

• L1 https://www.vellum.ai/llm-leaderboard
• L2 https://www.vellum.ai/open-llm-leaderboard
• L3 https://artificialanalysis.ai/methodology
• L4 https://artificialanalysis.ai/leaderboards/models
• B1 https://arxiv.org/abs/2009.03300
• B2 https://arxiv.org/abs/2210.09261
• B3 https://ar5iv.labs.arxiv.org/html/2110.14168
• C1 https://ar5iv.labs.arxiv.org/html/2107.03374
• C2 https://arxiv.org/abs/2310.06770
• M1 https://arxiv.org/abs/2311.16502
• M2 https://ar5iv.labs.arxiv.org/html/2307.06281
• R1 https://arxiv.org/abs/2412.15194

ERR! Error: The package "esbuild-windows-64" could not be found, and is needed by esbuild.
ERR!
ERR! If you are installing esbuild with npm, make sure that you don't specify the
ERR! "--no-optional" flag. The "optionalDependencies" package.json feature is used
ERR! by esbuild to install the correct binary executable for your current platform.
ERR!     at generateBinPath (D:\Dropbox\04_Development\06_vent\node_modules\esbuild\lib\main.js:1643:15)
ERR!     at esbuildCommandAndArgs (D:\Dropbox\04_Development\06_vent\node_modules\esbuild\lib\main.js:1699:11)
ERR!     at ensureServiceIsRunning (D:\Dropbox\04_Development\06_vent\node_modules\esbuild\lib\main.js:1856:25)
ERR!     at Object.build (D:\Dropbox\04_Development\06_vent\node_modules\esbuild\lib\main.js:1749:26)
ERR!     at D:\Dropbox\04_Development\06_vent\node_modules\vite\dist\node\chunks\dep-85dbaaa7.js:42489:54
ERR!     at Array.map (<anonymous>)
ERR!     at scanImports (D:\Dropbox\04_Development\06_vent\node_modules\vite\dist\node\chunks\dep-85dbaaa7.js:42489:31)
ERR!     at processTicksAndRejections (node:internal/process/task_queues:96:5)
ERR!     at async optimizeDeps (D:\Dropbox\04_Development\06_vent\node_modules\vite\dist\node\chunks\dep-85dbaaa7.js:63029:30)
ERR!     at async runOptimize (D:\Dropbox\04_Development\06_vent\node_modules\vite\dist\node\chunks\dep-85dbaaa7.js:66901:48)
ERR!     at async createServer (D:\Dropbox\04_Development\06_vent\node_modules\vite\dist\node\chunks\dep-85dbaaa7.js:66930:9)
ERR!     at async Object.start (D:\Dropbox\04_Development\06_vent\node_modules\storybook-builder-vite\index.js:33:20)
ERR!     at async Promise.all (index 0)
ERR!     at async storybookDevServer (D:\Dropbox\04_Development\06_vent\node_modules\@storybook\core-server\dist\cjs\dev-server.js:123:28)
ERR!     at async buildDevStandalone (D:\Dropbox\04_Development\06_vent\node_modules\@storybook\core-server\dist\cjs\build-dev.js:112:31)
ERR!     at async buildDev (D:\Dropbox\04_Development\06_vent\node_modules\@storybook\core-server\dist\cjs\build-dev.js:154:5)
ERR!  Error: The package "esbuild-windows-64" could not be found, and is needed by esbuild.

開発サーバを起動する前に、npm rebuild esbuildを実行すると解決します。

docker-composeで起動する場合は、commandに追記してあげれば大丈夫でした。

version: '3'
services:
  app:
    command: sh -c 'npm rebuild esbuild && yarn dev'

参考記事

• reactjs : Vite Reactアプリ:Dockerコンテナのesbuildエラー
• Vite + Esbuild Docker issue #2671

スクロールの挙動を変更

スクロールの挙動を変更するには、基本的に以下の2つの方法があります。

• nuxt.config.js内のroute.scrollBehaviorプロパティ
• router.scrollBehavior.js (v2.9.0 ~ )

公式的には、router.scrollBehavior.jsを作成した方法を推奨しているようなので、今回はそちらの方法で設定を行っていきます。

※これらの設定は、Nuxt.jsが既に定義してあるデフォルトの設定を上書きする形になるので、注意が必要です。

router.scrollBehavior.jsの作成

プロジェクトのルートディレクトリ配下にappディレクトリを作成して、その中にrouter.scrollBehavior.jsを配置していきます。

// app/router.scrollBehavior.js
export default (to, from, savedPosition) => {
	return { x: 0, y: 0 }
}

このメソッドは、ページがレンダリングされる度に呼ばれます。メソッドの詳しい説明については、公式ドキュメントを参照してください。

Vue-Router-async-scrolling

単純にページ遷移時にスクロール位置を先頭にするには、上述したようにreturn { x: 0, y: 0 }を返却するだけでいいので、特にこだわりが無ければこれだけでも問題ないようにも思えます。

逆に固定レイアウトがある場合や、スムーススクロールを実装したい場合は少しこのファイルに手を加えてあげる必要があります。

// app/router.scrollBehavior.js
export default (to, from, savedPosition) => {
	return {
		selecter: to.hash,
		offset: { x: 0, y: 0 },
		behavior: 'smooth', // スムーススクロールの設定
	}
}

特定のアンカータグの遷移

Headless CMSから取得したコンテンツを利用する場合、nuxt-linkが使用できず普通のアンカータグになってしまうかと思います。この場合、アンカータグデフォルトの動作となってしまいscrollBehaviorがうまく動作してくれないことがあります。

この場合は、アンカータグのデフォルトの挙動を宣言して、vue-routerで遷移させることで解決します。

例えば、記事の目次としてこのようなアンカータグが存在するとします。

<div class="toc">
	<a href="#h1">H1</a>
	<a href="#h2">H2</a>
	<a href="#h3">H3</a>
</div>

これらのアンカータグに対して、preventDefault()を呼んであげて、その後vue-routerのpush()を呼んでページを遷移するといった形になります。

setup () {
	const router = useRouter()
	onMounted(() => {
		const tocs = document.querySelectorAll('.toc a[href^="#"]')
		for (let idx = 0; idx < tocs.length; i++) {
			tocs[idx].addEventListener('click', e => {
				e.preventDefault()
				router.push({ path: e.target.hash })
			})
		}
	})
}

エラー発生時の対応

DOMException: Failed to execute 'querySelector' on 'Document': '~~~' is not a valid selector.

日本語のハッシュをpushしたときに発生するエラーだと思います。パラメータの%E3とかが解決できなくて起きている模様ですね。こちらは、Nuxt.jsのデフォルトの設定を参考にhashをエスケープすることで解決することが可能です。

const hash = (() => {
  if (typeof window.CSS !== 'undefined' && typeof window.CSS.escape !== 'undefined')
    return `#${window.CSS.escape(to.hash.substr(1))}`
  return to.hash
})()

return {
	selector: hash,
}

TypeError: Cannot read properties of undefined (reading 'behavior')

デフォルトの設定を参考に色々触っていた際に、scrollBehaviorにasyncをくっつけていた時に発生したエラーです。

export default async (to, from, savedPosition) => {
	// ...
}

下記が、Vue-Routerのソースです。

router.app.$nextTick(function () {
  var position = getScrollPosition();
  var shouldScroll = behavior.call(
    router,
    to,
    from,
    isPop ? position : null
  );

  if (!shouldScroll) {
    return
  }

  if (typeof shouldScroll.then === 'function') {
    shouldScroll
      .then(function (shouldScroll) {
        scrollToPosition((shouldScroll), position);
      })
      .catch(function (err) {
        if (process.env.NODE_ENV !== 'production') {
          assert(false, err.toString());
        }
      });
  } else {
    scrollToPosition(shouldScroll, position);
  }
});

behavior.callの部分で定義したscrollBehaviorを呼び出しています。その後のIF文でshouldScrollオブジェクトは、asyncを付けているためPromiseと解釈されてしまいエラーが発生しているようでした。

解決策としては、asyncを使用するのをやめるか、Promiseオブジェクトを返却（試してはない）してあげればOKです。

参考文献

• Nuxt.js-scrollbehavior
• Nuxt.js-router.scrollBehavior.js
• 特定のアンカータグの遷移処理をrouter.pushでさせたい

前回までの記事

• React × DRFで画像アップロード機能作成 (環境構築編)
• React × DRFで画像アップロード機能作成 (フロント実装編)

実行環境

• Mac OS X 11.2.1
• Docker 20.10.5
• docker-compose version 1.28.5
• node v15.10.0
• npm 7.9.0
• react 17.2.0

コンテナに入る

今回は、server用のコンテナに入って作業をしていきます。下記コマンドを実行して、serverコンテナに入ります。

$ docker exec -it server bash

Django Projectの作成

コンテナに入ったら、まず初めにDjangoのProjectを作成していきます。下記コマンドで、Django Projectを作成します。

$ django-admin startproject server

上記コマンドを実行すると下記のようなファイルたちが生成されます。

server/
    manage.py
    server/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

Django Appの作成

Projectの作成が完了したら、続いてはAppの作成をしていきます。
下記コマンドで、Django Appを作成します。

$ python manage.py startapp api

上記コマンドを実行することで、apiというディレクトリを作成されます。

server/
    manage.py
    server/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py
		polls/
		    __init__.py
		    admin.py
		    apps.py
		    migrations/
		        __init__.py
		    models.py
		    tests.py
		    views.py

Djangoの開発サーバで確認してみる

正常にDjangoのファイルたちが作成されているか確認するために、Djangoが用意している開発サーバを立てて、確認をしてみます。下記コマンドを実行して、サーバを立てます。

$ python manage.py runserver 0.0.0.0:8000

サーバが立ち上がったら、ブラウザからhttp://localhost:8000/へアクセスします。

下記画面が表示されたら、確認は完了です。

ここまでの手順は、Djangoの公式サイトのチュートリアルに沿った形で実行しています。各コマンドの詳細が気になる方は、公式サイトを確認してみてください。

Django公式tutorial

実装

設定ファイルの修正

早速実装に移っていこうと思いますが、その前に実装を始める前の準備段階として設定ファイル等を修正していきます。

/server/server/settings.pyをエディターで開きます。

ALLOWED_HOSTS = ['*'] # 修正

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework', # 追記
    'api.apps.ApiConfig', # 追記
    'corsheaders', # 追記
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    'corsheaders.middleware.CorsMiddleware' # 追記
]

# 追記
CORS_ORIGIN_WHITELIST = (
    'http://localhost:3000',
)

LANGUAGE_CODE = 'ja' # 修正

TIME_ZONE = 'Asia/Tokyo' # 修正

# 追記
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

上記のようにsettings.pyを修正します。
※関係のない部分は省略しています。

mediaディレクトリの用意

上記のsettings.pyでMEDIA_URLとMEDIA_ROOTを定義しました。

こちらは、画像の保存先を指定しており、画像が保存されると指定したmediaディレクトリ内に保存しようとします。そのため、事前に空のmediaディレクトリを用意しておいてください。

ルーティングの設定

続いて、ルーティングの設定を行っていきます。まず、/server/server/urls.pyをエディターで開きます。

from django.contrib import admin
from django.urls import path, include
from django.contrib.staticfiles.urls import static
from . import settings

urlpatterns = [
    path('api/', include('api.urls')),
    path('admin/', admin.site.urls),
]

urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

次に、前回作成したapiアプリ内にurls.pyを作成して下記コードを記述します。

from django.db import router
from django.urls import path, include
from . import views
from rest_framework.routers import DefaultRouter

router = DefaultRouter()

urlpatterns = [
    path('image/', views.ImageFileView.as_view(), name='images'),
    path('', include(router.urls)),
]

これでルーティングの設定が完了しました。

流れとしては、example.com/api/imageというURLがあったとして、はじめに、server/urls.pyをみて、api/ というパスが存在するので、includeしてあるapi/urls.pyに飛びます。

そして、api/urls.pyでは、image/ というパスに対して、ImageFileViewというviewの処理へ促すようルーティングしています。

Viewの実装

先程のルーティングでimage/ に対してのルーティングが完了したので、このままimage/ が来たときのViewの処理を実装します。

/server/api/views.pyを編集します。

from django.shortcuts import render
from rest_framework import status, generics, permissions
from .models import *
from .serializers import *

class ImageFileView (generics.ListCreateAPIView):
    permission_classes = (permissions.AllowAny,)
    queryset = UploadFile.objects.all()
    serializer_class = UploadFileSerializer

ここでは、Django REST frameworkのgenerics.ListCreateAPIViewを使用してViewの処理を記述しています。

こちらのViewは、HTTPメソッドがGET or POST で来た場合、GET なら該当Modelのデータを返却し、POST なら、該当Modelにデータを登録してくれます。

詳しい仕様は、公式ドキュメントを参考にしてみてください。

該当Modelとは、後述するUploadFileModelになります。

Modelの定義

Viewの処理の実装が完了したので、続いてModelの定義を行っていきます。

from django.db import models
import os

def upload_image (instance, filename):
    return 'images/{0}/'.format(filename)

class UploadFile (models.Model):
    file = models.ImageField('画像ファイル', upload_to=upload_image)

    def __str__ (self):
        return self.file.url

    @property
    def filename (self):
        return os.path.basename(self.file.name)

ここでは、「file」名前のという画像専用のフィールドを用意しています。
upload_toには、データ登録時の保存先のパスを指定しています。
@propertyにて、新たに当Modelにプロパティを追加することで、画像名の取得を容易にしています。

Serializerの定義

続いて、Serializerを定義していきます。Serializerは、データの入出力を扱い、それをモデルに渡してくれるためのものです。

from rest_framework import serializers
from .models import *

class UploadFileSerializer (serializers.ModelSerializer):
    file = serializers.ImageField()
    file_name = serializers.SerializerMethodField()

    class Meta:
        model = UploadFile
        fields = '__all__'

    def get_file_name (self, obj):
        return obj.filename

migrationとmigrate

ここまでの実装が完了したら、Modelの変更点等を反映するために、一度マイグレーションとマイグレートを行います。

$ python manage.py makemigrations api
$ python manage.py migrate

動作確認

ここまでで、すべての実装は完了です。動作確認をするため、client、server両方のサーバを起動して、実際に画面からファイルをUploadしてみます。

無事にUploadが完了したら、server/media/imageディレクトリ内に、アップロードした画像が保存されていることが確認できるかと思います。

ディレクトリ構成

ここまでの作業が完了したら、下記のようなディレクトリ構成になっているかと思います。

├── client
│   ├── Dockerfile
│   └── img_uploader
│       ├── package.json
│       ├── public
│       │   ├── favicon.ico
│       │   ├── index.html
│       │   ├── manifest.json
│       │   └── robots.txt
│       ├── src
│       │   ├── App.css
│       │   ├── App.test.tsx
│       │   ├── App.tsx
│       │   ├── assets
│       │   │   └── image
│       │   │       └── upload_bg.jpg
│       │   ├── index.css
│       │   ├── index.tsx
│       │   ├── react-app-env.d.ts
│       │   ├── reportWebVitals.ts
│       │   └── setupTests.ts
│       ├── tsconfig.json
│       └── yarn.lock
├── docker-compose.yml
└── server
    ├── api
    │   ├── __init__.py
    │   ├── admin.py
    │   ├── apps.py
    │   ├── migrations
    │   │   ├── 0001_initial.py
    │   │   └── __init__.py
    │   ├── models.py
    │   ├── serializers.py
    │   ├── tests.py
    │   ├── urls.py
    │   └── views.py
    ├── db.sqlite3
    ├── manage.py
    ├── media
    │   └── images
    │       └── back_vOylmoT.jpg # アップロードされた画像ファイル
    └── server
        ├── __init__.py
        ├── asgi.py
        ├── settings.py
        ├── urls.py
        └── wsgi.py

実際のコードはこちらになります。

https://github.com/yoshihiko555/img-uploader

まとめ

今回は全３回に渡って、React × DRFを用いた簡単な画像アップロードアプリを作成してみました。拙い文章が多い中最後まで読んでくださった方には感謝です。

Django REST frameworkを用いることで、非常に簡単にRESTAPIの作成が可能です。Reactに関してはまだまだ、スキル不足な部分が多いので、もっと邁進していきたいと感じました。

前回までの記事はこちらです。

• React × DRFで画像アップロード機能作成 (環境構築編)

実行環境

• Mac OS X 11.2.1
• Docker 20.10.5
• docker-compose version 1.28.5
• node v15.10.0
• npm 7.9.0
• react 17.2.0

コンテナに入る

前回作成したclient用のコンテナが起動していること確認後、下記コマンドを実行して、client用のコンテナに入ります。

$ docker exec -it client sh

Reactアプリの作成

コンテナに入ったら、下記のコマンドを実行してReactのアプリを作成します。

$ cd client
$ npx create-react-app --template typescript

コマンドを実行すると、各ライブラリのインストールが始まります。インストールが完了すると、下記メッセージが出力されます。

We suggest that you begin by typing:

  cd img_uploader
  yarn start

Happy hacking!

開発用サーバを起動

アプリの作成が無事に完了しているか確認するために、一度開発用サーバを起動して確認します。

$ cd img_uploader
$ yarn start

サーバを起動したら、http://localhost:3000/に接続します。下記画面が表示されていれば、アプリの作成とサーバに起動は成功です。

ライブラリのインストール

次に、アプリ作成に必要なライブラリを別途インストールしていきます。

今回インストールするライブラリは下記になります。

• axios
• Material-UI
• react-dropzone

下記コマンドを実行して、ライブラリをインストールします。

$ yarn add axios @material-ui/core react-dropzone
$ yarn add -D @types/react-dropzone

機能概要

ライブラリのインストールが完了したら、早速フロント側の機能実装に移りたいと思います。今回作成するアプリの機能は以下のようなものになります。

• ドラッグアンドドロップで画像選択
• 「Selectボタン」でファイル選択
• 選択された画像のプレビュー
• 「Uploadボタン」でサーバに選択された画像を送信

実装

早速、実装に移ろうと思います。まずは、画面を描画しているApp.tsxの編集を行っていきます。

必要ライブラリのインポート

まずは、今回使用するライブラリをインポートしていきます。

import React, { useState, useCallback } from 'react'
import { makeStyles } from '@material-ui/core/styles'
import {
    Container,
    Card,
    CardContent,
    CardActions,
    Typography,
    Button,
} from '@material-ui/core'
import { useDropzone } from 'react-dropzone'
import './App.css';
import bg from './assets/image/upload_bg.jpg'
import axios from 'axios'

Material UIのデザインアレンジ

次に、前回インストールした画面のデザインを簡単に作ってくれるライブラリであるMaterial UIのデザインを少しアレンジしていきます。

Material UIの詳しい使用方法は、公式ドキュメントを参照してください。

const useStyles = makeStyles({
    root: {
        minWidth: 300,
        position: 'absolute',
        top: '50%',
        left: '50%',
        transform: 'translate(-50%, -50%)'
    },
    title: {
        textAlign: 'center',
    },
    subtitle: {
        textAlign: 'center',
    },
    actions: {
        justifyContent: 'center',
    }
})

コンポーネントの作成

実際に描画されるコンポーネントの作成を行っていきます。

// Dropzoneの設定
const acceptFile = 'image/*'

type MyFile = File & {
    preview: string
}

const App:React.FC = () => {

    // Style
    const classes = useStyles()

    // State
    const [isShow, setIsShow] = useState(false)
    const [files, setFiles] = useState<MyFile[]>([])

    // ドロップした時の処理
    const onDrop = useCallback((acceptedFiles: File[]) => {
        setIsShow(true)

        setFiles(acceptedFiles.map(
            file => Object.assign(file, {
                preview: URL.createObjectURL(file)
            })
        ))
    }, [])

    // Dropzone
    const { getRootProps, getInputProps, isDragActive, open }
        = useDropzone({ noClick: true, onDrop, accept: acceptFile })

    const upload = () => {
        const data = new FormData()
        files.forEach(file => data.append('file', file))
        axios.post('http://localhost:8000/api/image/', data)
        .then(res => {
            console.log(res)
            setIsShow(false)
            setFiles([])
        })
        .catch(e => {
            console.log(e)
        })
    }

    return (
        <Container maxWidth="sm">
            <Card className={classes.root}>
                <CardContent>
                    <Typography variant='h6' component='h2' className={classes.title}>
                        Image uploader
                    </Typography>
                    <Typography component='p' color='textSecondary' className={classes.subtitle}>
                        drag & drop
                    </Typography>
                    <div {...getRootProps({ className: 'dropzone' })}>
                        {isShow ? (
                            files.map(file => (
                                <img key={file.name} src={file.preview} alt={file.name} width='200' />
                            ))
                        ) : (
                            <img src={upload_bg} alt='bg' className={'upload_img ' + (isDragActive ? 'is-on' : '') } width='200' />
                        )}
                        <input {...getInputProps()} />
                    </div>

                </CardContent>

                <CardActions className={classes.actions}>
                    <Button
                        size='small'
                        color='primary'
                        variant='contained'
                        component="span"
                        onClick={open}
                    >Select</Button>
                    {isShow && (
                        <Button
                            size='small'
                            color='primary'
                            variant='contained'
                            component='span'
                            onClick={upload}
                        >Upload</Button>
                    )}
                </CardActions>
            </Card>
        </Container>
    )
}

export default App;

useStyles()

const classes = useStyles()

ここでは、上で定義したMaterial UIのデザインのアレンジするための関数を実行して、その戻り値をclassesに格納することで、デザインを適用するための処理です。

実際に、デザインを適用するためには、下記のようにclassNameに適用させたいクラス名を定義します。

<Card className={classes.root}>

usState()

useState関数を使用して、コンポーネント内での状態管理を行います。useStateは下記のようにして使用します。

const [変数, set変数] = useState(初期値)

今回は、画像が選択された際に、画面の表示を切り替えるためのフラグをここで管理しています。

const [isShow, setIsShow] = useState(false)
const [files, setFiles] = useState<MyFile[]>([])// ドロップした時の処理
    const onDrop = useCallback((acceptedFiles: File[]) => {
        setIsShow(true)

        setFiles(acceptedFiles.map(
            file => Object.assign(file, {
                preview: URL.createObjectURL(file)
            })
        ))
    }, [])

// ...

// isShowがFalseなら、デフォルトで表示するべき画像を表示しています。
{isShow ? (
    files.map(file => (
        <img key={file.name} src={file.preview} alt={file.name} width='200' />
    ))
) : (
    <img src={upload_bg} alt='bg' className={'upload_img ' + (isDragActive ? 'is-on' : '') } width='200' />
)}

ドラッグアンドドロップの処理

react-dropzoneというライブラリを使用して、コンポーネントの一部のエリアにドラッグアンドドロップをすることによって、画像を選択させるといった処理が可能になります。

// ドロップした時の処理
const onDrop = useCallback((acceptedFiles: File[]) => {
		// 
    setIsShow(true)

    setFiles(acceptedFiles.map(
        file => Object.assign(file, {
            preview: URL.createObjectURL(file)
        })
    ))
}, [])

// useDropzone実行時に渡しているプロパティについて
// noClick: trueを渡すことで、ドラッグアンドドロップでのみ画像選択を許可する
// onDropを渡すことで、ドラッグアンドドロップ時に、実行する関数を指定できる
// Dropzone
const { getRootProps, getInputProps, isDragActive, open }
    = useDropzone({ noClick: true, onDrop, accept: acceptFile })

// ...

<div {...getRootProps({ className: 'dropzone' })}>
    {isShow ? (
        files.map(file => (
            <img key={file.name} src={file.preview} alt={file.name} width='200' />
        ))
    ) : (
        <img src={upload_bg} alt='bg' className={'upload_img ' + (isDragActive ? 'is-on' : '') } width='200' />
    )}
    <input {...getInputProps()} />
</div>

API呼び出し

Uploadボタンを押した時に、このあと作成するAPIを呼び出すための処理の実装を見ていきます。

{isShow && (
  <Button
      size='small'
      color='primary'
      variant='contained'
      component='span'
      onClick={upload}
  >Upload</Button>
)}

const upload = () => {
    const data = new FormData()
    files.forEach(file => data.append('file', file))
    axios.post('http://localhost:8000/api/image/', data)
    .then(res => {
				// API成功時の処理
        console.log(res)
        setIsShow(false)
        setFiles([])
    })
    .catch(e => {
        console.log(e)
    })
}

uploadボタンは、isShowフラグがtrueのときのみ表示され、ボタンを押下した時にupload関数が実行されます。

upload関数では、選択されたファイルをFormDataに格納していき、それをAxiosを使用して、APIを実行しています。

APIの処理が成功したときは、.then の処理に入りisShowフラグを折り、選択ファイルを空にしています。

デザインを整える

App.tsxの実装が完了したら次は、CSSで細かいデザインを整えて行きます。

body {
    background-color: #eee;
}

.upload_img {
    display: block;
    margin: 20px auto;
    border-style: dashed;
    border-radius: 10px;
    border-color: #7c88cb;
}
.upload_img.is-on { opacity: .7; }
.hidden { display: none; }

img {
    display: block;
    margin: 20px auto;
}

動作確認

ここまで実装が済んだら、実際に画像をドラッグアンドドロップしてみます。

選択した画像がプレビューされることが確認でき、Uploadボタンが表示されたら一先ずOKです。

まとめ

今回は、ドラッグアンドドロップで画像を選択して、選択された画像をプレビューするところまで実装しました。次回は、Uploadボタンを押下時に受け取るサーバ側の処理を実装していこうと思います。

実行環境

• Mac OS X 11.2.1
• Docker 20.10.5
• docker-compose version 1.28.5

作業ディレクトリの用意

今回のアプリを開発するための作業ディレクトリを用意していきます。

ディレクトリ構成は下記のようにします。

└── sample
    ├── client
    └── server

イメージの作成

まず手始めに、今回のアプリを作成していくにあたりDockerのイメージを作成していこうと思います。Dockerのインストールがお済みでない方は、下記の記事からDockerをインストールをしてから進めていただくと幸いです。

各OS毎のDockerインストール手順

Dockerfileの用意

今回は、クライアントはReact、サーバはDjango REST frameworkを使用していこうと思います。それぞれの環境を構築するために、Dockerfileを用意していこうと思います。

client用Dockerfile

clientのディレクトリにDocekrfileという名前のファイルを作成して、下記の内容を記述してください。

FROM node:15.10.0-alpine3.11

WORKDIR /usr/src/app

server用Dockerfile

serverのディレクトリにもclientと同様にDockerfileという名前のファイルを作成して、下記の内容を記述します。

FROM python:3

ENV PYTHONUNBUFFERED 1

RUN apt update
RUN apt install -y --no-install-recommends \
	net-tools \
	sudo \
	bzip2 \
	curl \
	gcc \
	python3-dev \
	vim
RUN apt clean

RUN pip install --upgrade pip
RUN pip install \
	django \
	djangorestframework \
	djangorestframework-jwt \
	django-filter \
	django-environ \
	django-cors-headers \
	gunicorn \
	Pillow

docker-compose.ymlの用意

次に、複数コンテナを管理するためにdocker-composeを使用するために、docker-compose.ymlを用意していきます。

sampleディレクトリ直下にdocker-compose.ymlという名前のファイルを用意して、下記の内容を記述します。

version: '3'
services:
    client:
        build: ./client
        image: client-image
        container_name: client
				environment:
            - NODE_ENV=production
        ports:
            - '3000:3000'
        volumes:
            - ./client/:/usr/src/app/
        tty: true

    server:
        build: ./server
        image: server-image
        container_name: server
        ports:
            - '8000:8000'
        volumes:
            - ./server/:/usr/src/app/
        tty: true

ここまでディレクトリ構成は以下のようになっています。

└── sample
		├── client
		│   └── Dockerfile
		├── docker-compose.yml
		└── server
		    └── Dockerfile

コンテナの作成

上記の手順で用意した、Dockerfileたちをもとに、実際に稼働するコンテナを作成していきます。

下記のコマンドで、Dockerイメージのビルドと、コンテナの起動を行っていきます。

$ docker-compose up -d --build

上記のコマンドを実行すると、Dockerイメージのビルドが始まり、ビルドが成功すると自動でコンテナが起動します。下記のメッセージが出力されればOKです。

Successfully built 593c766c576516137e385bb2ddeff448bdc53d546d642059be900350d3b74011
Starting client ... done
Starting server ... done

実際にコンテナが起動しているか確認

下記コマンドを実行して、コンテナが起動しているか確認します。

$ docker-compose ps

Name             Command            State           Ports         
-------------------------------------------------------------------
client   docker-entrypoint.sh node   Up      0.0.0.0:3000->3000/tcp
server   python3                     Up      0.0.0.0:8000->8000/tcp

StateがUpとなっていれば、コンテナは無事起動しています。ここまでで、アプリを作成するための環境構築は完了です。

次回は、クライアント側であるReactのプロジェクトを作成して、画面側の準備をしていこうと思います。

Dockerとは

Dockerをインストールする前に、簡単にDockerとは何かを説明しておきます。Dockerとは、仮想化技術の一つである、「コンテナ型」の仮想化技術を提供するための、オープンソースソフトウェアです。

コンテナ化したアプリケーションを、作成・配布・実行を、簡単に実現することが出来、開発や運用等を効率的に行うことが出来ます。

各OS毎のDockerインストール手順

macOS

macOSにて、Dockerをインストールする方法は、２通り存在します。

1. 公式サイトからDocker Desktop for Macをインストール
2. Homebrewを使用してインストール

公式サイトからインストール

Docker公式サイト Get Startedへアクセスして、Dockerをインストールします。Get Startedから、ご自身の環境にあったインストーラーをインストールします。

ダウンロードした「Docker.dmg」を実行し、Docker Desktop for Macのインストールを開始します。実行完了後、Docker.appをApplicationディレクトリにコピーします。

インストールが完了したら、Docker.appを起動してDockerを起動します。
無事に起動が出来ていれば、ツールバーのクジラアイコンをクリックすると、
「Docker Desktop is running」と表示されます。

Homebrewを使用してインストール

DockerをHomebewを使用してインストールする場合は、下記のコマンドを実行するだけでOKです。

$ brew install --cask docker

参考文献として、Homebrewのページがこちらです。

Windows

公式サイトからインストール

公式サイトからOSに対応するインストーラーをダウンロードするところまでは、macOSと同様です。

ダウンロードした「Docker Desktop Installer.exe」を実行すると、自動的にDockerのインストールが始まります。インストールが完了すると、下記の画面が出てくるので、そのまま「Close」を押して画面を閉じます。

無事に起動が完了すると、右下のタスクバーにクジラアイコンが表示されます。

公式によると、ゴミ箱機能はアーカイブ機能のように動かすことを想定しているからだそうです。
必要なときにいつでも削除・復元が出来るから便利でしょってことなんだろうと思います。

ただ、実際にはゴミ箱に溜まったノートを一括で削除した場面は多いと思います。そこで、Andrew Wangさんが提供しているPythonのスクリプトを実行して、Notionのゴミ箱の一括削除を行います。

notion-clear-trash

こちらのスクリプトですが、非公式の内部APIを使用したものとなっておりますので、使用する際はご注意ください。

アクセストークンの取得

APIとの通信には、Notionが発行しているアクセストークンを使用します。

Fast Notionなどを使用している方は既にご存じかもしれません。

1. WebブラウザでNotionを開き、DevToolsを起動

お使いのWebブラウザからNotionを開きログインします。
ログインが完了したら、DevToolsを起動します。

• Windowsの方は、F12 または、Ctrl + Shift + I
• Macの方は、Option + Command + I

2. アクセストークンのコピー

DevTools上の、Application タブ > Storage > Cookies > token_v2 を探して、value をコピーします。

スクリプトの実行

次にPythonのスクリプトを実行していきたいのですが、現時点で提供されているコードでは、Notion側のAPIの形式に変更があったようで、実行してもエラーが出力されてしまいます。
なので、エラーを解消したものを用意したのでそちらを実行していきます。

ファイルのDLはこちらから行ってください。

yoshihiko555/notion-clear-trash

DLが出来たら、CLIからnotion-clear-trash.pyを実行してください。

実行すると、Please enter your auth token: と出力されるので、先ほどコピーしたアクセストークンを張り付けてもらえれば、スクリプトが起動し、お使いのNotionのゴミ箱が一括で削除されます。