Kiro Steering Files vs AGENTS.md vs CLAUDE.md: The Complete 2026 Comparison

Three AI instruction systems. One codebase. This is where most teams get confused.

AWS Kiro launched in 2026 with a purpose-built instruction layer called steering files. Claude Code has had CLAUDE.md since 2024. AGENTS.md has quietly become the universal cross-tool standard adopted by nearly every major AI coding tool. If your team uses more than one tool — or is evaluating Kiro alongside what you already have — you need to understand how these three systems differ and where they overlap.

We analyzed Kiro’s steering file specification, Claude Code’s CLAUDE.md behavior, and the AGENTS.md standard across six major tools to produce this comparison. Here is what we found.

Quick Verdict

Use Kiro steering files when you want fine-grained control over which rules activate for which file types, or when you need to reference live workspace files inside your instructions.

Use AGENTS.md when your team uses multiple AI tools and needs one instruction file that works everywhere — Claude Code, GitHub Copilot, Cursor, Windsurf, Gemini CLI, OpenAI Codex, and Kiro all read it.

Use CLAUDE.md when you are working exclusively in Claude Code and want advanced features: hierarchical loading, @import directives for modular files, skill definitions, and hook references.

The practical answer for most teams: maintain all three. It sounds like overhead, but there is significant overlap — your AGENTS.md content can live inside a Kiro steering file, and your CLAUDE.md imports can pull from the same source. We cover this in the “Running Multiple Systems Together” section below.

Kiro Steering Files: Deep Dive

Kiro places its steering files in .kiro/steering/ within the workspace. For rules that apply across all projects, use ~/.kiro/steering/ as the global location.

Each steering file is a Markdown file with optional YAML frontmatter. The frontmatter controls when the file is included. Without frontmatter, the file defaults to always inclusion.

The Four Inclusion Modes

always — Include in every interaction (default)

---
inclusion: always
---

# Project Conventions

Always use TypeScript strict mode. Never use `any`.
Run `npm test` before marking any task complete.

conditional — Triggered by file patterns

---
inclusion: conditional
fileMatch:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

# Testing Rules

Use Vitest for all new tests. Describe blocks should match the module name.
Mock external HTTP calls with `vi.fn()`. Never hit real APIs in tests.

When the agent is working with files that match the fileMatch glob, this steering file is automatically included. When it is not, it is omitted — keeping context lean.

manual — Referenced on demand

---
inclusion: manual
---

# Database Migration Runbook

Step 1: Back up the target table before running any migration.
Step 2: Test migration script against staging data snapshot.
Step 3: ...

Reference this file in chat with #steering-file-name (the filename without extension). Use manual mode for detailed runbooks or checklists that are only needed in specific sessions.

auto — AI decides based on description

---
inclusion: auto
description: "Detailed rules for writing and maintaining API documentation with OpenAPI 3.1 schema."
---

# API Documentation Standards

All endpoints require OpenAPI annotations. Use $ref for shared schemas.

With auto inclusion, the Kiro agent reads the description field and decides whether the file is relevant to the current task. No manual triggering required — but the decision depends on Kiro’s judgment.

Referencing Live Files

Kiro steering files support #[[file:path]] syntax to embed live workspace content:

---
inclusion: always
---

Current database schema:
#[[file:prisma/schema.prisma]]

Follow the naming conventions in this schema for all new models.

This is not a static copy. Kiro fetches the referenced file’s current contents at the time of each interaction. Your steering file stays accurate as the schema evolves without manual updates.

AGENTS.md Compatibility

Kiro natively reads AGENTS.md files placed in the workspace root or within .kiro/steering/. When Kiro reads an AGENTS.md file, it applies always inclusion — there is no frontmatter to add, and none is needed. If you already have an AGENTS.md, Kiro picks it up with zero configuration changes.

AGENTS.md: The Universal Standard

AGENTS.md was not designed by any single company. It emerged as the convention that multiple AI tools converged on independently, and is now formally supported by:

