Steering File Starter

What is a steering file?

A steering file is a markdown document that tells your AI coding tool "read this every single time you generate anything for this project."

Without steering, you get the tool's default opinion about how to build software. Generic. Inconsistent. Drifts between sessions.

With steering, you get your opinion — your stack, your style, your constraints — applied consistently, without you having to repeat yourself in every prompt.

Treat this file as your taste, serialized. The more specific it gets, the better your outputs get.

Pick your tool

The template is identical across tools — only the file location and install instructions change.

Copy this into a new file. Fill in every section. Delete sections that don't apply, but don't leave them vague.

═══════════════════════════════════════════════════════════════
PROJECT STEERING FILE
═══════════════════════════════════════════════════════════════

Last updated: [date]
Owner: [your name]

───────────────────────────────────────────────────────────────
1. PROJECT CONTEXT
───────────────────────────────────────────────────────────────

What this project is:
[One paragraph. The customer, the durable need, the outcome.
This should echo the PR-FAQ, not restate it in full.]

Who it's for:
[One specific person or role. Not "users" — a person.]

What success looks like:
[1-2 concrete outcomes. Shipped features, usage metrics,
adoption goals. Specific, not aspirational.]

───────────────────────────────────────────────────────────────
2. STACK
───────────────────────────────────────────────────────────────

Frontend: [React + Vite + Tailwind, Next.js, Astro, etc.]
Backend:  [Supabase, Postgres + Node, serverless, none]
Auth:     [Supabase Auth, Clerk, none, magic link]
Hosting:  [Vercel, Cloudflare Pages, Lovable, etc.]
AI/LLM:   [Anthropic API, OpenAI API, none, etc.]

Package manager: [npm / pnpm / bun / yarn]
Node version:    [20.x]
TypeScript:      [yes / no]

───────────────────────────────────────────────────────────────
3. STYLE & CONVENTIONS
───────────────────────────────────────────────────────────────

Code style:
- [e.g., Functional components only, no class components.]
- [e.g., Use named exports. Default exports only for pages.]
- [e.g., Co-locate tests with source files.]
- [e.g., Use TanStack Query for server state, not useEffect.]

Naming:
- Files:       [kebab-case / PascalCase / camelCase]
- Components:  PascalCase
- Variables:   camelCase
- Constants:   SCREAMING_SNAKE_CASE
- DB tables:   [snake_case / plural / singular]

Folder structure:
[Describe or paste. Be specific about where things live.]

───────────────────────────────────────────────────────────────
4. VOICE & COPY
───────────────────────────────────────────────────────────────

How the product talks to users:
- Tone:        [friendly but direct / formal / playful / etc.]
- Person:      [second person "you" / first person plural "we"]
- Jargon:      [none / industry-appropriate / explain on hover]
- Microcopy:   [short / no filler words / button labels are verbs]

Things we never say:
- [e.g., "Awesome!" / "Oops!" / "Uh oh"]
- [e.g., "Powered by" unless contractually required]
- [e.g., Passive voice in error messages]

───────────────────────────────────────────────────────────────
5. DESIGN CONSTRAINTS
───────────────────────────────────────────────────────────────

Colors:       [paste token values or reference a design file]
Typography:   [font families, weight scale, line-height scale]
Spacing:      [e.g., Tailwind default scale, rem-based]
Radius:       [sm: 4px, md: 8px, lg: 12px, pill: 9999px]
Shadows:      [soft, elevated, none]

Motion:
- Use subtle, short transitions (< 300ms)
- Never animate on page load without user interaction
- Respect prefers-reduced-motion

Accessibility:
- WCAG AA minimum on text contrast
- All interactive elements keyboard navigable
- Focus states visible on every focusable element
- Form inputs always paired with labels

───────────────────────────────────────────────────────────────
6. CONSTRAINTS & NON-NEGOTIABLES
───────────────────────────────────────────────────────────────

Things we will not do, regardless of how clever the prompt:

- [e.g., No client-side state libraries (Zustand, Redux).
  Use TanStack Query + URL state.]
- [e.g., No custom CSS outside Tailwind. No styled-components,
  no CSS-in-JS.]
- [e.g., No new dependencies without explicit approval.]
- [e.g., Do not rewrite files > 200 lines without asking.
  Propose the diff first.]

───────────────────────────────────────────────────────────────
7. WORKING STYLE WITH ME
───────────────────────────────────────────────────────────────

How I want to collaborate with you (the AI tool):

- When in doubt, ask. Don't invent.
- Explain your reasoning when the answer isn't obvious.
- If you're changing something I didn't ask about,
  tell me before you do it.
- Quote the existing code when you're proposing a diff.
- If I push back, update your model of what I want.

When I say "let's ship this," it means:
- Tests pass
- No console.log statements left
- No TODO comments added in this session
- The feature works on mobile
- I can copy and paste what you wrote without edits

───────────────────────────────────────────────────────────────
8. EARS REQUIREMENTS STYLE
───────────────────────────────────────────────────────────────

All acceptance criteria are written in EARS notation:

- Ubiquitous:   THE SYSTEM SHALL [behavior]
- Event-driven: WHEN [trigger], THE SYSTEM SHALL [behavior]
- State-driven: WHILE [state], THE SYSTEM SHALL [behavior]
- Unwanted:     IF [condition], THEN THE SYSTEM SHALL [behavior]
- Optional:     WHERE [feature], THE SYSTEM SHALL [behavior]

Never generate a feature without at least one "IF" (unwanted
behavior) clause. Happy paths without error cases are not specs.

───────────────────────────────────────────────────────────────
9. SECURITY & DATA
───────────────────────────────────────────────────────────────

- Never commit secrets. Use .env files and environment
  variables everywhere.
- Never log PII to the console or to third-party services.
- All database access goes through Supabase RLS or an
  equivalent row-level policy. No raw SQL from the client.
- Never cache user-specific data across sessions without
  explicit invalidation.

The rule of thumb

If you catch yourself writing the same prompt twice, it belongs in your steering file.

• If you tell the tool "don't use class components" three times, that's a steering file entry.
• If you correct the voice of the copy in every session, that's a steering file entry.
• If a stakeholder keeps asking "does this handle PII correctly?", that's a steering file entry.

Your steering file is a living document. It grows as you notice patterns.

Use this freely. Share it. Adapt it. If it helps you ship something, tag @ajbubb on LinkedIn.