prompting

Prompting

Rules for any document a model executes. Each rule targets variance: the same document should drive the same process on every run.

To rewrite an existing document, see references/conversion.md.

Placement

Put material in the body when every run needs it. Put it behind a pointer when only some runs reach it. Leave it unpointed when a human should choose whether to reach it, because a pointer from the body hands that choice to the model.

Move reference that only some branches need out of a step sequence, even when it is short. Leaving it in place makes the model attend to the surrounding steps inconsistently across runs, which costs more than the tokens do.

Bodies hold two kinds of material: the ordered actions the model performs, and the definitions and rules it consults while performing them. Keep a flat list of peer rules flat.

A document can be too long even when every line is live and unique. Past that length the model attends unevenly across it. Move reference behind pointers, then split by case or by sequence so each path carries only what it needs.

Pointers

A pointer names material outside the context and states when to reach it. A skill description, a CLAUDE.md line naming a rule file, a See <file> link, and a tool description are all pointers.

The pointer's wording determines whether the model reaches the material. Sharpen the wording before inlining anything.

Write a pointer to state what the material is and which cases trigger it. Prune it harder than the body, because it costs every turn:

• Put the trigger word first.
• One trigger per case. Synonyms for one case are that case written twice.
• Cut identity the body already carries.

Co-location

Keep a concept's definition, rules, and caveats under one heading. Test a section by reading it alone: it should answer the question it names without sending the reader elsewhere in the file.

Splitting

Split a sequence when later steps tempt the model to finish the current one early. That works only across a real context break: a hand-off, a subagent dispatch, a separate request. An inline reference leaves the later steps in context.