Devinにドキュメントを生成してもらう実験

Devinにお願いしてソースコードからドキュメントを生成してもらえると面白そうなので実験してみた。Devin Wiki や Deep Wiki もあるんだけど、それとは別に自分で指示を出してコントロールできるのもいいかなという気持ち。

どうせ作るなら自分がドキュメントを読みたいやつがいいなぁと思って、ecspresso が好きだから、ecspressoのソースコードからドキュメントを生成してみることにした。

軽い気持ちでやってみたら、思ってたより苦戦した。すごくいい感じにできたわけじゃないので「この記事をめちゃ信じる！」んじゃなくて「へー、ちょっと参考にしとこっか」くらいが良いと思う。

勢いで書かないと書き終わらなさそうだったので、勢いでざーっと書いた。ので長い。

できあがったもの

できあがったものを最初に書いておく。わりと気に入ってる。ただ、生成するたびに色々変わるので、雰囲気で参照することにする。

注意：このドキュメントが正しいかどうかは確認できていないです！

https://bufferings.github.io/devin-docs/ecspresso/

注意：今後色々触っていくうちに上記のドキュメントは見えなくなるかもしれない

Devin?

Devin https://devin.ai/

お願いすると勝手に動いてPRを作ってくれるAIエージェント。個人では Core (Pay as you go) プランを契約している。使った分だけ払うやつ。

やりたいこと

ecspressoのソースコードを元にドキュメントを生成して、それをGitHub Pagesで見られるようにしたい。

最初はecspressoをフォークしてごにょごにょしてたけど、それよりもドキュメント生成用のリポジトリを作るほうがいいかも？と思ってそうした。そのリポジトリからecspressoをチェックアウトしてきてドキュメントを生成する。

https://github.com/bufferings/devin-docs

1. GitHub Actionsをポチると、Devinにドキュメント更新を依頼する
2. Devinが最新のソースコードを読んでドキュメントを生成してPRを出す
3. 僕がPRを手でマージする
4. mainブランチが更新されると、GitHub Pagesが最新のドキュメントに更新される

メインは手順2のプロンプトなので、それ以外を先にさらっと説明しておく。

3. 僕がPRを手でマージする

PRのマージも自動化できるとは思うけど、やりたいことのメイントピックじゃないから、今回はそこは手動でいい。

4. mainブランチが更新されると、GitHub Pagesが最新のドキュメントに更新される

この設定を先にしておく。GitHubリポジトリの

• Settings > Pages > Build and deployment

のところで GitHub Actions を選んで、Jekyll用のワークフローのファイルを作成した。

https://github.com/bufferings/devin-docs/blob/main/.github/workflows/jekyll-gh-pages.yml

デフォルトから変更したのは、反応しないでほしいファイルを設定しただけ。

    paths-ignore:
      - '.github/**'
      - '.instructions/**'

1. GitHub Actionsをポチると、Devinにドキュメント更新を依頼する

GitHub ActionsからDevinにどうやって依頼しようかな？DevinのAPIを叩くかな？と思ってたら、APIが利用できるのはTeamプラン以上だった。CoreプランだとAPIは利用できない。ふむ。

SlackからDevinに話かけるとDevinが動いてくれるので、これを使えばいいか。GitHub ActionsからSlackに依頼を投げてDevinに動いてもらおう。

Slack Appを登録してWebhookを作って、GitHub ActionsからはそのSlack AppのWebhookをcurlで叩くことにした。

トリガーは手動実行でいいので workflow_dispatch

name: Ask Devin to generate ecspresso docs

on:
  workflow_dispatch:

jobs:
  prompt-devin:
    runs-on: ubuntu-latest
    steps:
      - name: Send prompt via Incoming Webhook
        run: |
          SLACK_TEXT="<@DevinのSlackユーザーID> ここに依頼を書く。"

          payload="{\"text\":\"${SLACK_TEXT//\"/\\\"}\"}"

          curl -X POST -H 'Content-Type: application/json' \
               --data "$payload" \
               "${{ secrets.SLACK_DEVIN_CALLER_WEBHOOK_URL }}"

2. Devinが最新のソースコードを読んでドキュメントを生成してPRを出す

ということでメイン。試行錯誤の結果プロンプトはこうなった。

