前回まで

前回は、筆者が考える「ナレッジスキル」の3分類のうちの2つ目、「設計の指針」を紹介しました。ナレッジスキルは、次のように分類しています。

1. 純粋なナレッジ
2. 設計の指針
3. ベストプラクティス

今回はその最後の1つ、「ベストプラクティス」です。これは本質的には前回の「設計の指針」と同じ種類のものですが、もう少し小さな粒のもの、と筆者は感じています。この連載の「スキル」の話の締めくくりとして、この「ベストプラクティス」を解説します。

「ベストプラクティス」とは何か

開発の世界では、「ベストプラクティス」という言葉をよく見かけますし、よく使います。ですが、正確にはどういう意味なのでしょう？ この記事を書こうとして、筆者の中にこの疑問が湧きました。ChatGPTに聞いてみたところ、「その分野で、一般的にうまくいく可能性が高いとされている、推奨されているやり方」という答えが返ってきました。それはそれでよいのですが、筆者がこの記事で扱いたいのは、次のような話です。

1. 何かを試して、何かにつまずいて、そこに時間がかかった。ときには調べものもした
2. 最終的にその解決策を見つけ、何が必要だったのかを理解した
3. それが自分にとっての「ベストプラクティス」なので、スキルとして保存する

こういった流れで得られたものを、この記事では「ベストプラクティス」と呼び、これを蓄積していくことを筆者は推奨していると捉えてください。

ベストプラクティスの例：pxかremか

世の中でベストプラクティスと呼ばれるものは無数にあるので、ここでは、CSSに関するトピックを1つだけ挙げてみます。「pxかremか」です。

これはとてもありふれた設計上の判断です。font-sizeにはremを使うべきなのか？ いつremを使うべきなのか？ こういう疑問が自分の中に湧いたら、その感覚を絶対に見過ごさないでください。AIに聞くのです。「Hey Claude Code、フォントサイズの指定は、pxじゃなくてremを使うべきなのかな？」という具合です。

そうすると、AIエージェントはざっくりと、あるいはかなり深く調べて、答えを返してくれます。それに対してさらに質問を続け、自分が本当に納得できるまで、この問答を続けます。そして最後に、それをスキルにさせるのを忘れないでください。この場合であれば、/px-vs-remのようなスキルです。

• /px-vs-remスキルの例

基本的に、これがここで紹介したいベストプラクティスのスキルです。おすすめしたいのは、この「つまずく → 解決する」という体験を、つまずくたびにスキルにしていくことです。そうしていくと、たくさんのナレッジスキルが手元に溜まっていきます。

「ベストプラクティス」スキルは経験からつくられる

前回の記事で紹介した「設計の指針」という分類は、このベストプラクティスを磨いて、整理し直したものと言えるのかもしれません。「pxかremか」「GridかFlexboxか」「CSS変数はいつ使うのか」……。こういったスキルが磨かれて育っていくと、それはほとんど1冊の本のようなものになります。自分がどうコードを書くかという、個人的なリファレンスです。この例でいえば「自分はこうCSSを書く」というリファレンスになります。

筆者はこの種のスキルをたくさんもっています。前述のとおり、筆者はいつもこの「Hey Claude Code」スタイルの問答をしていて、そのたびにスキルを作っているからです。ほぼ、何かにつまずくたびにです。そのときに時間がなければ、Claude Codeにその発見をissueとして起票させておいて、あとでスキルにします。

これは、ぜひ自分で作ってみてください。筆者のナレッジドキュメントをコピーして使うのも、もちろんかまいません。ですがそうすると、「何かがうまく働いているようだけど、なぜかはわからない」という感覚になるはずです。コピーしただけのスキルでは、そこで何が起きているのかを理解するのは難しいと思います。そのスキルがある場合とない場合とで、何が違うのかもわからないでしょう。

しかし、それが自分で作ったスキル、あるいは自分がすでに理解している内容のスキルであれば、AIは、あたかも自分が過去に失敗し、解決してきたことを、すでに経験しているかのように働いてくれます。

AIエージェントの働き方とベストプラクティススキル

ここで、AIエージェントがどう動いているのかを考えてみましょう。Claude CodeやCodex、あるいは似たようなAIエージェントの背後にはLLMがいて、推論を行っています。推論というのは（ざっくり言えば）可能性の高い答えを返すことです。そして推論の労力（reasoning effort）を高く設定すると、「本当にこれが答えなのか？」と何度も検討を重ねてから答えを返し、コードを編集します。

