はじめに

普段の開発では Claude Code をメインに、Codex CLI や Cursor などを併用して毎日触っています。

毎日使っているうちに、「こうすると出力が安定する」「ここは気をつけないと事故る」「これは習慣にしておいてよかった」というのが少しずつ溜まってきました。この記事はそれを一回棚卸しした内容です。

特別なことはやっていません。公式が用意している機能を素直に使うのと、ちょっとした運用上の工夫の積み重ねがほとんどです。なにか刺さるものがあれば、くらいの気持ちでまとめます。

棚卸ししてみると、やっていることは結局 「AI との認識のズレを減らす」「毎回の繰り返しを仕組みに逃がす」「文脈をツールの外に残す」 の 3 つに集約されていました。記事も、前半でふだんの作業の進め方を流れに沿って、後半でそれを支える環境づくりと、まだ試行錯誤中の工夫を、という順で書いていきます。

ふだんの作業の進め方

ここは要件 → 設計 → 実装 → セッションの区切り、という普段の流れに沿って並べています。通底しているのは「コードを書く前に AI とのズレを潰し、書いた後は続きやすい形で区切る」という意識です。

AI には、人に依頼するときと同じだけ情報を渡す

これは新しい話ではないんですが、改めて意識し直したのがこれでした。

普段の仕事で「こういう機能作って」と大雑把に依頼されたとき、たぶん動くものは出せるけど、依頼した人が頭の中で描いていたものとはちょっと違うものが出る、ということがあります。お互いの認識がずれていて、実装の途中でそれが見えてくる、という流れになりがちです。

AI もまったく同じだなと思っていて、「これってできる？」と聞けば「できます」と返ってきてコードも書く。動く。でも自分が思っていた完成形とは微妙にズレている、というのがよくあります。

これは AI が悪いわけじゃなくて、こちらが渡した情報の範囲で AI は忠実に作ってくれているだけです。ズレを減らしたいならこちらが情報を増やすしかない、というだけの話でした。

特に実装フェーズでは「どれだけ情報を渡すか」を意識するようにしています。具体的には、

期待する入出力や、簡単なテストケース（「X を渡したら Y を返す」）
「既存の〇〇ファイルと同じ構造で」のような参考パターン
「このファイルだけ」「この機能の範囲だけ」というスコープの線引き
バグ修正なら、症状・再現手順・「直った」と言える条件

人の場合は、要件や仕様を書いたり、わからないことは事前に確認したりを自然にやっているのに、AI を相手にすると「すぐ書いてくれそうだから」と省きたくなる。省いた分だけ後でやり直しになります。ここがたぶん一番、出力の質に効くポイントだと思います。

設計はプランモードと grill でズレを潰す

情報の渡し方とセットで習慣にしているのが、プランモードを使うことです。

実装をいきなり始めさせず、まず「どう作るつもりか」を出させて、自分でレビューする。ここで認識のズレに気づければ、コードを書く前に直せます。書いてしまった後に方針が違うと分かると、まるごとやり直しになるので、その手前で止めておく感覚です。

特に 3 ステップ以上に分かれそうなタスクは、ほぼプランモードから入ります。プランを見て「あ、ここ意図と違うな」が分かるだけで十分元が取れていて、結果的にこれが一番手戻りを減らしている気がします。

最近はこれに加えて、プランを「質問攻め」にしてもらうこともやっています。grill-me / grill-with-docs というスキルを使っていて、これは Matt Pocock 氏が公開しているスキル集に含まれているものです。

ざっくり言うと、プランモードが「AI が案を出す → 自分がレビューする」だとすると、grill 系は逆向きです。AI が設計ツリーを一つずつ辿りながら、まだ決めていない部分・曖昧な部分を一問ずつ質問してくる。答えているうちに「あ、ここ自分でも決めきれてなかったな」が炙り出されるのが面白いところです。

grill-me: 対話だけ。プランや設計をひたすら質問されて、認識をすり合わせる
grill-with-docs: 同じく質問されつつ、確定した用語や決定事項をその場で CONTEXT.md（用語集）や ADR に書き出してくれる。後から「あの用語どっちの意味だっけ」がなくなる

プランモードがコードを書く前のズレ潰しだとすると、grill 系はさらにその手前、「そもそも自分の頭の中が固まっているか」のズレ潰しです。質問されないと自分が曖昧にしていた箇所には気づけないので、ここを言語化させられるだけで設計の精度が上がる感覚があります。

設計を詰める時間は、エージェントを増やさず Claude Code と 1 対 1 で話すようにしています。思考の一貫性が崩れる方がデメリットが大きいので、ここはあえて 1 対 1 を守る、という使い分けです（grill 系もこの 1 対 1 の対話と相性がいいです）。手戻りが減るぶん無駄なトークン消費も抑えられて、利用上限の中で長く作業を続けられるのも地味な利点です。

実装はマルチエージェント＋複数 AI で進める

設計が固まった後の実装フェーズは並列化しています。設計が決まっていれば作業を分担できるので、ここで初めてマルチエージェントが効いてきます。

