はじめに

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 の設定例

.claude/settings.json

{
  "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 の設定例

.claude/skills/improve-config/SKILL.md

---
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の設定は、設計するものではない
運用の中で観測し、改善し、反映することで進化させるもの
最初から完成形を目指すのではなく、最小構成から始めて、自分の思考と一致する設定へと育てていく

最初から正しい設定を目指す必要はありません。
まずは最小構成で使い始めて、繰り返し発生する摩擦だけを設定に昇格させる。
その運用を続けた先に、ようやく「使いこなせる設定」が残ります。