ループエンジニアリングを調べ終えたばかりなのに、もう次の言葉が出てきた
そんな順番でこのページにたどり着いた方も多いと思います
今回のテーマはグラフエンジニアリングです

グラフエンジニアリングとは何か、ひとことで答えるならAIの仕事をノードとエッジに切り分けて、つなぎ方まで決めておく設計の考え方です
1体のAIをどう回すかではなく、複数の担当と受け渡しをどう組むかを扱います

この記事は「AIの◯◯エンジニアリング」連載の5本目です
前回のエージェントループが「時間軸でどう回すか」だったのに対して、今回は構造軸でどう組むかの話になります

この言葉が一気に広まったきっかけは、実は冗談の投稿でした
ただ、中身まで冗談ではありません

ジャベ雄

聞き慣れない言葉ばかりですが、やっていることは仕事の分担と同じです

グラフエンジニアリングとは？まず結論から

結論から言うと、AIの仕事を点と線のつながりとして書き出しておく営みです
点がノード、線がエッジ、そのあいだを流れる情報が状態です

よく出てくる「有向グラフ」は、点と線を向き付きでつないだ図のことです
棒グラフや折れ線グラフとは別物です

では、なぜ書き出すのか？
1つの流れに判断も情報も外への操作も詰め込むと、途中で止まったときどこから再開すればいいのかが分からなくなります
切り分けておけば、止まった点だけをやり直せます

ジャベ雄

この3語、仕事の役割分担をそのまま言い換えただけなんです

ループエンジニアリングとの違い 時間軸と構造軸

ループエンジニアリングが設計するのは時間軸です
1体のAIをどう回し続けるかを扱います
グラフエンジニアリングが設計するのは構造軸のほう、複数の担当をどう並べてつなぐかです

押さえたいのは、2つが置き換えではなく包含の関係だという点です
ループは消えません
1体のAIが回している輪が、そのままグラフの1つの点に収まります

グラフを「多くのループにまたがる調整のレイヤー」と呼ぶ解説もありました

資料づくりで言うと、書いた人が「直して出し直す」を繰り返しているのがループです
その人を含めた全員の担当と受け渡しを決めるのがグラフになります
担当が1人なら、そもそも線を引く必要がありません

あわせて読みたい

エージェントループとは 推論と行動を繰り返す仕組み AIエージェントが自分で考えて動き続ける正体がエージェントループです この記事では推論 行動 観測を停止条件まで繰り返す基本のしくみを ReActの由来やClaude Codeの実例とあわせて解説し 後半では2026年に登場したループエンジニアリングという新しい考え方も等身大で紹介します

ノード・エッジ・状態 3つの部品を噛み砕く

この3語さえ握っておけば、英語の解説を開いても迷子になりません

ノードは「1つのことだけをやる担当」

置かれるのは、だいたい次の粒度になります

• AIに1回考えさせる(下書きを作る・要約する)
• ツールを動かす(検索する・APIを呼ぶ・コードを走らせる)
• 検証役(evaluator)として、前のノードの出来を判定する
• 人の承認(human gate)として、進めていいかを人に聞く

1つのノードにあれもこれも詰め込まないのがコツです
最初にこの言葉を使った記事も、ノードは退屈なくらい単純がいいと書いています
資料づくりでいえば、書く人とチェックする人を兼ねさせないことです

エッジは矢印ではなく「取り決め」

エッジは矢印ではなく、ノードとノードのあいだで交わす取り決めのことです
線1本に、次の4つがぶら下がります

• 渡すもの・受け取るもののかたち(項目や型)
• どういう条件のときに、その線を通るのか
• そのノードが外に対してやっていい操作の範囲
• 失敗したときの扱い(前へ戻すのか・別の線へ逃がすのか)

資料づくりなら「書き終えたら声をかける」だけでは足りません
誤字を直してから渡す・内容が薄ければ書き直しに戻す、そこまで決めるのがエッジです

状態は「途中から再開できるようにする進捗表」

状態は、ノードのあいだで共有される情報です
会話の履歴をそのまま抱える形と、項目を決めた表のように持つ形があります

差が出るのは、状態を会話ログから切り離すかどうかです
切り離してあると、止まっても最後に保存した地点から再開できます
あとから「どの時点で何が入っていたか」もたどれます

共有フォルダの進捗表と同じです
誰でも読める場所に進み具合を書いておけば、担当が抜けても続きから入れます
会話の中だけで進めると、それが残りません

ノード・エッジ・状態という整理は、We Are Entering the Graph Engineering Phase(Josh C. Simmons、2026年7月4日)でも示されています

エッジで表せる4つの形

複雑そうな構成も、たいていこの組み合わせです

4つ目のループ回帰が、さっきの包含の関係です

ジャベ雄

エッジを「矢印」でなく「取り決め」と読み替えるのが、いちばんの山です

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

言葉の出どころ 論考が先で 冗談で火が付いた

この順番を取り違えやすいので、日付で並べます

皮肉の的になったのは、業界が数か月ごとに同じ営みを改名し続けることでした
ループエンジニアリングが広まって、まだ6週間ほどのタイミングです
「もう次の名前に移ったの？」という揶揄でした

この2つの投稿は、新しい製品やモデルの発表をきっかけに起きたものではありません

ただ、冗談が出発点だったわけではありません
2週間前の7月4日の論考は「エージェントループが十分に良くなった結果、自分の天井が見えてしまった」と書いています
この限界はモデルの質とは関係ない、次は複数をどうつなぐかだ、という主張です

実装のほうが言葉より2年半早い

LangGraph は2024年1月なので、言葉より2年半ほど先に実装があったことになります
新しい言葉が出た=新しい技術が出た、とは限りません

身近なところだと、Claude Code にも複数のエージェントをつなぐ仕組みがあります
公式ドキュメントによると、有料プラン向けで v2.1.154 以降が要ります
Pro は既定でオフなので、/config の Dynamic workflows から入れる形です
私はグラフのフレームワーク自体は触っていないので、名前を挙げるだけにとどめます

ジャベ雄

2026年8月の時点で、言葉はひと月・実装は2年半です
この差を知っておくと落ち着いて読めます

冷静な見方 ほとんどのエージェントには要らないという声

Turing Post は、この概念は新しくないとはっきり書いています
ループはすでにグラフの一種ですし、状態機械や DAG(向きがあって一周しない図)は数十年前からあるものです

2年半という数字はAI向けの道具に限った話で、考え方まで遡れば数十年になります

Turing Post には、ほかに次の2点も書かれています

• 「Microsoft と Stanford と Anthropic が同時に発見した」という言われ方には根拠がない
• ほとんどのエージェントに、グラフのフレームワークは要らない

出典はIs Graph Engineering Real?(Turing Post)です
最初期の記事と並べて読むと、温度差がはっきり出ます

もう1つ、日本語の指摘で納得したものです
配線をどれだけ賢くしても、1つ1つのノードの判定が甘ければ、複雑な配線は間違った方向に速く進む装置にしかならない
つなぎ方より、ノードが出す答えの質が先だ、という主張です

これは書き手の意見ですが、私が読んだ範囲では中身が濃かったです
出典はループエンジニアリングの次は本当に「グラフ」なのか考えてみた(Zenn)です

グラフにする / しないの見分け方

線を引くかどうかの判断材料が、解説記事に出ていました

ほかに、独立した枝が複数あるとき・複数の担当が連携するとき・数分を超える待ち時間があるとき・権限の違う操作が混じるときも挙がっていました

3つ目だけ補足します
動的に線を組み替えられる道具もあるので、手順が変わる=グラフにできない、ではありません
ただし組み替えを前提にすると、設計のほうが重くなります

判断の軸は分担する理由があるかどうかに集約されます
元にした記事はグラフエンジニアリングとは？(AI総合研究所、2026年7月28日)で、私が見た限りでは日本語の解説でいちばん詳しかったです

私はまだ線を引くほどの規模ではありません
それでも3語を知っていると、解説を読む速さが変わります

ジャベ雄

迷ったら、まず線を引かずに1本の流れで書いてみるのがおすすめです

まとめ グラフエンジニアリングの要点と連載ナビ

グラフエンジニアリングとは、AIの仕事をノード・エッジ・状態に分けて、つなぎ方まで決めておく設計の考え方でした

• ノード(担当)・エッジ(取り決め)・状態(共有の進捗表)の3つで組む
• エッジは矢印ではなく、渡すもの・条件・許す操作・失敗時の扱いまで含む取り決め
• ループとは包含の関係、ループはグラフの1つのノードとして収まる
• 広まったきっかけは2026年7月18日の冗談の投稿、ただし論考は7月4日で先
• 実装は言葉より2年半早い(LangGraph は2024年1月)
• ほとんどのエージェントにグラフのフレームワークは要らない、という指摘もある

最後に、いちばん持ち帰ってほしいことです
新しい「◯◯エンジニアリング」が出てきたら、結局、何のノードと何のエッジの話をしているのかに分解して読む
これを覚えておけば、名前が変わっても中身は追えます

この読み方はグラフエンジニアリングを知ろう(Qiita、2026年8月6日)が勧めていたものです

この記事は連載「AIの◯◯エンジニアリング」の1本です
全体を1枚で見たいときはハブからどうぞ

あわせて読みたい

AIエンジニアリング5種の違い コンテキストからグラフまで AIの使いこなしは プロンプト コンテキスト ハーネス ループ グラフ の5段階で進化してきました それぞれ何を設計する技術なのか どう違うのかを1枚の地図で俯瞰し 単発チャットから複数エージェントの編成までの流れをつかめるようにまとめた総論です

• 連載#1:指示文の書き方を5つのコツで整える
• 連載#2:AIに渡す材料を選び直す
• 連載#3:AIを取り囲む器のほうを整える
• 連載#4:AIが自分で考えて動き続ける輪のしくみ

5本を通して読むと、AIの作り込みが指示文→渡す材料→器→回し方→つなぎ方と外側へ広がってきた流れが見えます

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

Claude Code フォルダ構成は、放っておくとどんどん増えていきます
materials・research・rules・assets、見覚えのない名前が並んでいても、それが何のためにあるのかは分からないまま
このフォルダ、消してしまっていいんでしょうか？

私も気づいたら似たようなフォルダがいくつも並んでいて、どれが本物か分からなくなりました
AIは指示されればフォルダを作りますが、前回どう名付けたかまでは気にしてくれません

この記事では、AIが作るフォルダを3つの層に分けて読み解きます
層が分かると「これは触っていい」「これは触ると壊れる」がその場で判断できるはずです

ジャベ雄

フォルダ名を覚えるより、層で見分けるほうが早いです

Claude Code フォルダ構成は3つの層に分けて読む

結論から言うと、プロジェクトの中にあるフォルダは「誰が決めたか」で3層に分かれます
この分け方が便利なのは、層ごとに「名前を変えたときに何が起きるか」がはっきり違うからです

ややこしいのは、この3層が同じ階層に並んで置かれることです
見た目はどれも同じフォルダなので、開いてみるまで区別がつきません

ちなみに冒頭で挙げた materials と rules も、実は別々の層
rules は公式仕様に載っている第1層、materials は誰も決めていない第3層です、名前の見た目が似ていても扱いはまったく別ものになります

フォルダ構成とディレクトリ構成は同じ意味

調べているとディレクトリ構成という書き方によく出会いますが、これはフォルダ構成とまったく同じ意味です
どちらか一方が正しいわけではありません

ディレクトリのほうが古くからある呼び方で、もともとは「住所録」や「目録」を指す言葉でした
Windows がフォルダという呼び方を広めたあとも、開発の現場では前からの呼び方が残っていて、いまも両方が混在しています

AIも文脈によって呼び分けます
フォルダ名の意味を調べるときは、どちらの言葉でも同じ内容にたどり着くと思っておけば十分でしょう

ジャベ雄

呼び方が2つあるだけで、指しているものは同じです

第1層|公式に決まっているフォルダは名前を変えられない

第1層は Claude Code が仕様として読みに行くフォルダです
名前を変えると、その中身は読み込まれなくなります、置き場所も名前も公式ドキュメントで決まっているので、勝手に変えられません

プロジェクトの中の .claude フォルダ

プロジェクトのフォルダ直下に置く .claude が第1層の本体です
先頭にドットが付いているので、環境によっては隠しフォルダとして見えないこともあります

この中で見落としやすいのが rules です
「AIが勝手に作った雑多なフォルダ」に見えますが、実際は公式に用意された置き場で、テーマごとに指示を分けて書いておくためのものです

もうひとつ、commands というフォルダを見かけることがあります
スラッシュコマンドを置く場所ですが、公式は skills への移行をすすめています、同じ仕組みに統合されたので新しく作るなら skills のほうです

ジャベ雄

rules を「よくわからないから」で消すと、指示が丸ごと効かなくなります

パソコン全体で共通の ~/.claude フォルダ

プロジェクトごとの設定とは別に、パソコンのユーザーフォルダの中にも同じ名前のフォルダがもう1つ
こちらは全プロジェクト共通の設定置き場で、どのプロジェクトを開いても効きます

パスの先頭に付いている ~ は、ホームフォルダ(自分のユーザーフォルダ)を1文字で表す省略記号、読み方は「チルダ」です
この記号で始まっていたら、自分のユーザーフォルダから始まる場所を指しています

Windows なら C:\Users\(ユーザー名) がその場所にあたります
つまり ~/.claude/ と書いてあったら、それは C:\Users\(ユーザー名)\.claude\ のことだと読み替えてください

なぜ Windows なのに / 区切りなのか、と思われたかもしれません
この書き方はもともと Mac や Linux の流儀で、開発の世界では共通語として使われているものです、Claude も説明のときはこちらで書いてきます

ジャベ雄

チルダを見たら「自分のユーザーフォルダのことだな」と思えば大丈夫です

実際に開いてみると、この一覧に載っていないフォルダもいくつか並んでいます
cache・sessions・shell-snapshots のような、アプリが動くために自分で作って自分で使う置き場です

この手のフォルダは説明書に載っていないほうが普通だと考えてください
公開されている仕様は「人が触る前提のもの」だけで、動作の裏側で使う置き場までは案内されません

なお第1層の「ファイル」のほうを詳しく知りたい場合は、設定ファイルだけを一覧にした記事があります
どのファイルがどこに効くのか、継承のルールまで整理してあるのでこちらもどうぞ

あわせて読みたい

Claude Code 設定ファイル早見表 役割と場所 Claude Codeを触っていると次々に登場する設定ファイル(CLAUDE.md・settings.json・AGENT.md・SKILL.mdなど)を、保存場所と役割で一覧化した早見表記事です、微調整目線で抑えたい初心者〜中級者向けにまとめました

第2層|業界の慣習で決まっているフォルダ

第2層は、仕様ではないけれどほとんどの開発者が同じ意味で使っているフォルダです
名前を変えても動きますが、読む人が混乱します、いわば共通語のようなものだと思ってください

AIがプロジェクトを組み立てるとき、まず作るのがこの層です
学習したコードの大半がこの慣習に従っているので、指示しなくても自然にこの名前が出てきます

この中でいちばん質問されるのが src です
読み方は「ソース」で、source の母音を抜いた省略形になります、コンパイルが必要な言語で古くから使われてきた作法がそのまま各言語に広がりました

dist と build が両方あって混乱することもあります
どちらも「完成品の置き場」でほぼ同じ意味です、片方しか使わないのが普通なので、両方あるなら片方は使われていない可能性があります

