Devin でタスクを並行実行していると、いろいろ見えてきた部分についてまとめておきます。

日付を扱う単体テストは、Devinとローカルでは結果が異なった

Jestで単体テストを行ったときに、husky で コミット前に 単体テストを回した構成のプロダクトで、日付を扱うようなテストは注意が必要です。

ローカルや手元の環境では JSTとして動いた単体テストは通るのにDevinが単体テストを実行しようとすると異なる結果になりテストが通らない問題に直面した。

この問題は、DevinがUTCで動くVM上で行ったためだった。
例えば月を跨ぐような単体テストでは、JST上では1月1日として識別されてもUTCでは12月31日となる。

そのため、月単位の単体テストでは日付が狂ったような振る舞いになるため、結果としてDevinがコードをコミットとpushできなかったという問題がおきた。

日付の単体処理では、タイムゾーンを確認しておきたいほうが良さそうです。
Devinに実行前に、VMのタイムゾーンを聞き、JSTにタイムゾーンを変更しておいてと指示しておきましょう。

Knowledgeに書いておいても良さそう。

playbookは最初のセッションでしか読み込まない

作成したplaybookで、チャット内にマクロを指定しても最初のセッションでしか起動できない。
後続のチャットのやり取りで マクロを指定しても、テキストとして処理されて中身のコンテンツを参照できないという問題があった。

セッション途中で、playbookの内容を再度確認させたり、仕様をまた食わせる必要がある。
メモリに限界があるため、過去の情報が消えていくのが基本と考えてよいかも。

PRにコメントが付いたものを勝手に修正する

最初のセッションの始まりのplaybookで、PRがコメントがついても勝手に修正しなかったがセッションが長くなるとplaybookを無視していくため、PRの文脈で勝手修正し始める。

ある意味暴走気味になるとかなり、やりとりに時間を取られてしまうため活用方法はうまく操作する必要がでてくる。

PRの概要を勝手に上書きをする

PRの編集でエビデンス用の画像だったりを貼ったりを自分自身が行った編集自体がDevinが修正してくる。
Playbookには書いたりセッションには書いてるはずなのに、時間が経過するにつれて変更するたびに上書きされる状態になった。

Knowledgeにすでに明記しながら、行うほうが適切のようだ。

• PRの編集は、最新の概要を確認したうえで変更すること

playbookなどにも書いておくよりも永続的に意識したいものは、Knowledgeとして定義することが大切なようだ。

また、PRのコメントについても内容を確認した上で一度上がってきた内容を質問もしくは質問で返してくださいみたいなKnowledgeも容易しておく必要がある。

やりとりが長くなると途中で要約として整理して投げる

セッション中の会話も残っているものの、基本のガードレールは忘れがちになります。
決まったことなどを定期的にやりとりを発生させて、Knowledgeに突っ込んでいくようなフローがよさそう。

セッション中に要約をなげて渡しておいて、再度セッションを開始するような形で記憶を呼び戻すようなイメージでやりとりをする

ずっとわすれてほしくないものは、Knowledgeに格納するように意識する。

エビデンス画像はDevinで貼れない

GitHubのPRの概要に、エビデンス画像を渡してもうまくアップロードしてくれない。
パスが違うためでGitHub上には展開できないようだ。

そのため、手動で概要編集している。（アップロードできたときもあったが理由不明）

文脈の理解しやすいように指示をする

指示する人間が間違ってた場合も考慮する必要がある。
指示を明確に与える。こちらのゴールが明確ではなければならない。（当たり前だけど）

Knowledgeの追加方法

Knowledgeの最初にいれても、Devinに参照されない。
Devinが見ているのVM上でのmarkdownのみです。

そのため、人間が識別するために設定のKnowledgeが定義されている。

1. Devinのセッション中に、やりとりを要約してKnowledgeを作ってと指示する
2. Devinが指示を行い、IMPLEMENTATION_RULES.mdなどのKnowledge用ファイルを作成させる
3. 作成されたmarkdownをコピーして、Knowledgeにコピー and ペースト
4. 修正されるたびにKnowledgeをDevinの設定画面で行う

このワークフローを考えると、常にリポジトリで完結するようにしたほうがいいと感じた。
kiroといった他の仕様駆動で作ったドキュメントなども リポジトリ内を参照しているため、設定でまとめる必要性がメリットがないと感じた。

結局のところルールや仕様は、 devin/knowledge/ に格納するように指示したほうがよさそう。

https://findy-tools.io/products/devin/399/602

生産性をどのように図ってるかの参考。

GitHub上のPR概要に画像添付がうまくいかない

Devin上のチャットで、画像を添付してPR画像に添付しておいてと指示しても、一個のときはうまくいくが、複数アップロードだとうまくいかないときがある。
GitHubの問題なのか。Devinが失敗したのかわかっていない。（書かれたパスがVMのパスだったため、Devinのように感じる）

