---
name: agentic-engineering-vocabulary
description: "Reverse-lookup glossary of 526 terms for building software with agents, from Harness. Turns a vague description into its exact term (\"the agent should check its own work before showing me\" -> Backpressure; \"it forgot my rule after a long session\" -> Compaction). Use when someone asks \"what's it called when...\", describes a behaviour, failure or practice without knowing its name, or wants the right word and a concrete sentence to say to an agent. For naming a concept, not implementing one."
---

# Agentic engineering vocabulary

Turn a vague description of something in agent-assisted software work into the precise term, so the person knows what to ask for.

## Quick start

The person describes a concept loosely. Return the matching term in this format:

```
**Term**: what it is, in the words of the glossary below.
Say it: the sentence to type to an agent, from the full entry.
```

If several terms could fit, list the best match first, then one or two alternates with a line on how they differ.

## Instructions

1. **Read for intent, not keywords.** People describe symptoms ("it says it is done but nothing works", "it forgot what we agreed"), not the technical name. Map the symptom to the glossary below.
2. **Quote the glossary as written.** Its descriptions are the authority. Do not paraphrase them into something stronger.
3. **Disambiguate close terms.** When two compete, say what separates them so the person can pick.
4. **When nothing matches exactly,** name the closest term and say plainly that it is an approximation.
5. **Stay within this glossary.** If a term is not here, say so instead of inventing one, though you may explain the idea using these words.
6. **Keep it tight.** A naming question wants a name, not an essay. Lead with the term and expand only if asked.

Full entries, with sources and the sentence to say to an agent: https://dev.dqnotes.com/glossary.md

## Glossary

### Before the agent

#### The machine

- **Source code**: The text of a program, written by a person or an agent and saved in ordinary files. It is a precise set of instructions. The computer does what the text says, which is not always what its author meant. Described as: "the text a program is written in", "the actual code behind an app", "what the agent is writing when it writes code".
- **Program**: A set of instructions a computer can carry out. Your browser is a program, and so is the agent you talk to. A program sits in a file doing nothing until something starts it. Described as: "software, an application", "the thing that runs on the computer", "what is the difference between code and an app".
- **Files and folders** (Directory): A file is a named chunk of data kept on a computer. A folder, also called a directory, is a named container for files and other folders, so everything on the machine forms one big tree. Described as: "where things are kept on the computer", "what is a directory", "hidden files I can't see", "what is the .env file and why can't I see it".
- **Code editor** (Text editor, Editor, IDE, VS Code): A program for opening and changing plain text files, made for code. It colours the text so the structure stands out, shows the project's folders down one side, and marks some mistakes as you type. VS Code is a common one. Described as: "where do I open code", "what do programmers type code into", "can I use Word to write code", "what is VS Code", "what is an IDE".
- **CPU and memory** (RAM, Processor): The CPU is the part that carries out instructions, one tiny step at a time, very fast. Memory, or RAM, is the quick short-term space where a running program keeps its instructions and the values it is working on. Described as: "my laptop fan spins up", "it ran out of memory", "what is RAM", "the part that makes a computer fast".
- **Disk** (Storage, SSD): Long-term storage, where files stay when the power goes off. It is much slower than memory. A program that only keeps data in memory loses it when it stops, crashes or the machine restarts. Described as: "everything disappeared when I restarted", "I saved it but it was gone", "what survives a reboot", "storage versus memory".
- **Process** (PID): One running copy of a program, with its own private memory and an ID number called a PID. Start a program twice and you have two processes that know nothing about each other. Each runs until it finishes or something stops it. Described as: "port already in use", "address already in use", "it is still running in the background", "my change is not showing up", "how do I stop a program that is stuck".
- **Terminal** (Command line, Console, CLI): A window where you control a computer by typing instead of clicking, and it answers in text. It looks old-fashioned, but nearly every tool a programmer uses can be driven from it. Described as: "the black window with text in it", "where you type commands", "the hacker screen", "what is a CLI", "the command line".
- **Shell** (bash, zsh): The program inside the terminal that reads your line, works out what you mean, starts the right programs and shows you the result. Common ones are bash and zsh. It can also join programs together, and that is most of its power. Described as: "what actually reads what I type", "what is bash", "what is zsh", "difference between shell and terminal".
- **Command** (Flag, Argument, Option): One line you give the shell: the name of a program, then flags that change how it behaves, then arguments saying what to work on. In rm -r build, rm is the program, -r is a flag and build is the argument. Spaces separate the pieces. Described as: "what do the dashes mean", "what does -rf mean", "my file name has a space and it broke", "the options after a command".
- **Path**: The written address of a file or folder. An absolute path starts from the top, as in /home/you/notes.txt, and means the same everywhere. A relative path, as in src/cart.js, starts from where you are. .. means the folder above and ~ means your home folder. Described as: "no such file or directory", "file not found but it is right there", "what does ../ mean", "what does the squiggle ~ mean", "it only works on my machine".
- **Working directory** (Current directory, cwd, pwd, cd): The folder a shell is standing in right now. Relative paths start from here. pwd prints it and cd changes it. Every process has its own, so a cd inside a script doesn't move the shell you started it from. Described as: "it ran in the wrong folder", "which folder am I in", "cd did not stick", "it installed in the wrong place".
- **Environment variable** (Env var, export): A named setting a process carries with it, such as TZ=Europe/London for its time zone. A program can read it without it being in the code, and passes a copy to any program it starts. A child can't change its parent's copy. Described as: "where does the API key go", "works on my machine but not on the server", "I set it but the program can't see it", "what is a .env file", "what does export do".
- **The PATH variable** ($PATH): An environment variable holding a list of folders. When you type a program's name, the shell looks through those folders in order and runs the first match. If none has it, you get command not found, even when the program is on the machine. Described as: "command not found", "I installed it but it says not found", "it runs the wrong version", "what does adding something to my path mean".
- **Exit code** (Exit status, Return code, $?): The number a program hands back when it ends. 0 means it went fine, and anything else means it didn't. You rarely see it, but the shell keeps the latest one in $?. Automatic checks in software rest on this. Described as: "how does it know a command failed", "exit 1", "it said success but it failed", "error code 127", "what does dollar question mark mean".
- **stdin, stdout and stderr** (Standard streams, Standard output, Standard error): Three channels every process starts with. Stdin is what comes in. Stdout is its results. Stderr is for errors and remarks. On screen, stdout and stderr look alike, but they are separate and can each be sent somewhere different. Described as: "where does the error text go", "I saved the output to a file but errors still showed", "the input and output of a program", "difference between output and error output".
- **Redirection** (2>&1, /dev/null): Sending a stream somewhere other than the screen. > writes stdout to a file, replacing what was there, and >> adds to the end. 2> does the same for stderr. 2>&1 sends stderr wherever stdout is going. /dev/null throws away whatever reaches it. Described as: "what does 2>&1 mean", "save the output to a file", "what is dev null", "the greater-than sign in a command", "hide the output".
- **Pipe** (Pipeline, pipefail): The | character. It feeds one program's stdout into the next program's stdin, so small tools combine: grep ERROR app.log | sort | uniq -c finds lines, sorts them and counts repeats. By default, the whole line reports only the last program's exit code. Described as: "the vertical bar in a command", "feed the output into another command", "tests failed but it says success", "keep only the last few lines".
- **File permissions** (rwx, chmod, sudo, root): Rules saying who may read, write and run each file. ls -l shows them as -rwxr-xr--: three letters for the owner, three for a group, three for everyone else. chmod changes them. root, the administrator account, ignores most of them. Described as: "permission denied", "what does chmod do", "what does rwx mean", "what does sudo mean", "should I use sudo", "the file is there but it won't run".
- **Programming language**: A strict, made-up notation for writing instructions. Python, JavaScript, TypeScript, Go and Rust are all programming languages. Each has exact rules, so a missing bracket is not a typo to read past. It is a program that won't run. Described as: "Python or JavaScript", "what language should I use", "what is this written in", "coding language".
- **Compiler** (Compile, tsc): A program that reads all your source code and translates it into a form a machine can run. If anything is broken, it refuses and produces nothing. Go, Rust and C are compiled. TypeScript's compiler, tsc, checks each value is the right kind and writes JavaScript. Described as: "a build error before it even runs", "translating code into what the machine runs", "it won't compile", "what does tsc do".
- **Interpreter and runtime** (Runtime, Node.js): An interpreter runs source code directly, working through it as it goes, so many problems only appear when reached. A runtime is what a program needs around it while running. Python, Node.js and Bun are examples. The line with compilers is blurry. Described as: "it only crashed when it got to that line", "it worked in the demo then broke later", "what is Node", "what does runtime mean", "runtime error".
- **Package manager** (npm, Registry): A program that downloads code other people have published, from a public store called a registry, and keeps track of what you use. npm, pnpm and Bun do this for JavaScript, and pip and uv for Python. You run it in the terminal like anything else. Described as: "npm install", "how do I get a library", "bun add", "pip install", "where does code I didn't write come from".
- **Dependency** (Transitive dependency, node_modules, Package): Code your project relies on but didn't write. The ones you name, in a file called package.json for JavaScript, are direct. They have dependencies of their own, and those have theirs, so these transitive ones are usually most of what you install, into a folder called node_modules. Described as: "why is node_modules so huge", "I installed one thing and it added hundreds", "what is a transitive dependency", "a library my app needs".
- **Lockfile** (package-lock.json, bun.lock): A file the package manager writes, recording the exact version of every dependency it installed and a fingerprint of its contents. It means everyone, and every automated run, installs the same code. Don't write it by hand, but do keep it in the project. Described as: "it worked yesterday and nothing changed", "works on my machine but not on the build server", "a huge diff in package-lock.json", "should I commit the lock file", "different versions on different machines".
- **Script** (Shell script, set -e, bun run): A text file of commands that run in order, so what you would type by hand happens the same way every time. Projects also give short ones names in package.json, which is what bun run check means. A shell script has to be told to stop at a failure. Described as: "automate the commands I keep typing", "what is bun run", "what does set -e do", "it kept going after an error", "the hash and exclamation mark on the first line".
- **Operating system** (OS, macOS, Linux, Kernel): The program that runs the machine: it shares out the CPU and memory, keeps files on the disk, and starts and stops processes. macOS, Linux and Windows are operating systems. Programs ask it for everything, so a program built for one often won't run on another. Described as: "works on my Mac but not on the server", "Mac versus Linux", "what does the OS actually do", "file name capitals broke the build", "sed gives an error on my Mac".
- **Binary and bytes** (Bit, Byte, Executable): Computers store everything as bits, each one 0 or 1. Eight bits make a byte, which can hold 256 different values. Text, pictures and programs are all runs of bytes, and only the reader decides what they mean. Described as: "ones and zeros", "what is a byte", "the file is gibberish when I open it", "what is a binary", "kilobytes and megabytes".
- **Text encoding** (UTF-8, Unicode, Mojibake): The rule for turning characters into bytes and back. UTF-8 is the usual one today: English letters take one byte, é takes two and 日 takes three. Read with the wrong rule, the same bytes come out as garbage, such as café for café. Described as: "weird characters like é in my text", "accents are broken", "question marks in diamonds", "what is UTF-8", "an emoji broke my text", "garbled text".
- **Your first agent** (Installing an agent, Getting started): A coding agent is a program you install and then start in a terminal, from inside a project's folder. It reads and changes what is there and runs commands, usually asking you first. A project is only a folder, so a new empty one will do. Described as: "how do I actually start", "what do I need to install", "how do I get an agent on my computer", "where do I type to the AI", "do I have to pay for this".

#### The network

- **Client and server**: A client asks and a server answers. A server is only a program on a computer somewhere, waiting to be asked. Your browser is a client. So is a phone app, or a script you run in a terminal. Described as: "which computer does this code run on", "the thing that asks and the thing that answers", "does this run on my machine or theirs", "what is a server, actually".
- **Browser**: The program that turns an address into a page. It asks servers for files, draws what comes back, and runs the code that came with it. Chrome, Safari and Firefox are browsers. Described as: "I clicked and nothing happened", "how do I see what the page is loading", "the panel that shows all the requests", "it works on your side but not in my browser".
- **Frontend and backend** (Client side and server side): The frontend is the code that runs in the user's browser. The backend is the code that runs on your server. Anyone can read the frontend and change what it sends. Nobody outside can read the backend. Described as: "can users change the price", "hiding the button should be enough", "where does the secret key go", "is this code visible to everyone", "someone could just edit the request".
- **URL** (Web address): The address of one thing on the web. https://shop.example.com:443/cart?coupon=SAVE#total has a scheme, a host, a port, a path, a query and a fragment. Each part is read by something different. Described as: "the bit after the question mark", "what does the # do in an address", "the link looked like my bank but went somewhere else", "the address has weird percent signs in it".
- **DNS** (Domain Name System): The internet's address book. It turns a name like shop.example.com into the numeric address of a computer. Answers get saved along the way, and each one says how long it may be kept, which is called its TTL. Described as: "I changed the domain but it still shows the old site", "waiting for the domain to update", "how does a name turn into a server", "it works for me but not for my friend after the move".
- **IP address and port**: An IP address identifies a computer on a network, like 203.0.113.10. A port number picks out one program on that computer, because many can be listening at once. Together they say exactly where a message goes. Described as: "address already in use", "the number after the colon", "connection refused", "two things fighting over the same port".
- **Localhost** (127.0.0.1, Loopback): A name that always means this same computer. A server on localhost:5173 answers you and nobody else, because for anyone else the same name means their own machine. Described as: "it says localhost but the page will not open", "can my friend see my local site", "the site only works on my computer", "why can't I open what the agent started".
- **TCP connection** (TCP): A reliable conversation between two programs across a network. Before any data moves, the two sides exchange messages to open the connection, and that costs one full trip there and back. Described as: "too many connections", "the first request is slow and the next ones are fast", "the database ran out of connections", "what happens before the data is sent".
- **HTTP**: The agreed format browsers and servers use to talk. One side sends a request, the other sends back a response. It remembers nothing between requests, so each one has to carry everything the server needs to know. Described as: "what is actually being sent", "how do the browser and server talk", "why does the server forget me between clicks", "what does the http in the address mean".
- **Request and response**: A request is a method (a verb such as GET), a path, some headers (labelled lines of extra information) and maybe a body (the content). A response is a status code (a number saying how it went), some headers and maybe a body. Every feature on the web is built from those two shapes. Described as: "the API is broken but I do not know which side", "what gets sent when I click", "what comes back from the server", "the two halves of a web call".
- **curl**: A command that sends one HTTP request from the terminal and prints what comes back. It takes the browser out of the question, so it tells you whether the server itself works. Described as: "test the server without the website", "send a request from the terminal", "the check passes even though the server returned an error", "how can the agent prove the endpoint works".
- **HTTP method** (HTTP verb, GET and POST): The verb at the start of a request. GET reads, POST creates or submits, PUT replaces, DELETE removes. The method also tells everything between you and the server whether it's safe to send the same request again. Described as: "I clicked twice and got charged twice", "the difference between GET and POST", "is it safe to retry this", "a link deleted something by itself".
- **Status code** (HTTP status): A three-digit number at the top of every response. 2xx means it worked, 3xx means look elsewhere, 4xx means the request was wrong, and 5xx means the server failed. It works like an exit code for the web. Described as: "it says 200 but it failed", "the page says 404", "what does this error number mean", "tell the client to slow down", "the difference between 401 and 403".
- **Header** (HTTP header): A labelled line of extra information on a request or response, such as Content-Type: application/json. Names ignore upper and lower case. Many travel with every request, and you never see them unless you look. Described as: "the hidden information on a request", "where does the content type go", "the extra lines above the body", "I set the cookie in my code and it was ignored".
- **JSON**: A plain text format for data: named values in curly braces (called objects), lists in square brackets, text in double quotes, plus numbers, true, false and null, which means nothing. Most programs on the web send it. Nothing else is allowed, including comments. Described as: "the curly bracket format", "unexpected token in JSON", "the id came back with different digits", "package.json stopped working after I edited it".
- **API** (Web API, Endpoint): The set of requests a program agrees to answer, and the answers it promises to give. It's a contract between two pieces of software, so that neither side has to read the other's code. Described as: "the agent made up a function that does not exist", "how two programs talk to each other", "I changed the backend and the app broke", "the docs for what the server accepts".
- **REST** (RESTful): A style of designing web APIs around things rather than actions: GET /orders/42, not POST /getOrder. The word comes from Roy Fielding's 2000 dissertation, and most APIs called REST follow only part of it. Described as: "how should I name the routes", "should it be getUser or users", "what does RESTful mean", "the agent made a mess of the URLs".
- **Database, briefly**: A program whose whole job is keeping data safe on disk and finding it again quickly. Your server sends it questions over a connection. When your server restarts, its memory is gone, and the database still has everything. Described as: "my data disappeared when I restarted", "it works until I deploy", "where should this be saved", "different users see different lists".
- **Cookie**: A small piece of text a server asks the browser to keep. The browser then attaches it to later requests to that site, by itself. It's how HTTP, which has no memory, comes to know you. Described as: "it keeps logging me out", "login works locally but not in production", "how does the site remember me", "can JavaScript read my login", "a form on another site acted as me".
- **Login session** (Session, Server-side session): The server's memory of a signed-in user. At login it creates a record and gives the browser a long random id in a cookie. Each later request carries the id, so the server can look up who it belongs to. Described as: "I logged out but the old link still works", "how does the server know it is me", "someone copied my cookie", "should I use sessions or tokens".
- **HTTPS and TLS** (SSL): HTTPS is HTTP sent through TLS, an encrypted tunnel. TLS proves you reached the real site, hides what you send, and detects any change on the way. A padlock means the line is private, and says nothing about whether the site is honest. Described as: "the padlock in the address bar", "certificate error", "can people on the wifi see my password", "the agent turned off the security check to make it work".
- **The life of a request** (Latency budget): One click travels through a DNS lookup, a connection, encryption, your server, your database and back. Each step takes time, and they add up. A latency budget says how long the whole trip may take, so you can see which step broke it. Described as: "the page is slow but I do not know why", "where does the time go", "it is fast for me and slow in Australia", "how fast could this possibly be".
- **Caching in the browser and on the way** (HTTP cache, Cache-Control): A saved copy of a response, kept by the browser or by something between you and the server, so the same request needn't travel again. The Cache-Control header sets the rules. It makes sites fast, and it's why people see old versions. Described as: "I deployed but I still see the old version", "it works after a hard refresh", "people are seeing stale data", "why is it downloading the same file again".
- **CDN** (Content delivery network, Edge): A network of servers around the world that keep copies of your files close to users. Requests go to the nearest one, and only a miss has to travel on to your real server, which is called the origin. Described as: "it is slow for people far away", "one user saw another user's page", "the copy near the user", "the site fell over when we cleared the cache".
- **Reverse proxy** (Load balancer, Gateway): A server that stands in front of your real server, takes requests from outside and passes them on. It can handle encryption, share load between copies and cut off slow replies, so "the server" is usually several programs. Described as: "502 bad gateway", "the error is not in my logs", "nginx is in the way", "something between the internet and my app".
- **WebSocket**: A connection that stays open, so either side can send at any moment. It starts as an ordinary HTTP request, and then both sides agree to switch. Plain HTTP can't do this, because there the server only ever answers. Described as: "live updates without refreshing", "how does the chat update by itself", "the page keeps asking the server every second", "the words appear one at a time".
- **Webhook**: A request another company's server sends to yours when something happens, such as a payment clearing. It's an API call the other way round: you give them a URL and wait. Anyone who finds that URL can send to it too. Described as: "the payment company tells my app when something happens", "the customer got the order twice", "how do I know it is really from them", "I can't receive it on localhost".
- **Framework**: A large body of code that makes most of the structural decisions for you, such as how a URL finds its code and where files go. You fill in the gaps. Next.js, Rails, Django and Laravel are frameworks. Described as: "the agent used an old way of doing it", "where do I put this file", "why does this folder name have brackets", "the code it wrote does not match the docs".
- **HTML, CSS and JavaScript**: The three languages a browser understands. HTML says what's on the page, CSS says how it looks, and JavaScript says what it does. Whatever tools an agent uses, these are what finally reach the browser. Described as: "the page looks right but nothing happens", "the styling is wrong", "which language does what", "it is only a visual problem".
- **Server and client rendering** (SSR, CSR, Hydration): Rendering means turning data into a page. Server rendering does it before sending, so the HTML arrives ready to read. Client rendering sends JavaScript that builds the page in the browser. Static rendering does it once, when the site is built. Described as: "the page is blank and then pops in", "I click and nothing happens until it finishes loading", "view source shows almost nothing", "search engines cannot see my content".
- **Timeout**: A limit on how long to wait for something before giving up and reporting failure. Without one, a program waiting on a server that never replies can wait for ever, holding on to everything it was using. Described as: "it just hangs forever", "one slow service took the whole site down", "the spinner never stops", "how long should it wait".