もうひとつ覚えておくと役に立つのが vendor です
「取引先」という意味そのままで、自分で書いていないコードが入っています、ここを直しても更新のたびに上書きされるので触らないのが原則です

フォルダ名の付け方にも慣習がある

名前そのものだけでなく、書き方のほうにもゆるい決まり
自分でフォルダを追加するときも、この形に合わせておくと後々あつかいやすくなります

• すべて小文字で書く(Windows以外では大文字と小文字が別ものとして扱われるため)
• 単語の区切りはハイフンかアンダースコアにする、空白は入れない
• 日本語の名前は避ける、コマンドやツールで扱うときに事故のもとになる
• 複数形か単数形かは、プロジェクトの中で揃える

ジャベ雄

最後の「揃える」が、あとで一番効いてくる決まりです

第3層|AIがその場で作る作業フォルダ

第3層が、この記事でいちばん伝えたいところです
公式仕様でもなく業界の慣習でもない、その場の話の流れでAIが名付けたフォルダがここに入ります

「調べた内容をまとめておいて」と頼めば、AIはどこかに置き場を作ります
そのときの名前は materials かもしれないし research かもしれません、どちらでも間違いではないぶん、決まりようがないわけです

右端の列に注目してください
第3層のフォルダは、ほぼすべてが第2層の誰かと役割が重なっています、output と dist、reference と docs といった具合です

ここが散らかりの発生源になります
慣習の名前を使えば済むところに、AIがその場の言葉で別の名前を作ってしまうからです

とはいえ第3層そのものが悪いわけではありません
コードを書かない使い方だと src も tests も出番がないので、第3層の名前でプロジェクトの大半が構成されることすらあります、問題は名前が揺れることだけです

ジャベ雄

第3層は自由なぶん、放っておくと一番散らかります

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

AIに任せると同義フォルダが増えていく

いくつかのプロジェクトをAIに任せて育ててきた結果、私の手元では同じ役割のフォルダが違う名前で並ぶ状態があちこちにできていました
散らかり方には、はっきりした型があります

test と tests が両方あるのは、我ながらなかなかの散らかり具合でした
どちらにテストを書けばいいのか、開いた瞬間に手が止まりました

画像置き場にいたっては6種類に分かれていました
作業の内容が少しずつ違うので当時はそれぞれ理由があったはずですが、あとから見るとどれを開けばいいのか自分でも分からないありさま

なぜ増えてしまうのか

AIの不注意というより、仕組みから見て起きるべくして起きています
理由は主に4つです

• AIは前回どう名付けたかを見ていない、そのときの会話の流れだけで名前を決める
• 既存のフォルダがあっても、こちらの言い回しが違えば別のフォルダを作ってしまう
• 英語としてはどちらも正しいので、AIから見れば間違いに見えない
• 人が指摘しないかぎり、増えたことに誰も気づかない

3つめが特に厄介です
test も tests も英語として自然なので、AIには直すべき対象として見えていません、つまり待っていても勝手には揃いません

増殖を止める方法

対策はシンプルで、フォルダ名の正本を1か所に書いておくことです
プロジェクト直下の CLAUDE.md か、第1層で紹介した .claude/rules/ の中に書きます

## フォルダの決まり

- テストは tests/(複数形)に置く、test/ は作らない
- 画像は images/ に集約する、figures/ や screenshots/ は作らない
- 調べものは research/ に置く、materials/ は作らない
- 一時ファイルは tmp/ に置く、使い終わったら消してよい

新しいフォルダが必要になったら、勝手に作らず先に相談すること

ポイントは「使う名前」だけでなく「使わない名前」も書くこと
使わないほうを明記しておかないと、別の言い回しで頼んだときにまた作られます

そもそも .claude/rules/ という置き場が公式に用意されているのは、こういう決まりごとを書いておくためです
指示を一度書いておけば毎回読まれるので、同じ注意を繰り返さずに済みます

すでに散らかってしまった場合も、片付け自体を頼めます
「同じ役割のフォルダが複数ないか調べて、統合案を出して」と伝えると一覧にしてくれます、移動や削除は案を見てから自分で判断するのが安全です

ジャベ雄

使わない名前まで書く、これに気づくまで結構かかりました

そのまま使えるフォルダ構成テンプレート2種

ここまでの整理をふまえて、そのままコピーして使える形にしました
おすすめは最初から凝った構成にしないこと

公式ドキュメントも同じ立場で、まずは CLAUDE.md を1枚置くところから始めて、使いながら育てるやり方をすすめています
空のフォルダをいくつも先に作っても、結局は使われずに残るだけ

アプリ・ツールを作る場合

myapp/
├── CLAUDE.md          プロジェクトの決まりごと
├── README.md          このアプリが何なのかの説明
├── .claude/
│   ├── settings.json  権限などの設定
│   └── rules/         テーマ別の指示
├── src/               プログラム本体
├── tests/             動作確認のコード
├── docs/              仕様や手順の文書
├── assets/            画像やアイコンなどの素材
└── scripts/           補助的な小さいプログラム

第2層の慣習だけで組んだ構成
この形にしておけば、初めて見る人にも中身の見当が付きますし、AIも迷わず正しい場所に置いてくれます

dist や build をあえて入れていないのは、必要になったらツールが自動で作るからです
同じ理由で logs や tmp も先に用意しません、使う段になってから増やせば十分です

ブログや資料などを作る場合

myblog/
├── CLAUDE.md          文体や書き方の決まりごと
├── .claude/
│   ├── settings.json  権限などの設定
│   └── rules/         テーマ別の指示
├── articles/          記事の原稿
├── research/          下調べ・調査メモ
├── images/            画像
└── archive/           公開済み・使い終わったもの

コードを書かない使い方だと、src や tests は出番がありません
そのぶん第3層の名前を使うことになるので、どれを使うか先に決めておきたいところ

この構成では、調べものの置き場を research に寄せて materials は作らないことにしています
逆に materials 側に寄せてもかまいません、大事なのはどちらかに決めて書いておくことのほうです

ジャベ雄

迷ったら少なめに作る、足りなくなってから足せば十分です

消していいフォルダ・ダメなフォルダの見分け方

散らかったフォルダを片付けたくなったときの判断基準です
層ごとに扱いが違うので、まずはどの層かを見てから決めます

いちばん多いのは最後の「役割が分からない」です
この場合はフォルダを開いて、中に入っているファイルの拡張子と日付を見るのが早道
そのフォルダ、最後に更新されたのはいつでしょうか？

日付が古いまま止まっていれば、途中で使わなくなった置き場の可能性が高いでしょう
逆にここ数日の日付が並んでいるならいまも動いているということなので、消さずに残します

名前が同じでも中身が違うことがある

もうひとつ注意したいのが、同じ名前でも層が違うケースです
たとえば rules は .claude/ の中にあれば第1層ですが、プロジェクト直下に置かれていれば誰かが作った第3層かもしれません

判断の決め手は名前ではなく置かれている場所です
同じ名前を見つけたら、どの階層にあるのかを先に確認してください

templates や agents も同じように取り違えやすい名前です
.claude/ の外に出ていれば公式仕様とは無関係なので、消しても動作には響きません

消す前の安全弁

そのプロジェクトを Git で管理しているなら、消す前にひと手間かけておくと安心です
Claude に「このフォルダは Git で管理されているか調べて」と頼めば、裏で確認して教えてくれます

• Gitで管理されている → 消しても履歴から戻せる
• Gitで管理されていない → 消したら戻せない、先に別の場所へ退避する

ジャベ雄

迷ったら消さずに archive へ移す、これでたいてい間に合います

まとめ|3層に分ければフォルダ構成は読める

AIが作ったフォルダは、名前をひとつずつ覚えなくても大丈夫です
「誰が決めたのか」で3層に分ければ、初めて見るフォルダでも扱い方の見当が付くはずです

• 第1層(.claude/ の中)は公式仕様、名前を変えると効かなくなるので触らない
• 第2層(src ・ docs ・ tests など)は業界の共通語、慣習に合わせておくと読みやすい
• 第3層(materials ・ research など)は誰も決めていない、だから自分で決める
• 同義フォルダの増殖は、CLAUDE.md か .claude/rules/ に正本を書いて止める
• 消すときは層を確認してから、中身を見てから

最初の一歩としておすすめなのは、いま開いているプロジェクトのフォルダを眺めて、それぞれがどの層かを言ってみることです
言えなかったものが、そのまま整理すべき対象です

ちなみに CLAUDE.md も .claude/rules/ の中身も、すべてマークダウンという形式で書かれています
AIが書いた文書を読んだり直したりする機会は増える一方なので、記法を押さえておくとこのあたりの作業がぐっと楽になるはずです

あわせて読みたい

マークダウンの書き方入門 AIに伝わるmd記法まとめ マークダウン(Markdown)の書き方を初心者向けにまとめました チャットでよく使う基本記法から CLAUDE.md など AIが読むファイルで使う記法まで網羅し 素のMarkdownとGFM拡張の違いやよくある崩れの直し方まで解説しています

第1層で触れた skills や agents が実際に何をするものなのかは、Claude Codeの拡張機構をまとめた記事で解説しています
用語そのものが分からないときはClaude用語集もあわせてどうぞ

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

最近、AIの話題を追っていると「○○エンジニアリング」という言葉が次から次へと出てきませんか？
プロンプトエンジニアリングにコンテキストエンジニアリング、その名前に慣れてきたと思ったら今度はハーネスだのループだの、新しい言葉が後から後から増えていきます

どれも似た響きなので、どれが何を指すのか、お互いの違いがつかみにくいところです
名前は聞いたことがあるけれど、頭の中で整理がつかないまま、という方も多いのではないでしょうか

実はこれらの言葉、バラバラの流行り言葉ではなく1本の進化の流れの上に並んでいます
先にプロンプトがあって、そこへコンテキスト、さらにハーネス、ループ、グラフと、新しい言葉ほど後から積み重なってきた、という順番なんです

この記事は、その流れを1枚の地図として見渡す総論(ハブ)で、各テーマの詳しい回への入り口にもなっています
言葉を1つずつ暗記する必要はありません
大事なのは5つの位置関係で、それさえ頭に入れば、次に新しい用語が出てきても「あの流れのどこか」と見当がつくようになります

ジャベ雄

まず全体像をつかんでから、気になる回を読むのがおすすめです

まず結論 AIの使いこなしは5段階で進化した

結論から言うと、AIへの指示のしかたは プロンプト → コンテキスト → ハーネス → ループ → グラフ という順番で発展してきました
ざっくり言えば、設計する対象が内側から外側へ、だんだん広がっていく流れです

• プロンプト:AIに渡す1回分の指示文を作り込む
• コンテキスト:指示だけでなく、AIに見せる情報の全体を組み立てる
• ハーネス:AIを取り囲む道具立てやルールの土台を用意する
• ループ:AIが自分で回り続ける仕組みそのものを設計する
• グラフ:複数のAIをどう並べて、どうつなぐかを設計する

最初は「どう言葉をかけるか」だけを考えていたのが、だんだん「どんな環境を与えて、どう自走させるか」まで広がってきた、という話です
大きな方向性としては、単発のチャットから、自分で動く自律エージェントへの移り変わりと言えます

ここで気をつけたいのは、新しいものが古いものを消したわけではないという点です
後から出た考え方は、前の考え方を土台にして、その外側を足していくイメージで捉えると迷いません

5つのエンジニアリングを1枚で見渡す比較表

細かい解説に入る前に、まず全体を1枚の表で見比べてみましょう
「いつ登場したか」「何を設計するのか」「どれくらい定着しているか」を並べると、5つの関係が一気に見えてきます

表を縦に見ると、設計する対象が「指示文」から「情報全体」「土台」「動き続ける仕組み」「つなぎ方」へと外へ広がっているのが分かります
ここからは、1つずつ噛み砕いていきます

プロンプトエンジニアリング すべての出発点

プロンプトエンジニアリングは、AIに渡す指示文(プロンプト)を工夫して、ほしい答えを引き出す技術です
5つの中でいちばん歴史があり、土台になっている考え方です

広まったのは、GPT-3が登場した2020年前後だと言われています
その後、ChatGPTが2022年末に公開されて一般にも一気に浸透しました(誰が最初に名付けたかは諸説あるので、ここでは踏み込みません)

やることは、たとえば次のようなものです

• 「あなたは経理の担当者です」のように役割を与える
• 手順を番号で区切って、順番に考えさせる
• 出力の形(表・箇条書きなど)を先に指定しておく

具体的には、「悪い例」と「良い例」を1つずつ添えるだけでも、出力の質はぐっと安定します
短い指示でも、望む形を実例で見せてあげると、AIは狙いを外しにくくなります
こうした積み重ねが、今もプロンプトエンジニアリングの中心にあります

「もう凝ったプロンプトは要らない」という声も一部で聞きますが、なくてもAIがカバーしてくれる可能性が上がっただけで、実際には指示の作り込みは今でも効きます
プロンプトは古びたのではなく、次に出てくるコンテキストの一部として組み込まれたと捉えるのが正確です

コンテキストエンジニアリング プロンプトを包んで進化した

コンテキストエンジニアリングは、AIに見せる情報の全体を組み立てる設計です
1回の指示文だけでなく、AIが受け取る材料まるごとを対象にします

ここでいう「情報の全体」とは、AIが一度に読み込める作業スペース(コンテキストウィンドウ)に何を積むか、という話です
具体的には次のような中身を組み合わせます

• 役割や方針を伝えるシステムプロンプト
• 外部から引っ張ってきた参考資料(RAG)や社内文書
• これまでの会話の履歴や、覚えさせたメモ(メモリ)
• AIが使える道具(ツール)の一覧と、その実行結果

プロンプトとの違いは「置き換え」ではなく「包含」

ここが今回いちばん押さえたいポイントです
コンテキストエンジニアリングはプロンプトエンジニアリングを置き換えたのではなく、その中に含んで広げたものです

プロンプト(指示文)は、コンテキスト全体の中の一部分にあたります
つまりプロンプトはコンテキストの部分集合で、指示の良し悪しだけでなく「そもそも何を見せているか」まで含めて設計しよう、という発想の広がりなんです

たとえば「この議事録を要約して」と頼むとき、議事録の本文を渡さなければ、どれだけ指示を磨いても良い答えは返ってきません
逆に、関連する過去資料や用語の定義まで一緒に渡せば、指示はシンプルなままでも精度が上がります
これがコンテキストを設計するということです

ただし、情報は多ければ多いほど良いわけではありません
関係ない資料まで詰め込むと、かえってAIが迷って精度が落ちることもあります
だからコンテキストエンジニアリングは「何を足すか」だけでなく「何を削るか」の設計でもあるんです

この言葉が広まったのは、わりと最近です
ShopifyのCEOであるTobi Lütke(トビ・リュトケ)氏が2025年6月ごろに使い始めたのが起点とされ、AI研究者のAndrej Karpathy(アンドレイ・カルパシー)氏が賛同して一気に広まりました

その後、Anthropic(Claudeの開発元)も2025年9月に体系立てた解説を出し、コンテキストエンジニアリングをプロンプトエンジニアリングの自然な進化だと位置づけています
くわしくはAnthropic公式の解説も参考になります

個人的な話をすると、私がClaude Codeを使うときも、この感覚はよく実感します
作業フォルダに CLAUDE.md という前提メモを置いておくと、毎回こまかく指示しなくても、狙った方向で動いてくれる確率がぐっと上がるんです