やり方はシンプルで、固まった設計をもとに、独立して進められる作業を複数のサブエージェントに割り振って同時に走らせる、という形です。同じファイルを同時に触らせると上書き事故が起きるので、影響範囲が大きいときは git の worktree を使って作業ツリーごと分け、別々のディレクトリで走らせます。重い探索や試行錯誤もサブエージェントに渡してしまえば、メインの会話のコンテキストが汚れないのも利点です。

もう一つ習慣にしているのが、複数の AI を併用することです。Claude Code をメインにしつつ、Codex CLI には設計の見直しやコードレビューを任せています。同じタスクを両方に投げて競わせる、というより、Claude Code が組み立てた設計や書いたコードを Codex に読ませて違和感を出してもらう、という分業に近いです。

実装と同じモデルにレビューさせると、同じ思考の癖を見落とすので、別モデルに見させたほうが指摘の質が上がる、というのが今のところの肌感です。人間でも、自分が書いたコードのレビューより他人のコードのレビューの方がアラが見えるのと同じだと思っています。

ツールをまたぐと「さっき向こうで何の話をしていたか」が分からなくなりがちなので、各ツールの会話の要点を 1 箇所にまとめておくと引き継ぎが楽になります。

/compact と /clear をタイミングで使い分ける

長いセッションをやっているとコンテキストが膨れて、挙動が不安定になってきます。そこで使うのが /compact と /clear です。

/compact: 同じ作業を続けたいけど、コンテキストが重い。要約だけ残して続きをやる
/clear: 作業のテーマが切り替わる。前の文脈を引きずると逆効果なので、いったん全部捨てる

タイミングの目安は「ここで一旦昼休みに入って、戻ってきてから続きをやりたいな」と思った瞬間。同じ作業を継続したいなら /compact、別タスクに切り替えるなら /clear、という分け方です。

どちらの場合も、「過程」は消えていいけど「結論」は別ファイルに残しておくようにしています。設計プランやその日の作業ログを Markdown に書き出しておけば、今日中に終わらなくても翌日そのファイルを読み直すだけで続きから入れます。「昨日どこまでやったっけ」を記憶でやらなくていいのが地味に大きいです。/clear は最初こそ捨てるのが怖かったんですが、結論さえ残してあれば思い切って打てます。

環境づくりと、まだ試行錯誤中の工夫

ここからは、よく使う指示や手順をコマンド・スキル・Hook などにまとめて、Claude Code を自分の作業に合わせて組み立てていく話です。

公式の拡張ポイント（Skill / コマンド / Hook / Subagent / MCP）を素直に使う

毎日使っていて地味に一番効いているのが、たぶんこれです。

Claude Code と Codex には、Skill / Slash Command / Hook / Subagent / MCP といった拡張ポイントが用意されています（ツールによって名前や揃っている範囲は少し違います。最初は名前だけ知っている状態でなんとなく使っていたんですが、一つずつドキュメントを読んで実際に触ってみる時間を意識的にとるようにしました。凝った独自コマンドを作り込む、という話ではなく、まず公式の機能を一通り把握して素直に使う、というだけです。

ざっくりした個人的な理解はこんな感じです。

Skill: 「この状況のときだけ読んでほしい前提」を切り出す場所。CLAUDE.md（Codex なら AGENTS.md）のような常時読み込まれるファイルに全部書くと重くなるので、機能別に分けて置いておく（前半で使った grill も、この Skill の一つです）
Slash Command: 毎回同じ前置きを打っているな、と気づいたら、それをコマンドにまとめてしまう
Hook: 特定の操作の前後に処理を挟む仕組み。「やってはいけない操作を自動でブロックする」「修正後に自動で lint をかける」のように、人間が毎回気をつけなくていいようにする用
Subagent: メインの会話に入れたくない作業（大量のファイルを読む探索、レビューだけやらせる、など）を別コンテキストに逃がす用。自分で定義を作らなくても、組み込みのサブエージェントがデフォルトで動くので、実装フェーズの並列化もまずはこれで足りる。自作するのは、使えるツールを絞りたい・専用の役割やシステムプロンプトを持たせたい・モデルを固定したい・特定の作業で自動的に呼ばせたい、みたいに何かしらカスタムが必要になったときだけでいい
MCP: AI を外部のデータやツールにつなぐ仕組み。ライブラリの公式ドキュメント取得やコードのシンボル単位検索といった「読む」系だけでなく、Notion・ブラウザ操作（Playwright）のように外部サービスを「操作する」系まで任せられる。回答の根拠が現物に紐づいて嘘が減り、AI の作業範囲がエディタの外まで広がるのが効いている

