適当ツールはなんちゃって仕様駆動開発で作って公開しよう

気軽に適当ツールを公開したい！

はじめに自作ツールのご紹介

今回 pouch という CLI ツールを公開しました。

pouch は Linux 系コマンドでおなじみの touch, mkdir を自動的に判別してファイルやディレクトリを構築してくれます。たとえば src/tool/main.go というファイルがほしいとき、次のように直感的な生成が可能です。

# Before: mkdir と touch を組み合わせる
mkdir -p src/tool
touch src/tool/main.go

# After: pouch なら一発！
pouch src/tool/main.go

拡張子を指定しない場合はディレクトリ扱いになります。複数のパスやファイルを同時に指定しての生成も可能です。要するに touch, mkdir -p をいい感じに統合、拡張しましたというツールですね。これが pouch の由来でもあります。

リポジトリで公開しているデモ動画もご覧ください。go install と mise use に対応しているので、興味があれば使ってみてくださいね。

この記事で紹介したいこと

なぜツールを公開したいのか

正直に言って pouch はシェルスクリプトでも簡単につくれます。たしかに .bashrc や .zshrc に似たようなものを書いている方も多いのではないのでしょうか？

それでもツールとして公開したい大きな理由は、保守性と可搬性にあります。dotfiles 内に自作コマンドを置いておくのでも十分かもしれません。とはいえ

• テストコードが書きにくくグレードしがち
• バージョン管理が複雑化する
• 誰かに配布するために特別な準備がいる
• 配布できたとしても動く保証がない

といった問題が残ります。別のリポジトリとして公開することで、これらがまるっと解決します (というより解決せざるを得ません)。

加えて 誰かが見ているものなのだからちゃんと書かなきゃ！ という気持ちが働き、自然と品質が上がります。これが一番大きなメリットかもしれません。

仕様駆動開発っぽく進めてみた

今回のツールは AI エージェントに大半を作ってもらいました。せっかくだから仕様駆動開発をやってみるかと思ったのですが、この規模の CLI ツールならそんな大仰なものは必要ありません。そこで少し軽量化した形にカスタマイズしたところ、必要十分な品質になったと感じています。この記事では、その過程を紹介したいと思います。

なお、今回のツール作成には次の記事が大変参考になりました。今回は Go 言語で実装しましたが、特定の言語に限らず汎用的に使える内容だと思います。

なんちゃって仕様駆動開発

仕様駆動開発のイメージ

この記事では、仕様駆動開発 (SDD) を「仕様」を中心に据えて開発を進める手法として捉えます。とくに AI エージェントと組み合わせる場合は、先に仕様書を作成し、それに沿って実装やテストを進めていく形になります。要するに、

• 具体性が高いコードではなく、より抽象的な成果物である仕様書を中心に置く
• コードを修正した場合でも仕様書に必ず同期し、常に信頼できる状態に保つ

という点がエッセンスだと私は考えています。コードを AI が大きく前に進めてくれるなら、人間はまず仕様に集中し、設計や検証の観点をそこに反映していくのが重要だ、というアイディアですね。

仕様駆動開発のフレームワークは spec-kit が有名ですが、これは少し重いです。今回つくりたいのは所詮小さな CLI ツールですから、巨大なアプリケーションすら対応できるフレームワークを流用するのはちょっと気が引けます。

もっと気軽に仕様駆動開発を捉える

仕様書とは、その語感から主に外部設計書を指していると感じます。主にエンドユーザーから見た仕様ですね。しかし、「外部設計書だけを先に固定して、内部設計は実装時に初めて考える」というのは明らかに不適切です。設計は

• What: 利用者や業務に対する契約である「何を実現するか」
• How: その契約を実現・維持できるかを検証する「どう実現するか」

を往復しながら考えるもの、つまり外部設計と内部設計は表裏一体です。素朴に考えると、仕様駆動開発で事前に洗練させるべきドキュメントは、外部設計書と内部設計書のペア ということになります。

ところで、リポジトリには一般に README.md があります。AI を利用するリポジトリには、AGENTS.md や CLAUDE.md など、コーディングエージェントに向けた指示ファイルがあります。これらはミニマムな外部設計書と内部設計書に非常に近い性質を持っていると考えていました。つまり

• 外部設計書として README.md を洗練させる
• 内部設計書として AGENTS.md を洗練させる

という方針でドキュメントを整理すれば、自然と仕様駆動開発っぽい進め方になるのではないかと思ったのです。

