A Hands‑On Review of Amazon Q’s Custom Rules for Shift‑Left Governance

Spoiler: in less than an hour I transformed two plain‑English Markdown files into 22 actionable findings that Amazon Q surfaced directly in VS Code.

Why This Matters

Modern engineering teams already live in their IDEs and CI pipelines; meanwhile security, compliance and architecture guidance too often sits in PDFs or wikis that no one reads until audit time. Amazon Q’s new Custom Context Rules feature collapses that gap by letting you drop Markdown rulebooks into a special folder (.amazonq/rules/). The AI assistant then enforces those rules every time you:

• run q chat from the CLI,
• trigger a pull‑request check, or
• ask the VS Code extension for a code review.

In other words, your policies become a first‑class, executable artifact – just like the infrastructure and application code they protect.

The Setup

1 — A Sample Three‑Tier Terraform Stack

For my demo I spun up a classic three‑tier app in Terraform: VPC, public & private subnets, an ALB, an EC2 web tier, RDS PostgreSQL and a handful of S3 buckets.

2 — Two Markdown Rulebooks

I authored two documents and placed them under best‑app‑ever/.amazonq/rules/:

File	Purpose
well-architected.md	A distilled version of the AWS Well‑Architected Framework. I kept the built‑in five pillars and tagged each bullet with a priority code ([P1], [P2], [P3]).
company-rules.md	EuroFinBank (my fictional FinServ) regulations layered on top – e.g. PSD2, GDPR, DORA, internal tagging standards and sustainability goals.

## Pillar: Operational Excellence
- **[P1]** Perform operations as code.
- **[P1]** Make frequent, small, reversible changes.
...

## Pillar: Governance & Compliance (EuroFinBank)
- **[P1]** Maintain a centralized AWS Landing Zone with guardrails codified via AWS Control Tower & Service Catalog.
- **[P1]** Enforce tagging policies (cost center, data sensitivity, regulatory domain) via Organization SCPs.
- **[P1]** Record & version all IaC in a secure Git repo with restricted merge approvals.

📸 Screenshot 1 (left pane) shows well-architected.md with the familiar blue headings rendered in VS Code.

Running the Review

A. From the CLI

$ q chat "review the code in my current directory recursively and respond with P1 findings only."

Amazon Q parsed both rulebooks, walked the entire Terraform tree and replied with a concise list of Priority‑1 violations:

1. Security Group Configuration: 0.0.0.0/0 ingress for SSH. Violates “Apply security at all layers”.
2. Missing Resource Tagging: No cost‑center or data‑sensitivity tags. Violates EuroFinBank P1 tagging mandate.
3. Plaintext Database Credentials: Environment variables instead of Secrets Manager. Triggers CWE‑798 & Well‑Architected “Protect data at rest and in transit.”
4. CloudTrail Disabled: No org‑wide audit trail. Breaks EuroFinBank traceability requirement.
5. Encryption Not Enabled: RDS, EBS & S3 left unencrypted. Violates both frameworks.

Q suggested a one‑liner fix for every item, including ready‑to‑copy Terraform snippets.

B. Inside VS Code

Open the Command Palette → “Amazon Q: Review Workspace”.

The extension lit up the Problems panel with 99 findings. In the Amazon Q side bar I could drill into:

• Critical (2):
  • CWE‑798 – Hard‑coded credentials (pointing to main.tf line 30).
  • Inadequate error handling detected… – Amazon Q flagged an empty catch {} in a Lambda module.
• High (7) – multiple unencrypted volumes, disabled RDS encryption, etc.
• Medium (13) – readability, maintainability, and naming consistency tips.

📸 Screenshot 3 captures the moment: severity badges, CWE identifiers, quick‑fix icons and even a “Explain” hover action.

A single click on Explain opened a chat tab with an in‑context rationale and step‑by‑step remediation guidance – all without leaving the editor. Talk about developer ergonomics!

What I Learned (Key Take‑Aways)

Lesson	Why It’s Interesting
Policies as Code ≠ Code as Law	You don’t need to translate prose into OPA or Sentinel on day one. Amazon Q happily ingests plain English. Start simple, iterate.
Priority Tags Drive Focus	The [P1]/[P2]/[P3] convention lets leadership decide what’s non‑negotiable. Engineers see only P1 blockers when they’re in a hurry, but can expand to best practice tips later.
Shift‑Left Compliance Is Now Drag‑and‑Drop	Placing a new Markdown file in .amazonq/rules/ is literally all it takes to roll out a fresh policy across every repo. No pipeline re‑wiring required.
Human‑Readable, Audit‑Friendly	Auditors love narrative. With these files committed to Git, you have an immutable timeline of when each rule was introduced or updated – perfect for SOC 2 change management evidence.
Extensible to CI/CD	The same CLI command can run in GitHub Actions, CodeBuild or Jenkins, turning pull requests red if a new commit regresses on P1 rules.
Security & Sustainability Under One Roof	My EuroFinBank doc even includes sustainability pillars (e.g., “Prefer Graviton processors”). Amazon Q doesn’t care – if it’s a bullet, it’s a rule.

Final Thoughts

Amazon Q’s Custom Context Rules feel like linting for your entire operating model. The barrier to entry is almost comically low – just write Markdown. Yet the payoff is huge: unified guidance, faster reviews, happier auditors and, ultimately, safer releases.

If you already use the Well‑Architected Framework, start by pasting your favorite pillar into a rule file. If you’re in a regulated industry, carve‑out your compliance handbook section‑by‑section. Then let Amazon Q do the policing so your engineers can stay focused on shipping value.

Happy (and compliant) building!