重要：指示に正確に従ってください。
devin-docsの.instructions/docs-ecspresso/step1.mdを見つけてください。
そのファイルに書かれた指示に従って作業を実施してください。
他のファイルは指示があるまで読み込まないでください。

もう、僕の苦労が見えてくるプロンプト。

先に断っておくと、これはDevinが悪いわけではない。僕のやりたいことが悪いのだ。現時点では、この依頼はDevinの正しい使い方ではないだろう。ドキュメントの生成はコードを全部読んで理解してから書く必要があるため、Devinにはつらそう。もっと小さなタスクを依頼する方がDevinの持つ力を発揮できると思う。

ということで、自分が試行錯誤したポイントを書いておく。

指示は別ファイルで管理することにした

最初はSlackのメッセージに指示内容を全部書いてみてたんだけど、それだとちょこちょこ依頼した内容の取りこぼしがあるように思えた。だから、指示を指示ファイルに書くことにした。

指示に正確に従ってください

どうも、指示が多いと勝手に違うことをやる場合がある様子。なので書いておいた。

step1.mdを見つけてください

step1.mdは存在するのに「step1.mdが見つかりません。どうしたらいいですか？」って聞いてきて止まるので「見つけてください」と書いておいたら見つからないと思っているときに、探してくれるようになった。

他のファイルは指示があるまで読み込まないでください

後で触れるけど、指示ファイルはstep1とstep2に分けている。そして、step1.mdが見つからないと思うと、step2.mdを見てそちらの指示を覚えてしまう。それだと、結局取りこぼしが発生するので、この指示を書いた。

そうすると「他のファイルは指示があるまで読み込みません！」って言って我慢してくれる。えらい。

指示ファイルの内容：step1

step1の指示ファイルは、こんな内容。

https://github.com/bufferings/devin-docs/blob/main/.instructions/docs-ecspresso/step1.md

# ステップ1

## 重要

- 実装方針の確認はせずにプルリクエストを作りきること

## 指示

以下の手順どおりに作業をしてください

1. devin-docsのecspressoフォルダを削除する
2. https://github.com/kayac/ecspresso のv2ブランチを一時フォルダにチェックアウトする
3. これまでに得ているecspressoの情報はすべて忘れること
4. ここまでの作業が終わってから、./step2.mdの指示を読んで作業を実施すること

指示ファイル1つに全部を書いてもまだ、どうも細かい部分を見落とすように思えたので、ステップ1とステップ2に分けた。見落としが減ったような気がする。

実装方針の確認はせずにプルリクエストを作りきること

実装方針を考えたら「この実装方針で進めてもいいでしょうか？」って聞いてくるときがあるので、書いておいた。

事前に知識を持っている様子

Devinの強みではあるのだけど、事前にリポジトリの情報を知識として持っている。今回だとdevin-docsというリポジトリに前回生成したドキュメントの情報を持っている。

今回の場合はドキュメントは依頼するたびにゼロから生成してほしかったので、この知識が邪魔になった。だから「これまでに得ているecspressoの情報はすべて忘れること」という指示を入れておいた。ただ、本当に忘れてくれたのかはよく分からない。気休め程度かもしれない。

指示ファイルの内容：step2

step2の内容はこう

https://github.com/bufferings/devin-docs/blob/main/.instructions/docs-ecspresso/step2.md

# ステップ2

## 重要

- 実装方針の確認はせずにプルリクエストを作りきること

## 指示

以下の内容に従ってecspressoのドキュメントを生成してください。

- 分析対象：
  - kayac/ecspressoのGoのソースコードをとても注意深く読み込んで深く理解すること。
  - README.mdなどのドキュメントは古い可能性があるのでソースコードで確認をして確証が得られた情報のみを使用すること。
- 言語：日本語
- 出力形式：Jekyllでビルドするためのマークダウン形式
- 内容：「どう使うか」に焦点を当てた技術ドキュメント
- 図表：Mermaidを使用したアーキテクチャ図・データフロー図によって理解が深まる場所には図をいれる
- 目次構造：
   1. はじめに
      1.1 ecspressoとは
      1.2 インストール方法
   2. クイックスタート
      2.1 基本的な使い方
      2.2 よくあるユースケース
   3. コマンドリファレンス
   4. 実践ガイド
      4.1 CI/CDパイプラインとの統合
      4.2 複数環境での運用
      4.3 大規模サービスの管理
   5. トラブルシューティング
