Purpose and How to Read This

The distinction the whole document turns on, who each part is for, what is deliberately out of scope, and the evidence convention.

Most material on prompting falls into one of two categories. It is either a list of tricks with no mechanism behind it, or a research summary offering no path to anything one can type tomorrow. This document attempts the thing in between: a mechanical account of how a prompt becomes an output, wired to practices that can be adopted today, with the evidence stated plainly where evidence exists and its absence stated equally plainly where it does not.

1.1 The Distinction That Governs Everything #

There is a single line running through this entire document, and it should be named before anything else.

Prompting is what you write. Context engineering is what arrives.

The prompt one types is a small fraction of what the model receives. In an agentic session, it is frequently under two percent. The remainder consists of a system prompt written by someone else, tool schemas that may never have been read, an instruction file committed eighteen months ago, retrieved files, previous turns, tool results, and, if the session has run long enough, a summary of a summary of the conversation one thought was taking place.

Everything you can control falls into one of two categories. You can change the words in your request, which is prompting and which is the subject of Part II. Or you can change what else is in the window, which is context engineering and which is the subject of Parts III and IV. Beginners spend nearly all their effort on the first. The measurable wins are overwhelmingly in the second.

There is a third category, and it is the one people forget: what you cannot control. On any coding agent, a layer between you and the model rewrites your request before it is sent, and that layer measurably changes the answer. Section 6 covers it because a great deal of effort is wasted attributing to a model what was caused by its harness.

1.2 Who Each Part Is For #

Part	Level	Read it if
I—Foundations	100–200	You want the vocabulary. Everything later assumes it.
II—The Craft	200–300	You write prompts and want them to work more often.
III—The Environment	300	You configure agents, or you own a repository other people’s agents run in.
IV—Economics	300–350	You pay the bill, or you are about to be asked why it went up.
V—Advanced Mechanics	400+	You build on models rather than with them.
VI—Platforms	300	You are standardizing on a vendor, or comparing several.

Part V is deliberately steep. It descends below the API surface into tokenization, attention geometry, sampling, constrained decoding, evaluation design, and adversarial mechanics. Readers already comfortable with Parts I through IV should begin there and refer backward as needed.

1.3 Scope, and What Is Deliberately Absent #

This document covers producing quality output from a language model or coding agent. It does not cover the organizational question of how far to push agent autonomy, how to structure verification and review capacity, or what controls belong on a delivery pipeline. That material is a separate framework and is not repeated here.¹ Where a mechanic in this document has a governance consequence, the consequence is named in a sentence and the reader is pointed at the other document rather than given a second, thinner treatment of it.

Also absent: model training, fine-tuning, and RAG index construction. Retrieval appears in Section 12 as a context-assembly problem, not as a system to build.

1.4 The Evidence Convention #

Prompting sits awkwardly across two literatures. Some techniques carry peer-reviewed measurement behind them, while others amount to craft that works, is widely used, and has never once been tested. Presenting both in the same voice is the most common failure in writing on this subject, and it is precisely why so much prompting advice ages badly.

Two markers run through this document:

Claims carrying a ^N footnote trace to a named primary source. The reference entry says what kind of source it is (peer-reviewed, preprint, vendor documentation, or vendor-published research) and names the limitation where one exists.
Claims marked [unmeasured] are practices I and others use, which have documentation or mechanical justification, and for which no published measurement of effectiveness could be located. They are included because they work in practice and excluded from any argument that depends on their being proven.

If a technique appears with neither marker, it is a mechanical statement about how a system behaves, verifiable in the cited documentation.

1.5 What Good Looks Like #

A reader who has finished Part II writes prompts that specify the output contract, supply the constraints the model cannot infer, and fail loudly rather than quietly. One who has finished Part IV can examine an unexpected invoice and identify which lane the spend landed in and what change produced it. And one who has finished Part V can read a model’s logprobs, design an eval that catches a regression before a user does, explain why a JSON schema changed an answer, and build a harness that does not leak its own instructions.

None of that depends on knowing magic words, because there are no magic words. There are only mechanisms, and mechanisms are learnable.

1.6 Examples #

A final note about examples contained in this document. The primary language used in this document is Python. This is because, with the exception of perhaps a few, all model providers have officially supported SDKs for the language. The source code examples are meant to demonstrate functionality specific to the sections for which they were written. However, in most cases, those examples are not complete. In instances where an SDK is not required, I have also demonstrated C# or TypeScript. The purpose is purely versatility in design, but they serve the same function and, in many cases, the languages are interchangeable. Unless stated otherwise, do not assume specific functionality is exclusive to the language shown.