# How to Configure AI-DLC Rule Loading for Amazon Q IDE: Complete Setup Guide

> Master AI-DLC rule loading for Amazon Q IDE. Follow this complete setup guide to configure rules for seamless AI-powered development within your existing workflows.

- Repository: [Amazon Web Services - Labs/aidlc-workflows](https://github.com/awslabs/aidlc-workflows)
- Tags: how-to-guide
- Published: 2026-05-09

---

**To configure AI-DLC rule loading for Amazon Q IDE, create a `.amazonq/rules/` directory in your project root, copy the core rule set into it, and place the detailed rule specifications in `.amazonq/aws-aidlc-rule-details/` so Amazon Q Developer can discover them automatically.**

Amazon Q Developer discovers AI-DLC (AI-Driven Development Life Cycle) workflow rules from markdown files located in specific project-level directories. This configuration enables the adaptive three-phase AI-DLC workflow (Inception → Construction → Operations) within the IDE, using the official rule sets provided by the `awslabs/aidlc-workflows` repository.

## Understanding the AI-DLC Directory Architecture

The AI-DLC rule loading mechanism depends on a strict three-part directory structure. Amazon Q treats `.amazonq/` as the **project-level context** folder for all rule configurations.

The architecture consists of:

- **`.amazonq/`** – A hidden directory in the project root that signals to Amazon Q where to look for context-specific rules.
- **`.amazonq/rules/`** – Contains one or more rule collections, such as `aws-aidlc-rules/`. The IDE scans this subdirectory at startup to discover available rule sets.
- **`.amazonq/aws-aidlc-rule-details/`** – Holds the detailed rule specifications referenced by the core workflow. Note that this folder lacks a leading dot and must be placed directly under `.amazonq/` as a sibling to the `rules/` folder.

As implemented in `awslabs/aidlc-workflows`, the core workflow definition in [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) resolves references to detailed specifications using paths like `.amazonq/aws-aidlc-rule-details/`. Because Amazon Q does not use a leading dot for the details folder, maintaining the exact naming is critical to avoid missing rule loads.

## Step-by-Step Configuration

Follow these steps to configure the rule directories in your project root.

### 1. Create the Rules Directory

Create the hidden `.amazonq` folder and the `rules` subdirectory:

```bash
mkdir -p .amazonq/rules

```

This establishes the project-level context that Amazon Q monitors for rule changes.

### 2. Copy Core AI-DLC Rules

Copy the core rule collection from your downloaded AI-DLC package into the rules folder:

```bash
cp -R ~/Downloads/aidlc-rules/aws-aidlc-rules .amazonq/rules/

```

This places the workflow definitions—including [`core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/core-workflow.md)—where Amazon Q can discover them during IDE startup.

### 3. Copy Detailed Rule Specifications

Copy the detailed rule directory into the `.amazonq/` folder:

```bash
cp -R ~/Downloads/aidlc-rules/aws-aidlc-rule-details .amazonq/

```

The exact naming `aws-aidlc-rule-details` (without a leading dot) is critical. Amazon Q resolves relative paths from the core rules to this directory, and a mismatch will cause missing rule loads.

## Platform-Specific Setup Commands

The [`README.md`](https://github.com/awslabs/aidlc-workflows/blob/main/README.md) in the `awslabs/aidlc-workflows` repository provides platform-specific commands for creating these directories and copying files.

### macOS and Linux

Use the following Bash commands to set up the directory structure:

```bash

# Create the hidden Amazon Q rules folder

mkdir -p .amazonq/rules

# Copy the core AI-DLC rule collection into the rules folder

cp -R ~/Downloads/aidlc-rules/aws-aidlc-rules .amazonq/rules/

# Copy the detailed rule specifications next to the rules folder

cp -R ~/Downloads/aidlc-rules/aws-aidlc-rule-details .amazonq/

```

### Windows PowerShell

For PowerShell environments, use these commands:

```powershell

# Create the hidden folder

New-Item -ItemType Directory -Force -Path ".amazonq\rules"

# Copy core rules

Copy-Item "$env:USERPROFILE\Downloads\aidlc-rules\aws-aidlc-rules" ".amazonq\rules\"

# Copy detailed rule specs

Copy-Item "$env:USERPROFILE\Downloads\aidlc-rules\aws-aidlc-rule-details" ".amazonq\"

```

### Windows Command Prompt

For CMD environments, use `xcopy` to preserve directory structure:

```cmd
mkdir .amazonq\rules
xcopy %USERPROFILE%\Downloads\aidlc-rules\aws-aidlc-rules .amazonq\rules\aws-aidlc-rules\ /E /I
xcopy %USERPROFILE%\Downloads\aidlc-rules\aws-aidlc-rule-details .amazonq\aws-aidlc-rule-details\ /E /I

```

## Verifying Rule Loading in Amazon Q IDE

After configuring the directories, verify that Amazon Q correctly loaded the AI-DLC rules:

1. Open the **Amazon Q chat window** in your IDE.
2. Click the **Rules** button located in the lower-right corner.
3. Confirm that entries for `.amazonq/rules/aws-aidlc-rules` appear in the rule list.

The [`README.md`](https://github.com/awslabs/aidlc-workflows/blob/main/README.md) (lines 154-156) documents this verification flow. You can also compare your results against the reference screenshot in `assets/images/q-ide-aidlc-rules-loaded.png` to ensure the rules display correctly.

## Key Files and References

Understanding these source files helps troubleshoot configuration issues:

- **[`README.md`](https://github.com/awslabs/aidlc-workflows/blob/main/README.md)** – Contains the platform-specific setup instructions (lines 121-140) and the architectural overview (lines 726-730) explaining the relationship between the rules folder and the details folder.
- **[`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md)** – The core workflow definition loaded by Amazon Q that references detailed specifications.
- **`aidlc-rules/aws-aidlc-rule-details/`** – The detailed rule specifications referenced by the core workflow during execution.

## Summary

- **Create** a `.amazonq/rules/` directory in your project root to store core AI-DLC rules.
- **Copy** detailed rule specifications to `.amazonq/aws-aidlc-rule-details/` (note the missing leading dot on the folder name).
- **Verify** loading by opening the Amazon Q chat window, clicking **Rules**, and confirming the `aws-aidlc-rules` entry appears.
- **Reference** the `awslabs/aidlc-workflows` repository for the latest rule definitions and platform-specific commands.

## Frequently Asked Questions

### What is the exact folder structure required for AI-DLC rules in Amazon Q?

Amazon Q requires a `.amazonq/` directory in the project root containing two subdirectories: `rules/` (for core rule collections) and `aws-aidlc-rule-details/` (for detailed specifications). The `rules/` folder contains markdown files like [`core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/core-workflow.md), while the `aws-aidlc-rule-details/` folder houses the granular rule definitions referenced by those core files.

### Why does the aws-aidlc-rule-details folder not have a leading dot?

The `aws-aidlc-rule-details` folder intentionally omits the leading dot used by `.amazonq/` because it is referenced by relative path from the core workflow rules. Amazon Q resolves these references during execution, and the path resolution expects the details folder to be a visible subdirectory of `.amazonq/` rather than a hidden one. Using a dot prefix would break the reference resolution mechanism.

### How do I verify that Amazon Q IDE loaded the AI-DLC rules correctly?

Open the Amazon Q chat panel and click the **Rules** button in the lower-right corner. If configured correctly, you will see entries for `.amazonq/rules/aws-aidlc-rules` in the displayed list. This verification step is documented in the repository's [`README.md`](https://github.com/awslabs/aidlc-workflows/blob/main/README.md) (lines 154-156), which also provides a reference screenshot showing successful rule loading.

### Which file contains the core workflow definition that references the detailed rules?

The file [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) contains the core AI-DLC workflow definition. This markdown file is loaded by Amazon Q and contains references to detailed specifications stored in `aws-aidlc-rule-details/`. The IDE resolves these relative paths during the rule loading process to construct the complete workflow context.