もちろん、

• README.md は詳細な外部設計書ではなく、あくまで簡潔なのガイドである
• AGENTS.md はプロジェクト固有の情報に限らず、開発者やチーム単位での決まりごとも含む

といった前提がありますが、情報の性質としてはかなりオーバーラップするのではないでしょうか。今回はこの方針で進めてみます。

エージェントにもちゃんと伝えておく

AI には前提知識をちゃんと伝えておきましょう。AGENTS.md に以下の内容を記載しておきます。

外部/内部設計書をつくりこむ

外部設計書 にはユーザーから見た動作仕様を記載します。正直に言って、この規模のツールであれば詳細な外部設計書は必要ありません。README.md に外部設計書的な内容を記載して、あとはインストール方法とライセンスでも記載しておけば十分です。

もちろん人間が読むものなので、人間にとって読みやすい文章である必要があります。しかし 書き手である人間にとって読みやすい文章に整理していく過程こそが、仕様書のブラッシュアップ作業そのもの だと感じます。おかしな仕様がないか、よりよい仕様がないかを考える中で自然とよい内容になるはずです。¹

内部設計書 にはユーザーが気にする必要がない情報、すなわちプロジェクト全体のアーキテクチャや思想を記載します。ここはかなり開発者としてのスキルが試されるところですが、これも小さなツールならそれほど作り込む必要はありません。

AI にコーディングを依頼するとき、たとえば Go 言語なら「Go 言語の CLI ツールとして自然な設計にして」といえば十分に動くものを作ってくれます。それを参考にして、実装しながらドキュメントをつくっても問題ありません。大切なのは実際のコードをドキュメントとして永続化することです。仕様駆動開発の中心はドキュメントですから、コードだけが先行しないように注意を払いましょう。

そして人間の役割として重要になるのは、生成物に違和感を覚えることです。

• なんかクラスの責務が過剰じゃない？
• これだとテスタビリティに影響しない？無理やりテストしてない？

といった違和感はすぐに AI に伝えましょう。その指摘が正しかった場合、過去に間違った方向に進んでしまった事実もドキュメントに書いておくとなお良いです。

英語と日本語のドキュメントを同期する

ところでREADME.md は一般に英語です…。悲しいかな英語がダメな私は README.md の日本語版 README-ja.md をつくって同期するようにしました。これなら日本語版を編集しても、AI に英語版への反映を依頼できます。

具体的には AGENTS-ja.md に次の内容を記載します。もちろん日本語版にも。

なお、これらの作業は繰り返し使うものだと感じたのでスキル化しました。
apm からインストールできるようにしてあるので、よければ使ってみてください。

apm install zawa-kyo/skills/dev/bootstrap-repo-docs

英語は自然なものにする

README.md は世界に公開するものなので、少しでも自然な英語にしておきたいものです。でも私には自然かどうかなんてわかりはしません。なので英語ドキュメントのレビューには stop-slop を使っています。

本当に自然になったのかはわからないのですけど、たぶんよくなっているはずです。たぶん。

まとめと終わりに

以上、なんちゃって仕様駆動開発で適当ツールを作って公開してみた過程の紹介でした。「公開してみた」の部分に目新しさはないので、CI の設定などはリポジトリを参照してください。以下は内容のまとめです。

• pouch という小さな CLI ツールを仕様駆動開発っぽくつくってみた
• 仕様駆動開発を小さく捉えると、次のドキュメントでも仕様書の責務を担える
  • 外部設計書としての README.md
  • 内部設計書としての AGENTS.md や CLAUDE.md
• 人間が違和感を覚えることが大切。それもドキュメントに反映する
• 英語がダメなひとは日本語版をつくって AI に同期してもらいましょう

AI の発展によって便利になった反面、コーディングが退屈になったとよく耳にします。気持ちはとてもわかります。その反発からなのか、この記事は人間100%で書こうと決めていました。

今回のツール作成は「たまにはコード書きたいなあ」という気持ちから始めました。AI に書いてもらってばかりいるので、結局はレビューばかりになります。でもやっぱり何かを作ることは楽しいです。コードとの関わり方が変わっても、変わらないものだってありますよね。

1. 「CLIツールとして不自然な仕様があれば教えてね」と AI に伝えるとたくさん教えてくれます。一般的な知識量では人間は AI に勝てないので、どんどん聞いちゃいましょう。人間はドメイン知識で活躍すればよいのです。 ↩