はじめに
AIエージェントを活用してプロジェクトの色々なタスクを実行できるかどうかを検証しています。 直近まではGitHub Copilot Agentを利用していましたが、Amazon Q Developer Proでq chatを使ってみて体験が良かったため、 携わっているプロジェクトで利用できるようにq chatでAIエージェントのオンボーディングを実施してみました。
Amazon Q Developerとは
Amazon Q Developerは、AWSが提供する生成AI搭載の開発者向けアシスタントサービスです。AWS環境での開発、運用、トラブルシューティングを支援し、コード生成、セキュリティスキャン、アーキテクチャ相談などの高度な機能を提供します。
q chatとは
Amazon Q Developerが提供する機能の一つで、コマンドライン（ターミナル）上で q chat というコマンドを打つことで起動する対話型チャットインターフェースです。
AWSサービスに関する質問、トラブルシューティング、コードスニペットの生成などを、コマンドライン環境から離れることなく実行できます。
前提条件
対象読者
- AWS環境で開発・運用を行う開発者、インフラエンジニア
- GitHub CopilotやAmazon Q DeveloperなどのAIエージェントの利用経験がある、または興味がある方
- プロジェクトの生産性向上やドキュメント作成の効率化に関心がある方
環境
- AWSアカウント
- Amazon Q Developer
- ローカルマシンにAmazon Q Developer CLIがインストール済みであること
- AWS Documentation MCP Server（aws_doc_mcp）のMCPサーバーが利用できること
- ターミナル（コマンドライン）の基本的な操作知識
手順
1. q chat開始
まずは任意のディレクトリでAmazon Q Developer CLIを起動します。
ユーザー実行
$ cd ai-onboarding
$ q chat
✓ awslabsaws_diagram_mcp_server loaded in 2.16 s
✓ aws_doc_mcp loaded in 3.59 s
✓ awslabscdk_mcp_server loaded in 3.87 s
⢠⣶⣶⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⣶⣿⣿⣿⣶⣦⡀⠀
⠀⠀⠀⣾⡿⢻⣿⡆⠀⠀⠀⢀⣄⡄⢀⣠⣤⣤⡀⢀⣠⣤⣤⡀⠀⠀⢀⣠⣤⣤⣤⣄⠀⠀⢀⣤⣤⣤⣤⣤⣤⡀⠀⠀⣀⣤⣤⣤⣀⠀⠀⠀⢠⣤⡀⣀⣤⣤⣄⡀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠋⠀⠀⠀⠙⣿⣿⡆
⠀⠀⣼⣿⠇⠀⣿⣿⡄⠀⠀⢸⣿⣿⠛⠉⠻⣿⣿⠛⠉⠛⣿⣿⠀⠀⠘⠛⠉⠉⠻⣿⣧⠀⠈⠛⠛⠛⣻⣿⡿⠀⢀⣾⣿⠛⠉⠻⣿⣷⡀⠀⢸⣿⡟⠛⠉⢻⣿⣷⠀⠀⠀⠀⠀⠀⣼⣿⡏⠀⠀⠀⠀⠀⢸⣿⣿
⠀⢰⣿⣿⣤⣤⣼⣿⣷⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⢀⣴⣶⣶⣶⣿⣿⠀⠀⠀⣠⣾⡿⠋⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⡇⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⢹⣿⣇⠀⠀⠀⠀⠀⢸⣿⡿
⢀⣿⣿⠋⠉⠉⠉⢻⣿⣇⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⣿⣿⡀⠀⣠⣿⣿⠀⢀⣴⣿⣋⣀⣀⣀⡀⠘⣿⣿⣄⣀⣠⣿⣿⠃⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⠈⢿⣿⣦⣀⣀⣀⣴⣿⡿⠃
⠚⠛⠋⠀⠀⠀⠀⠘⠛⠛⠀⠘⠛⠛⠀⠀⠀⠛⠛⠀⠀⠀⠛⠛⠀⠀⠙⠻⠿⠟⠋⠛⠛⠀⠘⠛⠛⠛⠛⠛⠛⠃⠀⠈⠛⠿⠿⠿⠛⠁⠀⠀⠘⠛⠃⠀⠀⠘⠛⠛⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠿⢿⣿⣿⣋⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠿⢿⡧
╭─────────────────────────────── Did you know? ────────────────────────────────╮
│ │
│ Use /model to select the model to use for this conversation │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
/help all commands • ctrl + j new lines • ctrl + s fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 You are chatting with claude-4-sonnet
2. 大枠の指示を出す
AIエージェントのオンボーディングという大きな目的を伝え、q chatからプロアクティブに質問してもらいながらコンテキストファイルを作成する方針で指示を出しました。
/editor を実行するとテキスト入力画面に切り替わるので、指示を入力します。
ユーザー実行
> /editor
以下を入力し、 :wq で閉じます。
AIエージェントをオンボーディングしながらプロジェクトに適したコンテキストファイルを作成するタスクを進めてください。 ## 解決する課題 AIエージェントがなかなか効率的に使えていない AIエージェントに指示をしているがいまいち精度が良くない ## このタスクで目指すこと コンテキストファイルを作成することで、AIエージェントを新しく参画したメンバーのようにプロジェクトにフィットさせる（＝オンボーデンングする） ## プロセスごとのReference - 実装、構築：GitHubのPR、プロジェクトのREADME - プロセスの進め方：チケットのコメント - プロジェクトの思想：各種ドキュメント ## タスク 上記の内容を踏まえた上で、AIエージェントからプロアクティブに質問してもらいながらコンテキストファイルを作成する。 mcp: amazon q developerの公式ドキュメントに記載しているベストプラクティスに基づいてコンテキストファイルを適切な場所、ディレクトリ、ファイルに保存する。
最後の mcp の指示を与えておくことで、q chatを運用する上でコンテキストファイルをどのディレクトリに保存すべきかを検索して適切に保存してもらうことができます。
出力
※ Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]: の確認メッセージは t を入力すると、それ以降は確認メッセージを出さないようにできます。
🛠️ Using tool: search_documentation from mcp server aws_doc_mcp
⋮
● Running search_documentation with the param:
⋮ {
⋮ "arguments": {
⋮ "limit": 5,
⋮ "search_phrase": "Amazon Q Developer context files best practices"
⋮ },
⋮ "name": "search_documentation"
Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:
>t
⋮ }
⋮
● Completed in 1.980s
🛠️ Using tool: read_documentation from mcp server aws_doc_mcp
⋮
● Running read_documentation with the param:
⋮ {
⋮ "arguments": {
⋮ "max_length": 3000,
⋮ "url": "https://docs.aws.amazon.com/prescriptive-guidance/latest/best-practices-code-generation/onboarding.html"
⋮ },
⋮ "name": "read_documentation"
Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:
> t
⋮ }
⋮
● Completed in 0.885s
🛠️ Using tool: read_documentation (trusted) from mcp server aws_doc_mcp
⋮
● Running read_documentation with the param:
⋮ {
⋮ "arguments": {
⋮ "max_length": 4000,
⋮ "url": "https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/third-party-context-project-rules.html"
⋮ },
⋮ "name": "read_documentation"
⋮ }
⋮
● Completed in 0.719s
mpcの指示によって、aws_doc_mcpがAWS公式ドキュメントを検索し、AIエージェントのオンボーディングに関するベストプラクティスや、コンテキストに関するルールを読み込んでくれていることがわかります。
q chatからの出力
> 素晴らしい！Amazon Q Developerの公式ドキュメントを確認しました。プロジェクトルールは .amazonq/rules フォルダにMarkdownファイルとして保存するのがベストプラクティスですね。
このように、人手でAWSドキュメントを検索しなくても、q chatが自ら適切なコンテキストファイルの保管先を判断してくれます。
3. q chatからのプロジェクト概要の質問に回答する
q chatがユーザーからの指示を受けて、プロジェクトの概要について質問をしてくれます。
q chatからの質問
それでは、あなたのプロジェクトに最適なコンテキストファイルを作成するために、以下の質問にお答えください： ## 1. プロジェクトの基本情報 • どのような種類のプロジェクトですか？（Webアプリケーション、API、インフラ構築、データ分析など） • 主要な技術スタック（プログラミング言語、フレームワーク、クラウドサービス）は何ですか？ • チーム規模はどの程度ですか？ ## 2. 現在の課題の詳細 • 「効率的に使えていない」とは具体的にどのような内容ですか？ • 「精度が良くない」と感じる場面はどのようなときですか？ • AIエージェントに期待している主な作業は何ですか？（コード生成、レビュー、ドキュメント作成など） ## 3. 既存のドキュメント・リソース • 現在、プロジェクトにはどのようなドキュメントがありますか？（README、設計書、API仕様書など） • GitHubリポジトリのPRやIssueで特に参考になるものはありますか？ • チケット管理ツール（Jira、GitHub Issues等）は何を使っていますか？ ## 4. プロセスと思想 • 開発プロセスで重要視していることは何ですか？（コードレビューの観点、テスト戦略、セキュリティ要件など） • プロジェクトの設計思想や原則があれば教えてください
以下のように回答しました
ユーザー実行
## 1. プロジェクトの基本情報 • どのような種類のプロジェクトですか？（Webアプリケーション、API、インフラ構築、データ分析など） 過去から継続しているアプリケーションはWebアプリケーション、xxxのシステムで利用されるxxxを利用したシステム。 これらを支えるAWSのインフラ構築、運用、改善などが主なタスクです。 最近、新しくxxx基盤のプロジェクトも始まりました。 • 主要な技術スタック（プログラミング言語、フレームワーク、クラウドサービス）は何ですか？ プログラミング言語：Python、シェルスクリプト クラウドサービス：AWS • チーム規模はどの程度ですか？ ステークホルダー：インフラチームの責任者、その上長 自社メンバー：PM1名、技術メンバー3名 ## 2. 現在の課題の詳細 • 「効率的に使えていない」とは具体的にどのような内容ですか？ 既存のスクリプトをベースとして踏襲するように指示をするも、アウトプットを微調整しなければならない • 「精度が良くない」と感じる場面はどのようなときですか？ 上に同じ • AIエージェントに期待している主な作業は何ですか？（コード生成、レビュー、ドキュメント作成など） 意思決定に必要な情報収集、ステークホルダーとの方針決めに使う資料作成 ## 3. 既存のドキュメント・リソース • 現在、プロジェクトにはどのようなドキュメントがありますか？（README、設計書、API仕様書など） BacklogのWiki：プロジェクトのルール Backlogのチケット：ステークホルダーとのコミュニケーション xxx：タスクを進める上でのDesignDoc、ADR、手順書、プレイブック ガイドブック：全体のガイドライン • GitHubリポジトリのPRやIssueで特に参考になるものはありますか？ GitHubには参考になる情報はありません • チケット管理ツール（Jira、GitHub Issues等）は何を使っていますか？ Backlog ## 4. プロセスと思想 • 開発プロセスで重要視していることは何ですか？（コードレビューの観点、テスト戦略、セキュリティ要件など） 顧客の垣根を超えてチームとしてプロジェクトを進める ふりかえりの文化 カイゼンのマインド • プロジェクトの設計思想や原則があれば教えてください チケットの内容や各種ツールの内容に表れているので、適宜質問してください。
4. q chatによるプロジェクト構造の確認と既存プロジェクトの探索
プロジェクト概要に回答すると、q chatは既存のコンテキストやドキュメント類を探索し始めます。
q chatの出力
> 素晴らしい！プロジェクト構造が見えてきました。既に context ディレクトリがありますね。 重要なディレクトリの中身も確認してみましょう： 🛠️ Using tool: fs_read (trusted) ⋮ ● Reading directory: ~/xxxx/context with maximum depth of 0 ⋮ ● Completed in 0.1s ...
すでにcontextディレクトリに独自でプロジェクトルールや方針をまとめたドキュメントが存在していたため、q chatはそれをベースにコンテキストファイルを作成しようとしてくれました。
5. q chatによるコンテキストファイルの作成
q chatは既存プロジェクトの探索をした後、.amazonq/rules ディレクトリと個別コンテキストファイルを段階的に作成してくれました。
q chatによる実行
cd ~/xxxx/ && mkdir -p .amazonq/rules
個別コンテキストファイルの一例（project-overview.md：プロジェクトの全体像を把握するための基本ルールファイル）
# xxxx プロジェクト概要 ## プロジェクトの性質 このプロジェクトはxxxシステムとxxx基盤を支えるAWSインフラの構築・運用・改善を行います。 ### 主要コンポーネント - **xxxシステム**: データ収集・監視システム - **データ基盤**: データ分析基盤 - **セキュリティ管理**: SecurityHub是正対応 - **インフラ運用**: AWS環境の構築・運用スクリプト ### 技術スタック - **プログラミング言語**: Python、シェルスクリプト - **クラウドサービス**: AWS（複数環境: dev, stg, prd） - **データ分析**: Amazon Athena、S3 - **セキュリティ**: AWS SecurityHub ### 環境構成 - 開発環境 - ステージング環境 - 本番環境 ## チーム構成 - **ステークホルダー**: インフラチームの責任者、その上長 - **自社メンバー**: PM1名、技術メンバー3名 ## プロジェクト管理ツール - **チケット管理**: Backlog - **ドキュメント管理**: xxxx（DesignDoc、ADR、手順書、プレイブック、ランブック） - **Wiki**: BacklogのWiki（プロジェクトルール） - **ガイドライン**: xxxx ## 重要な価値観・原則 - 顧客の垣根を超えてチームとしてプロジェクトを進める - **ふりかえりの文化**: 継続的改善 - **カイゼンのマインド**: 常に改善を意識 ## コード・スクリプト生成時の注意点 - 人がメンテナンスすることを前提とした成果物を作成 - 技術的負債にならないような実装を心がける - 小さく始めて段階的に拡張 - 過度な抽象化を避ける - 複雑さに応じてアプローチを調整
このように、対話を通じてq chatがコンテキストファイルを生成してくれます。 最終的にq chatが作成したドキュメント群は以下の通りです。
ファイル構成
.amazonq/
├── rules/ # コンテキストルール
│ ├── project-overview.md # プロジェクト全体像
│ ├── aws-infrastructure.md # AWS・セキュリティルール
│ ├── project-management.md # プロジェクト管理
│ ├── ai-agent-interaction.md # AIエージェント連携
│ ├── security-hub-remediation.md # SecurityHub是正
│ ├── docbase-backlog-integration.md # DocBase・Backlog連携
│ └── feedback-and-kaizen.md # フィードバック・カイゼン
└── feedback-templates/ # フィードバックテンプレート（4ファイル）
├── quick-feedback.md # 2-3分のクイックフィードバック
├── weekly-review.md # 15-20分の週次レビュー
├── monthly-evaluation.md # 30-45分の月次評価
└── feedback-guide.md # 実践ガイド・コツ集
6. コンテキストファイルのレビュー
q chatに依頼し、作成されたファイルを1つずつレビューして最適化します。
ユーザー実行
> コンテキストファイルをレビューしたいです。 一覧を出しつつ、1つずつ出力してそれに対して添削する形で進めたいです。
q chatの出力
> 承知しました！作成したコンテキストファイルを一覧表示し、1つずつレビュー・添削していきましょう。
出力した内容を確認し、適宜 /editor などを活用して指摘を出します。
余計な情報が思いのほか多かったので行ごと削除したりファイルごと削除しました。
7. 作成されたコンテキストファイルの確認
/context showで確認できます。
ユーザー実行
> /context show
🌍 global:
.amazonq/rules/**/*.md (8 matches)
README.md (1 match)
AmazonQ.md
👤 profile (default):
<none>
9 matched files in use:
🌍 /xxx/.amazonq/rules/docbase-backlog-integration.md (~1730 tkns)
🌍 /xxx/README.md (~200 tkns)
🌍 /xxx/.amazonq/rules/ai-agent-interaction.md (~1070 tkns)
🌍 /xxx/.amazonq/rules/project-management.md (~620 tkns)
...
Total: ~10800 tokens
大事なこと
AIエージェントに指示を出して早くタスクが終われば生まれるのは時間です。
その生まれた時間で人間はアイディアを出したり想像力を働かせることに時間を使えるはずです。そして、新たな価値を生み出してプロジェクトをより良いものにできてこそAIエージェントの成果になると思います。また、そこに至るまでに得られた知識や知見がチームを成長させることにもなり、これもまた成果だと思います。
この点を忘れないように、今後も効果的で価値のある使い方にしていきたいものです。
ということで、コンテキストファイルにこの思想を取り入れてみても面白いと思いました
任意のコンテキストファイル
## 🎯 AIエージェント活用の基本思想 ### 真の価値創造のサイクル 単純作業の自動化 → 時間の創出 → 創造的活動への集中 → 新たな価値創出 → 人間の成長 → より高次の課題解決 ### AIエージェントの役割 AIエージェントは**作業の代替者**ではなく、**人間の創造性を解放するパートナー**である。
若干言い回しに癖がありますが、大事なことなのでこれくらい大袈裟に指示を与えても良いかと思います。
ちなみに
/context コマンドでq chatに設定されたコンテキストを管理することができます。
/context add <コンテキストとして認識させたいパスかファイル> と実行することでq chatにコンテキストを認識させることができますが、
.amazonq/rules/配下 のディレクトリにコンテキストファイルとして保存されるわけではないです。
（動作を確認するまではなんとなく保存されるような認識を持ってしまっていため、若干戸惑いました）
ユーザー実行
> /context add context/* # context/ディレクトリ配下をコンテキストとして認識させる
Added 1 path(s) to profile context.
> /context show
🌍 global:
.amazonq/rules/**/*.md
README.md (1 match)
AmazonQ.md
👤 profile (default): # profileはディレクトリやファイルの実態があるわけではない
context/* (3 matches)
例えばチームでq chatを運用する場合、
- プロジェクト全体で統一させたいコンテキストは本記事のオンボーディングを活用して .amazonq/ディレクトリ に保管して継続運用し、
- 個人のタスクや個別のプロジェクトなどに関連するコンテキストはprofileに寄せて /context add でコンテキストを認識させるのが良さそうです。
まとめ
すでに数年携わっているプロジェクトでAIオンボーディングを試してみましたが、改めてプロジェクトの進め方を見直すいい機会になりました。 プロジェクトのチーム全員でやってみるのが良さそうなので、実施する機会があれば得られた知見を共有したいと思います。
自然言語でプロアクティブに対話しながら段階的にコンテキストを作成できる点や、既存ルールを考慮して統合できる点もかなり体験が良かったです。
今後は作成されたコンテキストファイルを利用して実際にタスクを実行してみて効果を測りたいと思います。 また、プロジェクトで利用しているツール（BacklogやGithubなど）を直接MCPサーバーと連携させてコンテキストファイルを作成することなく、AIが直接コンテキストを理解してもらえる用なアプローチも試したいです。
おまけ
このブログは途中までは自身で執筆しましたが、途中からはq chatで完成させました。特にプロンプトの具体的な内容や、マスクしている部分は手作業でやると非効率なため、オンボーディングの最後にお願いしました。
> 最後にここまでの一連のプロセスをブログにしたいです。 ベースは書きました ---- ここに手書きのブログ内容を貼り付け ---- ブログを完成させてください。markdownで出力して保存してください。
