🧠 スキルとハーネス設計 23問

課題で作成したskill(AIに特定の作業のやり方を覚えさせておく設定ファイル)の叩き台が完成した後、それを使いながらどうアップデートしていけばいいか、具体的な方法がわからないという質問です。

講師は図解作成のskillを例に説明します。作った直後は見やすいと思っても、繰り返し使ううちに「ここの色が派手すぎる」「この文章が長すぎる」といった気になる点が出てきます。そうした気づきをもとにskillをチューニングし、より見やすいものへ育てていくことがアップデートの基本です。

コツは、AIに対して具体例を渡すことです。「あなたの作った図解のここが長すぎる」と、キャプチャ(画面の様子を画像で保存したもの)やリンクを添えて具体的に伝えると、AIはある程度うまくskillを更新してくれます。ただし、その問題だけをピンポイントで解決しようとしてしまう傾向があるため、もっと本質的な改善をしてほしい場合には、「パッチワークではなく、今回の問題の本質を捉えて仕事をしてください」という一文を添えるのが効果的です。パッチワークとは、屋根に穴が開いたときにとりあえずレンガで塞ぐような、その場しのぎの対応を指します。この一文を加えることで、伝えた問題点をなくすだけでなく、そもそもの原因から改善したり、他の似たパターンでも問題が起きないようにしてくれたりするようになります。

もう1つの注意点は、skillを修正し続けていると、気づかないうちに内容が散らかっていくことです。同じことが別の場所にも重複して書かれていたり、古い情報が残っていたりする状態になりがちなので、AIに任せっぱなしにせず、自分でも読んで整理されているかを確認する必要があります。レビューをAIにさせる場合、講師は「最近のskillについて熟知したAnthropicのエンジニアとして」サブエージェント(特定の役割を与えて動かす補助的なAI)を立ち上げてレビューさせる、という方法をよく使うといいます。skillという仕組みを作った側であるAnthropicの視点を借りることで、質の高いレビューが期待できるからです。

社内のあらゆる情報をGitHub(コードや文書の保管・管理サービス)にマークダウン形式で集約しようとする中で、リポジトリ(プロジェクトの保管庫)をどう切り分けるか悩んでいるという質問です。全社共通の情報と事業ごとの情報の分け方、給与情報などの機密データをどこまで同じ場所にまとめてよいかの判断基準が知りたいという内容で、SSoT(Single Source of Truth。同じ情報は1ヶ所だけで管理するという原則)に基づき、なるべく1つのリポジトリに集約すべきかという疑問も含まれています。

複数のプロジェクトを1つのリポジトリにまとめる構成は一般に「モノレポ構成」と呼ばれます。しかし、会社の情報をすべて1つのリポジトリに入れてしまうと、個々人の給与情報や評価面談の文字起こしまで全社員に見えてしまう状態になり、使いにくくなります。そのため講師の会社でもリポジトリは分けています。会社の経営に関わる重要情報や個人の報酬情報が入ったリポジトリは、独立したリポジトリとして権限を別に管理し、それ以外は基本的に事業部ごとに1リポジトリを作るという方針です。

ただし、事業が進むと1つのリポジトリの中にiPhoneアプリのコード、Webアプリケーションのコード、カスタマーサポート関連の情報などが混在し、逆に何がどこにあるかわかりづらくなることもあります。そうした場合は、大きくなりすぎたリポジトリを適宜切り出しているといいます。最初からリポジトリを細かく分けすぎる必要はなく、権限上問題がなければ1つの事業部の情報を1つのリポジトリに集約し、重くなってきたら切り出すというやり方が現実的です。

全社で共有したい情報については、共通フォルダを作り、GitHub Actions(GitHub上でコードの実行や作業を自動化する仕組み)を使って、そのフォルダの内容を更新すると他のすべてのリポジトリに自動で反映される仕組みを作っているといいます。各リポジトリ側では直接編集せず、元のソースだけを更新する運用にすることで、情報の重複や食い違いを防いでいます。

講師はこれを「1つのやり方にすぎず、もっと良い方法があるかもしれない」としながらも、どんなツールややり方を採用しても、SSoTの原則を守ることだけは変わらない普遍的な考え方だと強調しています。

講義で共有された図解ツールなどの中身を見ても、どうやったらそこまで作れるのか、自分のやり方が合っているのかわからず、「バチッとはまる感覚」を得られずにいるという質問です。ツール開発の手順やフォーマット、流れを教えてほしいという内容です。

講師はまず、この点について一言で答えられるものではないと率直に述べます。AI-Driven School全体が、まさに「ツール開発において何を大事にすべきか、どんな手順でやるのがいいか」をさまざまな切り口から伝え続ける全12回のプログラムであり、一言で全部うまくいく方法があるわけではないからです。

そのうえで講師が勧めるのは、共有された図解ツールが「なぜこのやり方になっているのか」をAIに噛み砕いて解説してもらうことです。講師自身、共有したツールが完璧だとは思っていないとしながらも、そこにある設計判断には意味があるとしています。

