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

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 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:

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:

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

This places the workflow definitions—including 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:

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 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:

# 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:

# 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:

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 (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 – 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 – 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, 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}