Agents.md を配置すること

1. AGENTS.md とは

• Devin は AGENTS.md というファイルをサポート。
• AGENTS.md は AI エージェント用の簡易マニュアル（README のようなもの）。
• プロジェクトに必要なコンテキストや指示を記述して、Devin が作業前に読み取れる。
• AIエージェント（Devin）専用の指示ファイル
• プロジェクトに必要なコンテキストや作業ルールを明示
• Devin がコーディング開始前に自動参照する
• AIエージェント向けの README のような役割

2. AGENTS.md の設置

• プロジェクトルートや任意の場所に AGENTS.md を置く。
• Devin は作業開始前にこのファイルを自動で参照。
• 記載内容によって、コーディングスタイルや開発手順、テスト手順などを理解させられる。

README との違い

3. AGENTS.md の基本構成例

# AGENTS.md

## 1. 目的
このファイルは AI エージェント（Devin）専用の指示書です。
Devin が作業を始める前に参照し、正確に作業できるようにプロジェクトのコンテキストやルールを提供します。

## 2. セットアップコマンド
- 依存関係のインストール: `npm install`
- 開発サーバー起動: `npm run dev`
- テスト実行: `npm test`
- 本番ビルド: `npm run build`

## 3. コードスタイル
- TypeScript strict モードを使用
- React は関数コンポーネント優先
- ESLint と Prettier の設定に従う
- コミットメッセージは Conventional Commit 形式

## 4. テストガイドライン
- 新規関数にはユニットテストを作成
- テストフレームワークは Jest
- カバレッジ >80% を目標
- コミット前に必ずテストを実行

## 5. プロジェクト構造
- `/src` - メインアプリコード
- `/tests` - テストコード
- `/docs` - ドキュメント
- `/public` - 静的アセット
- README.md は人間向けで、Devin は自動参照しない

## 6. 開発ワークフロー
- `main` ブランチから機能ブランチを作成
- プルリクエストでコードレビュー
- マージ前にコミットを squash
- 新規機能にはドキュメントを更新

## 7. Devin向け注意事項
- README は人間向けで参照されない
- AGENTS.md は Devin 専用の指示書としてコーディング前に必ず参照
- `.rules`、`.mdc`、`.cursorrules`、`.windsurf` なども自動参照される
- 可能な限り詳細で明確な指示を記載することで、Devin の作業効率が向上

4. Devin における参照範囲

• Devin は以下を自動的に参照して作業に活用する
  • AGENTS.md
  • README.md
  • ファイル構造
  • .rules、.mdc、.cursorrules、.windsurf など
• 参照情報をもとにリポジトリ知識を生成し、コード理解や作業効率に活用

5. オンボーディングのポイント

1. AGENTS.md を整備する
   • Devin が作業に必要な環境やルールを理解できるようにする。
2. 開発環境のセットアップ情報を記載
   • 依存関係、ビルド、テストコマンドなど。
3. コードスタイル・テスト・ワークフローのルールを明確化
   • Devin がプロジェクトの標準に従って作業できる。
4. プロジェクト構造やドキュメント参照先も提示
   • 必要に応じてファイルやディレクトリのパスを具体的に書く。
5. 更新と改善
   • 新しいルールや変更があれば、AGENTS.md を随時更新。

まとめ

• Devin にとって AGENTS.md は「プロジェクトの操作マニュアル」。
• ここを充実させることで、Devin が迷わず効率的に作業可能。
• 小さなタスクだけでなく、ワークフロー全体の理解にも役立つ。

Playbook の整理

1. Playbook とは

• 繰り返し行うタスク向けの再利用可能なプロンプト集
• 特定のタスクを自動化したり、複数の Devin セッションで同じ手順を繰り返す場合に便利
• 共有・再利用が容易で、組織内で成功事例を簡単に複製可能
• 知識（Knowledge）とは異なり、タスク手順やプロンプトをそのまま Playbook に記述する

2. Playbook を使うべきケース

• 同じタスクを複数回 Devin で実行する場合
• Devin に同じ注意事項やリマインドを何度も伝えている場合
• 他のメンバーや組織で使える可能性がある場合

3. Playbook の構成要素

3-1. Overview

• タスクの全体概要と、Devin に達成してほしい成果を簡潔に記載

3-2. What’s Needed From User（ユーザーからの入力）

• Devin だけでは対応できない外部情報や入力を明示
• 例：トークン、CSV ファイル、Kaggle リンクなど

3-3. Procedure（手順）

• タスクの全体範囲を網羅した手順を順番に記載
• 各行に1ステップ、命令形で書く（Write, Navigate to, Create など）
• セットアップ・実タスク・成果物納品を含む
• 手順は 相互に重複せず、全体を網羅する（Mutually Exclusive & Collectively Exhaustive） ことを意識

