アイデアからリリースまで：私が毎日使っているスキル

エンジニアにAIをどう使っているかと聞くと、ツールの名前が返ってきます。アイデアからリリースまでの間に何をしているのかと聞くと、答えは急に曖昧になります。ここに書くのは私が毎日たどっている手順で、打ち込むコマンドと返ってくるものも添えています。

例として、ひとつの小さな機能を最後まで追います。管理者が注文一覧を表計算ソフト用にダウンロードできる、エクスポートボタンです。機能そのものは架空ですが、手順はすべて実際の仕事と同じです。

スキルとは

以前は、良いプロンプトこそ残す価値があると思っていました。バグの追い方をモデルに説明するとうまくいくのに、一週間後には記憶を頼りに劣化版を打ち直していました。

それを解決するのがスキルです。ひとつの種類の作業のための短い手引きで、何を、どの順番で、どこまでやれば終わりかが書いてあります。毎回同じ手引きなので、結果が私の気分に左右されにくくなります。

実際には、作業を始める前にモデルが読むマークダウンのファイルです。長いセッションの終わりに毎回使っているスキルの冒頭は、こうなっています。

---
name: handoff
description: Compact the current conversation into a handoff
  document for another agent to pick up.
---

Write a handoff document summarising the current conversation
so a fresh agent can continue the work.

私のスキルの多くは、Matt Pocockが公開しているスキル集から来ています。/grill-me のように、名前を打ち込んで呼び出します。手を入れたものもあれば、自分たちで書いたものもあります。

コードを書く前に

高くつく間違いは、誰かがコードを書く前に起きます。モデルは間違ったものを、速く作ります。

だから最初に打つのは /grill-with-docs と、一行のアイデアです。モデルは作り始めません。何回かに分けて私に質問し、どの質問にも自分ならこう答えるという案を添えてきます。

> /grill-with-docs 注文一覧にエクスポートボタンを付けたい

Q1  ファイル形式：CSV、Excel、それとも両方？
    おすすめ：CSV。どの表計算ソフトでも開けます。

Q2  使える人：全員、それとも管理者だけ？
    おすすめ：管理者だけ。注文には顧客の住所が
    含まれます。

Q3  大きな店舗では注文が8万件あります。ファイルを
    ブラウザで作りますか、裏側で作りますか？
    おすすめ：裏側で作り、できたらリンクをメールする。

私はたいてい「はい」の一言で答えます。価値があるのは、Q3のように自分では思いつかなかった質問です。管理者の権限がもうあるかどうかのように、コードを見れば分かることは、私に聞かずに自分で調べます。

質問が尽きると、モデルはそう言って待ちます。私が終わったと認めるまで、何も作られません。

多くのコーディングツールには、計画モードもあります。そこではモデルがコードを読み、私の望みを推測し、できあがった計画を承認のために差し出します。自信のある計画は、推測が間違っていても承認しやすいものです。質問攻めでは私が先に答え、計画はその答えから書かれます。

/grill-with-docs は質問に加えて、プロジェクトで使う言葉の短い一覧を CONTEXT.md というファイルに書いていきます。私がある所で顧客と言い、別の所でアカウントと言うと、どちらのことかを止まって聞いてきます。モデルが私たちと同じ言葉を使えば、書かずに済むレビューコメントがたくさんあります。まだコードがないアイデアなら、/grill-me がメモを取らずに同じ質問をします。

書き残す

次に、/to-spec が会話を仕様書にします。新しい質問はしません。問題、直し方、テストの方法、そして普通の文章で書いたユーザーストーリーの長い一覧を書き出します。

1. 管理者として、すべての注文をCSVで書き出したい。
   表計算ソフトで確認できるように。
2. 管理者として、大きなエクスポートが終わったら
   リンク付きのメールがほしい。画面で待たずに済む
   ように。
3. 管理者権限のないスタッフには、エクスポート
   ボタンが表示されない。

私はそれを読み、作り始める前に承認します。

そのあと /to-tickets が、仕様を、ひと区切りで終わる大きさのチケットに分けます。どのチケットも機能全体を細く貫く切れ端で、どこかの層だけを切り出したものではありません。それぞれに、先に終わっているべきチケットも書いてあります。

01  管理者が注文のCSVをダウンロードする   先行：なし
02  大きなエクスポートを裏側で動かす       先行：01
03  ダウンロードリンク付きのメール         先行：02
04  管理者以外にはボタンを隠す             先行：01

順番が記録に残るので、04は02と並行して進められます。

作る

アイデアに自信がないときは、まだきちんと作りません。/prototype が使い捨ての試作を作ります。画面なら、まったく違うレイアウトをいくつかひとつのページに並べ、リンクで切り替えられるようにします。私はそれを触って比べてひとつを選び、試作そのものは本番のコードに入れません。

アイデアが間違っていると知るための、いちばん安い方法です。

方向が決まったら、/implement がチケットをひとつずつ取り、/tdd でテストから作ります。モデルは失敗するテストをひとつ書き、それを通すだけのコードを書き、次のテストに進みます。

RED    管理者がorders.csvを受け取る。1注文1行
GREEN  注文一覧から行を順に書き出す
RED    管理者権限のないスタッフは断られる
GREEN  エクスポートに権限の確認を追加

テストが確かめるのはコードが何をするかで、どうやるかではないので、あとでコードを整理してもそのまま使えます。最初のテストの前に、テストをどこに置くかをモデルが私に確認するので、手間が大事なところにかかります。

