Shift-left with GitHub Amazon Q Developer Project Rules

Most would agree that shift-left is the right thing to do, but actually doing it has historically been painful. The not-so-favorably looked upon policy-as-code initiatives often come with new languages, new tools, and new places developers have to remember to look—so it’s no surprise it doesn’t always stick. In this post, I’ll walk through how GitHub Amazon Q Developer Project Rules make shift-left feel natural by bringing policy-as-context directly into pull requests using simple Markdown files, turning security and compliance into something developers engage with instead of work around.

TL;DR: Policy-as-code has always been hard for most organizations, but for a long time it was the only real way to shift-left. With GitHub Amazon Q Developer Project Rules, we can now shift left using policy-as-context instead—and honestly, life is much better.

What is Shift-Left?

Shift-left is the practice of moving security, compliance, and quality checks earlier in the software development lifecycle—ideally as close to code creation as possible. Instead of discovering issues during late-stage reviews, audits, or post-deployment incidents, teams aim to catch problems during the coding phase.

In theory, this sounds great…in reality, it’s been tough to pull off. Shift-left might be a buzzword, but if security and compliance only show up to review what’s already deployed instead of what’s about to be, teams end up stuck in a loop of rework, delays, and frustratingly slow delivery.

Most organizations that attempt shift-left eventually run into the same obstacles when adopting policy-as-code in their DevSecOps practices:

• Steep learning curves with policy as code (CloudFormation Guard, OPA, Rego, custom DSLs, framework-specific tooling)
• Fragmented tooling across CI, security, and platform teams
• Technical debt for maintaining policies
• Limited participation because policies have generally lived outside of the “everything as code” world

Yet, shift-left is still the right answer to modern security and compliance challenges. The problem hasn’t been the goal—it’s been the method of implementation.

That’s where GitHub Amazon Q with Developer Project Rules fundamentally changes the equation.

Enter GitHub Amazon Q Developer

Amazon Q Developer for GitHub integrates generative AI directly into GitHub issues and pull requests. It acts as an AI-powered development and review agent that can:

• Perform automated code reviews
• Provide contextual feedback directly in PR conversations via comments
• Respect project-specific rules defined in your repository
• Generate code from issues (additional permissions need to be granted)

We have used Amazon Q Developer at Platformr for all our products for the last six months. It has been a game changer in pull requests and code review. Our development team reviews all feedback from Q and engages via comments on the pull requests. The feedback and code summarization is only for the code changes which saves time and improves code quality.

Don’t get me wrong, it doesn’t replace humans—but it dramatically improves signal, consistency, and speed. Additionally, it will not make a person who has no clue what they are doing suddenly brilliant..they still have no clue what they are doing.

Getting Set Up with GitHub Amazon Q Developer

To get started, install the Amazon Q Developer GitHub App from the GitHub Marketplace and grant access to your GitHub organization or selected repositories within the GitHub organization.

During installation:

• Choose which repos Q can access
• Approve permissions for issues, pull requests, and comments

You don’t even need an AWS account to get started during the preview. You can register the app with an AWS account later if you want, but it’s totally optional for now. And if you only enable it on a few repositories to start, no worries—you can always jump back into your GitHub org settings and tweak the app’s access as you go.

Once installed, any applicable repository that has a Pull Request opened on it will have Q automatically conduct a code review. Amazon Q Developer works primarily through:

• Automatic PR reviews (on new or reopened PRs)
  • Any existing PRs can have a review started by just commenting /q review
• Slash commands in comments:
  • /q review
  • /q dev
  • /q help
• Labels (such as Amazon Q development agent) on issues

When a PR is opened, Q can automatically review the code and leave inline comments—just like a human reviewer would. If you respond back to the inline comments, Q will engage you in dialogue. It is really handy to better understand any recommendation.

At Platformr we identified a best practice is to configure requiring all PR conversations to be resolved before merged. This can be set in the repository Settings>Rulesets Branch Rules section.