ジャベ雄

指示を盛るより、前提を先に渡しておくほうが効くと感じています

用語の意味だけをサッと確認したいときは、AI用語集もあわせてどうぞ

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

ハーネスエンジニアリング モデルを取り囲む土台

ハーネスエンジニアリングは、モデル本体を除いた、AIを取り囲むソフトウェアの土台を設計するという考え方です
「ハーネス(harness)」はもともと、馬具や安全帯のように本体を支える装具を指す言葉です

ここでいう土台には、次のようなものが含まれます

• AIが使うツールの統合(ファイル操作・検索・外部サービス連携など)
• 作業の途中経過を覚えておくメモリや状態の管理
• 失敗したときにやり直す検証と回復の仕組み
• 触ってよい範囲を制限する権限のガードレール

この関係を、界隈ではよく Agent = Model + Harness と表します
つまりエージェント(自分で作業するAI)は、モデルという頭脳と、それを取り囲む土台(ハーネス)を合わせたものだ、という整理です

身近な例でいうと、Claude Code Desktop がこの土台込みの仕組みにあたります
裏でファイルを読んだり、コマンド(プログラムへの命令)を走らせたり、失敗したらやり直したり、という一連の動きは、モデル単体ではなく、その周りの土台がこなしています

Anthropicも、Claude Codeと同じ仕組みを Claude Agent SDK として公開し、これを「汎用のエージェントハーネス」と呼んでいます
ハーネスという語そのものは、こうした公式ドキュメントでも使われている実在の言葉です

おもしろいのは、同じモデルでも土台の出来しだいで成績が変わる点です
AIの実力を測るベンチマーク(SWE-bench系)でも、モデルはそのままで土台を差し替えただけでスコアが動いた、という報告があります
ただし作り込むほど強いとは限らず、100行ほどの最小構成が高機能な土台を上回った例もあります
土台の設計で何が効くのかは、Anthropicのハーネス解説がくわしいです

エージェントの土台をもう少し具体的に知りたい方は、Claude Code拡張機構入門で、ツールや設定の仕組みを噛み砕いています

ループエンジニアリング AIを自走させる仕組み

ループエンジニアリングは、AIが繰り返し動き続ける仕組みそのものを設計するという考え方です

土台になっているのは「エージェントループ」という概念です
これは考える → 道具を使う → 結果を見る → また動くを、終了条件にたどり着くまで繰り返す動きのことで、ざっくり言えば「道具を持ったAIをぐるぐる回し続ける」イメージです

この繰り返しの考え方自体は前からあります
ループエンジニアリングは、その回し方を設計対象として名前を付けたもので、次のようなところを組み立てます

• ループを始める引き金(トリガー)をどう設けるか
• いつ止めるかの停止ルール
• 途中で結果をチェックする検証の仕組み

身近な例だと、プログラムのバグ直しがイメージしやすいです
コードを直す → テストを走らせる → 失敗を見てまた直す、をテストが通るまで自動で繰り返す、という流れをAI自身に回させるのがループの設計です

Anthropicの開発者を含む書き手がよく口にするのが「エージェントにプロンプトを出すのをやめて、エージェントにプロンプトを出すループのほうを設計しよう」という言い回しです
あなたが毎回指示を出すのではなく、指示を出し続ける仕組みを作るという発想の転換なんです

ハーネスとの関係も、まだ整理しきれていません
「ループはハーネスの一部」とする見方が多い一方で、「ループはハーネスに調整される別のもの」とする見方もあり、この2つは重なり合う領域があると捉えておくのが実態に近いです

さらに進むと、1つのループだけでなく、複数のループを組み合わせる話になります
調べる担当・書く担当・チェックする担当のように、役割ごとのループを重ねて大きな仕事をこなす設計です
これが次のグラフエンジニアリングにつながります

ジャベ雄

新しい言葉なので、断定より「そういう流れが来ている」くらいで追うのが安全です

グラフエンジニアリング 複数のAIをつなぐ最新の層

グラフエンジニアリングは、複数のAI・ツール・人の承認を、つなぎ方まで含めて設計するという、5つの中でいちばん新しい考え方です
担当を点(ノード)、受け渡しを線(エッジ)、そのあいだを流れる情報を状態と呼んで組み立てます

ただし、ここまでの4つとは少し性格が違います

ループが消えるわけではありません
1体のAIが回している輪が、そのままグラフの1つの点に収まります
置き換えではなく、外側に一枚かぶさったと読むのが正確です

この言葉が一気に広まったのは2026年7月18日で、きっかけは冗談の投稿でした
ただ2週間前の7月4日に真面目な論考が出ていて、順番としては論考のほうが先です

言葉が新しくても、中身まで新しいとは限りません
グラフでエージェントを組む道具は2024年1月の LangGraph まで遡れるので、実装のほうが言葉より2年半ほど早いことになります

ジャベ雄

担当が1人で済む作業なら、そもそも線を引く必要はありません

結局この5つはどう違うのか

最後に、5つの違いを一言でまとめておきます
キーワードは「設計する対象が、内から外へ広がっていく」という一点です

• プロンプト=指示文という「言葉」を設計する
• コンテキスト=AIに見せる「情報の全体」を設計する
• ハーネス=AIを取り囲む「土台」を設計する
• ループ=AIが動き続ける「仕組み」を設計する
• グラフ=複数のAIをつなぐ「編成」を設計する(ここだけ1体でなく複数体の話)

Claude関連の用語をもう少し押さえたい方は、Claude用語集(初心者向け)もあわせてどうぞ
この地図を頭に入れておくと、新しい言葉が出てきても「5つのどこの話か」で位置づけられるようになります

本シリーズの他の記事

この総論(ハブ)から、5つそれぞれを掘り下げた個別記事へ進めます
気になったテーマから読んでみてください

• プロンプトエンジニアリング入門:指示文の作り込みの基本
• コンテキストエンジニアリングとは:AIに見せる情報の設計
• ハーネスエンジニアリングとは:エージェントの土台づくり
• ループエンジニアリングとは:AIを自走させる仕組み
• グラフエンジニアリングとは:複数のAIをつなぐ編成

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

プロンプトエンジニアリングとは、AIへの指示文(プロンプト)を工夫して、狙った答えを引き出す技術です
この記事では初心者向けに、プロンプトエンジニアリングの書き方を、そのままマネできる例つきで手を動かしながら学べるように整理しました

ChatGPTやClaudeに同じことを頼んでいるのに、人によって返ってくる答えの出来が違う そんな経験はありませんか？
その差の多くは、AIの性能ではなく頼み方から生まれています

難しい理論はいったん脇に置いて、まずは今日から書き方を変えられる5つのコツと、コピペで試せるプロンプト例を見ていきます

ジャベ雄

特別なツールは要りません いつものチャット欄に打ち込む文章を、ちょっと変えるだけです

プロンプトエンジニアリングとは 書き方の前に押さえる基本

結論から言うと、プロンプトエンジニアリングはAIに渡す指示文を設計して、望む出力を引き出す技術です
ここでいうプロンプトは、チャット欄に打ち込むあの文章そのものを指します

AIの中身(大規模言語モデル、いわゆるLLM)は、渡された文章の続きを確率的に予測して返す仕組みで動いています
だから入力の言葉が変わると、予測の方向も変わり、出てくる答えの質も大きく動くわけです

言葉の意味を先に押さえたい方は、AI用語集やClaude用語集も合わせてどうぞ
この記事は用語よりも、実際に手を動かす書き方に振っていきます

なぜ書き方で答えが変わるのか

たとえば「文章を書いて」とだけ頼むと、AIは相手の意図を推測で埋めるしかありません
誰に向けた文章なのか・何文字くらいか・どんなトーンか、そのあたりが空欄だと、AIは無難で平均的な答えを返してきます

料理に置き換えると分かりやすいです
「なんか作って」と「30分で作れる和食の副菜を1品」では、返ってくるものが全然違いますよね AIへの指示もまったく同じで、渡す条件が細かいほど、相手は動きやすくなります

逆に条件を具体的に添えると、AIは推測する範囲が狭まり、狙いに近い出力を出しやすくなります
つまりプロンプトの書き方は、AIに考える材料をどれだけ渡せるかという話なんです

いつ生まれた言葉なのか

プロンプトエンジニアリングという考え方は、GPT-3(2020年ごろ)の登場前後にAI界隈で広まったとされています
正確な命名者や初出は諸説あって、はっきりしていません その後ChatGPTの公開(2022年)で一気に一般にも知られる言葉になりました

プロンプトエンジニアリングの書き方 5つの基本テクニック

ここからが本題です
プロンプトの書き方は、細かいテクニックを挙げればきりがありませんが、初心者がまず押さえるべきは次の5つに絞れます

順番に手を動かせるよう、ステップ形式でまとめました
1つずつ足していくだけで、プロンプトの精度が変わってくるのが分かるはずです

ジャベ雄

全部いっぺんに覚えなくて大丈夫です まずは1つ目の「具体化」だけでも効果を感じられます

曖昧なプロンプトと改善後を見比べる

言葉で説明するより、ビフォーアフターで見たほうが早いです
左のような雑な頼み方を、右のように書き換えるだけで、返ってくる答えの質が変わります

やっているのは「誰に・何を・どんな形で」を足しているだけです
特別な言い回しは要りません 頭の中にある前提を、そのまま言葉にして渡すイメージで書けば大丈夫です

5つのコツを1つにまとめたテンプレート

毎回ゼロから考えるのは大変なので、使い回せる型を用意しておくと楽です
山カッコの部分を埋めるだけで、5つのコツがほぼ入った状態になります

# 役割
あなたは<職業・立場>です。

# お願い
<やってほしいこと>

# 条件
- 対象読者: <誰向けか>
- 目的: <何のためか>
- 文字数: <目安>
- トーン: <硬さ・やわらかさ>

# 出力形式
<箇条書き / 表 / 見出し付き など>

全部の欄を埋める必要はありません
要らない欄は削って、足りない部分だけ書き足すくらいの気軽さで使ってみてください

そのままマネできるプロンプト例

コツを言葉で読んでも、いざ書くとなると手が止まりますよね
ここでは、さっきの5つを組み合わせたプロンプト例をいくつか置いておきます コピペして、山カッコの部分を自分の内容に置き換えて使ってみてください

例1 ビジネスメールの下書き

役割・具体化・形式指定を全部入れた、実務でそのまま使える形です

あなたは丁寧な文章が得意なビジネスパーソンです。
次の内容で取引先へのメールを作成してください。

# 目的
納品が3日遅れる旨のお詫びと、新しい納品日の連絡

# 条件
- 相手: 取引先の担当者(あまり親しくない)
- トーン: 丁寧だが硬すぎない
- 文字数: 250字前後
- 件名も付ける

例2 長い文章の要約

要約は「どう縮めるか」を指定しないと、ただ短くしただけの答えになりがちです
読む相手と形式を添えるのがコツになります

あなたは要点整理が得意な編集者です。
以下の文章を、忙しい上司が30秒で把握できるように要約してください。

# 出力形式
- 冒頭に結論を1文
- そのあと箇条書きで要点を3つ
- 専門用語は簡単な言葉に言い換える

# 対象の文章
<ここに要約したい文章を貼る>

例3 例を見せて分類させる(few-shot)

4つ目のコツ、お手本を渡す書き方の例です
入力と出力のセットを2組見せてから、本番の入力を渡します

次の問い合わせ文を「質問 / 要望 / クレーム」のどれかに分類してください。

例:
入力「使い方が分かりません」→ 質問
入力「もっと安くしてほしい」→ 要望

本番:
入力「注文した商品がまだ届きません、いつになりますか」→

お手本を2つ見せるだけで、AIは同じ形式(「〜→ 分類名」)で答えを返してきます
分類・変換・書式そろえのような作業は、この few-shot が特に効きます

例4 アイデア出しの壁打ち

正解が1つに決まらない相談も、条件を添えると精度が上がります
ポイントは出す数と切り口を指定することです

あなたは企画のプロです。
新しい家計簿アプリのキャッチコピーを10個提案してください。

# 条件
- ターゲット: 一人暮らしの20代
- トーン: 親しみやすく、少しユーモアを入れる
- 各案に、狙いを一言添える

数を多めに出させて、その中から良いものを選ぶ
この質より量で出させて選ぶやり方は、アイデア出しと相性が良いです

例5 エラーメッセージの意味を調べる

プログラムやExcelでエラーが出たとき、メッセージをそのまま貼って聞くと解決が早いです
役割を与えつつ、答えの形を原因→対処の順で指定するのがコツになります

あなたはプログラミング初心者に教えるのが得意なエンジニアです。
次のエラーの原因と対処法を、初心者にも分かる言葉で教えてください。

# 出力形式
- まず原因を1〜2文で
- そのあと対処の手順を箇条書きで
- 専門用語には短い説明を付ける

# エラー内容
<ここにエラーメッセージを貼る>

ここで効くのが、エラー文を省略せず全文を貼ることです
行番号やファイル名まで含めて渡すと、AIは状況を具体的につかめて、的外れな回答が減っていきます

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

プロンプトを書くときのよくある失敗とコツ

書き方のコツを足していく一方で、避けたい書き方もあります
私も最初のころ、つい欲張ってAIを混乱させていました よくあるつまずきを対比で並べておきます

覚えておきたいのは、プロンプトは一発勝負ではないという点です
最初の答えが微妙でも、そこから「もう少し短く」「専門用語を減らして」と会話で調整していけば、狙いに近づけていけます

悪い例と良い例をプロンプト全文で見比べる

丸投げのプロンプトと、条件を添えたプロンプトを全文で並べてみます
同じ「会議メモをまとめたい」でも、渡す情報の量で仕上がりがここまで変わります

この会議のメモ、いい感じにまとめて。
(誰が読む・どんな形式・何を残すかが、まるごと空欄)

これだと、AIは長さも形式も推測で埋めるしかありません
次のように読者・目的・形式を足すだけで、そのまま配れる議事録にぐっと近づきます

あなたは議事録づくりが得意なアシスタントです。
次の会議メモを、参加できなかった人が読んで分かる議事録にしてください。

# 出力形式
- 決定事項を箇条書きで
- 次にやること(担当者と期限つき)を箇条書きで
- 最後に未解決の論点を1〜2行で

# 会議メモ
<ここに会議のメモを貼る>

やっているのは、AIに考えさせる部分を減らしてこちらが決めた枠を渡すことです
「あとで自分が手直しする作業」を、先にプロンプトへ書いておくイメージですね

プロンプト単体の限界 次はコンテキストエンジニアリングへ

ここまでのコツを使えば、単発の依頼はかなり思い通りになります
ただプロンプトの書き方だけでは、どうしても届かない場面も出てきます

たとえば過去のやり取りを覚えておく・社内の資料を参照する・外部のツールを呼び出すといった動きは、1つのプロンプト文だけでは扱いきれません
プロンプトはあくまで「AIに渡す指示のかたまり」で、その外側の情報や仕組みまでは面倒を見られないんです

身近な例だと、自分だけのマニュアルをAIに読ませて答えさせたいとき、その資料をどうやって渡し続けるかは、プロンプトの書き方とは別の話になります
ここから先はプロンプトの外側の設計が主役になっていくわけです