- ファイル構成：
   - 各セクション・サブセクションは別々のファイル
   - コマンドリファレンスのセクションではコマンド1つに対して必ず1つのサブセクションを作成すること

完了後作業

- 生成したドキュメントをdevin-docsのecspressoフォルダに入れてプルリクエストを作成

Goのソースコードをとても注意深く読み込んで深く理解すること

「Goのコードを読む」程度で書いてたら、どうもREADMEの方を優先するようなので、Devinに聞いたら「もっと強調して！」って言うのでそうしてみた。「とても」とか「深く理解する」とかを普通に書いて「注意深く読み込んで理解すること」にしてたら、適当に読んでる部分があったのでさらに強調しておいた。

ただ、これも効いてるのかどうか分からない。たまたまかもしれない。

Jekyllでビルドするためのマークダウン形式

これだけでJekyll用のメタデータなどもつけてくれるので賢い。デザインテンプレートは僕が _config.yml で just-the-docs を指定している。

実は、最初はJekyllを使わずに、DevinにHTMLでドキュメントを生成してもらっていて、デザインも任せていたけど、さすがにそれは酷か、と思ったのでJekyllを使うようにした。

「どう使うか」に焦点を当てた技術ドキュメント

普通に「コードを読んでドキュメントを書いて」だと、内部構造の詳細ドキュメントを書いてくれたんだけど（それはそう）、僕が読みたいのはecspresso開発者のためのドキュメントじゃなくて、利用者のためのドキュメントだから、そういう指示を入れた。

Mermaidを使ってもらう

「Mermaidを使用したアーキテクチャ図・データフロー図によって理解が深まる場所には図をいれる」って書いておいたらちょうどいいくらいに 書いてくれた。

「Mermaidで図を描いてね」くらいだと全然なくていいところにもたくさん差し込んできてくれて、あ、そこまではいいんです、っていう気持ちで「図によって理解が深まる場所には図をいれる」という指示にした。

Mermaidで描いてくれるの、良い。

目次構造

目次がないと、指示がゆるふわすぎてDevinを困惑させてしまうのでつけておいた。この目次自体はDevinと話をしながら「どういうのがいいかねぇ？」「こんなのがいいと思います」って決めていった。

「ファイルAは読み込まないでください」は苦手っぽい

README.mdを読み込まずにGoのコードからドキュメントを生成してほしいなと思って「README.mdは読まないでね」って言っても必ず読み込んでた。だから、指示の中に「ecspressoをクローンしたらすぐにREADME.mdを削除すること」ってのを入れて、物理的に読めないようにしたらなんとかなった。

ecspressoをフォークしてたときは、それをやってもすでに知識としてDevinがREADME.mdの内容を知っているので、止められなかった。

負けた・・・

> 申し訳ありません。指示通りにREADME mdを削除してから作業を始めるべきでした。実際には、作業開始前にREADME mdの内容を確認してしまいました。これは指示に反する行動でした。正しい手順に従うべきでした。

— SHIIBA Mitsuyuki (@bufferings) May 17, 2025

最終的にはREADME.mdを読み込まずに生成してくれて僕が満足したので、README.mdは読んでもいいことにした。

指示ファイルの内容自体もDevinに相談して決めた

Devinと会話をしながらドキュメント生成の試行錯誤をして、だいたいこんな感じで良さそうってなったら、Devinに「この結果をDevinに迷いなく生成してもらうためのプロンプトを教えて」って書き出してもらった。それでもDevinは迷走してたけどね。

Knowledge

ここまでで、Slackの依頼、指示ファイルstep1, step2の内容まで終わり。だけど、これだけではまだちゃんと生成できない。Devinのサポートに質問したらKnowledge使うといいよ！って教えてもらった。

https://docs.devin.ai/get-started/devin-intro

登録しているKnowledgeも書いておく。効いているような気はするが、どれがいい感じに効いているのかはいまいち自信がない。英語と日本語があるのは、もう疲れてるから。

always checks the instruction file in the repository before starting a new task when it is requested

古い指示ファイルの情報を見て動くときがあったので、タスクに着手する前に指示ファイルを見てよ！っていう指示を入れておいた。

When analyzing source code to create documentation, ensure thorough examination of all features, including less obvious ones like VPC Lattice support in ecspresso. Don't rely solely on the most visible parts of the codebase or existing documentation. Search for all supported integrations, plugins, and service connections to provide comprehensive documentation.