たとえ話として、サッカー未経験の人がプロサッカー選手に「絶対にうまくなるたった1つのコツを教えて」と聞いても、プロからすれば「練習することだ」としか答えようがないという例を挙げています。なるべく無駄な試行錯誤を省いて学べるように設計しているつもりだが、一言で誰でもできるようになる方法を示すのは難しいというのが正直なところだといいます。

開発の手順があるとすれば、それは「AI-Driven Rules(AIを使いこなすための行動指針)を厳守して作っていくに尽きる」と講師は答えます。講師自身もAIでツールを作り始めた当初はプログラミングにブランクがあり、あれこれAIに指示をしてそれっぽいものはできても、何がどう動いているか全然わからない状態から始まったといいます。そこから1つずつ理解を積み重ねていき、今でもAIの書いたコードのすべてを理解できているわけではないとのことです。これは現役のエンジニアも同様で、大枠は理解していても、細部の細部まですべて読んでいる人はほとんどいません。学習を積み重ねていけば、いつか必ず「バチッとはまる感覚」が来るので安心してほしいと締めくくっています。

スキル(AIに特定の作業のやり方を教える再利用可能な指示書)には、どのリポジトリ(プロジェクトの保管庫)でも使える「ユーザースキル」と、特定のリポジトリだけで使う「プロジェクトスキル」があります。講師や運営会社はどちらを主に使っているのかという質問です。

結論として、基本方針は極力プロジェクトスキルにすることです。ユーザースキルとして設定すれば、Cursor(AIが組み込まれたコード編集ツール)やClaude Code(ターミナル上で動くAI開発ツール)をどこで開いても呼び出せて便利に思えます。しかしスキルはAIが状況を解釈して自動的に発動することがあるため、使う予定のないスキルが手元にたくさんある状態は、「このプロジェクトではそのスキルを使ってほしくなかった」という誤作動を招きやすくなります。

そのため、スキルは基本的にそのスキルが関連するリポジトリの中に置くのが望ましいとされています。応用的な運用として「モノレポ」(1つのリポジトリの中に複数のアプリケーションをまとめて置く運用方法)という考え方もあります。この場合、リポジトリの下にアプリケーションごとのフォルダーがあり、その各アプリケーションのフォルダーの中にある .claude フォルダー(Claude Codeの設定を置く場所)に、そのアプリケーション専用のスキルを配置します。そして実際の作業は、そのアプリケーションのフォルダーの階層でCursorやClaude Codeを開いて行います。

モノレポでリポジトリをまとめるメリットは、複数のツール間の連携や統合がしやすくなることです。一方でデメリットとして、1つのリポジトリがどんどん肥大化していく課題もあります。どちらが正解というものではなく、開発するものの性質によって使い分ける判断です。

なお、すべてのリポジトリで共通して使いたい設定は、ホームディレクトリ(パソコンの個人用フォルダーの起点)直下のCLAUDE.md(AIへの初期設定を書くファイル)に書くとすべてのリポジトリで読み込まれます。ただしこのファイルは極力簡潔に保つことが推奨されています。

便利なスキル(AIに特定の作業のやり方を教える再利用可能な指示書)をどんどん作って保存・更新していくうちに、どこに何を置いたか分からなくなってきたという質問です。

まず立ち止まって「スキルはどこに置いたら、どのように読み込まれるのか」という仕組みを確認することが第一歩です。基本方針としては、そのスキルが関連するリポジトリ(プロジェクトの保管庫)の中に置くことです。単体でいろいろな場所で使いたいスキルであれば、どのリポジトリでも呼び出せるユーザースキルとして定義できますが、その分、意図しない場面で勝手に発動してしまうリスクも高まります。

ここで押さえておきたいのは、Cursor(AIが組み込まれたコード編集ツール)とClaude Code(ターミナル上で動くAI開発ツール)では、スキルの読み込まれ方に実は差があるという点です。スキル名のフォルダーの中に skill.md(スキルの内容を書くファイル)を置くという基本形式は共通していますが、スキルの扱い方やスキル内に書ける内容には違いがあります。この差は最初のうちは大きな支障になりませんが、スキルをよりこだわって作り込もうとする段階になると理解が必要になってきます。

どこにスキルを置き、どんな名前にするか、Cursor専用にするかClaude Code専用にするか、両方で使えるようにしたいのかによって置き方は変わります。これは実はエンジニアリングにおける「どこに責任を持たせるか」という設計判断そのものであり、講師自身も日々悩みながら整理している問題です。絶対的な正解が決まっているわけではなく、CursorやClaude Codeがどのようにスキルを読み込んでいるのかという根本の仕組みを自分で調べて理解することが、迷子にならないための近道になります。

スキル(AIに特定の作業のやり方を教える再利用可能な指示書)と、その中で参照するリファレンス(詳細な参考情報をまとめた資料)を分けて管理する際、リファレンスの内容のまとめ方や、AIに精査してもらうときの良いプロンプト(AIへの指示文)を知りたいという質問です。

講師のおすすめは「最新のスキルのベストプラクティス(最も良いとされるやり方)について熟知したAnthropicエンジニアならどうするか、サブエージェント(特定の役割・視点でレビューなどを行うAIの分身)にレビューをしてください」というプロンプトです。スキルという仕組みの教科書はAnthropic(Claudeを開発する企業)の公式ドキュメントであるため、「Anthropicのエンジニアならどうするか」という視点をレビューの基準に据えています。