そこで最近は、指示文そのものだけでなく、AIに渡す情報全体をどう組み立てるかを設計する考え方に広がってきました
これが冒頭でも触れたコンテキストエンジニアリングで、会話履歴・参照資料・ツールの実行結果まで含めて、AIに渡す材料を丸ごとデザインしていく発想です

プロンプトエンジニアリングは、その土台にあたる第一歩です
まずはこの記事の書き方で手を慣らして、次のステップとして「情報の渡し方全体」へ進んでいく、という流れがつかみやすいと思います

ジャベ雄

プロンプトが土台、コンテキストがその上の階です 順番に登っていけば大丈夫です

次の一歩は、プロンプトの外側にある情報の設計です
同じく初心者向けにまとめているので、あわせてどうぞ

あわせて読みたい

コンテキストエンジニアリングとは AIに渡す文脈の設計 コンテキストエンジニアリングとは AIのコンテキストウィンドウに何を積むかを設計する考え方です プロンプトエンジニアリングとの違いや システムプロンプト RAG メモリ CLAUDE.md など構成要素を初心者向けに噛み砕いて解説します

プロンプトエンジニアリングのよくある質問

書き方を試す前に気になりやすい点を、Q&Aでまとめておきます

まとめ 本シリーズの他の記事

プロンプトエンジニアリングの書き方を、5つのコツと例で見てきました
最後に要点だけおさらいします

• 指示は具体化する(読者・目的・形式・トーンを添える)
• 役割を与えて、答えの視点をそろえる
• 出力の形式を先に指定して、手直しを減らす
• 言葉で難しければ、お手本(few-shot)を見せる
• 大きな依頼は分割して、会話で育てる

まずは1つ目の「具体化」から試して、慣れてきたら残りを足していくのがおすすめです
プロンプトの書き方が身についたら、その先のコンテキストエンジニアリングへ進むと、AIとの付き合い方がもう一段広がります

本シリーズの他の記事

この記事は「AIの◯◯エンジニアリング」進化ラダー連載の第1回(基礎)です
全体像と続きは、以下からたどれます(公開しだいリンクが有効になります)

• 連載ハブ AIの5つの「◯◯エンジニアリング」総まとめ
• 第1回(この記事) プロンプトエンジニアリングの書き方
• 第2回 コンテキストエンジニアリング
• 第3回 ハーネスエンジニアリング
• 第4回 エージェントループの設計(ループエンジニアリング)
• 第5回 グラフエンジニアリング(複数のAIをつなぐ)

用語をまとめて確認したいときは、AI用語集もどうぞ
この連載を通して読むと、AIへの頼み方が「指示」から「設計」へと変わっていくのが見えてくるはずです

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

コンテキストエンジニアリングとは、AIに渡す情報(コンテキスト)全体をどう組み立てるかを設計する考え方です
プロンプトの言い回しを磨くプロンプトエンジニアリングの先にある、いま急速に広まっているテーマなんです

AIに仕事を頼んで、指示じたいは悪くないはずなのに答えがズレる
そんなとき、原因は聞き方よりAIに渡している情報そのものの側にあることが多いです

この記事では、コンテキストエンジニアリングとは何かを、プロンプトエンジニアリングとの違い・具体的な構成要素まで初心者向けにまとめます
読み終えるころには、次の3つがつかめているはずです

• コンテキストエンジニアリングの意味:AIに何を渡すかの設計だと分かる
• プロンプトとの違い:どちらが上位で、なぜ置き換えではないのか
• 6つの構成要素:コンテキストに積むものを1つずつ噛み砕く

ジャベ雄

ざっくり言うと「AIの机の上に何を並べておくか」を考える話です

コンテキストエンジニアリングとは?まず全体像

結論から言うと、コンテキストエンジニアリングとは、AIが一度に読み込む情報のかたまり(コンテキスト)に、何をどう積むかを設計する技術です
単発の指示文だけでなく、AIが答えを作るために参照する材料をぜんぶひっくるめて整える、という捉え方なんです

AI(正確にはLLM=大規模言語モデル、文章を予測して作るAIの中身)は、渡された材料をもとに次の一手を組み立てます
だから材料が薄かったり、ノイズだらけだったりすると、聞き方をどれだけ工夫しても答えが決まりきらないんです

ここで前提になるのがコンテキストウィンドウという言葉です
下のメモにまとめておきます

Claudeの開発元である Anthropic は、コンテキストエンジニアリングをプロンプトエンジニアリングの自然な発展形と位置づけています
プロンプトを捨てる話ではなく、プロンプトも材料のひとつとして、コンテキスト全体を面倒みる、という広げ方なんです

もう少し身近にたとえると、新しく入ったメンバーに仕事を任せる場面に近いです
どれだけ優秀な人でも、必要な資料や過去の経緯を渡さなければ良い動きはできません
コンテキストエンジニアリングは、AIに対してこの「引き継ぎ資料の準備」を丁寧にやる作業だと考えると、とっつきやすいはずです

ここまでの話を1枚の図にすると、こんなイメージになります
窓というひとつの器を、性格の違う6種類の情報が分け合っている、という構図で見てもらえると分かりやすいはずです

なぜいま生まれた言葉なのか

コンテキストエンジニアリングは、2025年に一気に広まった比較的あたらしい言葉です
ざっくりした流れをおさえておくと、単なるバズワードではなく背景のある概念だと分かります

• 提唱:Shopify CEO の Tobi Lütke 氏が2025年6月ごろ、「LLM がタスクを解けるだけの文脈をぜんぶ渡す技術」として言い出したのが起点とされます(正確な日付は諸説あり、ここでは断定しません)
• 拡散:AI研究者の Andrej Karpathy 氏が同じ時期に賛同し、言葉として一気に広まりました(命名者というより後押し役の立場です)
• 体系化:Anthropic が2025年9月に「Effective context engineering for AI agents」で整理し、実務の枠組みとして定着させました

背景にあるのは、AIの使い方が単発の質問から自分で何ステップも作業するエージェントへ移ってきたことです
1往復で終わって、必要な前提もその場で書き添えられる用事なら、うまい聞き方でだいたい足ります

ところが、AIが道具を使って何度も往復しながら進むようになると、途中でどんな情報を持たせ続けるかが結果を左右します
この「持たせ続ける材料の設計」に名前がついたのが、コンテキストエンジニアリングなんです

ジャベ雄

AIが「単発の相棒」から「作業する部下」に変わったから、渡す資料の設計が要る、という流れです

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

ここが多くの人のつまずきどころなので、プロンプトエンジニアリングとの違いを表で整理します
ポイントは、片方がもう片方を置き換えるのではなく、プロンプトはコンテキストの一部という包含の関係だという点です

「プロンプトエンジニアリングはもう古い」という煽りを見かけますが、そこは冷静に受け止めたいところです
実務では指示文の作り込みはいまも必要で、コンテキストという大きな器の中でプロンプトが担う役割が明確になった、と捉えるのが無理のない理解なんです

言い換えると、聞き方(プロンプト)を磨くのは点の改善、渡す材料ぜんぶ(コンテキスト)を設計するのは面の改善です
点をいくら磨いても面が崩れていると結果は安定しないので、両方を行き来する感覚が実用的です

たとえば「この関数のバグを直して」と頼む場面を考えます
プロンプトの工夫は、頼み方を「エラー内容も添えて原因から説明して」と具体的にすること
コンテキストの設計は、そもそも該当のコードやエラーログ・関連する仕様まで一式を渡しておくことです
後者が抜けていると、聞き方をどれだけ整えても的外れな答えになりがちなんです

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

コンテキストに積む6つの構成要素

では、コンテキストには具体的に何が入るのか?
代表的なものを6つの構成要素に分けて、1つずつ噛み砕きます

• システムプロンプト:AIの役割やルールを決める土台の指示、「あなたは○○の担当です」のような前提
• ツール定義と実行結果:AIが使える道具(検索・ファイル読み書きなど)の説明と、実際に動かした結果
• RAG(外部知識の検索):手元の資料やデータベースから関連情報を引っぱってきて渡す仕組み
• メモリ:過去のやり取りやユーザーの好みを覚えておいて、あとで再利用する情報
• 会話履歴:ここまでの往復のログ、いま何を話しているかの流れ
• エージェント状態:いま何の作業の途中か、次に何をする予定かという進行の記録

この6つが、同じひとつのコンテキストウィンドウ(限られた窓)を分け合います
だからこそ、何を厚く積んで何を削るかの配分の判断が、コンテキストエンジニアリングの中身になるわけです

6つのうち、初心者がイメージしにくいのはツール定義と実行結果・エージェント状態あたりでしょうか?
前者は「AIが検索や電卓を使えるように渡す取扱説明書とその使用結果」、後者は「作業のしおり(いまどこまで進んだか)」だと思うと近いです

言葉の説明だけだとイメージしにくいので、実際にどんな中身が窓に載るのかをミニ例で並べてみます
同じ「情報」でも、要素ごとに質がぜんぜん違うのが伝わるはずです

こう並べると、6要素は「知識(RAG)」「記憶(メモリ)」「いまの流れ(会話履歴)」のように役割が分かれていると分かります
ぜんぶ同じ袋に放り込むのではなく、種類ごとに何をどれだけ載せるかを考えるのが、コンテキスト設計の勘どころなんです

RAG(外部知識の検索)とは

初めて聞く方向けに、RAGだけ少し補足します
RAG(Retrieval-Augmented Generation)とは、AIが答える前に関連資料を検索し、それを取り込んでから答えを作る仕組みです

AIの中身が最初から知っていることには限りがあり、社内マニュアルや最新の情報までは覚えていません
そこで、外から必要な資料を引っぱって窓に載せてあげると、AIはその場で参照しながら答えられます

身近な例だと、手元のPDFを読ませて質問に答えてもらう使い方がRAGの発想に近いです
言葉としてのRAGや周辺用語はAI用語集にもまとめているので、あわせてどうぞ

メモリと会話履歴の違い

メモリと会話履歴は似ていますが、役割が少し違います
会話履歴は「いまのやり取りの流れ」、メモリは「別の機会にも持ち越したい情報」というイメージです

会話が長引くと履歴が増えて窓を食いつぶすので、要約して圧縮するのもコンテキスト設計の一部です
全部を抱え込むより、要るものだけ残す引き算のほうが、じっさいには効いてきます

コンテキストは多いほどいいわけではない

ここまで読むと「とにかく情報を積めば安心」と思えますが、そこは落とし穴です
窓には上限があるうえ、関係ない情報が混ざると、AIがどこを見ればいいか迷って精度が落ちます

Anthropic も、コンテキストで大事なのは量ではなくその一手にとって過不足のない情報だと強調しています
だから実務では、足す設計と同じくらい、要らないものを削る・要約する設計が効いてきます

具体的には、窓に情報を詰め込みすぎると次のような実害が出ます
どれも「たくさん渡したのに、かえって精度が落ちた」という形で表れるのがやっかいなところです

• 古い情報の混入:更新前の仕様と最新版を両方渡すと、AIがどちらを正として答えればいいか迷う
• トークンの浪費:使わない資料まで窓の席を占めるぶん、肝心のやり取りに割ける余白が減っていく
• 精度の低下:関係の薄い情報が増えるほど、AIが要点を見失って答えがぼやけやすくなる

だから上限ギリギリまで詰めるより、その一手に要らない資料は思い切って外すほうが、結果的に答えが安定します
足し算より引き算のほうが効く場面は、じっさいに手を動かすとよく出くわします

「agent failures = context failures」という見方

コンテキストエンジニアリングを語るとき、よく引かれる整理があります
それがagent failures = context failuresという見方です

これは、エージェント(自分で作業するAI)の失敗の多くは、モデルの頭が悪いからではなくコンテキストの失敗が原因だ、という捉え方です
渡すべき情報が抜けていた、古い情報が混ざっていた、ノイズが多すぎた、といった材料側のほころびが結果を崩す、というわけなんです

この見方の便利なところは、AIがコケたときに直す先が具体的になる点です
「なんか賢くしてほしい」ではなく、「どの材料が足りなかったか」を点検すればいい、と切り分けられます

ジャベ雄

私も「AIが悪い」と思った失敗の大半は、渡す情報の抜けが原因でした

Claude Code の CLAUDE.md はコンテキストエンジニアリングの実例

抽象的な話が続いたので、私が日常的に触れている実例を挙げます
それが、AI開発ツールのClaude Codeで使うCLAUDE.mdというファイルです

CLAUDE.md は、プロジェクトの決まりごとをまとめておく設定ファイルで、AIが作業を始めるときに読み込みます
私はここに、使う言葉づかいのルールや、触ってほしくないファイル、フォルダの構成などを書いておくんです
ただし CLAUDE.md はAIへのお願いを書く場所で、アクセスを止める仕組みではありません
本当に触らせたくないファイルは、権限の設定側(settings.json の permissions.deny)で止めておくのが安全です

これはまさにコンテキストエンジニアリングそのもので、毎回おなじ前提を打ち直す代わりに、AIが読み込むコンテキストを先に整えておく、という発想です
先ほどの6要素で言えば、システムプロンプトやメモリに近い役割を、1枚のファイルで担わせている感じです

私の場合、CLAUDE.md を整えるほどに、指示が短くても意図どおり動いてくれるようになりました
逆に、ここが薄いと同じ説明を何度も繰り返すことになり、それこそ先ほどの「context failures」を自分で作ってしまいます

具体的には、CLAUDE.md を用意する前は「ですます調で、句点は控えめに」と毎回説明していたことが、いまは一言も添えずに文体がそろいます
渡す前提を一度ファイルに固定するだけで、往復のたびに積もっていた手間がまとめて消えた感覚です

CLAUDE.md をはじめとした設定ファイルの種類はClaude Code 設定ファイル早見表に、ツール全体の仕組みはClaude Code 拡張機構入門にまとめています
コンテキストの設計を手を動かして体感したい方は、そのあたりから触ってみるのがおすすめです

まとめ 次はハーネスエンジニアリングへ

コンテキストエンジニアリングとは、AIに渡すコンテキストウィンドウ全体に何を積むかを設計する技術でした
プロンプトを置き換えるものではなく、プロンプトを内側に含む上位の設計だと押さえておくと迷いません

• コンテキスト=AIが一度に読み込む材料のかたまり、窓には上限がある
• 積む要素は システムプロンプト・ツール・RAG・メモリ・会話履歴・状態 の6つ
• AIの失敗はcontext failuresとして捉えると直す先が具体的になる
• CLAUDE.md は身近なコンテキストエンジニアリングの実例

ここまでで「何を渡すか」の設計は見えてきました
すると次に気になるのが、そのコンテキストを実際に出し入れしたり、道具を動かしたりするAIの周りの仕組みぜんぶです

そこを扱うのが、次回のハーネスエンジニアリングです
コンテキストを含めてAIを取り囲むソフトウェア基盤の話に進みます

あわせて読みたい

ハーネスエンジニアリングとは AIの外殻を設計する話 ハーネスエンジニアリングとは モデル本体を取り囲む外殻(ツール統合・メモリ・状態・コンテキスト管理・ループ・検証・権限)を設計する新しい考え方です Agent=Model+Harnessという定式や scaffold との呼び分け Claude Code が実例である理由を初心者向けにまとめました

連載「AIの○○エンジニアリング」の記事一覧

• 総まとめ(ハブ):AIの○○エンジニアリング5種
• #1 プロンプトエンジニアリング(前回)
• #2 コンテキストエンジニアリング(この記事)
• #3 ハーネスエンジニアリング(次回)
• #4 ループエンジニアリング
• #5 グラフエンジニアリング

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