これはDevinが自分で追加したやつ。「ecspressoにはVPC Lattice対応が入ってるのにドキュメントにないよ！」って言ったときに「もっと詳しく見ます！」って言って登録してた。

When including JSON code blocks with comments in documentation, use jsonc instead ofjson to ensure that comment lines are correctly displayed and formatted in the rendered documentation.

これも、JSONにコメント入れてるときは json じゃなくて jsonc にしよっかって話したときにDevinが登録してた。

Jekyllは{{ }}をLiquidテンプレート構文として処理するため、ドキュメント内にテンプレート構文（特にバッククォート()を含む変数参照）がある場合、GitHub Pagesのビルドでエラーが発生します。解決策として: 1.{% raw %}...{% endraw %}タグでテンプレート構文をエスケープする 2. バッククォートを`のHTMLエンティティに置き換える（例:{{ must_env IMAGE_TAG }}→{{ must_env `IMAGE_TAG` }}`）

特に、ecspressoのようなテンプレート機能を持つツールのドキュメントを作成する際は、コード例内のテンプレート構文に注意が必要です。

Jekyllの構文エラーになったときにDevinが登録してた。Devinが日本語気分だったらしい。

Do not use auto-generated initial plans. Instead, follow only the explicit instructions provided in the specified files. Only open files that are explicitly mentioned in the instructions.

さっきもちょっと触れたけど、Devinはリポジトリの内容を知識として持っているので、いろいろ空気を読んで、指示していない情報もかき集めてうごきだすっぽい。今回はそういうことはしたくなかったので、書いた。でも・・・んー、まぁ効いてるかどうか分かんないな。たまに使ってる。

という感じ。

気づき

2ACUくらい使う

今回のケースだと、1回の依頼で30分ぐらい・2ACUくらい使う。

実際にこういうことをやろうと思ったら、初回生成だけ今回のプロンプトを使って、それ以降は「ソースコードが更新された部分のドキュメントを更新しておいて！」にするといいのかなと思った。

でも、既存のドキュメントとの整合性をとるほうにパワーを使ってしまうかもしれないから、やってみないと分かんないか。

試行錯誤にはACUをわりと使う

コードを読み込んで理解したうえでドキュメントをゼロから書いてってお願いしてるので、試行錯誤してるとACUをわりと消費する。今回の試行錯誤で120ACUくらい使ってしまった。そしたら30ACUくらいGift ACUが追加されてた。Cognitionがくれたのかな？ありがとう。

「〜をしないで、〜する」という表現は苦手みたい

「既存ドキュメントを参考にせずに、ソースコードからドキュメントを作って」と依頼しても「既存ドキュメントを参考にして考えます！」ってなった。

「〜をしないで、〜する」という表現は苦手なのかも。「〜する」の方を強調して書いて「〜をしない」は文章を分けてこちらも強めに書いたら、なんとか理解してくれた気がする。

長い文章は苦手っぽい

文章だけで依頼を書くと、長い文章になると理解が大変な様子。いくつか無視された。Devinに聞いたら、長い文章より箇条書きの方が分かりやすいっていうので、箇条書きにしたらわりと理解してくれた。

試行錯誤中に寝落ちする

セッションあたりのACUリミットがデフォルトで5ACUなので、試行錯誤中にはそこに引っかかってDevinが寝落ちしちゃったことが何回かあった。僕も寝落ちしてたからお互い様だね。

依頼が終わったらセッションをスリープしてほしい

けど、プロンプトに書いても無理そう。しかたがないか。ちなみにDevinに聞くと「『最後にスリープしてください』って書くとスリープしますよ！」って言うので書いてみたら、Devinが「それではスリープします」って言って「おぉ！」ってなったけど、あいつ寝たふりしてるだけだった（スリープしてなかった）。

DevinにDevinのことを聞くときほど信用できないことはない

— SHIIBA Mitsuyuki (@bufferings) May 17, 2025

ChatGPTもDevinには詳しくないので、Devinのことを聞くならふつうにサポートに問い合わせるのがいちばんいいね。

おしまい

ということで、疲れたー！でも、おもしろかった。

おまけ

「自分のリポジトリ内でPRを出したつもりがfork元にだしてしまいました」の札を下げています。ごめんなさいごめんなさい。

Create static.yml by bufferings · Pull Request #840 · kayac/ecspresso · GitHub