• Claude Code (Anthropic)
• GitHub Copilot (Microsoft)
• Cursor
• Windsurf (Codeium)
• Gemini CLI (Google)
• OpenAI Codex
• Kiro (AWS)
• OpenCode

The format is intentionally minimal: plain Markdown, no frontmatter, no special syntax. It lives in the project root and is always included when the tool activates. There is no conditional logic, no per-file targeting, no import system.

# AGENTS.md

## Commands

```bash
npm ci          # Install dependencies
npm test        # Run full test suite
npm run lint    # ESLint + Prettier check

Boundaries

Do not modify src/generated/ — these files are auto-generated by the build. Do not run database migrations without explicit instruction.

Conventions

• All React components live in src/components/
• API routes use the pattern src/routes/[resource].ts
• Error classes extend BaseError from src/lib/errors.ts

The value proposition is universal compatibility. One file, seven tools, consistent agent behavior regardless of which tool a team member is using.

The limitation is inflexibility. You cannot scope rules to file types, reference live workspace content, or trigger files on demand.

## CLAUDE.md: Claude Code's Native Format

CLAUDE.md is Claude Code's instruction file. It supports every AGENTS.md feature, plus a set of Claude-specific capabilities that have no equivalent in the other formats.

**Hierarchical loading:** Claude Code reads CLAUDE.md from multiple locations in order of specificity:

1. `~/.claude/CLAUDE.md` — global personal rules, applied to all projects
2. `CLAUDE.md` in parent directories — inherited by child projects
3. `CLAUDE.md` in the current project root
4. `CLAUDE.md` in subdirectories — applied when working within that directory

More specific files can extend or override more general ones.

**`@import` for modular files:**

```markdown
# CLAUDE.md

@import docs/coding-standards.md
@import .claude/security-rules.md
@import .claude/test-conventions.md

This pulls the content of each file into the session context. Teams that share coding standards across projects can maintain a single source file and import it into each project’s CLAUDE.md.

Memory sections:

# Project Memory