このプロンプトに「最新のベストプラクティスを熟知した」という言葉を入れているのは、AIに実際にウェブで最新情報を調べさせるためです。スキルへの基本的な考え方は大きく変わりませんが、ベストプラクティス自体は徐々に更新されていきますし、Anthropicの公式ドキュメントも随時更新されます。そのため、古い知識のままレビューさせるのではなく、最新のウェブ情報に基づいた判断を促す狙いがあります。

また、レビューをサブエージェントに任せるのは、それまでのチャットでのやり取り(コンテキスト)に判断が引っ張られないようにするためです。同じチャットの中でスキルを作りながらレビューもさせると、それまでの会話の流れに影響されて、公平な視点での指摘が得づらくなります。役割を分けたサブエージェントに新しい視点でレビューさせることで、より客観的な精査ができます。

なお、講師自身は「スキルを作るためのスキル」も作成しており、その中にAnthropicの公式ドキュメントの内容をまとめています。こうした専用スキルを用意すべきかどうかは議論の余地があり、あった方が使いやすいという考え方もあれば、余計なノイズになるという考え方もあります。

CLAUDE.md(Claude向けのAIへの初期設定を書くファイル)・agents.md(OpenAIなど他社のAIツール向けに同様の役割を果たすファイル)・hooks(AIが何か処理を実行した前後に自動で動くプログラム)について理解が追いついておらず、解説や実践を今後の講義で扱ってほしいという要望です。あわせて「ハーネス」という言葉についても説明されています。

CLAUDE.mdやagents.mdは、AIに対する初期設定やルールを書いておく場所です。Claudeの場合はCLAUDE.mdに、OpenAIのツールの場合はagents.mdに書くという住み分けになっています。hooksは、AIが何らかの処理を実行した後に自動で動くプログラムのことです。

そして「ハーネス」とは、これらCLAUDE.md・agents.mdのようなAIの振る舞いを設定するルール、再利用可能な専門能力であるスキル、コンテキスト(AIが認識している情報の範囲)を分離して担当を分けるサブエージェントの仕組み、AIの動作の前後に処理を挟み込むhooksの仕組み、さらにセキュリティ的な枠組みまで含めて、「じゃじゃ馬なAIを制御するための仕組み全体」を指す言葉です。AIはとても賢い一方でときに暴走するため、安全かつ思った通りに働いてもらうために取り付ける道具・ルール・仕切りをすべてまとめてハーネスと呼びます。

この根幹にある考え方は「AIに丸投げしても限界がある」という前提に立ち、AIを制御する仕組みを整えることでAIの性能を安定して引き出そうとするものです。例えばAIが作った原稿の言葉遣いが上から目線だった場合、その場でAIに直せば一時的には直りますが、次も同じミスが起きないようにするには、CLAUDE.mdのルールを修正する、原稿作成用のスキルを更新する、サブエージェントにレビューさせる、hooksで自動チェックのプログラムを走らせるなど、複数の選択肢があります。この「二度と同じミスをしない仕組みを作る」という発想が、ハーネスエンジニアリングの核です。

どこから手を付けるべきかは、コストパフォーマンスの良い方法からです。CLAUDE.mdへの記載だけで解決するならそれで十分ですが、それだけでは解決しきれない場合に、より大きな枠組みとしてハーネス全体を設計する視点が必要になります。ハーネスの全体を最初からすべて使いこなそうとするのはオーバースペックであり、AIの出力の質を突き詰めて高めたいと感じた段階で初めて必要になる考え方です。ハーネスという言葉そのものを前面に出すかは未定ですが、より具体的な場面に即した形で、今後の講義でも取り扱っていく予定です。

スキル(AIに特定の作業のやり方を教える再利用可能な指示書)やツールを磨いていく作業と、AIとのやり取りを続けているうちに迷走してハルシネーション(AIが事実に基づかないもっともらしい内容を出力してしまう現象)が起きる現象の違いを知りたいという質問です。

「やり取りを続けて迷走する」という現象は、1回のチャット(AIとの対話の一連の流れ)の中でやり取りを重ね続けることによって起こります。AIにはコンテキストウィンドウ(一度に処理できる情報量の上限)やアテンション(入力の中のどこに注目するかという仕組み)に物理的な限界があり、やり取りが長くなるほどこの限界、いわゆる「壁」にぶつかって性能が落ちていきます。1つのスキルを良くしようとして、そのためだけのチャットをずっと残したままやり取りを重ねていくと、AIは最初に伝えた指示を徐々に守らなくなり、応答が迷走していきます。

この現象を避けるには、やり取りを意図的に区切ることが必要です。「ここまで」と自分で線を引き、いったんチャットを終えて新しいチャットを立ち上げ、そちらで作業を続けます。これを繰り返しながらスキルを磨いたり、アプリケーション開発を進めたりするのが基本のやり方です。

つまり「スキルを磨く」という行為自体が迷走を招くわけではなく、1つのチャットに情報を溜め込みすぎたまま作業を続けることが迷走やハルシネーションの原因になります。区切りを意識してチャットをリセットしながら進めることで、AIの性能を安定させたまま、スキルやツールの改善を積み重ねていくことができます。

