Before before we begin...
• (a) Download a coding agent: Claude Code (npm install -g @anthropic-ai/claude-code) or Codex (npm install
• (b) Download Ghostty (ghostty.org) terminal emulator — split your terminal into two panes: one for this
slideshow, one for your coding agent
• (c) Have an IDE open on the side — we recommend Zed (zed.dev)
• (d) Optional: set up voice mode — macOS Dictation, Superwhisper, or your agent's built-in voice mode
Think of a small project you would like to build — something you find interesting but are not sure how to
implement as software yet.
It does not need to be polished or complete. A rough idea is enough.
Later, when we get to prompt engineering, you will get to build it live with a coding agent.
Given a sequence matrix $bold(X) in RR^(n times
d_"model")$ with $n$ tokens: ┌──────────┐
└──┬──┬──┬─┘
where $bold(W)_Q, bold(W)K in RR^(d"model" times │Q ││K ││ V │
d_k)$ and $bold(W)V in RR^(d"model" times d_v)$. └┬─┘└┬─┘└─┬─┘
The attention score from token i to token j: ┌────┴───┴──┐ │
└─────┬─────┘ │
│ Z = A V │
Each output vector is a weighted mix of all value │ Output z │
Attention Is All You Need (Vaswani et al., 2017) 5 / 53
Multi-head attention runs $H$ attention blocks in
parallel on different learned subspaces. ┌────────────────────┐
For each head $h = 1, 2, ..., H$: └─────────┬──────────┘
│ Per-head Q, K, V │
┌─┴──┐ ┌─┴──┐ ┌─┴──┐
with $d_k = d_v = d_"model" / H$. └───┬───┴───────┘
Concatenate all heads: │ Concat(O_1..O_H) │
┌───────┴───────┐
Final output projection: ┌───────┴───────┐
└───────────────┘
Attention Is All You Need (Vaswani et al., 2017)
A Transformer layer combines multi-head attention,
feed-forward networks, and residual connections. ┌─────────────┐
This is the pre-norm variant (used in GPT-2+), where │ Input X_l │
LayerNorm precedes each sub-layer. └──────┬──────┘
For layer $l$, let input be $bold(X)_l$: │ │
│ LayerNorm │ │
Autoregressive generation: predict the next token, append, repeat.
Context ┌───────────┐ ┌───────────┐ ┌─────────────────┐
x_1,...,x_t ──▶│ Tokenizer │──▶│ Embedding │──▶│ Transformer x N │──┐
└───────────┘ └───────────┘ └─────────────────┘ │
┌──────────────────────────────────────────────────────────────────┘
│ ┌─────────┐ ┌──────────────────┐ ┌──────────┐ ┌───────────┐
└─▶│ LM Head │──▶│ softmax(logits/τ)│──▶│ Sample / │──▶│ Next token│
└─────────┘ └──────────────────┘ │ Argmax │ │ x_(t+1) │
▲ └──────────┘ └─────┬─────┘
◁──── append to context, repeat ───────┘
The model sees only its context window. Everything it "knows" must be in the prompt or in its weights.
Language Models are Few-Shot Learners (Brown et al., 2020)
Long prompt ┌──────────┐ Active context ┌──────────────┐ ┌────────────┐
history ───▶│ Window │──▶ (latest tokens)─▶│ Transformer │──▶│ Next token │
│ Selector │ │ forward pass │ └─────┬──────┘
└──────────┘ └──────────────┘ │
└─────────│ Context manager │◁────────────────────────┘
Intuition: the model has a fixed maximum sequence length; the application decides what fits.
• The model's context window is a hard upper bound on input tokens
• The application / harness manages what goes in (truncation, summarization, RAG)
• There is no built-in "sliding window" — context management is an engineering problem
• Tokens that don't fit are never seen by the model
Lost in the Middle: How Language Models Use Long Contexts (Liu et al., 2023)
Intuition: solve hard questions with intermediate steps, not one direct jump.
Question ──▶ Prompt + ──▶ Reasoning steps ──▶ Final answer
context (chain of thought)
• Prompt the model to show its work ("think step by step") • Each reasoning step is generated as tokens in the context
• The model conditions on its own prior steps to reach the answer
Self-verification (checking and revising answers) is a separate technique that builds on CoT but was introduced
Chain-of-Thought Prompting Elicits Reasoning in LLMs (Wei et al., 2022)
Intuition: CoT began as prompting, then expanded into a broader reasoning stack.
2022: CoT ──▶ Self- ──▶ ReAct / ──▶ Search + ──▶ Reasoning-first
prompting consistency tool use planning training
engineering? ─────────────────────▶ Now: prompt + decoding + training
Today, CoT is more than prompt engineering:
• Early stage: "think step by step" prompting
• Next: better decoding and agentic inference
• Later: reasoning-focused training (GRPO, RL)
Self-Consistency (Wang et al., 2022) · ReAct (Yao et al., 2022)
CoT: Optimization Intuition
Analogy: CoT resembles iterative refinement — small steps toward a solution.
Question ──▶ State 0 ──▶ small ──▶ State 1 ──▶ more local ──▶ State T ──▶ Final
└────────────── one-shot jump (hard!) ──────────────────────────────────┘
• Each reasoning step is a small refinement of the solution state
• The sequence of steps forms a trajectory toward the answer
• A single direct jump to the answer is usually harder
This is an analogy, not a formal equivalence — but the intuition holds: decomposition makes hard problems
Chain-of-Thought Prompting Elicits Reasoning in LLMs (Wei et al., 2022)
GRPO (DeepSeek-R1 and OpenAI o1)
Intuition: step-by-step reasoning should be learned 
by the model, not only triggered by prompts.
GRPO adds an RL stage to encourage this behavior
• Sample a group of candidate responses for the
• Score each, then normalize rewards relative to
• Update the policy: upweight above-average,
Goal: make reasoning/search a native behavior of the
DeepSeek-R1 (DeepSeek-AI et al., 2025)
Intuition: with enough RL, reasoning behavior can Table 2 | An interesting "aha moment" of
emerge as a capability, not just a prompt pattern. DeepSeek-R1-Zero.
• An "AHA moment" appears during training: Question: If a > 1, then the sum of the real
behavior shifts from shallow answers to solutions of sqrt(a - sqrt(a + x)) = x is equal to
• The model starts showing self-reflection and Response: <think> To solve sqrt(a - sqrt(a + x)) =
correction more naturally x, let's start by squaring both sides... (sqrt(a -
• Strong gains on reasoning-heavy tasks (math, sqrt(a + x)))² = x² => a - sqrt(a + x) = x².
coding) Rearrange to isolate the inner square root term: (a
• Reasoning quality becomes less dependent on - x²)² = a + x => x⁴ - 2ax² - x + (a² - a) = 0 ...
manually crafted CoT prompts Wait, wait. Wait. That's an aha moment I can flag
here. Let's reevaluate this step-by-step... We
Message: GRPO makes reasoning a learned default started with the equation: sqrt(a - sqrt(a + x)) = x
behavior. First, let's square both sides: a - sqrt(a + x) = x²
=> sqrt(a + x) = a - x² ...
DeepSeek-R1 (DeepSeek-AI et al., 2025)
Limitation: Transformer Scaling
Intuition: transformer reasoning quality scales, but
attention cost scales too. ┌─────────────┐
• Self-attention becomes expensive as sequence └──────┬──────┘
length grows ┌──────┴──────┐
• Longer contexts increase latency and memory │ LayerNorm │
• Practical systems must trade off quality, ┌──────┴──────┐
speed, and cost │ MHA │◁── Attention cost
└──────┬──────┘ grows with length!
Result: long-context reasoning can become ┌──────┴──────┐
bottlenecked by compute. │ Add │
┌──────┴──────┐ Memory/latency
Attention Is All You Need (Vaswani et al., 2017)
Limitation: Context Window Failures
Intuition: fixed context windows can drop old constraints and trigger catastrophic forgetting.
• Only recent tokens remain in the active window
• Older instructions/facts can fall outside the window
• Model may forget them within the same long session
• Performance drops when evidence is deep in the second half of a long context (middle-position weakness)
Result: drift, contradiction, and long-context failures.
This is why harness engineering matters — external memory, chunked processing, and verification loops compensate
for the model's finite attention span.
Lost in the Middle (Liu et al., 2023)
Limitation: Overconfidence
Intuition: confidence and correctness can diverge.
• Model probability is not the same as factual │ Question │
• LMs can sound certain while being wrong ┌─────┴──────┐
• Miscalibration becomes worse on harder or │ Model │
out-of-domain inputs │ answer │
Hallucination is often a composition of multiple │ │
issues: overconfidence + missing evidence + ┌───┴────┐┌┴──────────┐
context/retrieval errors. │ High ││ Actual │
Language Models (Mostly) Know What They Know (Kadavath et al., 2022)
Limitation: Test-Passing != Good Engineering
Intuition: RL for code optimizes what is easy to verify.
• Reward misspecification: pass-at-k and unit tests are proxies, not the full objective
• Proxy gaming: patches can pass tests but still diverge from intended behavior
• Quality blind spots: security, maintainability, and readability can regress while tests still pass
• Optimization bias: GRPO-style objectives can bias response length without better normalization
• Current direction: combine richer rewards (tests + analysis + better judges)
No single loss fully captures "good engineering."
Intuition: a coding agent is an execution loop that turns intent into validated code changes.
What it does: Human role:
• reads repo context and constraints, • set goals and acceptance criteria,
• plans and applies code edits, • review outputs,
• runs tests, linters, and checks, • steer the next iteration.
• reports diffs, risks, and next actions.
│ Context Read │ ──→ files, git, docs
│ Plan + Edits │ ──→ write code
│ Run Checks │ ──→ tests, lints, types
│ Diff + Summary │ ──→ report changes
│ Approve/Revise │ ──→ iterate ↑
Tooling and Language Choices
Intuition: instruction following is strong; engineering discipline is now the bottleneck.
• Agents follow instructions well; human review 
• Prefer languages that surface bugs early
(types, linters, strict compilers)
• Make correctness explicit and violations loud
• TDD and spec-first development matter more
• Encode best practices in AGENTS.md / skills
SWE-bench Multilingual: Rust has the highest
▍ "In this simulated reality, English serves as the underlying 
▍ programming language, where the environment responds only to
▍ statements of absolute logical rigor and zero ambiguity."
▍ "The protagonist discovers that surviving the system requires
▍ 'precise speaking' -- the art of using flawlessly exact
▍ to compel the simulation's infrastructure to manifest one's
— The Cookie Monster (Vernor Vinge, 2003)
▒▒▒▒ Eagerly loaded (before the task starts) ▒▒▒▒ Lazily retrieved (during execution)
• CLAUDE.md / AGENTS.md / .cursorrules — • RAG / embeddings search — pull relevant
always-on project policy snippets on demand
• Custom system prompts — API-level or • Agent tool use — read files, grep, glob as
tool-level instructions needed
• README / docs / specs — project documentation • MCP tool calls — query databases, APIs,
• Pinned / attached files — type definitions, tickets mid-task
configs, schemas • Compiler / linter output — error messages as
• Git state — branch, recent commits, diffs feedback
• MCP servers — expose structured data sources • Test results — pass/fail signals that steer
at session start next steps
• Web search / fetch — external docs, issues,
▒▒▒▒ Reduce what enters the context ▒▒▒▒ Compress what stays in the context
• Serialize repeated logic into a CLI tool — • Summarize state periodically — short summaries
reuse as a tool call over raw logs
• Write skills for reusable prompt procedures • Use compact formats — markdown tables, YAML
• Split big tasks into bounded sub-tasks over verbose prose
• Lazy retrieval over pre-loading — let the • Request diffs, not full files
agent read on demand • Prune irrelevant context — drop old messages,
• Persist state to files (plan.md, checklists) resolved threads
and re-load • Reference file paths instead of inlining full
Anti-Pattern: Over-Obedience Trap
▒▒▒▒ Bad: rigid instruction with wrong assumption 
▍ "Add OpenMP parallelization to the diagonalize function in
▍ src/hamiltonian.jl. Use 8 threads and split the k-point
Problem: you haven't checked if diagonalization is even the
bottleneck, if LAPACK is already threaded, or if the code uses
MPI elsewhere. The model will obey and build the wrong thing.
▒▒▒▒ Good: flexible instruction that invites exploration
▍ "The band structure calculation is slow for large unit cells.
▍ Explore the codebase to find where time is spent and what
▍ parallelism already exists. Propose optimization options
▍ before making changes."
Rule of thumb: constrain the goal, not the method. xkcd #1613 (Randall Munroe, 2015)
▒▒▒▒ Bad: one giant task with no checkpoints ▒▒▒▒ Good: incremental plan with human checkpoints
▍ "Refactor the entire DMRG module to support ▍ "I want to add finite-temperature support to the
▍ finite-temperature ▍ DMRG module.
▍ density matrices. Update the tensor network ▍ Start by reading the current structure and propose
▍ contraction, add ▍ a step-by-step
▍ purification, and fix all the tests." ▍ plan. Ask me before each major change."
Problem: the agent runs for many steps, accumulates
wrong assumptions, silently drifts, and delivers a
large diff you can't easily review.
Rule of thumb: big tasks drift. Break them into plan → checkpoint → execute cycles. Keep the human in the loop.
Anti-Pattern: No Verification
▒▒▒▒ Bad: no way to verify correctness ▒▒▒▒ Good: explicit verification criteria
▍ "Implement the Hubbard model exact diagonalization ▍ "Implement Hubbard model ED for a 4×4 lattice with
▍ 4×4 lattice with periodic boundary conditions." ▍ Verify against the known half-filling ground state
Problem: the agent writes plausible code but you ▍ Add a test that compares with the 2×2 analytical
have no automated check. You read every line ▍ result.
manually, or trust blindly. ▍ Run tests until they pass."
Rule of thumb: always give the agent a way to check its own work. Tests, known results, and assertions turn hope
▒▒▒▒ Why role-playing works ▒▒▒▒ Examples
Language models are autoregressive — each token is ▍ "You are a senior Rust engineer reviewing
conditioned on all previous tokens. A role-playing ▍ code for unsafe blocks and lifetime errors."
prefix shifts the conditional distribution over
every subsequent token. The model prioritizes safety and correctness
concerns over feature suggestions.
▍ "You are a security auditor. Review this
▍ PR for OWASP top 10 vulnerabilities."
When the context begins with "You are an expert in
X", the model's next-token distribution skews toward Activates security-specific vocabulary and patterns
tokens that an expert in X would produce — technical the model learned during training.
vocabulary, deeper reasoning, domain-appropriate
caution. ▍ "Act as a compiler. Read this code and
▍ predict exactly what it outputs for input 5."
This is not anthropomorphism — it is conditional
sampling. The persona prefix is a soft constraint Forces step-by-step execution trace instead of
that biases generation toward a region of the high-level description.
model's learned distribution.
▍ "You are a team: an architect who designs
▍ the API, a security engineer who reviews it,
▍ and a QA engineer who writes edge-case tests.
▍ Discuss the design, then produce the code."
The model samples from multiple conditional
distributions in sequence — architect tokens, then
security tokens, then QA tokens — producing output 31 / 53
that no single persona would.
The Evolution of AI-Assisted Engineering
2021 2022 2023 2024 2025 2026
Copilot ChatGPT GPT-4 o1/Claude 3.5 Claude 4 Claude 4.5
preview (Nov) (Mar) Gemini/MCP o3/Gemini 2.5 Gemini 3
AI-assisted Prompt Agentic Reasoning Vibe Harness
completion engineering prototypes models coding engineering
Each stage was enabled by a step change in model capability — and each exposed the limits of the previous
From Completion to Orchestration
▒▒▒▒ 2021–2023: AI-assisted completion ▒▒▒▒ 2024: Prompt engineering era
• Copilot (2021): autocomplete on steroids — • GPT-4o (May): fast multimodal model
suggests the next few lines • Claude 3.5 Sonnet (Jun): long context, tool
• ChatGPT (2022): conversational code generation use, reliable instruction following
from descriptions • o1 (Sep): first reasoning model — plans
• GPT-4 (2023): first models capable enough for multi-step, self-evaluates
multi-file edits • MCP (Nov): standard protocol for connecting
Human role: author with autocomplete. You still
write the code; the AI fills in boilerplate. Human role: prompt engineer. Craft precise
instructions, manage context, design verification.
Bottleneck: model capability. Models couldn't hold
enough context or plan across files. Bottleneck: prompt quality. Models were capable but
sensitive to how you asked. The techniques in this
lecture — context management, anti-patterns,
verification — come from this era.
From Vibe Coding to Harness Engineering
▒▒▒▒ 2025: Vibe coding ▒▒▒▒ 2026: Agentic / harness engineering
▍ "There's a new kind of coding I call 'vibe ▍ "You are not writing the code directly 99% of the
▍ coding', where you fully give in to the vibes, ▍ time. You are orchestrating agents who do, and
▍ embrace exponentials, and forget that the code ▍ acting as oversight."
▍ ▍ — Andrej Karpathy (Feb 2026)
▍ — Andrej Karpathy (Feb 2025)
Claude 4.5/4.6, Gemini 3, Codex (OpenAI's coding
o3 (Apr), Claude 4 (May), Gemini 2.5 (Jun) — models agent, now at codex-5.4) — models and agents mature
got good enough that you could describe what you together.
want and get working code. Cursor, Windsurf, Claude
Code — the tools matured. Human role: architect and supervisor. Design the
environment, define constraints, build feedback
Bottleneck: production quality. Vibe-coded software loops.
had security gaps, no error handling, unmaintainable
architecture. It worked for prototypes but not for Bottleneck: the harness. Models are strong; the
shipping. constraint is how well you structure the environment
─────────────┼────────────────────────┼─────────────
Completion │ Model capability │ Author
Prompt eng. │ Prompt quality │ Prompt
The engineer's job shifts from writing code to designing the environment in which agents write code.
▒▒▒▒ What is a harness? ▒▒▒▒ OpenAI's experiment (Aug 2025 – Jan 2026)
The full environment of scaffolding, constraints, A small team (3→7 engineers) built a beta product:
and feedback loops that surround an agent and let it
do stable work: • ~1M lines of production code
• 0 lines manually written
• Repository structure and conventions • ~1,500 PRs merged
• CI configuration and test suites • 3.5 PRs/engineer/day
• Linters, formatters, type checkers • ~10× faster than manual development
• Project instructions (AGENTS.md)
• Application frameworks and package managers The agents wrote application logic, docs, CI config,
• External tool integrations (MCP, etc.) observability, and tooling — everything.
▍ Your primary job is no longer to write code, but to design environments, specify intent, and build feedback
▍ loops that allow agents to do reliable work.
Harness engineering: leveraging Codex in an agent-first world (Lopopolo, OpenAI, 2026)
Harness Engineering: Five Principles
1. What the agent can't see doesn't exist. Push all decisions into the repo as markdown, schemas, and exec plans.
An ExecPlan is a self-contained design doc — written so that a beginner could read it and implement the feature
2. Ask what capability is missing, not why the agent is failing. Don't prompt harder — instrument the environment
better. Build custom tools with observability rather than relying on libraries the agent may struggle with.
3. Mechanical enforcement over documentation. Enforce rules through code, not prose. Custom linters and
structural tests fail the build immediately on violation. The linters themselves were written by Codex.
4. Give the agent eyes. Connect DevTools, telemetry, and runtime snapshots. Pre/post-task comparison plus runtime
event observation lets the agent apply fixes in a loop until everything is clean.
5. A map, not a manual. Provide a brief architectural overview showing structure and boundaries — not an
encyclopedia. Architectural invariants are often expressed as "something does not exist here."
Harness Engineering: Architecture
▒▒▒▒ Enforced dependency layers ▒▒▒▒ Documentation as architecture
Each layer can only reference layers above it.
Linter errors inject correction instructions into docs/
the agent's context for self-repair. ├── design-docs/
Types (pure data) ├── exec-plans/
Config (settings) ├── product-specs/
Repo (data access) └── design-system.txt
│ • Root AGENTS.md is a map, not a manual — it
Runtime (orchestration) points agents to the right doc for their task
│ • Agents read only docs relevant to their
UI (presentation) working directory — preserves context window
• Cross-links are mechanically validated by CI
Violations are caught at build time, not code ▒▒▒▒ Entropy management
Background agents continuously scan for drift and
open refactoring PRs — automated garbage collection
Good formalism is your weapon against hallucination.
• Keep asking the model to simplify the code it generates
• Take abstractions seriously — name things precisely, enforce invariants with types
• Prefer strict, verifiable structure over clever but opaque logic
• Formal tools (type checkers, linters, proof assistants) catch errors that natural language reviews miss
▍ "With proof assistants, you don't need to trust the people
▍ you're working with, because the program gives you this
▍ 100 percent guarantee."
The more rigorous your formalism, the less room for hallucination to hide.
Intuition: tools are how agents interact with the world beyond text generation.
▒▒▒▒ Reading and searching ▒▒▒▒ Coordination
• Read — read files by path • AskUserQuestion — ask the human for
• Grep — search file contents by regex clarification mid-task
• Glob — find files by pattern • Agent — spawn sub-agents for parallel work
• LSP — type checking, go-to-definition • TodoWrite — track progress on multi-step tasks
• WebFetch / WebSearch — external docs
▒▒▒▒ Why AskUserQuestion matters
▒▒▒▒ Writing and executing
The agent does not have to guess. When uncertain
• Edit / Write — modify or create files about intent, scope, or a design choice, it can stop
• Bash — run shell commands, builds, tests and ask.
• Git — commits, diffs, branches
This is the cheapest way to prevent drift — a single
clarifying question costs far less than a wrong
Skills are reusable prompt modules that teach the agent a domain or workflow.
▒▒▒▒ What is a skill? ▒▒▒▒ Claude Code
• A markdown file (SKILL.md) with optional
scripts and references $ claude
• Encodes domain knowledge, conventions, and
procedures > /presenterm add a new slide about MCP
• The agent can pick up skills automatically
based on the task — you don't always need to Using skill: presenterm
invoke them explicitly Reading SKILL.md...
• You can also invoke a skill directly with I'll add a new slide using the presenterm
/skill-name format with <!-- end_slide --> separator
▒▒▒▒ Structure and management
├── SKILL.md # instructions
├── references/ # docs, specs $ codex
└── scripts/ # helper tools
> $presenterm add a new slide about MCP
# manage skills with ion: Adding slide with <!-- end_slide -->
ion skill init my-skill separator and setext headers...
Explicit invocation: /skill-name (Claude Code) or
Model Context Protocol (MCP)
Intuition: MCP is a standard interface that lets agents connect to external data and services.
▒▒▒▒ What it is ▒▒▒▒ Why it matters
• An open protocol for tool and data integration • Composability — plug in new capabilities
• Agent connects to MCP servers that expose without changing the agent
tools and resources • Standardization — one protocol instead of
• Servers can wrap anything — databases, APIs, bespoke integrations per tool
SaaS tools, local services • Separation of concerns — the agent reasons,
▒▒▒▒ How it works • Context injection — servers can provide
resources the agent reads on demand
Agent ──▶ MCP Client ──▶ MCP Server ──▶ Service ▒▒▒▒ Examples
tools + resources • GitHub MCP — PRs, issues, code search
exposed as schema • Database MCP — query SQL/NoSQL directly
• Slack MCP — read channels, send messages
• Custom MCP — wrap any internal API
Case Study: Kirin Rust Refactor
▒▒▒▒ What is Kirin? ▒▒▒▒ Harness principles in action
Kernel Intermediate Representation INfrastructure — What the agent can't see doesn't exist — 14 RFCs and
an MLIR-inspired compiler IR framework originally a structured AGENTS.md give agents full
written in Python. architectural context.
The rust branch is a full rewrite, built almost Mechanical enforcement — cargo nextest, cargo fmt,
entirely by coding agents. insta snapshot tests, and custom xtask validators
catch regressions at build time.
A map, not a manual — AGENTS.md lists crate
Metric │ Value purposes, build commands, and conventions concisely.
───────────────────┼───────── Domain-specific skills (derive macros, RFC writing)
Crates │ 21 encode deep knowledge.
Agent skills │ 23 Ask what capability is missing — 23 skills cover
RFCs (design docs) │ 14 everything from RFC authoring to code review to
Derive macros │ 5 crates systematic debugging. When agents struggled, the
response was a new skill — not a longer prompt.
github.com/QuEraComputing/kirin (branch: rust)
Stabilizer Tableau Simulator
▒▒▒▒ The stabilizer formalism ▒▒▒▒ Tableau representation
A stabilizer state $|psi⟩$ on $n$ qubits is uniquely Store stabilizers as a binary matrix — each row is a
defined by $n$ independent Pauli operators $S_i$ Pauli operator:
──┼───┼──────
Example: $|0⟩$ is stabilized by $+Z$. $|+⟩$ is 0 │ 1 │ Z
stabilized by $+X$. The Bell state $|Phi^+⟩$ is 1 │ 1 │ Y
stabilized by $+X X$ and $+Z Z$.
A $2n times (2n + 1)$ binary matrix:
▒▒▒▒ The Gottesman-Knill theorem
• First n rows: destabilizers (track X
Any circuit of Clifford gates (H, S, CNOT) on a operators)
stabilizer state can be simulated in $O(n^2)$ time — • Last n rows: stabilizers (track Z operators)
exponentially faster than full state-vector • Final column: phase bit (±1 sign)
Gates become row operations. Measurement becomes a
Improved Simulation of Stabilizer Circuits (Aaronson search over stabilizer rows.
Demo Step 0: Project Setup
▒▒▒▒ Principle: what the agent can't see doesn't ▒▒▒▒ 3. Symlink for Claude Code
Before writing any code, give the agent a map of the ln -s AGENTS.md CLAUDE.md
▒▒▒▒ 1. Find and install skills with Ion Claude Code reads CLAUDE.md by convention. A symlink
keeps a single source of truth while supporting both
Ion is a CLI skill manager — search for skills, • AGENTS.md — works with any coding agent
install them into your project, and share them with • CLAUDE.md — recognized by Claude Code
your team. The superpower tag covers brainstorming, • Symlink — one file, two names, zero drift
planning, and other agent-boosting skills.
▒▒▒▒ 2. Generate AGENTS.md
▍ Analyze this project and generate an AGENTS.md project/
▍ with conventions, structure, and commit style. ├── AGENTS.md # project instructions
├── CLAUDE.md -> AGENTS.md
AGENTS.md is the agent-agnostic project instruction └── .ion/ # installed skills
file — any coding agent can read it. ├── brainstorm/
Demo Step 1: Scaffold with a Skill
▒▒▒▒ Principle: a map, not a manual ▒▒▒▒ What we expect back
Before writing code, sketch the architecture. Use a
brainstorming skill to let the agent propose the src/
crate structure. ├── lib.rs // pub mod, re-exports
├── tableau.rs // Tableau struct, new(),
├── gates.rs // h(), s(), cnot()
▍ /brainstorm Sketch the module structure for a └── measure.rs // measure_z()
▍ stabilizer tableau simulator crate in Rust.
▍ Based on Aaronson & Gottesman (2004).
▍ Core types: Tableau, PauliRow. ▒▒▒▒ Principle: what the agent can't see doesn't
▍ Gates: H, S, CNOT. Measurement. Display. exist
▍ Propose a module layout and public API,
▍ don't write implementation yet. The brainstorming skill handles this — it invokes a
making-plan skill under the hood and dumps a
structured plan into docs/plan/. Every subsequent
prompt can reference it. The agent reads the plan —
not just your next message.
Demo Step 2: Data Structure
▒▒▒▒ Tableau representation ▒▒▒▒ Principles applied
Initial state |0⟩^n: destabilizer i = X_i, Mechanical enforcement over documentation — the
stabilizer i = Z_i. Display impl is a linter for our encoding. If x/z
bits map wrong, the test fails immediately.
Requiring Display is mechanical enforcement — it
forces the encoding to be correct before we add any Give the agent eyes — cargo test output tells the
gates. agent exactly what's wrong. We don't describe how to
debug; we give it a feedback loop.
The agent reads PLAN.md, implements only tableau.rs,
▍ Implement the Tableau struct from PLAN.md. and verifies with a concrete expected output.
▍ 2n rows of (x: Vec<bool>, z: Vec<bool>,
▍ phase: bool). First n rows destabilizers,
▍ last n stabilizers. Initialize to |0⟩^n.
▍ Implement Display: show stabilizer generators
▍ as Pauli strings with +/− signs.
▍ Add test: 2-qubit tableau prints +ZI and +IZ.
▍ Run cargo test until it passes.
Demo Step 3: Hadamard Gate
▒▒▒▒ Conjugation rules ▒▒▒▒ Principles applied
Hadamard maps: What the agent can't see doesn't exist — we spell
out the Y → −Y rule in the prompt. The paper is not
in the repo, so we bring the critical formula into
On the tableau, for each row and qubit j: Give the agent eyes — two tests:
1. Swap x[j] and z[j] • H|0⟩ → +X checks the basic swap
2. If x[j]=1 AND z[j]=1 after swap, flip phase (Y • HH = I catches sign errors that the first test
▒▒▒▒ Prompt One gate, one file, two tests. Small scope prevents
▍ Add Hadamard gate in gates.rs.
▍ For every row: swap x[j] and z[j].
▍ Then flip phase for rows where x[j]=1 AND
▍ z[j]=1 after the swap — this is the Y → −Y
▍ Tests: H|0⟩ stabilizer becomes +X.
▍ HH = I (apply twice, compare to initial).
Demo Step 4: Phase (S) Gate
▒▒▒▒ Conjugation rules ▒▒▒▒ Principles applied
Mechanical enforcement — the test on |+⟩ is the
minimal case that exercises the phase bit. Tests on
|0⟩ would pass even with the wrong update order (Z
On the tableau, for each row and qubit j: is unchanged by S).
1. phase ^= (x[j] AND z[j]) Ask what capability is missing — if the test fails,
2. z[j] ^= x[j] it's not a prompting problem. We check: did we give
the agent the right formula? The right test state?
Order matters — update phase before z.
We chose |+⟩ specifically because it's the simplest
▒▒▒▒ Prompt state that breaks under wrong operation order.
▍ Add S gate in gates.rs.
▍ For every row: phase ^= (x[j] AND z[j]),
▍ then z[j] ^= x[j]. Order matters — update
▍ Tests: prepare |+⟩ (H on |0⟩), apply S,
▍ stabilizer should be +Y.
▍ Also verify HSH = S† by comparing tableaux.
Demo Step 5: CNOT and Rowsum
▒▒▒▒ CNOT conjugation rules ▒▒▒▒ Principles applied
For each row, control i, target j: What the agent can't see doesn't exist — the phase
formula is given verbatim with a citation. Without
1. x[j] ^= x[i] it, the agent will invent a formula — and it will
2. z[i] ^= z[j] likely be wrong.
3. phase ^= x[i] AND z[j] AND (x[j] XOR z[i] XOR
1) Give the agent eyes — the Bell state test exercises
H and CNOT together. If any phase is wrong upstream,
▒▒▒▒ Verification: Bell state this test catches the composition.
|+0⟩ → CNOT → stabilizers +XX, +ZZ (|Φ+⟩) The CNOT² = I test is free mechanical enforcement —
an invariant that must hold regardless of
▒▒▒▒ Prompt implementation details.
▍ Add CNOT in gates.rs. For every row:
▍ x[target] ^= x[control],
▍ z[control] ^= z[target].
▍ Phase: phase ^= x[control] AND z[target]
▍ AND (x[target] XOR z[control] XOR 1).
▍ Ref: Aaronson & Gottesman Table 2.
▍ Tests: H(0) then CNOT(0,1) on |00⟩ gives
▍ stabilizers +XX, +ZZ. CNOT² = I.
▒▒▒▒ Z-basis measurement on qubit j ▒▒▒▒ Principles applied
1. Search stabilizer rows for one that Give the agent eyes — three levels of feedback:
anticommutes with Z_j (has x[j] = true)
2. If found (random outcome): • Deterministic case (|0⟩ → always 0)
◦ Rowsum to update other anticommuting rows • Statistical case (|+⟩ → both outcomes)
◦ Replace that row with Z_j • Entanglement correlation (Bell → agreement)
3. If not found (deterministic):
◦ Rowsum over destabilizers to compute Each level catches different classes of bugs. The
outcome Bell correlation test is the integration test for
Ask what capability is missing — if Bell
▍ Add measure_z in measure.rs. correlations fail, the bug is likely in rowsum
▍ Search stabilizer rows for x[j]=true. (phase accumulation), not in measurement logic. The
▍ If found: random outcome, rowsum to update test tells us where to look.
▍ other anticommuting rows, replace with Z_j.
▍ If not found: deterministic via destabilizers.
▍ Tests: measure |0⟩ → always 0.
▍ Measure |+⟩ → random (100 runs, both outcomes).
▍ Bell state: measure q0, then q1 must agree.
Demo Step 7: Property Tests
▒▒▒▒ Mechanical enforcement at scale ▒▒▒▒ Prompt
Unit tests verify specific circuits. Property tests ▍ Add proptest dependency. Write a property
verify invariants over all circuits. ▍ test: generate a random 3-qubit Clifford
▍ circuit (5-20 random gates from H(q), S(q),
Key invariant: for any Clifford circuit $U$: ▍ CNOT(q1,q2)). Apply it, then apply its
▍ inverse (reversed gates — H and CNOT are
▍ self-inverse, S inverse is S applied 3 times).
▍ Assert the tableau equals the initial state.
▍ Run cargo test until all tests pass.
The tableau after U then U† must equal the initial
state. ▒▒▒▒ Principles applied
This is the "proof assistant" idea from the Tao Mechanical enforcement over documentation — the
quote — a lightweight formal verifier that catches property test is a linter for correctness across the
bugs no hand-written test was designed to find. entire gate set. No prose review needed.
Give the agent eyes — "run until all tests pass"
creates an autonomous fix loop. The agent sees
failures, diagnoses, and iterates.
