Code ref
also called linked code, code anchor
A GitHub permalink attached to a spec — repo, path, line range, commit — with a note saying why those lines matter. Rendered as source inline beside the document.
A spec that describes code in prose ages badly, because prose cannot be checked. A spec that links to code at a commit can be checked in one click, by anyone, forever.
The note is the part that matters. "meter.go L88–112" tells a reviewer nothing they could not get from the diff. "The write path — atomic increment avoids read-modify-write races when two uploads land together" tells them what to disagree with. One line, aimed at why rather than what.
Refs come from two places in practice. A human pastes the handful that carry the decisions. A draft pull request contributes the files it touches automatically, which is coarser but catches what you forgot to mention. The two should not overwrite each other: sync owns what sync created, and a note a person wrote survives the next sync.
Pinning to a commit rather than a branch is what makes a ref durable. See permalink pinning.
github.com/acme/checkout-api/blob/1f30bb1/meter.go#L88-L112 — “The write path. Atomic increment avoids read-modify-write races when two uploads land together.”
- Permalink pinning
Linking code at a commit SHA rather than a branch, so the link keeps showing the code the decision was made against instead of whatever the branch drifted into.
- Blast radius
Code a change could break but does not touch. Marking it explicitly tells a reviewer where to look for second-order damage without reading the whole diff.
- Draft PR
A pull request opened to explore rather than to merge: stubs, a shape, enough to discover the constraint nobody remembered. It informs the plan and should never be treated as evidence the work is done.