0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

「あ、これ前も言ったな」から始める Claude Code の育て方

0
Last updated at Posted at 2026-09-12

はじめに

Claude Code を使っていると、「これは便利だ」と思う瞬間があります。
うまくはまったスキル(Skills)の使い方や、先に伝えておくと話が早い前提。
次も同じように使いたい、と感じます。

ただ筆者の場合、CLAUDE.md もスキルもメモリもフック(Hooks)も、なんとなくで使っていました。
機能の説明は、公式ドキュメントにも記事にも十分あります。
それでも「このお願いや命令は、どこに書いておくと次回も効くのか」が決められませんでした。

機能の一覧表は「その機能が何をするか」を教えてくれますが、「手元のこの 1 行をどこに置くか」までは決めてくれません。

本記事では、機能の説明ではなく、その手前にある考え方を整理します。
本記事は筆者の備忘録も含みます。

気になったこと

  • スキル・メモリ・フックは、結局なにが違うのか
  • よく聞く「ハーネス」は、それらとどういう関係にあるのか
  • 新しく覚えたことを、どこに書けば次回も効くのか

先に結論

4 つを分けているのは、機能の種類ではありません。
情報が、いつ Claude の目の前に出てくるかです。

置き場所 いつ目の前に出るか 誰が書くか 守られる保証
CLAUDE.md 毎回、必ず出る なし(お願い)
メモリ 毎回、必ず出る Claude(人が頼むこともできる) なし(お願い)
スキル 呼ばれてから出る(以後は残る) なし(お願い)
フック 目の前に出ない。機械が動く あり(強制)
ハーネス 上の 4 つが乗っている環境そのもの

そして迷ったときは、機能から選ばずに 「Claude はなぜ失敗したのか」から逆算します

  • 前提を知らなかった → 常に見える場所へ(CLAUDE.md・メモリ)
  • 毎回同じ手順を貼っている → 呼び出せる場所へ(スキル)
  • 知っていたのにやらなかった → 機械に守らせる(フック)
  • そもそも触れなかった → 環境側の問題(ハーネス)

ハーネスは 5 つ目の機能ではなく、上の 4 つを含む入れ物です。
機能を覚えることよりも、「自分が毎回同じ説明をしている」ことに気づくほうが先、というのが今回の学びでした。

前提となる 2 つの制約

一番イメージしやすい例えは、腕はいいのに毎朝すべてを忘れてしまう新人が 1 人チームに入ってきた状況です。
技術力は高く、指示すれば的確に動きます。

この新人には、2 つの制約があります。
CLAUDE.md もメモリもスキルもフックも、すべてこの 2 つにどう対処するかの答えです。

毎朝すべてを忘れる

前日に教えたことは、翌朝には何も残っていません。
これは比喩ではありますが、仕組みとしても実際にそうなっています。

Claude Code の各セッションは、新しいコンテキストウィンドウで始まります。

引用元:https://code.claude.com/docs/ja/memory

毎回まっさらな状態から始まります。

作業机には 2 つの癖がある

この新人が使う作業机には、2 つの癖があります。

1 つめは単純です。
広さに上限があります。

Claude が 1 回のやり取りで参照できる情報量には上限があり、これをコンテキストウィンドウと呼びます。
机に載りきらなかった資料は、そもそも参照されません。

やっかいなのは 2 つめです。
机に載せたからといって、見てもらえるとは限りません。

資料を積み上げていけば、いちばん下の 1 枚は机に載ってはいるものの、実際には目を通されません。
Claude の机でも同じことが起きます。

「広さが足りない」と「載っているのに読まれない」は、別の問題です。
公式ドキュメントも、この 2 つを分けて書いています。

多すぎるとコンテキストウィンドウがいっぱいになる可能性がありますが、Claude の効果を低下させるノイズを追加することもできます。スキルが正しくトリガーされない場合や、Claude が規約を失う場合があります。

引用元:https://code.claude.com/docs/ja/features-overview

「いっぱいになる」が広さの問題、「ノイズを追加する」が埋もれる問題です。
そして実務で先に効いてくるのは、たいてい後者のほうです。
机がいっぱいになる前に、規約が守られなくなります。

CLAUDE.md についても、同じ 2 段構えで書かれています。

