Cognition AI の自律型 AI ソフトウェアエンジニア「Devin」を組織へ本格導入する際、開発リーダーが直面しやすい課題が「チーム固有のテスト手順やアーキテクチャ制約、コード品質規約をいかに遵守させるか」です。セッションごとに同じ注意点をプロンプトへ繰り返し入力するのは非効率的であり、運用のばらつきを生む原因になります。Devin Playbook（プレイブック）は、再利用・共有・バージョン管理が可能なプロンプトテンプレートであり、特定のタスクに対する「カスタムシステムプロンプト」として機能することで、この課題を解決します。
テスト手順とリポジトリ固有のガイドラインを確実に定着させるには、Playbook の 5 つの基本構成要素を正しく設計し、Devin 管理画面での組織・全社レベルでの管理方法を理解し、リポジトリ単位の Skill（スキル）や Knowledge（ナレッジ）との適切な使い分けを確立することが不可欠です。
Devin Playbook の基本構造とエコシステムにおける位置付け
Devin Playbook は、反復的かつ複数ステップにわたるエンジニアリングタスクを実行するために用意された構造化テンプレートです。一度確立した成功ワークフローをプレイブックとして保存しておけば、チームメンバーはセッション開始時にそれを適用するだけで、Devin に一貫した手順と品質基準を守らせることができます。
Playbook、Skill、Knowledge の使い分けと連携
Devin 環境で自動化を推進するにあたり、3 つの機能の役割分担を明確に整理しておく必要があります。
| 機能 | 主な役割 | 保存・設定場所 | スコープと呼び出し方法 |
|---|---|---|---|
| Playbook | 複数ステップからなるワークフローや業務プロセスの標準化 | Devin Web アプリ（Settings > Playbooks）または API | 組織（Organization）/ 企業（Enterprise）全体で共有。UI での選択または !macro で呼び出し |
| Skill | 特定リポジトリに依存する環境構築・テスト実行・デプロイ手順 | 各コードリポジトリ内（.agents/skills/<name>/SKILL.md） | リポジトリ単位で Git 管理。Devin による自動検出、または @skills:name で明示実行 |
| Knowledge | コーディング規約、アーキテクチャ背景、独自ツール仕様、不具合対策 | Devin Web アプリ（Settings）/ マネージド Plugin へ移行中 | ワークスペース全体で共有。トリガー説明文に基づき Devin が自律的に参照 |
使い分けの鉄則: ローカル開発サーバーの起動コマンドや特定リポジトリのテスト実行コマンド（例: Docker 起動や npm test）など、特定のコードベースに直接紐づく手順は、Git でバージョン管理できる Skill としてリポジトリにコミットします。一方、不具合調査からテスト・修正・PR 作成までを一気通貫で行うタスク全体の流れや品質ゲートの定義は Playbook として作成します。Playbook の手順内からリポジトリ内の Skill（例: @skills:test-before-pr）を呼び出す設計にすることで、保守性の高い柔軟な運用が可能になります。
本番運用に耐えうるテスト用 Playbook の 5 大要素
Devin が過不足なく自律的に問題解決を行えるよう、効果的な Playbook は以下の 5 つのセクションで構成します。
1. 手順（Procedure）
Devin が実行すべきアクションを時系列で定義します。
- 原則として1 行につき 1 つの命令形ステップ（
Run、Inspect、Verify、Generateなど）で記述します。 - ステップ同士が MECE（モレなくダブりなく）になるよう設計します。
- 「環境準備（Setup）」「タスク実行（Task Execution）」「検証（Validation）」「引き渡し（Delivery）」の 4 フェーズを網羅します。
2. 成果物仕様・終了条件（Specifications）
タスク完了とみなす客観的基準（ポストコンディション）を明記します。テスト運用においては、「全自動テストの成功（Pass）」「Lint エラー・警告ゼロ」「カバレッジ基準の維持」などを定義します。
3. アドバイスと指針（Advice and Pointers）
Devin の判断基準をチームの好みに合わせるための補足情報です。例えば「時間短縮のため初手は全体テストではなく個別テストを実行する」「データベースはローカル再構築せず Docker コンテナを活用する」といった実務的なヒントを記載します。
4. 禁止事項（Forbidden Actions）
意図しない破壊的変更を防ぐためのセーフティレールです。「main ブランチへの直接プッシュ禁止」「テストを通すためだけに既存のアサーション（期待値）を改ざんすることの禁止」「未承認ライブラリの勝手なインストール禁止」などを定めます。
5. ユーザーからの必要入力（What's Needed from User）
コードベースから自律取得できない情報（マージ先ブランチ名、関連するチケット番号、ステージング環境のアクセス権など）を明確にします。
Devin 管理画面における Playbook の作成と運用
エンジニアリングリーダーや管理者は、Devin Web ダッシュボードからチームの Playbook を集中管理できます。
ステップ 1: Playbook 管理画面を開く
- Devin の Web アプリにログインし、Settings > Playbooks（
https://app.devin.ai/settings/playbooks）へアクセスします。 - 3 つのタブを用途に応じて確認します。
- Organization: 現在の組織/チーム全体で共有されるプレイブック。
- Enterprise: 全社配下のすべての組織に共通で適用されるプレイブック（エンタープライズ管理者向け）。
- System: Cognition 社が提供する標準プレイブック。
ステップ 2: プレイブックの新規作成
- Organization タブで Create playbook をクリックします。
- わかりやすいタイトル（例:
リポジトリテスト標準化および PR 準備規約）を入力します。 - Macro（マクロ） の設定:
!で始まる一意の識別子（例:!run-repo-testsや!pr-ready）を指定します。英数字、ハイフン、アンダースコアが使用でき、組織内で一意である必要があります。プロンプト入力時にマクロを打ち込むだけで即座に適用できるようになります。 - 本文エディタに、Markdown 形式で 5 つのセクションを記述します。
- Save をクリックして保存します。自動的にバージョン管理が開始されます。
ステップ 3: セッションでの呼び出し
開発者は以下のいずれかの方法でセッションに Playbook をアタッチできます。
- UI からの選択: セッション作成画面で Playbook を選択します。青色のピルタグとインライン編集コンポーネントが表示され、セッション開始前にパラメータを調整できます。
- マクロによる呼び出し: プロンプト入力欄に
!run-repo-testsと入力します。セッション開始後、タイムラインの最上部に灰色のカード背景で Playbook の内容が表示されます。
実践例: リポジトリテスト実行と PR 規約 Playbook テンプレート
以下は、実際の開発現場で活用できる、テスト自律実行と PR 品質担保を網羅した Playbook テンプレートです。
Playbook: リポジトリテスト実行および PR 提出標準規約
## Overview
コード変更に伴うテストの自律実行、不具合修正、および Pull Request の品質基準を標準化する。
## What's Needed From User
- マージ対象ブランチ名（未指定の場合は `main`）
- 修正対象の Issue 番号またはタスク要約
## Procedure
1. git status と git diff を確認し、変更されたファイルおよび未追跡ファイルを把握する。
2. リポジトリ直下にテスト用 Skill（`.agents/skills/` または `.devin/skills/`）が存在するか確認し、存在する場合は `@skills:<skill-name>` で実行する。
3. リポジトリ固有の Skill がない場合は、主要テストコマンド（`npm test`、`pytest`、`cargo test`、`go test ./...` など）を実行する。
4. テストが失敗した場合:
- 出力ログからスタックトレースと原因を分析する。
- 実装コード側を修正してバグを解決する。
- ユーザーから明示的な指示がない限り、既存テストのアサーション内容を変更してはならない。
- 失敗したテストファイルを再実行し、すべて成功するまで修正ループを継続する。
5. 静的解析およびフォーマッタを実行する: `npm run lint` および `npm run format:check`。
6. 今回の変更によって生じたすべての Lint エラーおよびスタイル違反を解消する。
7. git diff を再確認し、デバッグ用の一時コード、不要な中間ファイル、環境変数ファイルが混入していないか点検する。
8. Conventional Commits 規約に従ってローカルコミットを作成する（`fix:`, `feat:`, `test:`, `refactor:`）。
9. 以下の項目を含む詳細な PR 概要を生成する:
- 根本原因の分析内容
- 変更を加えた対象ファイル一覧
- 実行した検証コマンドおよびテスト通過ログ
## Specifications
1. 既存および新規のすべての自動テストがパスし、スキップされたテストがないこと。
2. Linter の終了コードが 0 であり、警告やエラーが一切残っていないこと。
3. API キーや `.env` ファイル、バイナリ成果物がコミットに含まれていないこと。
4. 最終レポートに実行したテストコマンドと成功ログが明記されていること。
## Advice and Pointers
1. 初期のデバッグ時は、実行時間を節約するためエラーが出たテストファイルを単体で実行する。
2. バックエンドやデータベースに依存するテストの場合は、`docker-compose.yml` を確認しバックグラウンドでサービスを起動する。
3. リファクタリング時は、大きな変更を一気に行わず、関数単位で都度テストを実行して安全性を確保する。
## Forbidden Actions
1. テストを通すためにテストケースをコメントアウト・スキップ・削除することを固く禁じる。
2. いかなる理由があっても `git push --force` を実行してはならない。
3. ユーザーの明示的な許可なく、`.github/workflows/` 等の CI/CD 設定ファイルを書き換えてはならない。
チームでの運用・継続的改善プロセス
Playbook の作成は一度きりの作業ではなく、チームの実務に合わせて継続的に育てるプロセスです。
1. セッション中のリアルタイム改善（Live Iteration）
新しい Playbook で Devin を実行する際は、セッションのログに注目します。もし Devin が指示の解釈に迷ったり、望ましくないコマンドを選択した場合は、チャット上で直接指示を出して補正します。セッション完了後、その補正内容を Playbook の「Advice」や「Forbidden Actions」に追記してテンプレートを更新します。
2. バージョン履歴とロールバック
Devin は Playbook の全変更履歴を保持します。Settings で保存するたびにバージョン番号が更新されます。新しいプロンプトによって予期せぬ挙動が発生した場合は、履歴から過去の差分を確認し、安定していたバージョンへワンクリックで復元可能です。
3. 組織からエンタープライズへの昇格
複数の開発チームを抱える企業では、まず特定チームの Organization 内で Playbook の試作と検証を行います。高い安定性と効果が確認された Playbook は、エンタープライズ管理者が「Promote to Enterprise」を実行することで全社共通テンプレートに昇格させ、企業全体の開発基準を底上げできます。
エンジニアリングリーダー向け導入チェックリスト
| フェーズ | 実施事項 | 完了の目安 |
|---|---|---|
| 役割分担 | 環境依存コマンドは Git 内の SKILL.md に集約、全体の業務手順を Playbook に定義 | Playbook 内に特定リポジトリ固有のパスがハードコードされていない |
| 構造設計 | Procedure、Specifications、Advice、Forbidden Actions、Inputs の 5 項目を記載 | テスト失敗時に Devin が勝手に終了せず自己修復ループを回す |
| ショートカット | Settings > Playbooks で分かりやすいマクロ（!pr-ready など）を登録 | メンバーがプロンプト入力時にマクロで手軽に適用できる |
| 品質維持 | 定期的なセッション振り返り、例外パターンの追記、バージョン履歴の活用 | 複数リポジトリ間でのテスト通過率と PR レビュー通過速度の向上 |
Devin Playbook によって開発・テストの標準化ルールを言語化・資産化することで、自律型 AI エンジニアのポテンシャルを最大限に引き出し、開発速度とソフトウェア品質の両立を実現できます。