AIエージェントまわりの話題で、2026年に入ってから急に見かけるようになった言葉があります
それがハーネスエンジニアリングです

ざっくり言うと、AIモデル本体ではなく、その周りを取り囲む”足場”を設計するという考え方です
ハーネスエンジニアリングとは何なのか、なぜ今この言葉が広まっているのかを、初心者向けにかみ砕いて整理してみます

この記事は「AIの○○エンジニアリング」連載の3本目です
前回はコンテキストをどう積むかという話でしたが、今回はそのコンテキストを積んだり道具を渡したりする外側の仕組みそのものに目を向けます

前回のおさらいをしたい方は、こちらもどうぞ

あわせて読みたい

コンテキストエンジニアリングとは AIに渡す文脈の設計 コンテキストエンジニアリングとは AIのコンテキストウィンドウに何を積むかを設計する考え方です プロンプトエンジニアリングとの違いや システムプロンプト RAG メモリ CLAUDE.md など構成要素を初心者向けに噛み砕いて解説します

ジャベ雄

「モデルが賢い」だけでは説明できない部分の話です

ハーネスエンジニアリングとは?ざっくり言うと

結論から言うと、ハーネスエンジニアリングとは、AIモデル本体をのぞいた「モデルを取り囲むソフトウェア基盤全部」を設計する営みのことです
ツールをつなぐ・途中経過を覚える・入力欄に何を載せるか・失敗したら立て直す、といった裏方の仕組みをまとめて指します

ハーネス(harness)という英単語は、もともと馬具や、登山・パラシュートで体を支える装具を意味します
暴れる馬や高所の体を、道具でしっかり支えて安全に働かせる、そんなニュアンスの言葉です

AIの世界では、この言葉が「賢いけど、そのままだと何もできないモデル」を実際に仕事させるための装具一式という意味で使われます
モデルは頭脳、ハーネスは体や道具や段取り、というイメージが近いです

ここで大事なのは、モデルとハーネスは別モノという点です
同じモデルでも、取り囲むハーネスの出来しだいで、できる仕事の質はかなり変わってきます

この「同じ頭脳なのに、周りの装具で結果が変わる」という感覚が、ハーネスエンジニアリングの一番の勘どころです
あとの章で、その中身を具体的に見ていきます

なぜ2026年に「ハーネス」が主流の言葉になったのか

この言葉がここまで広まった背景には、AIの作り方をめぐる言葉の進化ラダー(はしご)があります
ざっくり言えば、注目される設計対象が少しずつ外側へ広がってきた、という流れです

• プロンプトエンジニアリング:指示文(プロンプト)そのものを工夫する段階
• コンテキストエンジニアリング:入力欄ぜんぶに何を積むかを設計する段階(前回のテーマ)
• ハーネスエンジニアリング:そのコンテキストを扱う外側の仕組みごと設計する段階(今回)

指示文 → 文脈 → 外殻、と設計する範囲がだんだん広がってきたわけです
2026年に入って、この一番外側の「外殻(ハーネス)」に注目が集まった、というのがおおまかな流れになります

背景には、2026年ごろから長く動き続けるエージェントが実用になってきた、という事情もあります
数十分から数時間かけて自律的に作業させると、途中でつまずいたり脱線したりが増えるので、それを支える外側の仕組みの出来が、そのまま成果を左右するようになってきたわけです

「ハーネス」という語自体は公式も使っている

ハーネスという語自体は、一部の界隈で使われているような言葉ではありません

Claude を開発する Anthropic は、2025年11月に公開した記事で、自社のClaude Agent SDK(エージェントを作るための開発キット)を “a general-purpose agent harness”(汎用のエージェントハーネス)とはっきり呼んでいます
つまり「モデルを取り囲む装具」という意味でのハーネスは、公式の文書にも登場する実在の用語です

一次ソースを確認したい方はこちらです
Effective harnesses for long-running agents(Anthropic・英語)

「独立した分野」と呼ぶのは新しめのフレーミング

一方で、「ハーネスエンジニアリング」を一つの独立した専門分野として名指す言い方は、2026年になって広まった新しめの枠づけです
ベンダーのブログや技術記事から広がったフレーミングで、教科書に載っている確立した分類とはまだ言えません

「2024年はプロンプト・2025年はコンテキスト・2026年はハーネス」といったキャッチフレーズも見かけます
これは分かりやすい世代論として語られているだけで、公式に定められた区分ではない、という点は押さえておきたいです

ジャベ雄

語じたいは実在・分野名としては新興、この温度感で読むと安全です

ハーネス(外殻)は大きく6つの部品でできている

ハーネスと言われても、中身が見えないとピンとこないと思います
ここでは、モデルを取り囲む外殻を6つの部品に分けて見てみます

この6つのうち、コンテキスト管理を掘り下げたのが前回のコンテキストエンジニアリングでした
そして次回は、オーケストレーションループを掘り下げるエージェントループの回になります

連載でバラバラに見えていたテーマが、実はハーネスという一つの外殻の部品どうしだった、という見取り図です
今回はその外殻の全体像を押さえておく、という位置づけになります

モデルが賢いのではなく、外殻が賢さを引き出す

ここがこの記事で一番伝えたいところです
モデルの地力だけで決まるのではなく、周りの足場が賢さを引き出しているという見方です
効いているのはモデルと足場の両方で、そのうち足場の側の働きが見落とされがちだと思っています

たとえば同じ人でも、道具も資料も何もない部屋に放り込まれたら、実力を出しきれません
逆に、必要な資料・使い慣れた道具・失敗しても戻れる段取りがそろっていれば、同じ人でもぐっと良い仕事ができます

AIで言えば、資料を丸ごと読めるか・途中結果を覚えておけるか・失敗したときにやり直せるか、そのあたりが「道具のそろった部屋」かどうかにあたります
同じモデルでも、この段取りが足りないと、同じ問いに何度も答えを外す、ということが起きます

AIエージェントも同じで、モデルの地力は同じでも、ハーネスの出来で成果が大きく動きます
ここを混同すると「新しいモデルが賢くなった」と思っていた変化が、実は「周りの足場が良くなっただけ」だった、というズレが起きます

同じモデルでも足場でスコアが動く

この「足場で差がつく」現象は、コード生成の力を測るベンチマーク(性能テスト)でもよく話題になります
プログラムの課題をどれだけ解けるかを測るSWE-bench系のテストがその代表です

ここでは、モデル素の力を比べるために、あえて最小限のハーネスを使う工夫がされています
そのうえで、各社が自前で作り込んだ足場をかぶせると、同じモデルでもスコアが10〜30ポイントほど上がるという報告もあります(公開リーダーボードの一例)

数値は測り方や時期で変わるので鵜呑みは禁物ですが、足場を変えるだけで結果が大きく動くという傾向は、あちこちで共通して見られます
「モデルだけ見ていても半分しか分からない」というのが、ハーネスに注目する理由です

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

scaffold(足場)とハーネスはどう違うのか

ハーネスを調べていくと、たいていscaffold(スキャフォールド)という言葉に出くわします
日本語にすると「足場」で、建設現場に組む、あの足場と同じ単語です

結論を先に言うと、scaffold と harness は、ほぼ同じものを指す言葉です
どちらも「モデルを取り囲むソフトウェアの基盤」を意味していて、はっきり線を引ける別物ではありません

違うのは、主にニュアンスと、よく使われてきた場面です
ざっくり並べると、こんな呼び分けになります

おおまかには、scaffold は研究や評価の文脈で長く使われてきた言葉で、harness は製品・実行環境の文脈で2026年に主流化した言葉という住み分けです
新しく記事を読むときは、どちらが出てきても「あぁ、外殻の話ね」と同じ引き出しに入れて大丈夫です

Claude Code はハーネスエンジニアリングの実例

抽象的な話が続いたので、身近な実例に落とします
私が普段使っているClaude Code(Claude にファイル操作やコマンド実行までまかせられるツール)は、まさにハーネスの分かりやすい例です

あらためて振り返ってみると、私がClaude Codeを使いこんで「便利になった」と感じた場面の多くは、モデルが急に賢くなったからではありませんでした
ファイルを読ませる・コマンドを走らせる・失敗したら差し戻す、といった周りの段取り(=ハーネス)が整ったからという感覚のほうが近いです

ちなみに Anthropic 自身も、Claude Code と同じ土台をClaude Agent SDKとして公開していて、これを「エージェントハーネス」と位置づけています
つまり Claude Code は、ハーネスを実際の製品にした一例だと言えます

拡張機構はぜんぶハーネスの部品だった

Claude Code には、いわゆる拡張機構と呼ばれる仕組みがいくつかあり、この記事では代表的な4つを取り上げます
先ほどの「6つの部品」に重ねて見ると、それぞれの位置づけが分かりやすくなります

• MCP:外部の道具やデータにつなぐ規格 → ハーネスのツール統合にあたる
• サブエージェント(Agents):役割ごとに小さな担当を立てて任せる → オーケストレーションにあたる
• Hooks:処理の途中に自動で割り込ませる仕掛け → 検証と回復・権限にあたる
• Skills:再利用できる手順書をまとめておく仕組み → 段取りを部品化する働き

つまり、Claude Code の拡張機構をいじるという作業は、実は自分の手でハーネスを組み替えているのと同じことなんです
拡張機構そのものの入門は、こちらで別途まとめています

Claude Code拡張機構入門(Skills / Agents / MCP / Hooks)
Claude Code設定ファイル早見表

同じ枠組みは Claude 以外にもあります
OpenAI のCodex CLIや Google の Gemini CLI も、モデルの周りに独自のハーネスを組んだ製品で、各社が自前の外殻で腕を競っている、という構図です

なので、これからエージェント系のツールを選ぶときは、モデル名だけでなく、どんなハーネスを積んでいるかにも目を向けると、実際の使い勝手が見えてきます
同じモデルを積んでいても、使える道具の多さや失敗したときの粘り強さで、体感はけっこう変わってきます

ジャベ雄

「賢いモデル選び」と同じくらい「良い足場選び」が効いてきます

ハーネスエンジニアリングのよくある質問

まとめ 次回はハーネスの中の”ループ”を深掘り

最後に、この記事の要点を振り返っておきます

• ハーネスエンジニアリングとは、モデルを取り囲む外殻(足場)を設計する営み
• 定式は Agent = Model + Harness、同じモデルでも足場で成果が変わる
• 外殻はツール統合・メモリと状態・コンテキスト管理・ループ・検証と回復・権限の6部品
• scaffold とハーネスはほぼ同義、語感と使われる場面の違いくらい
• Claude Code はハーネスの実例、拡張機構はその部品

今回は外殻の全体像を押さえました
次回は、その中でも司令塔にあたるオーケストレーションループ、いわゆるエージェントループを一段深く掘り下げます

「考える→動く→結果を見る→また動く」をどう回すか、その設計に注目したエージェントループの話です
続きは次回のループエンジニアリングでどうぞ

あわせて読みたい

エージェントループとは 推論と行動を繰り返す仕組み AIエージェントが自分で考えて動き続ける正体がエージェントループです この記事では推論 行動 観測を停止条件まで繰り返す基本のしくみを ReActの由来やClaude Codeの実例とあわせて解説し 後半では2026年に登場したループエンジニアリングという新しい考え方も等身大で紹介します

連載「AIの○○エンジニアリング」の記事一覧

• 連載ハブ:AIの5つの○○エンジニアリング総まとめ
• 1本目:プロンプトエンジニアリングとは
• 2本目:コンテキストエンジニアリングとは
• 3本目:ハーネスエンジニアリングとは(この記事)
• 4本目:エージェントループの話
• 5本目:グラフエンジニアリングの話

用語をまとめて確認したい方は、AI用語集もあわせてどうぞ

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

AIエージェントが勝手にファイルを読んで、コマンドを試して、結果を見てまた次の手を打つ
あの「自分で考えて動き続ける」感じの正体がエージェントループです
エージェントループとは何か、という問いにひとことで答えるなら推論と行動を停止条件まで繰り返すしくみのことです

この記事は「AIの◯◯エンジニアリング」連載の4本目、テーマはエージェントループです
前回のハーネスエンジニアリングが「AIを取り囲む器」の話だったのに対して、今回はその器の中でぐるぐる回っている反復そのものを見ていきます

読んでもらうと、だいたい次のことが分かるようになります

• エージェントループの中身:推論→行動→観測→再行動という4つの流れと、止まるための条件
• ハーネスとの違い:器(ハーネス)とその中の反復(ループ)をどう切り分けるか
• ループエンジニアリング:2026年に登場したばかりの新しい考え方(ここは新しさと未確定さを添えて紹介)

ジャベ雄

難しい数式は出てきません
身近な作業の繰り返しに置き換えて読めば大丈夫です

エージェントループとは?まず結論から

結論から言うと、エージェントループとはAIが「考える→動く→結果を見る→また動く」を目標達成まで繰り返す反復のことです
研究者のあいだでは「ツールを持たせたAIを while ループの中で回す」という言い方で説明されることもあります

普通のチャットは、こちらが1回質問して、AIが1回答えて、それで一区切りです
この「1問1答」のかたちだと、AIは自分の答えが正しかったかどうかを確かめられません

エージェントループでは、そこに結果を観測して次に活かすという輪が足されます
たとえば「コードを直して」と頼むと、AIはファイルを読んで書き換え、テストを走らせます
エラーが出たらその中身を見て直す、というふうに自分の行動を材料にして進み続けるわけです

この反復のかたまりは、界隈では「エージェンティックループ」と呼ばれることもあります
言い回しは揺れますが、指しているものはほぼ同じで、ツールを使いながら自走する反復だと思ってもらえば十分です

身近な例で考えると、知らない街でお店を探すときの動きに近いです
地図を見て見当をつけ(推論)、その方向へ歩き(行動)、看板やお店の様子を確かめて(観測)、違っていたら引き返してまた探す(再行動)
この「やってみて、確かめて、直す」の繰り返しは人間なら当たり前ですが、その輪をAIに構造として持たせたのがエージェントループだと考えると、ぐっと身近に感じられると思います

ハーネスとループの違い 器と反復で切り分ける

連載を読んでいる方だと、前回のハーネスと今回のループが似て聞こえるかもしれません
ここは最初に切り分けておきたいところなので、対比で整理します

この連載では、AIの作り込みがプロンプトエンジニアリング → コンテキスト → ハーネス → ループと段を上がってきた、という流れで見ています
プロンプトが「1回の指示文を磨く」話、コンテキストが「渡す材料をそろえる」話、ハーネスが「器を整える」話だとすると、ループはその器の中で「どう回すか」を扱う一番内側の話にあたります
だから前回までの積み重ねの上に、今回の反復が乗っている関係だと考えてもらえると、位置づけがつかみやすいはずです

ざっくり言うと、ハーネスは外側の器で、ループはその器の中で回っている反復です
ハーネスエンジニアリングでは「Agent = Model + Harness(エージェント=モデル+ハーネス)」という式が使われていました
モデル本体を除いた、ツール連携・メモリ・権限のガードレールといった土台をまとめたのがハーネスで、その土台の上で「考えて動く」を繰り返す動きがエージェントループにあたります

ハーネスエンジニアリングの詳しい話は前回でまとめています

前回のハーネスエンジニアリングもあわせてどうぞ

あわせて読みたい

