Amazon Q Developerのコンテキストフックでプロジェクトの設計書をコンテキストに追加する

こんにちは。
アプリケーションサービス部、DevOps担当の兼安です。

今回は、Amazon Q Developerのコンテキストフックを使用して、プロジェクトの設計書をコンテキストに追加してみようと思います。

本記事のターゲット
本記事の検証環境
コンテキストとは
Amazon Q Developerのプロファイル
Amazon Q Developerのコンテキストフック
rulesもコンテキストである
まとめ
[補足]Kiroにおけるコンテキストの管理
2025年8月5日追記

本記事のターゲット

本記事は、Amazon Q Developerを使用したVibe Coding（＝自然言語を用いてAIにコードを書かせる開発手法）に興味がある方を対象としています。
本記事では、生成AIツールにAmazon Q Developerを使用していますが、コンテキストの概念については他のツールでも転用できる知識と思いますので、よろしければご覧ください。

本記事の検証環境

本記事の検証環境は以下の通りです。

Amazon Q Developer CLI 1.12.6
macOS Sequoia 15.5

では、早速始めていきましょう。

コンテキストとは

コンテキストとは、日本語で「文脈」や「背景」と訳されます。
AIにおいては、AIが何かを判断したり、次の行動を決定したりする際に考慮する、状況や背景、前提となるあらゆる情報を指します。
なので設計書をコンテキストに追加することで、AIはプロジェクトの目的や要件をより深く理解し、より適切なコードを生成できるようになります。

Amazon Q Developerのプロファイル

Amazon Q Developerには、プロファイルと言う概念があります。
AWS CLIを使用された方は、ご存知かもしれません。

以下の、公式ドキュメントにある通り、Amazon Q Developerはプロファイルを作成して切り替えることができます。

docs.aws.amazon.com

プロファイルについて、特に何も設定していなければ、defaultというプロファイルが使用されます。
これも、AWS CLIと同じですね。

q chat
> /profile list


* default

プロファイルを追加し、切り替えるには以下のコマンドを使用します。

q chat

# プロファイルの作成
> /profile create dev


Created profile: dev

# プロファイルの作成後にプロファイルの一覧をもう一度確認
> /profile list


* default
  dev

# プロファイルの切り替え
> /profile set dev


Switched to profile: dev


[dev] > /profile list


  default
* dev

Amazon Q Developerのコンテキストフック

Amazon Q Developerでは、コンテキストを追加することができます。
コンテキストを追加するには、コマンドを使うのが基本です。

q chat
> /context add <ファイルのパス>

これを自動で行うのが、コンテキストフックです。
詳細は先ほどと同じく、公式ドキュメントにあります。

docs.aws.amazon.com

私は、Amazon Q Developerを開始する際に、プロジェクトの設計書を自動でコンテキストに追加したいのと、その設定をはっきりとファイルに残しておきたいので、そこだけ取り上げさせていただきます。

コンテキストフックの設定は、グローバルもしくはプロファイルごとに設定できます。
グローバルは安易に使いたくないので、今回はプロファイルごとの方を使用します。

私は、自動つまり特になにも指定しなくても自然に設計書をコンテキストに追加したいので、デフォルトのプロファイルにコンテキストフックを追加します。
デフォルトのプロファイルを設定する場合は、以下のファイルに設定を記述します。

~/.aws/amazonq/profiles/default/default.json

設定内容は、以下のようにします。

{
    "paths": [
        "docs/**/*.md"
    ],
    "hooks": {}
}

docs/**/*.mdと指定しました。
これで、プロジェクトのdocsディレクトリ以下のMarkdownファイルが、コンテキストに追加されます。
サンプルとして、以下のような構成を用意しました。
docsディレクトリ以下に、設計書のMarkdownファイルを配置しています。
以下のような構成の場合、docs/naming-conventions.mdとdocs/product-overview.mdがコンテキストに追加されます。
なお、以下のディレクトリ構成は私の検証用プロジェクトのものなので、ベストプラクティスとかでは一切ないのでご注意ください。

project-root/
├── .amazonq/
│   └── rules/
│       └── rules.md
├── docs/
│   ├── naming-conventions.md
│   └── product-overview.md
├── src/
│   └── ...

コンテキストを読み込んだか確認

では、Visual Studio Codeを起動して、Amazon Q Developer CLIのチャットを起動して、コンテキストが読み込まれたか確認してみます。
コンテキストの確認は、/context showコマンドを使用します。

q chat
> /context show

🌍 global:
    .amazonq/rules/**/*.md (1 match)
    README.md (1 match)
    AmazonQ.md

👤 profile (default):
    docs/**/*.md (2 matches)

4 matched files in use:
🌍 <プロジェクトルートへのパス>/.amazonq/rules/rules.md (~40 tkns)
🌍 <プロジェクトルートへのパス>/README.md (~1810 tkns)
👤 <プロジェクトルートへのパス>/docs/naming-conventions.md (~90 tkns)
👤 <プロジェクトルートへのパス>/docs/product-overview.md (~610 tkns)

