Best Practices and Common Pitfalls

Duration: 5 min

After working with Kiro's spec workflow on real projects, a few patterns consistently lead to better outcomes — and a few mistakes consistently cause pain.

Do: Spec at the right granularity

One spec per feature, not per project. 'Build my entire SaaS app' is too big — you'll never finish reviewing it. 'Add Stripe subscription billing' is right-sized. 'Add a button' is too small — just ask Kiro directly.

Do: Edit the spec before executing

The spec is yours. Kiro generates a first draft — you own the final version. Add your team's constraints, remove things that don't apply, fix anything that doesn't match your architecture. Five minutes editing a spec saves an hour of code review.

Don't: Skip the design doc

It's tempting to go straight from requirements to tasks. Don't. The design doc is where Kiro commits to specific libraries, data shapes, and patterns. Without it, tasks are vague and the generated code may not fit your existing codebase.

💡 Tip: If you're in a hurry, a minimal design doc is still better than none. Even three bullet points — framework, data model, key library — give Kiro enough to make consistent decisions.

Don't: Let specs go stale

If you change the implementation significantly during execution, update the spec. A spec that doesn't match the code is worse than no spec — it actively misleads future readers and AI agents.

Do: Use steering for cross-cutting concerns

Things that apply to every feature — error handling patterns, logging conventions, security rules — belong in steering files, not repeated in every spec. Keep specs focused on the specific feature; let steering handle the universal rules.