CLAUDE.md ファイルあたり 200 行以下を目標にします。より長いファイルはより多くのコンテキストを消費し、遵守を減らします。

引用元:https://code.claude.com/docs/ja/memory

「コンテキストを消費する」だけでなく、そのあとに「遵守を減らす」と明記されています。
長く書くほど守られにくくなる、という直感に反する性質があります。
CLAUDE.md は足していくファイルではなく、定期的に削るファイルとして扱ったほうがよさそうです。

全体像

「毎朝忘れる」と「机は有限で、しかも載せただけでは見てもらえない」。
この 2 つの制約を同時に見ると、4 つの置き場所がきれいに並びます。

オフィス全体がハーネス、机の上がコンテキストウィンドウにあたります。

スキルの矢印だけラベルが違います。
セッション開始の時点で机に出るのは背表紙(名前と説明文)だけで、中身が広がるのは呼ばれたときだからです。

1.CLAUDE.md — 毎朝渡す引き継ぎメモ

CLAUDE.md は、毎朝この新人に必ず渡す引き継ぎメモです。
セッションの開始時に読み込まれ、そのセッションのあいだ机の上に出しっぱなしになります。

ここに書くべきなのは、どの作業をするときでも必要になる前提です。

  • ビルドコマンドやテストコマンド
  • 「npm ではなく pnpm を使う」といった、常に効くルール
  • プロジェクトの構造や命名規約

特定の作業のときにしか使わない長い手順書は、ここには向きません。
毎朝渡すメモに、年に数回しか使わないマニュアルを綴じ込むようなものだからです。

そしてもっとも大事な性質が、これは強制ではないという点です。

どちらも各会話の開始時に読み込まれます。Claude はこれらをコンテキストとして扱い、強制的な設定ではありません。アクションをブロックするには、Claude の判断に関わらず PreToolUse hook を使用してください。

引用元:https://code.claude.com/docs/ja/memory

CLAUDE.md に「本番環境に接続しないこと」と書いても、それはお願いであって保証ではありません。

「書いたのに守られない」と感じたときは、守られる仕組みではないものに守らせようとしている、と考えるのが正確です。
確実に止めたいものには、**4.**のフックを使います。

2.メモリ — 新人が自分でつける業務日誌

メモリは、この 4 つのなかで唯一Claude 自身が書き手になるという点で性質が違います。

CLAUDE.md が「こちらが渡す引き継ぎメモ」なら、メモリは「本人が業務中につけている日誌」です。
作業しながら気づいたこと、詰まって解決した手順、こちらの好みなどを、Claude が自分の判断で書き残していきます。

自動メモリを使用すると、Claude は何も書かずにセッション間で知識を蓄積できます。Claude は作業中に自分自身のためにメモを保存します。

引用元:https://code.claude.com/docs/ja/memory

同じページによると、保存先は ~/.claude/projects/<project>/memory/ で、MEMORY.md が索引の役割を持ちます。
毎セッション読み込まれるのは MEMORY.md の先頭 200 行、または 25KB までで、詳細なトピックファイルは必要になったときに読まれます。

メモリのほうにも、机の広さという同じ制約がかかっています。
日誌が厚くなりすぎれば、朝いちばんに目を通せる範囲を超えてしまいます。

2.1. 人の側から書かせることもできる

Claude が自分で書くだけでなく、こちらから働きかけることもできます。
「これを覚えておいて」と頼めば、Claude はその場でメモリに書き残します。
/memory からファイルを開いて、自分で書き換えることも削除することもできます。

頼んだ内容がどこに保存されるかは、公式ドキュメントに明記されています。

Claude に何かを記憶するよう求めるとき、「常に npm ではなく pnpm を使用する」または「API テストがローカル Redis インスタンスを必要とすることを覚えておく」のように、Claude はそれを自動メモリに保存します。代わりに CLAUDE.md に指示を追加するには、Claude に直接「これを CLAUDE.md に追加する」と尋ねるか、/memory を通じてファイルを自分で編集します。

引用元:https://code.claude.com/docs/ja/memory

「覚えておいて」と頼んだ内容は、メモリに入ります。
CLAUDE.md に入れたいときは、「これを CLAUDE.md に追加して」と明示的に伝える必要があります。

