AI導入時の運用ルール・プロンプト設計ガイドライン

## プロンプト設計の原則

### 上流工程（要件定義・基本設計・詳細設計）向け

- 以下の要素で構成する
  - **役割の指定**：どういう立場で回答させるか（例：「業務システム開発経験豊富なシステムアナリスト」）
  - **背景・コンテキスト**：システムの概要・技術スタック・動作原理など前提情報
  - **インプット情報**：そのフェーズで確定した成果物の内容
  - **出力指示**：何をどの形式で生成させるか。以下を明示することが品質向上につながる
    - 確定済み内容と叩き台として追記する内容を区別して出力するよう指示する
    - 出力してほしいものだけでなく出力してほしくないものも明示する
    - 出力形式（表・項目構成など）を具体的に指定する
- プロンプトは単体で完結する情報を持たせる（使用するツールがプロンプト外の文書を参照できない場合、必要な情報はプロンプト内に展開して記載する）

### 製造・テストフェーズ向け

- 以下の要素で構成する
  - **前提・条件**：対象のPR番号・ブランチ・テスト方針など作業の前提となる指定を記載する
  - **作業内容**：タスク固有の実装内容・指示を記載する
  - **参照ファイル**：起点となるファイルを指定し、対象ファイルをAIに特定させる。タスク固有の機能・画面仕様は該当する仕様ファイル（例：docs/配下）の参照を指示する
  - **証跡**：「AGENTS.mdの証跡ルールに従いPRコメントに記載すること」とする
- 一度に全部を頼まず、タスク（動作確認できる単位）で区切る
- AGENTS.mdに共通ルール・制約を記載し、タスク固有の内容はタスクプロンプトで指示する
- タスクのアウトプットを明確化する（明確な成功基準を持つタスクでDevinは力を発揮する）
- 出力してほしくないことはAGENTS.mdの「実装しないこと」に明示する

---

## 運用ルール

### AGENTS.mdの管理（Devin,Claude共通）
- 初版は「新しいエンジニアに最初に渡すオリエンテーション資料」と考えると加減がわかりやすい
- リビングドキュメントとして扱い、状況の変化や新しい知見に合わせて随時更新する
- タスク共通で判断の根拠とする情報を含める。タスク固有の情報は含めずに肥大化させない（目標値: 200行以下）
- タスク固有の機能・画面仕様はAGENTS.mdに含めず、個別ファイル（例：docs/配下）として管理し、該当タスクのプロンプトで参照を指示する（トークン節約と指示遵守率の向上につながる）
- 「実装しないこと」はAIが意図を誤解しないよう具体的に書く
- PRコメントへの証跡記載ルールをAGENTS.mdに定義する
- Claude Code用にCLAUDE.mdを作成し、冒頭に`@AGENTS.md`と記載して同じ階層上のAGENTS.mdをインポートする

### Skillsの活用（Devin,Claude共通）
- デプロイ手順、リリースチェックリスト、レビュープロセスといった、繰り返し行われる手順に関する指示は、skillとして`.claude/skills//SKILL.md`に定義する
- Claude：スラッシュコマンド（`/skill-name`）による実行やタスクへの自動マッチングを通じてClaudeがそのスキルを呼び出す
- Devin：`@skills:skill-name`による実行や関連性に基づいてDevinがスキルを自動的に呼び出す