- Switched from Jest to Vitest on 2026-05-12 (see PR #341)
- The legacy `auth/` directory is read-only pending migration
- Admin endpoints use API key auth, not JWT

Claude Code preserves this section across sessions in specific configurations, giving you persistent project context.

Tool-specific features: CLAUDE.md supports Claude Code skills (slash commands), hook references, and permission rules. These are Claude Code internals with no equivalent in AGENTS.md or Kiro steering files.

Side-by-Side Feature Table

Migration Guide: Adding Kiro to an Existing AGENTS.md Repo

If you already have AGENTS.md and are adopting Kiro, you have nothing to migrate. Kiro reads your AGENTS.md immediately.

What you want to do is extend what you have. Here is the workflow we recommend:

Step 1: Let Kiro read your existing AGENTS.md

No action needed. Kiro finds AGENTS.md in the workspace root automatically and applies it with always inclusion.

Step 2: Create .kiro/steering/ for Kiro-specific enhancements

mkdir -p .kiro/steering

Step 3: Add conditional steering files for file-type rules

Rules that make sense only for specific file types should move from AGENTS.md (where they clutter every context) to conditional steering files:

# .kiro/steering/react-components.md
---
inclusion: conditional
fileMatch:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

# React Component Rules

Use functional components exclusively. No class components.
Props interfaces are named `[ComponentName]Props`.
Co-locate tests: `Button.tsx` + `Button.test.tsx` in the same directory.

Step 4: Move verbose runbooks to manual steering files

Long runbooks bloat the context when you do not need them. Move them to manual-mode steering files and reference them only when relevant:

# .kiro/steering/deploy-runbook.md
---
inclusion: manual
---

# Deployment Runbook

[Detailed deployment steps...]

Reference with #deploy-runbook in a deployment session.

Step 5: Add live file references where useful

# .kiro/steering/schema-aware.md
---
inclusion: always
---

Current schema:
#[[file:prisma/schema.prisma]]

Use these exact model names and field types in generated code.

The result: your AGENTS.md stays intact and works across all your tools. Kiro gets additional context tuned specifically for its capabilities.

Running Multiple Systems Together

This is the configuration for a team that uses Kiro, Claude Code, and multiple other tools:

repo-root/
├── AGENTS.md                         # Universal rules (all tools read this)
├── CLAUDE.md                         # Claude Code extensions
│   └── @import .claude/standards.md  # Shared with Kiro steering
├── .claude/
│   └── standards.md                  # Shared source of truth
└── .kiro/
    └── steering/
        ├── always/
        │   └── project-context.md    # Kiro-specific, always included
        ├── react.md                  # Conditional for .tsx files
        ├── api.md                    # Conditional for routes/
        └── deploy-runbook.md         # Manual, referenced on demand

The key principle: AGENTS.md holds the rules that every tool should know. CLAUDE.md extends them for Claude-specific capabilities. Kiro steering files extend them for Kiro-specific capabilities.

Content duplication is the main risk. If you write the same convention in AGENTS.md, CLAUDE.md, and a Kiro steering file, you have three maintenance points for one rule. The pattern that avoids this:

• Write team conventions once in AGENTS.md
• Use CLAUDE.md’s @import to pull in shared files (not to restate AGENTS.md content)
• Use Kiro steering files for additions (conditional rules, live file references, manual runbooks) rather than duplicating AGENTS.md content

Decision Guide: Which to Use When

You work alone with Claude Code only → CLAUDE.md. Use @import to keep it modular. Add a global ~/.claude/CLAUDE.md for cross-project preferences.

Your team uses multiple AI coding tools → AGENTS.md as the base. Add tool-specific extensions (CLAUDE.md, Kiro steering) on top without duplicating the core content.

You need rules that only apply to specific file types → Kiro steering files with fileMatch. This feature has no equivalent in AGENTS.md or CLAUDE.md.

You have large runbooks or checklists used only occasionally → Kiro manual steering files. Referenced with #name in chat — not loaded into every context.

Your rules reference content from other project files → Kiro steering with #[[file:path]]. AGENTS.md and CLAUDE.md require manual copy-paste.

You want agent rules tracked in version control across all tools → AGENTS.md. It is a plain Markdown file in your repo root. Every tool that matters supports it.

Browse Real-World Examples

See how production teams structure their AI instruction files in our rules gallery. Includes AGENTS.md examples, CLAUDE.md configurations, and emerging Kiro steering patterns from public repositories.

FAQ

Does Kiro read AGENTS.md automatically?

Yes. Kiro reads AGENTS.md placed in the workspace root with no additional configuration. It applies always inclusion — the file is included in every interaction, the same behavior as in Claude Code or GitHub Copilot.

Can I use CLAUDE.md inside Kiro?

Kiro does not natively read CLAUDE.md. If you need CLAUDE.md content in Kiro sessions, create a Kiro steering file that mirrors the relevant content, or reference shared source files using #[[file:path]].

What happens if both AGENTS.md and a Kiro steering file cover the same topic?

Both are included in the context. There is no automatic conflict resolution — the agent sees both sets of instructions. For clarity, keep non-overlapping scopes: AGENTS.md for universal rules, Kiro steering for Kiro-specific extensions.

Are Kiro steering files version-controlled?

Yes. Files in .kiro/steering/ live in your repository and are version-controlled with the rest of your code. Files in ~/.kiro/steering/ are personal, global, and not part of any repository.

Which system has the best context efficiency?

Kiro steering files win here. The conditional and manual modes keep context lean by excluding irrelevant rules. AGENTS.md and CLAUDE.md are always fully included — every rule, every session, regardless of what the agent is currently doing.

Related Articles

• AGENTS.md Best Practices 2026: What 60,000+ Repos Teach Us
• AGENTS.md vs CLAUDE.md: Complete Comparison
• Windsurf vs Cursor vs AGENTS.md: Rule File Comparison 2026
• AGENTS.md for GitHub Copilot: Complete Integration Guide