3-4. Specifications（成果物条件）

• タスク完了後に満たされるべき条件を記述
• 例：ファイルの出力、テスト通過、データ保存

3-5. Advice and Pointers（助言）

• Devin にタスクを実行する際の注意や推奨方法を記述
• タスク全体に共通する場合はトップレベルに、特定ステップにのみ適用する場合は手順内にネストして記述

3-6. Forbidden Actions（禁止事項）

• Devin が絶対に行ってはいけない操作を明示

4. 作成方法

• Web アプリから「Create a new Playbook」をクリックして作成
• もしくは .devin.md ファイルとして保存し、セッション開始時にドラッグ＆ドロップで添付

5. Playbook 作成のコツ

• 小さなマルチステップタスクから始める
• 手順は具体的すぎず、Devin が柔軟に問題解決できる余地を残す
• 試行錯誤で改善し、成功パターンを蓄積する
• 成果物の条件を明確に伝え、タスクが「正しく完了した」と簡単に確認できるようにする
• 実行速度や効率も意識して最適化する

6. 例（R データサイエンスチュートリアル Playbook）

## Overview
R マークダウンノートブックでデータサイエンスチュートリアルを作成

## What’s Needed From User
- データセットのリンク（CSVファイルまたは Kaggle リンク）
- 作成したいチュートリアルの内容

## Procedure
1. データセットをダウンロード
   - 必要なら Kaggle CLI を使用
2. `data_science_tutorial.Rmd` を作成
3. `tmp.Rmd` を作成して中間コード保存
4. 5つのメインセクションを作成しコードを記述：
   - データ統計
   - EDA（棒グラフ・散布図作成）
   - Train-Test 分割（80:20）
   - モデル学習・保存
   - 推論・テストデータ評価
5. 各セクションに短い説明を追加
6. HTML に変換
7. ノートブック、HTML、モデル、テストデータをユーザーに送付

## Specifications
- R マークダウンノートブックと HTML ファイル送付
- 保存済みモデルとテストデータ送付

## Advice and Pointers
- パッケージ再インストール不要
- RStudio サインイン不要
- 各セクション追加後に全体ノートブックを実行

## Forbidden Actions
- `data_science_tutorial.Rmd` を上書きしない

💡 まとめ

• Playbook は Devin の再利用可能な「作業手順書」
• Procedure / Specifications / Advice / Forbidden Actions / User Input の順で整理
• 小さなタスクから始めて、試行錯誤で改善していく

1. Knowledge とは

• Devin がすべてのセッションで参照できる ヒント・助言・指示の集合

• 新入社員を教育するように、プロジェクトや組織の文脈を事前に共有する仕組み

• 追加・更新可能で、必要なときに自動で関連 Knowledge を呼び出す

• 用途例：

  • ドキュメントの参照方法
  • 内部ライブラリの使い方
  • よくあるバグと対処法
  • デプロイ手順、テストフロー
  • 社内専用ツールとの操作方法

2. Knowledge の作り方

ステップ 1：Knowledge 追加

1. Settings & Library ページ に移動
2. Knowledge タブ を開く
3. 右上の 「Add Knowledge」 をクリック

ステップ 2：Trigger（トリガー）の設定

• Trigger Description（呼び出し条件）を設定する

  • 短いフレーズや文章で、Knowledge を参照する条件を記載

  • 例：

    • 「デプロイ手順を参照」
    • 「React コンポーネント命名規則」

• Devin は Trigger に関連する作業をしているときに Knowledge を呼び出す

ステップ 3：Knowledge の内容

• 数文程度で、必要な情報だけを明確に記載
• 内容は 特定のワークフローやアクションに関連する情報 に絞る
• 長文になりすぎず、複数の Knowledge に分割可能

3. Knowledge の活用と管理

Devin の提案を活用

• Devin はチャット内のフィードバックから自動で Knowledge を提案
• 提案を編集して保存、または不要なら破棄
• 既存 Knowledge の更新提案も可能

定期的に追加・更新

• 頻繁に繰り返すタスクやよく使うプロンプトを Knowledge に登録
• Knowledge は組織全体で共有され、継続的に Devin の精度向上に寄与

Retrieval（取得）の注意

• Devin は関連性があると判断したときに Knowledge を呼び出す
• 一度にすべてを参照するわけではない
• Trigger は内容に対して 高い関連性を持たせる

4. Knowledge のピン留め（どのリポジトリに適用するか）

• ピン留めなし：必要なときだけ Devin が自動で参照
• 特定リポジトリのみ：そのリポジトリで作業するときに常に使用
• 全リポジトリ：すべてのリポジトリで自動適用

5. Devin が理解しやすい Knowledge の書き方

基本ルール

1. 簡潔・明確に書く
   • 数文で完結、具体的で冗長にならない