2.2. CLAUDE.md との住み分け

  • CLAUDE.md … チームで共有するルール。バージョン管理に入り、全員に効く
  • メモリ … Claude が気づいたこと、こちらが覚えておいてと頼んだこと。マシンローカルで、個人の作業のなかで育つ

「さっき教えたのに」と思ったとき、CLAUDE.md に書くまでもない小さな学びは、Claude 側に残っていることがあります。
メモリの存在を知っておくだけで、「教えたことが消える」という感覚はかなり減ります。

自動メモリはデフォルトで有効です。
無効にしたい場合は /memory のトグル、または設定の autoMemoryEnabled で切り替えられます。

3.スキル — 書庫に並ぶマニュアル

スキルは、書庫に並んでいるマニュアルです。
普段は棚に入っていて机の上を占領せず、必要になったときに持ってきます。

CLAUDE.md コンテンツとは異なり、スキルの本体は使用されるときにのみ読み込まれるため、長いリファレンス資料は必要になるまでほぼコストがかかりません。

引用元:https://code.claude.com/docs/ja/skills

引用の「コスト」は料金ではなく、机の場所のことです。

ここが CLAUDE.md との決定的な違いになります。
CLAUDE.md は毎回、机の場所を取ります。
スキルは、呼ばれるまで机の場所を取りません。

だから、長い手順書やリファレンス資料はスキルに置くのが合理的です。
デプロイ手順、コードレビューのチェックリスト、社内 API の書き方。
どれも「必要なときにだけ完全な内容が要る」情報です。

スキルの価値は便利さよりも、机を散らかさないことにあります。
いま関係のない資料を机に出さずに済む、という一点でスキルにする価値が決まります。

3.1. 一度出したマニュアルは、棚に戻らない

一度呼ばれたスキルは、そのセッションのあいだ机の上に出しっぱなしになります。

ユーザーまたは Claude がスキルを呼び出すと、レンダリングされた SKILL.md コンテンツは会話に単一のメッセージとして入力され、セッションの残りの間そこに留まります。

引用元:https://code.claude.com/docs/ja/skills

棚に戻す方法は、セッションを終えることだけです。
スキルが机を占領しないのは、出すまでの間だけです。
次々に呼び出せば、机はやはり埋まっていきます。

この性質は、スキルを書くときの指針に直結します。

Claude Code は後のターンでスキルファイルを再度読み込まないため、タスク全体を通じて適用すべきガイダンスを 1 回限りのステップではなく、スタンディング指示として記述します。

引用元:https://code.claude.com/docs/ja/skills

一度出したら最後まで机の上にあるのだから、セッションを通して読まれても破綻しない書き方にしておく必要があります。
呼び出した直後の 1 回だけ効けばいい手順書、という書き方は避けます。

3.2. description が書庫の索引になっている

description は、書庫の索引です。

スキル本体は呼ばれるまで読み込まれませんが、名前と説明文はセッション開始時に読み込まれます。
Claude はこの説明文を見て「今の作業に関係あるか」を判断します。

つまり、スキルが呼ばれないときの原因は本文ではなく説明文にあることが多い、という構造になっています。
公式のトラブルシューティングでも、最初に確認する項目として挙げられています。

Claude がスキルを期待どおりに使用しない場合:

  1. 説明にユーザーが自然に言うキーワードが含まれていることを確認します

引用元:https://code.claude.com/docs/ja/skills

マニュアルの中身がどれだけ良くても、背表紙に何も書いていなければ棚から取られません。

3.3. 効かなくなったように見えるとき

最初は効いていたスキルが、途中から効かなくなったように見えることがあります。

スキルが最初の応答の後に動作に影響を与えるのを停止しているように見える場合、コンテンツは通常まだ存在し、モデルは他のツールまたはアプローチを選択しています。

引用元:https://code.claude.com/docs/ja/skills

スキルの内容は机の上に残ったままで、Claude が別のやり方を選んでいます。
机の上にあるのに、埋もれている状態です。
前提の章で書いた「載せても見てもらえるとは限らない」が、そのまま起きています。

対処は 3 通りあります。

  • description と指示を強化して、優先されやすくする
  • もう一度呼び出して、机の手前に出し直す
  • 確実に守らせたいなら、4.のフックで強制する

