こんにちは。電通総研コーポレート本部システム推進部の山下です。
この記事は自分がAmazon Q Developer(以降Amazon Q)の実体験で得た知見を整理したものとなっています。
大体Amazon Qを使って5-6万行程度のコードを書かせてみて得られた知見となっています。これからAmazon Qを使った開発をしてみたいという方の参考になれば幸いです。
対象読者
以下のことにはある程度慣れている人が対象です
生成AIを使ったコーディングエージェント
コーディングエージェントって利用されている方、聞いたことがある方も増えてきているのではないでしょうか？
例をあげると以下のようなツールたちです。
IDEと統合されているCursorやClineといったものもありますが、今回のものとは少し異なります。
世の中のブログなどではClaude Codeが話題になっていることが多いような印象があります。
Amazon Q Developer とは
さて、今回紹介するAmazon Q Developer(以降 Amazon Q)は、AWSが提供しているコーディングエージェントです。
利用開始には、アカウントが必要でこのアカウントが少し分かりづらい形になっています。
まず、アカウントの払い出しの方法としては2種類あります。
- IAM Identity Center
- Builders ID
IAM Identity Centerの方が機能が多かったりするようです。
コーディングエージェントとして利用する場合には大きな機能の差はありません。
IAM Identity Centerを有効にできるかはAWSアカウントの都合などもあります。
プロジェクトのポリシーと合わせてどういった形で利用するかは検討してください。
インストール & 初期設定
現在のAmazon QのCLIはLinux環境にしか存在していないので注意が必要です。
Windowsの場合は以下のような手段で環境を構築するのが良いでしょう。
- WSLを導入する
- DevContainerを導入してその上で利用する
なお、Amazon QのCLIの更新は頻繁でaptのリポジトリの整備がなされていないので定期的に入れ直しが発生するかもしれません。下に示すインストールコマンドを再度実施するなどして環境を随時最新になるようにしてください。
公式手順に従い CLI を導入
自分は以下のような手順で導入しています。
cd /tmp wget https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.deb sudo apt-get install -f sudo dpkg -i amazon-q.deb rm amazon-q.deb
Amazon Qを起動
インストールが完了したらまずはログインします。
ターミナルで以下のコマンドを実行してください。
q login
すると
? Select login method › ❯ Use for Free with Builder ID Use with Pro license
上記のような選択肢が出るので、「Use with Pro license」を選んでアカウントの情報を順番に入力していってください。最終的にブラウザが起動して認証を行うことになります。
これでAmazon Qを起動する準備が整いました。
以下のコマンドで起動できるはずです。
q
起動すると以下のような画面が表示されるはずです。
基本的な使い方
Amazon Qが起動したらあとは好きなように指示を出せばAmazon Qがコードを書いたり様々なタスクを実行してくれます。
例えば「Next.jsでhello worldアプリを作って」みたいな大雑把な指示でもある程度動作してくれます。
このままでも、十分便利なのですが、この状態ではまだAmazon Qの使い方としてはもったいないです。
以降ではこれを改善する細かいテクニックなどを紹介します。
Amazon Qのより効率的な利用方法
ツールの実行を自動承認する
Amazon Qが外部のプログラムを実行する場合、都度承認を求めてきます。
いちいち応答するのは面倒なうえ開発速度が落ちてしまいます。なので、自動承認してしまうことにします。
/tools trust all
これを許可するために、Dev Containerの環境を構築して実行するのがおすすめです。
Amazon Qは極端な話ですが rm -rf / だろうがなんでも実行してしまいます。実際にAmazon Qにrebootコマンドを実行されてしまったという話を聞いたことがあります。他にもaptで何かをインストールされたり、curl https://.../ | sh ... のようなスクリプトを実行されたりします。
プロンプトでこれらのコマンドの実行を禁止するなどして制御はある程度出来ますが完全ではありません。この自動承認を許可するためにコンテナのような分離された独自の環境を用意してその上で実行するべきです。
コンテキストを常に意識する
Amazon Qに限らず生成AIのモデルにはコンテキストという概念があります。
これは現在のモデルがどの程度の文書を保持しているかといったものになります。
人間の短期記憶に近い概念ですね。
この容量は現在のAIではそれほど巨大ではありません。例えばプロジェクトの全ソースコードを収めるといったことは通常できません。ドキュメントについても同様です。このためこのコンテキストにいかに情報を詰め込んでいくかということが生成AIによるコーディングでは重要になります。
また、このコンテキストに情報を詰め込みすぎても上手く行きません。コンテキストが不足してくると生成AIは途端に制御が効かなくなり、同じことを繰り返し続けたり、全然関係ない作業を始めたり、誤魔化そうとしたりと様々なことを始めるようになります。
つまり、コンテキストには今実際に作業を行っている内容に関係がある必要最小限の内容となっている状態が最良の状態ということです。そうなるようにプロンプトや指示の仕方を工夫していく必要があります。
また、このコンテキストを制御するコマンドがいくつかあるので上手く使っていきたいです。
特に、/clearや/compactといったコマンドはAmazon Q自体が勝手に実行したりします。
/clearは現在のコンテキストをまっさらにするコマンドです。
/compactは現在のコンテキストを圧縮(サマライズ)して格納し直すコマンドです。
このコマンドのうち /clearは非常に多用するコマンドになります。
逆に/compactコマンドはAmazon Qが自分で勝手に実行することがあります。これはコンテキスト量を自分で把握していて不足してきたら実行するためです。この状態になってしまったらもはや適切な動作は望めません。現在の作業を中断するなりして /clear を実施し、与えるコンテキストや指示内容などから見直しを実施すべきです。
理想的には何か指示を出して結果を受け取ったら /clear を実行することが望ましいです。
システムプロンプト(AmazonQ.mdなど)について
AmazonQは動作する際に、いくつかのファイルを自動的に読み込むようになっています。
AmazonQ.md.amazonq/rules/*.md
この中に色々記述することで動作をカスタマイズすることが出来ます。
なお、これらのファイルのベストな書き方はまだ世の中にも答えがない状態だと思います。
さらに使っているツールによっても違うと思います。
Amazon Qをメインで使っている自分とClaude Codeを使っている人では大幅に内容が違うということも十分あると思います。
ここでは、自分がAmazon Qを使っていて、こう設定したほうが良いなと考えていることを紹介します。
また、重要なことですがこれらのファイルの管理も「Amazon Qに書かせる、整理させる」のです。
- 「〇〇 (ファイル名)にこのようなことを追加して必ず守るようにして」などと指示をする
- 定期的に「〇〇ファイルが大きくなったので整理して簡潔にして」などと指示をする
このような指示を行ってプロジェクトや自分用のプロンプトを育てていくと良いでしょう。
AmazonQ向けの工夫
ここでは、Amazon Qを使っていて気がついたAmazon Qを使う上で注意、工夫が必要なことについて紹介します。
ドキュメントの書き方/書かせ方
開発ドキュメントなども含めてAIに書かせたいと思うのは自然なことだと思います。
ただし、Amazon Qは以下のような文書を書く癖があります。
- とにかくコードを使って説明したがる
- コードの話をしていないのに具体的なコードを使って文書を書いてしまう
- まだ説明していないことを勝手に補完してしまい膨大な分量の文書を書いてしまう
これらの動作を抑制するためのプロンプトをAmazonQ.mdなどには記載しておくべきです。
- 指示した以外の内容はドキュメントに記載するな
- コードを使った説明は指示しなかった場合以外はドキュメントに記載するな
などと指示しておくことで抑制できます。具体的なフォーマットを指示しておくと一層効果的です。
特にコードを使った説明や不要な文書はコンテキストを消費するだけで無駄なので常に避けるべきです。
Amazon Qに実行させるコマンドについての注意点
ログを大量に生成してしまうコマンド
コンテキストに関連することもあり、ログの出力には気をつける必要があります。
例えば、テストでスタックトレースを出力するなど膨大なログが出るような場合はそれだけでコンテキストを消費します。このログの出力については自分が試していても顕著に効果がありました。実装の最初のうちは、テストで何も考えずに普段通りログ出力が多い形でテストを実施していたところ、簡単にコンテキストが枯渇しAmazon Qが無限ループに突入しました。そこで、テストでは極力不要なログを出さないように実装させることでテストもちゃんと実施できるようになりました。
ユーザの入力待ちになるコマンド
また、テストやサーバ起動のコマンドについても注意が必要です。
Amazon Q は簡単に入力待ちになってしまうコマンドを実行します。
例えば、npm run start コマンドなどは起動後は Ctrl+C の入力待ちになっている場合がほとんどだと思います。
Amazon Qがこれを実行してしまうと完全に動作が停止します。これは困るので、AmazonQ.mdなどでプロジェクトで実行するコマンドは明示するようにし、上記のコマンドの場合ではnohupを使ったものを使うように設定しておくと上手くいきます。
理想的にはプロジェクトに関係があるコマンドは全てドキュメントにまとまっていて場当たり的なコマンドはAIには実行させない形になっていると良いです。
とはいえ、実際にはAmazon Qが勝手に色々実行したりすることが多いです。その場合は落ち着いてAIに代わって自分が追加の入力をしてあげる、もしくはCtrl+Cを押して追加の指示を出し、「そのコマンドを実行するならnohupをつけて実行してください」などと依頼して回避することができます。
なお、Amazon Qはたまに npm run start& などと実行して回避しようとしたりするのですが、これは正常に動作しないプロセスが生成されるようです。なのでnohupをつけたうえでバックグラウンドで実行するように指定する必要があるようです。
Amazon Qの得意、苦手なこと
ここでは、Amazon Qが得意なこと、苦手なことについて紹介します。
得意なこと
Amazon Qは基本的に愚直に作業を行ってくれるので、そういった仕事は得意です。
地道に行うことが求められる作業
複雑でなく量が膨大となるような作業はとても得意です。
- このプロジェクトの特定のディレクトリの下にある関数に〇〇というクラスを引数として与えるようにして
- Nextのフロントエンド部分を切り出して独立したReactのプロジェクトにしてほしい
など人間がやると苦痛に感じる作業でも淡々とこなしてくれます。Vueに変更するのは単純作業ではないですが、頑張ってやりきってくれます。
テストの生成
- テスト作成、モック作成 のような作業は得意です
- もちろん、ちゃんとテストできているかは確認する必要があります。例えば、coverageを測定することで一定の安心感を得ることはできると思います。
計画を立てること
作業内容についてAmazon Qと相談し、結果を作業手順書や計画書としてまとめるようにするとそれなりに整った計画書にしてくれます。
さらにそれをTODOリストの作成と指示すると進捗管理も出来て便利です。
Amazon Qの苦手なこと
Amazon Qを使っていて苦手だなと感じる作業を簡単にまとめておきます
| 課題 | 症状 | 対策 |
|---|---|---|
| インフラ構築の作業が苦手 | DockerfileやTerraformなどを書かせると内容が古かったり、そもそも動かないものが生成される | 生成後に人間がレビュー |
| シェルスクリプトが下手 | 全く使えないシェルスクリプトを生成する。 | 書かせない、もしくは他のツールの利用を検討する |
| 開発環境整備が苦手 | 環境変数をうまく設定して起動するようなものが苦手。 | レビューをちゃんとやる、もしくは人が構築する。 |
| PORTという環境変数を作っているのに、APP_PORTという環境変数を別に作ったりする。 | ||
| 不要コードを残してしまう | リファクタ後も極力古いコードを残そうとする | 「使わないコードを削除せよ」と明確に指示して削除する。それでも残そうとするので人間がたまにチェックする。 |
どうも、インフラが関わってくる操作が顕著に苦手なようです。シェルスクリプトが苦手なのは意外でした。例えばChatGPTなどはシェルスクリプトをとても綺麗にかいてくれる印象があったのでAmazon Qもそうなのだと期待していたのですが現状だと難しいようです。
Amazon Qが快適に作業を行えるように
さらにAmazon Qが作業しやすいように、Amazon Qの作業結果を受け入れやすいように環境の整備を行っていくことも重要です。
ここではそういった作業の例をいくつか紹介します。
ガードレールの整備を行う
- git pre-commitでLint／フォーマット／静的解析を行う
- 作業が完了したらdiffを確認して問題がないかなどのチェックを行う
- これもAIにやってもらうのが理想
- 別ウィンドウでAmazon Qを動作させ確認させるなどで実現
ファイルの整理
- 不要なドキュメント、不要なファイルは極力排除する
- ファイルが探しやすいディレクトリ構造にしておく
事前準備などの苦手なことは人間が引き受ける
- Dockerfile、Terraform などのインフラに関するコードは人間が必ずレビューし動作確認する
- 場合によっては人間が全部書いたほうが良いこともある
- 開発環境の初期設定は可能な限り人間があらかじめ実施
- CI/CD環境、デプロイスクリプトなども人間がやったほうが早い
自分がとりあえず採用したワークフローと得られた生産性
自分が現在使っている作業の流れは以下のような流れになります。
| # | ステップ | 具体的な操作 |
|---|---|---|
| 1 | 着手前 | 要件箇条書きを渡して「作業計画書」「ADR」を Q に作成させる |
| 2 | ToDoリストの作成 | 作業計画を元にToDoリストの作成を行ってもらう |
| 3 | コード生成 | ToDoリストに従ってコード生成を進めていく。TDDで極力すすめてもらう |
| 4 | タスク管理 | ToDo リストを Q に更新させる、ToDoリストは定期的に整理を指示する |
| 5 | コンテキスト整理 | 1つの作業完了、もしくはやり取りが増えたら /clear。 |
このフローで、概ね1週間で1-2万行くらいのコード生成ができました。もちろん常にこの結果が得られるとは限らないと思います。あくまで参考情報です。
さらに後半は読まないといけないコードや文書量が増え消費するコンテキストの量が増えていくため、生成速度はだんだん遅くなっていくような状況になりました。
この状態からさらに生産性を上げていくには、例えばAmazon Qを複数起動させることで増やしていくこともできるでしょうが、レビューしたり、人間のほうがボトルネックになっていきそうですね。
スケールの限界と分割戦略
自分がAmazon Qを使っていて、これ以上の規模になると一気に生産性が落ちたり、プロジェクトの進行が著しく遅くなったと感じた基準について紹介します。
ソースコードの行数の上限は約2万行 程度だろうと感じました。可能であれば1万行に達する前に対策を検討するのが良さそうです。対策としてはプロジェクトを分割、またはディレクトリ単位でAmazon Qのプロセスを分けるなどの対策が良さそうでした。ただし、使う言語などによってはディレクトリ分割では分割として認識が弱いようです。例えば、Nodeの場合だとディレクトリよりもパッケージ分割を行うほうが上手く行くようでした。また、分割後は インターフェイス仕様書のようなものを整備し、ソースコードの参照を減らすことでコンテキストの消費を防ぐことも重要でした。
また、個別のファイルについても大きくなりすぎない方が上手く行くようです。例えば、ファイルは最大でも500行程度で分割したほうが上手く編集してくれるようでした。
MCPサーバについて
便利なので導入すると良いかもしれないです。ただし、自分はあまりまだたくさんは導入していないです。
playwrightのMCPサーバは便利でした。これを頻繁に起動すると時間がかかるようになるので要検討だと思います。
Amazon QでMCPを使うには ~/.aws/amazonq/mcp.json に設定を追記すれば利用できます。
例えば、以下のように記述することでplaywrightのMCPサーバを利用できるようになります。
{ "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest" ] } } }
Amazon Qを使っていて遭遇する問題
- Amazon Qを使っているとエラーが表示されることがある
- 稀にエラーが出るようですが、再起動するしかないようです
- モデルを選び直すように指示される
- /modelを入力して別モデルを使う
Amazon Qの入門としておすすめすること
これから試す人は例えば以下のようなことをやってみるとAmazon Qの使い方が何となく分かるのではないでしょうか
- AmazonQ.md に “プロジェクトの開発ルール” の雛形を作成させる
/tools trust-allを実施しても大丈夫な環境(devcontainerなど)を立ち上げ、Hello World アプリを 1 日で作る- 生成されたテスト・ドキュメントの質と開発速度を確認し、チームのベストプラクティスを固める
まとめ
Amazon Q Developerはとても良いツールなので是非皆さんも使ってみてください。
余談
AWSがkiroというAIを活用しているIDEを発表しましたね。
これが採用しているワークフローが自分が構築したワークフローとかなり似ていて
偶然ですが、Amazon Q向けの使い方を自分は意図せずしていたようです。
執筆：@yamashita.tsuyoshi
レビュー：@mizuno.kazuhiro
（Shodoで執筆されました）