Total: ~2550 tokens

実際には<プロジェクトルートへのパス>の部分には、プロジェクトのルートディレクトリのパスが表示されます。
設計書がコンテキストに追加されていることが確認できました。
2つの設計書がコンテキストに追加されていることがわかります。

Amazon Q Developerが自動でコンテキストに追加するファイル群

もう一つ注目すべきなのは、この部分です。

🌍 global:
    .amazonq/rules/**/*.md (1 match)
    README.md (1 match)
    AmazonQ.md

Amazon Q Developerは、この3種類のパスを見にいき、該当するファイルがあれば特に何も設定しなくてもコンテキストに追加します。
GitHubにあるAmazon Q Developer CLIのソースでもこれが確認できます。
（2025年7月22日現在の情報です）

別のプロジェクトを開いてみた場合の挙動

今回はコンテキストフックでdocs/**/*.mdを指定しているので、別のプロジェクトを開いてみた場合、そのプロジェクトのdocsディレクトリ以下にMarkdownファイルがあれば、コンテキストに追加されます。
以下のような感じです。
（こちらのプロジェクトのディレクトリ構成も、ベストプラクティスとかでは一切ないのでご注意ください）

q chat
> /context show


🌍 global:
    .amazonq/rules/**/*.md
    README.md (1 match)
    AmazonQ.md

👤 profile (default):
    docs/**/*.md (10 matches)

11 matched files in use:
🌍 /<プロジェクトルートへのパス>/README.md (~620 tkns)
👤 /<プロジェクトルートへのパス>/docs/adr/ADR-20240805-<ADRのタイトル>.md (~700 tkns)
👤 /<プロジェクトルートへのパス>/docs/adr/ADR-20250701-<ADRのタイトル>.md (~460 tkns)
👤 /<プロジェクトルートへのパス>/docs/adr/ADR-20240607-<ADRのタイトル>.md (~270 tkns)
👤 /<プロジェクトルートへのパス>/docs/adr/ADR-20240424-<ADRのタイトル>.md (~610 tkns)
👤 /<プロジェクトルートへのパス>/docs/database_design.md (~1130 tkns)

別のプロジェクトを開いたら、そのプロジェクトの設計書がコンテキストに追加されていることがわかります。

rulesもコンテキストである

最後に、context showした結果をもう一度見てみましょう。

q chat
> /context show

🌍 global:
    .amazonq/rules/**/*.md (1 match)
    README.md (1 match)
    AmazonQ.md

👤 profile (default):
    docs/**/*.md (2 matches)

4 matched files in use:
🌍 <プロジェクトルートへのパス>/.amazonq/rules/rules.md (~40 tkns)
🌍 <プロジェクトルートへのパス>/README.md (~1810 tkns)
👤 <プロジェクトルートへのパス>/docs/naming-conventions.md (~90 tkns)
👤 <プロジェクトルートへのパス>/docs/product-overview.md (~610 tkns)

Total: ~2550 tokens

/context showした結果から、globalとprofileの違いがありますが、rules配下のファイルもコンテキストとして扱われていることがわかります。
Amazon Q Developerでは、rulesはそこにあれば自動でコンテキストに追加される場所ですね。
rulesという名前からして特別な意味がありそうに思えますが、ただの場所だと思っておいて問題ないと思います。

まとめ

Amazon Q Developerのコンテキストフックを使用すれば、自動でコンテキストを追加することができます。
コンテキストフックでdocs/**/*.mdを指定し、プロジェクトでdocsディレクトリ以下に設計書を配置することで、設計書を自動でコンテキストに追加できます。
docs/**/*.mdのようにワイルドカードを使用することで、プロジェクトごとに異なる設計書の構成にも対応できるでしょう。

今回は以上です。
ありがとうございました。

[補足]Kiroにおけるコンテキストの管理

本記事の執筆時点（2025年7月22日）では、私の方では本記事で書いてある設定内容が、KiroのViveとSpecに有効かどうかは確認できませんでした。
現状、Kiroの場合はコンテキストの管理はステアリングを使用する設計思想のようです。
Kiroはまだプレビュー版なので、これから変わるかもしれませんし、私が調べきれていないだけかもしれません。
このあたりは分かり次第、別記事でフォローアップしたいと思います。

2025年8月5日追記

Amazon Q Developer のバージョン1.13.0 より後発のバージョンの場合、この記事の設定を行なってq chatを実行した場合、以下のメッセージが表示されることを確認しました。

Legacy profiles detected. Would you like to migrate them?

Yesと入力すると、.amazonq/agents/default.jsonという設定ファイルができます。
バージョン1.13.0 より後発の場合、この設定ファイルでコンテキストなどを管理していくのが正しい可能性があるので、分かり次第別記事にまとめようと思います。