Steering files

Steering files are project-level configuration files that guide AI coding assistants with your project's conventions, patterns, and constraints. When an AI assistant reads these files, it generates code that follows your team's standards and Amplify best practices.

Why use steering files

AI assistants work best when they understand your project's context. Without steering files, the assistant may:

• Use outdated API patterns or incorrect import paths
• Generate code that doesn't match your auth/data model conventions
• Miss Amplify-specific patterns like defineAuth(), defineData(), or defineStorage()

Steering files solve this by giving the assistant persistent context about your project.

Kiro steering

Kiro uses steering files to maintain consistency across your project. Create steering rules that describe your Amplify project conventions:

• Data model naming patterns and authorization rules
• Auth configuration preferences (social providers, MFA settings)
• Frontend framework patterns (React hooks, Next.js App Router vs Pages Router)
• Testing conventions

Learn more in the Kiro steering documentation.

CLAUDE.md for Claude Code

If you use Claude Code, create a CLAUDE.md file in your project root. This file is automatically loaded into every conversation.

Example CLAUDE.md for an Amplify project:

# Project conventions

This is an AWS Amplify Gen 2 project using TypeScript.

## Structure
- `amplify/` — Backend resources (auth, data, storage, functions)
- `amplify/data/resource.ts` — Data model schema using `@aws-amplify/backend`
- `amplify/auth/resource.ts` — Auth configuration using `defineAuth()`
- `src/` — Frontend application code

## Amplify patterns
- Use `a.model()` for data models with `.authorization()` chains
- Use `allow.owner()` for user-owned data, `allow.guest()` for public read
- Import client operations from `aws-amplify/api` with `generateClient<Schema>()`
- Use `Amplify.configure(outputs)` with the generated `amplify_outputs.json`

## Testing
- Run `npx ampx sandbox` for local development
- Backend changes auto-deploy on file save during sandbox

Cursor rules

For Cursor, create rules in the .cursor/rules/ directory:

.cursor/
  rules/
    amplify.mdc     # Amplify-specific conventions

Example .cursor/rules/amplify.mdc:

---
description: Amplify Gen 2 conventions
globs: amplify/**/*
---

- Backend resources are defined in `amplify/` using TypeScript
- Data models use `a.schema({})` with `a.model()` definitions
- Authorization uses `.authorization(allow => [...])` chains
- Auth is configured with `defineAuth()` in `amplify/auth/resource.ts`
- Storage uses `defineStorage()` in `amplify/storage/resource.ts`
- Use `@aws-amplify/backend` for backend definitions
- Use `aws-amplify` for frontend client operations

Amazon Q Developer context

Amazon Q Developer supports workspace context through the @workspace command. You can add reference files to help Q Developer understand your Amplify conventions:

• general.md — General Amplify Gen 2 conventions and file structure
• authentication.md — Auth configuration patterns and examples
• modeling-schema.md — Data model schema best practices
• modeling-relationships.md — Data relationship patterns

Download these files and place them in a context/ folder in your project root.

AWS Blocks integration

If your project uses AWS Blocks alongside Amplify, you can guide AI coding assistants to follow the Blocks integration patterns — defining backend capability in aws-blocks/index.ts, authenticating with your Amplify Cognito pool, and calling the generated typed client instead of constructing requests by hand.

Use the official AWS Blocks skill (recommended)

AWS publishes an AWS agent toolkit — official, AWS-supported skills and plugins for AI coding agents — that includes an aws-blocks skill. The skill loads on demand when your task involves AWS Blocks (for example, when your project has an aws-blocks/ directory or imports @aws-blocks packages) and keeps the assistant aligned with the current Blocks APIs and best practices, so you don't have to hand-maintain steering rules.

Install it once for your assistant:

/plugin install aws-core@claude-plugins-official

npx skills add aws/agent-toolkit-for-aws/skills --skill aws-blocks

codex plugin marketplace add aws/agent-toolkit-for-aws

For the full list of tools and setup options, see the AWS agent toolkit repository.

Add project-level rules

Adding AWS Blocks to an existing Amplify project doesn't scaffold an AGENTS.md — create-blocks-app only generates one when you create a standalone Blocks app. So for an Amplify project, the official aws-blocks skill above is the simplest way to keep assistants aligned.

If you prefer file-based rules that live in your repo, add an AGENTS.md (or your tool's steering file — CLAUDE.md, .cursor/rules/, .kiro/steering/) yourself. Rather than copying a list of rules that can drift out of date as the Blocks APIs evolve, point that file at the authoritative sources — the aws-blocks skill and the AGENTS.md that create-blocks-app generates for a standalone Blocks app.

Tips for effective steering

• Be specific about imports — Tell the assistant which packages to import from (@aws-amplify/backend for backend, aws-amplify for frontend)
• Document your auth model — Describe which authorization strategies your app uses (owner-based, group-based, public)
• Include file paths — Reference where backend resources are defined so the assistant edits the right files
• Keep it updated — Update steering files when you add new Amplify features or change conventions