Amazon Q Developerを用いた開発にてコンテキストを永続化する運用方法

はじめに

Amazon Q Developerで長時間開発を行っていると、以下のような文章が表示されます。

これはAmazon Q Developerの機能で、チャット履歴がコンテキストウィンドウの容量上限に近づくと表示されます。

Allowを選択するとチャット履歴は要約され、以後の会話ではこの要約のみがコンテキストとして利用されます。そのためAmazon Q Developerは、要約に含まれる情報だけを参照して応答を生成することとなります。

その過程で以下のような情報が失われ、作業効率の低下につながります。

• 詳細な作業内容
• デプロイ時の認証情報
• 指定した作業の進め方

本記事では、この問題を解決する手段として、Amazon Q DeveloperのRules機能を活用した運用方法を紹介します。

Rules機能とは

Rulesはプロジェクト内の.amazonq/rulesフォルダに保存されるMarkdownファイルで、主に以下の目的で使用されます。

• コーディング標準の統一
• ベストプラクティスの強制
• チーム全体での一貫性確保
• 開発ワークフローの標準化
• セキュリティガイドラインの適用

プロジェクト資産に加え、RulesをGitなどで管理・共有することで、プロジェクトメンバー全員が共通利用できます。

Rule作成方法

Amazon Q Developerのチャット画面右上に表示されている「Rules」をクリックします。

これまでに作成したRuleの有効／無効を切り替えたり、「Create a new rule」から新しいRuleを追加できるウィンドウが開きます。
「Create a new rule」をクリックします。

「Create a rule」ウィンドウに移行します。
ここでは新しく作成するRuleファイルの名前を決定することができます。

英字、数字、ハイフン、アンダースコアのみを使用し、先頭は英字または数字で始めてください。最大100文字までです。

名前を決定したら左下の「Create」をクリックします。

すると、このように Rule の具体的な内容を記載できる画面が表示されます。
基本的には、以下の雛形に従って作成するとスムーズです。

雛形

# ルール名

## 目的
このルールが存在する理由を明確に記述

## 指示事項
- Amazon Q Developerが従うべき具体的な指示
- 追加の指示事項（独自の識別子付き）
- 指示が適用される条件

## 優先度
[Critical/High/Medium/Low]

## エラーハンドリング
- 例外が発生した場合のAmazon Q Developerの動作
- 主要な指示に従えない場合のフォールバック戦略

ここまで記載すればRuleの作成は完了です。
作成したRuleは自動的に有効となり、今後の応答に利用されます。

Rules機能を活用した運用方法

ここまで紹介したRules機能に「context-management」というRuleを加えることで、コンテキストを永続的に保持できるようにします。

ファイル構造

project-root/
├── .amazonq/
│   └── rules/
│       └── context-management.md
├── project-context.md　← 初回利用時に自動作成

context-management作成

Rule内容

# context-management.md

## 目的
チャットセッション間での作業継続性を確保し、重要な開発情報の損失を防ぐ

## 指示事項
### ファイル管理（絶対パス基準）
- セッション開始時に`project-context.md`を自動読み込みする (ID: AUTO_LOAD_ABSOLUTE)
- ファイル未存在時は`project-context.md`を新規作成する (ID: CREATE_AT_ROOT)
- 重要な変更時は即座に`project-context.md`を更新する (ID: IMMEDIATE_UPDATE_ABSOLUTE)
- 更新時はタイムスタンプを自動挿入する (ID: TIMESTAMP)

### セッション管理
- コンテキストウィンドウ80%超過時に保存を提案する (ID: USAGE_WARNING)
- コンパクト化前に現在の状況を必ず`project-context.md`に保存する (ID: PRE_COMPACT_SAVE_ABSOLUTE)
- コンパクト化後に保持情報の概要を表示する (ID: POST_COMPACT_SUMMARY)
- 文脈不明時は`project-context.md`から情報を参照する (ID: CONTEXT_REFERENCE_ABSOLUTE)

### 標準テンプレート
新規作成時は以下の要素を記載する：

- 最終更新
[自動挿入されるタイムスタンプ]
- 現在の作業
- 技術設定
- AWSリージョン:
- 環境:
- 主要サービス:
- 重要な決定事項
- 解決済み問題
- 次回のタスク
- 注意事項

