SDD Framework

Steering Files & Project Memory

Create and maintain .kiro/steering/ files that give AI tools permanent memory of your architecture, conventions, and domain rules.

What Are Steering Files?

Steering files are markdown documents in .kiro/steering/ that capture your project's persistent context. Every cc-sdd command reads all steering files before generating any output — this means the AI always knows your project's conventions without you re-explaining them.

Think of steering files as your project's DNA. They capture decisions that should never change without deliberate intent: your architectural choices, your naming conventions, your business rules, your security requirements.

The Context Loss Problem

Without steering files, every AI coding session starts from scratch. You get inconsistencies:

  • Session 1: Components use camelCase filenames
  • Session 2: Components use PascalCase (AI defaulted to its training data)
  • Session 3: A new pattern is introduced that conflicts with Session 1's architecture

Steering files solve this by making your conventions explicit and persistent. The AI reads them before every operation.

Core Steering Documents

architecture.md: Your system's overall design — layers (presentation, business logic, data), key components, data flow, and how parts connect. The AI reads this to understand where new code should go.

tech-stack.md: Languages, frameworks, libraries, and their versions. Package manager. Build tooling. CI/CD pipeline. The AI reads this to know what libraries are available and which patterns are appropriate.

naming-conventions.md: File naming patterns (component-name.tsx vs ComponentName.tsx), variable naming styles (camelCase vs snake_case), API naming conventions (REST conventions, URL patterns), database naming (snake_case columns, table pluralization).

domain-rules.md: Business logic and validation rules specific to your application's domain. "Users cannot delete items created by other users." "Prices are always stored in cents as integers, never as floating point." "All user-facing dates are in the user's timezone."

security.md: Authentication methods, authorization patterns, data handling requirements, encryption requirements, input sanitization standards.

Custom Steering Documents

Beyond the core five, you can create steering files for any domain-specific standards:

api-standards.md: REST endpoint naming conventions, versioning scheme, error response format (consistent JSON structure), authentication header format, pagination pattern.

error-handling.md: Error classification (user errors vs system errors), error response format, logging standards, retry behavior.

authentication.md: Session management, JWT vs session cookies, password policy, OAuth flows, MFA requirements.

testing.md: Testing philosophy (unit vs integration vs e2e), test file naming, coverage requirements, mocking patterns.

Creating Steering Files

Run /kiro:steering on an existing project and cc-sdd analyzes your codebase to generate initial steering docs. You review and refine them.

For custom rules, run /kiro:steering-custom [description] to generate a custom steering document for a specific domain area.

Steering Files and Kiro IDE

The cc-sdd steering files are compatible with Kiro IDE's steering files (project.md, tech.md, design.md). If you use Kiro IDE, your steering files work in cc-sdd too. The formats are portable across tools.

Example: architecture.md

markdown
# Architecture

## System Overview
A React SPA with a Supabase backend. Client-side routing with React Router v6.
No server-side rendering — pure client-side application.

## Layers
- **Presentation**: React components in src/components/
- **Pages**: Route-level components in src/pages/
- **Data**: Supabase client calls, no separate service layer
- **Types**: TypeScript interfaces in src/types/index.ts

## Key Patterns
- Components use default exports
- Data fetching happens in page components, not in leaf components
- Global state is handled with React Context (no Redux)
- Forms use controlled components with local useState

## File Naming
- Components: PascalCase (UserCard.tsx)
- Utilities: camelCase (formatDate.ts)
- Pages: PascalCase (UserProfile.tsx)
- CSS: kebab-case (user-card.module.css)

Key Takeaways

  • Steering files capture project memory that persists across every AI session
  • Without steering, AI tools default to generic patterns that may conflict with your decisions
  • Core files: architecture.md, tech-stack.md, naming-conventions.md, domain-rules.md, security.md
  • Custom steering files capture domain-specific standards beyond the core five
  • Run /kiro:steering to generate initial files from your existing codebase automatically

Example

markdown
# .kiro/steering/naming-conventions.md

# Naming Conventions

## Files & Directories
- React components: PascalCase.tsx (UserProfile.tsx)
- Utility functions: camelCase.ts (formatDate.ts)
- Pages: PascalCase.tsx in src/pages/
- Test files: *.test.ts or *.spec.ts alongside source
- Constants: SCREAMING_SNAKE_CASE in lib/constants.ts

## TypeScript
- Interfaces: PascalCase, prefix with 'I' only if needed for disambiguation
- Types: PascalCase (UserProfile, not userProfile)
- Enums: PascalCase with PascalCase members
- Generic params: T, TItem, TResult (descriptive for complex generics)

## React Components
- Props interfaces: ComponentNameProps
- Event handlers: handle[Event] (handleClick, handleSubmit)
- Boolean props: is/has/should prefix (isLoading, hasError)

## Database (Supabase)
- Tables: snake_case plural (user_profiles, blog_posts)
- Columns: snake_case (created_at, user_id)
- Foreign keys: [table_singular]_id (user_id, post_id)

## API Routes
- Resources: plural nouns (/users, /posts)
- Actions: POST to create, PUT to replace, PATCH to update
- Nested: /users/:id/posts (max 2 levels deep)
Try it yourself — MARKDOWN