Skip to content

CONCEPT Cited by 1 source

AI instructions as code

The thesis

When writing documentation for AI agent consumption, treat the instructions themselves as code: versioned, reviewed, iterated, formally structured, with edge cases and conventions made explicit. The instruction document is the load-bearing artefact — more consequential than the choice of model or coding tool.

The 2026-02-03 Instacart post canonicalises this framing:

"We achieved the most consistency and highest accuracy when we stopped writing documentation for humans and started writing instructions specifically for AI consumption. Our 325+ line migration guide is effectively a program that the AI executes. Documentation written for AI agents must be far more explicit. It forces you to articulate conventions, edge cases, and decision points that human developers may or may not intuit. This documentation serves triple duty: AI agents execute it autonomously, human developers use it as a checklist, and code reviewers verify that the steps were followed. Like code, these guides require investment and must be iterated upon. After 5–6 migrations, we refined the guide until the process became highly predictable."

What this implies

If the thesis holds:

  • Instructions have a development cycle. They're authored, reviewed, tested (by running against a sample migration), versioned, and iterated — not just written once.
  • Explicitness is the correctness lever. Implicit conventions that human developers "just know" are where AI misgenerates code; making them explicit is the fix.
  • Triple-duty utility. The same document that the AI executes is also (a) the human engineer's checklist and (b) the code reviewer's verification rubric — the instruction document is a shared contract across three distinct consumers.
  • The migration guide / skill is the team's deliverable, not just the migrated code. Future teams / future migrations reuse the instruction artefact, not the 1:1 code changes.
  • Context window is a budget. Packing the instruction document efficiently matters — see concepts/context-window-as-token-budget and the progressive-disclosure property of Agent Skills.

Observed investment shape

Instacart's arc over Phases 2 + 3:

Stage Instruction artefact Size / structure
Early Phase 2 (manual) Internal migration notes Ad-hoc
Mid Phase 2 (AI-assisted) Markdown migration guide Growing; edge cases captured per migration
Late Phase 2 → early Phase 3 Refined markdown guide 325+ lines; "highly predictable" after 5–6 iterations
Phase 3 (current) Structured Agent Skill 17 steps across 4 stages with progressive disclosure

Each evolution step required engineering investment; each amortised over more migrations than the previous one could.

Why this matters beyond migration

The "instructions as code" framing is a generalisation of context engineering's "not a magic spell but a straightforwardly legible programming problem" stance applied to the specific case of authoritative task specifications vs. transient prompts. Prompts parameterise; instructions define. Both are code; instructions are the durable layer.

Caveats

  • The thesis is about mechanical tasks. For creative / novel-architecture work the instruction document can't fully specify the target — AI judgement remains load- bearing.
  • Instruction quality ≠ AI quality. Even with excellent instructions, AI misgenerations happen; guardrails (tests, CI, engineer checkpoints, visual-parity gates) remain necessary.
  • Explicit-for-AI is more verbose than implicit-for- humans. Reviewers of the instruction document pay the verbosity tax; experienced human engineers may find it over-specified. Triple-duty framing helps but doesn't eliminate the tension.
  • Versioning discipline is non-zero cost. Treating instructions as code means code-review for changes, regression-testing for skill updates, rollback machinery. This is real engineering investment.
  • Instruction sprawl is a risk. A team shipping many task-specific instruction documents can end up with an un-curated skill library; treating them as code includes the discoverability / deprecation / ownership problems code already has.
  • Model capability drift. As models improve, earlier explicit-step instructions may become over- constrained; instructions have a currency too.

Seen in

Last updated · 319 distilled / 1,201 read