こうして返ってくる結果は、驚くほど望みどおりです。とはいえ、多くの選択肢の中から確率の高いものを選んでいるだけである、ということは知っておく必要があります。具体的な例で言えば、Webサイトのfont-sizeにpxを選んでくることがあります。ですが、それを責めることはできません。それはただの計算結果ですし、そこにはランダム性も存在しているからです。

しかし、彼らに与えるコンテキストによって、その方向を調整できます。たとえば次のような具合です。

OK、こういうケースでは、pxではなくremを使って。ユーザーはブラウザの設定でデフォルトのフォントサイズを変更できるので……

ですが、こうした説明を毎回プロンプトで伝えるのは、手間がかかりすぎます。だから、そのショートカットとしてスキルを使うのです。

つまり、重要なタイミングでスキルを渡すというのは、彼らに対してとても長いセミナーを行うのとほぼ同じことです。ただ、彼らは基本的に超高速な計算機なので、時間はかかりません。本当に数秒です。映画『マトリックス』でネオがカンフーを学んだときのような感じです（例えが古いかもしれませんが）。

以上が、筆者の3つ目のナレッジスキルの分類、「ベストプラクティス」のまとめです。

ナレッジを管理することでAIエージェントがより使いやすく

ここまでで、ベストプラクティスをつくることについて説明してきました。しかし、筆者は、このナレッジをテキストとしてつくるだけでなく、整理していくことこそが、AIの使い方における成長の中心にあると考えています。ただこれは、AIの使い方の成長というだけではありません。自分自身の成長でもあります。

ですから、筆者はこのナレッジの整理にかなり大きな労力を払っています。そしてその結果として、AIエージェントをとても快適に使えていると感じています。この資産があるゆえに、Claude CodeからCodexに乗り換えたとしても、ほぼ同じことをやってくれると期待できます。理由はシンプルで、「過去にこういうことがあったのでこうすべし」という情報をまとめて渡しているからです。

ごくごく単純化して言うとすれば、AIは次に来るであろうコードを予測し、プログラムを書く処理を実行しているだけです。実際にその結果どうなるかは、動かすまでわかりません。コードを書き、プログラムを動かし、その結果を確認してはじめて、ここは落とし穴であるという事態に遭遇するのです。そこで生まれるのがベストプラクティスなので、はじめからその道案内をしておけば、落とし穴は回避できるということです。

では、このスキル作成をひたすら続けるだけでよいのでしょうか？ 本項では、そのナレッジスキルの管理について、筆者が個人的にやっていることをいくつか紹介します。

リファレンス形式のスキル

まずはスキルをリファレンス形式にすることです。

リファレンス形式とはどういうことか。たとえば、この記事では「pxかremか」ということについての/px-vs-remスキルの例を挙げました。前回の記事では「タイトトークン戦略」という、Tailwind CSSのルールを使ったCSSのコーディング方法の/dev-tight-token-strategyスキルの例を挙げました。これらを/css-wisdomのような1つのスキルにまとめてしまうという方法です。

まとめると言っても、ただテキストファイルを2つつなげるだけではありません。インデックス＋リファレンスという形で扱います。次のような構成です。

css-wisdom/
├── SKILL.md
└── references/
    ├── px-vs-rem.md
    └── dev-tight-token-strategy.md

各CSSトピックの詳細はreferences/ディレクトリに、個別のMarkdownとして保存されます。そしてルートの/css-wisdomのSKILL.mdには、個別のトピックの概要だけを書いておくようにし、必要に応じてそれらを動的に読み込ませるようにスキルを作らせます。

こうしておけば、たとえば次のようにスキルを呼び出すと、

/css-wisdom pxとremのベストプラクティスを参照のこと

Claude Codeはpx-vs-rem.mdを読み込みます。これによって、かなり大きな辞書のようなスキルを実現できます。

Claude Codeは、スキルが大きくなってくると、このようなリファレンス形式に整理してくれることもありますが、明示的に依頼するほうが確実です。この連載で紹介してきた/skill-creatorには、このreferences/の構成についての説明が含まれているので、たいていの場合は勝手に整理しますが、具体的にこの内容を伝えるとしたら、たとえば次のように頼むとよいでしょう。

/skill-creator /css-wisdom が大きくなってきたので、トピックごとに references/ ディレクトリへ分割して整理して

たとえばこの手のスキルが100個ぐらいあったとしたら、Claude Codeは起動時にそれらのスキルの概要をすべて読みに行くので、スキル数に比例して、起動時のトークンコストが上がっていきます。

