はじめに
世間では生成 AI の活用用途が拡張しており、以前に比べてより多くの作業や権限を委譲して共同でタスクを進めることが基本になりつつあります。 具体的にはコード生成だけでなく、壁打ちや情報整理、ドキュメント作成など、比較的抽象的なタスクでも生成 AI が効果を発揮する場面が増えています。
弊社では Amazon Q Developer を安全に利用できる環境が整っているため、Amazon Q Developer CLI（以下、Q CLI）をAIエージェントとして活用してさまざまな業務を進めています。
Amazon Q Developer の社内利用率を可視化してみた | サーバーワークスエンジニアブログ
本記事では、日々の業務で Q CLI を活用する中で遭遇した 3 つのつまずきポイントと、その対策や実際に運用している仕組みについて具体的にご紹介します。
参考：インフラ改修業務での活用例についても、以前の記事でご紹介していますので合わせてご参考にしてもらえれば幸いです。 【Amazon Q Developer】q chat でインフラ改修タスクを効率化する | サーバーワークスエンジニアブログ
前提
対象読者
- AWS 環境で開発・運用を行う開発者、インフラエンジニア
- Amazon Q Developer などのエージェントの利用経験がある、または興味がある方
- プロジェクトの生産性向上や作業効率化に関心がある方
環境
- AWS アカウント
- Amazon Q Developer
- ローカルマシンに Q CLI と AWS CLI がインストール済みであること
- ターミナル（コマンドライン）の基本的な操作知識
本記事の内容は私独自の運用手法であり、全てのプロジェクトや組織に適用できるものではないことをご了承ください。また、Q CLI や Amazon Q Developer の機能詳細よりも、実業務で運用する中で感じた課題とその対策に焦点を当てて言語化しています。 なお、本記事では Q CLI のチャットでやり取りする相手のことを「エージェント」と記載しています。
つまずきポイント1：エージェントの暴走/迷走問題
特に生成 AI に慣れていない頃によく直面する問題です。なんとなく生成 AI に指示を出してある程度時間を使って進めた結果、思っていたものと違うアウトプットが出来上がり、作業の手戻りが発生してしまいます。
エージェントはいい感じに自走してくれますが、その反面、よく暴走したり迷走したりします。
例えば、「このコードをレビューして」と指示したら、想定していた観点とは全く異なる部分を指摘したり、
「この機能を実装して」と依頼したら、既存のコードを大幅に書き換えてしまったり。
こうした事態は、作業時間の無駄だけでなく、手戻りによる精神的な疲労にもつながるため、指示の仕方や自動的に対策できるような仕組みづくりが必要になってきます。
t-wada さんのスライド「Agentic Software Engineering」でも以下のように言及されています：
エージェントは自走するが暴走/迷走もする。ガードレール設計としてのソフトウェアエンジニアリングや技術の 3 本柱（バージョン管理、テスティング、自動化）の重要性がさらに増している
引用元：Agentic Software Engineering / Findy 2025-07 edition - Speaker Deck
原因
エージェントの暴走/迷走問題は根本的には特定のタスクを指示する際に、作業の方向性やゴール、作業背景などの必要なコンテキストを明確にして指示していないことが原因です。
エージェントは与えられた情報から最善を尽くそうとしますが、人間側が曖昧な指示を出すとエージェントも曖昧な解釈で作業を進めてしまいます。
対策: 目的・背景・ゴールの言語化
きちんとコンテキストとなる情報を与えた上で、タスクの目的や背景、ゴールとは何かを言語化してイメージをすり合わせる作業が必要です。
NG 例:
> 〜の作業を進めて。 > レビューして。 > 〜を実装して。
OK 例:
> 〜の作業を進めたい。背景としてはxxで、目的はxxをしたいから。ゴールはxxとなっていること。 > 〜のレビューをしてほしい。レビュー観点はxxで、ローカル環境からデプロイして動作も確認したい。 > 〜を実装してほしい。まずは既存コードを把握して、実装に関する要件を理解して。TDDで進めたいのでテスト観点も洗い出して。
このように、単に「やってほしいこと」だけでなく、「なぜやるのか」「どうなっていればゴールなのか」を明確に伝えることで、エージェントの暴走/迷走を大幅に減らせます。
また、一度にまとめて指示を出さずにエージェントと対話を重ねて設計指針のようなドキュメントを共同で作成してから作業に取り掛からせることもできます。
対策: タスクリストによるガードレール
タスクリストで進め方や段階に分けてゴールを達成するような道標を与える方法も効果的です。 リストがあることでエージェントが暴走/迷走しないようなガードレールとなり、 また作業の途中で方針が変更になったとしても実行済みのタスクを保持しているため、スムーズに軌道修正できます。
タスクリストの例:実装作業の場合
[] 既存のコードを把握する。 [] 実装要件や背景（要求）を理解する。 [] 単体テスト観点を洗い出す。 [] 単体テストを実装する。 [] テストする。 [] 失敗したテストがパスするように実装を修正する。 [] テストが全てパスすることを確認する。 [] リファクタリングする。 [] レビューする。 [] PRを作る。
このように段階的なタスクリストを提示することで、エージェントは一度に全てを実行しようとせず、
一つずつ確実にステップを踏んで作業を進めます。
また、人間側も進捗状況を把握しやすくなり、途中で軌道修正することも容易になります。
補足: Q CLI の TODO リスト機能について
Q CLI は TODO リスト管理機能（/todos コマンド）が提供されています。
この機能は実験的機能として提供されており、/experiment コマンドで有効化できます。
エージェントが複雑なタスクを分解する際に自動的に TODO リストを作成し、/todos view や /todos resume などのコマンドで管理できます。
参考：TODO Management - Amazon Q Developer CLI GitHub
私はまだこの標準機能を活用できていないので、より効率的にタスク管理を行っていけるかどうかも今後検証してみたいと思います。
つまずきポイント2：直近タスクの作業詳細忘れる問題
時間のかかるタスクや抽象的なタスクをエージェントと共同で作業を進めているとよく発生する問題ですが、例えば、作業を進めていて仕掛かり中のままの状態で他のプロジェクトのタスクを進行したり、次の日に作業を継続することはよくあります。
そのような場合、作業再開時にエージェントは「直近の作業をどのような状態でどこまで進めていたか」を忘れてしまい、スムーズに再開できないことがあります。
よくあるシナリオ:
1 日目に作業を進めて、途中で中断します：
人）〜の作業を進めて エージェント）わかりました。...ですね。...を開始します。...が完了しました。 人）...の部分を直して。 エージェント）わかりました。...を直します。 人）今日はここまで。（セッション終了）
翌日、作業を再開しようとすると：
人）昨日の続きを進めたいんだけど...どこまでやったっけ？
あるいは、エージェントに聞いても：
人）昨日の作業の続きを進めてください。 エージェント）わかりました。どのような作業を進めますか？ 人）（えっ、覚えてないの...？）
このように、人もエージェントも作業の詳細を忘れてしまい、スムーズに再開できません。
原因
以下の 2 つが主な原因です。
- タスクを中断した時のセッション間での情報の断絶
- 長時間作業によるコンテキストデータの肥大化
Q CLI はセッションをまたいでも会話履歴を保持していますが、複数のタスクを並行して進めていたり、
時間が経過すると、エージェントも人も作業の詳細を忘れてしまいます。
対策: 進捗管理ドキュメントの活用
このような事態を避けるために、進捗管理ドキュメントを作成します。
先述した TODO リスト機能は、ゴールや方針が明確なタスクには有効ですが、あらかじめやることが決められていないタスクや調査や考察を繰り返しながら模索しながら進める作業は、事前に TODO リストを作ることが困難です。
そのような場合は、任意のタイミング（特に他の作業への切り替え時や 1 日の作業終了時）に、仕掛かり中の作業のスナップショットを取っておきます。次回セッション再開時にその進捗管理ドキュメントを読み込ませることで、スムーズに作業を再開できます。
進捗管理ドキュメントの作成・更新方法
作業を中断する際に、以下のように指示します：
人）ここまでの作業内容を進捗管理ドキュメント（progress.md）として保存してください。
セッション終了後に作業を再開する際、このドキュメントを読み込むことで
仕掛かり中の作業をスムーズに継続できるようにしたいです。
以下の項目を含めてください：
- 現在の状態（ステータス、最終更新日時）
- 完了したこと
- 次にやること
- 懸念点やメモ
エージェント）承知しました。progress.mdに進捗管理ドキュメントを作成します。
[ファイル作成の実行...]
進捗管理ドキュメントを作成しました。次回セッション再開時に
「progress.mdを読み込んで作業を再開してください」と指示していただければ、
スムーズに作業を継続できます。
作業を再開する際は、以下のように指示します：
人）progress.mdを読み込んで、仕掛かり中の作業内容を把握してください。
その後、作業を再開します。
エージェント）progress.mdを確認しました。
現在の状況：
- タスク: 〜の実装
- ステータス: 実装中
- 完了: 既存コードの調査、実装要件の整理、テスト観点の洗い出し
- 次のステップ: 単体テストの実装
単体テストの実装から再開しますか？
進捗管理ドキュメントの例:
# タスク名: 〜の実装 ## 現在の状態 - ステータス: 実装中 - 最終更新: 2025-10-08 ## 完了したこと - 既存コードの調査完了 - 実装要件の整理完了 - テスト観点の洗い出し完了 ## 次にやること - 単体テストの実装 - テストパスするように本体コードを修正 ## 懸念点・メモ - xx の部分で既存の仕様と競合する可能性がある - パフォーマンスへの影響を確認する必要がある
コンテキストウィンドウ制限への対応
進捗管理ドキュメントの仕組みは、エージェントのコンテキストウィンドウ（会話履歴の保持容量）の制限にも効果的かと思います。
コンテキストウィンドウとは
Q CLI では、会話履歴やコンテキストファイルを保持するための「コンテキストウィンドウ」に制限があります。詳細は以下の AWS 公式ドキュメントをご参照ください。
参考：Context management - Amazon Q Developer User Guide
実際の影響
長時間の会話や複数タスクの並行作業を続けると、コンテキストウィンドウが埋まってきます。コンテキストウィンドウには制限があるため、古い会話履歴の詳細が失われる可能性があります。
特に複数タスクを並行して進めている場合、直近のタスクに関する情報の解像度が低くなり、同じ精度で作業を継続することが難しくなります。
コンテキストウィンドウがオーバーフローした際の挙動
コンテキストウィンドウが限界に達すると、以下のように突然赤文字で The context window has overflowed, summarizing the history... のメッセージが表示され、問答無用で会話履歴が圧縮されてしまいます
# Q CLI のタスク進行中 🛠️ Using tool: execute_bash (trusted) ⋮ ● xxx ⋮ ● Completed in 0.32s The context window has overflowed, summarizing the history... ✔ Conversation history has been compacted successfully! # 英語の出力に変わってしまう。。。
圧縮後はそれまでの詳細なやり取りが要約されてしまうため、直前まで日本語でやり取りしていたのに英語で返答されたり、細かい文脈が失われたりすることがあります。 このような事態が起こったとしてもすぐに作業を継続できるよう、コンテキスト使用状況を定期的に確認し、重要な情報は進捗管理ドキュメントとして外部化しておくと良いと思います。
コンテキスト使用状況の確認方法
コンテキスト使用状況を常時監視しておくことでオーバーフローに備えることができます。
Context Usage Indicator（実験的機能）で常時監視
実験的機能として「Context Usage Indicator」が提供されています。この機能を有効にすると、プロンプトに常時コンテキスト使用率が表示されるようになります。
有効化方法
# Q CLI 起動中 > /experiment
実験的機能の一覧が表示されるので、「Context Usage Indicator」を選択して ON にします
⚠ Experimental features may be changed or removed at any time ? Select an experiment to toggle › ❯ Knowledge [ON] Enables persistent context storage and retrieval across chat sessions (/knowledge) Thinking [ON] Enables complex reasoning with step-by-step thought processes Tangent Mode [ON] Enables entering into a temporary mode for sending isolated conversations (/tangent) Todo Lists [ON] Enables Q to create todo lists that can be viewed and managed using /todos Checkpoint [OFF] Enables workspace checkpoints to snapshot, list, expand, diff, and restore files (/checkpoint) Context Usage Indicator [OFF] Shows context usage percentage in the prompt (e.g., [rust-agent] 6% >)
有効化すると、プロンプトにコンテキスト使用率がパーセンテージで表示されます：
8% >
この機能を使えば、わざわざコマンドを実行しなくても、常にコンテキスト使用状況を把握できます。ただし、実験的機能のため、将来的に変更や削除される可能性がある点には注意が必要です。
コンテキストの内訳を確認したい場合
コンテキストの内訳を詳しく見たり、最適化を検討する際には、以下のコマンドが役立ちます。
1. /usage コマンド - 全体的な使用状況を確認
> /usage Current context window (107290 of 200k tokens used) ||████████████████████████████████████████████████████████████████████████████████ 53.65% █ Context files: ~1120 tokens (0.56%) █ Tools: ~1330 tokens (0.66%) █ Q responses: ~25450 tokens (12.73%) █ Your prompts: ~79400 tokens (39.70%) 💡 Pro Tips: Run /compact to replace the conversation history with its summary Run /clear to erase the entire chat history Run /context show to see tokens per context file
コンテキストウィンドウの使用状況が視覚的に表示され、何にどれだけトークンを消費しているかが一目でわかります。
2. /context show コマンド - ファイルごとの使用状況を確認
$ q chat > /context show Total: ~1100 tokens 📄 .amazonq/rules/security.md (~180 tkns) 📄 .amazonq/rules/coding-standards.md (~320 tkns) 📄 docs/architecture.md (~150 tkns) 📄 docs/best-practices.md (~200 tkns)
引用元：Understanding context window impact - Amazon Q Developer User Guide
補足: ナレッジベース機能について
コンテキストウィンドウの問題に対しては、ナレッジベース機能を駆使することでより最適化できる可能性があります。ナレッジベースは検索時のみトークンを消費するため、大規模なコードベースや膨大なドキュメントを扱う際に有効です。
適切なアプローチや使い分けについては、以下の公式ドキュメント（英語）をご参照ください：
- Choosing the right context approach - Amazon Q Developer User Guide
- Knowledge base context (for large datasets) - Amazon Q Developer User Guide
つまずきポイント3：同じ説明の繰り返し問題
エージェントとの共同作業に慣れてくると、定型作業や同じような指示を繰り返し行う場面に出くわすともっと効率化したいと感じるようになります。
例えば、作業手順書を作成するたびに「このフォーマットで書いてください」「レビュー観点はこれです」「対象環境はこれです」と毎回説明するのは時間の無駄です。また、説明を忘れたり、説明内容にばらつきが出て品質に影響を与えてしまいます。
対策: カスタムエージェントとコンテキスト構造化
このような繰り返し作業を効率化するために、カスタムエージェントとコンテキスト構造化が有効です。
具体例: 手順書作成エージェント
私の場合は継続プロジェクトで定期的に作業手順書を作成する機会が多く、毎回同じような説明を繰り返していました。そこで、手順書作成専用のカスタムエージェントを作成しました。
作業手順書はフォーマットや記載する粒度、レビュー観点がある程度決まっているため、それらをテンプレートとルールとして定義しておくことで、作業内容を伝えるだけで標準化された手順書を自動生成できるようになりました。
実際に運用している手順書作成エージェントの構成例：
{ "name": "manual-writer", "description": "手順書作成を支援するエージェント", "prompt": "あなたは手順書作成の専門エージェントです。以下の手順で作業を進めてください：\n\n## 基本方針\n- 既存手順書の活用を最優先とし、汎用テンプレートは補完的に使用\n- 現状調査完了後に手順書作成を開始\n- AWS公式ドキュメント検証を手順書作成前に必ず実施\n- 対話形式で必要な情報を段階的に収集\n\n## 作業フロー\n1. チケット作業ディレクトリの確認\n2. 現状調査完了確認\n3. 手順書分割方針確認\n4. AWS公式ドキュメント検証\n5. 手順書ベース選択（既存手順書の検索）\n6. 事前条件確認（対象アカウント、作業日時）\n7. 情報収集（段階的）\n8. 手順書生成と品質チェック\n9. 出力・保存\n\n## 重要な注意事項\n- 現状調査完了を必ず確認してから手順書作成を開始する\n- AWS公式ドキュメント検証は手順書作成前に必ず実施する\n- 必ず既存手順書の検索から開始する\n- 段階的に情報を収集し、一度に多くを聞かない\n- 不明な点は推測せず、ユーザーに確認する", "resources": [ "file://templates/manual-template-console.md", "file://templates/manual-template-cli.md", "file://.amazonq/rules/progress-management-rules.md" ], "tools": [ "fs_read", "fs_write", "aws___search_documentation", "aws___read_documentation" ] }
ディレクトリ構造の例:
project/
├── .amazonq/
│ ├── cli-agents/
│ │ └── manual-writer.json
│ └── rules/
│ └── progress-management-rules.md
└── templates/
├── manual-template-console.md
├── manual-template-cli.md
└── aws-verification-template.md
このように、エージェント定義とテンプレート、ルールを整理しておくことで、「手順書を作成して」と指示するだけで、対話形式で必要な情報を収集し、標準化された手順書を自動生成してくれます。
実際の使用例
カスタムエージェントを起動して手順書を作成する流れ：
# カスタムエージェントを起動 $ q chat --agent manual-writer 人）RDS のスナップショット取得手順書を作成してください エージェント）承知しました。AWS公式ドキュメントでRDSスナップショットの手順を確認します... 確認完了しました。以下の内容で手順書を作成します： - 対象: RDS スナップショット取得 - 環境: 本番環境（xxxxxxxxxxxx） - テンプレート: manual-template-console.md 手順書を生成しています... 手順書を manual-rds-snapshot-20251010.md に保存しました。 内容を確認してください。
このように、カスタムエージェントが対話形式で必要な情報を収集し、テンプレートに基づいて標準化された手順書を自動生成してくれます。毎回フォーマットや対象環境のリストを説明する必要がなく、作業効率が大幅に向上します。
補足: resources フィールド
カスタムエージェントの resources フィールドに指定したファイルは、エージェント起動時に自動的にコンテキストとして読み込まれます。エージェント毎に読み込ませたいファイルをあらかじめ作成してここに記載しておくことで、毎回同じような説明をする必要がなくなり、アウトプットのばらつきや品質の安定化を図ることができます。
{ "name": "my-project-agent", "resources": [ "file://.amazonq/rules/**/*.md", "file://README.md", "file://docs/architecture.md" ] }
参考：Configuring persistent context with agent resources - Amazon Q Developer User Guide
最後に
Q CLI を日々の業務でAIエージェントとして活用する中で、試行錯誤しながら辿り着いた運用方法をご紹介しました。 まだまだ活用できていない機能や使い方があるので、今後もより効果的な活用方法を模索しながら日々の業務に利用したいと思います。
どなたかの参考になれば幸いです。
