Use AGENTS.md as Steering

AGENTS.md is a plain Markdown file that several AI coding tools read for project instructions, and Kiro loads it as steering. Drop one in your repository root and Kiro picks it up with no configuration and no front matter.

When to use this

Use AGENTS.md when your team runs more than one AI coding tool and you want a single file of house rules. Use it in a monorepo where each package needs its own local rules, since Kiro finds nested files too. Stay with .kiro/steering/ when a rule should load only for certain paths.

Steps

1. Create AGENTS.md in the root of your repository.

2. Write the rules that should apply to every conversation. Keep it short, because the file is always included.

   AGENTS.md

   # Project rules
   
   - Python 3.12 with FastAPI and SQLAlchemy 2.x. No new dependencies
     without a note in the design document explaining why.
   - Routers stay thin. Business logic lives in src/services/.
   - Every bug fix ships with a regression test.
   - Money values are integers of minor units. Never floats.

3. Add a nested AGENTS.md inside a package or subdirectory when that area has its own rules. Kiro discovers files below the workspace root, so a monorepo can carry one file per package.

4. Put a personal AGENTS.md in ~/.kiro/steering/ if you want the same rules in every project you open.

5. Move any conditional rule into .kiro/steering/ with inclusion: fileMatch. AGENTS.md has no way to express “only for the API folder”.

6. Commit the file. It is project documentation, and a human reader benefits from it too.

Check it worked

Start a new chat session and ask the agent something that only your AGENTS.md answers, such as which database library the project uses. In the CLI, the configuration panel added in v2.21.0 lists loaded steering. If the rule takes effect in a brand new session with no other prompting, the file is loading.

Common problems

• Nothing changes after you add the file. Check your Kiro version. Nested discovery landed in CLI v2.18.0 and IDE v1.0.309. Older builds may only read the workspace root.
• The file grows into a manual. It is always included, so every line costs context on every turn. Push long reference material into a skill that loads on demand.
• Rules contradict .kiro/steering/. Kiro’s documentation does not state which one wins. Do not rely on a guess. Pick one home for each rule.
• You expect AGENTS.md to be optional. It is not. There is no inclusion: manual equivalent, so anything you write there applies to every request.
• Secrets end up in it. The same rule as all steering: no tokens, no keys, no customer data.

Related

• Steering covers inclusion modes and merge behaviour.
• Create your first steering file sets up the foundational three.
• Advanced Tutorial discusses the team decision between the two formats.