Barncore/prompting-agents

Prompting agents

The reader is a capable model with none of your context. Say what must be true at the end and why, and let it plan the path: a route written for work the model can plan is followed faithfully, wrong steps included. The packaging differs — brief, handoff, skill — the writing does not.

The core

What goes in. The line test: could the reader derive this from the task and its training? Facts it cannot look up, the user's conventions, contracts, hard constraints and done-criteria fail the test and stay. Routes for plannable work pass it and go. A checklist of criteria is an end-state; a checklist of steps is a route.

Self-contained. A fresh session reads only the prompt and the disk. Every message carries the full current rule set with changes applied in place — never "as before, plus these changes" — and every document restates each standing rule it depends on, never "as in the parent".

The why, stated positively. The model generalises from reasons, so each rule carries its own ("one continuous line per paragraph, because the chat box treats a line break as intended"). State the target behaviour; a prohibition drags the banned behaviour into context and makes it more available, so keep one only as a hard guardrail, paired with the positive target. Pressure language (MUST, CRITICAL, caps) over-triggers on current models; write "use X when…".

Leading words, one place, no no-ops. A word the model already holds (receipts, fog of war, tight loop) beats a phrase; the user's own term beats both. Each meaning lives in one place. A sentence the reader obeys by default pays load to say nothing: delete the sentence, not words from it.

Prompt anatomy

1. Intent — the larger goal, who it serves, what the output enables; the model spends it on the micro-decisions the prompt never reaches.
2. End-state — what exists when done, with what properties, and what the user can now do. Checkable, and exhaustive: "every modified file accounted for" forces legwork that "produce a change list" does not. The deliverable's format lives here; it is a property, not a procedure.
3. Hard constraints — the inviolables: read-only sources, budgets, terminology, provenance. The user's stated constraints, as stated — never your own economy defaults.
4. Checkpoints — the one place prescription still belongs: when to pause for the human (a destructive or irreversible action, a real scope change, input only they hold) and what is out of scope.
5. Freedom clause — licence to restructure and push back. On ambiguity, make routine calls and state the assumption; ask when the answer could prevent a problem later, such as readings that lead to materially different work or a choice that is costly to undo. The user welcomes those questions. In an unattended run, the question becomes a ruling with a safe default applied, and the work continues.
6. Receipts — in every brief: before reporting done, audit each claim against an artifact from this session, and say plainly what is unverified; this near-eliminates invented status reports.

Ordered steps earn a place where order matters (a migration, a safety protocol) or where a skipped step is the failure; there, a checklist the reader copies and ticks off beats prose.

Before you send

Could any numbered procedure become an end-state sentence? Is every remaining line a constraint, checkpoint, verification rule or deliverable spec? Does any sentence let the reader stop, slow or cut scope for a reason the user did not state? Would the reader have needed to sit in this conversation to act on it?

Branches

• One-shot message to a reader you can model (subagent dispatch, prompt for another session, handoff, message to an external AI) → references/briefs.md
• Brief for an unattended run, its checkpoint memos and rulings, sequencing under a closing window → references/autonomous-runs.md
• Durable document (skill, CLAUDE.md, reference doc), and when to hand a skill build to Anthropic's skill-creator → references/skills-and-docs.md
• Choosing the reader's model or effort level, or writing for Haiku or Fable rather than Opus → references/models.md