はじめに
AIエージェントは初期状態でも十分に動きます。
一方で、他人の設定をそのまま導入すると、何が効いているのか理解できず、最終的に使いこなせなくなることがあります。
そのため、最初から設定を作り込むのではなく、実際の利用で発生した「摩擦」を観測しながら段階的に拡張していくのが良いと考えています。
自分の行動や指摘から改善点を抽出し、それを設定に反映していくと、設定は自分の思考と一致し始めます。
この「観測 → 改善 → 反映」のループを回すことで、AIエージェントは単なるツールではなく、自分の作業スタイルに適応した環境へと変わります。
本記事では、Claude Code を例に、この改善ループを前提とした最小構成と、その回し方を整理します。
なぜ「全部入り設定」は失敗するのか
多くの記事では、完成された設定やテンプレートの導入が紹介されていますが、実際には、これらは高確率で形骸化します。
主な理由は以下の通り。
- 設定の意図が理解できない
- どの設定が効いているのか分からない
- 想定外の動作が起きたときや、期待した動作をしなかったときに原因を追えない
- 使わないルールが蓄積してノイズになる
- 結果として、設定は「あるだけのもの」になり、使われなくなる
- 理解できない設定は、必ず運用から外れる
基本戦略：最小構成から始める
最初にやるべきことは、設定を増やすことではなく、設定を最小限にすること。
最小構成の例
- hooks: 「観測用途」に限定
- skills: 改善候補を整理し、最小の変更案として扱うために 1 つだけ用意する
- CLAUDE.md: 必須ではない。繰り返しが見えてから追加する
- subagent: 最初は使わない
ここで重要なのは、最初から最適化しようとしないこと です。
なぜなら、最適化は、実際の利用からしか生まれないためです。
改善ループの設計
Claude Codeを使う上で最も重要なのは、このループを回すことです。
利用 → 摩擦発生 → 観測 → 改善候補抽出 → 設定反映 → 利用
-
利用
通常通りClaude Codeで作業する。 -
摩擦発生
以下のような状態が発生する。- 同じ指摘を何度もしている
- 毎回同じ修正をさせている
- 出力の形式が安定しない
- タスク後に追加指示が発生する
-
観測
hooksを使って、タスク完了時にログや指摘内容を収集する。
ここでは重い処理は不要。軽量モデル（例：haiku）で十分。 -
改善候補抽出
観測データから、以下のようなパターンを抽出する。- 繰り返される指摘
- 一貫した修正パターン
- 作業フローの癖
-
設定反映
抽出された改善候補をもとに、設定を更新する。
ここで重要なのは、「自動で反映しすぎないこと」。
必ず人間が採用判断を行う。
改善の単位を決める
すべてを設定に反映すると破綻するため、明確な基準が必要です。
改善候補の基準
- 1回の不満 → 無視
- 2〜3回繰り返し → 改善候補
反映先の判断
- 明文化できるルール → CLAUDE.md
- 手順として再利用可能 → skills
- 役割分離が必要 → subagent
Before / After の具体例
例1：出力形式のブレ
Before
- 毎回「結論から書いて」と指摘している
- 出力の構成が安定せず、毎回微修正が必要になる
After
- CLAUDE.md に出力方針を追加
- 再指示が減り、出力のブレを抑えやすくなる
例2：レビュー後の手戻り
Before
- 毎回 lint / test / 差分説明を追加で依頼している
- タスク完了後に同じ後処理が発生している
After
- レビュー補助の skills を追加
- 再指示が減り、出力のブレを抑えやすくなる
改善ループを回すための最小 hooks 構成
最初は hooks を広く仕込む必要はありません。
まずはタスク完了時だけを対象にして、改善候補の観測に限定するのが扱いやすいです。
ここで重要なのは、hooks を「自動で設定を書き換える仕組み」にしないことです。
hooks の役割は、利用中に発生した摩擦や繰り返しの指摘を拾い、改善候補として整理することにあります。
設定を反映するかどうかは、最後までユーザが判断します。
そうすることで、設定が自分の手を離れず、何をどう変えたのかを把握したまま運用できます。
最小 hooks 構成のフロー
タスク完了
↓
hooks 発火
↓
「繰り返し指摘」「出力のブレ」「毎回の追加依頼」を抽出
↓
CLAUDE.md / skills / subagent のどこに反映すべきかを提案
↓
必要なら改善 skill（ここでは例として /improve-config という名前）を実行
0. ディレクトリ構成
プロジェクト単位で共有したいなら projectRoot/.claude/settings.json、個人全体で使いたいなら ~/.claude/settings.json に置きます。
.claude/
├─ settings.json # hooks の設定
└─ skills/ # skills の設定
└─ improve-config/
└─ SKILL.md
1. hooks の発火設定
発火タイミングは、まずはタスク完了時だけで十分です。
途中のすべてのイベントを拾い始めると、
- ノイズが増える
- 分析対象がぶれる
- 改善候補の粒度が揃わない
といった問題が起きやすくなります。
そのため、「完了したタスクを振り返る」ための1箇所だけに絞る方が運用しやすいです。
hooks の設定例
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "prompt",
"timeout": 20,
"prompt": "あなたは Claude Code の設定改善候補を見つけるための軽量チェッカーです。\n\n以下の文脈を読み、会話の中に「繰り返し発生している摩擦」があるかどうかだけを判定してください。\n\n文脈:\n$ARGUMENTS\n\n判定対象:\n- 同じ指摘を何度もしている\n- 毎回同じ修正を追加で依頼している\n- 出力形式のブレが繰り返し起きている\n- 毎回同じ後処理を頼んでいる\n\n判定ルール:\n- 1回だけの要望は改善候補にしない\n- 2〜3回以上の繰り返しだけを候補にする\n- 設定ファイルは編集しない\n- JSON だけを返す\n\n改善不要な場合:\n{\"ok\": true}\n\n改善候補がある場合:\n{\"ok\": false, \"reason\": \"改善候補があります。/improve-config を実行して設定案を確認してください。候補例: 1) 結論先出しを CLAUDE.md に追加 2) レビュー後の lint/test/差分説明を skills 化\"}"
}
]
}
]
}
}
2. 設定を改善する skills の設定
hooks 発火時には、作業ログや直前の指摘内容をもとに、改善候補があるかどうかを判定します。
改善候補が見つかった場合だけ、改善用 skill /improve-config の実行をユーザに促します。
/improve-config の役割は次の3つです。
- 繰り返し発生している指摘を見つける
- 明文化できるルール候補を挙げる
- 改善候補を実際の設定変更案として具体化する
ここでは、設定を自動反映するのではなく、
「どこを改善するとよさそうか」を人間が判断できる形に整えることを優先します。
skills の設定例
---
name: improve-config
description: 直近の会話で繰り返し発生した摩擦をもとに、Claude Code の設定改善案を最小単位で提案する
---
# improve-config
あなたは Claude Code の設定改善アシスタントです。
目的は、直近のやり取りから「繰り返し発生している摩擦」を見つけ、
設定に昇格させるべき最小の変更案を提案することです。
## 見るべきもの
以下のような繰り返しだけを対象にしてください。
- 同じ出力形式の指摘が何度もある
- 同じ修正依頼が複数回ある
- タスク後に毎回同じ追加作業を頼んでいる
- 同じ作業手順を毎回手で繰り返している
以下は無視してください。
- その場限りの好み
- 単発の要望
- 一度しか出ていない指摘
## 判断ルール
- 1回だけなら設定にしない
- 2〜3回繰り返したら改善候補
- 変更は常に最小単位にする
- 無関係な改善を一度にまとめない
## どこに反映するか
候補は次のいずれかに分類してください。
1. `CLAUDE.md`
- 安定した出力ルール
- 毎回求められる書き方
- 応答方針
2. `skills`
- 複数ステップの定型作業
- 毎回同じ順序で行う処理
3. `subagent`
- 役割分離が本当に必要なときだけ
基本的には `CLAUDE.md` または `skills` を優先し、
`subagent` は必要性が明確な場合だけ提案してください。
## 出力形式
以下の形式で出力してください。
### 観測した摩擦
- ...
### なぜ繰り返しと判断したか
- ...
### 反映先
- `CLAUDE.md` / `skills` / `subagent`
### 最小変更案
- ここに提案内容をそのまま書く
### この変更を最小に留める理由
- ...
## 制約
- ファイルは直接編集しない
- 理想の設定を作ろうとしない
- まずは保守しやすさと理解しやすさを優先する
よくある失敗パターン
この方針で運用すると、次のような失敗を避けやすくなります。
-
最初から全部設定する
→ 理解不能になり、使われなくなる -
何でも CLAUDE.md に書く
→ ノイズが増え、逆に精度が落ちる -
hooks を最初から重くしすぎる
→ 不要な hooks まで発火し、ノイズになる -
skills と CLAUDE.md の責務が混ざる
→ どこに何を書くべきか分からなくなり、使いこなせなくなる
まとめ
- Claude Codeの設定は、設計するものではない
- 運用の中で観測し、改善し、反映することで進化させるもの
- 最初から完成形を目指すのではなく、最小構成から始めて、自分の思考と一致する設定へと育てていく
最初から正しい設定を目指す必要はありません。
まずは最小構成で使い始めて、繰り返し発生する摩擦だけを設定に昇格させる。
その運用を続けた先に、ようやく「使いこなせる設定」が残ります。