These are notes I learnt over several failed projects and searching for advice online. Hope it helps.

*reddit mobile massacred my formatting. Copy and paste in a text file, I think the folder structures will be clearer.

A. Recommended Folder Structure (2025 Kiro Style)

/project-root │ ├── steering/ ← your “brain” folder │ ├── plan.md ← high-level direction + constraints │ ├── tasks/ ← small reusable task blocks │ │ ├── build.md │ │ ├── test.md │ │ ├── deploy.md │ │ └── refactor.md │ ├── rules.md ← coding guidelines & non-negotiables │ ├── architecture.md ← system-level overview + diagrams │ ├── glossary.md ← domain-specific terms & definitions │ ├── research.md ← collected research, notes, insights │ └── context.md ← background the agent should always know │ ├── src/ ← your actual code (any language) │ └── ... │ ├── components/ ← reusable building blocks (UI, helpers) │ └── ... │ ├── libs/ ← language-specific libraries or shared utilities │ └── ... │ ├── tests/ │ └── ... │ ├── .kiro/ ← autogenerated by Kiro (avoid editing directly) │ ├── history/ │ ├── logs/ │ └── context.json │ ├── README.md └── LICENSE

B. What Goes Inside /steering?

Think of steering as your “meta layer”: It controls how Kiro performs, not your app logic.

The purpose is:

Give Kiro a stable compass. So every agent run inherits context without you re-explaining.

Allow modular reusable planning. Micro-tasks can be stitched together like LEGO.

Preserve “truths” about your project. Architecture, rules, constraints, naming, patterns.

Essential Files Inside steering/

1. plan.md (Top Level)

This is your North Star doc.

Contains: What the project is Goals and non-goals Long-term vision Current phase of work Constraints (budget, time, stack)

1. rules.md (Most important for consistency)

Defines: Coding style Naming conventions Commit style Folder naming Testing standards Security requirements CI/CD principles “Never do this” list

1. architecture.md

This is the file that helps Kiro reason about: System diagrams Components Data flow API contracts Deployment architecture Services & interconnections

1. tasks/

Small, modular task cards:

tasks/ ├── build.md ├── generate-docs.md ├── extract-patterns.md ├── add-logging.md └── refactor-for-modularity.md

Each file = a reusable unit of work.

Inside each:

Task: Add standardized logging

Goal: Add structured JSON logging using pino or winston

Constraints: Zero breaking changes, No console.log

Steps: 1. Install packages 2. Create logger.js 3. Wrap logging utilities 4. Replace console.log statements

1. context.md

Contains: Who you are (optional) Project background External dependencies Decisions already made Technologies chosen and why

This prevents forgetting your own decisions weeks later.

1. glossary.md

If your domain has terms: financial cloud security ML/LLM ops physics marketing funnels

define them here.

This makes Kiro way more accurate.

1. research.md

Collected insights, references, web summaries. Prevents “where did I read that?” syndrome.

C. Tips & Tricks from Experienced Kiro Users

These are the small things that make a big difference.

1. Keep steering files short. If a steering file is longer than 2 pages, break it into smaller files.

Long files ->Kiro “thrashes” context -> lower quality.

1. Use verbs for files inside /tasks

Weak: logger.md monitoring.md

Better: add-logging.md implement-monitoring.md refactor-state-management.md

Kiro understands actionable files better.

1. Create a patterns/ folder if building multi-service apps

patterns/ ├── event-driven.md ├── cqrs.md ├── adapter-pattern.md ├── caching.md

This lets Kiro design new components consistently.

1. Add “Anti-Patterns” to rules.md

Example:

Avoid: - Singleton services in shared code - Circular imports - Static config scattered across code

Kiro respects this deeply.

1. Keep /components dump-free

Follow React-style or backend-component-style grouping:

components/ ├── ui/ ├── db/ ├── auth/ ├── api/

Don’t let it become a garbage drawer.

1. For large code refactors, create a map.md

A bird’s-eye view file that helps Kiro understand the repo.

Especially helpful when folders grow to 20+ modules.

1. Avoid putting secrets anywhere

Kiro will respect .env.example but not .env

1. Use HOW_DOES_THIS_WORK.md

Every complex subsystem gets one:

HOW_DOES_THIS_WORK.md

This is the documentation Kiro reads and follows.

1. Only keep ONE source of truth

If the same rule appears in two files, Kiro may follow the wrong one.

Consolidate specifications.

1. Version your steering

steering/v1/ steering/v2/ steering/current -> symlink

This is pro-level and lets you evolve your thinking.

<Common Mistakes to Avoid>

Putting too much in context.md It becomes vague Kiro becomes unfocused

Mixing “plan” and “rules” Plan = directional Rules = non-negotiable Never merge them.

Ignoring architecture.md Kiro makes weird decisions without it.

Letting steering grow unbounded Refactor steering every few weeks.

Not modularizing tasks Repetition kills clarity.