ハーネスエンジニアリングとは AIの外殻を設計する話 ハーネスエンジニアリングとは モデル本体を取り囲む外殻(ツール統合・メモリ・状態・コンテキスト管理・ループ・検証・権限)を設計する新しい考え方です Agent=Model+Harnessという定式や scaffold との呼び分け Claude Code が実例である理由を初心者向けにまとめました

ジャベ雄

器は場所と道具、ループはそこで手を動かし続けること、と分けると迷いにくいです

ループの中身 推論→行動→観測→再行動

エージェントループの中身は、大きく4つの動きに分けられます
ぐるっと1周してみると、なぜAIが自走できるのかが見えてきます

ポイントは、この4つが1回で終わらずゴールに届くまで何度も回るところです
人間なら「トライして、様子を見て、直して、またトライ」を無意識にやっています
その無意識の流れを、AI側では構造として組み込んであるわけです

この輪でとくに効いてくるのが行動と観測のセットです
AIがどれだけ賢く推論しても、外の世界に触れて結果を持ち帰れなければ、思い込みのまま突き進んでしまいます
ツールという手足で実際に動かし、その結果を観測して受け取るからこそ、間違いに気づいて直せるわけです

ここで欠かせないのが停止条件です
「ゴールに到達した」「回数の上限に来た」「これ以上進めないと判断した」といった条件を決めておかないと、ループはいつまでも回り続けてしまいます

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

ReAct からエージェントループへ 概念の出どころ

「考えて動く」を繰り返す発想は、急に出てきたものではありません
もとをたどると、2022年に発表されたReActという手法にたどり着きます

ReActは Reasoning(推論)と Acting(行動)を組み合わせた造語で、Yao らの研究で示されました
それまでは「AIに考えさせる」か「AIに行動させる」かのどちらか寄りだったところに、考えることと動くことを交互に織り交ぜるやり方を持ち込んだのがポイントです

たとえば「AだからBのはず」と推論だけで突き進むと、途中の思い込みに気づけないまま答えを出してしまいます
ReActの考え方では、推論のあいだに実際の行動と観測をはさむので、事実で答え合わせをしながら進めます
この「考えながら確かめる」の積み重ねが、そのままループの1周1周になっていると見ると、両者がつながって見えてきます

この「推論と行動を行き来する」考え方を具体的なループのかたちにしたものが、いま言うところのエージェントループにあたります
だからエージェントループという言葉じたいは、思いつきの造語ではなくすでに定着した中核の概念だと受け取ってもらって大丈夫です

用語の位置づけをもう少し整理したい方は、AI用語をまとめたハブ記事も用意しています

あわせて読む:AI用語集(生成AI・エージェント関連をまとめて解説)

Claude Code が実際に回しているループ

ここからは私の体験ベースで話します
身近にエージェントループを感じられるのが、AIにコード作業を任せられるClaude Codeだからです
Claude Code はデスクトップ向けのAIツールで、黒い画面にコマンドを打たなくても、こちらのお願いをうけてAIが自分でファイルを触ってくれます

私が「このスクリプトの不具合を直して」とお願いしたとき、Claude Code はだいたい次のように動きました

• 関係しそうなファイルを探して読む(推論と行動)
• あたりを付けて書き換える(行動)
• テストや実行を走らせて結果を見る(観測)
• エラーが残っていれば原因を考えて、また直す(再行動)

これはまさに、さっき見た推論→行動→観測→再行動の輪がそのまま動いている状態です
1回で直らなくても、結果を見て自分で軌道修正してくれるので、こちらは細かい手順を指示しなくても仕上がりに近づいていきます

裏で走っているコマンドは、Claudeが自分の判断で実行しているプログラム命令です
私たちがターミナル(黒い画面)を触る必要はなく、お願いと確認だけでループに乗れるのが、初心者にとってのありがたさだと感じています

面白いのは、ループの途中でこちらに確認を求めてくる場面があるところです
ファイルを書き換える前や、影響の大きいコマンドを走らせる前に、いったん手を止めて「これで進めていいか」を尋ねてくれます
ループは自走しますが、要所で人が承認を挟めるようになっていて、任せきりにする不安をやわらげてくれるのが助かるところです
ただし、どこで手を止めるかは権限まわりの設定しだいです
確認を省く設定にしていれば、止まらずに進んでいきます

Claude Code そのものの拡張のしくみは、別記事でまとめています

あわせて読む:Claude Code 拡張機構入門(4つの仕組みを総まとめ)

ジャベ雄

結果を見て直してくれる、この一輪があるだけで任せられる範囲がぐっと広がります

ループエンジニアリングとは?2026年に生まれた新しい考え方

ここまでのエージェントループは、すでに定着した概念でした
いっぽう、この節で扱うループエンジニアリングは、生まれてまだ数か月しか経っていないできたての新しい言葉です
そこは差し引いて読んでもらえるよう、はっきり書いておきます

ループエンジニアリングという呼び方は、2026年6月ごろに Google の Addy Osmani 氏が書いた記事をきっかけに広まりました
ただし本人が名付け親を名乗っているわけではなく、同じ時期に複数の書き手が同じ話を始めていました
swyx が「Loopcraft(ループを積み重ねる技)」という表現を出し、LangChain も関連記事を公開するなど、いくつもの発信が重なった時期です

命名の手柄が誰にあるのかは資料によって割れていて、そこも含めて立ち上がったばかりで固まっていない分野だと受け取るのが正確です
長く残る言葉になるのか、別の呼び方に吸収されるのかは、まだ見えていません

では、なぜ今この言葉が出てきたのか?
エージェントが一度の指示で長く走り、何十周もループを回すようになってきたからです
1周ずつが短ければループの良し悪しは目立ちませんが、長く回るほどどう回すかの設計が結果を左右するようになり、そこにあらためて名前が付いた、という流れだと私は理解しています

肝心の中身はこうです
これまでは「AIに良いプロンプトを書く」ことに力を注いでいましたが、ループエンジニアリングでは発想を一段ずらして、AIをプロンプトする”ループ(しくみ)”のほうを設計することに軸を置きます
言い換えると、手を動かすのはAIに任せて、そのAIをどう回すかを人が組み立てる、という考え方です
ただしループを組むようになっても、1周ずつでAIに渡す指示文の作り込みが要らなくなるわけではありません
プロンプト・コンテキスト・ハーネス・ループは置き換えではなく積み上げの関係です

料理でたとえるなら、これまでは「おいしく作って」と料理人(AI)に上手に頼むのがプロンプトの工夫でした
ループエンジニアリングは、料理人そのものより、注文が入る流れ・味見のタイミング・出し終わりの合図といった厨房の回し方のほうを設計する側に立つイメージです
作るのは料理人に任せて、どう回すかを組む、という役割分担だと考えると、新しさの手ざわりがつかめると思います

では、ループの何を設計するのか?
よく挙がるのが次の4つの設計対象です

この4つを見て気づくかもしれません
停止ルールや検証は、さっきの停止条件や観測と地続きの話です
つまりループエンジニアリングは、まったくの別物というよりエージェントループを”設計の対象”として捉え直したものと見ると腑に落ちやすいです

ジャベ雄

プロンプトを磨いたうえで、さらにループを組み立てる段階に来た、という話です

まとめ エージェントループの要点と連載ナビ

エージェントループとは、AIが推論→行動→観測→再行動を停止条件まで繰り返す反復のしくみでした
要点をおさらいしておきます

• エージェントループ=推論と行動と観測を、停止条件まで繰り返す自走のしくみ
• ハーネス(器)とループ(その中の反復)は分けて捉える、ただし境目は論者で揺れる
• 発想の源流は2022年の ReAct、エージェントループ自体は定着した中核概念
• Claude Code は、結果を見て直す輪を回して自走する身近な例
• ループエンジニアリングは2026年6月に生まれた新しい言葉、長期定着はまだ未確定

この記事は連載「AIの◯◯エンジニアリング」の1本です
ほかの回もあわせてどうぞ(公開まで少しお待ちください)

• 連載ハブ:AIの◯◯エンジニアリング 5つの型まとめ
• 連載#1:プロンプトエンジニアリングとは
• 連載#2:コンテキストエンジニアリングとは
• 連載#3:ハーネスエンジニアリングとは
• 連載#5:グラフエンジニアリングとは

4本を1枚の地図としてつないだ総まとめは、連載ハブにまとめています
prompt・context・harness・loop を束ねる呼び方として、界隈では「エージェンティックエンジニアリング」という言い方も出始めています

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

AIに何かをお願いするとき、昔ほどプロンプトを凝る必要はなくなってきました
それでも、Claude Code の CLAUDE.md みたいな「AIが読み込むファイル」は、今もマークダウン(Markdown)で書くのが定番なんです

マークダウンは、記号をちょっと添えるだけで見出しや箇条書きを表せる書き方です
これを覚えておくと、大きく2つの場面で役に立ちます

• AIに構造を正しく伝える:見出しや箇条書きで整理して渡すと、話の区切りが伝わりやすい
• AIが作ったmdファイルを読める・直せる:CLAUDE.md や README.md を開いても慌てずに済む

この記事では、チャットでよく打つ基本記法から、チャットでは出番が少ないけどmdファイルで頻出の記法まで、初心者向けにまとめて解説します
Claudeそのものの使い方はClaudeの使い方(初心者向け)でも扱っているので、あわせてどうぞ

ジャベ雄

記号は10個ほど覚えれば、たいていの場面をカバーできます

そもそもマークダウンとは?

いちばんの狙いは読みやすさで、記号付きのテキストのままでも人がすっと読めるように作られています
だからこそ、人が編集して、AIも読む、という使い方に向いていて、CLAUDE.md のような設定ファイルにも採用されています

まずは、記号とそれが表す構造の対応をざっと見ておきましょう
細かい書き方は次の章でまとめて扱います

作ったのは John Gruber という人で、2004年に考案しました
Aaron Swartz も相談役として関わりましたが、共同作者というより協力者という立ち位置です
その後、実装ごとの挙動のズレをそろえる CommonMark という標準仕様も整備されています

拡張子の .md がマークダウンで書かれたファイルの目印で、CLAUDE.md 以外に README.md や AGENTS.md などでも使われます
Claude Code の設定ファイルの中身は、Claude Code 設定ファイル早見表にまとめています

ジャベ雄

まずは「記号で構造を書くテキスト」とだけ覚えておけば十分です

マークダウンの記法一覧

ここからは、マークダウンの記法をよく使う順に3段階でまとめます
「まず覚える」「mdファイルで頻出」「AIのmdで見かける」の順なので、上から読んでいけば無理なく身につきます

必須 – まず覚える

チャットでもmdファイルでも出番が多い、土台の6つです
まずはこの書き方から押さえましょう

# 見出し1
## 見出し2

- 箇条書き
- もうひとつ

1. 番号つき
2. その次

**太字** と *斜体*

`インラインコード`