私がいちばんモデルに任せているのがここです。難しい考えごとは、前の段階で済んでいるからです。コミットする前に、/code-review が、コーディングのルールに沿っているか、仕様どおりのことをしているかの二つの面から変更を確かめます。それでも、最後は自分で読みます。

壊れたとき

バグの原因を推測させると、モデルはコードを読み、もっともらしい仮説を選び、一度も起きるのを見ていない問題のために三つのファイルを書き換えます。

だから /diagnosing-bugs を打ちます。ルールは、まずバグをもう一度起こすことです。たとえば、エクスポートのメールがときどき二通届くと管理者から報告があったとします。モデルはコードに触る前に、ページを開いてボタンをすばやく二回押し、届いたメールを数える小さなスクリプトを書きます。

$ node scripts/repro-double-export.mjs
clicks: 2   export emails: 2   expected: 1
FAIL

これで、バグを狙って毎回起こせるようになりました。

再現できないバグは、推測しているだけのバグです。

ここまで来れば、修正はたいてい小さく済みます。今回は、最初のエクスポートが終わる前に二回目のクリックで新しいエクスポートが始まっていたので、実行中かどうかの確認をひとつ足すだけでした。同じスクリプトが PASS を出したら、ほかに変わったところがないかを私が確かめます。

仕事ごとに合ったモデル

すべての段階に、いちばん高いモデルが要るわけではありません。どのモデルも、クライアントのルールで認められている場合にだけ使います。

• 計画と確認。 私たちが主に使っているClaudeが計画を管理し、結果を確認します。お金やセキュリティに関わるものは、人が判断します。
• コードを書く。 低コストのモデルが、チケットをひとつずつコードにします。それができるのは、チケットがはっきり書かれているからです。
• セカンドオピニオン。 /codex review（gstackのスキル）で、今のところ私たちのセカンドオピニオンであるOpenAIのCodexに変更を見せます。別の会社のモデルは違うところに気づきやすく、見つかったことは計画とテストに照らしてから判断します。

エクスポートでは、私たち自身のレビューで見落としたことを、セカンドオピニオンが見つけました。エクスポートがページの日付の絞り込みを無視していたのです。先週の分を見ていた管理者に、これまでのすべての注文が届くところでした。日付について確かめるテストがひとつもなかったので、テストはすべて通っていました。

引き継ぐ

モデルとの一回のセッションが覚えていられる量には限りがあり、長い仕事は必ずそこにぶつかります。その前に、/handoff を打ちます。モデルが次のセッションへの短いメモを書きます。仕様やチケットは写さず、その場所へのリンクを載せます。

# 引き継ぎ：注文のエクスポート

決まったこと：CSVのみ、管理者のみ。大きなエクスポートは
裏側で動かし、リンクをメールする。仕様とチケット01から04を参照。

完了：01、04。作業中：02（裏側の処理）。
次：02を仕上げ、03（メール）へ。
注意：二回目のクリックで二つ目のエクスポートを始めないこと。

おすすめのスキル：/implement、/tdd

次のセッションはこれを読んで、すぐに作業を始めます。その裏にある二時間分の会話は要りません。

メモが短くて済むのは、どの決定も仕様かチケットに一度だけ書かれていて、ほかはそこへリンクしているからです。

機能と機能のあいだ

機能と機能のあいだに使うスキルが、ほかに三つあります。

• 片づける。 /improve-codebase-architecture が、よく変更される部分を調べ、変えにくくなっているところを見つけます。候補をレポートにまとめ、私が選んだものは最初に戻って、質問攻めから始まります。
• 調べる。 /research がバックグラウンドのエージェントに、公式のドキュメントから答えを探させ、出典つきで書き残させます。読んでいる間も、私は作業を続けられます。
• わからなくなったら。 /wait-what で、モデルに直前の説明を止めさせ、やさしい言葉で言い直させます。一行だけのスキルですが、読み返す手間がずいぶん減ります。

エクスポートのコードについて出てきたレポートから、カードをひとつ短くして載せます。

候補: エクスポートの処理が三か所にある
対象: エクスポート画面、裏側の処理、メール
問題: 三か所が注文一覧を別々に組み立てる。
  一か所で直した絞り込みが、ほかでは壊れたまま
解決: 三つすべてが呼ぶモジュールをひとつ作る
推奨度: 高い

セカンドオピニオンが見つけた日付の絞り込みのバグと同じものです。三か所のうち一か所で直しても、残りの二か所では壊れたままでした。

人が決めるところ

こうしたことで、モデルが結果に責任を負うようになるわけではありません。どの段階も、最後は人が決めて終わります。私が計画を承認し、テストの方法に同意し、届ける前にすべての変更を読みます。

ほとんどの段階はモデルが進めます。青い三つでは、人が決めます。

クライアントにとっては、作業の前に計画が固まり、すべての変更が届く前に確認されるということです。

試してみる

スキルは無料で、オープンソースです。Claude Codeなら、入れるのはコマンドひとつです。

claude plugins install mattpocock-skills

そのあとプロジェクトごとに一度、/setup-matt-pocock-skills を実行します。チケットをどこで管理するか（GitHub、Linear、またはリポジトリ内のファイル）と、ドキュメントをどこに置くかを聞かれます。ほかのコーディングエージェントには、npx skills@latest add mattpocock/skills で同じスキルを入れられます。

まずは次に作る小さな機能で、/grill-with-docs から始めてみてください。