はじめに
前回の記事では、AIに仕様書（スペックMD）を先に書かせることで、コードの手戻りを減らす話をしました。
今回はその続きです。仕様書を挟む流れが定着してきたころ、別の問題が出てきました。
「毎回同じ説明をClaudeにしている」問題です。
シリーズ4本目です。
悩んでいたこと
このサイトでは、UIコンポーネントの事例ページを1件ずつ追加していく作業が繰り返し発生します。
1件追加するには、だいたい次のような流れが必要です。
- 仕様書（スペックMD）を読み込む
- デザインルールや実装ルールを確認する
- HTML / CSS / JS を作る
- サイト全体のデータファイルにエントリを追加する
- ブラウザで動作を確認する
- サンプルコードの整合性チェックを実行する
- サイトマップを更新する
- リリース前のチェックリストを確認する
8ステップある。多い。
しかも作業量によっては「HTMLまで作ったところで今日は終わり、続きは明日」ということも起きる。次の日に再開するとき「あと何が残ってたっけ」ってなる。
Claudeに毎回「今日は仕様書ができているので、HTMLを作って、そのあとデータファイルも更新してください」と説明するのも地味に面倒でした。もっと言えば、説明し忘れてステップが飛ぶこともある。
具体的に困ったこと①：修正に気づいても忘れて公開してしまう
チャットでやり取りしながら作業していると、途中で「あ、ここ直した方がいいな」と気づく瞬間がある。でもそのままチャットの流れで作業を続けて、修正を忘れたまま公開してしまうことがあった。後日ページを見て「あ、直してなかった」と気づいて再修正。公開後の修正は地味にストレスでした。
具体的に困ったこと②：やることが揃ったり揃わなかったりする
「HTMLを作って」と依頼したとき、あるときはデータファイルもサイトマップも一緒に作ってくれる。あるときはHTMLだけで終わる。Claudeの気分次第（？）で結果がバラバラでした。
データファイルの更新が抜けていると、トップページのカード一覧に表示されないため、ブラウザで動作確認するときに「あれ、カードが出ない」となってその都度対処が必要でした。
コアの問題：作業フローが頭の中にしかない
仕様はファイルに書いてある。デザインルールもファイルに書いてある。でも「何をどの順番で実行するか」は毎回自分が覚えていないといけなかった。
Claudeへの指示の粒度によって、やってくれることとやってくれないことが変わる。その不安定さが積み重なって、毎回の作業に微妙なストレスがありました。
「カスタムコマンド」という機能を使うことにした
Claude Codeには「カスタムコマンド」という機能があります。
ひとことで言うと、「よく使う指示をファイルに保存しておいて、短い一言で呼び出せる仕組み」です。
仕組みはシンプルで、プロジェクト内の .claude/commands/ というフォルダにMarkdownファイルを置くだけ。たとえば create-example.md というファイルを置けば、チャットで「/create-example を実行して」と伝えるだけで、そのファイルに書いた手順をClaudeが読んで実行してくれます。
「スラッシュ（/）コマンド」とも呼ばれますが、言葉を聞いてもよくわからなかったので補足します。Slack や Discord に「/announce」みたいな命令がありますよね。あのイメージです。自分でオリジナルの命令を追加できて、使うときは「/命令名」と伝えるだけ。
大事なのは、コードを一行も書かなくてよいところです。ファイルの中身は普通の日本語の文章です。「まずこれをやって、次にこれをやって」という手順を書くだけで動きます。
もう一つ大事なことがあります。このコマンドファイル自体、自分で一から書かなくてよいということです。
「こういう作業を繰り返しているんだけど、コマンドにできる？」とClaudeに聞いて、一緒に作ってもらいました。自分の作業フローを説明すると、「それはこう整理できますね」「この順番の方がよくないですか」「このステップは失敗したときどうしますか」と、考えていなかった観点まで出してくれます。
「AIで作業を自動化するツールを、AIと一緒に作る」という構図が面白いなと思いました。仕様書（スペックMD）を先に詰めてからコードを作る流れと全く同じです。ファイルの中身が固まってから「では書いて」とお願いするだけ。
実際に作った2つのコマンド
作業の途中で中断することがあるので（HTMLを作ったら一度確認してから続ける）、2つに分けることにしました。
作成コマンド（/create-example）
このコマンドを呼ぶと、仕様書を読み込み → 実装ルールを確認 → HTML / CSS / JS を生成 → データファイルを更新、という流れで進みます。完了後は「ブラウザで確認して、問題なければ /release-example を実行して」と自動で案内してくれます。
リリースコマンド（/release-example）
このコマンドを呼ぶと、サンプルコードの整合性チェックを実行 → 「ブラウザで確認してOKと入力してください」と表示して一時停止 → 「OK」を受け取ったらサイトマップを更新 → リリース前チェックリストを全項目確認して ✅ / ❌ で結果を表示、という流れになります。
コマンドファイルの中身はこんなもの
実際のファイルを見せます。作成コマンドのファイルの冒頭部分です。
以下の手順で作業を進めてください。対象IDは「$ARGUMENTS」です。 作業開始時にチェックリストを全項目表示し、 各ステップ完了のたびにリストを更新してください。 ## チェックリスト - [ ] 1. 仕様書（スペックMD）読み込み - [ ] 2. 参照ドキュメント確認 - [ ] 3. データファイルの順番確認 - [ ] 4. HTML 作成 - [ ] 5. CSS 作成 - [ ] 6. JS 作成 - [ ] 7. データファイル更新
$ARGUMENTS というのは、コマンドを呼ぶときに渡した引数に置き換わります。たとえば「/create-example を実行して。対象IDは form-textbox-5」と伝えると、$ARGUMENTS が form-textbox-5 に変わります。
チェックリストは作業が進むたびに ✅ に更新されていきます。「今どこにいるか」が視覚的に一目でわかる。
ファイルの残りは各ステップの詳細な手順が書いてあります。「このファイルを読み込め」「この形式でエントリを追加しろ」という指示を、普通の日本語で書いたものです。
自分の繰り返し作業に置き換えるなら、たとえばこういうイメージです。
毎週のレポート作成なら
必要なステップを書き出すだけでいい。「データを確認して」「グラフを作って」「本文を書いて」という手順がそのままコマンドになる。
お客様への返信フローなら
確認すべき項目をリスト化するだけ。「件名を確認して」「過去のやり取りを見て」「返信案を3パターン出して」という手順を書けばいい。
コードのレビュー作業なら
確認観点をチェックリストにするだけ。毎回「セキュリティ、パフォーマンス、可読性を見て」と打つ代わりに、コマンドを呼ぶだけになる。
「毎回同じことをClaudeに説明している作業」があれば、それがコマンド化の候補です。
なぜ全自動にしなかったか
リリースコマンドが途中で止まる設計にしたのは、意図的なものです。
サンプルコードのブラウザ確認だけは、人間の目が必要だと思っていました。「動くか動かないか」は機械で確認できる。でも「意図した動きになっているか」「見た目がおかしくないか」は、自分の目で見ないとわからない。
全部自動で流してしまうと、このチェックが省略されやすくなる。あえて止まる設計にすることで、確認のタイミングが自然に生まれます。
全自動にできるのにあえてしない。どこを人間が判断するかを最初から決めておくと、作業の安心感が違います。
バイブコーディングに慣れてきたころに気づいた感覚ですが、AIに任せすぎると後からのリカバリーが大変になる場面がある。自動化の範囲は意識的に決めた方がいいと思っています。
コマンド自体もチャットで設計した
面白いのは、このコマンドを作る過程もチャットで行ったところです。
自分がやっていた作業フローを説明して（「まず仕様書を確認して、次にHTMLを作って、最後にデータファイルを更新して...」）、「どこをコマンドにするか」「2つに分けるのはどうか」という話を一緒に詰めました。それをもとにコマンドファイルを作ってもらいました。
仕様書（スペックMD）を書く前にチャットで詰める作業と同じ構図です。「何をどう作るか」を先に言語化してから、ファイルに落とす。
バイブコーディングでありがちな「気づいたら思ってたものと違うものができてた」問題を、コマンド作成でも同じ方法で避けました。
実際に使ってみて
事例ページを1件追加する作業で実際にこのコマンドを使ってみました。
全体の感触は「思った以上によかった」というのが正直な感想です。毎回チャットで数回やり取りして進めていた作業が、コマンドを呼ぶだけで流れが分かりやすくなりました。
チェックリストの効果が特に大きかったです。各ステップが終わるたびにリストが更新されるので、「今どこにいるか」が視覚的にわかる。これまでは「次何するんだっけ」と自分で確認していた部分がなくなりました。
リリースコマンドの「ブラウザで確認してOKと入力」という一時停止も、実際に機能しました。確認 → フィードバック → 続行という流れが自然でストレスがなかったです。
コマンド外の修正依頼も普通にチャットでできるので、「コマンドに縛られて融通が効かない」感覚は一切ありませんでした。途中でデモの内容に不足があると気づいたときも、そのままチャットで「ここを直してほしい」と伝えて対応してもらいました。
一点だけ補足すると、「/create-example と入力すれば動く」というよりは「/create-example を実行してと伝えるとClaudeが代わりに動かしてくれる」というイメージが正確です。最初に少し戸惑ったので先に書いておきます。
まとめ
繰り返し作業のフローをカスタムコマンドに焼き付けた話でした。
やったことはシンプルです。「毎回Claudeに説明していた手順」を、Markdownファイルに書き出した。それだけです。コードは一行も書いていません。
この仕組みが嬉しいのは、ファイルが「作業マニュアル」として残ることです。自分の頭の中にしかなかったフローが、ファイルになって見える。明日また再開するときも、チームの誰かに引き継ぐときも、このファイルを渡せばいい。
バイブコーディングで開発を続けていると、「点」の作業をずっとやっていることに気づきます。「このページを作って」「この機能を追加して」と1つずつ頼む。でも実際の開発は「流れ」があって、決まった手順が繰り返されています。
その流れをコマンドという形で定義すると、3つのことが変わります。
Claudeの動きが安定する
毎回の指示の粒度に関係なく、同じ手順で動いてくれます。「今日は説明が雑だったから抜けが出た」ということがなくなります。
自分が「流れを管理する人」になれる
細かい手順を覚える必要がなくなり、「次は何を作るか」「ここの仕様はどうするか」という判断に集中できます。
積み上がっていく
コマンドファイルはプロジェクトに残り続けます。フローを改善したくなったらファイルを更新する。作業のやり方がどんどん洗練されていきます。
「同じことをClaudeに毎回説明しているな」と感じる作業があれば、それがコマンド化のサインです。
最後まで読んでいただきありがとうございました。