ですので、それぞれのスキルのすべての概要を詰め込んで読ませることは諦めます。しかし、そうするとClaude Codeは個別のトピックまでは自分で見つけにくいので、/css-wisdomをこちらで明示して呼ぶ形にするのです。CSSに関する何かが必要なときはこのスキルを添えてあげる、というように。

基本的には、まずはこのやり方でナレッジを育て始めることをおすすめします。ここではCSSを例に挙げましたが、Next.jsのスキル、Astroのスキル、GitHub Actionsのスキル……。何でもよいのですが、日々の開発で使っているトピックがちょうどよいです。重要なのは、そのスキルが自分の経験したことを保持している、という点です。きっと、AIエージェントが自分の望むように働いてくれると感じられるはずです。

スキルからドキュメントへ

もう1つは、このスキル自体をドキュメント化するという方法で、これはリファレンス化の延長線上にあります。

筆者も最初は前述のリファレンス形式でナレッジを管理していたのですが、筆者にとっては、スキルが増えるにつれて詳細を読むのがかなりつらいものになってきました。簡単に言えば、それらのスキルをもっと人間が読みやすい形で読みたかったのです。そこで、ドキュメント執筆まわりでほかにも動機があったこともあり、筆者は「zudo-doc」というドキュメントフレームワークを作りました。

• zudo-doc

そして、エージェントがそのドキュメントをスキルとして参照できる仕組みを実装しました。詳細をここに書くと長い説明が必要になるので、興味のある方は次のガイドを読んでみてください。

• ドキュメントスキルシムリンカー | zudo-doc

ここで実現したかったことは単純です。スキルのためのドキュメントビューアーが欲しかった、というだけです。スキルと言ってもただのMarkdownファイルなのだから、ビルドしたらサイトになるし読みやすいでしょう、という発想です。それがこの仕組みです。

このzudo-docを使って、筆者は次のようなナレッジドキュメントをメンテナンスしています。これらは基本的にはWebサイトですが、次に併記したスキル名で、Claude Codeにこのドキュメントを参照させることができます。

• zudo-css-wisdom: CSSナレッジ /css-wisdom
• zudo-test-wisdom: テストナレッジ /test-wisdom
• zudo-tauri-wisdom: Tauriナレッジ /tauri-wisdom
• zudo-cloudflare-wisdom: Cloudflareナレッジ /cloudflare-wisdom
• zudo-slack-wisdom: Slackナレッジ /slack-wisdom
• zudo-codemirror-wisdom: CodeMirrorナレッジ /codemirror-wisdom

それぞれ、かなり大きなドキュメントです。ですが、使い方は簡単です。新しいプロジェクトを始めるとき、筆者はだいたい次のように伝えます。

CSS設計については /css-wisdom のベストプラクティスを参照のこと

また、AIでアプリやWebサイトを作り続けていると、すぐにテストの問題に直面するはずです。そのときには、よく次のように伝えます。

テストについては /test-wisdom を参照のこと

すると、筆者が過去に直面したことのある問題に似たものは、ほとんど解決されます。

スキルはただのテキストファイルである、ということを忘れないでください。ここでは筆者のやり方を紹介していますが、特別なツールは何も必要ありません。シンプルです。何に困って、どう解決したかをメモしておく。筆者がおすすめしているのはそれだけです。

加えて、スキルが大きくなってきたら、時間を取ってスキルをリファクタリングしてください。トピックが重複していて、マージできるかもしれない……というような具合です。これをしないと、スキルは簡単に、ごちゃごちゃしたテキストファイルの山になってしまいます。

方向を矯正しているだけで、正しさの保証はない

ここまで読んで、筆者は正しいやり方をしている、正しいリファレンスを使い、AIエージェントに正しい情報を与えている、と思われたかもしれません。ですが、それは違います。ここでは何の正しさも約束されていません。

前回の記事で書いたように、ここにあるのは選択だけです。道Aに進むのか、道Bに進むのか。つまり筆者がやっているのは、「方向を矯正する」ということです。AIが選ぶ、確率的に正しいであろう選択肢について、素の状態で選ぶであろう選択肢を変える要素を与えているのです。

ここでのポイントは、自分が与えているのはあくまで筆者自身の経験からくる意見のようなものであり、それで望ましいゴールにたどり着けるという安心感は、そもそももたないほうがよいということです。端的に言えば、そんな風に知見を積んできたところで、それは間違っていることもあるぞということです。

