Coding Agents: Foundations, Architecture, Harnesses, and Enterprise Practice

Building, Orchestrating, Evaluating, and Scaling AI Software Engineers

A Peanutbook manuscript. Build it with bubble-build; read the source in chapter*/.

---

What this book argues

One claim, stated in Chapter 1 and earned over the following eleven:

A coding agent is not a language model with a code prompt. It is a software engineering system built around a model.

The question it answers is not whether AI can write code. That is settled, and settling it mattered less than everyone expected. The question is:

How do we engineer software-development systems in which humans and coding agents work together reliably on large production codebases?

Roughly seventy percent of the text is architecture, large-codebase practice, verification, evaluation, security, and multi-agent engineering. The other thirty percent uses specific systems as concrete implementations, because abstract discussion of agents is unfalsifiable and boring. That ratio is deliberate: the named products will be replaced, some of them before this is in print. The questions in the other seventy percent will not.

---

Register

The voice is already set by the first three chapters. Match it. These are descriptions of what the existing prose does, not aspirations.

Address the reader as "you." Never "we." Across the written chapters: 89 instances of you, one of we. The reader is an engineer doing this work, not a co-author being carried along.

First person singular is rationed, and only ever for first-hand experience. Four instances in fifteen thousand words, all of the form "in notes I wrote in March 2024." Use it to introduce evidence you personally hold. Never for opinion — the argument should stand without the byline.

State the claim, then earn it. The paragraph shape is: assertion, mechanism, consequence. Not: build-up, build-up, reveal.

Prefer the corrective construction. X is not Y. It is Z. — "The context window is not storage. It is a working set." "File context is not repository context." This is the book's most characteristic sentence, because most of what it has to teach is a correction to a reasonable-sounding wrong model.

End on the consequence, not the hedge. A sentence that trails off into "...but of course this depends on your situation" has wasted the reader's attention. If it depends, say what it depends on.

No hype vocabulary. No revolutionary, seamless, game-changing, paradigm shift, cutting-edge. The existing chapters contain none. Enthusiasm is conveyed by precision, not adjectives.

Concrete over abstract, always. A number with a date beats a characterization. A named failure beats "challenges." A worked example beats a principle.

Date every number, or state only the shape. The field moves fast enough that an undated figure is worse than none, and a book that quotes a leaderboard without saying when looks careless within a year. Where a figure carries an argument, cite the paper and the date. Where only the trend matters, describe the trend.

Name few products, and never rank them. A book that ranks models has a shelf life measured in months.

Say what did not work. Anyone can write "here are the best practices." The material worth reading is "we thought the bottleneck was X and it was Y." The author's own failed work is the strongest evidence in the book; use it.

Admit uncertainty in the text, not in a hedge. "This is model-specific and worth measuring on your own workload" is honest. "This may or may not apply" is noise.

Structural habits

Element	Convention
>IMPORS: box	One claim, stated once. About six per chapter.
>NOTES: box	An aside the reader can skip. About two per chapter.
Cross-references	Constant — roughly one per 230 words. Every chapter says which chapter takes a thread further.
Figure captions	20 words maximum, stating the claim. Longer explanation goes in the paragraph that introduces the figure.
<!-- --> comments	Author notes, verification lists, publication gates. Dropped from the PDF.
Chapter ending	A named handoff to the next chapter.

Two things that are not register, but read like it

>NOTES: blocks print. They are for the reader. Notes to yourself go in HTML comments, which pandoc drops.

Every chapter opens with a real, attributed epigraph. Brooks (Ch 1), Parnas (Ch 2), Pike (Ch 3). Do not invent quotes, and do not attribute the book's own theses to anyone — those belong in >IMPORS: boxes.

---

Shelf life

The book is written for a 5–10 year spine and a 2–3 year surface, and the two need to stay physically separable.

What is being bet on lasting: the verification principle, context as a working set with an allocator, file context against repository context, benchmarks scoring a harness rather than a model, paired evaluation, the prefill/decode asymmetry, and the seven-component decomposition — which survives on Parnas's test, not on fashion, because each component is a decision that changes independently of the others.

What will rot on schedule: model names, context sizes, prices, benchmark numbers, API shapes, and the current claim that frontier general models beat code-only models. All of it is real and all of it belongs in the book.