開発スピードを優先すると技術的負債(その場しのぎの対応が積み重なり、後から修正コストとしてのしかかる状態)が増えて品質担保が難しくなり、逆にAIが書いたコードを理解しながら進めると開発スピードが落ちるというトレードオフをどう扱えばよいか、最初はスピードを捨てて理解に徹すべきかという質問です。

答えは、その開発が何のために行われているかによって変わります。仮説検証、つまり「そもそもこのツールに価値があるか」「便利かどうか」がまだ分からない段階であれば、コードの品質を緻密に整えることにこだわりすぎるのは時間の無駄です。多少コードが荒くても、明日ユーザーに使ってもらえるレベルであれば、いったん出してフィードバックをもらう方が合理的です。

一方で、高品質なプロダクトを生産性高く開発し続けたいという段階では話が変わります。プログラム全体がどう動いているかを理解しないまま突き進むと、結局すべてやり直しになるケースが多く発生します。「突っ走ると結局遅くなる」というのが経験則です。プログラムは使い続ける限り改善したくなるものであり、一度作って終わりということはほぼありません。パッチワーク的に継ぎ接ぎで対応したものは負債として蓄積し、いつか高いコストで返済することになります。

そのため開発の大原則は、何をしているかを自分の頭で理解しながら、その場面において整理整頓を心がけて作ることです。実践的な手段として、コードを書いたあとにエンジニアの視点を持つサブエージェント(特定の役割でレビューを行うAIの分身)にレビューをしてもらう方法があります。サブエージェントは細かいところまで指摘してくれる一方、必ずしもすべてを修正する必要はなく、「本当にクリティカルな問題かどうか」を自分の頭で判断することが重要です。クリティカルな指摘を無視し続けると、結果的に大きなやり直しやバグの温床につながり、トータルで高いコストを払うことになります。

AIにコードレビューをさせると際限なく改善案を出してくるため、どのタイミングで一旦線を引くべきか、工数対効果(かけた手間に対して得られる効果)の観点で引き際を知りたいという質問です。

講師は基本的に2つのタイミングでレビューをさせています。1つ目は開発計画を立てた段階です。社内ではOpenSpec(どんな開発をするか、どんな技術で作るか、どんなタスクがあるかを事前に整理するためのフレームワーク)というツールを使って開発計画をまとめ、シニアエンジニアの視点を持つサブエージェント(特定の役割でレビューを行うAIの分身)にレビューさせます。UIが絡む場合はUI/UXデザイナーの視点を持つサブエージェントにもレビューさせます。コードを書く前にレビューする方が、後から修正するより効率がよいためです。なお、OpenSpec自体は誰にでも積極的におすすめできるツールではなく、個人開発にはやや大げさで面倒に感じられる場合もあります。

2つ目は、コードを書いた後です。すべての開発が終わってからではなく、開発計画の中のフェーズ(段階)ごとに、実際に書いたコードを1回レビューしてもらいます。それ以上何度も繰り返してレビューをかけることはありません。

重要なのは、サブエージェントのレビュー結果のすべてを修正する必要はないということです。サブエージェントは、そこまでやる必要があるか疑わしいほど細かい指摘もしてきます。返ってきた内容が理解できない場合は、噛み砕いて説明してもらい、「これは本当に今やるべきか」を自分の頭で判断します。そのうえで、クリティカルな指摘(致命的、あるいは重大な問題を指す指摘)だけを修正して終わりにする、というのが講師の実践する線引きです。この運用で問題が起きたことはほとんどないとされています。

サブエージェント(特定の役割でレビューを行うAIの分身)のレビュー結果を見ても、内容がよく分からないまま結局そのまま実行してしまうという初心者の悩みです。

講師自身も正直なところ、「なんとなく問題がありそうだから修正しておこう」と、内容を完全には理解しないまま進めてしまうことがあると認めています。ただし、それはいつも罪悪感を抱えながらの対応であり、基本的には理解してから進めるようにしています。

実践的な工夫として、レビューをさせる際に「レビュー結果は、技術が分からない人でも直感的に分かるように、簡単な言葉で説明してください」とあらかじめ指示しておく方法があります。こうすることで、最初のレビュー結果からすでに分かりやすい言葉で返ってくるようになり、毎回聞き返す手間を省けます。この指示を繰り返し使うようであれば、スキル(AIに特定の作業のやり方を教える再利用可能な指示書)に組み込んでしまう、あるいはCLAUDE.md(AIへの初期設定を書くファイル)やagents.md、Cursor Rules(Cursor向けのルール設定)に書いておくという方法もあります。AIへの指示はプロンプト(その場での指示文)で直接伝えるのが最も優先度が高く、AIに聞いてもらいやすいとされています。

一定の開発経験がある講師自身でも、サブエージェントの指摘の意味が分からないことがあります。そうした場合は、なんとなく言っていることが分かる範囲で前に進めることもありますが、まったく理解できない段階でレビュー通りにどんどん改善を進めてしまうと、自分の意図しない方向に気づかないうちに進んでしまうことがよくあります。

おすすめの姿勢は、レビュー結果を分かりやすい言葉にして返してもらうよう最初から指示しておくこと、そして分からないときは焦らずに質問することです。この積み重ねによって、いきなりではなく少しずつ技術への理解が深まっていきます。