スキルは机に載り続けますが、載り続けることと守られることは別です。
ここでもやはり、スキルは最後まで「お願い」のままです。

4.フック — 本人の判断に頼らない入退室ゲート

フックは、これまでの 3 つとは性質がまったく違います。
CLAUDE.md もメモリもスキルも「Claude に読ませて、判断してもらう」仕組みでした。

フックは Claude の判断を経由しません
特定のイベントが起きたら、設定されたコマンドが必ず実行されます。

オフィスの比喩でいえば、入退室ゲートやサーバールームの鍵にあたります。
「勝手に入らないでくださいね」というお願いではなく、物理的に開かない仕組みです。

4.1. お願いではなく、強制になる

公式ドキュメントは、この違いを決定論性という言葉で整理しています。
フックとスキルを比較した表の、決定論性の行が以下です。

側面 Hook Skill
決定論性 イベントで常に発火。トリガーは保証される Claude が指示を解釈。結果は異なる可能性

引用元:https://code.claude.com/docs/ja/features-overview

同じページには、より直接的な指針も書かれています。

ガードレールをフックに入れます。 CLAUDE.md またはスキルの「.env を編集しない」のような指示はリクエストであり、保証ではありません。編集をブロックする PreToolUse フックは強制です。

引用元:https://code.claude.com/docs/ja/features-overview

ここから導かれる判断基準はシンプルです。

「たまに破られても困らない」ならお願い(CLAUDE.md・スキル)、「一度でも破られたら困る」なら強制(フック)。

フックを入れるかどうかを決めるのは、習熟度ではなく破られたときの被害の大きさです。
「これだけは絶対に」という項目が 1 つでもあるなら、そこが入門のタイミングになります。

4.2. すべてをフックにしない理由

強制できるなら、全部フックにすればよさそうに思えます。
ただしフックが動くのは、Claude がすでに何をするか決めたあとです。

CLAUDE.md に「pnpm を使う」と書けば、Claude は最初から pnpm を使います。
フックで npm をブロックするだけだと、Claude は npm を試して弾かれ、理由が分からなければ yarn を試して、また弾かれます。

ブロックは方向を示しません。
禁止だけを並べると、Claude は総当たりを始めます。

公式ドキュメントも、この役割分担を明記しています。

設定を技術的な強制に使用し、CLAUDE.md を行動ガイダンスに使用します。

引用元:https://code.claude.com/docs/ja/memory

同じページの対応表では、「特定のツール、コマンド、またはファイルパスをブロックする」は設定側、「コードスタイルと品質ガイドライン」と「Claude の行動指示」は CLAUDE.md 側に振り分けられています。

フックが扱えるのは、機械的に判定できる条件だけです。
「このパスは .env か」は書けますが、「この命名はプロジェクトの規約に沿っているか」は書けません。

アクションが毎回同じ方法で実行される必要があり、Claude が考える必要がない場合は hook を使用します。

引用元:https://code.claude.com/docs/ja/features-overview

裏返すと、考える余地があるものは CLAUDE.md 側の担当になります。
そしてフックは、登録したイベントでしか発火しません。
想定していなかった経路は、そのまま通り抜けます。

CLAUDE.md で方向を示し、そのうえで「一度でも破られたら困る」ものだけフックで止める。
この順序が実用的です。

5.ハーネス — 4 つを載せている環境そのもの

ここまでの 4 つを並べたあと、当然「ではハーネスは?」となります。
筆者もここで一度つまずきました。

ハーネス(harness) は、4 つと並ぶ 5 つ目の選択肢ではありません
4 つが全部そのなかに入っている、入れ物のほうです。

5.1. Claude を、モデルとツールに分けて見る

ハーネスを説明するために、ここまで「Claude」とひとまとめに呼んできたものを 2 つに分けます。

  • モデル … 考える側。コードを読み、何をすべきかを判断する
  • ツール … 動く側。ファイルを読み書きし、コマンドを実行し、検索する(公式はファイル操作・検索・実行・ウェブ・コードインテリジェンスの 5 カテゴリに整理しています)

ツールは Claude Code を agentic にするものです。ツールがなければ、Claude はテキストで応答することしかできません。ツールがあれば、Claude はアクションを実行できます。