#### Version control

- **Version control** (VCS, Source control): A system that keeps every saved version of a project, with who changed what and when, so you can compare any two versions or go back to one. Git is the one this course uses, and the one you will keep meeting. Described as: "how do I undo what the AI just did", "keeping old versions of my code", "final_v2_really_final.zip", "seeing what changed and when", "going back to when it worked".
- **Repository** (Repo): One project under version control: your files, plus a hidden folder called .git that holds the entire history. Run git init in a folder and it becomes a repository. Delete .git and the history is gone. Described as: "what is that hidden .git folder", "turning this folder into a git project", "where is the history actually stored", "is my project in git".
- **Commit**: A saved snapshot of the whole project, with a message, an author, a time, and a link to the commit before it. Its name is a hash: a long fingerprint worked out from all of that, so identical contents always get the same name. Described as: "saving my progress in git", "a checkpoint I can go back to", "what are those long random codes", "a save point for the code".
- **Diff**: A list of exactly what changed between two versions: the lines removed, the lines added, and a few around them for context. Removed lines start with a minus sign and added lines with a plus. Described as: "seeing what the AI actually changed", "the red and green lines", "comparing two versions of a file", "it says it only changed one thing".
- **Staging area** (Index, The cache): A holding area between your files and the next commit. git add puts a copy of a file there, exactly as it is at that moment, and git commit records only what is there. This lets you commit one change while others wait. Described as: "it committed files it should not have", "only saving some of my changes", "what does git add actually do", "my commit has random stuff in it".
- **Branch**: A name that points at one commit, and moves forward each time you commit on it. It lets you work on one thing without touching the main line. HEAD is git's marker for which branch you are on. Described as: "trying something without breaking the working version", "a separate copy to experiment on", "keeping this work apart from the rest", "what does HEAD mean".
- **Main branch** (main, master, Default branch, Trunk): The branch everyone treats as the real version of the project. Work happens elsewhere and joins it when it is ready. The name is only a convention: many older projects call it master. Described as: "the real version of the code", "it pushed straight to production branch", "master or main, which is it", "where finished work ends up".
- **Merge**: Bringing one branch's work into another. If only one side has moved, git simply slides the branch forward. If both have, it finds the commit they share, combines the two sets of changes, and makes a new commit with two parents. Described as: "combining two versions of the code", "bringing my branch back into main", "what does fast-forward mean", "getting the agent's work into the main code".
- **Merge conflict**: What happens when two branches changed the same lines. Git can't choose, so it stops and writes both versions into the file between markers, and someone has to decide what the file should really say. Described as: "the weird <<<<<<< lines in my file", "git says it can't merge", "two people changed the same thing", "the AI deleted my change when it fixed the conflict".
- **Rebase**: Moving your commits so they start from a newer point, by replaying them one at a time. The result looks as if you began today and worked in a straight line. But each replayed commit is a new commit, with a new hash. Described as: "making my branch look clean before review", "updating my branch with the latest main", "the commit hashes all changed", "squashing my messy commits".
- **Remote** (origin): Another copy of the repository, usually on a server, which yours knows by name. The usual name is origin. Your machine also keeps its last-known note of where the server's branches were, called origin/main. Described as: "the copy on GitHub", "what does origin mean", "it says up to date but it isn't", "is my code on the server or just my laptop".
- **Push and pull** (Fetch): Push sends your commits to the remote. Pull fetches the remote's commits and brings them into your branch. Fetch only downloads, and changes none of your work. Nothing travels until you do one of these. Described as: "getting my code onto GitHub", "getting other people's changes", "it says divergent branches", "my commit is not showing on the website".
- **Pull request** (PR, Merge request, MR): A request, on a hosting site such as GitHub, to merge one branch into another. It shows the diff, collects comments and check results, and keeps the whole discussion attached to the change. Described as: "asking to get my code merged", "the page where people review changes", "what is a PR", "getting someone to check the agent's work".
- **Clone and fork**: A clone is a full copy of a repository on your machine, history included. A fork is your own copy on the hosting site, which you can change without asking anyone and later propose changes from. Described as: "downloading a project from GitHub", "making my own copy of someone's repo", "contributing to a project I don't own", "is it safe to run this repo".
- **.gitignore** (Ignore file): A file listing the names and patterns git should not track, such as dependencies, build output and secrets. Git then behaves as if those files weren't there. It only applies to files git isn't already tracking. Described as: "stop committing node_modules", "it committed my .env file", "I added it to gitignore but git still tracks it", "keeping secrets out of git".
- **Commit message** (Conventional Commits): The note attached to a commit. Its first line says what changed, short enough to read in a list, and the body says why. Conventional Commits is a common format for that first line: fix(cart): stop charging VAT twice. Described as: "what should I write when I commit", "the AI writes useless commit messages", "feat and fix at the start of commits", "nobody knows why this was changed".
- **Small commit** (Atomic commit): A commit that does one thing and leaves the project working. If you need the word "and" to describe it, it is probably two commits. A rename, a bug fix and a reformat are three, even if they happened in the same hour. Described as: "the agent made one giant commit", "too many changes in one commit", "I can't undo just the bad part", "splitting my work up".
- **Revert**: Undoing a commit by adding a new commit that does the opposite. The mistake stays in the history along with its undoing, and nobody else's copy is disturbed. Described as: "undoing a commit that is already on GitHub", "taking one bad change back out", "undo without rewriting history", "the safe way to undo".
- **Reset** (git reset --hard): Moving the current branch to a different commit. Soft leaves your files and staged work alone. Mixed, the default, also clears what is staged. Hard also overwrites your files to match that commit, which destroys uncommitted work. Described as: "the AI wiped my changes", "go back to the last commit and throw this away", "hard or soft reset, which one", "undo my last commit but keep the code".
- **Force push** (git push --force, --force-with-lease): Telling the server to replace a branch with yours, even when that throws away commits it has. A normal push can only add. This one can delete other people's work from the server, and it barely mentions it. Described as: "the push got rejected so it forced it", "my colleague's commit disappeared", "overwriting what is on GitHub", "updates were rejected, what now".
- **Stash**: A shelf for unfinished work. git stash puts your changes to tracked files aside and returns your folder to the last commit, and git stash pop brings them back. New files git isn't tracking yet stay where they are unless you add -u. Described as: "putting changes aside for a moment", "switch branches without committing", "where did my changes go", "save this but not as a commit".
- **Tag**: A permanent name for one commit, usually a release such as v1.2.0. Unlike a branch, it doesn't move when you commit. An annotated tag also records who made it, when, and a message. Described as: "marking a release", "naming a version of the code", "the last version that worked", "v1.0 in git".
- **Blame** (Annotate): A view of a file showing, for each line, the last commit that changed it and who made it. The name is unfortunate: you use it to find out why a line exists, not whose fault it is. Described as: "who wrote this and why", "finding out why this weird line exists", "when did this line change", "every line says the formatter changed it".
- **Bisect**: A way to find the commit that introduced a bug by halving the range. You name a good commit and a bad one, git checks out the middle, you say good or bad, and it halves again. A thousand commits takes about ten tests. Described as: "it worked last week and now it doesn't", "which commit broke this", "finding when the bug started", "too many commits to check by hand".
- **Worktree** (git worktree): A second working folder attached to the same repository, on its own branch. The folders share one history, but each has its own files, its own staged changes, and its own idea of which branch is current. Described as: "running two agents at once on one repo", "agents keep overwriting each other", "working on two branches at the same time", "it committed the other agent's files".
- **Git hook**: A script git runs by itself at certain moments, such as just before a commit or a push. If the script exits with anything other than 0, git stops. Hooks live in your own copy of the repository and aren't part of its history. Described as: "running checks automatically before a commit", "it skipped my pre-commit check", "my hook isn't running", "stop bad code getting committed".
- **GitHub** (Forge, GitLab, Hosting site): A website that hosts git repositories and adds what git lacks: pull requests, reviews, issues, permissions and automated checks on every push. Git is the tool. GitHub is one company's service built around it, and GitLab is another. Described as: "is git the same as GitHub", "the website where my code lives", "stopping people pushing to main", "where the checks and reviews happen".
- **Reflog**: Git's private diary of everywhere HEAD has been: each commit, checkout, reset and rebase. When a commit seems lost, it is usually listed here, and you can walk straight back to it. Described as: "I lost my commits", "the AI reset my branch, can I get it back", "git log doesn't show my work any more", "undoing a bad rebase".
- **Git guardrails**: Rules at three levels that stop dangerous git commands: a deny rule in the agent's settings, a script that inspects each command before it runs, and protection on the server. Each one catches things the others miss. Described as: "how do I stop it force pushing", "stopping the AI deleting my work", "it ran a dangerous git command", "rules the agent can't get around", "what permissions should it have for git".

#### Reading and debugging

- **Reading code**: Working out what code does by following it. You rarely read a file from top to bottom. You start where the program starts, or where the problem showed up, then follow the calls, each place one piece of code starts another, and ignore everything that path never touches. Described as: "where do I even start reading this code", "the file is huge and I am lost", "how do people understand code they did not write", "which parts of this actually run".
- **Variable**: A name for a value the program is holding, like a label on a box. In JavaScript, let means the name can be given a new value later, and const means it can't. Described as: "I changed the price but the total stayed the same", "what is let and const", "a name that stores a value", "why did this not update".
- **Function**: A named piece of code you run by writing its name followed by brackets. It lets one idea be written once and used in many places, and it lets a reader take in the name rather than the details. Described as: "the same code is copied in three places", "what does the word function mean", "a named block of code", "what are the brackets after the name for".
- **Parameters and return values** (Arguments): Parameters are the inputs a function asks for, named in its brackets. The values you pass in are the arguments. return hands one value back to the caller and ends the function, and a function with no return hands back undefined, JavaScript's word for nothing. Described as: "it works out the answer but I get undefined", "it prints the right thing but the result is empty", "what goes in the brackets", "NaN shows up further down".
- **Type**: What kind of value something is: a number, some text (called a string), true or false (a boolean), and so on. The type decides what an operation means, so + adds two numbers but glues two strings together. Described as: "adding two numbers gives 205", "it says NaN", "the number is actually text", "why is this a string".
- **Conditions and loops** (If statement, For loop): A condition (if) runs some code only when a test is true. A loop (for, while) repeats some code until its test turns false. Between them, they decide which lines run and how many times. Described as: "the page froze", "it never stops running", "do this for every item", "only do this if something is true".
- **Lists and objects** (Array, Dictionary): A list, called an array, holds values in order, numbered from 0. An object holds values under names, like a small form. Both live in a box in memory, and a variable holds a pointer to the box, not what is in it. Described as: "I changed the copy and the original changed too", "two variables seem to be linked", "why does the list start at 0", "a list of things with names".
- **Modules and imports**: A module is a file that shares some of what it defines using export. Another file pulls those parts in using import. Anything not exported stays private, so a module's insides can change without breaking the files that use it. Described as: "cannot find module", "does not provide an export named", "how does one file use another", "the agent imported something that does not exist".
- **Null and undefined**: Two ways JavaScript says "nothing here". undefined usually means nothing was ever set, and null usually means someone set it to nothing on purpose. Reading a property of either one crashes the program, with an error you will see often. Described as: "Cannot read properties of undefined", "undefined is not an object", "it says undefined on the page", "it crashes when a field is missing".
- **Exception** (Thrown error): An error that stops the current function and climbs back through whoever called it, until some code catches it using try and catch. If nothing does, the program ends. Described as: "it failed but nothing showed up", "the error just disappears", "what is try and catch", "it fails silently".
- **Stack trace** (Backtrace, Traceback): What a crash leaves behind: the error message, then every function that was running at that moment, newest first, each with a file and a line. It is a map from where it blew up back to where it started. Described as: "a wall of red text", "what are all those lines starting with at", "which line actually broke", "the error points at a file I did not write".
- **Classes and objects**: A class is a blueprint. Each object made from it with new gets its own data and shares the functions, called methods. Inside a method, the word this means the object it was called on. Described as: "what does this mean in code", "this is undefined", "what is the word new doing", "difference between a method and a function".
- **Async and await** (Promise): Slow work, such as a network call, doesn't hold everything up. The program gets a promise of a result and moves on. await pauses one function until its promise finishes, and other code gets to run in the meantime. Described as: "it says done before it has finished", "it prints in the wrong order", "I see Promise object where the value should be", "why does this log 1 3 2".
- **State**: Everything a program remembers at a given moment: its variables, what is in its database, what you have selected. The same function can behave differently depending on state, so a bug can depend on what happened before, not only on what you did just now. Described as: "it only breaks the second time", "it works after a refresh", "it depends on what I did before", "turning it off and on again fixes it".
- **Side effect**: Anything a function does beyond handing back its answer: writing to a database, sending an email, changing something outside itself, even printing. A program's useful work is mostly side effects, and so is most of its risk. Described as: "it sent the email twice", "calling this changes something somewhere else", "it does more than its name says", "a function that writes to the database".
- **Pure function**: A function whose answer depends only on its inputs, and which changes nothing else. Same input, same output, every time. Code that is not pure is called impure, which is no insult: impure code does the useful work. Described as: "it is hard to test because it needs the database", "the same input gives different answers", "a function with no surprises", "it depends on the time of day".
- **Scope and closures**: Scope is which names a line of code can see. A name made inside a function or a block can only be seen there. A closure is a function that keeps hold of the variables around where it was created, even after that code has finished. Described as: "it says the variable is not defined", "it is using an old value", "all the buttons do the same thing", "how does this function still know that".
- **Logging** (Print debugging): Making the program write down what it is doing as it runs, with something like console.log. It lets you see inside a run without stopping it, and what comes back is evidence, not a theory about what happened. Described as: "print statements everywhere", "how do I see the value at this point", "I cannot tell what the code is doing", "add some logging".
- **Debugger**: A tool that runs your program under your control. It pauses on a line you chose, shows you every variable and the call stack, and moves on one step at a time. Browsers have one built in, and so do most code editors. Described as: "pause the program and look around", "go through it line by line", "step through the code", "see every variable at once".
- **Breakpoint**: A mark on a line that tells the debugger to pause there, so the program can run at full speed up to the part you care about. A conditional breakpoint only pauses when a test you wrote is true. Described as: "stop only when this value is wrong", "pause on that line", "stepping through takes forever", "it only goes wrong on the 500th time round".
- **Reproduction** (Repro, Steps to reproduce): A set of steps that makes the bug happen, ideally every time. Without one, you can't tell if a change fixed the bug or if it just didn't happen this time. A bug you can't reproduce isn't fixed, only quiet. Described as: "it only happens sometimes", "it works on my machine", "it happened once and went away", "I cannot make it fail again".
- **Minimal reproduction** (Reduced test case, Delta debugging): The smallest input or program that still shows the bug. You get there by removing things until the failure goes away, then putting the last thing back. What remains is often close to an explanation. Described as: "cut it down to the smallest thing that breaks", "which part of this input matters", "the file is too big to share", "strip it back until it still fails".
- **Hypothesis**: One specific guess about the cause that a single check could prove wrong, such as "the price is already a string by line 40". Debugging goes fastest when you test one at a time and change one thing at a time. Described as: "changing things at random until it works", "the agent keeps guessing", "I changed five things and now it works", "how do I narrow this down".
- **Debugging by halving** (Binary search): Finding a fault by checking the middle. If things are still right there, the bug is in the later half, and if not, the earlier half. Each check rules out half of what is left, so a thousand places takes about ten checks. Described as: "it worked last week and I do not know what changed", "which of these broke it", "cut the problem in half", "too many places it could be".
- **Explain it out loud** (Rubber duck debugging): Explaining the problem line by line to anything at all: a colleague, a pet, a rubber duck. You often spot the mistake part way through, because explaining makes you say what you had only been assuming. Described as: "I worked it out while I was explaining it", "talking it through", "as soon as I asked, I saw the answer", "explaining it to someone who does not know the code".
- **Root cause** (Symptom): The symptom is what you can see going wrong. The root cause is the earliest wrong thing that produced it, and the place where a fix ends it for good. A fix at the symptom only hides it, and it comes back somewhere else. Described as: "the fix just moved the problem", "it keeps coming back", "patching over it", "why was it wrong in the first place".
- **Off-by-one** (Fencepost error): Being wrong by exactly one at an edge: stopping a step too early or too late, or miscounting because lists number from 0. A list of 5 has positions 0 to 4, so position 5 is off the end. Described as: "the last item is missing", "there is one extra blank row", "undefined at the end of the list", "wrong by exactly one".
- **Heisenbug**: A bug that goes away or changes when you try to look at it, because looking changes the timing or the conditions. The name is a joke on Heisenberg's uncertainty principle. Described as: "it goes away when I add a print", "it only fails in production", "it works in the debugger", "adding logging fixed it somehow".
- **Comments**: Text in a file meant for people, which the program ignores. In JavaScript it starts with //. The useful ones say why the code is the way it is, which the code itself can't tell you. Described as: "the comment says one thing and the code does another", "comments everywhere saying what each line does", "the grey text in the code", "should I ask for more comments".
- **Grep and code search** (ripgrep, Regular expression): Searching every file for some text or a pattern. grep is the old command, and ripgrep (rg) a fast modern one. A regular expression is a small language for patterns: \bprice\b finds the word price, but not priced. Described as: "find everywhere this is used", "where is this in the code", "search the whole project", "is anything still using this".
- **Language server** (Go to definition, LSP): A program running beside your editor that understands your code's structure. It powers go to definition, find references, rename and the red underlines. Because it follows scope and imports, it knows which of five things called total you mean. Described as: "jump to where this is defined", "right click, go to definition", "rename it everywhere safely", "which total does this refer to".
- **Fix loop** (Going round in circles): When an agent tries fix after fix for the same bug, each one plausible, none of them working, some undoing the last. More attempts rarely help when its idea of the problem is wrong. This is the point at which you step in. Described as: "it keeps trying the same thing", "going round in circles", "each fix breaks something else", "the agent is stuck", "tried four times and it is still broken".

### The agent

#### The model

