概要
Amazon Q CLIでコンテキストを設定する方法について、公式仕様に基づいて説明します。
設定方法の種類
- 1. プロジェクトルール（自動適用）
- 2. 手動コンテキスト追加
- 3. コンテキストフック（自動実行）
- 4. プロファイル管理
詳細設定方法
1. プロジェクトルール（推奨・自動適用）
プロジェクトルートに .amazonq/rules/ ディレクトリを作成し、Markdownファイルでルールを定義します。 これらのルールは、プロジェクト内でAmazon Q を使用する際に自動的に適用されます。
ディレクトリ構造
project-root/
├── .amazonq/
│ └── rules/
│ ├── coding-standards.md
│ ├── security-rules.md
│ ├── aws-guidelines.md
│ └── project-context.md
└── ...
coding-standards.md の例
# コーディング規約
## TypeScript規約
- すべてのTypeScriptコードでstrict modeを使用する
- 型定義を明示的に記述する
- ESLintとPrettierの設定に従う
- 関数には必ずJSDocコメントを記述する
## テスト規約
- Jestを使用した単体テストを必須とする
- テストカバレッジは80%以上を維持する
- テストファイルは `*.test.ts` または `*.spec.ts` の命名規則に従う
## エラーハンドリング
- すべての非同期処理でtry-catchを使用する
- カスタムエラークラスを定義して使用する
- ログ出力は構造化ログ形式で行う
security-rules.md の例
# セキュリティガイドライン
## AWS セキュリティ
- すべてのS3バケットで暗号化を有効にする
- S3バケットでSSLを強制し、パブリックアクセスをブロックする
- DynamoDBテーブルで暗号化を有効にする
- SNSトピックで暗号化を有効にしSSLを強制する
- SQSキューでSSLを強制する
## 認証・認可
- 環境変数に機密情報を直接記述しない
- AWS Secrets ManagerまたはParameter Storeを使用する
- IAMロールは最小権限の原則に従う
## コード内セキュリティ
- ハードコードされた認証情報を使用しない
- 入力値の検証を必ず行う
- SQLインジェクション対策を実装する
project-context.md の例
# プロジェクトコンテキスト
## プロジェクト概要
- プロジェクト名: MyServerlessApp
- 環境: Development/Staging/Production
- 主要言語: TypeScript
- フレームワーク: Serverless Framework
## アーキテクチャ
- フロントエンド: React (TypeScript)
- バックエンド: AWS Lambda (Node.js)
- データベース: DynamoDB
- ストレージ: S3
- 認証: Cognito
- API: API Gateway
## デプロイメント
- CI/CD: GitHub Actions
- インフラ: AWS CDK
- 環境管理: AWS Parameter Store
- モニタリング: CloudWatch
## 開発環境
- Node.js: v18.x
- パッケージマネージャー: npm
- テストフレームワーク: Jest
- リンター: ESLint + Prettier
2. 手動コンテキスト追加
Q CLI内で /context add コマンドを使用して、任意のMarkdownファイルをコンテキストに追加できます。
基本的な使用方法
q chat
# 単一ファイルを追加
> /context add README.md
# 複数ファイルを一度に追加
> /context add docs/*.md
# グローバルコンテキスト（全プロファイルで共有）に追加
> /context add --global coding-standards.md
# 現在のコンテキストを確認
> /context show
# コンテキストから削除
> /context rm README.md
# すべてのコンテキストをクリア
> /context clear
3. コンテキストフック（自動実行）
コマンドを自動実行してその結果をコンテキストに含める機能です。
フックの種類
- conversation_start: 会話開始時に1回実行
- per_prompt: 各プロンプトごとに実行
設定例
q chat
# Git状態を各プロンプトで自動取得
> /context hooks add git-status --trigger per_prompt --command "git status --short"
# プロジェクト情報を会話開始時に取得
> /context hooks add project-info --trigger conversation_start --command "echo 'Project: '$(basename $(pwd))"
# 現在のAWSプロファイルを表示
> /context hooks add aws-profile --trigger conversation_start --command "aws configure list"
# フック一覧を確認
> /context hooks
# フックを無効化
> /context hooks disable git-status
# フックを削除
> /context hooks rm git-status
4. プロファイル管理
異なるプロジェクトや役割に応じてコンテキストセットを切り替えられます。
プロファイル操作
q chat
# 現在のプロファイル確認
> /profile
# 新しいプロファイル作成
> /profile create backend-dev
> /profile create frontend-dev
> /profile create devops
# プロファイル切り替え
> /profile set backend-dev
# プロファイル固有のコンテキスト追加
> /context add backend-guidelines.md
> /context add api-documentation.md
実践的な使用例
プロジェクト初期設定
# 1. プロジェクトルールディレクトリを作成
mkdir -p .amazonq/rules
# 2. 基本的なルールファイルを作成
touch .amazonq/rules/coding-standards.md
touch .amazonq/rules/security-rules.md
touch .amazonq/rules/project-context.md
# 3. Q CLIでプロファイル作成
q chat
> /profile create myproject
# 4. 有用なコンテキストフックを設定
> /context hooks add git-status --trigger per_prompt --command "git status --short"
> /context hooks add aws-profile --trigger conversation_start --command "aws configure list"
開発チーム向け設定例
# チーム共通のグローバルコンテキスト
> /context add --global team-coding-standards.md
> /context add --global security-guidelines.md
# プロジェクト固有のコンテキスト
> /context add project-architecture.md
> /context add api-specifications.md
質問例（コンテキスト適用後）
"このプロジェクトの規約に従ってLambda関数を作成して"
"セキュリティガイドラインに準拠したS3バケット設定を教えて"
"現在のGit状態を考慮してデプロイ手順を説明して"
設定ファイルの場所
プロジェクトルール（自動適用）
project-root/.amazonq/rules/*.md
プロファイル設定
~/.aws/amazonq/profiles/profile-name/context.json
グローバル設定
~/.aws/amazonq/global_context.json
注意事項とベストプラクティス
セキュリティ
- プロジェクトルールファイルに機密情報を含めない
- コンテキストフックで認証情報を出力するコマンドを避ける
.amazonq/ディレクトリをバージョン管理に含める（ルールファイルのみ）
パフォーマンス
- コンテキストフックのコマンドは5秒でタイムアウト
- フック出力は10KB制限
- 不要なフックは無効化する
チーム開発
- プロジェクトルールをGitで共有
- チーム共通のグローバルコンテキストを設定
- プロファイル命名規則を統一
トラブルシューティング
プロジェクトルールが適用されない
# ディレクトリ構造を確認
ls -la .amazonq/rules/
# ファイル内容を確認
cat .amazonq/rules/coding-standards.md
コンテキストフックが動作しない
q chat
> /context hooks
> /context hooks enable hook-name
プロファイルが見つからない
q chat
> /profile
> /profile create new-profile-name
コメント