[リンクの文字](https://example.com)

• 見出し:行頭に # と半角スペース、# の数でレベルが決まる、話題の区切りを示す(# の直後の半角スペースは省かない)
• 箇条書き:行頭に – と半角スペース、並列の項目を並べる
• 番号リスト:1. の形、手順に使う、番号は打ち間違えても表示は自動で連番になる
• 太字・斜体:記号2つで太字、1つで斜体、強調したい語に(単語の途中はアスタリスクが安全)
• インラインコード:バッククォート1つで囲む、コマンドやファイル名を文中で見せる
• リンク:角カッコに表示テキスト、続けて丸カッコにURL

ジャベ雄

この6つが打てれば、日常のやり取りはほぼ回せます

よく使う – mdファイルで頻出

CLAUDE.md や README.md でよく見る、少し長めの記法です
チャットでは出番が少なくても、ファイルを読むなら押さえておきたいところ

```python
print("hello")
```

> 引用文はこう書きます

---

| 列A | 列B |
| --- | --- |
| あ  | い  |

- 親の項目
  - 子の項目(半角スペースで下げる)

• フェンスドコードブロック:バッククォート3つで前後をはさむ、先頭に python などの言語名を書くとハイライトの合図になる、コードのかたまりを見せる、AIが吐くmdで頻出
• 引用:行頭に大なり記号、注記や引用文に使う
• 表:縦棒で区切り、見出しの下に区切り行を1本入れる(GFM拡張、対応環境でだけ効く、詳しくは次の章)
• 水平線:ハイフンを3つ以上並べた単独行、話題の切れ目に
• 箇条書きのネスト:子の項目を半角スペース2〜4個下げて揃える、入れ子の階層を表す(下げ幅は環境で違うので揃えるのが大事)

知っておいた方がいい – AIのmdで見かける

自分で書く機会は少なくても、AIが生成したmdには顔を出す記法です
読めれば、崩さず直せます

- [ ] 未完了のタスク
- [x] 完了したタスク

~~打ち消し線~~

![代替テキスト](image.png)

[表示テキスト][ref]
[ref]: https://example.com

マークダウンで足りないところは、HTMLをそのまま書けます
AIの生成物では、折りたたみの <details> や改行の <br> あたりでよく見かけます

段落の途中で改行<br>したいとき

<details>
<summary>クリックで開く</summary>
折りたたみの中身
</details>

• チェックリスト:角カッコの中を空白で未完了、エックスで完了、ToDoに使う(GFM拡張、対応環境でだけ効く)
• 打ち消し線:チルダ2つで前後を囲む、消し込みの表現に(GFM拡張、対応環境でだけ効く)
• 画像:リンクの先頭にビックリマークを付ける、代替テキストとURLを続ける
• 参照リンク:本文は角カッコにラベル、別の行で「ラベルとコロンとURL」を定義する、リンクが多い文書向け
• エスケープ:記号の直前にバックスラッシュ、意図しない装飾を止める(くわしくは「よくある崩れ」の章で)
• HTML直書き:改行の <br> や折りたたみの <details> など、HTMLをそのまま書ける
• setext見出し:テキストの下に イコール3つ でH1、ハイフン3つ でH2、古いmdで見かけることがある

最後に、ここまでの記法を早見表にまとめます
「どこで使うか」は チャット / mdファイル / AIが生成 の3つに分け、○=よく使う・△=たまに・×=ほぼ出ない の目安で示しました
迷ったらここに戻ってきてください

ここまでで、表・チェックリスト・打ち消し線には「GFM拡張」と付けました
これが効くかどうかは貼り先しだいで、その仕組みは次の章で整理します

ジャベ雄

全部を丸暗記せず、早見表で引きながらで十分です

素のマークダウンとGFM拡張・環境依存の違い

「同じ書き方なのに、効いたり効かなかったりする」
これがマークダウン最初のつまずきで、答えは記法が3つの層に分かれていることにあります

3層というのは、素のMarkdown(CommonMarkコア)/ GFM拡張 / 表示環境依存 の3つです
ざっくり表にするとこうなります

CommonMark は、実装ごとにバラバラだったマークダウンの挙動を、あいまいさなく決めた標準仕様です
ここに入っている記法は、だいたいどの環境でも同じように効きます

いっぽう GFM(GitHub Flavored Markdown)は、GitHubがCommonMarkに独自の拡張を足したものです
表・タスクリスト・打ち消し線・URL自動リンクは、この拡張にあたります
つまり対応している環境でしか効かないことがあるんです

身近な例だと、GitHubで書いたタスクリスト付きのメモを、GFMに対応していないメモアプリに貼るとします
すると、チェックボックスが出ずに角カッコがそのまま残ることがあります
記法が悪いわけではなく、貼り先がその拡張に対応していないだけ、というケースです

もうひとつ紛らわしいのが、コードの色付けです
言語名を書く「記法」自体はCommonMarkコアなので素のマークダウンの範囲ですが、実際に色を付けるかどうかは表示する側しだいです
だから「言語名を書いたのに色が付かない」ことも起こります

ジャベ雄

効いたり効かなかったりの正体は、この3層の切り分けです

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

AIに構造を正しく伝えるマークダウンのコツ

ここからが、AIとマークダウンを組み合わせる本題です
結論から言うと、見出しと箇条書きで整理して渡すだけで、AIの読み違いはかなり減ります

これは私の体感だけの話ではなくて、Anthropicの公式ドキュメントでもそう案内されています
CLAUDE.md を書くときは「構造化のために見出しと箇条書きで指示をまとめる」ことが推奨されていて、公式は「Claudeは人と同じように構造をスキャンする」と説明しています

なぜ構造が効くかというと、見出しや箇条書きは「ここで話題が変わる」「ここは並列の項目」という区切りを、記号で分かるようにしてくれるからです
人が流し読みするときの手がかりと同じものを、AIにも渡しているイメージで捉えると分かりやすいです

だらだら続く長い文章より、区切られた見出しのほうが追いやすい、というわけです
やることはシンプルで、次の3つを意識するだけで整います

たとえば「まずAをして、次にBをして、最後にCを確認して」とベタ書きするより、手順を箇条書きで1つずつ並べたほうが、AIは順番を取り違えにくくなります
渡す前に自分でざっと読み返して、区切りが見えるかを確かめるのがコツです

逆に、全部を1つの長い段落に詰め込むと、どこが指示でどこが補足か分かりにくくなります
難しく考えず、話題ごとに見出しを立てて、並ぶものは箇条書きにする
それだけでAIに渡す情報がぐっと整理されます

コードフェンスの区切りも、AIに渡すときに効いてきます
コマンドや設定を三連バッククォートで囲んでおくと、そこが「そのまま扱うコード」だとAIに伝わり、説明文と混ざって解釈される事故が減ります
短い1行でも、コードはコードとして囲っておくと安全です

Claude Code の拡張機構そのものに興味が出たら、Claude Code 拡張機構入門もあわせてどうぞ

ジャベ雄

見出しと箇条書きを足すだけで、読み違いがぐっと減ります

AIが作ったmdファイルを読む・直すコツ

AIに任せていると、CLAUDE.md のようなmdファイルをAI自身が書いてくれる場面が増えてきます
中身を読めるようになると、気になったところを自分で微調整できます

たとえば、こんな中身のCLAUDE.md があったとします

# プロジェクトの前提

このプロジェクトは Python 製の集計ツールです

## コーディング規約

- インデントはスペース4つ
- 文字コードは UTF-8

## やってほしいこと

1. まずテストを書く
2. それから実装する

読み方はシンプルです
# ではじまる行が見出し(話題の区切り)、– や数字ではじまる行が箇条書き
あとはふつうの文章、と分けて読めば構造がつかめます

直すときに崩れやすいのは、見出しの記号やインデントのあたりです
1行いじったら、エディタのプレビューで表示が崩れていないかを確認すると安心です

特に、見出しの # と本文のあいだの空行や、箇条書きのインデントは崩しやすいところです
コピペで持ってくると全角スペースが紛れ込むこともあるので、貼ったあとに一度プレビューを見ておくと、そのまま進めて大丈夫か判断できます

読むときのコツとして、インデント(行頭の字下げ)にも注目すると構造がつかみやすくなります
字下げされた箇条書きは、上の項目のさらに細かい中身、という入れ子の関係を表しています
ここが半端にずれていると階層を取り違えやすいので、直すときは字下げの幅をそろえておくと崩れにくくなります

「触るのはちょっと怖い」というときは、直し方をClaude自身に頼んでしまうのが早いです
ただし丸投げにはせず、書き込む前に直した内容を提示してもらうようにすると、意図しない変更を防げます

ジャベ雄

自信がないときは、直し方をClaudeに聞いてしまうのが早いです

マークダウンでよくある崩れとつまずき対処

最後に、初心者がつまずきやすい「崩れ」を、症状・原因・直し方でまとめておきます
ほとんどは記号のまわりを半角スペースで揃えると解決します

いくつか補足します
行末の半角スペース2個は目に見えないうえ、エディタが保存時に勝手に消すことがあります
強制的に改行したいなら、行末にバックスラッシュ \ を置く方法もあります
改行が消えて困るときは、空行で段落を分けるか <br> を使うのが無難です

全角スペースは日本語入力あるあるの落とし穴です
マークダウンの記法は半角スペースを前提にしているので、# の後などに全角スペースが入ると認識されないことがあります
「なぜか効かない」ときは、いちど半角に打ち直してみてください

エスケープも覚えておくと便利です
たとえば商品名に付けたアスタリスクが2つ並ぶと太字の記号と解釈されたり、変数名の my_var_name に含まれるアンダースコアが斜体の合図とみなされて、途中が斜体に化けたりします
そのまま文字として出したいときは、記号の直前にバックスラッシュを1つ足すと、装飾が発動しなくなります

表がうまく出ないときは、直す前に貼り先がGFMに対応しているかをまず確かめてください
対応していれば、各行で縦棒の数をそろえて、見出しの下に区切り行を1本入れれば整います
列の中で縦棒そのものを文字として使いたいときは、その縦棒の前にもバックスラッシュを足すと、区切りと勘違いされずに済みます

ジャベ雄

崩れの大半は、半角スペースで揃えると直ります

まとめ

マークダウンは、記号を少し添えるだけで構造を表せる書き方です
AIに指示を渡すときも、AIが書いたmdファイルを読むときも、同じ記法が土台になります

• まずは見出し・箇条書き・太字・リンクの基本記法から
• 表やタスクリストは GFM拡張=対応環境だけで効く
• AIに渡すときは見出しと箇条書きで構造を整理する
• 崩れたら半角スペースで揃える・プレビューで確認・迷ったらClaudeに直してもらう

設定まわりをもう少し知りたくなったら、Claudeデスクトップアプリの設定ガイドもあわせてどうぞ

ジャベ雄

まずは見出しと箇条書きから、気楽に使ってみてください

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

Claudeの設定メニュー、開いてみたら項目が多くて、どこを触ればいいのか迷った経験はありませんか？
Claudeデスクトップアプリの設定は、大区分が3つ・その中に中区分が15項目という構成になっています

この記事では、その15項目をまるごと順番に解説していきます
公式ドキュメントで裏を取りながら、初心者がまず押さえたい設定と、うっかり触ると危ない設定を切り分けて紹介するので、設定画面の全体像がつかめるはずです

設定メニューを開いたところ。左に大区分3つ・全15項目が並びます

本題に入る前に、設定メニューの開き方だけ確認しておきます
迷いやすいのは最初の入り口だけで、開いてしまえばあとは区分を切り替えるだけです

まず前提 この画面は「アプリ全体」の設定です

先に大事な前提を1つ
この設定メニューでは、コード開発（Code）やおまかせ作業（Cowork）といった一部の機能だけでなく、Claudeデスクトップアプリ全体の設定ができます

いまのアプリは画面上部がHome と Code の2つのタブに分かれていて、Homeの中でチャットとCoworkを切り替えます
その全部にまたがる設定が、この1つのメニューにまとまっている、というわけです

アプリの構成はわりと頻繁に変わるので、タブの並びは自分の画面で確認してください

ジャベ雄

つまりここは、コード専用ではなくアプリ全体をまとめて調整する場所なんです

設定メニューの全体像 大区分3・中区分15の早見表

細かい話に入る前に、15項目をひとことずつでまとめた早見表を置いておきます
「今どこの話をしているか」を見失ったら、ここに戻ってきてください

この15個を、上から区分ごとにまとめて見ていきます
ぜんぶ触る必要はないので、気になった項目だけ拾い読みしてもらってもかまいません

【設定】プロフィール・外観・アカウント周り

まずは「設定」区分の入り口、一般から
ここは氏名やアバター、そして「Claudeには何とお呼びしてほしいですか？」という呼び名の設定が並びます

意外と便利なのがClaudeへの指示（カスタムインストラクション）です
ここに書いた内容は、チャットでもCoworkでも常に考慮されます
「説明は簡潔に」「コードにはコメントを付けて」のような自分の好みを一度書いておくと、毎回頼まなくてよくなって楽になります

そのすぐ下には外観（テーマ）やチャットフォント、モーションの設定もあります
外観はシステム・ライト・ダークから選べるので、目が疲れにくい方を選んでおくといいです
さらに下には、音声（言語・速度）や、レスポンス完了などの通知のオン・オフも並びます

アカウント・請求・使用量

残り3つはお金とアカウントまわりです

• アカウント … 今のプランの確認や、アカウントの削除ができます（削除はプランによって先に解約が必要）
• 請求 … サブスクの契約状況や支払い方法、プラン変更・解約を扱います
• 使用量 … 今の期間でどれくらい使ったか、上限までの余裕を確認できます

使用量については、Claude Codeの画面でもモデル選択の横にある使用量のリングから、コンテキストの消費とプランの使用状況をのぞけます
プランの使用量は複数の画面で共有される点だけ覚えておくと、数字の見方で混乱しません

【設定】プライバシー ここは最初に確認したい

15項目のなかで、私が「まず一度は開いてほしい」と思うのがプライバシーです
ここには「AIモデルの改善にご協力ください」という、自分の会話をAIの学習（モデル改善）に使うかどうかの切り替えがあります

Free・Pro・Maxのプランでは、このデータ学習のトグルを自分でオフにできます
オフにすると新しい会話は学習に使われず、データの保持も標準の30日になります
逆にオンのまま（学習に協力する）だと、最大5年間保持される設計です

ジャベ雄

仕事の内容を入力する人ほど、まずここのトグルを確認しておくのがおすすめです

プライバシーの「AIモデルの改善にご協力ください」が、会話を学習に使うかのスイッチです

【設定】機能 使える道具のオン・オフ

機能のタブは、Claudeが使える道具（能力）のトグルが並ぶ場所です
実機ではいくつかのグループに分かれていて、代表的なのはこのあたりです

• メモリー … 過去のチャットを検索・参照させるか、履歴からメモリーを作るか
• アーティファクト … コードや文書・図を、チャットの隣のパネルに描き出す
• インライン可視化 … 会話の中に直接グラフや図を出す
• クラウドコード実行とファイル作成 … サーバー上でコードを動かして資料やPDFを作る（スキルの利用に必要）
• ツールアクセスモード … 新しい会話でコネクターの道具をどう読み込むか

ひとつ注意点
ウェブ検索やリサーチ、拡張思考のオン・オフは、この「機能」タブではなくチャット入力欄のスイッチ側で切り替えます
並ぶ項目はプランやバージョンで変わるので、実際は自分の画面で確かめてください

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

【設定】Claude Code 権限モードがいちばんの肝

Claude Codeまわりで最初に理解したいのが権限モードです
コーディング作業でClaudeにどこまで自動でやらせるか、を決める仕組みです

ここで大事な注意が1つ
権限モードの切り替えそのものは、設定メニューではなく作業画面（送信ボタンの横のセレクタ）で行います
設定メニューのClaude Code項目でできるのは、主に後述の「許可をバイパス」を使えるようにする開放です

まずは権限モードに何があるのか、表で並べてみます

初心者のうちは、作業画面のセレクタを手動のままにして様子を見るのが安全です
Claudeが何をやろうとしているか、1つずつ確認できるので、動きが読めてきます

混同しやすいのが自動と許可をバイパスの2つ
名前は似ていますが、中身はまったく別物です

自動は、裏で安全チェックを回しながら進める、いわば「安全寄りの自動」です
確認の回数を減らしつつ、危なそうな操作は止めてくれるので、慣れてきた人が作業画面で選ぶ常用モードにしやすいです

権限モードのほかに、使うモデルの選択も作業画面（送信ボタンの横）から切り替えられます
モデルも権限モードも作業の途中で変えられるので、「軽い調べ物は素早いモード、複雑な実装は賢いモード」のように場面で使い分けると効率が上がります

この項目には「許可をバイパス」の開放のほかにも、ブラウザツールのオン・オフ、コーディング画面の見た目（テーマ・フォント）、プルリクエストの自動化、作業用のワークツリーの保存場所など、多くのスイッチがまとまっています
権限まわりの考え方をもっと固めたい人は、Claude Codeのセキュリティ設定や、設定ファイルの早見表の記事も合わせてどうぞ

権限モードの切り替えは作業画面側、設定にあるのは「許可をバイパス」を使えるようにする開放です

【設定】Cowork と Claude in Chrome

比較的新しい2つの機能の設定です
まずCoworkは、タスクを丸ごと渡すと、ファイル・カレンダー・メール・つないだツールを横断して、完了まで進めてくれるおまかせ作業の面です
Claude Codeの一般業務版、と考えると分かりやすいです

Coworkはもともとデスクトップ発の機能ですが、2026年にはWebやスマホにも広がってきました
いまのデスクトップアプリでは、Homeタブの中でチャットと切り替えて使う形になっています（外出先から進捗を見て、続きをあとで受け取る使い方も可能）

もう一つのClaude in Chromeは、Chrome拡張との連携です
設定メニューのこの項目で扱えるのはサイト単位の許可です
すべてのサイトで動かすか（拡張機能を許可）と、使わせたくないブロックサイトの登録ができます

一方で「操作のたびに確認するか」といった操作の強さは、設定メニューではなく拡張機能側で選びます

• 都度確認 … 操作のたびに止まって承認を求める（安全寄り）
• 確認なしで実行 … 自分で進め、危なそうなときだけ確認する

購入やアカウント作成のような操作は、そもそも実行できない安全弁も入っています
この機能は進化が速いので、実際の画面は自分の環境で最新を確かめるのが確実です

【デスクトップアプリ】一般・拡張機能・開発者

2つ目の大区分、デスクトップアプリはアプリ本体の設定です
ここは3項目にまとまっています

一般には、スタートアップ時にClaudeを起動するか、システムトレイに常駐させるか、といったアプリ本体の設定が並びます
目玉はコンピュータ使用のトグルで、許可したアプリ上でClaudeが画面を見て、キーボードやマウスを操作できるようになります（既定はオフ、Macだと画面収録などの許可も追加で必要）
ほかに、拒否するアプリの登録や、作業後にウィンドウを元に戻すかどうかの設定もここです

拡張機能は、MCP拡張をワンクリックで入れられる仕組みです
以前は設定ファイル（JSON）を手で書く必要がありましたが、専用の拡張ファイルを選ぶだけで導入・管理できるようになっています

ジャベ雄

MCPって何？という人は、拡張機構の入門記事から読むとつかみやすいです

最後の開発者は、作業中のローカルMCPサーバーを追加・管理する項目です
設定ファイルを直接編集する導線や、開発者向けドキュメントへのリンクが置かれた、ちょっと踏み込んだメニューになります

拡張機構やMCPの全体像は、Claude Code拡張機構の入門記事でまとめて解説しているので、そちらも参考にしてください

【カスタマイズ】スキル・コネクタ・プラグインの違い

3つ目の大区分、カスタマイズはClaudeを自分好みに拡張するメニューです
スキル・コネクタ・プラグインの3つが並びますが、名前が似ていて混乱しやすいので、違いを表で整理します

ざっくり言うと、スキルが個別の能力・コネクタが外部連携・プラグインがそれらの詰め合わせ、という関係です
どれもカスタマイズメニューの「＋」ボタンから一覧を開いて、インストールや接続を進める流れになっています

スキルは関連する場面で自動で読み込まれるほか、入力欄で「/」を打って手動で呼び出すこともできます
コネクタはつなぎたいサービスで認証すれば、Claudeがそのサービスのデータを読んだり操作したりできるようになります

カスタマイズのスキル一覧。同じ並びにコネクタ・プラグインもあります

よくある質問 設定メニューまわり

まとめ まず触る設定・触らない方がいい設定

Claudeデスクトップアプリの設定メニュー15項目を、区分ごとに一周しました
最後に、初心者がまず触るとよい設定と、当面は触らない方がいい設定をまとめておきます

ジャベ雄

全部を触る必要はないので、まずは名前と外観、プライバシーあたりからで十分です

設定画面は更新が速いので、細かい項目名や並びは、この記事を片手に自分の画面で答え合わせしてもらうのがいちばん確実です
Claude自体の使い方から知りたい人は、Claudeの使い方（初心者向け）や、Claude用語集から入ると、設定の意味もより腑に落ちるはずです

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています

もともと私の手元には、自分のサーバー上のデータベースにPythonで接続するモジュールがありました、ただこれが古いライブラリ前提で作られていて、最新の環境に上げようとすると動かない、という状態でずっと固まっていたんです

どうせ作り直すなら、ただの接続モジュールに戻すのはもったいない、せっかくなら Claudeから直接データベースを覗ける道具にしてしまえば便利なのでは? と思いついたのがきっかけでした

その「道具」がMCPサーバーと呼ばれるものになります、この記事では Claude Codeに伴走してもらいながら、自分専用のMCPサーバーを設計から公開まで作った体験を、コードの深い話は抜きにして広めに書いていきます

先に結論を言うと、プログラムをゴリゴリ書ける人でなくても、自分専用の道具は作れます、Claudeに設計から相談して、実装もレビューも任せて、最後に自分が確認するだけで形になりました

ジャベ雄

「自作」って聞くと身構えちゃうけど、やってることの大半は日本語の相談なんですよね

Claude Codeの拡張機構の全体像はClaude Codeの拡張機構入門の記事、AI周辺の用語はAI用語集でまとめているので、言葉でつまずいたらそちらも合わせてどうぞ

そもそもMCPって何 Claudeに道具を持たせる仕組み

まず言葉の整理から、MCP(エムシーピー)はClaudeに「外部の道具」を持たせるための拡張の仕組みの1つです

Claudeはそのままだと、賢く文章を考えたり相談に乗ったりはできても、「私のサーバーにあるデータベースを読んできて」みたいな手元の操作はできません、本体に手足が付いていないイメージです

そこで 道具(=MCPサーバー)を外付けしてあげると、Claudeが単体ではできない操作を、その道具を介してできるようになります、今回私が作ったのは「自分のサーバーのデータベースを読む道具」です

これをClaudeに登録しておくと、あとは日本語で 「このテーブルから昨日のデータを出して」と頼むだけで、Claudeが裏でデータベースへの問い合わせ(SQLという命令文)を組み立てて、結果を返してくれます

ジャベ雄

SQLを自分で書かなくていいの、ここが地味にうれしいんですよ

なぜ既製品でなく自作だったのか

ここで疑問が出ると思います、データベース用のMCPなんて世の中にすでにあるのに、なぜわざわざ自分で作ったのか? という話です

結論から言うと、既製品が私のサーバー環境にそのままでは繋がらなかったからです、この接続の壁が今回いちばんの分かれ道でした

実は最初、私は「わざわざ作らなくても、既にあるものを入れれば一発でしょ」と軽く考えていました、ところがいざ繋ごうとすると、データベースの接続情報を正しく入れているのに、どうやっても弾かれてしまう、ここで「あれ、これ普通のやり方では届かないやつだ」と気づいたわけです

Xserverは「二段構え」でつなぐ必要がある

私が使っているレンタルサーバー(Xserver)は、データベースに直接つなぐのではなく、いったん別のサーバーに安全な経路でログインしてから、その先のデータベースへ繋ぐという二段構えが前提になっています

この「安全な経路を一本通してから、その中を通ってつなぐ」やり方を SSHトンネルと呼びます、外から直接データベースを叩けないようにする、セキュリティ上ありがたい仕組みなんですが、繋ぐ側からするとひと手間多いわけです

一般的なデータベース用のMCPは、この SSHトンネルの機能を持っていません、だからXserverのような二段構えのサーバーには、既製品をそのまま当ててもつながらないんです

既製品は「参考にはするけど、そのままでは私の用途を満たさない」、これが自作に踏み切った理由になります、自分の環境にぴったり合う道具がないなら、作ってしまえばいいという発想です

Claude Codeに全工程を伴走させた流れ

ここからが記事の本題です、私は今回 「バイブコーディング」的に、ほぼ全工程をClaude Codeに伴走させて作りました、ノリと相談で進めていく感じの作り方ですね

AIでアプリを作る体験そのものについてはAIでアプリ開発に挑戦した体験記でも書いているので、雰囲気が気になる方はそちらも、ここでは「道具(MCP)を作るときの流れ」に絞ります

大きく分けると、壁打ち → 設計 → タスクごとに実装 → 最終レビュー → 公開という5ステップで進みました

「先にテストを書く」ってどういうこと

STEP3で「先にテストを書いてから本体を作る」と書きました、これは TDD(テスト駆動開発)という作り方で、ざっくり言うと「合格ラインを先に決めてから中身を作る」やり方です

料理で言えば、完成形の味見の基準を先に決めておいて、その基準を満たすように作る感じですね、こうすると 作ったものが意図どおり動いているかを毎回その場で確認できるので、後からのやり直しが減ります

大事なのは、この段取り自体もClaudeが提案して進めてくれた点です、私が「TDDでやって」と細かく仕切ったわけではなく、相談する中で自然とこの形に落ち着きました

ジャベ雄

「実装する人」と「チェックする人」を分ける、これ人間のチーム開発と同じ発想なんですよね

AIで仕事を減らしたい方へPR

AI鬼管理｜Claude Code活用の業務自動化トレーニング

Claude Code を業務の自動化に使うためのトレーニングです
いきなり申し込む形ではなく、まずは無料の業務効率化診断(オンライン面談)から始められます

無料の業務効率化診断を見てみる

Notta｜AI自動文字起こし

会議や動画の音声を自動で文字にするサービスです
議事録や書き起こしの手作業を減らしたいときに

Nottaを見てみる

最終レビューで「自分のバグ」が見つかった話

この章の話が今回いちばん学びになりました、各タスクのレビューはちゃんと通していたのに、最後の全体レビューで実際のバグが1つ見つかりました

中身を平たく言うと、読み取り専用のはずなのに、ある特殊な書き方をすると書き込み命令が通ってしまう抜け穴でした、「読むだけ」を守らせていたつもりが、すり抜ける経路が残っていたんです

怖いのは、これが 各機能ごとの個別レビューを全部すり抜けていた点です、1つひとつの機能を見ているときには気づけず、全体を改めて厳しい目で見直したときに初めて浮かび上がってきました

見つかったあとの流れはシンプルで、指摘 → 修正 → 再レビューでその抜け穴を塞ぎました、ここでもやっているのは「Claudeに直してもらって、もう一度別の目で確認する」という同じ進め方です

AIは賢いんですが、万能で無謬というわけではありません、だからこそ 作る工程とチェックする工程を分けて、最後に全体を見直す、この一手間が安心につながると実感しました

AIにデータベースを触らせるときの安全設計

今のバグの話とつながりますが、AIにデータベースを触らせるなら、安全側に倒した設計が要ります、ここは自作する人だけでなく、既製のMCPを使う人にも役立つ考え方なので少し丁寧に書きます

基本は「読み取り専用」にしておく

私が決めたのは 既定で「読むだけ」にするという方針でした、AIにデータベースを任せるとき、いちばん怖いのはうっかりデータを書き換えられたり消されたりすることです

だから道具の側で「ふだんは読むだけ、書き込みは明示的にスイッチを入れたときだけ許可する」という作りにしました、自分でも「今は書き込みOKにしているぞ」と意識しないと書けない、という ブレーキです

本当の安全弁はデータベース側にある

ただ、ここで大事な考え方があります、道具(アプリ)側のチェックは第一の防御線にすぎません

さっきのバグのように、アプリ側の「読むだけ」設定はすり抜ける経路が残っていることがあります、だから 本当の安全弁は、データベース側に「読み取りしかできない利用者」を用意することです

つまり、そもそも書き込み権限を持たないアカウントで繋いでおけば、仮にアプリ側のチェックを抜けても、データベースが「あなたには書き込み権限がありません」と弾いてくれます、二重のブレーキです

考え方としてはこうです、データベースには、つなぐための利用者(アカウント)を何種類か作れます、ふだんアプリやサーバーの管理に使うのは強い権限を持った利用者ですが、AIに渡すのは「読むことしかできない利用者」を別に1つ用意して、そちらだけを使わせるのが安心です

こうしておくと、構造はとてもシンプルになります、アプリ側の「読むだけ」設定が 第一の防御線、その奥でデータベース側の読み取り専用の利用者が 最後の安全弁として控える、という形です、手前のチェックがうっかり抜けても、いちばん奥で物理的に書き込めない、この奥行きが効いてきます

手順の細かい話は環境ごとに変わるので踏み込みませんが、方針として覚えておきたいのは 「アプリで頑張る」より「権限を持たせない」ほうが強いという一点です、できないように作ってあれば、そもそも事故が起きようがありません、ここは私自身が今回のバグで痛感したところでもあります

使った道具は「最新の保守されたもの」だけ

技術の中身には深入りしませんが、1点だけ、今回 古い(メンテが止まった)接続方式をやめて、今も保守されている方式に乗り換えられたのは大きな前進でした

使ったのは3つで、安全な経路(SSH)を扱う asyncssh、データベースとやり取りする aiomysql、Claudeと話す土台になる FastMCP、それぞれ「SSHを扱う道具」「データベースを扱う道具」「MCPを作る土台」くらいの理解で十分です

名前を覚える必要はありません、ポイントは 今も更新が続いているライブラリだけで動くようにできたこと、古いものに縛られて身動きが取れなかった状態から解放されたのが、地味にいちばん嬉しかったところです

実際に使ってみたらこうなった

道具が完成して、Claudeに登録したあと、さっそく試してみました、頼み方はいたってシンプルで、日本語で「このテーブルから昨日ぶんのデータを抽出して」とお願いするだけです

するとClaudeが裏で問い合わせ(SQL)を自分で組み立てて、結果を返してくれました、私はSQLを1行も書いていません、それでも自分がためているデータがちゃんと取れて、試したときは千件を超える実データが返ってきました

ジャベ雄

自分のデータに話しかけて答えが返ってくる感じ、ちょっと未来っぽくて楽しいんですよ

これで 自分専用の「自分のサーバーのデータベースをClaudeから覗く道具」が手に入りました、欲しかったのはまさにこれです、既製品では届かなかった一歩を、自作で埋められたという達成感もありました

使ってみて地味に効いたのが、データの中身を確認するためにいちいち管理画面を開かなくてよくなったことです、これまでだと「あのデータどうなってたっけ」と思うたびにブラウザでログインして画面をたどっていました、それが今は、Claudeに一言聞けば返ってくる、この距離の近さが思った以上に快適でした

しかも返ってきた結果について「この中で件数が多い順に並べて」とか「先週ぶんと比べてどう?」みたいに、そのまま会話で深掘りできます、データを取り出す道具と、それを読み解く相手が同じ場所にいる、この一体感がふつうのデータベース管理ツールとはひと味違う使い心地でした

もう少し具体の流れを書いておくと、たとえば あるテーブルに対して「ここから昨日ぶんを出して」と日本語で頼むと、Claudeがその指示を読み取って、裏で問い合わせ(SQL)を自分で組み立てます、私が見ているのは「昨日ぶんを出して」という自分の文と、しばらくして返ってくる結果だけです、途中の命令文を意識しなくていいのが、思った以上に身軽でした

ひとつ注意があって、取り出す件数が多いと、既定の上限で途中まで返って打ち切られることがあります、千件を超える量を一気に頼むと、最初のいくらかが返ってきて「ここまでで止めています」という挙動になる感じですね、全部ほしいときは「もっと多く返して」と上限を上げてもらうか、条件を絞って小さく取り直します、いきなり全件をどっと返さない作りは、安全側に倒すうえでもむしろ都合がよかったです

登録自体は数行で済む

「道具を登録」と書くと身構えるかもしれませんが、Claude Codeに道具(MCPサーバー)を教えるのは設定ファイルへの数行の追記です、ファイル名は .mcp.json で、ここに「どの道具を、どう起動するか」を書きます

イメージとしてはこんな形で、サーバーの名前と起動コマンドを書くだけです(中身は環境ごとに変わります)

{
  "mcpServers": {
    "my-db-tool": {
      "command": "（自作した道具を起動するコマンド）"
    }
  }
}

この設定ファイルが何者なのか、ほかにどんな設定ファイルがあるのかはClaude Codeの設定ファイル早見表にまとめています、.mcp.json の置き場所や役割が気になったらそちらをどうぞ

そして設定ファイルを触るのが怖い人へ、ここも Claude自身に「.mcp.jsonにこの道具を登録して」と頼んで書かせるのが楽です、書いてもらった内容を自分で確認してから反映すれば、手で打ち間違える心配も減ります

コードを書けなくても自分専用の道具は作れる

最後にまとめます、今回いちばん伝えたいのは Claude Codeを使えば、設計から実装、レビュー、公開まで伴走してもらいながら、自分専用の道具(MCP)を作れるということです

振り返ると、私が手を動かしたのは「何を作るか相談する」「設計書を読んでOKを出す」「最後の確認をする」あたりで、実装そのものはほとんどClaudeに任せていました、それでもちゃんと動くものが手に入ります

• いきなり書かせず、まず壁打ちで「何を作るか」を言葉にする
• 設計と実装はClaudeに任せ、人間は読んで判断する側に回る
• 「作る役」と「チェックする役」を分け、最後に全体を見直す
• AIにデータを触らせるなら「読み取り専用」を基本に、権限は大本で絞る
• 設定ファイルが怖ければ、Claudeに書かせて内容を確認してから反映する

そして今回の出発点を思い出してほしいんですが、私が作ったのは「既製品が自分の環境に合わなかった」からでした、世の中にある道具が自分の環境にハマらないときこそ、自作の出番です

プログラムをゼロから書ける必要はありません、やりたいことを言葉にして、相談しながら一緒に作っていく、その伴走役としてClaude Codeは頼りになります、興味が出たら、まずは小さな「自分専用の道具」から試してみてはどうでしょうか?

ジャベ雄

「これ既製品じゃ届かないな」って思った瞬間が、自作のスタートラインなんですよね

Claude・生成AIを学べる本PR

実践Claude Code入門

西見公宏・吉田真吾・大嶋勇樹

Amazonで見る楽天で見る

Claude CodeによるAI駆動開発入門

平川知秀

Amazonで見る楽天で見る

開発効率をアップする! Claude Code 実用入門

大澤文孝

Amazonで見る

私のおすすめからランダムで3冊を表示しています