スキル(AIに特定の作業のやり方を教える再利用可能な指示書)やリファレンス(詳細な参考情報をまとめた資料)を触り続けているうちに、かけた時間に対して得られる効果が見合わなくなり、完璧を目指さず手動対応を残す方が現実的だと感じるケースについて、どこまで直してどこで止めるかの判断基準を知りたいという質問です。

これは絶対的な指針がなく、使っているツールや目的によってケースバイケースになる、という前置きのうえで、経験則が語られています。AI開発ではどんどん形になっていく過程で「もっとこういうことができればいいのに」と機能を付け足したくなりますが、そこで思っていた5倍・10倍の時間がかかり、沼にはまってしまうことは非常によく起こります。

この線引きは「夢と現実、どちらが大事か」という問いに近く、どちらも大事であるがゆえに悩ましいものです。すべてのやりたいことを詰め込んだ「夢」と、一旦動くものとして仕上げる「現実」の間で、どれだけアクセルを踏み、どれだけブレーキを踏むかという判断そのものが、エンジニアリングの技量と言えます。

新しく機能を追加するかどうかを判断する際の重要な問いとして、「この機能がないとブチギレる人がいるか」「これがないと使いものにならない、と言われるだけの理由があるか」という基準が紹介されています。単に「必要か必要でないか」を考えると、作り手はどうしても「必要だ」と考えてしまいがちです。そこで「これがないと本当に困る人がいるか」という、より厳しい基準に置き換えることで、際限のない機能追加や細部の詰めに歯止めをかけやすくなります。

完璧を目指さず手動対応を残す判断は、多くの場面でむしろ現実的な選択になります。

図解のわかりやすさが個人のセンスに依存してしまい、AIで生成しても良し悪しの判断に迷う、業務で使う以上は属人化させず再現性を持たせたいという質問です。

結論として、最も重要なのは、自分たちが分かりやすいと思う模範解答(AIに参考として示す、質の高い出力例)を作り込むことです。AIに1回だけ出力させて終わりにするのではなく、何度も指示を重ねながら、これぞという模範解答を仕上げます。模範解答を作り込む以上にAIの性能を引き上げる方法はない、と言えるほど重要な作業です。

いい図解と悪い図解の判断基準について、AIは特に指示をしないと、簡潔で洗練されたまとめ方をしてくる傾向があります。しかし講師の考えるいい図解とは、その図解だけを見れば、前提となる知識や技術的な理解が必要な部分もすべて噛み砕いて説明されている、丁寧すぎるくらいの図解です。知識のある人にとっては多少冗長に感じられるかもしれませんが、それによって生まれるコストは大したことがありません。逆に、知識のない人が「これってどういうこと?」と質問し、それに答える工数が発生する方が、全体としての生産性を大きく下げてしまいます。

つまり、いい図解の判断基準を一言でまとめると「丁寧すぎるくらいの説明がちょうどいい」ということです。この基準を模範解答の形でAIに繰り返し学習させ、指示のたびに参照させることが、属人化を避けて再現性を持たせる最も実践的な方法になります。

AIがアクセスするSSoT(Single Source of Truth、情報の唯一の正しい保管場所という考え方)に従って、ソースデータはGitHubに、視認性が必要な社内ウィキはNotionに、タスクはLinearに、といった形でストック情報の置き場所とツールを使い分けているが、運営会社ではどのような全体像でツールを使い分けているのかという質問です。

基本方針として、情報は極力GitHubリポジトリ(プロジェクトの保管庫)に集約させるべきだと考えられています。Notionは以前は使い倒していましたが、今はほとんど使わなくなりました。ただしNotionが使ってはいけないツールというわけではなく、良い点も多くあります。リポジトリだけで情報を整理していくには、Gitを扱えるといった一定のリテラシー(知識・スキル)が働く人全員に必要になる、という制約があります。

タスク管理にはLinearを使っています。理由はAI経由で操作しやすいことです。ただしLinearでなければ絶対にできないことがあるわけではなく、細かい使い勝手の積み重ねで採用しているという位置づけです。

一方で、大きなサービスのカスタマーサポートのやり取りなど、膨大な情報をすべてGitHubリポジトリの1か所に貯めていくのは現実的ではありません。リポジトリは整理整頓された情報をストックする場所であり、大量の文章・画像・動画のような大容量データの置き場には向いていません。そうした場合は、まずテキストデータに変換できないかを検討したうえで、クラウドのデータベースやストレージシステム(講師らはSupabaseやSupabase Storageを使用)を活用しています。

Git上にコンテキスト(AIが認識する情報の範囲)を整理しておくと、スキル(AIに特定の作業のやり方を教える再利用可能な指示書)を呼び出す際に、常に最新のコンテキストを基にAIに仕事をさせることができます。同様のことはGeminiのGems(Googleが提供するカスタムAIアシスタント機能)やClaudeのプロジェクト機能でも部分的に可能ですが、これらはGitのように差分を管理してコミット(変更を保存する単位)していく仕組みがないため、こまめに最新の状態を保って更新していくという観点では、現時点では不便さが残ります。

