Embedded Instructions

Using embedded instructions to precisely control content generation

Embedded instructions allow you to precisely control what content Amazon Q generates in your README files. They are HTML comments with specific instructions that tell Amazon Q exactly what content to generate and where.

Instruction Syntax

Embedded instructions use HTML comments with a specific prefix:

<!-- qmims: Your instruction here -->

Amazon Q will process these instructions and replace them with generated content.

Note

The instructions are removed from the final document and replaced with the generated content.

Instruction Placement

Instructions should be placed at the exact location where you want the generated content to appear. For example:

# Project Title

<!-- qmims: Generate a concise project overview based on the codebase -->

## Features

<!-- qmims: List the main features of the project based on the code structure -->

When you run qmims edit, the instructions will be replaced with the generated content:

# Project Title

This project is a Node.js library for processing CSV files with support for streaming, transformation, and validation. It provides a simple API for reading, writing, and manipulating CSV data.

## Features

- Fast streaming CSV parsing and generation
- Data transformation with customizable pipelines
- Schema validation for CSV data
- Support for various CSV dialects and formats
- Automatic type detection and conversion

Instruction Types

You can use different types of instructions:

1. Generate content

<!-- qmims: Generate a list of API endpoints from the code -->

2. Update existing content

<!-- qmims: Update this installation section based on the package.json file -->

3. Add specific sections

<!-- qmims: Add a "Contributing" section with guidelines -->

4. Format content

<!-- qmims: Format this API documentation as a table -->

Processing Instructions

To process embedded instructions:

# For existing README files
qmims edit

# For generating new README files with instructions
qmims generate --mode instruct

Writing Effective Instructions

To get the best results from Amazon Q, follow these guidelines for writing instructions:

Be Specific

❌ Less Effective:

<!-- qmims: Write about installation -->

✅ More Effective:

<!-- qmims: Provide step-by-step installation instructions using npm, including any prerequisites and verification steps -->

Provide Context

❌ Less Effective:

<!-- qmims: List the features -->

✅ More Effective:

<!-- qmims: List the main features of this authentication library based on the code in the src/auth directory -->

Specify Format

❌ Less Effective:

<!-- qmims: Document the API -->

✅ More Effective:

<!-- qmims: Document the API as a table with columns for Function Name, Parameters, Return Value, and Description -->

Tip

You can use the --dry-run option to preview the changes without modifying the file:

qmims edit --dry-run

Example Use Cases

Updating Installation Instructions

## Installation

<!-- qmims: Update the installation instructions based on the latest package.json, including all required dependencies and peer dependencies -->

Generating API Documentation

## API Reference

<!-- qmims: Generate comprehensive API documentation for all exported functions in src/api.js, including parameters, return values, and examples -->

Creating Usage Examples

## Usage Examples

<!-- qmims: Create 3-5 practical usage examples showing common use cases for this library, with code snippets and explanations -->