なかでも Hook は最近よく使うようになりました。使い方は大きく 2 つで、「毎回やってほしいことを自動で挟む」のと「やってほしくないことを止める」です。前者はたとえば「コードを修正したら lint やテストを自動で回す」。毎回「直したらテスト流しておいて」と口頭でお願いしてもいいんですが、こちらも言い忘れるし、AI 側も忘れることがあります。Hook にしておけば編集が入るたびに勝手に走るので、誰も覚えていなくても毎回確実に実行される。後者は、触ってほしくない操作や禁止したいコマンドをブロックしておく使い方で、AI がうっかり実行しようとしても止められます。どちらも共通しているのは、「毎回お願いする・毎回気をつける」を仕組みに変えられること。人間の注意力に頼らなくてよくなるのが Hook の良さだと思います。

履歴から「スキル化・フック化したほうがいいこと」を AI に提案させる

拡張ポイントを「使う」だけでなく、「そもそも何を拡張ポイントにすべきか」自体を AI に見つけてもらえないか、と最近試しているのがこれです。

毎日 AI と作業していると、

毎回同じことを言っている（同じ前提、同じ注意）
毎回同じコマンドを禁止している
毎回同じコマンドを実行している

みたいな「繰り返し」が必ず出てきます。これって本来、Skill や Hook、コマンドにまとめてしまえば毎回言わなくて済むはずのものです。でも、作業に集中していると「あ、これ繰り返してるな」と気づくこと自体が難しい。

そこで、1 週間くらいの単位で、AI 自身のメモリや会話履歴を AI に振り返らせて、「これは Skill にしたら？」「これは Hook で自動化したら？」と提案してもらう、ということを探り探りやっています。

毎回手で言っている前提 → Skill にする候補
毎回禁止しているコマンド → Hook でブロックする候補
毎回実行しているコマンド → コマンド化・自動化する候補

人間が「最近よく繰り返してるもの」を思い出すのは苦手ですが、履歴という記録が残っていれば、そこから拾うのは AI が得意な作業です。自分の作業のクセを AI に棚卸ししてもらって、面倒な部分を仕組みに変えていく、というイメージです。

まだ仕組みとして固まっているわけではないんですが、「繰り返しに気づく」を人間の記憶力に頼らない形にできそうな手応えはあります。

Obsidian を「外部記憶」にする

セッションをまたいでも、ツールをまたいでも消えない「結論の置き場所」をどこにするか。さっきの /clear で結論を別ファイルに残す話や、ツール間の引き継ぎの話とつながる部分です。最近は、設計ドキュメントや作業ログ、案件ごとのナレッジを Obsidian にまとめるようにしています。

Obsidian は、Markdown 形式でメモを書けるアプリです。データは基本的に自分の PC にローカル保存され、リンクでつないで「知識のネットワーク」を作っていけるのが特徴です。中身はただの Markdown ファイルなので、AI に渡すのとも相性がいい。

これが効くのは、AI に渡す前提を Obsidian 側で先に整えておけるからです。案件の前提や決定事項をきれいに書いておけば、Claude Code にも Codex にも同じ前提を共有できる。ツールをまたいでも「言ったこと・言わないこと」がぶれにくくなります。AI のメモリ機能や会話履歴はそのツールの中に閉じていますが、Obsidian に出しておけばツールの外側の「外部記憶」として、どの AI からでも参照できる状態になります。

おわりに

書きながら整理してみると、最近やり方を変えたのはこのあたりでした。

ふだんの進め方で変えたこと：

AI に対しても、人に依頼するときと同じくらい情報を渡す（特に実装フェーズ）
設計はプランモードと grill で、コードを書く前にズレを潰す
実装はマルチエージェント＋複数 AI で並列化。レビューは別モデル（Codex）に任せる
/compact と /clear をタイミングで使い分け、結論は別ファイルに残す

環境づくりで変えた・試していること：

Skill / コマンド / Hook / Subagent / MCP という公式の拡張ポイントを調べて素直に使う
履歴からスキル化・フック化のネタを AI 自身に提案させる（試行錯誤中）
Obsidian を AI の「外部記憶」にする（試行錯誤中）

派手なことはやっていなくて、どれも「ちょっとした工夫」レベルです。冒頭にも書いたとおり、結局は 「ズレを減らす」「繰り返しを仕組みに逃がす」「文脈を外に残す」 の 3 つを、いろんな場面で繰り返しているだけ、とも言えます。ただ、毎日触っているツールなので、こういう小さい工夫の積み重ねが結構効いてきます。

もう一つ、テクニックというより心構えの話を。AI を中心に作業するようになってから、自然と PC の中のファイルを整理するようになりました。AI に迷わず動いてもらうには、どこに何があるかがはっきりしている必要があるからです。これは人間が探すときと同じで、AI のために整理したつもりが、自分の頭の中まで整理されます。この「整理する習慣」がついたことが、地味だけど一番大きい変化だったかもしれません。

長くなりましたが、このうちひとつでも、明日の作業から試せそうなものがあれば嬉しいです。

参考リンク・引用元

mattpocock/skills（grill-me / grill-with-docs）
Claude Code 公式ドキュメント
Codex CLI（openai/codex）
Cursor
Model Context Protocol（MCP）
Playwright MCP（microsoft/playwright-mcp）
Architecture Decision Records（ADR）
Obsidian