AIエージェント(AIが自律的にツールを使って作業を進める仕組み)について、体系的に学べる場が欲しいという要望がありました。

まず、受講生はすでにAIエージェントを日常的に使っているという指摘がありました。たとえばCursorのチャットも、ファイルの読み込み・書き込み、Web検索といった複数のツールをAIが使いこなして動く、立派なAIエージェントです。「AIエージェント」という言葉を簡単に言えば「AI＋ツール」であり、この「ツール」という言葉が指す範囲が広く抽象的であるため、独立した専門分野として体系立てて学べるものは特にない、と説明されました。

自分専用のAIエージェントを一から作りたい場合は、どのAIモデルを使うか、どんなツールを使わせるか、どんな外部サービスと連携させるか(この連携の仕組みはMCP〈Model Context Protocol、AIと外部サービスをつなぐ共通規格〉と呼ばれます)を設計する必要があり、プログラミングの知識が求められる高度な取り組みになるといいます。

ただし、「AIエージェントを学ぶ」という特別な学問があるわけではなく、自分にとって都合のいい「AI×ツール」の組み合わせを作っていく営み全体が、ハーネスエンジニアリング(AIが動きやすい周辺環境を整える取り組み)にほかならないと説明されました。そしてこのハーネスエンジニアリングは、Gitでファイルや情報を管理するところからすでに始まっており、受講生はすでにAIエージェント作りの一歩を踏み出している、と位置づけられました。

自社商品のローンチ準備でNotion(ページやデータベースを扱う情報管理サービス)に商品情報・戦略・タスクなどを一元管理しているが、価格変更のたびに10〜20箇所の更新が必要になる。Claude CodeにNotionの更新を任せようとしても、Notion API(外部からNotionを操作するための窓口)が不安定で反映が難しい、という相談。Notionを使わなくなった理由についても質問がありました。

Notionを離れた理由は「AIフレンドリーではないから」と説明されました(最近は改善されつつあるとも補足されています)。事業の情報はすべてGitリポジトリ(ファイルの変更履歴を管理する保管庫)で管理しており、経営相談でもGitリポジトリでの一元管理を強くすすめているといいます。ただし、顧客情報についてはGitリポジトリでは管理していないと明言されました。

一方で、Notionで一元管理するという考え方自体は素晴らしいとした上で、Git管理にも難しさがあることが率直に語られました。たとえば複数メンバーでの閲覧のしやすさはNotionに分があり、逆にGit管理は変更履歴の追いやすさに強みがあります。それでも、社内の共有フォルダにWordファイルが散らばっている状態よりは、Notionでもはるかに良いとされました。

AIの性能を最大限引き出したいのであれば、まず一部の情報だけを切り出してGit管理を試してみることがすすめられました。複数人で運営している場合、他のメンバーがGitに慣れるまでに2週間〜1ヶ月ほどかかりますが、一度慣れるとNotionには戻れなくなるという体験も語られました。Git管理はAIに読み込ませやすく自由度が高い一方、使う側に一定のリテラシー(知識や使いこなす力)が求められ、Notionの便利な機能(データベースビューなど)は使えなくなるというトレードオフがあります。

結論として、NotionとGit管理のどちらが絶対的に正しいかではなく、自分がどこで独自の付加価値を出したいかという戦略的な判断によって選ぶべきだとされました。

開発を続けていくうちに、.cursor や .claude(CursorやClaude Codeがスキルや設定ファイルを保存するフォルダ)の中身がいつの間にか増えてしまい、整理の仕方に悩む、という相談でした。

「整理の仕方もAIに聞くとよいか」という問いには、明確にYESと回答されました。AIにどんどん作業を任せていると、リポジトリ(ファイルをまとめて管理する保管庫)が散らかっていくのは誰にでも起こることだといいます。

その対策として重要なのは、今のフォルダの中身を確認しながら、あるいはコミット(変更内容を記録として保存する操作)する前に何が変わったのかという差分を確認しながら、こまめにコミットを重ねていくことです。CursorやClaude Codeでは、自分がAIに依頼した結果としてどんなファイルが増えた・減った・変更されたのかという差分を、ひとつひとつ確認しながら細かくコミットしていくことで、自分がAIに何をやらせたのかを把握しながら進められる、と説明されました。

ハーネスエンジニアリングとは、すごく賢いけれどたまに間違った方向に行ってしまうAIを制御するための仕組み全体を組み立てる作業のことです。具体的には、AI向けのルール・スキルを作ること、サブエージェント(特定の役割に特化させた分身AI)やフック(AIの意思に頼らず、一定の条件でプログラムやAIを強制的に動かす仕組み)を用意すること、バリデーション(出力が正しい形式・内容になっているかの検証)やセキュリティのチェックを組み込むことなど、AIを操るための仕組み全般を指します。

うまく行うコツは、最初からやりすぎないことです。おすすめの順番は次の通りです。

1. まずAIにざっくりと丸投げしてやらせてみる
2. 何がダメだったかを確認する
3. 模範解答(お手本となる完成例)を渡してみる
4. それでも足りない部分について、ルールやスキルの中身を整備する
5. それでも難しいときに初めて、サブエージェント・フック・プログラムによるバリデーションを検討する