### 情報分類と管理
以下の情報を優先的に管理する：
- 即座に永続化: 技術的決定、設定変更、解決済み問題、認証設定
- セッション終了時に永続化: 進行中タスク、次回予定、学習事項
- 一時記憶のみ: 現在の会話文脈、試行錯誤の過程

### 動作確認とフィードバック
- ファイル更新時：「project-context.mdを更新しました（[更新内容の概要]）」
- エラー時：「project-context.mdへのアクセスに失敗しました（ [パスリスト]）」

## 優先度
Critical

## エラーハンドリング
- アクセス失敗した場合は、チャット内に情報を表示し手動保存を依頼する
- ファイル破損時は`.backup`拡張子でバックアップを作成してから修復する
- 権限エラー時は代替パスを試行し、全て失敗した場合はユーザーに権限確認を依頼する
- 情報競合時は最新情報を優先し、競合内容を明示する

「context-management」Ruleを導入すると、コンテキストを「project-context.md」に切り出して保存できるため、履歴圧縮による情報の損失を防げます。

動作確認

「context-management」Ruleが有効になっていることを確認したら、実際にAmazon Q Developerでチャットしてみましょう。

新規で「project-context.md」が作成され、これまでの作業内容が追加されていることが確認できました。
ちなみに「project-context.md」は以下のような構造で作成されていました。

project-context.md

# プロジェクトコンテキスト

## 最終更新
2025-09-20 20:56 JST

## 現在の作業
プロジェクト削除機能実装完了

## 技術設定
- **AWSリージョン**: ap-northeast-1
- **環境**: 本番環境（CloudFront + S3）
- **主要サービス**:
  - Cognito (User Pool + Identity Pool)
  - DynamoDB (Projects, ChatHistory)
  - S3 (ファイルストレージ)
  - CloudFront (CDN)

## 重要な決定事項
1. **認証システム**: Cognito User Pool + Identity Pool連携
2. **データ共有設計**:
   - チーム共有: プロジェクト、ソース、チャット機能
   - 個人管理: 履歴機能（ユーザーごとに分離）
3. **UI設計**: ソース表示（閲覧のみ）、選択機能削除
4. **削除処理**: DynamoDB + S3 + チャット履歴の包括的削除

## 解決済み問題
1. Identity Pool設定とUser Pool連携
2. DynamoDBアクセス権限設定
3. TypeScriptエラー修正（User interface拡張）
4. メンバー数表示修正（作成者含む1人から開始）
5. 表記統一（チーム→メンバー）
6. ステータスフィルター機能削除
7. プロジェクト削除機能実装（確認モーダル付き）

## 現在の実装状況
- **認証**: 完了
- **プロジェクト管理**: 完了（作成・表示・削除）
- **削除機能**: 実装完了（未デプロイ）
  - DynamoDB: プロジェクト + チャット履歴削除
  - S3: プロジェクト関連ファイル削除
  - 確認モーダル付き

## 次回のタスク
1. プロジェクト削除機能のデプロイ
2. S3イベント通知による自動ベクトルDB更新（オプション）
3. ファイルアップロード機能の実装
4. チャット履歴の永続化

## 注意事項
- S3削除は現在手動同期が必要（ベクトルDB更新）
- Identity Pool ID: XXXXXXXXXXXXXXXXXXXXXXXXXXX
- CloudFront Distribution ID: XXXXXXXXXXXXXXXXXXXXXXXXXXX
- プロファイル: XXXXXXXXXXXXXXXXXXXXXXXXXXX

## 技術的詳細
- **バケット構造**: XXXXXXXXXXXXXXXXXXXXXXXXXXX
- **DynamoDBテーブル**: XXXXXXXXXXXXXXXXXXXXXXXXXXX
- **削除処理**: 包括的削除（プロジェクト→チャット履歴→S3ファイル）

「context-management」Ruleに用意された標準テンプレートで必要な情報はほとんどカバーされています。
あとはファイルを適宜更新して読み込ませれば、履歴が要約されてもこれまでの作業内容を失わずに進められます。

まとめ

• Amazon Q Developerでは履歴が圧縮されると大事な情報が抜け落ちてしまうことがあります
• そこで「context-management」Ruleを使えば、作業内容や設定が「project-context.md」に保存され、履歴をまたいで利用できるようになります
• これにより、長時間の開発でも効率を落とさず、安定した作業を続けられます

皆さんもAmazon Q Developerで開発を行うときは、ぜひ試してみてください！

参考文献