Metadata-Version: 2.4
Name: coding-agents
Version: 0.0.1.dev0
Summary: The reference software engineering harness and runtime for autonomous coding agents.
Author-email: Coding Agents Authors <authors@example.com>
License: MIT
Keywords: coding-agents,llm-agents,software-engineering,harness,autonomous-coding,swe-bench
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Provides-Extra: llm
Requires-Dist: anthropic>=0.20.0; extra == "llm"
Requires-Dist: openai>=1.0.0; extra == "llm"

# 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 <month year>* 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:

```text
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

```bash
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:

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

Check captions before building:

```bash
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
