🔥

SpecKitを使ってBitrise Stepを書いた

に公開

承前

https://zenn.dev/fumitoito/articles/3cb9da3320aca3

以前、GitHubのPersonal Access Tokenを駆逐するためにBitriseのGitHub Appsを利用する方法を記述した。

BitriseのGitHub AppsはPRへの書き込み権限を持つが、Issueへの書き込み権限がない。業務の都合上、「Issueに書き込む権限が欲しい!」という状況になってしまったので、泣く泣くBitriseからGitHub AppsのInstallation tokenを発行することにした。

BitriseからGitHub AppsのInstallation Tokenを発行する公式のステップはない

なんで?

ユースケースとしては多そうだが、現時点では公式の提供するBitrise Stepは見つけることができなかった。JWTで署名したトークンを生成してGitHub APIを叩くだけなのでサンプルコードはいくらでも見つかるのだが、正直書くのは面倒だ。

認証周りは怖いので、公式以外は使いたくない。自分で書くにはつまらない。メンテもできればしたくない。できればAIに全部書いて欲しいし、最悪メンテするとしても仕様書を詳しく残していつでも人に渡せる状況にしておきたい。

ありとあらゆる自分勝手な都合が積み重ねられた結果、SpecKitに白羽の矢がたった。お前、仕様駆動開発とか言ってるらしいな?

SpecKit

https://github.com/github/spec-kit

SpecKitに関する詳しい説明やインストール方法は他にいくらでもドキュメントが公開されているので、ここでは省略する。

出たばかりの時に少し触ったことがあるのだが、改めてアップデートしてみるとカスタムコマンドのインターフェースや生成物が微妙に変わっていた。触っていない期間が長い場合は更新してから試すがのいいだろう。

SpecKitは一言で言えば「生成AIでプロジェクトを進めるための矯正ギプス」である。後述するが、生成AIを使ってまともなソフトウェアを作りたいなら最低限これくらいはやれ、そんなメッセージをビンビンに感じられる。

作ったもの

https://github.com/fumito-ito/bitrise-step-github-apps-installation-token

permissionなどを指定してtokenを生成することができる。以下の例ではghコマンドに生成したトークンを渡している。

workflows:
  build:
    steps:
    - github-apps-installation-token:
        inputs:
        - app_id: $GITHUB_APP_ID
        - installation_id: $GITHUB_INSTALLATION_ID
        - private_pem: $GITHUB_APP_PRIVATE_PEM
        - permissions:
            contents: read
            checks: write
    - script:
        inputs:
        - content: |
            #!/bin/bash
            echo $GITHUB_APPS_INSTALLATION_TOKEN | gh auth login --with-token

SpecKitは生成AIでプロジェクトを進めるための矯正ギプスだ

SpecKitの基本的な流れは以下のようになる。

各コマンドを実行するたびに各種のドキュメントが生成され、コードが編集されるのは /speckit.implement 以降である。

最終成果物のチェックを除いて人間に求められる作業は概ね生成されたドキュメントのチェックと修正で、特に specs/{spec}/spec.md と specs/{spec}/plan.md は実装時に参照されるドキュメントであるため、念入りにチェックする必要がある。 /speckit.analyze で問題を指摘されるのも概ねこのあたりのドキュメントだ。

/speckit.clarify や /speckit.analyze で問題が見つかる確率はなかなか高く、一つの仕様に対して2〜3回は修正が発生した。

つまり、かなりドキュメント重視の開発が求められる。実際、筆者も業務上の全ての仕様について毎回このレベルのドキュメントを用意することはない。逆に言えばこれは「コーディングエージェントをまともに使いたいならこのくらい正確なドキュメントを用意しろ」というGitHubからのメッセージなのだ。

筆者としては、この矯正ギプスをはめることで「成果物の品質」が向上する実感はない。しかし、手戻りや「やっぱりここはこうして欲しい」とコーディングエージェントに依頼する回数は確実に減った。「やっぱりここはこうして」のような依頼を繰り返しているとコーディングエージェントのコンテキストが矛盾をハンドリングしきれなくなって壊れる確率が高くなると言う感覚が以前からあったので、この点では正しい矯正をされていると感じている。