Amazon Q Developer comments are part of the PR conversation. Requiring all conversations to be resolved ensures developers must explicitly acknowledge or address Q’s feedback, which turns AI review into a real enforcement mechanism—not just suggestions developers ignore and mash the merge button.

Amazon Q Project Rules: The Missing Link for Shift-Left

Amazon Q Developer becomes truly powerful when combined with custom project rules.

What Are Amazon Q Project Rules?

Project rules are Markdown files stored directly in your repository under:

.amazonq/rules/

These files provide explicit guidance to Amazon Q Developer about:

• Coding standards
• Security requirements
• Compliance constraints
• Architectural decisions
• Organizational best practices
• Basically anything you put in there…

When present, Amazon Q automatically uses these rules as context when:

• Reviewing pull requests
• Generating code
• Suggesting changes

No pipelines.

No custom DSLs.

No external policy engines.

Just Markdown…

Personal Note: I did a lot of work on the Guard Rules registry creating rules for AWS CloudFormation Guard. If I had something like this at the time, I would not have done that work.

Why This Is a Breakthrough for Shift-Left

The policy-as-context approach solves many historical policy-as-code problems:

• Low Learning Curve: Markdown is universal. Anyone can read it. Most can write it.
• Policies Live with Code: Rules are versioned, reviewed, and evolved in the same repository as the application.
• Organization-Wide Contribution: Security, platform, and application teams can all contribute rules through normal pull requests. Pretty much you just have to be literate to potentially contribute.
• Immediate Feedback: Policies are enforced during PR review, not hours after deployment.

This is shift-left without friction. Basically if you can write out the rule in text, it can be applied.

Creating Custom Rules: A Practical Guide

Step 1: Create the Rules Directory

In your repository:

.amazonq/rules/

That’s it. No configuration files or service registration required.

Step 2: Organize Rules by Initiative or Policy Domain

Instead of one massive policy file, break rules into focused Markdown documents:

.amazonq/rules/
├── security-baseline.md
├── cdk-typescript-rules.md
├── roberts-rules.md
├── general-coding-standards.md
└── compliance-soc2.md

This keeps rules:

• Easier to review
• Easier to maintain
• Easier for different teams to own

Step 3: Write Clear, Directive Rules

The example below shows how you can very easily create rules files. The file roberts-rules.md contains a very specific naming convention tag rule stated in a simple sentence (no code needed). There is also a detailed rule for AWS SDK clients which demonstrates the flexibility of the rules context files.

Example: roberts-rules.md

# Roberts Rules

## Purpose

Follow best practices from Robert who has rules of order

### Naming conventions

- All AWS resources should include a tag with key "robert" and value "approved"

### AWS Service Clients

All AWS SDK service clients must be configured with retry settings:

- `maxAttempts: 10` - Set maximum retry attempts to 10
- `retryMode: "standard"` - Use standard retry mode for consistent behavior

Example:
const orgClient = new OrganizationsClient({
  ...clientCreds,
  maxAttempts: 10,
  retryMode: "standard"
});

With these rules added, Amazon Q will now factor these rules into:

• PR reviews
• Code suggestions
• Feature generation

When you open a PR, you will see your policies which you expressed as rules being evaluated and Q commenting on them. It is that simple.

Final Thoughts

Shift-left has always been the right goal—but it’s often failed due to complexity and poor user experience. GitHub Amazon Q Developer Project Rules finally make shift-left practical, approachable, and collaborative. It is bringing the shift-left implementation from policy-as-code to policy-as-context which lowers the barrier of adoption.

By combining:

• AI-assisted PR reviews
• Repository-native Markdown rules
• Enforced PR conversation resolution

You get a lightweight but powerful system for embedding security, compliance, and quality directly into everyday development workflows, which about any person can contribute.

Note: If your teams are apprehensive about markdown, it is only because it is new to them. Reassure them that using the absolute basics of Microsoft Word is much harder than working with markdown.

This is one of the most effective shift-left implementations I’ve seen—and it’s only getting better.