- **Language model** (LLM, Large language model): A program that takes text and outputs a probability for each piece of text that could come next. One piece gets picked and added to the text, and the step repeats. Everything it appears to do is built out of that step. Described as: "what is an AI model actually doing", "how does ChatGPT work", "is it just fancy autocomplete", "why does it sound so convincing".
- **Token**: The unit a model reads and writes: a chunk of text such as a short word, part of a long word, a space plus a word, or a single symbol. Limits are counted in tokens, and so is what you pay. Described as: "why isn't the limit in words", "what counts as one token", "how much text fits", "what am I paying for per million".
- **Tokeniser** (Tokenizer, Byte pair encoding, BPE): The program that cuts text into tokens before the model sees it and joins tokens back into text afterwards. Its vocabulary is fixed in advance, so the same text can count differently on different models. Described as: "why does this short text use so many tokens", "why does Japanese cost more than English", "how does it split text up", "does whitespace cost anything", "minified code token count".
- **Training**: Adjusting a model's numbers over a huge amount of text until it gets better at predicting what comes next. When training ends the numbers are frozen and shipped. Using the model doesn't change them. Described as: "does it learn from what I tell it", "I told it this yesterday", "why does it keep making the same mistake", "how did it learn to code".
- **Knowledge cutoff** (Training cutoff): The date after which a model's training text has little or nothing. Nothing tells it that time has passed, so it describes old versions and old APIs in the present tense unless the prompt says otherwise. Described as: "it used an old version of the library", "it says that function exists but it was removed", "it doesn't know about the new release", "it thinks it is still last year".
- **Inference**: Running a trained model to get output. Each request is worked on separately, and the model itself carries nothing over from one to the next, so it starts every request knowing only what that request contains. Described as: "why doesn't it remember what we did earlier", "it forgot everything in the new chat", "what happens when I send a message", "does each message start from scratch".
- **Context window**: The most tokens one request can involve: instructions, the conversation so far, files read, and the reply. What is outside it can't affect the output, any more than a program can use a file it never opened. Described as: "it forgot what I said at the start", "conversation too long error", "it stopped following my instructions after a while", "how much can it read at once", "prompt is too long".
- **System prompt**: The part of a request set by whoever built the tool rather than typed by the user: the role, the rules, how to use tools. It is still text in the window, read as tokens like everything else. Described as: "the hidden instructions it starts with", "how do I give it permanent rules", "can I make it always do something", "it ignored my instructions".
- **Prompt**: Everything sent to the model in one request: system prompt, tool definitions, earlier messages, file contents and your latest words. In everyday speech it means only what you just typed, which is usually a small part. Described as: "what does the AI actually see", "how do I write a better prompt", "what gets sent when I press enter", "why did my short message cost so much".
- **Sampling** (Temperature, Top-p, Top-k): Choosing the next token from the model's odds, by weighted dice. Temperature stretches or flattens the odds: low favours the likeliest token and high gives rare ones a chance. Top-p and top-k leave unlikely tokens out of the draw. Described as: "how do I make it less random", "what does temperature do", "set temperature to zero", "creative versus precise setting".
- **Non-determinism**: The same input can give different output. Dice are the obvious cause. Even with the dice removed, a hosted model can vary, because of details such as how requests get batched together on the server. Described as: "it worked yesterday and nothing changed", "same prompt, different answer", "why does it give a different result every time", "it passes sometimes and fails other times".
- **Hallucination**: Output that reads as fact and isn't: a package, function, flag or citation that doesn't exist. It is produced by the same step as correct output, so nothing in the text marks it, and confident wording tells you nothing. Described as: "it made up a package that doesn't exist", "that function isn't real", "it cited something that doesn't exist", "it sounds so sure but it is wrong", "why does AI make things up".
- **Sycophancy**: A tendency to produce what the person seems to want rather than what is true: backing down when challenged, praising weak work, confirming your guess about a bug. Described as: "it always says I am right", "you're absolutely right", "it changes its answer when I push back", "it told me my bad idea was great".
- **Confabulated explanation**: An account a model gives of its own behaviour, written as new text rather than read from a record. It may be right or wrong, and it reads the same either way. Asking "why did you do that" gets you a plausible story. Described as: "I asked it why and the answer made no sense", "it gave a different reason each time", "it admitted the mistake, but was that real", "can I trust its explanation of what it did".
- **Tool call** (Function calling): Structured output asking for a named action with arguments, such as read_file on config.json. The model runs nothing. The program around it, which the next chapter calls the harness, decides whether to run it and sends back the result as text. Described as: "how does the AI run commands", "can it actually touch my files", "how does it use tools", "what stops it deleting things", "function calling".
- **Thinking and effort** (Reasoning, Extended thinking, Effort level): Tokens a model produces before its answer, working a problem through, which tends to help on hard tasks. Effort is the setting that controls how much of this happens. More effort costs more and takes longer. Described as: "the thinking dots", "how do I make it try harder", "why is my output token count higher than the text", "can I read its reasoning", "it took ages to answer".
- **Prompt caching**: The provider keeps the processed start of your request for a few minutes. If your next request begins with exactly the same bytes, that part costs a fraction of the price. One changed byte invalidates everything after it. Described as: "why is my bill so high for long chats", "it costs less if I keep the start the same", "cache_read_input_tokens is always zero", "repeated context is expensive".
- **Model tiers**: Providers sell a ladder of models at very different prices. Higher rungs cost more per token, tend to be slower and tend to do better on hard work. The names change often, so check the current list rather than remembering one. Described as: "which model should I use", "is the expensive one worth it", "Opus or Sonnet", "cheap model for simple tasks".
- **Token cost**: What a request costs: the tokens of each kind multiplied by that kind's price per million. Input, cache writes, cache reads and output are all priced separately, and output is the most expensive, five times input on current Claude models. Described as: "how much will this cost", "why was my bill so high", "what does an agent session cost", "input versus output price".
- **Embedding** (Vector embedding): A list of numbers standing for a piece of text, produced so that texts with related meanings get similar numbers. Compare two lists and you get a measure of how related the texts are, even if they share no words. Described as: "search by meaning not keywords", "how does semantic search work", "find related documents", "what is a vector database for".
- **Model benchmarks** (SWE-bench, Leaderboard): A fixed set of tasks that models are scored on so they can be compared. SWE-bench is the best known for coding: given a real bug report from GitHub and the project's code, the model has to produce a change, and tests decide whether it worked. Described as: "which AI is best at coding", "the leaderboard says this one is best", "how do they measure model quality", "is the benchmark score real".
- **Jagged frontier**: Models do some tasks very well and others badly, and the boundary is not where you would guess: two tasks that seem equally hard can fall on opposite sides. The output looks equally polished on both. Described as: "it nailed the hard thing and failed the easy one", "brilliant at one task and useless at the next", "how do I know what it's bad at", "when can I trust it".
- **Fine-tuning**: Training a copy of a model further on your own examples, so that it leans towards your format or style. It changes tendencies. It isn't a way of giving a model your code base, which changes daily anyway. Described as: "can I train it on my code", "teach it our style permanently", "custom model for my company", "make it know my codebase".
- **Stop reason** (stop_reason, Truncated output, max_tokens): A field on each response saying why the model stopped: it finished, hit your token limit, wants a tool run, or declined. It arrives on a success, so code that only reads the text can treat half an answer as a whole one. Described as: "the answer got cut off", "it stopped halfway through the file", "response ends mid sentence", "the JSON from the model won't parse", "it wrote half a file".

#### The agent

- **Agent** (AI agent): A model, a loop and some tools. The model asks for a tool, a program runs it and hands back the result, and this repeats until the model says it has finished. Described as: "AI that actually does things instead of just answering", "it ran commands by itself", "a chatbot versus something that edits my files", "why does it keep going without me".
- **Agent loop** (Agentic loop, Tool loop): The cycle inside every agent: send the context to the model, read its reply, run any tools it asked for, add the results to the context, and send it all again. It ends when the model stops asking for tools. Described as: "it goes round and round until it is finished", "what is it actually doing between my messages", "why does each step take longer and cost more", "the cycle of ask, run, read the result".
- **Harness** (Agent harness, Agentic harness): Everything in an agent except the model: the loop, the tools, the instructions, the permissions, the hooks, the sandbox. It decides what the model sees and what happens to what it asks for. Described as: "everything around the AI that is not the AI", "the setup that makes the agent work", "why does the same model behave differently in different tools", "the part that runs the model".
- **Tool**: A function the harness offers the model, described by a name, a purpose and the inputs it takes. The model can only write a request to use it. The harness checks the request, runs the function and returns the result. Described as: "how does the AI actually run commands", "the list of things it is allowed to call", "giving the agent a new ability", "it can search the web but not my database".
- **Coding agent**: An agent whose tools can read and edit files and run commands, so it can write code, run it, see what broke and try again. Claude Code, Codex and Cursor's agent are coding agents. Described as: "an AI that writes and runs code by itself", "Claude Code, Codex, that kind of thing", "something better than copy pasting from a chatbot", "it tests its own code".
- **Vibe coding**: Building with a model and not reading the code it writes. You accept every change, paste errors back in, and judge only by whether it seems to work. It describes how you work, not which tool you use, and it is fine for throwaway projects. Described as: "I just keep prompting and never read the code", "it mostly works and I do not know why", "accept all and hope", "built a whole app without looking at the code", "is it ok to not review a quick prototype".
- **Agentic engineering** (Vibe engineering, Augmented coding): Building software with coding agents while staying answerable for the result. You set the goal, decide what the checks are, and can explain what shipped. The agent types, and you are still the engineer. Described as: "using AI seriously at work", "the grown-up version of vibe coding", "I direct the agent but I own the code", "what do I call it when I actually check the work".
- **AGENTS.md and CLAUDE.md** (Instructions file, Memory file): A plain text file in your repo that the agent loads when it starts: build commands, a map of the code, things not to do. AGENTS.md is the name shared across tools. CLAUDE.md is Claude Code's own. Described as: "a file that tells the AI about my project", "I keep telling it the same things every session", "where do I put the instructions", "it keeps using npm when we use bun", "what should go in CLAUDE.md".
- **Rules file** (Cursor rules, Path-scoped rules): Instructions that load only when they apply, usually when the agent touches certain files. A rule for database code stays out of the context until the agent opens database code. Described as: "instructions only for some folders", "different rules for the frontend and backend", "the cursorrules thing", "my instructions file is too long".
- **Skill** (Agent Skill, SKILL.md): A folder holding a SKILL.md file: a name, a one-line description and steps to follow, sometimes with scripts beside it. Only the name and description load at first. The agent reads the rest when the description matches what it is doing. Described as: "a saved procedure the agent can follow", "teach it how we do releases once", "it only loads when it is needed", "a reusable prompt with scripts", "it never uses the thing I wrote for it".
- **Slash command**: A word starting with / that you type to make the harness do something right now: clear the context, switch mode, or run a saved prompt. You type it, not the agent. Described as: "the commands that start with a slash", "a shortcut for a prompt I keep typing", "how do I clear the chat", "save this prompt so I can reuse it".
- **Hook** (Agent hook, PreToolUse hook): A script the harness runs at a set moment, such as just before a tool runs or when the agent tries to stop. It can block the action. The model has no say in whether it runs. Described as: "run a script before the agent does something", "block a command no matter what the AI thinks", "make it run the formatter after every edit", "an automatic check on every action".
- **Subagent** (Sub-agent): A second agent the main one starts for a side job. It gets its own context window and its own instructions, and hands back a summary. The thousands of lines it read never enter the main conversation. Described as: "get another AI to do the research", "the main chat is filling up with search output", "a helper agent that reports back", "hand off a side task".
- **MCP** (Model Context Protocol): Model Context Protocol: a standard way for an agent to use tools that live outside it. A server offers tools such as "search issues", and any agent that speaks the protocol can list and call them. Described as: "connect the agent to GitHub or my database", "a plugin for the AI", "how does it talk to other services", "the agent needs to see our issue tracker".
- **Code registry** (shadcn registry, Copy-in registry): A list of code you can pull into your repo as files you own, with a command that works out what else each piece needs. You end up with source in your tree that you can edit, and not a dependency someone else updates for you. Described as: "copy the component into my repo", "should this be a package or a registry", "my agent cannot change the library code", "share components across my projects", "what is a shadcn registry".
- **Permission modes** (Approval mode, Run mode, YOLO mode): A setting for how much the agent may do before it has to stop and ask you. Modes run from asking about nearly everything to asking about almost nothing. Described as: "it keeps asking me to approve everything", "how do I stop all the prompts", "let it run without asking", "yolo mode", "can I make it ask before it deletes things".
- **Allowlist** (Allow rules, Permission rules): A list of actions the agent may take without asking. Anything not on it still stops for approval. Rules like Bash(bun test) are how you cut prompts without turning them off. Described as: "stop asking me about bun test", "approve this command forever", "pre-approve safe commands", "the list of commands it can run", "always allow".
- **Sandbox** (Agent sandbox): A boundary enforced by the operating system that limits what a running command can touch: which folders it can write to, which it can read, and where it can connect. It holds even when the agent has been tricked. Described as: "stop it touching anything outside the project", "what if it runs something bad", "lock the agent in a box", "can it read my SSH keys".
- **Plan mode**: A mode where the agent can read and explore but can't edit your source files. It writes a plan, you read and change it, and only then does the work start. Described as: "make it think before it touches anything", "read only until I say go", "it started coding before I had explained", "show me what you will do first".
- **Agent session** (Thread, Conversation): One run of an agent from its first message to its last, with its own growing context. When it ends, that context is gone unless you resume it, or the agent wrote something to a file. Described as: "it forgot what we did yesterday", "start a new chat or keep going", "one very long conversation", "pick up where I left off".
- **Agent memory** (Auto memory, Memories): Whatever carries over from one session to the next. There is nothing magic in it: it is files, put back into the context when a session starts. Some you write yourself. Some the tool writes for itself. Described as: "make it remember this for next time", "it learned this last week and forgot", "where does it store what it knows about me", "it keeps believing something out of date".
- **Headless mode** (Print mode, Non-interactive mode): Running an agent with nobody at the keyboard: one command, one prompt, and output a script can read. It is how an agent runs on a schedule, or in continuous integration, the automatic checks on a server that chapter 9 covers. Described as: "run it from a script", "an agent in CI", "no one there to click approve", "run it overnight without me", "automate it on a schedule".
- **Levels of autonomy** (Autonomy slider, The five levels): A scale for how much of the work an agent does before a person looks at it. At one end you approve every line. At the other you write a spec and judge only the result. Described as: "how much should I let it do alone", "do I still need to read the code", "should I review everything", "how far can I trust it", "no human looks at the code".
- **Human in the loop** (Approval prompt, Prompt fatigue): A person has to approve at a chosen point before the work continues. That point could be each command, each plan or each merge. Described as: "I just click yes without reading", "approval fatigue", "where should I actually be checking", "it asks me about everything".
- **Destructive actions** (Irreversible actions): Anything that can't easily be undone: deleting data, force-pushing, dropping a table, sending an email, spending money. An ordinary mistake gets another attempt. These may not. Described as: "it deleted my files", "it wiped the database", "can it push over my work", "what should it never be allowed to do", "commands you can not undo".
- **What the agent can reach** (Blast radius of an agent, Agent trust boundary): Everything the agent could touch if it wanted to, or if someone tricked it: your files, your environment variables, your logins, your network. That reach, and not the task you gave it, is the size of what could go wrong. Described as: "what can it get at on my machine", "could a README trick my agent", "it has all my logins", "is it safe to point it at a random repo", "what is the worst it could do".

#### Context

- **Context engineering**: Choosing what the model can see on each request: which instructions, files, tool results and history go in, and which stay out. The prompt is what you say. Context is everything else it reads before it answers. Described as: "what does the agent actually know about my project", "it guessed instead of looking", "getting it the right information", "prompt engineering but for agents", "why better wording did not help".
- **Context budget** (Attention budget): Treating the window as money you spend. Each token that goes in stays in, gets sent again on every later turn, and leaves less room for what comes next. Test logs and whole files are the big purchases. Described as: "what is using up all the space", "why does each message cost more than the last", "how much of the context is gone already", "it has read half the repo", "where did my tokens go".
- **The dumb zone** (Smart zone, Context rot): The informal claim that a model gets worse past some point in its window, so you should stay below it. That reliability falls as context grows has support. Any specific percentage is a working rule, because no one has shown us a measured line. Described as: "it gets worse the longer the session goes", "it got dumber after a while", "how full is too full", "is 40 percent a real number", "the smart zone thing", "it forgets things late in a session".
- **Instruction budget** (Short AGENTS.md): The limit you set on instructions that always load. AGENTS.md goes into every request, so each line has to earn its place on every task, including the many it has nothing to do with. Short and specific beats long and thorough. Described as: "my instructions file keeps growing", "how long should CLAUDE.md be", "the AI generated a huge AGENTS.md", "it ignores half of what I wrote", "does AGENTS.md even help".
- **Progressive disclosure**: Starting the agent with a small entry point and showing it where to look next: a short index now, details when they are needed. A skill's description is the index entry, and its body is the detail. Described as: "only load the instructions when they are needed", "it never uses the skill I wrote", "too many tools are loaded", "a table of contents for the agent", "keep the start small".
- **Just-in-time retrieval** (Just-in-time context, Agentic search): Keeping lightweight pointers, such as file paths and search patterns, and loading what they point to only when it is needed. The agent searches, reads twenty lines and moves on, and never holds the whole repo in view. Described as: "read only the part it needs", "stop reading every file", "it uses an old version of the file", "search first, then read", "look it up when you need it".
- **Codebase map** (Repo map): A short description of how a repo is laid out: which folder does what, and where to begin. It gives the agent a picture of the project without reading it, so its first search is aimed at something. Described as: "it does not know where anything is", "a summary of how the repo is laid out", "it keeps searching in the wrong place", "should I describe the folders", "where do I tell it to start".
- **Pointing at examples** (Prior art): Telling the agent to copy something that already exists: "follow the pattern in src/db/users.ts". One path, and the code does the explaining. It is about the cheapest useful context there is. Described as: "do it the way we already do it", "it invented its own style", "it ignores how the rest of the code looks", "copy this file as a template", "it wrote a new helper when we already had one".
- **Retrieval (RAG)** (Retrieval-augmented generation, BM25): Searching a body of text, taking the top matches and putting them in the prompt so the model answers from them. Keyword search (BM25 is the standard scoring formula) finds exact words. Embeddings find related meaning. Each misses what the other finds. Described as: "make it answer from our documents", "chat with my docs", "do I need a vector database", "it did not find the page that was right there", "search then answer".
- **Context-efficient output** (Context-efficient backpressure): Making your tools print only what an agent can use: one tick when a check passes, and the full output only when it fails. The check still runs in full. Only the reading gets shorter. Described as: "the test output is enormous", "it wastes all its context on logs", "it ran the slow tests twice", "only show me what failed", "it piped the tests through head".
- **Subagents as context hygiene**: Sending noisy work, such as searching or reading big files, to a subagent, so the reading happens in its window and only a short summary comes back to yours. What you are buying is the clean window, not a specialist. Described as: "the search results filled up the chat", "keep the main session clean", "get a helper to do the reading", "are subagents worth it", "it read too many files".
- **Context poisoning**: A mistake that gets into the context and stays: a guess stated as fact, an invented function, a wrong summary. Every later turn reads it again and builds on it, so the agent's own earlier words keep arguing for the error. Described as: "it keeps coming back to the same wrong idea", "I corrected it three times", "it is stuck on a false assumption", "it built everything on a mistake", "it will not let go of it".
- **Drift** (Session drift): A session slowly moving away from what you asked: the scope grows, an early rule stops being followed, the goal changes shape. No single turn looks wrong. You notice when the diff has things in it you never asked for. Described as: "it wandered off from what I asked", "it stopped following my rule after a while", "the change got much bigger than I wanted", "it forgot the point of the task", "it started doing other things".
- **Starting fresh** (/clear, Context reset): Ending the conversation and beginning a new one with empty context, then giving it only what it needs. Your files and commits stay. What it read and said is gone, unless it was written down. Described as: "should I start a new chat", "is it ok to throw the conversation away", "it has gone off the rails", "new task, same chat", "start over but keep what we learned".
- **Compaction** (/compact, Tool result clearing): Replacing older turns with a summary, so a session can continue in less space. Most tools do it automatically near the limit, or when you ask. Whatever the summary leaves out is gone, and nothing flags the loss. Described as: "it forgot my rule after a long session", "the conversation got summarised", "context left until auto-compact", "it lost the error message", "what survives when it compresses".
- **Handoff note** (Structured note-taking): A short file one session writes for the next: what is done, what failed, what was ruled out, what to do next and how to check it. It is all that crosses from one empty context to the next, so it has to stand alone. Described as: "pick up tomorrow where we left off", "notes for the next session", "it starts from scratch every time", "how do I carry on in a new chat", "it tried the same dead end again".
- **Research, plan, implement** (RPI, Frequent intentional compaction): Splitting work into three phases. Research how the code works now and write it down. Turn that into a plan file. Implement from the plan. Each phase starts from the last one's file with a small window, and you review the files. Described as: "it works on small things but fails in a big codebase", "review the plan and not the code", "break the work into stages", "it charged ahead without understanding the code", "RPI".
- **Docs in the repo**: Keeping decisions, plans and how-tos as plain files next to the code, not in a wiki or a chat. The agent can search them with the same tools it uses on code, they change in the same commit as the code, and review covers them. Described as: "where should the docs live", "our wiki is out of date", "it believed an old readme", "keep docs next to the code", "the agent can not see our notion".
- **The repo as the system of record** (System of record): The rule that anything the work depends on lives in the repo, in a form the agent can read. A decision in a meeting, a chat thread or your head doesn't exist for the agent until someone writes it where the agent looks. Described as: "the agent does not know what we decided", "it is all in Slack", "only one person knows how this works", "make the repo the source of truth", "it keeps asking about things we settled".
- **Agent legibility** (Legibility, Ambient affordances): How easily an agent can find out what it needs by itself: names it can search for, errors that say what went wrong, logs it can query, an app it can start. Whatever an agent can't observe, it can only guess about. Described as: "it can not tell what happened when it runs", "it can not find the code by searching", "make the project easier for the agent", "it keeps asking me to check the browser", "the logs are useless to it".