SpecKitは /speckit.analyze があるから好ましい

我々はよく「やってみないと分からない」と言う。アホみたいに無責任な発言だが、これには一定の意味がある。

  • 「要求Aと要求Bを満たすには抽象化した要求Cとして扱えば良いが、そうするには前提条件Dが正しいかどうかが重要である」
  • 「要求Aは実は要求Cに依存しており、要求Bは要求Cと矛盾するので解決するには要求Dも実現する必要がある」

みたいなことは、実際にタスクに落として全体の関連性を明確にした後でないと気が付かないことがしばしばある。SpecKitはその不完全性を理解している。だから /speckit.analyze が存在するのだ。

前述のように /speckit.analyze では大なり小なりいくつかの問題が見つかる。筆者は CIRITICAL ISSUE とラベルされたものには最低限対処してプロジェクトを進めたところ、最終成果物に大きな問題は見つからなかった。実際に見つかった問題はコンソールなどに出力されるため、各Issueをよく読んで対応の有無を判断するのが良いだろう。

コンテキストの消費が大きいのでは、という懸念

感覚的にAIの稼働が多い、というかコンテキストの消費が激しいのは /speckit.specify, /speckit.clarify あたりで、筆者が作業しているときは clarify を通した直後にコンテキストが枯渇した(Claude Proプラン)。特に最初の /speckit.specify では関連ドキュメントのWebフェッチやローカル環境のリサーチなどが行われるため、コンテキストの消費が大きいと思われる。

実装時に参照するコンテキストは概ね specs/{spec} 以下のドキュメントに閉じている。すべてのドキュメントを合わせても~100KB程度だが、これを多いとみるべきか少ないとみるべきかは分からない。都度Webフェッチなどをしながら実装するよりはコンテキストが小さくなるとは思うが、これは実装しようとする仕様のサイズにも依存するだろう。

コンテキストの消費を適切なサイズにするには、実装させようとする仕様をコーディングエージェントがハンドリング可能なサイズに縮小する必要があるのだ。この点も矯正ギプスとして働いていると感じる。

また、今回作成したBitrise stepのようにあらかじめ雛形が決まっているようなタイプのプロジェクトでは、雛形を人間が用意してからSpecKitを導入した方がコンテキストが節約できるのではと感じた。たとえば、fumito-ito/bitrise-step-github-apps-installation-tokenではプロジェクトのConstitutionを定める際に「すでに雛形を作成してあるので、Bitrise stepの一般的なフレームワークに則って仕様を実現すること」と指定した。これによってBitrise stepのセットアップなどに関するコンテキスト消費はスキップされ、純粋にどのように仕様を実現するかにコーディングエージェントのリソースが割かれていたので、プロジェクトの種類によってConstitutionを適切に設定することが効率的な運用に効果的であると思われる。

生成されるドキュメントは引き継ぎ資料として使えるか

生成されるドキュメントはいわゆる「引き継ぎ資料」として使うのは難しいと思われる。

specs/{spec} に生成される一連のドキュメントは、あくまでも対象とする使用を実現するために必要なドキュメントだからだ。既存の概念としてはArchitecture Decision Recordsに近い。

引き継ぎ資料として一般に期待されるのは、おそらくプロジェクトのオーバービューやできること / できないことの一覧、開発に関わるメンバーやエコシステムにおける立ち位置がわかる資料である。長期的なメンテナンスや意思決定においてはもちろんADRも重要なドキュメントではあるのだが、プロジェクトを他人に渡すときの資料としてはいささか内容が細かすぎると感じた。

この辺は /speckit.constitution でプロジェクトのConstitutionを定める際に「./docs に ARCHITECTURE.md を作成してコード変更が完了した際に実態に合わせて編集する」みたいなことを書いておくといいのかもしれない。

まとめ

SpecKitを使って簡単なBitrise stepを作成した。仕様の策定に関しては一定のコストがかかるものの、自前のコーディングなしに現実的なソフトウェアを実装できた。生成されるドキュメントはADRとして一定の価値があるが、引き継ぎ資料としての価値は高くないので何らかの対応が必要そうである。

Discussion