引用元:https://code.claude.com/docs/ja/how-claude-code-works

ここでいうツールは、Claude Code に最初から備わっている実行能力です。
ここまで見てきた CLAUDE.md・メモリ・スキル・フックは、その上に乗る層にあたります。

基本機能の拡張: 組み込みツールが基盤です。スキルで Claude が知ることを拡張し、MCP で外部サービスに接続し、フックでワークフローを自動化し、subagent にタスクをオフロードできます。これらの拡張は、コア agentic ループの上に層を形成します。

引用元:https://code.claude.com/docs/ja/how-claude-code-works

ツールという手足があって、初めて動けます。
その上に、何を知っていて何をすべきかを決める層が乗っている、という関係です。

5.2. ハーネスとは、モデルの周りにあるもの全部

ハーネスの定義は、そのまま公式ドキュメントに書かれています。

agentic ループは 2 つのコンポーネントによって駆動されます。推論するモデルと、アクションを実行するツールです。Claude Code は Claude の周りの agentic ハーネスとして機能します。 言語モデルを有能なコーディングエージェントに変えるツール、コンテキスト管理、実行環境を提供します。

引用元:https://code.claude.com/docs/ja/how-claude-code-works

Claude Code そのものがハーネスです。

「Claude の周りのハーネス」が「ツール、コンテキスト管理、実行環境を提供します」という構造を図にすると、こうなります。

ツールはハーネスが提供するもので、枠の中にあります。
モデルは提供を受ける側で、枠の外にいます。

モデルが差し替え可能であることも、これを裏づけます。
/model で Sonnet と Opus を切り替えてみてください。

使える道具も、CLAUDE.md の読み込まれ方も、Esc で止まることも、権限の聞かれ方も変わりません。
変わるのは、考える力だけです。

オフィスも机も道具も引き継ぎメモもそのままで、座っている新人だけが交代する
これがモデルの切り替えです。
そして交代しても残っているもの、それがハーネスです。

5.3. ハーネスが提供する 3 つと、本記事の 4 つ

引用にあるとおり、ハーネスが提供するものはツール・コンテキスト管理・実行環境の 3 つです。
ここに本記事の 4 つを当てはめると、こうなります。

ハーネスが提供するもの 本記事で見てきたもの
ツール (本記事の対象外。組み込みの実行能力)
コンテキスト管理 CLAUDE.md・メモリ・スキル
実行環境 フック、権限、MCP

「コンテキスト管理」は、ずっと話してきた机の管理そのものです。
CLAUDE.md もメモリもスキルも、ハーネスが提供する 3 つのうち 1 つの内訳でしかありません。
だからハーネスと横に並べられない、という話になります。

フックだけがコンテキスト管理の枠に入らないのは、フックがコンテキストを消費しないからです。
「フックだけ性質がまったく違う」と書いてきたことの、構造的な理由がここにあります。

この 3 つへの割り当ては筆者の整理です。
公式ドキュメントが 4 つの機能をこの 3 つに分類しているわけではありません。

5.4. ハーネスがないとどうなるか

ハーネスの輪郭は、無い状態と比べるといちばんはっきりします。

Claude Code を使わず、API を直接呼び出すと何が起きるでしょうか。
CLAUDE.md は読まれません。
メモリもスキルもフックもありません。
コンテキストが埋まっても、誰も圧縮してくれません。
そもそもファイルを読む手段がないので、返ってくるのはテキストだけです。

Anthropic Client SDK は直接 API アクセスを提供します。プロンプトを送信し、ツール実行を自分で実装します。Agent SDK は、組み込みツール実行を備えた Claude を提供します。Client SDK では、ツールループを実装します。Agent SDK では、Claude がそれを処理します。

引用元:https://code.claude.com/docs/ja/agent-sdk/overview

ファイルを読ませたければ、その仕組みを自分で書くことになります。
この差分がハーネスです。

claude と打った瞬間に、これらが全部用意されています。
だからハーネスは「これから作るもの」ではなく、すでにそこにあるものです。