#### The brief

- **Brief**: What you tell an agent before it starts: what to build, why, what counts as finished, and whatever it couldn't work out by itself. It can be one sentence or a page. Anything it leaves out, the agent decides for you. Described as: "I told it what I wanted and got something else", "how much detail do I give the agent", "it built the wrong thing", "what should I write in the prompt".
- **Spec** (Specification): A written description of what something must do, exact enough that two people, or two agents, would build the same behaviour from it. It says what and why, and usually leaves how to the builder. Described as: "a document that says what to build", "write it down before building", "the agent and I keep remembering it differently", "what is the difference between a prompt and a spec".
- **Requirement**: One thing the result must do, stated so that someone could check it. "apply ignores an event older than the newest one for that order" is a requirement. "Handle events properly" is a wish. Described as: "how do I say exactly what it must do", "my request was too fuzzy", "what is a good requirement", "which parts of the prompt actually matter".
- **Acceptance criteria**: The specific checks that decide whether this piece of work is finished, agreed before it starts. Each one passes or fails. The best are written so that a program can run them. Described as: "how do I know when it is actually finished", "the checklist for this ticket", "its tests pass but it is still wrong", "write down what success looks like first".
- **Definition of done**: The list that must be true before anything counts as finished, on every task: say the code type-checks, the tests pass and the docs are updated. You write it once, and it applies to all the work. Described as: "it says done but it is not", "what should finished actually mean", "the same checklist for every task", "done means different things to me and the AI".
- **Scope**: The edges of the job: which files, features and behaviours this task may change, and which it may not. One line of scope can save a long review. Described as: "it rewrote half the project", "it changed files I did not ask about", "the diff is huge", "it only did the bare minimum".
- **Non-goal**: Something that could reasonably be a goal and that you have chosen not to pursue this time. "No offline mode in this version" is a non-goal. "It shouldn't crash" isn't, because nobody was ever going to want crashes. Described as: "it keeps adding things I did not ask for", "it added a settings page nobody wanted", "how do I say not this time", "tell it what we are deliberately leaving out".
- **Edge case**: An input at the limit of what a program expects: nothing at all, exactly one, zero, the largest allowed, the same thing twice, things in the wrong order. Bugs gather here because the usual case is what everybody pictures. Described as: "it works until someone does something odd", "what if the list is empty", "unusual inputs break it", "it only breaks in weird situations".
- **Constraint**: A limit on how the job may be done, rather than on what it must do: no new libraries, under 200 milliseconds, use the database we already have. Described as: "it installed a library I did not want", "it used a different database", "it must stay under a size limit", "it picked an approach we ruled out".
- **Examples** (Specification by example, Few-shot prompting): Showing what you want with concrete inputs and the results they must give, in place of or beside a description. A good one settles what a paragraph leaves open, and it is hard to read two ways. Described as: "it is easier to show than explain", "give it a sample input and output", "here is what I mean", "it keeps misreading my description".
- **Ambiguity**: A sentence that can honestly be read more than one way. A model rarely stops to ask which you meant. It picks a reading and writes working code for it, so nothing looks wrong. Described as: "it took what I said the wrong way", "that is not what I meant", "I meant the other kind", "it could mean two things".
- **Have it interview you** (Interview me): Instead of writing the brief yourself, you ask the agent to question you until it could write it. It finds the decisions you hadn't noticed you were making. Described as: "I do not know what I want yet", "ask me questions first", "help me work out the requirements", "I have not thought this through".
- **Plan**: The steps an agent intends to take, written before it takes them: which files, in what order, what it will check, and what it isn't sure about. Described as: "tell me what you are going to do first", "it charged off in the wrong direction", "it should think before coding", "walk me through your approach".
- **Plan as an artefact** (Plan file, Feature list): A plan saved as a file in the repo, with steps that get ticked off, so that it survives the session. A later agent can pick it up, and a reviewer can see what was meant. Described as: "it lost track of the plan", "keep the plan so the next session can use it", "a checklist the agent works through", "we planned it yesterday and it is gone".
- **Spec-driven development** (SDD, Specifier role): Working so that the spec comes first and stays the main thing: you write and review the spec, and agents produce the code from it. How far this goes varies, from a spec for one task to a spec that replaces code as what you edit. Described as: "write the spec and let the AI generate the code", "the spec is the source of truth", "Spec Kit or Kiro", "edit the document instead of the code".
- **The best spec is code** (Plan through code): The opposite position: write code early, because code that runs answers questions a document can only guess at. A working version or a prototype becomes the description of what you want, and anything written comes after. Described as: "stop planning and just try it", "I will know it when I see it", "the plan looked fine but the code showed it was wrong", "do I need a spec for this".
- **Vertical slice** (Tracer bullet): A small piece of a feature that goes through every layer, from what the user sees down to where the data is kept, so it works end to end even though it does very little. Described as: "it built the whole backend and nothing works yet", "get one thing working all the way through", "nothing can be tried until the end", "build a thin version first".
- **Decomposition**: Splitting a big job into pieces small enough to be done and checked alone, in an order where each piece builds on something already known to work. Described as: "this is too big for one go", "it got lost halfway through", "how do I break this up", "draw the rest of the owl".
- **One task per session**: Start a new session for each separate job, so one job's leftovers don't end up steering, or being paid for by, the next. Described as: "should I start a new chat", "one long conversation for everything", "it is still thinking about the last task", "it got confused after I changed the subject".
- **Spike**: A small throwaway program written to answer one question, such as whether a library can do something or how a function really behaves. You keep the answer and delete the code. Described as: "I am not sure this is even possible", "try it quickly before we commit", "just find out if it works", "a quick experiment to answer one question".
- **Go deep first**: Get one agent doing one hard thing well, with real understanding and real checks, before you run several at once. A setup you can't trust with one agent gives you ten times the mess with ten. Described as: "should I run ten agents at once", "it was faster until I had to fix everything", "do one properly first", "lots of agents and lots of mess".
- **Prototype**: A quick version built to help you decide something, such as which layout or how an interaction should feel. It is meant to be thrown away, and the real one gets built properly afterwards. Described as: "I want to see it before deciding", "a rough version to show people", "try a few options quickly", "mock something up".
- **User story**: One short sentence about who wants something and why, usually written "As a [someone], I want [something], so that [reason]." It starts a conversation and isn't meant to be the whole spec. Described as: "as a user I want", "what is a ticket supposed to say", "tell it who this is for", "why are we building this".
- **Stop condition**: A rule the agent can check that says when to stop: these commands exit 0, or this many tries have been used. It stands in for the agent's own feeling that it has finished. Described as: "it stopped too early", "it kept going for hours", "how does it know when to stop", "it spent all night on one bug".
- **Ask, don't guess** (Never block on the human): A rule for the agent: when the answer changes what gets built and it can't find out for itself, stop and ask instead of quietly picking. People disagree about how often that should be. Described as: "it assumed instead of asking", "it keeps asking me about everything", "it should have checked with me first", "when should it stop and ask".
- **The right word** (Vocabulary, Say precisely what you mean): Using the exact term of the trade instead of a description: "idempotent" for "handles repeats okay", "debounce" for "waits until I stop typing". One word can carry a set of requirements you would otherwise have to spell out, if you know it. Described as: "what is it called when", "I can describe it but I do not know the word", "does it matter what words I use with AI", "how do I ask for this properly".

### The harness

#### Backpressure

- **Harness engineering**: When an agent makes a mistake, you don't just ask it to try again. You change its environment so that mistake can't easily happen again: a line in its instructions, a script it can run, a check it has to get past. Described as: "the agent keeps making the same mistake", "I keep telling it the same thing every session", "how do I stop it doing that for good", "fixing the setup rather than the code".
- **Backpressure** (Back pressure): Any automated check that refuses an agent's work and tells it why, so that it corrects itself before a person is involved. Types, tests, linters and security scanners can all do this. Described as: "the agent should check its own work before showing me", "it told me it was done but it does not even compile", "how do I make it fix its own mistakes", "the checks push back on the agent".
- **Guide** (Feedforward control): A control that acts before the agent does, steering it towards the right thing: an instructions file, a skill, a code template, an example to copy. Described as: "telling the agent how to do things up front", "instructions it reads before starting", "giving it an example to follow", "steering it rather than correcting it".
- **Sensor** (Feedback control): A control that acts after the agent does, observing what it produced so it can correct itself: a test run, a type check, a screenshot, a review. Described as: "checking what the agent actually did", "how do I know it followed the rule", "something that looks at the result afterwards", "proof it did what I said".
- **Computational control** (Deterministic check): A check run by ordinary code, so the same input should give the same answer, usually within seconds. Type checkers, linters and tests are computational. Described as: "a check that always gives the same answer", "a rule the agent can not talk its way out of", "enforced by code, not by asking", "the opposite of asking the AI to check".
- **Inferential control** (LLM as judge): A check where a model forms a judgement: an AI code review, a second agent grading the first. It can notice things no rule can express, such as whether a change makes sense. Described as: "having another AI check the work", "asking the AI to review the code", "AI code review says different things each time", "a check based on judgement".
- **Formatter**: A program that rewrites your code into one fixed layout: spacing, line breaks, quote marks. It doesn't change what the code does, and running it a second time changes nothing. Described as: "the diff is full of spacing changes", "it changed every line but only one thing is different", "a tool that tidies the code automatically", "stop arguing about tabs and spaces".
- **Linter**: A program that reads your code without running it and flags patterns you have decided are wrong. It takes milliseconds and never gets bored. Described as: "something that flags bad patterns automatically", "a tool that complains about code style or mistakes", "red squiggly lines under code", "catch this mistake without running the code".
- **Errors as prompts** (Remediation message): Writing an error message for the agent that will read it: what is wrong, where, and exactly what to do instead. The message goes straight into the agent's next turn, so it works as a prompt. Described as: "the error message does not say how to fix it", "the agent keeps guessing after an error", "make the failure tell it what to do", "the test output is so long it loses track".
- **Type checker**: A program that reads your code without running it and checks that each value is used as the kind of thing it is: no adding text to a number, no asking for a field that isn't there. For TypeScript that program is tsc, and tsc --noEmit only checks. Described as: "red underlines saying the types do not match", "it passed text where a number was meant", "catch mistakes without running the code", "the compiler is complaining about the agent's code".
- **Strict mode**: A setting that makes a type checker stop trusting you in the places it otherwise would. The one that matters most: with it off, a value that could be missing is treated as if it were always there, so the crash waits until the program runs. Described as: "it crashes with cannot read properties of undefined", "the checker said fine and it still blew up on null", "make TypeScript less forgiving", "the agent keeps forgetting the value might be missing".
- **Structural test** (Architecture test, Fitness function): A test about how the code is arranged and not what it computes: which folder may use which, where the database may be touched. It reads the imports (the lines where one file pulls in another) and fails if a forbidden one appears. Described as: "the agent imported the database straight from the page", "keep the layers of the app separate", "enforce the folder structure automatically", "code is reaching into parts it should not".
- **Pre-commit hook**: A script git runs when someone makes a commit. If it exits with anything but 0, the commit is refused. The git chapter showed how one works. The question here is what belongs in it: fast checks only, on what is really going in. Described as: "check the code before every commit", "it let me commit a password", "the commit got rejected by a script", "the hook passed but the bad code went in anyway".
- **Stop hook**: A script the harness runs when the agent tries to end its turn. If the script says no, the agent is told why and has to keep working. Described as: "stop the agent from finishing until the tests pass", "make it keep going until it actually works", "run something when the AI thinks it is done", "it stopped while the tests were still failing".
- **Continuous integration** (CI): Everyone merges their work into the shared code often, and a server builds and tests each change on a clean copy of the project. That server is called CI too, and its green tick or red cross sits on the pull request. Described as: "it works on my machine but nowhere else", "tests should run on every pull request", "the red cross on the pull request", "a server that checks the code", "the agent pushed and nothing checked it".
- **Fast feedback** (Shift left, Fail fast): Run first the checks most likely to fail for each second they take, so a bad change hears no as early as possible. In practice that mostly means cheapest first: format, lint, types, unit tests, then the slow and costly ones. Described as: "waiting ages to find out it failed on something simple", "run the quick checks first", "the pipeline takes twenty minutes", "it only failed at the very end".
- **Quality gate**: A set of conditions work has to meet before it may go further, where failing any one stops it: types clean, tests pass, no new security findings. It answers yes or no, and nobody gets to argue with it on the day. Described as: "all the checks passed and it is still wrong", "nothing can merge until the checks are green", "it built the wrong thing and everything is green", "a list of things the code has to pass".
- **Check fatigue** (False positive, Alert fatigue): What happens when a check says no to good work too often: nobody believes its no any more. Each wrong no is a false positive. So count how often a check's no turned out to be right, and keep it, fix it or demote it on that number. Described as: "everyone just ignores that check", "it keeps failing on code that is fine", "we click override every time", "the AI reviewer always finds something", "too many false alarms".
- **Fail closed**: When a check can't run or crashes, treat that as a failure and stop, rather than letting the work through. The opposite, fail open, lets the work through when the check breaks. Described as: "the check crashed and it let the code through anyway", "what should happen if the check itself breaks", "a scan that quietly stopped running", "it passed because nothing ran".
- **No bypass**: The rule that nobody gets past a check by switching it off: skipping the hook, silencing the error, deleting the failing test. An agent may try any of these, so the rule has to be held by something that can see them, and not by asking. Described as: "it deleted the failing test so the tests would pass", "it used no-verify to get past the hook", "it just added ts-ignore", "the agent turned off the check instead of fixing the code", "all green because it skipped the test".
- **Ratchet**: A rule of thumb: when the agent makes a new kind of mistake, add something that catches that kind from then on. On an old codebase, record today's count of a problem and fail only when it goes up. Quality can then rise, and it can't quietly slip back. Described as: "every mistake becomes a new rule", "making sure it never happens twice", "the setup keeps getting better over time", "turning bugs into permanent checks".

#### Tests

- **Test** (Automated test): A small program that runs your code with a known input and checks the answer. If the answer is wrong it fails, loudly, without a person watching. Described as: "a way to check it still works automatically", "code that checks my code", "so I do not have to click through it every time", "how do I know it did not break anything".
- **Assertion**: The line in a test that compares what happened with what should have happened, such as expect(total).toBe(550). Without one, a test only proves the code did not crash. Described as: "the line that actually checks the answer", "the test passes but checks nothing", "expect something to equal something", "a test with no real check in it".
- **Test runner**: The program that finds your tests, runs them, prints what failed, and exits with a code saying whether everything passed. Examples are bun test, Vitest, pytest and Playwright Test. Described as: "the command that runs all the tests", "the thing that prints which tests failed", "how does it know the tests passed", "npm test or pytest".
- **Unit test**: A test of one small piece of code on its own, usually a function. It runs in milliseconds and points straight at what broke. Described as: "testing one function by itself", "a really small fast test", "test just this bit of the code", "test it without the database".
- **Fixture**: The known starting state a test sets up before it runs: a sample user, a few rows in a table, a file on disk. Good ones are created fresh for each test. Described as: "the sample data a test starts with", "setting things up before the test", "test data", "beforeEach".
- **Test double** (Stand-in, Fake, Stub, Spy, Dummy): Anything that replaces a real part of your system during a test, like a stunt double. It lets you test without charging a real card or waiting on a real server. Described as: "pretend version of a service for testing", "test without calling the real API", "a fake database for the test", "not charging a real card in tests".
- **Mock**: A test double that records how it was called, so the test can check the calls. In casual use, people say mock for any stand-in. Described as: "the test still passes when I break the code", "everything in the test is fake", "checking that a function was called", "the test just tests the mock".
- **Integration test**: A test where several real pieces work together: your code against a real database, or two of your services talking to each other. It is slower, and it finds the bugs that live in the joins. Described as: "test it with the real database", "each part works but together they break", "testing how pieces work together", "the mock passed but production failed".
- **Contract test**: A check that a real outside service still behaves the way your test doubles say it does. If the provider renames a field, this fails, even while everything else stays green. Described as: "the other service changed and our tests did not notice", "our fake no longer matches the real thing", "the API changed under us", "tests pass but the integration is broken".
- **End-to-end test** (E2E test): A test that drives the whole system the way a user would: a real browser, clicking real buttons, against the real app and its database. Described as: "test it like a real user clicking", "a robot that clicks through my site", "make sure the whole thing works together", "test in a real browser".
- **Acceptance test** (Gherkin): A test written from what the customer asked for and not from how the code works. Often written in Given, When, Then sentences that a person can read and a tool can run. Described as: "tests written in plain English", "given when then", "how do we check it does what the customer wanted", "a test the non-programmer can read".
- **Smoke test**: A very quick check that the thing runs at all: it starts, the main page loads, the health endpoint answers. It says nothing about whether it is right, only whether it is on fire. Described as: "just check that it starts at all", "a quick check after deploying", "does the app even load", "the simplest possible test".
- **Test pyramid**: A rule of thumb for the mix: many fast unit tests at the bottom, fewer integration tests in the middle, and very few slow end-to-end tests on top. Described as: "how many of each kind of test", "our tests are too slow", "too many browser tests", "what mix of tests should I have".
- **Flaky test**: A test that sometimes passes and sometimes fails on the same code. Usually the cause is timing, shared state or something outside the test, such as the network or the clock. Described as: "the test passes when I run it again", "it fails sometimes for no reason", "works on my machine but fails in CI", "re-running until it goes green".
- **Regression test**: A test written after a bug, which fails on the old code and passes on the fix. A regression is when something that used to work stops working. Described as: "make sure this bug never comes back", "it worked before and now it does not", "the same bug came back again", "a test for the bug I just fixed".
- **Snapshot test**: A test that saves the output once to a file, then fails whenever later output differs. It tells you something changed. It can't tell you whether the change is good. Described as: "it just saves the output and compares it", "the test failed so it updated the snapshot", "a huge file of expected output", "approved output file".
- **Characterisation test** (Golden master test): A test that records what old code does today, bugs included, so you can change it safely. You are writing down the behaviour before you touch it, without claiming that it is right. Described as: "I need to change old code nobody understands", "lock in what it does now before refactoring", "no tests on this legacy code", "keep the behaviour exactly the same".
- **Test-driven development** (TDD): Writing the test before the code that makes it pass, in very small steps. The test fails first, because the code does not exist yet, and that failure is the point. Described as: "write the tests before the code", "tests first", "how do I stop it writing tests that just match the code", "is TDD worth it".
- **Red, green, refactor** (Red/green TDD): The TDD cycle in three steps. Red: write a test and watch it fail. Green: write just enough code to pass. Refactor: tidy up while the tests stay green. Described as: "watch the test fail first", "the test passed before I wrote any code", "write the test, make it pass, clean up", "how do I know the test can actually fail".
- **Test oracle**: Whatever tells you what the right answer is. It may be a number you worked out by hand, a spec, an old system, or a rule that must always hold. Described as: "how do I know what the right answer should be", "it copied the output into the test", "the expected value came from the code", "who decides what is correct".
- **Coverage** (Line coverage, Code coverage): The share of your code that ran during the tests. It says what ran. It says nothing about whether anything checked the result. Described as: "what percentage of the code is tested", "we have 100% coverage but it still broke", "it wrote tests just to hit the number", "which lines did the tests never run".
- **Tautological test** (Assertion-free test): A test that can't fail, because it compares the code with itself, checks nothing, or only checks something that is always true. Described as: "the test can never fail", "it compares the function with itself", "it says 47 tests pass but they check nothing", "tests that pass whatever the code does".
- **Goodhart's law**: When a measure becomes a target, it stops being a good measure. Point anyone at a number and they will move the number, whether or not the thing it stood for moves too. Described as: "it just games the metric", "the number went up but nothing got better", "it did exactly what I measured and not what I wanted", "the target stopped meaning anything".
- **Mutation testing**: A tool makes one small deliberate bug in your code, such as changing a < to <=, and runs your tests. If they fail, that bug was caught. If they still pass, your tests have a blind spot exactly there. Described as: "how do I know my tests are any good", "break the code on purpose and see if tests notice", "test the tests", "the tests pass but I still do not trust them".
- **Mutation score**: The share of deliberate bugs your tests caught: killed divided by total. 18 of 30 is 60%. It measures how strong the tests are, not how right the code is. Described as: "a percentage for how good the tests are", "what score should we aim for", "how many of the bugs did the tests catch", "the tests are weak but how weak".
- **Equivalent mutant**: A mutant that changes the code but not what it does, so no test could ever catch it. It survives, and that says nothing bad about your tests. Described as: "this mutant can never be killed", "the change makes no difference to the result", "why can I not reach 100% mutation score", "a surviving mutant that is not a real problem".
- **Property-based testing** (Generative testing): Instead of a few examples, you state a rule that must always hold, such as "the shares always add up to the bill". The tool invents hundreds of inputs, and when one fails it cuts it down to the smallest input that still fails. Described as: "test it with lots of random inputs", "a rule that should always be true", "find the smallest input that breaks it", "I can not think of all the cases".
- **Fuzzing** (Fuzz testing): Throwing huge numbers of random or damaged inputs at a program to see if it crashes or hangs. You do not need to know the right answer, only that it should survive. Described as: "throw random garbage at it", "what if someone sends weird input", "it crashes on strange characters", "test the parser with broken data".
- **Empirical verification** (Prove it works, Run it and look): Checking a claim by running the real program on the surface a user touches and looking at what happens: open the page, send the request, read the row in the database. What you saw counts, and what the agent says it saw does not. Described as: "it says it works but did it actually run it", "it compiles but does it work", "open the app and check for real", "show me it working and not just the test output".
- **Invariant**: Something that must always be true, at every moment, whatever happens: a balance never goes below zero, a refunded order never ships, the shares always add up to the bill. It is a plain sentence first and code second. Described as: "a rule that must never be broken", "this should always be true", "the balance must never go negative", "what has to stay true whatever happens".
- **Model checking** (TLC, Explicit-state checking): A tool walks every state a small model of your system can reach, in every order the steps could happen, and checks an invariant in each. If one breaks, it hands you the shortest sequence of steps that gets there. The model is a short description of the design, not your code. Described as: "it only breaks when two things happen at once", "try every possible order of events", "the race only shows up once in a thousand runs", "how do I test all the interleavings".
- **Formal verification** (Formal methods, Proof, Vericoding): Proving that code or a design meets a written specification for all inputs, not only the ones you tried, with a machine checking the proof. It covers what the spec says, under what the proof assumes, and nothing else. Described as: "prove it works for every input", "the proof passed but the code is still wrong", "can the AI formally verify this", "what does formally verified actually mean", "TLA+ or Lean or Dafny".
- **Statechart** (State machine, Finite state machine): A drawing of a system as the states it can be in and the moves between them. Anything not drawn isn't allowed, so a refunded order simply has no arrow to shipped. A statechart adds states inside states, and regions that run side by side. Described as: "the order ended up both shipped and refunded", "too many boolean flags", "a diagram of what state it can be in", "how do I stop impossible states happening".
- **Test tampering** (Reward hacking): Changing the tests so they pass, in place of fixing the code: skipping a test, deleting it, changing the expected answer, weakening the check, or making the code recognise the test's exact input. Described as: "it changed the test to make it pass", "it deleted the failing test", "it marked the test as skipped", "it hard-coded the answer the test wanted".
- **Holdout scenario** (Hidden scenario, Holdout): A test of what the software should do, kept where the agent can't read it or change it. The agent is judged on it afterwards, so it can't fit its work to it. Described as: "tests the agent is not allowed to see", "so it can not just write code to pass the tests", "a secret exam for the code", "checking it against something it never saw".
- **Verification spend** (Verification budget, Where the tokens go): Choosing where a limited budget of tokens and attention goes: mechanical gates, running the real thing, formal checks, or a model reading the code. Each sees things the others can't, so ask what this change could get wrong, and which check could see that. Described as: "which checks are actually worth paying for", "is AI code review worth the tokens", "we cannot run everything on every change", "should this money go on review or on tests".
- **Eval** (Evaluation): A test for an AI system: give it a task, grade the result, and do that many times, because it may answer differently each time. The result is a rate, not a pass or a fail. Described as: "did changing the prompt actually help", "testing the AI and not the code", "it worked once but how often does it work", "measuring how good the agent is".