サブエージェントやフックのような「いかにもハーネスエンジニアリングらしい」仕組みを最初からすべて使おうとするのはオーバースペックです。AIがミスをするたびに「二度とミスをしないように」と仕組みを一気に装着してしまうと、何が間違っているのかがかえって分からなくなります。

まず3つの保存形式をおさらいします。Markdownは見出し・箇条書き・強調などを記号で表現できる軽量なテキスト形式で、人間が直接読み書きしやすく、Gitで履歴管理もしやすい、最も手軽な文章のまとめ方です。JSONはキーと値のペアでデータを構造化する形式で、プログラムから読み書きしやすく、件数が増えてきた構造化データの保存に向きます。データベース(略してDB)は、さらに大量のデータを表形式で保管する仕組みで、複数人の同時編集や高速検索に強く、Gitでは扱いきれない領域に進むときの選択肢です。

判断の勘所は、基本的にはハーネスエンジニアリングのコツと同じ考え方です。迷ったら情報はMarkdownで管理するところから始めるのが原則です。それが最も手軽で、AIの性能を落とすこともない選択だからです。

一方で、自分の中で「これは明らかにWebアプリケーションにしていく」という覚悟を持って進めるときは、最初からデータベースを前提に情報管理する選択もあり得ます。カジュアルな飲食店を開くなら、安く素早く美味しく作れることが大事なので、材料をすべて手作りする必要はなく、既製品を活用すれば十分です。しかし食通も唸らせる一流のレストランを作ると決めているなら、材料や調味料の一つひとつからこだわり、既製品を使う選択肢は最初から考えないはずです。自分がどこまでの完成度のものを作りたいかによって、判断は変わります。

つまり判断の勘所は経験を積むことで確実に磨かれていきますが、迷った時点でのデフォルトの答えは常に「まずはMarkdownで管理する」であり、これを土台にしておけば大きく判断を誤ることはありません。

まずはシンプルに実現する方法を考えることから始まる、というのが基本方針です。ただしAIの性能がものすごい速度で上がっているなかで、最初からある程度しっかりしたサービスにする前提で開発を始めることも増えています。それでも「小さく試していく」ことを重視する理由は、無駄な頑張りをしたくないからです。既存のツールへの簡単な指示やスキル(AIに繰り返し使わせる作業手順・専門知識のまとめ)だけで十分な仕事をしてもらえるのに、最初からガッツリとしたツール開発を前提に考えるのはオーバースペックになりがちです。

AIコーディングで自分のツールを作る経験を重ねると、「このツールは最終的にデータベースにしたくなるだろう」といった未来が読めるようになってきます。しかしこれは葛藤すべき危険な誘惑でもあります。人はついつい最初から完璧を目指して作りすぎてしまうからです。

これまでの講義で扱ってきたように、AIにはコンテキストウィンドウ(一度に読み書きできる情報量の上限)・アテンション(どの情報に注目するかの集中力)・オートリグレッション(直前までの出力を踏まえて次の一語を予測し続ける性質)という3つの壁があります。自分の理想を詰め込んで一気に高度なものをAIに作らせようとすると、これらの限界に達して性能が劣化し、指示した内容がきちんと反映されなくなります。

さらに、一気に作ってしまうと、作りながら気づく発見を最初の設計に取り込めません。着手した時点での理想のイメージと、作っている途中での理想のイメージは必ず変わっていくもので、「最初はこう思っていたが、冷静に考えるとこっちのほうがいい」という気づきは誰にでも起こります。一気に作ってしまうと、こうした気づきが膨大な「そもそも論のやり直し」になってしまい、トークンも作り直す時間も無駄になります。

結論として、本当のコアな部分から完成させ、小さく作って大きく育てていくのが大原則です。あとは知識と経験を積むほど、判断のスピードは上がっていきます。

体感としては実装の時間の方が長いといいます。ただしこの「実装時間」のほとんどは、プルリクエスト(コードの変更を本番のサービスに取り込む前に、バグやおかしな挙動がないかを検証してもらうレビュー依頼)を出したあとの、テストの実行とAIのコードレビューを待つ時間です。この待ち時間だけで、実装時間の9割ほどを占めている感覚があるといいます。その間はただ待っているのではなく、同時並行で複数の作業を進めています。AIのレビューを受けて修正する作業自体はAIに任せきりで、1行1行コードを確認することはなく、ざっくりと構造として何をしたのかを理解できればよいとしています。

タスクの重要性や自分の集中力をどこに向けているかという観点で見ると、設計・企画の比重が9割というのは的を射た感覚だといいます。実装力、つまり細かいコードの文法を理解してコードに落とし込む力は、もうほとんど不要で、そこは全部AIがやってくれます。最も重要なのは、自分が作っているツール・プロダクトのコンセプト(そのツールがどこに向かうのかの言語化)です。

作りながら「もっとこうしよう」と気づくことは必ず起き、これをゼロにすることはできません。しかし、やり直しが増えてしまう主な要因は、ツール・プロダクトのコンセプトが明確でないことにあります。コンセプトを言語化する力を養う手段として、『コンセプトの教科書』という書籍を読むことが勧められています。

つまり「設計