この仕組み一式は Claude Agent SDK として提供されており、自分でハーネスを組むこともできます。
読み込み元を settingSources で絞れば、CLAUDE.md やスキルを一切読まない構成にすることも可能です。
CLAUDE.md は Claude の必須要素ではなく、Claude Code というハーネスが用意している仕組みです。

最小のハーネスエンジニアリング

「ハーネスエンジニアリング」という言葉は、多層の設計パターンとして語られることが多く、初心者には遠い話に見えます。
筆者も最初はそう感じました。

しかし考え方そのものは、実はとても素朴です。

同じ失敗を二度させないために、会話ではなく環境のほうを直す。

Claude が規約を間違えたとき、その場で「違うよ、こうして」と言い直せば直ります。
ただしそれはその場かぎりで、明日になれば新人はまた忘れています。

言い直しは一瞬で済むので、負担がないように見えます。
しかし実際には、毎朝おなじ手間を払い続けていることになります。
その手間に気づいて、1 回の言い直しを CLAUDE.md の 1 行に変える。
これが最小のハーネスエンジニアリングです。

公式ドキュメントも、まさにこのトリガーを起点に整理しています。
「セットアップを時間をかけて構築する」という表から抜粋します。

トリガー 追加
Claude が規約またはコマンドを 2 回間違える CLAUDE.md に追加
同じプロンプトをタスクを開始するために何度も入力している ユーザーが呼び出し可能な skill として保存
同じプレイブックまたは複数ステップの手順をチャットに 3 回目に貼り付けている skill としてキャプチャ
何かが毎回聞かずに起こることを望んでいる hook を記述

引用元:https://code.claude.com/docs/ja/features-overview

この表を動かすのは人です。
Claude Code は、規約を 2 回間違えたからといって、自分で CLAUDE.md に書き足したりはしません。
トリガーに気づいて手を動かすのは、こちら側の仕事になります。

例外はメモリだけです。
Claude は作業中に「これは次回も役立つ」と判断したことを、自分で書き残していきます。
同じ失敗を二度させないための学習は、一部だけすでに自動化されています。

裏を返せば、1 回の言い直しを CLAUDE.md の 1 行に昇格させるかどうかは、人が決めることとして残されています

大掛かりな設計から入る必要はありません。
「あ、これ前も言ったな」と思った回数が、そのまま設計の出発点になります。

失敗から逆算する

以上をふまえると、置き場所を選ぶときの手順は「機能を比較する」ではなく「症状を分類する」になります。

症状ごとの早見表にすると、次のようになります。

症状 置き場所 理由
同じ規約を 2 回間違える CLAUDE.md どの作業でも必要な前提だから
同じ手順書を 3 回目に貼っている スキル 使うときだけ読み込めば足りるから
「絶対にやるな」が守られない フック CLAUDE.md は強制ではないから
CLAUDE.md が長くなり、守られなくなってきた スキルへ移す 長いほど遵守率が下がるから
前に教えたはずのことを毎回説明している /memory を確認 Claude 自身が書き残している可能性があるから
そもそも必要な情報源に触れない MCP・権限設定 知識ではなく道具の問題だから

この表の要点は、最初の列が「機能」ではなく「症状」になっていることです。
機能から入ると毎回比較が必要になりますが、症状から入れば置き場所は 1 つに決まります。

まとめ

Claude Code の機能を「機能」として覚えようとすると、数が多くて比較に疲れます。
そうではなく、毎朝忘れる新人と、載せただけでは見てもらえない作業机という 2 つの制約から見ると、置き場所は 4 つに整理できます。

  • 毎回必要な前提は、机に出しっぱなしにする(CLAUDE.md)
  • Claude が気づいたことと、覚えておいてと頼んだことは、本人の日誌に溜まる(メモリ)
  • 使うときだけ必要な手順は、書庫に置く(スキル)
  • 絶対に守らせたいことは、お願いではなく仕組みにする(フック)
  • そしてこれら全部を用意して動かしている環境が、ハーネス

選ぶときは機能を比較するのではなく、症状から逆算します。
前提を知らなかったのか、知っていたのにやらなかったのか、そもそも触れなかったのか。
原因が決まれば、置き場所も決まります。

最後にもう一度書いておくと、いちばん大事な感覚は「あ、これ前も言ったな」です。
その気づきの回数だけ、Claude Code は育てられます。

参考

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?