# Steering Principles

Steering files are **project memory**, not specification documents.

Their purpose is to capture the patterns, conventions, and decisions that would take a new contributor (or an AI assistant) time to discover on their own — and to record them in a form that guides future decisions, not in a form that catalogs what currently exists.

---

## Content Granularity

### The Core Rule
> "If new code follows existing patterns, steering should not need updating."

When steering accurately captures the principles behind how the codebase is organized, individual additions that follow those principles require no steering change. Only new patterns, architectural shifts, or deliberate convention changes warrant an update.

### What Belongs in Steering

- **Organizational patterns**: Feature-first, domain-driven, layered — the principle and an example
- **Naming conventions**: File naming (kebab-case), type naming (PascalCase), constant naming (SCREAMING_SNAKE_CASE)
- **Import and module resolution strategy**: Absolute paths vs relative, index re-exports, barrel file usage
- **Architectural decisions**: State management approach, API style (REST vs GraphQL), service communication pattern
- **Technology standards**: Key frameworks with version-relevant conventions, toolchain choices and configuration norms

### What Does Not Belong in Steering

- Complete directory trees or file listings
- Per-component or per-module descriptions of every item
- Exhaustive dependency manifests or lock file contents
- Implementation details, algorithm descriptions, or code that belongs in comments
- Agent-specific tooling directories (`.cursor/`, `.gemini/`, `.claude/`, etc.)
- Contents of `.sdd/settings/` — those are internal metadata, not project knowledge

### Illustration

**Avoid this style** (specification-like):
```markdown
- /components/Button.tsx — Primary action button, supports `variant` and `size` props
- /components/Input.tsx — Controlled text input with validation message slot
- /components/Modal.tsx — Focus-trapped dialog with accessible ARIA roles
... (40 more entries)
```

**Prefer this style** (pattern-oriented):
```markdown
## UI Components (`/components/ui/`)
Stateless, design-system-aligned primitives. Each file exports one component and its TypeScript interface. No business logic or data fetching belongs here.
- Named by function (Button, Input, Modal, Tag)
- Props interface co-located in the same file as the component
```

---

## Security

Steering files must never contain:
- API keys, access tokens, or credentials of any kind
- Database connection strings or internal URLs
- Internal IP addresses, hostnames, or network topology details
- Any value that would need to be rotated if exposed

---

## Quality Standards

- **Single domain per file**: Each steering file addresses one coherent topic — do not mix API conventions with testing strategy
- **Concrete examples**: Abstract principles must be grounded with real code excerpts or representative examples
- **Explained rationale**: Record why a decision was made, not just what was decided — context prevents future second-guessing
- **Appropriate length**: 100–200 lines is the typical target; files approaching 300 lines likely contain too much detail or scope

---

## Preservation When Updating

When updating existing steering files, follow these rules:
- **Add, do not replace**: New content goes alongside existing content; do not delete user-authored sections
- **Mark changes**: Record what changed and the reason in an `updated_at` field or a brief note
- **Preserve examples**: User-provided examples and domain-specific terminology are intentional and must be kept
- **Additive by default**: When uncertain whether to update or add, choose to add with a note rather than overwrite

---

## Notes

- All `{{SDD_DIR}}/steering/*.md` files — core and custom — are loaded as project memory by every SDD command
- Templates in `{{SDD_DIR}}/settings/templates/steering/` are starting points; always adapt them to the actual project
- Custom steering files carry equal weight to the three core files
- Light references to `{{SDD_DIR}}/specs/` and `{{SDD_DIR}}/steering/` are acceptable context; avoid referencing other `.sdd/` subdirectory paths
- The steering directory should feel like a well-organized onboarding document, not an architecture diagram or a file system snapshot

---

## File-Specific Focus Areas

- **product.md**: Core purpose, user value proposition, primary capability domains — not an exhaustive feature list
- **tech.md**: Key frameworks and versions, language conventions, architectural decision record highlights — not a full dependency manifest
- **structure.md**: Module organization principles, naming rules, import conventions — not a directory tree
- **Custom files**: Specialized patterns for a single domain (API design, testing, security, error handling, etc.) — not cross-cutting concerns
