Teaching HQ: /learn, Policies, and Why Knowledge Compounds

5 min read Updated Oct 2026

Anyone who has corrected HQ twice on the same thing and would like to never do it a third time.

Claude Code · /learn

› /learn never use emojis in customer emails✓ Rule saved · scope: company · applies to every future session next week, drafting an email…✓ Draft written. (No emojis: your standing rule.)

Illustrative · correct twice, teach once, never repeat it

A plain chatbot forgets everything the moment the conversation ends. You tell it your company always deploys on Fridays, it nods, and next week you're telling it again. HQ is built to break that cycle: /learn turns corrections and discoveries into standing rules that every future session obeys automatically. This is the single biggest payoff of HQ over a chatbot, and it only works if you actually use it.

What a policy is#

A policy is a standing rule HQ must follow, a small text file stating the rule, why it exists, and when it applies. Examples of real, useful policies:

"NEVER email customers directly, all customer email goes through the support inbox."
"ALWAYS use the staging branch, not main, for the acme-web repo."
"When writing for Acme, use sentence case in headings, never Title Case."

Policies are loaded automatically. At the start of every session, and again the moment a rule becomes relevant (you mention deploying, the deploy policy surfaces), HQ injects the applicable policies as constraints. You don't re-teach; the rule is just there. /startwork even shows you a count of the policies in force so you can see the guardrails.

How /learn works#

When something is worth remembering, say so:

shell

/learn always write Acme blog posts in first person plural. "we", never "I"

HQ extracts the rule, checks whether a similar policy already exists (updating beats duplicating), decides where it belongs, and writes the policy file. From then on, every session that touches Acme content carries the rule. You'll get a short confirmation showing the rule, its scope, and where it was saved.

For corrections that must never be violated, add --hard:

shell

/learn --hard never commit directly to main in the acme-web repo

Hard-enforcement rules are surfaced more aggressively, they're constraints, not suggestions.

You often don't even need to invoke it: /handoff and /checkpoint reflect on the session and route notable lessons through the same pipeline automatically. But explicit is better than implicit, when you feel the "I already told you this" flash of irritation, that's the signal.

Rule of thumb: corrected the same thing twice → /learn it. Once might be a fluke. Twice is a pattern, and patterns belong in policies, not in your patience.

Scopes: where a rule applies#

Not every rule should apply everywhere. /learn files each rule at the right level:

Scope	Applies to	Example
Global	Everything you do in HQ	"Always confirm before sending anything external"
Company	One company only	"Acme's brand voice is warm, no exclamation marks"
Repo	One codebase only	"This repo deploys from the staging branch"

HQ infers the scope from context, if you're working inside Acme when you /learn, the rule lands in Acme's policies. Company scoping matters for isolation: Acme's rules never leak into your other companies, and if HQ can't tell which company a rule belongs to, it asks rather than guessing. You can also just say the scope: "learn this for the acme company only."

(Two narrower scopes exist for specific commands and workers. HQ routes those automatically; you rarely need to think about them.)

Besides rules, /learn can also capture insights, explanations worth keeping that aren't directives ("why the export is slow on Mondays"). Rules constrain behavior; insights inform it. Both are searchable later with /search.

Why knowledge compounds#

Here's the arithmetic that makes this worth 30 seconds each time.

Every correction you don't capture is a correction you'll make again, in every future session, forever. Every correction you do capture is made exactly once. Week one, you might /learn five things. Week ten, new sessions start already knowing your brand voice, your deploy rules, your client quirks, your formatting preferences, and each session's output needs less fixing, which frees you to notice subtler things worth teaching.

It compounds across people, too. Company-scoped policies sync to your teammates in a cloud-backed company (one connected to HQ Cloud), so when one person teaches HQ that invoices always go out on the 1st, everyone's HQ knows it. Your team's operational knowledge stops living in one person's head.

That's the difference in kind, not degree, from a chatbot: a chatbot session starts at zero every time. An HQ session starts at everything you've ever taught it.

Common questions#

What's the difference between a policy and the knowledge base?

The knowledge base is what HQ knows, documents, facts, meeting notes. Policies are what HQ must do (or never do). "Our refund window is 30 days" is knowledge; "never promise refunds outside the 30-day window without approval" is a policy.

Can I see, edit, or delete a policy?

Yes. They're plain text files, global ones in personal/policies/, company ones in companies/{company}/policies/. Read them, edit them, delete the ones that no longer apply. /learn tells you the exact file path each time, and a periodic /garden pass helps prune stale ones.

Will HQ create duplicate rules if I /learn the same thing twice?

No, it checks for similar existing policies first and updates or merges rather than duplicating.

Is there such a thing as too many policies?

Yes, mildly: a policy that's wrong or obsolete is worse than none. Capture real patterns, not one-off preferences, and prune occasionally. The "twice" rule of thumb is a good filter.

Do my personal learnings get shared with my team?

Global-scoped rules stay in your personal overlay, yours alone. Company-scoped policies belong to the company and sync to its members. That's usually exactly what you want: personal taste stays personal, team rules become team-wide.

If you get stuck#

If a learned rule doesn't seem to apply in a new session, check it exists (/search the rule text) and that you're working in the scope it was saved to, a company rule won't fire outside that company. Still off? See The "I'm stuck" guide or file /hq-bug.