This ships on KDP, where a revised interior is a re-upload rather than a print run, so the cost of carrying perishable material is low and the book can afford more of it than a traditionally published one. But the thing that does not get revised is the reviews. A one-star "already out of date" from the first edition sits on the same product page as the fourth, and no amount of iteration removes it. So perishable content is still quarantined into clearly dated sections — not to make revision cheap, but because a reader forgives datedness they were warned about and punishes datedness that presented itself as current.

Handled that way the perishable sections invert from liability to asset: a section titled The Frontier, as of is a reason to buy the new edition. Put the edition and its date on the title page, and keep a short revision record in the back matter.

The genuine risk is not that details age. It is that the harness framing itself gets absorbed — models that do multi-hour repository work with no scaffold would turn Part II into a historical chapter. The hedge is to write the harness chapters around why a harness exists — verification, budget, policy, accountability — rather than how to build one. Those four survive the absorption, because someone still has to verify the diff, pay for it, constrain it, and answer for it.

The lifespan is therefore mostly decided by whether the book's own concepts get adopted: the Coding Agent Stack, the Evolution Ladder, the Agent-Ready Repository, Harness Engineering. A book that is cited for its framework outlives its examples. A book that only summarizes today's tools does not, however well written.

---

Structure

Four parts, twelve chapters, following one line of development:

Static Agent -> Stateful -> Persistent -> Multi-Agent -> Self-Evolving

#	Chapter	Words	State
	Part I — Foundations
1	Code Language Models	4,300	drafted
2	Anatomy of a Coding Agent	6,200	drafted
3	Context and Repository Understanding	4,100	drafted
	Part II — The Agent Harness
4	Tools, Skills, and Agent Harnesses	4,700	drafted
5	Planning and Spec-Driven Development	4,600	drafted
6	Coding, Debugging, and Refactoring	4,500	drafted
7	Verification and Repair		outline
	Part III — Coding Agents in Production
8	Coding Agents at Scale		outline
9	Long-Running and Multi-Agent Systems		outline
10	Evaluation, Observability, and Economics		outline
11	Security and Enterprise Deployment		outline
	Part IV — The Next Generation
12	Self-Evolving Coding Agents		outline

Front matter is in chapterx/ — the preface is outlined, not written, and it owns the author-credibility argument and the book-structure walkthrough. chapter2/_draft-from-ch1.md is the original Chapter 1, kept because its forty-line agent and enterprise retrospective still have somewhere to go.

The concepts the book has to deliver, not merely name: the Coding Agent Stack, the Agentic Software Engineering Loop, the Agent-Ready Repository and its readiness score, Harness Engineering, and the Coding Agent Evolution Ladder.

---

Building

conda activate usao

bubble-convert 3              # one chapter, while drafting
bubble-build --style square   # the whole book -> book_square.pdf
bubble-single-star            # style lint

bubble-convert does not run figure scripts; only bubble-build does. When you change a figure while drafting, run it yourself first:

cd chapter3-*/img && python myfig.py && cd ../..

Check captions before building:

grep -rn '^!\[' chapter*/*.md | sed 's/^\(.*\):!\[\(.*\)\](.*/\1|\2/' \
  | awk -F'|' '{n=split($2,a," "); if (n>20) printf "%d words: %s\n", n, $1}'

Figures are generated by Python scripts in each chapter's img/, never committed as hand-made images. The conventions are in .claude/skills/peanutbook-figures/; mindmaps need mathicon.

---

Source material, and the gate on it

raw/ holds the author's Oracle talk and design notes from 2023–2024. Read raw/README.md before using any of it.

The short version: the model rankings in those notes are dead, and the methods are not. The recitation probe, paired evaluation, and the generate–verify–repair loop all come from there and all still hold. Cite the papers with dates, never the slides. Abstract employer-internal specifics into general lessons, strip colleague names and email addresses, and confirm publication clearance.

---

Before this ships

• Preface written — it owns the author's position and the book's structure
• Every date, benchmark size, and figure verified against its source
• The frontier claims in Chapter 1 re-checked and stamped
• author set in peanut.config; covers replaced
• Every @fig: resolves, no caption over 20 words, bubble-single-star clean