#### Design

- **Good code** (Changeability): Code that is cheap to change correctly. Two programs can pass the same tests today and differ hugely in what next week's request costs. Working is the minimum, and how easily it changes is what separates them. Described as: "it works but every change takes longer than the last", "small requests have started taking all day", "what does good code even mean", "the tests pass but I am afraid to touch it".
- **Naming**: Choosing what to call things so a reader can guess what they do without opening them. unpaidInvoices tells you something. data tells you almost nothing. Described as: "the agent wrote a second copy of a function we already had", "everything is called data or handler", "I can't find where this happens", "what should I call this".
- **Small functions** (Method length, One Thing): The advice that functions should be short, so each does one thing and has a name that says what. How short is where people stop agreeing. One famous book says very short. Another says too short makes code harder to read. Described as: "this function is too long", "the code has been chopped into so many tiny pieces I can't follow it", "I keep jumping back and forth between functions", "how long should a function be".
- **Cohesion**: How much the things inside one module belong together. High cohesion means that when one part changes, the rest tend to change with it, and nothing unrelated gets dragged along. Described as: "this file has a bit of everything in it", "there is a utils file nobody understands", "why is this function in here", "unrelated things live in the same place".
- **Coupling**: How much one module has to know about another. If changing A forces you to change B, they are coupled. Modules have to talk to each other, so you can't get rid of it. The questions are how much, and whether you can see it. Described as: "I changed one thing and five others broke", "everything depends on everything", "a small fix touched twenty files", "why does the login page care about the invoice code".
- **Separation of concerns**: Keeping different kinds of decision in different places: what the tax rule is, how it is stored, how it is shown. Then you can think about one, and change one, without reading the others. Described as: "one function does the database and the web page and the maths", "I can't test this without running everything", "everything is mixed together in one place", "changing the wording meant reading the SQL".
- **Abstraction**: A simpler way to think about something complicated, leaving out what you don't need right now. save(user) lets you forget about disks and SQL. Every well-named function is a small abstraction. Described as: "a wrapper that doesn't seem to do anything", "hide the complicated part behind something simple", "too many layers to get to the real code", "I just want to call save and not think about it".
- **Leaky abstraction**: An abstraction whose hidden detail shows through anyway, usually at the worst moment. The interface promises something simple, and what sits underneath forces you to care about it after all. Described as: "it worked with the fake and broke on the real one", "I shouldn't have to know this but I do", "the date came back as a string from the cache", "swapping the backend broke things the interface never mentioned".
- **Interface**: Everything one module must know to use another: function names, what they take, what they return, what can go wrong, and any rule that isn't written down anywhere. Described as: "what do I need to know to use this", "someone depended on a thing I never promised", "the function signature", "how the two pieces talk to each other".
- **Deep module** (Shallow module): A module that does a lot behind a small interface. A shallow one has an interface nearly as complicated as what it does, so using it spares you very little. The words are John Ousterhout's. Described as: "I have to call five functions in the right order to do one thing", "this wrapper is as complicated as what it wraps", "a simple front on something complicated", "every caller repeats the same steps".
- **Single responsibility** (SRP): The rule that a module should have one reason to change. "Reason" is the word people miss: Robert Martin means one group of people whose requests cause the change, which isn't the same as doing one task. Described as: "this class does too much", "two different teams keep editing the same file", "one module with too many reasons to change", "my fix for support broke something for finance".
- **SOLID**: Five design rules for code built from classes, under one acronym: Single responsibility, Open-closed, Liskov substitution, Interface segregation and Dependency inversion. They give you words for arguing about design. Described as: "the five principles everyone asks about in interviews", "clean object-oriented design rules", "the agent added interfaces for everything", "senior engineers keep saying this letter word".
- **DRY** (Don't repeat yourself): Don't repeat yourself: each piece of knowledge should live in one place, so changing it means changing it once. It is about knowledge and not about text. Two lines can look alike and mean different things. Described as: "the same thing is written in four places", "I fixed it in one place and missed another", "it copied the code instead of reusing it", "one rule should only live in one place".
- **Rule of three** (Three strikes and you refactor): Put up with the first duplicate. When you are about to write the same thing a third time, extract it. By then you have enough examples to see what is really shared. Described as: "should I merge these two similar functions yet", "the shared function has so many flags now", "when is copying fine", "we made a helper too early and it got worse".
- **YAGNI** (You aren't gonna need it): You aren't gonna need it: don't build something now because you guess you'll want it later. Build it when you do want it. Described as: "it added options nobody asked for", "what if we need this later", "building for a future that may not come", "the agent made it configurable for no reason".
- **KISS** (Keep it simple): Keep it simple, stupid. Prefer the plainest design that does the job, because someone will have to fix it under pressure one day, without its author there to explain it. Described as: "this is too clever", "why is it so complicated for such a small thing", "I just want the plain version", "the agent reached for a design pattern for ten lines of code".
- **Dependency injection** (DI): Passing a function the things it needs, so it doesn't have to go and get them. isExpired(token, now) can be tested at any date. A function that reads the real clock inside can only be tested today. Described as: "I can't test this without the real database", "how do I test something that depends on today's date", "it sends a real email when I run the tests", "the function grabs what it needs from everywhere".
- **Composition over inheritance**: Build behaviour by combining small parts, rather than stacking parent and child classes. Want a client that logs and retries? Wrap the client in something that adds each behaviour, rather than extending it. Described as: "the class hierarchy is five levels deep", "I have to read the parent class to understand this", "changing the base class broke everything", "how do I add behaviour without subclassing".
- **Layered architecture**: Dividing a program into layers, such as interface, rules and storage, where each layer may only use the ones beneath it. The rule about direction is what does the work. Described as: "the database code imports the web page code", "which part is allowed to call which", "keep the layers from leaking into each other", "the agent keeps taking shortcuts across the app".
- **Clean architecture**: Robert Martin's version of layering: business rules sit at the centre and know nothing about databases or web frameworks. Those sit on the outside and depend inwards, so they can be replaced. Described as: "I want to swap the database without rewriting the rules", "the business logic is tied up with the framework", "keep the core free of tools", "dependencies should point inwards".
- **Boundary**: A line in the code where one part hands over to another: your code and the network, one module and the next, your code and a library. What crosses it should be checked and kept narrow. Described as: "the library is used all over the codebase", "we want to replace this vendor and can't", "where should this check go", "keep their types out of our code".
- **Parse, don't validate**: Where data enters, turn it into a type that can only hold good data, rather than checking it and passing the original along. After that nothing needs to check again, and nothing can forget to. Described as: "we check the same thing in five places", "someone forgot to check before calling it", "the number came in as a string and got added wrong", "it passed validation and still broke later".
- **Make illegal states unrepresentable**: Design your data so that a wrong combination can't even be written down. An order that is both cancelled and shipped should be impossible to express, rather than something every function must remember to check. Described as: "an order somehow ended up both cancelled and shipped", "these two flags should never both be true", "we keep adding checks for things that should not happen", "how did the data get into this state".
- **Refactoring**: Changing how code is organised without changing what it does, in small steps, running the tests after each one. If the behaviour changed, it wasn't refactoring. Described as: "clean this up without breaking it", "the agent said refactor and rewrote the lot", "tidy the code first and then add the feature", "the behaviour changed during the clean-up".
- **Code smell**: A pattern in code that suggests a problem without proving one: a very long parameter list, one module reaching into another's data, the same switch in five places. It is a prompt to look, and it isn't a verdict. Described as: "something feels off but it works", "this code looks wrong and I can't say why", "warning signs in code", "the review bot keeps listing style complaints".
- **Technical debt**: A metaphor: taking a shortcut now is like borrowing. You get the feature sooner, and then you pay interest on every later change until you pay it back. Described as: "we took a shortcut and now everything is slower", "when do we clean this up", "we have to pay for that later", "it keeps getting slower to add features".
- **Cyclomatic complexity** (McCabe complexity): A count of the separate paths through a function: one, plus one for each fork, such as if, a loop, a case or &&. More paths mean more to understand and more tests to cover them. Described as: "too many ifs in this function", "how complicated is this, as a number", "a tool says the function is too complex", "so many paths through this code".
- **CRAP score** (Change Risk Analysis and Predictions): One number combining how complicated a function is with how little of it the tests run. Complicated and untested scores terribly. Simple or well tested scores low. The formula is complexity squared, times untested fraction cubed, plus complexity. Described as: "which functions are risky to change", "complicated and has no tests", "one number for how scary this code is", "the agent split everything up to hit the metric".
- **Duplication detection** (Clone detection): A tool that finds code repeated across a project, usually ignoring names so that a renamed copy still counts. It hands you candidates, and you decide whether they are really the same idea. Described as: "find all the copy-pasted code", "the agent keeps rewriting things that already exist", "how much of this is duplicated", "the same code with different variable names".
- **Slop** (AI slop): Agent output that works and that nobody would have chosen to keep: checks for cases that can't happen, comments that restate the code, helpers with one caller. The tests pass, which is how it gets in. Described as: "it works but it feels bloated", "this looks AI generated", "so many comments saying what the code does", "why is this 50 lines".
- **Agent sprawl** (Overbuilding): An agent building more than you asked for: extra files, options and layers for a small job. Each addition is reasonable on its own, and the total is a bigger thing to carry for as long as the code lives. Described as: "I asked for a small thing and got a framework", "it added ten files for one button", "the diff is far bigger than the request", "why did it build all this".
- **Monolith and microservices**: A monolith is one program, deployed as one thing. Microservices split it into many small programs that talk over a network, each deployed by itself. One is simpler to run. The other lets teams move separately. Described as: "should we split this into services", "one big app or lots of small ones", "everything has to be deployed together", "the agent can't run the whole system locally".
- **Architecture decision record** (ADR): A short text file in the repo recording one design decision: the situation, what was decided, and what it will cost. You don't rewrite it later. A new record replaces the old one. Described as: "why did we build it this way", "the agent undid something on purpose", "we keep having the same argument", "write down what we decided".
- **Simple versus easy**: Easy means close at hand or familiar. Simple means not tangled together. The two are independent: a tool can be easy to start with and leave you a knot. Rich Hickey drew this line in a 2011 talk. Described as: "it was easy to build and now it is a knot", "quick to start and painful to change", "what is the difference between simple and easy", "these two things should not know about each other".

#### Review

- **Green doesn't mean right** (Verification gap): A passing check only proves what it checked. When one agent writes the code and its tests, all of them can pass while the code does the wrong thing, because the tests came from the same misunderstanding. Described as: "all the tests pass but it still does the wrong thing", "CI is green so why is it broken", "the agent wrote the tests and they prove nothing", "it passes but I do not trust it".
- **Code review**: Someone other than the author reads a change before it joins the main branch and decides whether it should. It is a judgement about the change, made by a person or an agent, on top of whatever the automatic checks said. Described as: "someone checks my code before it goes in", "getting a second opinion on a change", "what happens to a pull request before merging", "who approves the code".
- **Reading a diff**: A diff shows a change rather than a program: red lines went away, green lines arrived, and plain lines are context. You read it for what changed, and for what should have changed and did not. Described as: "the whole file shows as changed", "it re-indented everything and I cannot see what changed", "the red and green lines in a pull request", "how do I read what the agent changed".
- **What to look for, in order**: A review has an order: is this the right change, is it designed sensibly, does it work, is it tested, can it be read. Style comes last, because a linter should be handling it. Described as: "what am I supposed to check in a review", "I do not know where to start with a big change", "I only ever comment on style", "a checklist for reviewing code".
- **Blast radius**: How far a change can reach: everything that imports it, calls it or relies on how it behaves, directly or through something else. A one-line change to shared code can have a bigger blast radius than a thousand new lines nobody uses yet. Described as: "what else could this change break", "a tiny change took everything down", "how many things depend on this file", "I changed one line and something unrelated broke".
- **Self-evaluation bias**: An agent marking its own work gives itself too high a mark. It checks what it meant to build rather than what it built, and from the inside those look the same. Described as: "it says everything is perfect", "the AI always thinks its own code is fine", "I asked if it was sure and it said yes", "it graded its own homework".
- **A fresh agent**: A new session with none of the conversation that produced the code, handed the diff and the spec and asked to judge it. It has no history to defend and no memory of why any of this seemed like a good idea. Described as: "have another AI check it without the backstory", "start a new session just to review", "a second opinion from something that did not write it", "it keeps defending its own code".
- **The reviewer's prompt**: The words you give an AI reviewer. They set how hard it pushes, and they can move the verdict more than the code does. So the prompt is a setting with a cost on each side, and you choose it knowingly. Described as: "the AI reviewer always finds something", "it never approves anything", "how do I word the prompt for a code review", "changing the prompt changed the verdict".
- **Findings must show evidence**: A review finding has to come with what proves it: the line, the input, what happens and what should happen. A finding without that is an opinion, which is worth having, and which should not stop a merge. Described as: "the reviewer complains but cannot show the bug", "prove it", "how do I know this review comment is real", "it sounds right but is it actually a problem".
- **Review in the abstract** (Abstract review): Reading code with nothing to check it against: no run, no stated intent, no question to answer. The reviewer fills the gap with what can be said about any code, which means small style points and warnings about things you may not need. Described as: "the reviewer only talks about style", "it keeps telling me I do not need this", "a review full of nitpicks and no bugs", "the AI review comments are all noise", "how do I keep the reviewer on behaviour".
- **AI code reviewers**: A product that reads your pull requests with a model and leaves comments on the lines it doubts. Most of them comment and leave the decision with a person. Described as: "a bot that comments on my pull requests", "should I let an AI approve my code", "automatic code review tools", "copilot left comments on my PR".
- **You own what you merge**: Whoever merges a change answers for it, whoever or whatever typed it. That means being able to say what it does, what could go wrong, how you would notice, and how you would undo it. Described as: "the AI wrote it so whose fault is it", "who is responsible for AI generated bugs", "I got blamed for code the agent wrote", "can I say the agent did it".
- **Code owners** (CODEOWNERS): A file in the repo that maps paths to the people or teams responsible for them, so a pull request touching those paths automatically asks the right reviewer. On GitHub it can also be made a requirement for merging. Described as: "the right person never gets asked to review", "make sure payments code goes past the payments team", "automatically assign reviewers by folder", "anyone can approve changes to the sensitive bit".
- **Comprehension debt**: The gap between how much code exists and how much of it anyone understands. Like money borrowed, it costs nothing today, and you pay later, in the time it takes to work out the code before you can safely change it. Described as: "nobody understands this code any more", "it works but I have no idea how", "the agent wrote it and now I am scared to touch it", "we are shipping code nobody has read".
- **Cognitive debt**: A close cousin of comprehension debt, and many writers use the two as one. Where a difference is drawn, this one is about people rather than code: a team gradually losing its shared picture of how the system works and why. Described as: "the team has lost track of how this works", "nobody can explain why it was built like this", "everyone is afraid to change things", "we move fast but understand less each week".
- **Explain it back**: Before accepting code, say what it does in your own words, including what it does on awkward inputs, then check yourself by running it. If reality disagrees with you, you have just found what you did not understand. Described as: "I read it and it made sense but could I explain it", "check I actually understand this", "quiz me on this code", "could I defend this in an interview".
- **The review bottleneck**: The point where agent-written work piles up waiting for someone to read it. Writing code got cheaper and reading didn't, so the queue in front of reviewers is now what limits how fast a team ships. Described as: "my pull requests sit there for days", "we write code faster but ship no faster", "everyone is waiting on reviews", "the agents produce more than we can read".
- **Small pull requests**: Keeping each pull request to one reviewable idea, often a few hundred lines at most. Long changes get split so that each piece makes sense and passes its checks by itself. Described as: "the pull request is huge", "nobody wants to review this", "how big should a change be", "it is too much to read in one go".
- **Stacked diffs** (Stacked pull requests): A long change split into a chain of pull requests, each built on the one before it, so each can be reviewed alone and you don't have to wait for the first to merge before writing the next. Described as: "one PR depends on another one", "I do not want to wait for review before starting the next part", "chain of small pull requests", "split a feature into reviewable pieces that build on each other".
- **Making work reviewable**: Doing the work so a reviewer can check it cheaply: one idea per pull request, a description saying what changed and why, and pasted evidence that it works, with the output of what you ran. You spend your time to save theirs. Described as: "what should go in a pull request description", "make this easy for someone to review", "the description says it works but how do they know", "help the reviewer".
- **Nit** (Nitpick): A review comment marked as small and optional: a matter of polish that the author can take or leave. The label tells them not to hold the change up for it. Described as: "a small comment on a pull request", "this is not important but", "what does nit mean", "the reviewer keeps picking on tiny things".
- **Blocking and non-blocking**: A blocking comment must be dealt with before the change can merge. A non-blocking one is advice. Saying which one you mean is half of what makes a review useful. Described as: "does this comment have to be fixed before merging", "which review comments actually matter", "the reviewer left twelve comments", "must fix or nice to have".
- **LGTM** (Looks good to me): Short for "looks good to me": the usual way to approve a pull request. It is supposed to be a claim that you read it and would stand behind it. Described as: "what does LGTM mean", "how do I approve a pull request", "I just said it looked fine", "someone approved it in ten seconds".
- **Rubber-stamping**: Approving without really reviewing, because the last fifty were fine and there are ten more waiting. The approval still gets recorded, so from outside it looks exactly like a review. Described as: "I approve everything without really reading it", "review has become a formality", "it is always fine so I stopped looking", "I clicked approve on autopilot".

### Everything it can get wrong

#### Security

- **Threat model**: A short written answer to: what are we building, what can go wrong, what will we do about each thing, and did that work? It turns "be secure" into a list you can check. Described as: "how do I work out what could be attacked", "I want the agent to think like an attacker before it builds", "what should I worry about in this design".
- **Attack surface** (Hardening): Every place someone outside can send your system something: forms, URLs, uploads, webhooks, headers, and any file or page your agent reads. The bigger it is, the more you have to defend. Described as: "how many ways in does my app have", "the agent added an endpoint I never asked for", "what can someone outside actually reach".
- **OWASP Top 10**: A list of the ten most serious kinds of web application risk, kept by the non-profit OWASP and updated every few years. The trade uses it as shared vocabulary, and it is a good first checklist for a review. Described as: "is there a standard list of what to check", "what are the most common web vulnerabilities", "what does A01 mean".
- **Injection**: Text from a user gets pasted into something another program reads as instructions: a database query, a shell command, a web page. The program can't tell which part you wrote, so the user's text can become commands. Described as: "user input ends up running as code", "someone typed a command into my form", "why is joining strings dangerous".
- **SQL injection** (SQLi, parameterised query, prepared statement): SQL is the language for asking a database for things, as in SELECT * FROM users WHERE name = 'alice'. Paste a user's text into that sentence and they can rewrite the question. A parameterised query sends the value separately, so it can only ever be a value. Described as: "someone logged in by typing a quote", "a search box returned every user", "how do I stop people messing with my database queries".
- **Cross-site scripting** (XSS): An attacker gets their text into your page, and the visitor's browser runs it as code. That code runs as your site, with the visitor's logged-in session, so it can do whatever they can. Described as: "someone put a script in a comment", "an alert box popped up on my site", "user text is running in the browser".
- **Output encoding** (escaping, contextual encoding): Converting a value when you put it into a page, so the browser reads it as text. The right conversion depends on where it lands: inside a tag, in an attribute, or in a link are three different problems. Described as: "I escaped it and it still ran", "what is the right way to put user text in a link", "do I escape on the way in or the way out".
- **CSRF** (cross-site request forgery): Another website makes your visitor's browser send a request to your site. The browser attaches their cookie automatically, so your server sees a logged-in user asking to do something they never asked for. Described as: "another site made my user do something", "a link deleted something while logged in", "why does a form need a hidden token".
- **SSRF** (server-side request forgery): A feature fetches a URL the user gave it, such as an image from a link. The attacker gives it an internal address, and your server, which sits inside your network, fetches what the attacker could never reach. Described as: "my server fetched something internal", "the image URL feature can reach my database", "can a user make my server call things".
- **Path traversal** (directory traversal, dot dot slash): A filename from a user includes ../, which means "the folder above", until it climbs out of the folder you meant to serve. Then your server hands over files you never meant to expose. Described as: "someone downloaded a file outside the folder", "dot dot slash in a URL", "can a user read my config by changing the filename".
- **Open redirect**: A link on your own site sends visitors wherever a parameter says, as in /login?next=... An attacker sends a link that starts with your trusted address and ends on theirs, ready for a convincing fake page. Described as: "the login page sends people to another site", "phishing link that starts with my domain", "how do I check a return URL".
- **Input validation**: Checking that what arrives is what you expect, in type, length and format, and refusing it if not. It must run on the server, because anyone can skip the browser and send the request directly. Described as: "the browser check got skipped", "should I block special characters", "how do I make sure the data is sensible".
- **Memory safety** (Buffer overflow, Use after free, Memory-safe language): Code is memory-safe when it can't read or write memory it doesn't own. C and C++ leave that to the programmer, so one wrong length can overwrite whatever sits next to it. Languages like Rust, Go, Java and Python check it for you, or won't let you write it. Described as: "what is a buffer overflow", "it crashed with a segfault", "should we rewrite this in Rust", "what does memory-safe mean", "the agent wrote a native module".
- **Authentication** (authn, login): Proving who someone is: a password, a code from their phone, a passkey. The result is usually a session, so the server recognises them on every later request. Described as: "how does the site know who I am", "should I build my own login", "proving a user is really them".
- **Authorisation** (authz, authorization, permissions): Deciding what a known user may do, on this thing, right now. The server has to decide on every request, because anything in the browser can be changed by the person using it. Described as: "a normal user could do admin things", "who is allowed to do what", "being logged in is enough to do anything".
- **Broken access control**: The server fails to enforce what a user may do, so they can do it anyway: open an admin page, change a role, act on data that isn't theirs. It tops the OWASP list. Described as: "I can see the admin page by typing the URL", "the button is hidden but the API still works", "a normal user changed their own role".
- **IDOR** (insecure direct object reference, BOLA): The kind of broken access control you can do with a keyboard. /invoices/1003 is yours, so you try /invoices/1004 and get a stranger's, because the server looks up the id and never asks whose it is. Described as: "changing a number in the URL showed someone else's data", "I can see other people's orders", "walking through ids one by one".
- **Password hashing** (salt, Argon2id, bcrypt): Storing a scrambled form of a password that can't be turned back. At login you scramble what they typed and compare. It has to be deliberately slow, and salted with a random value for each user. Described as: "how should I store passwords", "the database got leaked, what can they do", "why is login meant to be slow".
- **Encryption in transit and at rest** (TLS, AES-GCM, encryption at rest): Scrambling data so only someone with the key can read it. In transit protects it on the wire, and that is what HTTPS does. At rest protects it on disk. Each covers one place, and neither stops a request your app treats as valid. Described as: "is the data safe if someone steals the disk", "what does encrypted at rest actually protect", "someone on the Wi-Fi can see the traffic".
- **JWT** (JSON Web Token, alg none): A login token the server signs and the browser sends back. It has three parts: header, payload, signature. The payload is only encoded, so anyone can read it. The signature proves it hasn't been changed, if the server checks it properly. Described as: "I decoded my login token and can read it", "what is the long string with two dots", "can a user change their role in the token".
- **Secret** (API key, credential, token): A value that grants access: a password, an API key, a signing key. It belongs outside the code, in an environment variable or a secret manager, and it should only ever be readable by what needs it. Described as: "I pasted my API key into the code", "I committed my password", "where should the key go".
- **Secret scanning** (gitleaks, push protection): A tool that searches your code and history for things that look like keys. It looks for known shapes, like an AWS key, and for strings that look too random to be ordinary text. That second measure is called entropy. Described as: "how do I stop keys getting committed", "can a tool find passwords in my repo", "GitHub blocked my push because of a key".
- **Least privilege**: Giving each person, program and agent only the access its job needs, and no more. Then when one of them is fooled or compromised, the damage stops at what it could reach. Described as: "why does this token have admin", "the agent has my whole AWS account", "how much access should this actually have".
- **CORS** (cross-origin resource sharing): A browser rule: a script on one site can't read a response from another site, unless that site's server says it may. The server says so in a header, Access-Control-Allow-Origin. It only constrains browsers, so curl ignores it. Described as: "the browser says blocked by CORS policy", "it works in curl but not in the browser", "can another website read my API".
- **Content Security Policy** (CSP): A header that tells the browser what this page may load and run: scripts only from here, no plug-ins, no framing. If an attacker's script gets into the page anyway, the browser can refuse to run it. Described as: "the browser refused to run my script", "a header that says what the page can load", "how do I limit the damage from XSS".
- **Security headers**: Lines your server adds to each response that turn on browser protections: always use HTTPS, don't guess file types, don't let other sites frame this page, don't leak the full address when linking out. They take minutes to add. Described as: "my security scan says headers are missing", "how do I stop my site being put in an iframe", "what should curl -I show".
- **Rate limiting** (throttling, token bucket, 429): Capping how many requests one person or address can make in a period, and answering 429 Too Many Requests after that. It makes guessing a password or a code slow enough to be pointless. Described as: "someone is trying thousands of passwords", "too many requests error", "a bot ran up my bill".
- **Supply chain attack** (dependency confusion, install script): Attacking you through something you depend on. A package gets taken over or swapped, you install the update as usual, and its code runs with all the access your program or your laptop has. Described as: "a package I use got hacked", "npm install ran something by itself", "can an update steal my keys".
- **Slopsquatting**: A model invents a package name that sounds right. It fails to install, and that's a clue. Then somebody notices the invented name and registers it with their own code, and now the same mistake installs without a murmur. Described as: "the agent imported a package that does not exist", "someone registered a package the AI made up", "npm install says 404 for a package the code needs".
- **Dependency audit** (npm audit): Checking the versions you have installed against a public list of known vulnerabilities. npm audit is one such command. It can only find what has already been reported. Described as: "npm says I have 12 vulnerabilities", "should I run audit fix force", "how do I know my packages are safe".
- **CVE** (CVSS, vulnerability id): A public id for one known security flaw, such as CVE-2025-54136, so everyone can talk about the same bug. Its severity is usually given as a CVSS score from 0 to 10. Described as: "what does CVE-2025 something mean", "how serious is this vulnerability", "a scanner says critical, should I panic".
- **SAST and DAST** (static analysis, dynamic scan, OWASP ZAP): Two kinds of automated security check. SAST reads your code without running it. DAST runs your app and attacks it from the outside. Each finds things the other can't. Described as: "a tool that scans my code for security bugs", "what is the difference between static and dynamic scanning", "can I test my app by attacking it".
- **Prompt injection** (indirect prompt injection): Text gives a model orders it wasn't meant to take. A model reads your instructions and a web page as one stream of words, so a line in that page can say what to do next. Indirect means it was planted somewhere the agent would read. Described as: "a web page told my agent what to do", "hidden text in a document changed what the AI did", "can someone hack the agent with an email".
- **Lethal trifecta**: Simon Willison's name for three powers that are dangerous together: access to your private data, exposure to untrusted content, and a way to send data out. With all three, a stranger's text can steal your data. Remove any one and that attack has no route. Described as: "is my agent setup dangerous", "which combination of tools is risky", "how could my data get out through the agent".
- **Tool poisoning** (rug pull, MCP poisoning): An MCP tool's description is read by the model, and you usually see a short version. A malicious server hides instructions in it, such as read this file and pass it along. The tool can also change after you approved it, which is called a rug pull. Described as: "can an MCP server be malicious", "the tool description has hidden instructions", "the tool changed after I approved it".
- **OWASP Top 10 for LLM apps** (OWASP LLM Top 10, excessive agency): A separate OWASP list for apps built on language models. Prompt injection is first. It also covers leaks of private data, poisoned models, trusting model output too readily, and giving a model too much power. Described as: "is there a security checklist for AI apps", "what can go wrong with a chatbot on my site", "should I trust what the model returns".
- **Sandboxing an agent**: Having the operating system fence in an agent's commands: which files they can touch and which other machines they can reach. It holds even if the agent is fooled, because it's enforced from outside the model. Described as: "how do I stop the agent reading my keys", "can I run it so it cannot reach the internet", "what does the sandbox actually block".
- **How often AI code is insecure** (Veracode GenAI report): Studies ask models to write code for risky tasks and scan the result. Numbers near half failing get quoted widely. They come from particular tests with particular limits, so they're a warning that this happens, not a rate for your codebase. Described as: "what percent of AI code has security bugs", "is AI-written code less secure", "someone quoted a scary statistic about Copilot".
- **Security review**: Reading a change only for how it could be abused, separately from whether it works. It asks: who can reach this, what can they send, and what's the worst they can do? A person or a fresh agent can do it. Described as: "how do I check the agent did not add a hole", "who reviews this for security", "I want a second look only for attacks".

#### Data and failure

- **Database**: A program whose job is to keep data safe and find it again quickly, while many other programs read and change it at once. Your app asks it questions over a connection. If your app crashes, or the database itself does, what it said it saved is still there. Described as: "where should the data actually live", "can I just use a JSON file", "two copies of the server see different data", "the data vanished when it crashed".
- **Table and row**: A table is a named collection of records that all have the same fields, like a strict spreadsheet. A row is one record, such as one order. A column is one field, such as its total, and every value in it is the same kind of thing. Described as: "it is like a spreadsheet but stricter", "the list comes back in a different order each time", "it put everything in one big JSON column", "how should the data be laid out".
- **Schema** (Constraints): The declared shape of your data: which tables exist, which columns they have, what type each holds, and the rules each must obey, such as not empty, or never below zero. The database enforces those rules on every write, whoever is writing. Described as: "bad data keeps getting into the table", "how do I stop a negative price being saved", "the rule is in the code but a script got round it", "the shape of the database".
- **Primary key**: The column that identifies one row and only one, for ever. It must be present and it must be unique. Usually it's a number or a random id with no meaning, because anything with meaning, like an email address, can change. Described as: "what identifies a row", "two rows are exactly the same and I can not delete one", "the customer changed their email and everything broke", "should the id be a number".
- **Foreign key**: A column in one table that must match the primary key of a row in another. An order's customer_id has to point at a real customer. The database refuses anything that would leave it pointing at nothing, and you choose what happens when the row it points at is deleted. Described as: "the order points at a customer who does not exist", "deleting one thing deleted lots of other things", "cannot delete because something still refers to it", "link two tables together".
- **Unique constraint**: A rule that no two rows may have the same value in a column, or in a set of columns. The database checks it as each row goes in, so it holds even when two people try in the same millisecond. The loser gets an error. Described as: "we got two accounts with the same email", "it checks first and still creates duplicates", "only happens when people double click", "make sure this can only exist once".
- **SQL**: The language for asking a relational database for things. You describe what you want, such as which rows, in what order and how many, and the database works out how to get it. SELECT reads. INSERT, UPDATE and DELETE change. It looks like English, and small mistakes in it can be enormous. Described as: "what is the code talking to the database", "SELECT star from", "it updated every row instead of one", "how do I read what the query does".
- **Query plan** (EXPLAIN): The steps the database chose to answer your query: which table to read first, whether to read all of it or use a shortcut, and how to join. You write what you want, and a part of the database called the planner decides how. EXPLAIN shows you its decision. Described as: "why is this query slow", "how do I see what the database is doing", "it was fast until the table got big", "it ignored my index".
- **Index**: A separate sorted structure that lets the database find rows without reading the whole table, like the index at the back of a book. The usual kind is a B-tree, a wide shallow tree you can walk from top to bottom in a few steps, however many rows there are. Described as: "it was fast in testing and is slow in production", "the search gets slower as we get more customers", "how does it find a row so quickly", "the database is at 100% on one query".
- **N+1 query**: One query to fetch a list, then one more for each item in it. A page of 50 orders that looks up each order's customer separately makes 51 trips to the database. Each is fast, and the page is slow. One query can usually fetch them all. Described as: "the page gets slower the more rows it shows", "hundreds of tiny queries in the log", "each query is fast but the page is slow", "it fetches them one at a time in a loop".
- **ORM** (Object-relational mapper): A library that lets you work with database rows as objects in your language, and writes the SQL for you. Prisma, Drizzle, Django and Active Record have one. It's convenient, and it hides how many queries a single innocent line of code will run. Described as: "the library that writes the SQL for me", "one line of code ran fifty queries", "I can not see what it is sending to the database", "should I write raw SQL".
- **Transaction**: A group of database changes that succeed or fail as one. You BEGIN, make the changes, then COMMIT. If anything fails before the COMMIT, or the power goes, none of them happened. Moving money is the classic case: the debit and the credit must both happen, or neither. Described as: "it crashed halfway and now the data is wrong", "the money left one account and never arrived", "make these changes all or nothing", "half of it saved".
- **ACID**: Four promises a transaction makes. Atomic: all of it or none. Consistent: your rules still hold afterwards. Isolated: others don't see it half-done. Durable: once it's committed it stays, through a crash. It's a word you'll hear in interviews, and each letter is something you can break. Described as: "what does ACID stand for", "is the data safe if the power goes", "it said saved and then it was gone", "what guarantees does this database give me".
- **Isolation level**: How much one transaction can see of others running at the same moment. Stronger levels hide more, and may refuse a transaction and make it retry. Weaker levels let strange things through. Dirty read, non-repeatable read and lost update are the names of those strange things. Described as: "two users at once see weird results", "the number changed in the middle of my report", "the database told it to retry the transaction", "it only happens under load".
- **Race condition**: A bug where the result depends on who gets there first. Two people buy the last ticket: both read one left, both subtract one, both write zero. Two sales, one ticket. Each step was right, and the bug was the order they ran in. Described as: "it only goes wrong when two people do it at once", "we sold more than we had", "the count is lower than it should be", "I can not reproduce it on my machine", "two requests overwrote each other".
- **Locks and atomic updates** (SELECT FOR UPDATE, Optimistic locking): Three ways out of a race. An atomic update does the maths inside one statement: SET stock = stock - 1. A lock makes others wait: SELECT ... FOR UPDATE. A version check lets everyone try and makes the loser start again. Try them in that order. Described as: "how do I stop them overwriting each other", "we added a lock and it still happens", "make the second one wait", "I need to read it and then change it safely".
- **Deadlock**: Two transactions each hold something the other wants, so neither can move. One locked row A and wants B, and the other locked B and wants A. They would wait for ever, so the database notices the cycle, kills one of them, and that one has to try again. Described as: "deadlock detected", "two things stuck waiting for each other", "it fails randomly and works when retried", "everything froze until something got killed".
- **Migration**: A script that changes the structure of a live database, such as adding a column, and is kept in your repo so that every copy can run it in order. The hard part is that, for a while, old code and new code are running against it at once. Described as: "the site went down when we changed the database", "it worked locally and broke on deploy", "change the database without downtime", "the column does not exist", "the migration has been running for ten minutes".
- **Expand and contract** (Parallel change): Making a breaking change in safe steps. Add the new thing alongside the old, have the code write to both, copy the old data over, move reads across, stop using the old, and only then remove it. At each step the old and the new code both work. Described as: "rename a column without downtime", "how do I change this without breaking the running site", "old and new code at the same time", "do it in stages so I can stop halfway".
- **Backup and restore**: A backup is a copy of your data, kept somewhere a mistake can't reach it. A restore is getting it back. Until you have really done a restore, you don't know the backup works, and a replica doesn't count, because it copies your mistakes too. Described as: "can we get the data back", "we have backups, I think", "how far back can we restore", "the replica deleted it too", "nobody has ever tried restoring".
- **Partial failure**: When some of the work happened and some didn't, and you may not be able to tell which. On one machine, a thing either ran or it crashed. Across a network, you sent a request and heard nothing: it might have failed, or it might have worked and the reply got lost. Described as: "they were charged but there is no order", "it half worked", "the request timed out but did it go through", "one service succeeded and the other did not".
- **Idempotency** (Idempotency key): An operation is idempotent if doing it twice has the same effect as doing it once. A client makes that true of a payment by sending a unique key with the request. The server saves the first result against that key, and a repeat gets that result back and charges nothing. Described as: "the customer got charged twice", "is it safe to retry this", "I pressed the button twice", "the same thing happened two times", "the retry created a duplicate".
- **Retry and backoff** (Jitter, Retry storm): Trying a failed call again, and waiting longer each time. Backoff is the growing wait. Jitter is making each wait random, so that clients which failed together don't all come back together. Without those, retries can keep a struggling server down. Described as: "everything came back at once and it fell over again", "how long should it wait before trying again", "the retries made the outage worse", "it keeps hammering the server", "thundering herd".
- **Delivery guarantees** (At-least-once, At-most-once, Exactly-once): What a message system promises. At most once: it may be lost, and it never repeats. At least once: it won't be lost, and it may arrive twice. Most systems you use give you at least once, so your code has to cope with seeing the same thing again. Described as: "the webhook came in twice", "we shipped the order two times", "the job ran twice", "can the message get lost", "how do I make sure it only happens once".
- **Out-of-order delivery**: Messages can arrive in a different order from the one they were sent in, because a retry of an old one can land after a newer one. If your code treats the latest to arrive as the latest to happen, a late "paid" event can undo a refund. Described as: "a refund got undone", "the old update overwrote the new one", "events arrive in the wrong order", "it went back to the previous status by itself".
- **Timeouts and deadlines** (Deadline propagation): A timeout limits one call. A deadline limits the whole job: the moment by which the answer stops being any use, handed down through every call that serves it, so nobody keeps working for a user who has gone. Described as: "the user gave up but the server kept working", "the timeouts add up to more than anyone will wait", "one slow thing makes everything slow", "it keeps working after the page has closed".
- **Circuit breaker**: A switch around a call to something that might fail. Count the failures, and past a limit stop calling it for a while and fail at once. After that, let one trial call through. If it works, close again. Named after the thing in your fuse box. Described as: "stop calling it when it is obviously down", "every request waits the full timeout", "one broken service ties up everything", "fail fast".
- **Queue**: A list of jobs waiting to be done, usually run by a separate service. One program adds a message, and a worker takes it later and deletes it when it's finished. The caller doesn't wait, and a spike of work waits in the queue and not on your server. Described as: "do this in the background", "the page waits for the email to send", "a spike of work took the site down", "the same job keeps failing over and over", "the worker died halfway through".
- **Graceful degradation** (Load shedding): Doing less when part of the system is unwell, in place of falling over. Hide the recommendations, serve a slightly old list, turn off the search, and keep the page up. You decide in advance what the product can live without, and what it can't. Described as: "one small widget took the whole page down", "keep the site up when part of it is broken", "what can we turn off under load", "show something rather than an error".
- **Money and floats**: Computers store most decimals in binary, which can't hold 0.1 exactly, so sums drift. A float is fine for measuring distance, and wrong for money. Store money as a whole number of the smallest unit, such as pence, or use a decimal type, and decide where rounding happens. Described as: "the total is a penny out", "0.1 plus 0.2 is not 0.3", "the invoice does not add up", "how should I store prices", "a long string of nines in the total".
- **Dates and time zones** (UTC, Daylight saving): An instant is one point in time, everywhere. What a clock on the wall shows depends on where it is and on that place's current rules. Store instants in UTC and convert when you display. A time in the future, like a meeting, is different: store the wall-clock time and the place. Described as: "the date is a day out for some people", "the job ran an hour early", "it broke when the clocks changed", "what time zone should I store", "the timestamp is wrong by a few hours".
- **Replication** (Read replica, Replica lag): Keeping copies of a database on other machines. One copy, the leader, takes the writes and sends them to the followers, which can serve reads. Usually it sends them after telling the client yes, so a follower is a little behind. That gap is called replica lag. Described as: "I saved it and the old value came back", "it shows the right thing after a refresh", "the copy of the database is behind", "we failed over and lost some data".
- **Eventual consistency**: A promise that all copies will agree if you stop changing things and wait. Until then, different readers can see different answers. It's a fair trade for speed and uptime, as long as the product was designed for it and it isn't a surprise. Described as: "different people see different numbers", "it will sort itself out in a minute", "one person's change got overwritten", "the item came back after I removed it".
- **CAP theorem**: When a network splits your copies of the data apart, you have to choose. Either refuse some requests, so nobody gets a wrong answer, or answer them all, and accept that some answers are out of date. You can't have both while the split lasts. Described as: "the data centres lost contact with each other", "error or stale data, which is better", "pick two of three", "should it stop working or show old data".
- **Personal data** (PII): Anything that can be tied to a real person: a name, an email address, a location, an account number. It carries legal duties in much of the world. It gets everywhere, into logs, backups, test databases and, now, an agent's context, which may leave your machine. Described as: "customer emails are in the logs", "can I test with a copy of production", "someone asked us to delete their data", "the agent pasted real customer rows", "what counts as personal data".
- **Agents and production data**: An agent with production credentials can delete data as fast as it can type. So keep credentials it can read away from production, give it a read-only role when it needs to look, and put destructive steps behind something it can't talk its way past. A sentence in its instructions doesn't count. Described as: "the agent deleted my database", "should the AI have access to production", "it ignored the code freeze", "how do I stop it wiping data", "it found a password in a file and used it".

#### Performance and cost

- **Measure first**: Before changing anything to make it faster, time it, find the slow part and write the number down. Then time it the same way after the change. Without both numbers, nobody can say the change helped. Described as: "the agent says it should be faster now", "how do I know the fix actually helped", "it optimised something without checking", "prove that it is quicker", "it feels faster but I am not sure".
- **Latency and throughput**: Latency is how long one thing takes. Throughput is how many things get done per second. They are separate numbers, and improving one can hurt the other: waiting to send items in a batch gets more done per second, and makes each item wait longer. Described as: "how many requests can it handle", "each request is slow but the server is not busy", "it handles more but every one takes longer", "what does fast actually mean here".
- **Percentiles** (p50, p95, p99): Sort every timing from fastest to slowest. The 95th percentile, or p95, is the value that 95% of them are at or under. p50 is the middle one. A percentile is a time someone really waited, which an average need not be. Described as: "the average looks fine but people are complaining", "what does p99 mean", "it is usually fast but sometimes really slow", "the dashboard says it is fine", "one slow request in a hundred".
- **Tail latency** (p99 latency, Hedged request): The slowest few requests, far along the end of the distribution. One in a hundred sounds rare until a single page makes dozens of requests and waits for them all, at which point a lot of people meet that one. Described as: "the page is slow for some people some of the time", "each service is fast but the page is slow", "one slow call holds up the whole page", "why is it slow when the averages are fine".
- **Benchmark**: A repeatable test that times a piece of code many times under the same conditions, so two versions can be compared. One timing isn't a benchmark, because the same code gives a different number on each run. Described as: "it was faster the first time I ran it", "the numbers change every run", "how many times should I run it", "the benchmark says it is faster but it does not feel it".
- **Profiler**: A tool that watches a program run and reports how much time each function took. Self time is what the function spent on its own. Total time also includes everything it called. The answer often surprises people. Described as: "where is all the time going", "which function is the slow one", "find out what is taking so long", "it is slow and I have no idea why".
- **Flame graph** (Flame chart): A picture of a profile. Each bar is a function, sitting on top of the one that called it, and the wider the bar, the more time it took. You look for the wide bars at the top: they are doing the work themselves, with nothing above them to blame. Described as: "the colourful graph of where time went", "what are the wide bars", "how do I read this profile", "show me which code is slow as a picture".
- **Big O** (Time complexity, O(n)): A way of saying how a program's work grows as its input grows. With O(n), twice the data takes about twice as long. With O(n²), twice the data takes about four times as long. It says nothing about how long any one run takes. Described as: "it was fine until we had more data", "it works on my test data and dies in production", "a loop inside a loop", "what does O(n) mean", "it gets slower and slower as the table grows".
- **Bottleneck** (Theory of constraints): The one stage that limits how much the whole line can do. Speeding up any other stage changes nothing at the end, and just makes a bigger pile in front of the narrow part. Described as: "we write code faster but ship no faster", "it all piles up at one step", "we sped that up and nothing changed", "everything is waiting on one thing".
- **Amdahl's law**: If part of a job has to be done one step at a time, adding more workers can only speed up the rest. If 5% must run alone, you can never go more than 20 times faster, however many workers you add. Described as: "we added more servers and it barely helped", "how much faster can it get", "adding more agents stopped helping", "is it worth optimising this part".
- **Premature optimisation**: Making code faster, and usually harder to read, before you know that it matters. The cost is real and paid at once in complexity. The gain is a guess until someone has measured that this code is where the time goes. Described as: "it added a cache nobody asked for", "why is this simple thing so complicated", "the code got clever for no reason", "someone quoted root of all evil at me", "should I bother making this faster".
- **Caching** (LRU, Hit rate): Keeping a copy of an answer somewhere quick, so you can skip the slow work next time. A hit is when the copy is there. A miss means doing the work anyway. A cache is small, so something has to decide what to throw out, often the least recently used. Described as: "keep a copy so it does not have to do that again", "the cache is not helping", "what is a cache hit", "it only gets fast the second time".
- **Cache invalidation** (Stale read, TTL): Getting rid of a stored copy when the real answer changes. Do it too late and people read old data, which is called a stale read. A time limit on each copy, or TTL, is the blunt way: it is simple, and wrong until it runs out. Described as: "I changed it but the old value still shows", "it is right after a few minutes", "clearing the cache fixes it", "users see old data", "it shows the old price".
- **Queueing and utilisation** (M/M/1, Load shedding): When work arrives at random, it sometimes bunches up and has to wait in line. Utilisation is how busy the server is. As it nears 100%, the line grows faster and faster: at 50% a request takes about twice its work time, at 90% ten times, at 99% a hundred times. Described as: "it was fine at 80% and fell over at 95%", "why does it get so slow when it is busy", "the queue keeps growing", "the server is not even at full capacity", "should we just add a bigger queue".
- **Load test** (Stress test, Coordinated omission): Sending a system a realistic amount of made-up traffic, on purpose, to see how it behaves before real people do. A stress test goes past the expected load, to find where it breaks. Described as: "will it cope with a thousand users", "it works for me but falls over in production", "test it under heavy traffic", "the load test passed and production still went down".
- **Concurrency and parallelism**: Concurrency means juggling many tasks, swapping between them while each waits for something. Parallelism means truly doing several at the same instant, on separate cores, the independent workers inside a CPU. Waiting can be juggled. Crunching numbers needs more cores. Described as: "I made it async and it is no faster", "run these at the same time", "does it use all my cores", "Promise.all did not help".
- **Event loop** (Long task, Blocking the main thread): In a browser or Node, a single line of work, called a thread, takes jobs off a list and finishes each before starting the next. While a job runs, nothing else can: no clicks, no animation, no other requests. A job over 50 ms in a browser is called a long task. Described as: "the whole page freezes for a second", "the button does nothing and then it all happens at once", "one slow request holds up everyone", "the spinner stops spinning", "it locks up while it works".
- **Connection pool**: A fixed set of open database connections that requests borrow and hand back. Opening a new one each time is slow, so they are reused. If all are in use, a request waits. If code forgets to hand one back, the pool slowly runs out. Described as: "too many connections error", "it hangs after a while until I restart it", "requests are stuck waiting on the database", "it works with one user and dies with fifty".
- **Memory leak**: Memory the program no longer needs, and can't release because something still points at it: a list that only grows, a listener never removed. Each bit is small, so it passes every test and takes days to bring a server down. Described as: "it gets slower the longer it runs", "restarting fixes it for a while", "memory keeps going up", "it crashes after a few days", "the tab uses more and more memory".
- **Garbage collection** (GC, GC pause): The part of a runtime that finds memory nothing can reach any more and frees it, so you don't have to. It costs work, and some of that work can pause your program. Those pauses are one reason a fast function sometimes isn't. Described as: "random pauses for no reason", "most requests are fast and a few stall", "does JavaScript free memory by itself", "the profile says garbage collector".
- **Core Web Vitals** (LCP, INP, CLS): Three scores for how a page feels. LCP: how soon the main content appears. INP: how soon the page responds when you tap. CLS: how much things jump around. Good means LCP within 2.5 seconds, INP within 200 ms and CLS at 0.1 or less. Described as: "the page jumps when the image loads", "I went to tap and the button moved", "Google says my site is slow", "it takes ages for anything to appear", "I tap and nothing happens for a moment".
- **Bundle size**: How much code a page makes the browser download. A browser then has to unpack it, read it and run it, so on a cheap phone a big bundle costs time long after the download has finished. Described as: "the site takes forever on my phone", "how big is our JavaScript", "it added a huge library for one function", "why is the download so big".
- **Lazy loading**: Not loading something until it is needed: an image as it nears the screen, a chart's code when someone opens the chart. The first view gets lighter, and anyone who never scrolls that far never pays for it. Described as: "only load images as you scroll", "the page loads things nobody looks at", "the first image appears late", "load it when it is needed".
- **Image optimisation**: Sending an image no bigger than it will be shown, in a format that compresses well, with its size stated in the page. Images are often the largest thing a page downloads, so this can be the cheapest big win going. Described as: "the photos make the page really slow", "why is this image so big", "which image format should I use", "the image looks fine but takes ages".
- **Performance budget**: A limit you set in advance on something like bundle size or p95 latency, with a check that fails when it is broken. Speed then stops being something you remember to care about, and becomes something that says no. Described as: "it keeps getting slower bit by bit", "how do I stop the site getting slower", "fail the build if it gets too big", "nobody notices until it is too late".
- **Cost per task**: What it really costs to get one piece of work finished: every try, every check and the failures you paid for and threw away. The price per token is only a price list. This is the number you can compare. Described as: "what does one feature actually cost", "is the cheap model really cheaper", "it took three tries so what did that cost", "how much did that agent run cost me".
- **Spending tokens well**: Deciding what is worth putting in front of the model. Every turn sends the whole conversation again, so a big log read early isn't paid for once. You pay for it again on each turn until the session ends. Described as: "why did that session cost so much", "it read the whole log file", "how do I use fewer tokens", "my usage ran out really fast", "long chats get expensive".
- **Model routing**: Sending each job to a model that fits it, instead of one model for everything: a cheap one for searching and summaries, an expensive one for planning and hard bugs. The router can be a rule, a setting or a person. Described as: "use the cheap model for simple stuff", "do I need the best model for everything", "plan with one and build with another", "how do I cut my bill without getting worse results".
- **Cache hit rate**: The share of a request's input tokens that came from the prompt cache. Because an agent resends everything each turn, a high rate can cut the input bill several times over, and a low one can quietly cost more than having no cache at all. Described as: "cache_read_input_tokens is zero", "the bill went up and nothing changed", "is my prompt cache working", "it got expensive after I came back from lunch".
- **Cost of an agent bill** (Unit economics): Working out the whole bill from its parts: people, tasks per day, cost per task. Once you have those three, you can tell what would double it, what a cut would save, and whether the work was worth what it cost. Described as: "how much will agents cost my team", "is it worth what we pay", "the bill doubled and I do not know why", "how much does a developer use per day".

#### Shipping and running

- **Production** (Prod, Live): Where your software runs for real, with real users, real data and real money. Every other copy of it exists to prepare for this one. Described as: "the real live site customers use", "where it actually runs for people", "the real database and not the test one".
- **Environment** (Deployment environment): One complete place your software can run, with its own address, its own data and its own settings. Development on your machine, staging and production are the usual three. Described as: "it works on my machine but not on the server", "the different copies of the app", "a separate place to try it out".
- **Staging** (Pre-production, Preprod): An environment that copies production as closely as you can afford, where a release runs before real users get it. Described as: "a copy of the site to try it on first", "test it somewhere that looks like the real thing", "it passed on the test server and broke on the real one".
- **Build**: The step that turns source code into the thing that actually runs: compiling, bundling, and copying everything into one output. Described as: "turning the code into what actually runs", "the compile step", "it runs in dev but the production bundle fails".
- **Semantic versioning** (Semver, Version range, Caret range): A three-part version number, like 2.4.1, that makes a promise. The last number means a bug fix, the middle one a new feature that breaks nothing, and the first means something may break. Described as: "what do the three numbers in a version mean", "what does the little hat before the version do", "is it safe to update this package".
- **Pinning** (Version pinning, Frozen lockfile): Fixing the exact version of something you depend on, by number or by hash, so that it changes only when you decide. A range is a rule. A pin is this one and no other. Described as: "it broke and nobody changed anything", "make sure everyone gets the same version", "the build is different today and the code is the same".
- **SBOM** (Software bill of materials): A list of every component in your software, including what your dependencies depend on, with exact versions. An ingredients label, generated from what you really built. Described as: "a list of everything we depend on", "do we use the package in that security alert", "what is actually in this thing we shipped".
- **Artefact** (Artifact, Build artifact, Release artifact): The finished output of a build, stored with a version so that you can move exactly that thing between environments. A bundle, a zip, a container image. Described as: "the thing that comes out of the build", "what we tested is not what we deployed", "build it once and move it along".
- **Container** (Docker container, Container image): A way to package a program with all the files it needs and run it as an isolated process, so that it behaves the same on your laptop and on a server. Described as: "package it up with everything it needs", "what is Docker for", "run it the same everywhere".
- **Serverless** (Functions as a service, FaaS): You hand a provider your code, and they run it on their machines when requests arrive. There are still servers. They just aren't yours to manage. Described as: "I do not want to manage a server", "just run my function when someone calls it", "where did my variable go between requests".
- **Infrastructure as code** (IaC, Terraform): Describing your servers, databases and networks in files kept in the repo, and letting a tool make the real world match them, in place of clicking around a console. Described as: "set up the servers from a file", "the agent wants to run terraform", "so nobody has to click around the cloud console".
- **Config and secrets** (Environment config, Deploy secrets): Whatever changes between deploys belongs outside the code: addresses, keys, passwords. The same artefact can then run anywhere, reading its settings from wherever it is running. Described as: "where do I put the API key", "different settings for test and live", "could we publish this repo tomorrow".
- **Deployment** (Deploy): Putting a new version where it can run. The aim is to make it automatic, small and boring, so that it can happen often. Described as: "how does the code get from my machine to the website", "it is merged but it is not live yet", "pushing the new version to the server".
- **Continuous delivery** (CD): Keeping your software in a state where it could go to production at any moment, so that releasing is a decision and not a project. Described as: "we should be able to ship at any time", "we only release once a month and it is terrifying", "what is the CD in CI/CD".
- **Trunk-based development** (TBD): Everyone merges small changes into one main branch, at least daily, and nobody keeps a branch going for long. Unfinished work stays hidden behind flags. Described as: "the branch has been open for weeks and now it will not merge", "everyone works on main", "merge day is a nightmare".
- **Feature flag** (Feature toggle, Kill switch, Percentage rollout): A condition in your code that turns something on or off, for some or all users, without a deploy. The code ships switched off, and you switch it on when you are ready. Described as: "turn it off without deploying", "release it to some users and not others", "ship it dark".
- **Canary** (Canary release, Canary deployment, Gradual rollout): Sending a small share of real traffic to the new version, comparing it with the old one, and only then sending everyone. If it is bad, few people met it. Described as: "try it on a few users first", "send 5% of traffic to the new version", "find out it is broken before everyone does".
- **Blue-green deployment** (Blue-green): Two identical production environments. One serves users while you deploy to the other and check it. Then you switch the traffic across, and the old one stays ready to switch back to. Described as: "two copies and flip between them", "switch all the traffic over at once", "keep the old version running in case".
- **Rollback** (Roll back, Roll forward, Fix forward): Going back to the previous version after a bad release. Rolling forward is the other choice: shipping a new version with the fix. Rolling back is usually faster, so you stop the harm first and fix it calmly. Described as: "undo the release", "put the old version back", "can we go back after this migration".
- **Observability** (o11y, Monitoring): How well you can work out what a running system is doing from the outside, using what it emits, including for problems you didn't predict. Described as: "how would we know if this broke", "I can not tell what it is doing in production", "let the agent see the logs".
- **Logs, metrics and traces** (Telemetry, Spans, The three pillars): Three kinds of signal. A log is a timestamped event. A metric is a number over time, such as requests a second. A trace follows one request through every call it makes. Described as: "the graph says it is slow but not why", "see where the time went in one request", "what is the difference between a log and a metric".
- **Structured logging** (Structured logs, JSON logs, Canonical log line): Writing each log entry as named fields, usually JSON, and not as a sentence. A query can then ask for exact values, without guessing at the wording. Described as: "which users were affected", "grep the logs and hope", "I can not search these log lines".
- **SLI and SLO** (Service level indicator, Service level objective, SLA): An SLI is a measure of how your service is doing, like the share of requests that succeed in time. An SLO is the target you set for that measure, like 99.9% over 30 days. Described as: "how reliable does this have to be", "what does 99.9% actually measure", "agree a target for uptime".
- **Error budget**: The failure your SLO allows. At 99.9% over 30 days, that is 43.2 minutes of total outage. While there is budget left you ship, and when it is gone you stop and work on reliability. Described as: "when should we stop shipping and fix things", "how much downtime can we afford", "product wants features and ops wants stability".
- **Alert** (Page, Burn-rate alert, Alert fatigue): A signal that tells a person to act now. A good one fires when users are being hurt and someone can do something about it. A burn-rate alert does this by asking how fast the error budget is going. Described as: "the alerts go off all the time and we ignore them", "it was broken for days and nothing told us", "get woken up only when it matters".
- **On-call** (Pager, Rotation): The rota that decides who answers when something breaks, at any hour. That person has to respond quickly, and needs the access and the knowledge to act. Described as: "who gets the phone call at 3am", "who looks after it once it is live", "taking turns to be responsible for the site".
- **Incident** (Outage, Incident commander, Mitigation): An unplanned event that is hurting users, or about to, and needs people to coordinate. The work has an order: stop the harm first, then understand why. Described as: "the site is down, what do we do first", "everyone is in the channel and nobody is in charge", "stop the bleeding before finding out why".
- **Runbook** (Playbook): Written steps for a known situation, which someone tired can follow: what you see, what to check, the exact commands, and when to call for help. Described as: "written steps for when this breaks", "only one person knows how to fix it", "what do I do when this alert fires".
- **Time to restore** (MTTR, Mean time to recover, Failed deployment recovery time): How long it takes to get back to healthy after something breaks. DORA's current version, failed deployment recovery time, counts only failures caused by a change. Described as: "how long were we down", "how quickly can we get back", "one awful outage ruined our average".
- **Postmortem** (Blameless postmortem, Incident review): A written record of an incident: what happened, what it cost, why, and what changes so that it doesn't happen again. Blameless means it asks how the system allowed this, and doesn't stop at who. Described as: "writing up what went wrong", "no finger pointing", "make sure that can't happen again".
- **DORA metrics** (DORA, Four keys): Five measures of software delivery from Google's DORA research: change lead time, deployment frequency, failed deployment recovery time, change fail rate and deployment rework rate. Speed and stability, side by side. Described as: "how do we measure if we are getting better", "are we shipping faster and breaking more", "what numbers should a team watch".
- **Change fail rate** (Change failure rate, CFR): The share of deployments that need fixing straight away, by a rollback or a hotfix. Five bad deploys out of fifty is 10%. Described as: "how often does a deploy break something", "our number looks great but it does not feel great", "what counts as a failed release".
- **The amplifier** (AI as an amplifier): DORA's description of what AI does to a software team: it makes strong teams stronger, and makes the problems of struggling ones worse. What decides which is what was already around the tool. Described as: "will AI make our team better or worse", "we went faster and things started breaking", "what did the DORA report actually find".

### The operator

#### Many agents

- **Parallel agents**: Several agents work at the same time on separate parts of a job, each in its own session. You get more done per hour only if the parts really are independent, and only if you can check all of what comes back. Described as: "can I run several agents at once", "this is too slow with one agent", "three agents on three features", "how many agents should I run".
- **Fan-out** (fan-in, map-reduce with agents): One job is split into pieces, each goes to its own worker at the same moment, and their results are gathered into one answer, which is the fan-in. The whole job takes as long as the slowest worker, plus the gathering. Described as: "look through the whole repo at once", "one agent per folder", "run the same thing on every package", "split it up and combine the answers".
- **Orchestrator** (coordinator, orchestrator-workers): An agent whose job is running other agents. It splits the work, briefs each worker, tracks what comes back and judges it, and writes no code itself. A mistake in its brief is repeated by every worker it sends. Described as: "one agent managing the others", "who keeps track of all these agents", "a boss agent", "the main agent keeps running out of context".
- **Worktree isolation**: Each agent gets its own git worktree: a separate folder with its own branch, sharing the same repository. One agent's half-saved file can't break another's test run, and an edit can't quietly overwrite another. They only meet at merge time. Described as: "two agents on the same repo", "my changes keep disappearing", "tests fail in a file nobody touched", "agents overwriting each other".
- **Coordination cost**: The time a team spends staying in step and not working: waiting, conflicts, re-reviews, explaining things again. It grows with the pairs of workers and not the workers. Past some point, adding one makes the whole team slower. Described as: "more agents is making it slower", "they keep stepping on each other", "merge conflicts all day", "I spend all my time reviewing".
- **Merge queue**: Pull requests wait in line, and each is tested on top of main plus everything ahead of it before it merges. Two changes that pass alone and break together get caught before they reach main, not after. Described as: "both pull requests were green and main broke", "main keeps going red", "it passed on the branch", "too many PRs merging at once".
- **Roles** (role specialisation, specialised agents): Give each agent one job with its own prompt, tools and check: one writes specs, one writes code, one tidies, one reviews. Each is told what not to do, so that each check stays with someone who did not write the code. Described as: "one agent to write and one to check", "a tester agent", "give each agent a job", "it keeps marking its own homework".
- **Evaluator-optimiser**: One side writes and the other judges, in a loop. The judge's notes go back to the writer until it passes or the tries run out. It works when the judge has clear criteria, and the result ends up as good as what the judge can see. Described as: "have one agent check the other", "keep going until the tests pass", "feed the errors back", "write then review in a loop".
- **Adversarial review**: A reviewer whose job is to break the work and not to approve it. It is fair only when each finding must be proved by a run. Without that rule, a reviewer told to find problems will find problems, whether or not they exist. Described as: "try to break it", "a harsh reviewer", "the reviewer keeps inventing problems", "red team this change", "is adversarial review worth the tokens".
- **Ralph loop** (Ralph Wiggum loop, Ralph): The same prompt, fed to a fresh agent, over and over, in a shell loop. Each run does one thing, writes down what it did, and exits. Its memory is on disk. It is cheap to set up, and it has no way of stopping unless you build one. Described as: "just run it in a loop", "let it work overnight", "keep restarting the agent", "the Ralph thing".
- **Long-running agents**: An agent working on one goal for hours or days, usually across many sessions that cannot remember each other. What lets it last is outside the model: a plan on disk, notes on progress, tests it can run, and a clean way to start again. Described as: "run for hours on its own", "the session ran out half way", "overnight agent", "it forgets where it was".
- **Progress files**: A file in the repo saying what has been done and what comes next, which each new session reads first and updates last. It is how a session with no memory finds its place. It is only as true as whatever checks it. Described as: "it says it finished but it didn't", "where did the last session get to", "keep a list of what is done", "it starts over every time".
- **Handoff artefacts**: A file one agent commits for the next to pick up: a spec, a diff, a report. Unlike a chat message it outlives the session, has a version, and can be checked. If you pass a commit, the next stage knows exactly what it received. Described as: "pass the result to the next agent", "what did the last agent actually do", "the second agent got it wrong", "agents passing work along".
- **Checkpoints**: A saved state you can go back to when a run goes wrong. Claude Code makes one per prompt, covering files its editing tools changed. Git commits cover everything git tracks. Neither can undo a database change or a sent email. Described as: "undo what the agent just did", "go back to before that", "it deleted something", "can I rewind this".
- **Scheduled agents** (routines, cron agents): An agent started by a clock or an event and not by a person: triage overnight, check a deploy every five minutes. Nobody is watching when it runs, so it needs narrower permissions than you'd give yourself, and its own way to stop. Described as: "run this every night", "check it every five minutes", "an agent on a timer", "do this while I am asleep".
- **Runaway loops** (cost runaway): A loop that keeps spending because nothing told it to stop, or a growing session where each turn resends everything before it. Spend rises with every turn, and if nobody is watching, the first sign is the bill. Described as: "how much will this cost", "the bill was huge", "it ran all night", "put a limit on it".
- **SwarmForge**: A tool for running a line of AI agents, one role each, in separate git worktrees and tmux sessions (tmux keeps several terminals running side by side). Work passes on as committed handoffs, and you approve it at a gate. Described as: "Uncle Bob's agent setup", "six agents in a line", "the gauntlet", "code nobody reads, checked by gates".
- **pstack**: A set of skills by Lauren Tan (poteto) for Cursor and Claude Code. It teaches going deep with one agent first, then running many with proof. It is instructions for the agent you already use, with no runtime of its own, and poteto-mode is the router. Described as: "poteto mode", "Lauren Tan's skills", "fearless parallelism", "prove it before merging".
- **Software factory**: A setup where specs and scenarios go in, and agents write, test and ship code, with few or no people reading it. People build the line and its checks. The phrase names a way of working. It is not a product, and not a measured result. Described as: "a software factory", "nobody writes code any more", "agents shipping on their own", "lights-out development".
- **Dark factory**: A software factory where no person writes or reads the code, so the lights can stay off. All the trust has to come from evidence such as hidden scenarios and real runs. Few teams claim to do this, and we found no outside audit of any. Described as: "nobody reads the code at all", "level five", "no humans in the loop", "can we stop reviewing altogether".
- **Entropy**: Agents copy what they find. Good and bad patterns alike spread with every run, so a repo nobody tidies gets less consistent, and faster than people alone would make it. No single change looks wrong. The drift shows up later. Described as: "the code is getting messier", "it keeps copying the old pattern", "five ways of doing the same thing", "the agent learned a bad habit from the repo".
- **Garbage collection agents** (doc gardening, doc-gardening agent, cleanup agents): Small background agents that each look for one kind of decay, such as stale docs or a broken convention, and open tiny pull requests to fix it. They pay down entropy in small amounts, so nobody has to hold a clean-up day. Described as: "the docs are out of date", "clean up in the background", "small automatic fixes", "an agent to keep the repo tidy".
- **Eval-driven development**: Write down what good looks like as a set of scored cases before you change anything, then change the prompt or harness and run them again. An eval is a test of behaviour across many runs. It tells you if the change helped, not how it felt. Described as: "is the new prompt actually better", "measure the agent", "how would we know this helped", "it felt better".
- **When not to**: Most work does not need many agents. If it fits in one session, or the parts share files, or you can't check the output, use one. If you could do it in the time it takes to write the brief, use none. Add more only once you have measured a gain. Described as: "do I need more than one agent for this", "is this overkill", "it would be quicker to do it myself", "everyone says to run ten agents".

#### The proof

- **How strong is this evidence** (Evidence hierarchy): A rough ranking of how far a kind of study lets you believe its claim: randomised trials near the top, then comparisons over time, then surveys and benchmarks, then single stories. A ranking only makes sense for one question at a time. Described as: "is this study any good", "someone sent me a statistic about AI", "how much should I believe this number", "which research can I actually cite", "one study says one thing and another says the opposite".
- **Randomised trial** (RCT, Randomised controlled trial): A test where chance decides who or what gets the treatment, so the two groups differ only by luck and by the thing you are testing. That is what lets you say one thing caused another, and not just that they went together. Described as: "how would you prove it actually helped", "we compared before and after we got the tool", "people only use it on the easy tasks", "flip a coin to decide", "what does controlled trial mean".
- **Confidence interval**: A range around a result showing how far it could be from the truth just from the luck of what got sampled. Fewer samples, wider range. It covers bad luck only: a biased study can have a narrow interval around the wrong answer. Described as: "it worked three times so it must be fine", "how many runs is enough", "the plus or minus on a result", "is that difference real or just luck", "the sample was tiny".
- **Base rate** (Prevalence): How common something is before you test for it. When the thing is rare, even a good detector's alarms are mostly wrong, because the many good cases set off more false alarms than the few bad ones set off true ones. Described as: "the alarm goes off and it is nearly always nothing", "a 90% accurate tool that is usually wrong", "most of what it flags is fine", "why does the check cry wolf", "everyone says they use AI so what does it prove".
- **METR's studies**: Studies by METR, a non-profit, timing experienced open-source developers on their own real tasks, with chance deciding whether AI was allowed. The 2025 one found them slower. The 2026 follow-up says it couldn't produce a reliable new number. Described as: "that study that said AI makes you slower", "the one where developers thought they were faster", "what about the METR paper", "didn't someone prove AI slows you down", "is that study still true".
- **Perception gap**: The distance between how much a tool feels like it helps and how much it measurably does. It can be large, it can point the wrong way, and the person inside it can't see it from there. Described as: "it feels so much faster", "I am sure it saves me hours", "it felt productive but nothing shipped", "how do I know I am not fooling myself", "everyone says it makes them faster".
- **Skill atrophy**: Losing a skill, or never building it, because something else does the work for you. With agents, the worry is that you can ship code you can't explain or debug, and that you don't notice until the agent gets stuck and so do you. Described as: "I can not code without it any more", "am I getting worse at programming", "I shipped it but could not explain it", "I feel lost when the agent is down", "juniors are not learning anything".
- **Trust surveys**: Surveys asking developers how far they trust AI tools. The number that gets quoted depends mostly on how the question was asked and which answers someone decided to count as trust. Described as: "87% of developers trust AI", "trust in AI went way up", "nobody trusts AI code according to a survey", "two surveys say opposite things", "developers say they trust it".
- **DORA on AI**: Google Cloud's DORA research on how software teams deliver. Its 2025 report, from a survey of nearly 5,000 technology professionals, calls AI an amplifier: it makes strong teams stronger and struggling teams worse. Described as: "AI made our good team better and our bad team worse", "it just speeds up whatever we were already doing", "what should we fix before adding agents", "we ship more and break more", "the amplifier thing".
- **Output isn't delivery**: More code isn't more software shipped. Output is what gets produced: lines, commits, pull requests. Delivery is what reaches people and does its job. Agents can raise the first a long way while the second moves much less. Described as: "we write way more code and ship the same", "lots of pull requests but nothing is finished", "my numbers look great and nothing changed", "more commits does not mean more done", "the agent keeps producing and the queue keeps growing".
- **Vendor studies**: Research published by a company that sells something in the same area. It can be perfectly good work. You say who paid when you quote it, and you read what it measured with that in mind. Described as: "45 percent of AI code is insecure", "a company that sells this says it works", "who funded this report", "the report came from the people selling the fix", "that number is from a blog post by a tool company".
- **What nobody has measured**: The questions with no good study behind them yet. For agent-written code the biggest is this: does it cause more production incidents? We found no primary, peer-reviewed measurement, and saying so is a stronger answer than filling the gap. Described as: "does AI code cause more outages", "is there a study on that", "I keep hearing about agents wiping databases", "nobody seems to have a number for this", "what do we actually not know".
- **Reading a productivity claim**: Four questions to ask of any number about AI and productivity, in this order: who measured it, what was it compared with, what did they count, and who paid. A claim that survives usually comes out smaller and more useful. Described as: "our CEO read that AI makes you 40% faster", "a study proves it doubles output", "how do I push back on a big AI number", "where does this number come from", "that claim sounds too good".
- **Prediction or measurement** (Forecast): A measurement says what happened, to what, compared with what. A prediction says what will happen. Both can be worth hearing, and they need different treatment: you check a measurement, and with a prediction you ask what would show it right or wrong, and when. Described as: "AI will rewrite all software", "my CEO shared a post about the future of coding", "how do I answer a big prediction", "nobody will write code soon", "is this a fact or a forecast".
- **The claim you can defend**: A short paragraph you can say out loud in which every sentence points at something you can open: a file, a commit, a failing run. If a sentence has nothing behind it, you either drop it or go and do the work. Described as: "how do I say I build with AI without sounding like a vibe coder", "what do I put on my CV about agents", "how do I prove I know what I am doing", "I want to claim this and back it up", "what do I actually say in the interview".
- **A repo worth showing**: One public project small enough to read in ten minutes, where the process is visible as well as the result: the brief, the checks, the history, and what went wrong. This is our suggestion. We found no employer saying which artefact persuades them. Described as: "what should I put on my GitHub", "what project should I show", "do employers look at portfolios", "how do I show my process and not just the app", "my repo is one big commit".
- **A commit trail**: A project's history read as evidence: what changed, in what order, and why. A good trail shows small steps with reasons, checks arriving after mistakes, and things being undone. One giant commit shows nothing. Described as: "my git history is a mess", "one huge commit called final", "can they tell I used AI from my commits", "should I clean up my history before showing it", "what does a good commit history look like".
- **AGENTS.md as evidence**: Your instructions file read as a record of what has gone wrong. A line naming a real command, file or past mistake shows someone was paying attention. A line like "write clean code" shows nothing at all. Described as: "what should my CLAUDE.md say", "my rules file is full of generic advice", "I copied someone else's instructions file", "can I show my prompts in an interview", "why is this rule even here".
- **The log of past failures** (Ratchet log, Failure log): A running list of mistakes: what went wrong, what now prevents it, and proof that the check fails on the old code. It shows you noticed a failure, generalised it, and closed it off. Described as: "how do I show what I learned from mistakes", "a list of everything the agent got wrong", "prove this check would have caught it", "keep a record of failures", "turn a bug into something I can show".
- **Decision records as evidence**: A short dated note of a decision: what you chose, what you rejected, and why. As evidence, it shows a person made a call the agent couldn't make alone, and it lets someone ask you about it a year later. Described as: "why did we do it this way", "write down why I chose this", "which decisions did I make and which did the agent", "I want to show my thinking", "nobody remembers why it is like this".
- **Reviewing live in an interview**: Reading code you didn't write in front of someone, saying what you are looking for and what you aren't getting to. Going by what hiring teams write, they are watching your order and your honesty at least as much as what you find. Described as: "they gave me a big diff in the interview", "how do I review code with someone watching", "I do not have time to read all of it", "where do I even start with this pull request", "I just said it looks fine".
- **Debugging without the agent**: Finding and fixing a bug yourself with the agent off: read the error, make a guess, test the guess, narrow it down. You don't have to be quick. You have to have a method, and be able to say what it is as you go. Described as: "the agent is stuck and I do not know what to do", "what if they make me code without AI", "it keeps trying the same fix", "I have never debugged this by hand", "my provider is down and I have a bug".
- **Explaining trade-offs**: Saying what you chose, what you gave up for it, and when you would choose differently. If you can't name the cost of a decision, you probably didn't make it. Described as: "why did you pick that", "what is the downside of your approach", "I only know the reasons for it", "how do I answer when they push back", "what would make you change your mind".
- **Saying what you don't know**: Saying plainly where your knowledge and your evidence stop. "I don't know, and here is how I would find out" is a complete answer. An absolute such as "always" or "fully tested" only needs one counter-example to sink you. Described as: "what if they ask something I do not know", "I do not want to sound like I am bluffing", "am I overclaiming", "how do I admit I have not measured it", "it sounds too confident".
- **Employer AI policies**: What a company says about using AI at work and in its hiring. They differ, often within one company: the same process may forbid AI in one round and expect it in the next. So you ask each time, and never assume. Described as: "am I allowed to use AI in the interview", "is it cheating to use Claude on the take-home", "what is their policy on AI", "can I paste work code into it", "do they want me to use it or not".
- **Take-homes in the agent era**: Work you do in your own time for a hiring process. Agents can now finish many of them, so companies are banning AI on them, redesigning them, or moving to scoped builds and live follow-up. Expect to defend every line. Described as: "can the agent just do the take-home", "they sent me a coding test to do at home", "should I tell them I used AI", "I did not finish all of it", "everyone can pass this test with AI now".
- **Red flags interviewers look for**: What interviewers report seeing when someone's claim to work with agents is hollow: no plan, permission checks off, a skimmed diff, stuck the moment the agent is stuck. A follow-up question or two is usually all it takes to find out. Described as: "how would they catch me out", "what makes someone look like a vibe coder", "what do interviewers hate", "I sounded fine until they asked a follow-up", "how can they tell I did not really understand it".
- **The hard questions**: The 57 questions a sceptical engineer could ask about how you build with agents, the same ones as the interview room. Only a few are asked verbatim by a source, and most are our own reasoning. The bench tells you which is which. Described as: "what will they ask me", "give me practice interview questions about AI", "how do I prepare for this interview", "could I pass this with the AI off", "test me".
- **What to do in your first week**: Learn the rules on AI and data. Read before you generate. Find out what blocks a merge. Ship something small and reviewed. Ask what failed last. These are the same habits as this course, on code you don't own yet. Described as: "I just started a new job", "how do I use agents on a codebase I do not know", "what should I do first at a new company", "I do not want to break anything in week one", "am I allowed to use my agent here".
- **What you can now say**: Only what you can point at. If you did the work, it comes out short: my agents write most of the code, here is how I brief them, here is what stops bad work, here is what still gets through, and here is how I find out. Described as: "so what can I actually say now", "I finished the course, what now", "am I ready to say I build with agents", "how do I sum all this up", "does reading this count".