Devin と開発を進めるための実践ハンドブック ― チーム開発に取り入れるステップとベストプラクティス
AIエージェント Devin を導入することは、新しいエンジニアをチームに迎えるのと同じです。
適切なルールを整え、ナレッジを共有することで、日常の開発を大幅に効率化できます。
本記事では、実際に触って得たナレッジをベースに、Devin公式ドキュメントにある Essential Guidelines や Good vs. Bad Instructions を組み合わせて、チーム開発にDevinを取り入れる際の基本ルールとベストプラクティス を整理しました。
Devin 導入の考え方
AIエージェント Devin をチームに導入する際は、まるで新しいエンジニアを迎えるような視点で考えることが重要です。
単なる自動化ツールとしてではなく、チームメンバーの一員として 役割や責任を明確にし、適切に指示やナレッジを提供する ことで、その能力を最大限に引き出せます。
期待できる効果
- 日常のルーチン作業や単純タスクの効率化
- コードレビューやテスト、ドキュメント生成などのサポート
- チーム内ナレッジの標準化・共有
注意点
- 指示が不十分だと意図通りに動作しない
- 複雑すぎるタスクはセッションが長引き、パフォーマンスが低下する
- チームでのルールやワークフローに沿わない出力は後で修正が必要
「人間の新メンバーを教育する」感覚で、最初に基本ルールやナレッジを整備することが必要です。
ドキュメントの使い分け
チーム開発でDevinを効果的に活用するには、人間向けとAI向けのドキュメントを分けて整理することが重要です。
リポジトリには、README.mdが定義されることが一般的です。
Devinでは、README自体を自動で参照することはなく代わりにAGENTS.mdを参照してプロジェクトのセットアップアップなど必要な情報自動参照してくれます。
README.md
プロジェクトのリポジトリにはREADME.mdを設置して、オンボーディングとして開発ルールや開発環境構築などが書かれます。
READMEはあくまで 人間向け のプロジェクト説明書です。
プロジェクトの概要、セットアップ方法、利用手順などを分かりやすくまとめ、チームメンバーや新しく参加したエンジニアがすぐ理解できる内容にします。
AGENTS.md
一方、AGENTS.mdは Devin専用の指示書 です。
コード規約、セットアップコマンド、テスト方針、プロジェクト構造、開発ワークフローなど、AIがコーディングを始める前に必要な情報を具体的に記載します。
Devinはプロジェクトルートに置かれたAGENTS.mdを自動的に参照し、コーディング作業に反映します。
| 項目 | AGENTS.md | README |
|---|---|---|
| 対象 | AIエージェント（Devin） | 人間の開発者 |
| 内容 | セットアップ手順、コードスタイル、テストガイドライン、プロジェクト構造、開発ワークフロー | プロジェクト概要、インストール方法、使用方法など |
| 参照 | Devin が自動参照 | 人間が読むための説明書 |
| 目的 | Devin が正確に作業できるようにする | 開発者がプロジェクトを理解・利用できるようにする |
README.mdは人間、AGENTS.mdはDevin という役割分担を明確にすることで、チーム全体の理解と作業効率が飛躍的に向上します。
セッション内でREADME.mdを参照させることも可能ですが、READMEには人間向けの情報が多く散在しているため、Devinには明示的にAGENTS.mdを参照させる方が正確かつ効率的です。
他のツールで使用してる AGENTS.mdファイルを用意されていることから、参考にしてみると良さそうです。
AGENTS.md の設置
- プロジェクトルートや任意の場所に AGENTS.md を置く。
- Devin は作業開始前にこのファイルを自動で参照。
- 記載内容によって、コーディングスタイルや開発手順、テスト手順などを理解できる
AGENTS.md の基本構成例
AGENTS.md を用意することでDevinが最初の環境準備の手助けになります。
基本構成は、プロダクトの環境で異なりますが、明確な指示内容で定義することをオススメします。
# 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向け注意事項
- PRにコメントがあっても、指示があるまで作業しないこと
- AGENTS.md は Devin 専用の指示書としてコーディング前に必ず参照
- `.rules`、`.mdc`、`.cursorrules`、`.windsurf` なども自動参照される
- 可能な限り詳細で明確な指示を記載することで、Devin の作業効率が向上
Devin における自動参照範囲
Devin は以下を自動的に参照して作業に活用されます。
- AGENTS.md
- ファイル構造
- README.md
- プルリクエストテンプレート（
pull_request_template.md、devin_pr_template.md） -
.devin/wiki.json（DeepWiki生成の制御用） - パッケージ管理ファイル（
package.json、requirements.txtなど） - 参照情報をもとにリポジトリ知識を生成し、コード理解や作業効率に活用
Devin オンボーディングのポイント
-
AGENTS.md を整備する
- Devin が作業に必要な環境やルールを理解できるようにする
-
開発環境のセットアップ情報を記載
- 依存関係、ビルド、テストコマンドなど
-
コードスタイル・テスト・ワークフローのルールを明確化
- Devin がプロジェクトの標準に従って作業できる
-
プロジェクト構造やドキュメント参照先も提示
- 必要に応じてファイルやディレクトリのパスを具体的に書く
-
更新と改善
- 新しいルールや変更があれば、AGENTS.md を随時更新
Knowledge と Playbook の活用
Devinをチームで効率的に活用するには、Knowledge と Playbook を整備することが重要です。
これらは、単発タスクだけでなく、コードベース全体や繰り返し作業に関する指示を整理・共有する仕組みです。
Knowledge とは
Knowledgeは、Devinがすべてのセッションで参照できる ナレッジの集合 です。
新しいエンジニアにチームのルールやコードベースの文脈を教えるのと同じように、Devinにもプロジェクトの文脈や慣習を事前に与えることで、より正確な作業が可能になります。
Knowledge は、リポジトリ内の .rules、.mdc、.cursorrules、.windsurf などの 特殊ファイルやカスタムルール からも自動取得されます。
これにより、チーム独自のコーディング規約やワークフローだけでなく、カーソル操作や編集ルールなどのカスタム設定も、Devinがセッション内で参照して活用できるようになります。
Knowledge Onboardingという公式のドキュメントを読むことで、新しいエンジニアにプロジェクトのオンボーディングを行うような使い方を学ぶことができます。
Knowledge に含める情報の例
以下は、Knowledge に含めると Devin が効率的に作業できる 一例 です。必ずしもすべてを含める必要はなく、チームやプロジェクトに応じて取捨選択してください。
- コード規約や命名ルール
- デプロイ・テスト・レビューのワークフロー
- プロジェクト特有の内部ライブラリやツールの使い方
- よくあるバグとその解決策
このような情報を整備することで、Devin は単発タスクだけでなく、チーム全体の作業フローやプロジェクトルールにも沿った支援が可能になります。
また、セッション内でやり取りされたアイディアや注意点は Knowledge として定義 しておくことが重要です。Markdown ファイルとして用意し、セッションに渡すことで、Devin が継続的に参照できるようになります。
Knowledge の設定ポイント
Knowledge は、小さな単位に分けて整理するのが基本です。
こうすることで、Devin はセッション内で必要な情報だけを効率的に参照でき、無関係な情報に惑わされずに作業が可能になります。
さらに、セッションでKnowledgeを使用する際は、関連するファイルやナレッジを明示的に指定することが重要です。
これにより、Devin は適切なKnowledgeを正確に取得し作業に反映できます。
- トリガーを明確にする：どのファイルやタスクに関連するKnowledgeかを指定
- 小さく分割する：複数のKnowledgeアイテムに分けることで、必要な部分だけを参照できる
- 定期的に更新する：チームのワークフローやプロジェクト内容に応じて追加・修正
Knowledge はドキュメント作成に似ている
Devin の Knowledge は、チーム内のルールや作業フローを整理して共有するものなので、ドキュメント作成のプロセスに非常に近いです。
- 情報を整理して分かりやすくまとめる
- 手順、注意点、参照先、禁止事項などを明確にする
- チームの誰でも理解できる形にする
そのため、テンプレートを用意しておくと非常に書きやすく、統一感も出ます。
Markdown で用意すれば、Devin が自動で参照できる Knowledge としてそのまま活用できます。
Knowledge テンプレートサンプル：例
チームによって内容は変わりますが、雛形を準備しておくことで統一感が生まれます。
テンプレートを用意することで、何を載せるのかという整理のハードルを下げることができます。
# Knowledge タイトル
Trigger Description: <Devin がこの Knowledge を参照する条件やキーワード>
## 概要
- この Knowledge の目的や使いどころを簡潔に説明
## 手順 / Procedure
- ステップ 1: <実行内容>
- ステップ 2: <実行内容>
- ステップ 3: <実行内容>
※必要に応じて複数ステップに分ける
## 注意点 / Advice
- Devin が気をつけるべきポイント
- 過去の失敗例や改善方法
## 参照情報 / References
- 関連ファイルやドキュメントのパス
- API リンクや仕様書など
## 禁止アクション / Forbidden Actions
- Devin が絶対に行ってはいけない操作
使用例（コード規約 Knowledge）
使用例（コード規約 Knowledge）
# コード規約 Knowledge
Trigger Description: "プロジェクトのコード規約"
## 概要
- チーム共通のコードスタイルと命名ルールを提供
## 手順 / Procedure
- 変数名は camelCase を使用
- 関数名は動詞 + 名詞形式で命名
- JSX コンポーネントは PascalCase
- ESLint と Prettier 設定を必ず適用
## 注意点 / Advice
- 自動整形前にレビューを行う
- 既存命名規則と矛盾しないこと
## 参照情報 / References
- `.eslintrc.js`、`.prettierrc`
- `/docs/coding-style.md`
## 禁止アクション / Forbidden Actions
- 命名規則を無視したコミット
Knowledgeのサンプルテンプレートを付録として掲載しています。
Playbook とは
Playbookは、繰り返し行う作業のためのカスタム指示集です。
例えば、特定のサードパーティライブラリを複数箇所で使う場合や、定型的な処理をDevinに任せる場合に有効です。
Playbook の特徴
- 再利用可能で共有しやすい
- 手順や仕様を明確に書くことで、Devinが独立して作業可能
- 複雑な作業でもステップごとに分けることで、精度と効率を向上
書き方のポイント
Playbookの書き方は、Devinが明確理解できるような内容でまとめるように心がけましょう。
Devin Docsを参考に、以下のようなPlaybookの書き方で運用することをオススメします。
# Overview
* タスクの全体概要と、Devin に達成してほしい成果を簡潔に記載
# What’s Needed From User（ユーザーからの入力）
* Devin だけでは対応できない外部情報や入力を明示
* 例：トークン、CSV ファイル、Kaggle リンクなど
# Procedure（手順）
* タスクの全体範囲を網羅した手順を順番に記載
* **各行に1ステップ**、命令形で書く（Write, Navigate to, Create など）
* セットアップ・実タスク・成果物納品を含む
* 手順は **相互に重複せず、全体を網羅する（Mutually Exclusive & Collectively Exhaustive）** ことを意識
# Specifications（成果物条件）
* タスク完了後に満たされるべき条件を記述
* 例：ファイルの出力、テスト通過、データ保存
# Advice and Pointers（助言）
* Devin にタスクを実行する際の注意や推奨方法を記述
* タスク全体に共通する場合はトップレベルに、特定ステップにのみ適用する場合は手順内にネストして記述
# Forbidden Actions（禁止事項）
* Devin が絶対に行ってはいけない操作を明示
チェックリストを作成する
Playbookを作成するときのチェックリストを用意することで明確に作成することができます。
チェックリストサンプル
# Devin Playbook 作成チェックリスト
## 1. Playbook の目的を明確化
- [ ] Devin に実行させたいタスクを簡潔に定義
- [ ] タスクの成果物やゴールを明示
## 2. ユーザーからの入力を整理
- [ ] Devin だけでは取得できない情報をリスト化
- 例：トークン、CSV ファイル、外部リンクなど
- [ ] 入力がないとタスクが完了できないものを明示
## 3. Procedure（手順）の作成
- [ ] タスク全体をカバーするステップを順序立てて記載
- [ ] 1ステップ1行で、命令形（Write, Navigate to, Create）で記述
- [ ] セットアップ・実作業・成果物納品を含む
- [ ] 手順は重複せず、全体を網羅する（Mutually Exclusive & Collectively Exhaustive）
- [ ] タスクが複雑な場合は細分化
## 4. Specifications（成果物条件）の明示
- [ ] タスク完了後に満たされるべき条件を記述
- 例：ファイル出力、データ保存、テスト通過
- [ ] 成果物の確認方法が簡単に分かる形にする
## 5. Advice and Pointers（助言）の記載
- [ ] タスク全体に共通する助言をトップレベルに記載
- [ ] 特定ステップにのみ適用する助言は手順内にネスト
- [ ] Devin の誤認識や prior の補正に活用
## 6. Forbidden Actions（禁止事項）の明示
- [ ] Devin が絶対に行ってはいけない操作を記載
- [ ] ファイルの上書きや誤操作などのリスクを事前に防ぐ
## 7. ドラフト作成と添付
- [ ] Web アプリで「Create a new Playbook」から作成
- [ ] または `.devin.md` ファイルとして保存し、セッション開始時にドラッグ＆ドロップ
## 8. テストと改善
- [ ] 作成した Playbook を小さなタスクで試す
- [ ] 実行手順が正確か、成果物条件が満たされるか確認
- [ ] 必要に応じて手順や助言を修正
- [ ] 他メンバーに共有して再利用可能な形に整備
---
💡 **ポイント**
- 小さなマルチステップタスクから始める
- Procedure は具体的すぎず柔軟に対応できるようにする
- 成果物条件を明確にして、正確に完了したか簡単に確認できるようにする
- 試行錯誤で改善して、組織内での成功事例を蓄積する
- Knowledge はコードベース全体のルールや文脈を伝える仕組み
- Playbook は定型タスクを正確に実行させる手順書
- どちらも整備することで、Devinがチームにとって 「信頼できるメンバー」 として機能
Knowledge と Playbook をうまく活用することで、日常の単純作業だけでなく、複雑な開発タスクもDevinに任せられるようになり、チーム全体の開発効率が大幅に向上します。
基本ルールとベストプラクティス
Devin をチームに導入する際は、単発のタスク指示だけでなく、日々のやり取りや Knowledge と組み合わせて活用することで効果が最大化されます。そのために押さえておきたい基本ルールを以下に整理しました。
-
指示は具体的かつ段階的に
抽象的な依頼ではなく、目的と手順を明示した具体的な指示を与えることが重要です。特に複雑なタスクは、段階に分けて依頼することで精度が高まります。 -
出力確認とフィードバックをセットで行う
生成結果は必ずレビューし、改善点をフィードバックとして返すことを習慣化しましょう。フィードバックは Knowledge に反映させると、次回以降の作業にも活きてきます。 -
チームのワークフローに沿って統一する
個々のやり方に委ねるのではなく、既存の開発フローに組み込むことが大切です。PR レビューやテスト手順などを Knowledge として明文化し、チーム全体で統一して使うことで、誰でも同じ水準で Devin を活用できます。
チーム開発でのステップ
Devin をチームに導入する際は、いきなり大規模な領域に任せるのではなく、段階を踏んで取り入れていくことがポイントです。以下は代表的なステップの流れです。
-
小さなタスクから Devin を試す
最初はドキュメント整備やユーティリティ関数の実装、Lint 修正など、影響範囲の小さいタスクに利用してみましょう。精度や指示の仕方をチームで確認しながらノウハウを蓄積できます。 -
CI/CD やレビュー工程への組み込み
慣れてきたら、CI/CD の設定補助やテストケースの作成、Pull Request レビュー補助など、既存フローの一部に Devin を参加させます。これによりチームの標準プロセスに沿った形で、AI の支援を自然に取り込むことができます。 -
ナレッジ・Playbook のフィードバックサイクルを回す
実際のやり取りの中で得られた気づきや改善点は、その都度 Knowledge や Playbook に反映しましょう。指示の仕方やプロジェクト特有のルールを明文化していくことで、Devin はチーム専用の「学習済みメンバー」として成長していきます。
まとめ
Devin の導入は「一度設定すれば完了」ではなく、チームと一緒に育てていくプロセスです。小さく始め、ワークフローに組み込み、ナレッジを循環させることで、AI は単なる作業補助ではなく、信頼できる開発メンバーへと進化していきます。
付録: docs.devin.ai の使い方
公式のドキュメントを参照するときは、 Ask a questionを使うことをオススメします。
日本語で質問することで、日本語での回答得ることができたり、特定のドキュメントを調べてもらうことが可能です。
Devin Deep Wiki / Ask と同じように Devinのドキュメント上で利用できます。
- 調べたい内容をフッターにある Ask a question で質問をする
- 質問した結果内容を確認する
- 該当のドキュメントへアクセスする（もしくは仕様を確認する等）
付録: Knowledge サンプル集
Knowledge はドキュメント作成と似ており、テンプレートやサンプルを用意しておくことでチーム全体で統一的に整備できます。以下に基本テンプレートとサンプルをまとめました。プロジェクトごとのカスタマイズの参考にしてください。
📝 基本テンプレート
基本テンプレート
# Knowledge タイトル
Trigger Description: <Devin がこの Knowledge を参照する条件やキーワード>
## 概要
- この Knowledge の目的や対象範囲を簡潔に説明
## 手順 / Procedure
- ステップ 1: <具体的な操作や確認内容>
- ステップ 2: <具体的な操作や確認内容>
## 注意点 / Advice
- Devin が迷いやすいポイントや過去の失敗例
## 参照情報 / References
- 関連ファイル、API リンク、仕様書など
## 禁止アクション / Forbidden Actions
- Devin が絶対に行ってはいけない操作
💻 サンプル 1: コード規約 Knowledge
コード規約
# コード規約 Knowledge
Trigger Description: "コード規約 / 命名ルール"
## 概要
- プロジェクト共通のコードスタイルと命名ルールを提供
## 手順 / Procedure
- 変数名: camelCase
- 関数名: 動詞 + 名詞形式
- React コンポーネント: PascalCase
- ESLint と Prettier 設定を必ず適用
## 注意点 / Advice
- 自動整形前にレビューを行う
## 参照情報 / References
- `.eslintrc.js`
- `.prettierrc`
## 禁止アクション / Forbidden Actions
- 命名規則を無視したコミット
🚀 サンプル 2: デプロイワークフロー Knowledge
デプロイワークフロー
# デプロイワークフロー Knowledge
Trigger Description: "本番環境デプロイ"
## 概要
- 本番環境への安全なデプロイ手順を定義
## 手順 / Procedure
- main ブランチにマージ後、自動で CI/CD パイプラインが実行
- ビルド・テストを通過した場合のみデプロイを許可
- デプロイ後は Slack #deploy チャンネルに通知を送信
## 注意点 / Advice
- 手動で main に push しない
## 参照情報 / References
- `.github/workflows/deploy.yml`
- `/docs/deployment-guide.md`
## 禁止アクション / Forbidden Actions
- main ブランチへの直接 push
- テスト失敗時のデプロイ
🧪 サンプル 3: テスト実行 Knowledge
テスト実行
# テスト実行 Knowledge
Trigger Description: "テスト実行 / テスト修正"
## 概要
- 単体テスト・統合テストの実行方法を定義
## 手順 / Procedure
- `npm run test` で全テストを実行
- `npm run test:watch` で開発中のテストを継続実行
## 注意点 / Advice
- スナップショットテストは不要に更新しない
## 参照情報 / References
- `/tests/README.md`
- Jest 設定ファイル `jest.config.js`
## 禁止アクション / Forbidden Actions
- テストをスキップしてのマージ
🛠️ サンプル 4: 内部ライブラリ利用 Knowledge
内部ライブラリ利用
# 内部ライブラリ利用 Knowledge
Trigger Description: "内部ライブラリ / utils"
## 概要
- プロジェクト共通の内部ライブラリの利用ルール
## 手順 / Procedure
- 日付処理は必ず `utils/date.ts` を利用
- API 呼び出しは `lib/apiClient.ts` を通す
## 注意点 / Advice
- 外部ライブラリをむやみに追加せず、まず utils を確認
## 参照情報 / References
- `/src/utils/`
- `/src/lib/apiClient.ts`
## 禁止アクション / Forbidden Actions
- 外部ライブラリの安易な導入
Discussion