NAME
.amazonq/rules/*.md — instruction file for Amazon Q Developer
SYNOPSIS
.amazonq/rules/
METADATA
DESCRIPTION
`.amazonq/rules/*.md` are Markdown instruction files for Amazon Q Developer, AWS's AI coding assistant available in VS Code, JetBrains, and the AWS Console. Rules follow the familiar frontmatter-based activation pattern: `alwaysApply` for always-on rules, `globs` for file-pattern activation, or manual reference.
The rules directory lives at `.amazonq/rules/` in the project root. This is separate from the `.aws/` directory used for AWS CLI configuration. Rules are committed to version control and shared with the team.
Amazon Q Developer's rule system is designed for the chat and agent features. The format closely mirrors Cursor rules and Roo Code rules, using the same frontmatter fields (description, alwaysApply, globs), making cross-tool migration straightforward.
STRUCTURE
ANNOTATED EXAMPLE
1---
2description: "AWS CDK infrastructure conventions"
3alwaysApply: false
4globs:
5 - "infra/**/*.ts"
6 - "lib/stacks/**"
7---
8
9# CDK Conventions
10
11## Stack Structure
12- One stack per service domain
13- Use L2 constructs when available, L1 only when necessary
14- Stack props interface for all configurable values
15
16## Naming
17- Stack names: PascalCase with environment suffix (e.g., ApiStackProd)
18- Construct IDs: PascalCase, descriptive (e.g., UserTable, ApiGateway)
19- Physical names: kebab-case with project prefix
20
21## Security
22- Never hardcode secrets — use SSM Parameter Store or Secrets Manager
23- Least-privilege IAM policies — no Action: "*"
24- Enable encryption at rest for all storage constructs
25
26## Testing
27- Snapshot tests for all stacks
28- Fine-grained assertions for security-critical resources
29- Use `cdk synth` to verify templates compile
30
31---
32
33## Example: Always-on rule (.amazonq/rules/general.md)
34
35```markdown
36---
37description: "General coding standards"
38alwaysApply: true
39---
40
41# Standards
42- TypeScript strict mode
43- Use ESM imports
44- Prefer async/await over raw Promises
45```
COMMON MISTAKES
Amazon Q Developer looks specifically in the `.amazonq/rules/` directory. The `.aws/` directory is for AWS CLI credentials and config, not Q Developer rules.
Amazon Q Developer's rule system is designed for the chat and autonomous agent features. Inline code completions (formerly CodeWhisperer) use a separate, more constrained context.
Amazon Q Developer scans for files with the .md extension. Other file types (.txt, .yaml, .json) in the rules directory are ignored.