### 決定的な保護機能（Hooks / Permissions / Managed settings）（Claude専用）
- 指示によるガードレールは従われない場合があるため、確実に守らせたいルールは指示ではなくコードによる強制（hooks/permissions/managed settings）で担保する
- **[Hooks](https://code.claude.com/docs/ja/hooks)**：`PreToolUse`イベントでツール呼び出しを検査し、終了コード2で強制ブロックする
  - 適用例：特定ディレクトリ（本番設定ファイル等）への書き込み禁止、危険コマンド（DB削除系等）の実行禁止、フォーマッタ・静的解析ツールの強制実行
- **[Permissions](https://code.claude.com/docs/ja/permissions)**：ツールごとの利用可否（許可／確認／禁止）を`settings.json`に定義し、プロジェクト単位で権限範囲を制御する場合に用いる
- **[Managed settings](https://code.claude.com/docs/ja/settings)**：管理者がデプロイし、ユーザーのローカル設定で上書き不可。組織全体で一貫した強制力を持たせたいルール（秘密情報アクセス禁止、本番DB操作禁止等）はこちらで担保する

### DESIGN.mdの管理（Devin,Claude共通）
- デザインシステム（配色・タイポグラフィ・コンポーネント仕様等）を機械可読・人間可読のハイブリッド形式で一元管理する
- UI生成タスクのプロンプトからDESIGN.mdを参照させ、実装のたびに見た目がぶれないようにする
- 既存デザインがない場合は初版を「現状のUIから抽出したスタイルガイド」として作成し、以降はAGENTS.md同様リビングドキュメントとして更新する

### AGENTS.md等の構成例
- 固有ルールを適用する階層にAGENTS.mdとCLAUDE.mdをセットで配置する。  
- [パス固有のルール](https://code.claude.com/docs/ja/memory#organize-rules-with-claude/rules/)は.claude/rules/にpathsスコープを指定して切り出す。  
- 決定的な保護機能（hooks/permissions）は.claude/settings.jsonに、繰り返し発生する手順はskillとして.claude/skills/に定義する。  
- デザインはDESIGN.mdとして、AGENTS.mdと同じ階層または対象範囲の粒度に応じてapp/frontend/等の下層に配置する。

```
project/
├── AGENTS.md              # プロジェクト全体の共通ルール
├── DESIGN.md               # デザインシステム（配色・タイポグラフィ・コンポーネント仕様）
├── CLAUDE.md              # @AGENTS.md
├── .claude/
│   ├── settings.json      # hooks・permissionsの定義（プロジェクト共有）
│   ├── rules/
│   │   └── frontend.md    # パス固有ルール（Claude専用）
│   └── skills/
│       └── code-review/
│           └── SKILL.md   # 繰り返し発生する手順（例：コードレビュー）
├── app/
│   ├── api/
│   │   ├── AGENTS.md      # app/api/ 固有ルール（DevinもClaude Codeも参照）
│   │   └── CLAUDE.md      # @AGENTS.md（→ app/api/AGENTS.mdを参照）
│   └── frontend/
│       ├── AGENTS.md      # app/frontend/ 固有ルール
│       ├── CLAUDE.md      # @AGENTS.md（→ app/frontend/AGENTS.mdを参照）
│       └── DESIGN.md      # frontend固有のデザイン仕様
└── docs/                  # 機能・画面仕様（タスクのプロンプトで参照を指示）
```

> 参考
- [How Claude remembers your project](https://code.claude.com/docs/ja/memory)
- [Steering Claude Code: CLAUDE.md files, skills, hooks, rules, subagents and more](https://claude.com/ja/blog/steering-claude-code-skills-hooks-rules-subagents-and-more)
- [Example Structure](https://docs.devin.ai/desktop/cascade/agents-md#example-structure)
- [サポートされているスキルファイルの配置場所](https://docs.devin.ai/ja/product-guides/skills#%E3%82%B5%E3%83%9D%E3%83%BC%E3%83%88%E3%81%95%E3%82%8C%E3%81%A6%E3%81%84%E3%82%8B%E3%82%B9%E3%82%AD%E3%83%AB%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E9%85%8D%E7%BD%AE%E5%A0%B4%E6%89%80)

---

### Devin活用ルール

#### タスク設計
- ジュニアエンジニアが半日程度で完了できる粒度を1タスクの目安とする
  - 例：環境構築・プロジェクト初期化、画面モック作成、画面単位の機能実装、テストコード生成・実行
- チームメイトに依頼する時と同じように必要なコンテキスト情報を提供する
  - 例：技術スタック・DB設計・画面仕様（AGENTS.md）、対象画面・機能の仕様、参照すべきファイル

#### セッション・PR管理

- タスクごとにセッションを切り替える（セッションをまたいだ作業継続は避ける）
- PRへの修正指示は同じセッションに投入し、同じPRブランチに追加コミットさせる
- PRをcloseして再作成させるのはタスクの方向性が根本的に誤っている場合のみ

> 参考
- [デビンの置かれている環境はどのようなものですか？](https://docs.devin.ai/onboard-devin/environment#what-is-devin%E2%80%99s-environment)  

---

### Claude.ai / Claude Code活用ルール

- 用途に応じて使い分ける
  - 文書生成・叩き台作成（上流工程）：Claude.ai（ブラウザ版）を使用する
  - コードレビュー・修正・補助（製造以降）：ターミナル版のClaude CodeまたはVS Code等IDE上からClaude Codeを使用する
- コードベースが存在しない工程ではDevinのAskモードよりClaude.ai（ブラウザ版）を優先して使用する
- DevinのPRに対する修正ではDevinに返却するよりClaude Codeを優先して使用する

> 参考
- [Claude Codeを実行する場所](https://code.claude.com/docs/en/platforms#where-to-run-claude-code)
- [クロードがアクセスできるもの](https://code.claude.com/docs/en/how-claude-code-works#what-claude-can-access)

---

### AIアウトプットのレビュー観点

#### 上流工程
- 網羅性：確定済みの方針・要件が漏れなく含まれているか
- 整合性：インプット情報・項目間で矛盾がないか
- 逸脱：対象外と決めた内容をAIが超えていないか
- 過剰補完：目的・規模に対して過剰な追記がないか
- 抽出漏れの確認：叩き台の追記内容から考慮漏れを判断し必要であれば方針を見直す

#### 製造・テストフェーズ
- 仕様準拠：画面・機能設計との整合性が取れているか
- セキュリティ：セキュリティ上の問題がないか
- 保守性：可読性・保守性に問題がないか
- 網羅性：テストケース・テストコードが仕様を網羅しているか