=9」に偏ること自体は、AI時代の開発として理にかなった配分であり、重要なのは比率の数値そのものよりも、設計の中身、特にコンセプトがどれだけ明確になっているかだといえます。

結論として、フックとエージェントチームにがっつり時間を取って講義で扱う予定は、今のところありません。理由をそれぞれ説明します。

エージェントチームとは、複数のサブエージェントが同時に立ち上がり、エージェント同士が議論しながらユーザーの依頼に対して最も良い結論を導き出す仕組みで、特にClaude Codeに実装されたことで話題になりました。しかしこの仕組みはトークン(AIが処理する文章の単位で、使用量に応じて費用がかかる)を非常に多く消費するうえ、講師自身も週1回使うかどうかという程度でした。使う場面は、どうしても解決できない問題に詰まったときに限られます。近年はモデル自体の性能が上がったことで、単体のモデルで解決できることが増えています。

エージェントチームの難しさは、チューニング(構成の調整)の正解が分からないことです。例えばエンジニア役・デザイナー役・企画者役のエージェントを立ち上げて議論させても、その役割構成が本当に最適なのかを判断する材料がありません。仮にうまくいったとしても、それが再現できるものなのか、たまたまの「ラッキーパンチ」だったのかを検証しにくいのです。AI活用の上手さとは何度やっても高い品質のものが出てくる「再現性」であり、なぜうまくいったのかが検証しにくい機能は使いづらいといいます。トークン代を払うのであれば、Claudeの「Fastモード」(通常のおよそ2倍のトークン費用がかかる代わりに、実行速度が大きく上がるモード)を使って人間と素早くやり取りしながら解決する方が、手っ取り早くおすすめだとしています。なお現在の開発の現場では、エージェントチームよりも「Dynamic Workflows」という、同じく複雑な作業を任せるための別の仕組みが注目されているとも紹介されています。

フックとは、AIの意思に頼らずにプログラムやAIを一定の条件で動かす、抽象度の高い便利な仕組みです。100回に1回のAIのミスをどうしても防ぎたい、というときの選択肢になります。理解するには、実際にCursor・Claude Code・Codexのいずれかで、AIに聞きながら1つフックを設定して動かしてみるのが一番だといいます。ただし最初からフックを積極的に使うことはおすすめされていません。仕組みが複雑になりやすく、成り立たせるまでに何度も試行錯誤が必要でトークン費用もかさむためです。実際、教材で使われている管理ツール「Quiz Studio」はフックの仕組みで動いていますが、デバッグ(不具合の原因を探して直す作業)には大変苦労したといいます。うまく設計できればAIの限界を超えることもありますが、それは「フックを使えば超えられる」のではなく「適切に設計できたときに限り超え得る」というだけであり、AI活用・AI開発の中級者以上になってから扱うべき機能だと位置づけています。

質問にある「Superpowers」とは、Claude Code用に有志が公開しているスキルの詰め合わせパッケージのことです。計画立案・デバッグ・コードレビュー・並列サブエージェント実行といった汎用スキルがセットになっており、公式プラグインからワンコマンドで導入できます。

結論として、講師自身はSuperpowersを使っていませんが、アンチというわけでもありません。以前はこうしたスキルセットを積極的に導入していた時期もありましたが、今は極力減らしているといいます。理由は、スキルは登録すると勝手に動くため、古いスキルが残っていることで自分が予期しない動作を引き起こすことがよくあるからです。また、一度作ったスキルはメンテナンスをし続ける必要があり、モデルが進化した結果「そもそもこのスキルがなくてもちゃんと動く」という状態になることも多くあります。すごく賢い人たちが作った詰め合わせパッケージを導入すると性能が上がったと感じる人もいますが、長く使ううちに「本当に必要か」と感じる瞬間がやってきます。中身を理解せずにパッケージをそのまま入れた状態にしていると、その取捨選択ができなくなってしまいます。パッケージの導入自体がダメなのではなく、ずっと使い続ける前提ではなく、日々使いながら「必要なスキルか」を考え続け、取捨選択していく姿勢が重要だということです。

具体的に「今」あったほうが便利だと感じているスキルとして、開発では2つ挙げられています。1つはプルリクエスト(コードの変更を本番のサービスに取り込む前のレビュー依頼)を作るスキル、もう1つはイシュー(タスクのこと)を作るスキルです。運営会社ではLinearというプロジェクトタスク管理ツールを使っており、そこでの1つのタスクをイシューと呼びます。開発において欠かせないのはこの2つで、それ以外は「ないと困る」とまでは感じないといいます。教材管理ツール「Quiz Studio」で使っているスキルは必須のものばかりですが、これらは汎用的なものではなく、明確な目的を持って動くスキルたちです。開発以外では、予約系のスキルが便利だといいます。これは主にClaudeの「Cowork」という機能で使われ、例えば美容室の予約では、カレンダーの空いている時間を見て、一定の期間を空け、いつもの担当者・いつものプランで予約を自動で押さえるように設定されています。

なお、講師自身1〜2週間ごとにスキル構成をチューニングしているため、「今週伝えた構成が来週にはもう使っていない」ということが起きるほど流動的である、という補足もあります。おすすめの構成そのものよりも、常に見直し続けるという姿勢が重要だということです。