/ docs

Steering rules

Per-file-glob prompt layering. Teach the agent your conventions once.

▶

Steering rules — walkthrough

Video walkthrough coming soon.

Steering rules — walkthrough

What steering rules are for

You have project-specific conventions — a house style for TypeScript, a banned set of libraries, a preferred error type. Rather than repeat them in every chat, drop them into a steering rule and the agent injects them into the system prompt only when editing files that match your glob.

Where they live

.hypex/steering/<slug>.md — workspace-scoped (commit them so the team gets them)

No user-level steering for now — rules are project-shaped by design.

File format

---
glob: "src/**/*.ts"
alwaysApply: false
---

# TypeScript house style

- Prefer named exports. Default exports only in Astro pages.
- Never throw raw Error. Use our `Result<T, E>` type from `@/lib/result`.
- Avoid `any` and `unknown` return types. If inference is off, explicitly type.
- Prefer arrow functions for callbacks; top-level exports use `function` keyword.
- JSDoc required on every exported function.

Frontmatter fields

Field	Default	Purpose
`glob`	(required unless alwaysApply)	Minimatch pattern. Rule fires when the active editor's workspace-relative path matches.
`alwaysApply`	`false`	If true, inject on every turn regardless of active file.
`priority`	`0`	Higher priority rules render first. Use if you have layered rules (global → module → file).

How injection works

Every turn, the system prompt builder does:

Read all .hypex/steering/*.md
Filter by alwaysApply OR glob matching the active editor's path
Concatenate bodies (priority-sorted) into a ## Active steering rules block in the system prompt

If no rule matches, the block is omitted entirely.

Example patterns

Monorepo — different conventions per package

# .hypex/steering/frontend.md   (glob: "apps/web/**")
# .hypex/steering/api.md        (glob: "apps/api/**")
# .hypex/steering/shared.md     (glob: "packages/**")

Always-on policy

# .hypex/steering/global.md
---
alwaysApply: true
priority: 10
---
- Only use MIT-licensed dependencies.
- No console.log in committed code — use our `log()` helper from `@/lib/log`.
- Every module has a copyright header.

File-type specific

# .hypex/steering/python.md
---
glob: "**/*.py"
---
- Python 3.12+. Use `type |` unions, not `Union[...]`.
- Prefer `pathlib.Path` over `os.path`.
- Run `ruff check .` before any commit.

Steering vs profiles vs skills

Profile — who the agent is (debugger / refactor / kernel / …). One at a time.
Steering — how the agent should edit this specific codebase. Layered on top of the profile when file globs match.
Skill — what to do for a specific task type (add tests, dockerize a project). Matched by keyword from the user's message.

All three stack: profile + steering rules that match + skills that match = the system prompt for the turn.

Commands

Hypex: Create Steering Rule — scaffolds a new rule
Hypex: Open Steering Folder — reveals .hypex/steering/