2. アクションに基づく表現
   • 命令形で記載すると Devin がタスクに反映しやすい
   • 例：
     • 「新しいコンポーネントを作るときは PascalCase を使用する」
     • 「PR は squash してマージする」
3. 1 Knowledge = 1テーマ
   • 複数テーマをまとめず、分割して登録
4. 必要な前提情報を明示
   • API トークンや外部リンクなど、Devin が自力で取得できないものを記載
5. 更新しやすく保つ
   • 内容変更時に古い Knowledge を上書きしやすくする

Devin 活用のベストプラクティス

1. Devinを使うタイミング

• Devinは「ジュニアエンジニアのように扱う」のが基本。
• 明確で詳細な指示を与えれば、ジュニアエンジニアやインターンが対応できるタスクをこなせる。
• 難易度が高すぎるタスクや高度な判断が必要なタスクは、細分化したり文脈を提供してから指示する。

2. Devin活用の基本方針

(1) 朝は複数のDevinを並行稼働

• TODOを整理して、小さなタスクに分割。
• インターンに任せられるレベルのタスクを複数並行で進める。
• 昼頃にはレビュー待ちのドラフトPRに戻って確認。

(2) Slackでの簡単修正に活用

• 30分以内で終わるタスクに最適。
• 長期間放置されがちな小タスクを消化するのに向いている。

(3) 確認しやすいタスクに集中

• CIが通るか、デプロイが成功するかなど、結果が明確に検証できるタスクが最適。
• 曖昧なタスクは避ける。表面的には完了して見えても別問題があることがある。

(4) 小さく始める

• まずは短いタスクで複数回試す。
• 1回のセッションで10ACU以上使わない。長時間セッションでは精度が下がる。

3. タスク評価のチェックポイント

タスク適正の判断

• 「ジュニアエンジニアが時間と文脈を与えられれば対応できるか？」を最初に考える。

タスク前チェックリスト

1. タスクの複雑さ

   • 判断や難しい決定が必要か？
   • インターンが失敗する可能性は？
   • 専門知識が必要なら分解して文脈提供。

2. タスク定義と範囲

   • 開始・終了が明確か？
   • 成功基準はあるか？（テスト通過、既存パターンとの一致など）

3. 参考資料の有無

   • 例やパターンを提供できるか？
   • プロトタイプや部分コード、既存ドキュメントを提示すると効果的。

4. 成功確認方法

   • テスト、lint、コンパイルなどで検証できるか？
   • 主観的な基準は避ける。

5. レビューの手間

   • CIが通るか、デプロイ確認程度で十分か？

6. タスクの大きさ

   • 大きい場合は小タスクに分割。
   • 分割することでDevinが迷わず進められる。

4. タスク後のレビュー

• セッション時間の確認
  長時間セッションで頻繁に制限に引っかかる場合は、タスクが複雑すぎる。
• 指示やガードレールの見直し
  Devinが時間をかけている箇所を分析。
• 環境の確認
  開発環境でつまずく場合はWorkspace設定を見直す。
• 場合によっては自分で完了した方が早い
  Devinの修正に時間をかけすぎない。

5. Devinの失敗から学ぶ

• 過去の障害を回避するために、次回は文脈や指示を追加。
• 学習済み知識を承認・追加し、Devinに前回の経験を活かさせる。

💡 ポイントまとめ

• Devin = ジュニアエンジニア扱い
• 小さく明確で検証しやすいタスクが得意
• 長時間・複雑タスクは分割・指示追加
• 失敗から学び、知識を蓄積させる

Devin が実装したPRでコメントがついたら、勝手に修正される

Devinが実装して立てたPRで、レビュワーからコメントがあったら勝手に内容をみて修正される。

こちらの指示を待ってから作業をしてほしいという意図をKnowledgeやplaybookに書いても行ってしまう。
GitHub Integrationのドキュメントを読んでいたら、勝手に実装を進めてしまう動きを無効にすることはできないようです。

https://docs.devin.ai/integrations/gh

Devin will automatically respond to any PR comments as long as the session has not been archived
セッションがアーカイブされていない限り、DevinはPRコメントに自動的に返信します。

レビュワーが明確に指示をする

このことを読み取ると、レビュワーのコメントが確認してください。だったり修正してくださいといった明確な指示をさせる必要があるようです。

よくよく考えると人間のレビューでも同様にコメントが意図がわからないことがあったり、修正してほしいのか確認したいのかわからないことがある。
これと同じことがDevinも意図がわからず、修正してほしいと汲み取るようだ。

レビュワーにレビューするときは、コメントの先頭に「確認してください」「修正実装する前に確認してください」と明確に伝えるような取り組みが必要かもです。

人間ではIMOだったりを書くことで相手への意図をつたえるような伝え方が工夫されるようにDevinにも同じようにする必要がありそうです。