# Steering Reference Card

> **Summary — what this page covers**
> A printable one-pager attendees keep. It answers "where does this instruction belong?" with
> the seven-methods decision table, the three decisions, a quick flowchart, and .NET
> copy-paste starters. Paste the finished content from the workshop's Steering Reference Card
> here; this stub gives the skeleton.

***The one page worth keeping.***

## The question behind every instruction

> Decide by four properties: **when it loads · survives compaction · context cost · authority.**

## The seven methods

| Method | When it loads | Survives compaction | Context cost | Use it for |
|---|---|---|---|---|
| **CLAUDE.md (root)** | Session start; re-read after compaction | Yes (memoized) | Always in context — keep < 200 lines | Facts & soft conventions Claude needs all the time |
| **CLAUDE.md (subdir)** | On-demand, when working in that folder | Partial (reloads when relevant) | Low — only when you're in that area | Folder-specific facts |
| **Rules** | Always (unscoped) or on file-match (path-scoped) | Yes | Low–medium | Path-scoped coding conventions |
| **Skills** | On `/name`, or auto-match by description | n/a (invoked on demand) | Low until triggered | A multi-step procedure (~30+ lines) |
| **Subagents** | When spawned | Isolated context; only the summary returns | Cheap to the parent — runs in its own window | Out-of-sight heavy work; a cost lever via `model:` |
| **Hooks** | On events (deterministic) | n/a (runs as code) | None — executes outside the model | "Every time X, do Y"; real guardrails (`PreToolUse` exit 2 blocks) |
| **Output styles** | Session config | n/a | Minimal | Changing how Claude formats responses |
| **Append-system-prompt** | Session start (flag) | Yes | Adds to every turn | One-off system-prompt additions |

## Three decisions you'll actually use

1. **"Every time X, always do Y" → hook.**
2. **"Never do X" → not a CLAUDE.md line** (hooks · permissions · managed settings).
3. **A 30-line procedure → skill.**

## "Where does this go?" — quick flow

Walk it top to bottom; take the **first** match:

1. **"Every time / never X" (deterministic)?** → **HOOK** (`PreToolUse` exit 2 to block).
2. **A multi-step procedure (~30+ lines)?** → **SKILL** (a folder, triggered by its description).
3. **A coding convention for a file area?** → **RULE** (path-scoped glob).
4. **An always-needed project fact?** → **CLAUDE.md** (root = map; subdir = local facts).
5. **Heavy / noisy work you want out of context?** → **SUBAGENT** (isolated; summary returns).

## .NET copy-paste starters

**Path-scoped C# rule** — `.claude/rules/data-access.md`

```markdown
---
paths:
  - "BookTracker.Data/**/*.cs"
---
# Data-access conventions
- Parameterized queries only — never string-concatenated SQL.
- Async EF methods; thread the CancellationToken.
- Migrations live in BookTracker.Data.
```

**Skill folder layout** — `.claude/skills/<name>/`

```text
.claude/skills/add-api-endpoint/
  SKILL.md          # name + model-facing description (the trigger) + procedure + Gotchas
  references/       # supporting docs the skill points Claude to
  scripts/          # helper scripts the skill can run
```

**Subagent (`.md` + frontmatter)** — `.claude/agents/test-writer.md`

```markdown
---
name: test-writer
description: Generate xUnit tests for a class, matching the patterns in BookTracker.Tests.
model: claude-haiku-4-5
---
You write focused xUnit tests. Read the target class and existing tests first,
mirror the house style, and cover happy path + edge cases.
```

**Guardrail hook registration** — `.claude/settings.json`

```json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [
        { "type": "command", "command": ".claude/hooks/block-destructive.sh" }
      ]}
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [
        { "type": "command", "command": "dotnet build" }
      ]}
    ]
  }
}
```

## Gotchas worth remembering

- Skills are **folders**, not files. Subagents are **`.md`**, not `.yaml`.
- Path-scoped rules load on **read**, not create — make creation-time rules unscoped.
- User-level `~/.claude/rules/` `paths:` is currently unreliable — use project-level.
- A skill's `description` is a **trigger written for the model**; its **Gotchas** section is the high-value part.