セルフホステッド ランナーの失敗談

筆者にとって、結構がんばって時間をかけて作ってきたスキルとして、セルフホステッド ランナーのノウハウをまとめたスキルがあります。結果的にこの実装方法を選択したこと自体が自分には合っていなかったと気づいたため、スキル自体は消してしまいましたが、これは筆者が方向を矯正した結果、まったくうまくいかなかったトピックとなりました。

• セルフホステッド ランナー | GitHub
• そのスキル /dev-actions-self-runner

AIを使った開発をハードにやり始めてから、GitHub Actionsを大量に使うようになりましたが、GitHub Actionsにはそれなりのコストがかかります。それを減らすための方法として、セルフホステッド ランナーを使いました。

自宅のPCをCI環境に使うというセルフホステッド ランナーの機能は魅力的でしたが、AI開発が並列に進むと、PCは頻繁にハングし、環境はどんどん散らかっていきました。

何気なくCIにやらせている種々の作業ですが、そこで起こっているのは多数のパッケージのインストールと環境自体のカスタマイズです。複数のプロジェクトでこれをやっていれば、環境が滅茶苦茶になっていくというのは、あとから考えると当然だったのですが、当初筆者は気づけていませんでした。この問題に遭遇するまで、筆者にとってCIのプロセスとは、どこかで何かが起こっていてビルドなりテストなりをしてくれている程度のものであり、その先がどうなっているかなんて、大して気にしていなかったのです。

スキルに話を戻すと

さて、「スキル」の話に戻りましょう。そのようなセルフホステッド ランナースキルを育てたとしても、そもそもそのプロジェクトでセルフホステッド ランナーを使うという選択自体が望ましいものでなかったのであれば、開発は難航する方向に向かうでしょう（一応補足しておくと、セルフホステッド ランナーを有効に使えるケースもあるとは思います）。

この連載では繰り返し「ボスとして振る舞う」と書いていますが、このような技術選択についても、主導権を握るのは人間自身ということですね。スキルは部下への依頼の参考資料みたいなものでしょう。ボスがひたすら「セルフホステッド ランナーをがんばれ」と言い続けていたら、部下は指示どおりにそうするでしょう。その結果うまくいかなかった、という話です。

まとめ

では結局、ここで重要なのは何でしょうか？ 単純な話です。よいアプリやWebサイトやデザインを作るための正しい方向を、開発者自身が知っている必要がある、ということです。そしてそれをスキルにしておくのが筆者からのおすすめの使い方ということになります。この記事は、この連載における「スキル」の最後のピースです。

これまで紹介してきた、筆者が考えるスキルの分類のうち、まず、ユーティリティスキルは小さな部品です。ショートカットのようなものです。次に、ワークフロースキルは、かなり大きなワークフローを一度に扱います。複雑な流れを扱うことができます。そしてそれ以外のすべてが、今回まで紹介してきたナレッジスキルです。ただ、ナレッジというのは、単なるテキストファイルの集まりです。AIエージェントにどう働いてほしいのか、それを書いたものであり、これによりAIが進む方向が矯正されます。

この手のAIエージェントを使っていくうえで重要なのは、AIエージェントを、ガチャのようにランダムに何かを作ってくれるものとして使わないという意識かもしれません。エージェントはコントロールできます。ただしそのためには、エージェント自体について知る必要があり、そして当然ながら、自分たちが何をやっているのかを理解している必要があります。

つまるところ、その分野の知識があり、そこにAIを使うノウハウが加算されると、かけ算のように大きい結果を得られるようなものではないかと、筆者は感じています。

たとえば、この連載で「回路基板を作るのは結構AIを使っても難しい」と書いたのですが、AIのモデル自体が発展して、最近は結構丸っとやってくれるようになってきたように感じます。そして以前書いたように、筆者自身に回路設計についての深い知識はないのですが、はじめに部品情報をまとめて収集させ、それをAIに読ませて設計させるという手法自体には、AIを使った開発のやり方がそのまま応用できています。

具体的には、たとえば筆者の能力がショボい「5」であっても、AIのブーストが「10」であれば、5 × 10で「50」の力になるというイメージです。ただ、昨今ではこの10が100とか1000ぐらいの力にもなりえるので、なおさら「5」のほうをしっかりしなければと感じています。

総じて、実装のスピード自体はAIエージェントによって劇的に変わりました。ですが、根本的なことは、AIエージェントの前と後とで変わっていないのです。

次回は最終回として、この連載のまとめの記事を書きたいと思います。