harness-engineering-101 README

README проекта с github.com/IsuruMaduranga/harness-engineering-101. Одним файлом markdown: README.md.

Harness Engineering 101

The LLM is the brain. The harness is the body.

Version 1.1, October 2026.

AI usage disclosure: I drafted every chapter myself, from what I learned building WSO2 MI Copilot, WSO2 BI Copilot and One Code. I used Claude Code and One Code to reorder each chapter so it leads with the answer (the Minto pyramid), to polish the English, to generate the diagrams, and to write the code that draws the charts.

A blog series about building AI agents from first principles, published as a book.

📖 Read it online: https://isuruwijesiri.com/harness-engineering-101/

An LLM API is stateless. Every turn, you send the entire conversation as a JSON array and get text back. A harness is the program that builds, maintains, and protects that array. Everything the field calls "agents" is a set of patches to that one loop, and each patch exists because something concrete broke. This series develops that one idea across 16 chapters, growing a ~300-line toy agent in plain Python as it goes.

I use the same ideas in One Code, an open-source coding agent built on pi.

The rendered book reads best online at the link above. If you'd rather read the source here on GitHub, follow the chapters in order below. The full introduction is on the book's landing page.

Reading order

Every chapter has the same shape: the failure, the minimal patch, what the patch costs.

Part I — The Wire (nothing is magic)

# Chapter The failure it patches
1 It's Just a JSON Array "How do I even talk to this thing?"
2 The Brain: A Next-Token Black Box "Why does it behave like that?"
3 Tools: JSON Mapped to Functions The brain can't touch the world
4 The Agent Loop One tool call isn't enough
5 Caching: Why Order Matters Resending the array gets expensive

Part II — Running Long (the array under pressure)

# Chapter The failure it patches
6 Context Is a Budget, Not a Bag The window fills up
7 Subagents: Fork the Context One array can't hold all the work
8 Steering the Running Loop The brain drifts mid-task
9 Background Work and Time The loop is synchronous; the world isn't

Part III — The Ecosystem (naming what you already understand)

# Chapter The failure it patches
10 Every Framework Is a Wrapper Around Chapter 1 Abstraction anxiety
11 Extending the Body: MCP, Skills, Deferred Loading, Hooks Capabilities don't fit in the array
12 Debugging the Array You can't fix the prompt you can't see

Part IV — Trust, Domains, and Data

# Chapter The failure it patches
13 Reflexes and Guardrails The loop will do something dumb
14 Case Study: Coding Agents How specialized does the body need to be?
15 RAG Was a Harness Pattern All Along A thousand names for one idea

Epilogue

Appendix — Advanced Topics

Standalone pieces. Read them when you need them.

Repository layout

Path What it holds
src/*.md The chapters and appendices (the book source)
src/SUMMARY.md The book's table of contents
src/harness/ The runnable toy harness, one file per stage
src/diagrams/ Diagram generators and their generated PNGs
book.toml mdBook configuration
scripts/sync-to-blog.sh Builds the book and mounts it into the blog for serving

Building the book locally

cargo install mdbook mdbook-mermaid   # or: brew install mdbook (+ mdbook-mermaid binary)
mdbook serve --open                    # live-reloading preview at http://localhost:3000
mdbook build                           # static site into ./book

mdbook-mermaid renders the inline mermaid diagrams; without it those blocks show as raw code.

Regenerating the quantitative diagrams

cd src/diagrams && python3 gen_all.py   # Python 3.10+, matplotlib

License

This repository is dual-licensed:

© 2026 Isuru Wijesiri.

harness-engineering-101 (IsuruMaduranga/harness-engineering-101)

Ищем в базе…

Что это такое?Это книга (изначально серия блог-постов), которая объясняет, как на самом деле работают ИИ-агенты. Автор строит с нуля «обвязку» на Python. LLM рассматривается как «мозг» без состояния, а обвязка — это окружающий код, который управляет массивом диалога, инструментами и состоянием.
Это книга или репозиторий с кодом?В основном это книга из 16 глав, а также эпилога и приложения. Её можно читать онлайн или на GitHub. Вместе с текстом она по главам наращивает работающего игрушечного Python-агента примерно на 300 строк (в src/harness/).
Как устроена книга?Книга разделена на четыре части: «Провод», «Долгий забег», «Экосистема» и «Доверие/Домены/Данные». Всего 16 глав, эпилог с полностью прокомментированной игрушечной обвязкой и четыре самостоятельных приложения по продвинутым темам.
Что нужно, чтобы собрать книгу локально?Нужны mdBook и плагин mdbook-mermaid, чтобы отрисовывать встроенные диаграммы Mermaid, которые используются в главах. Без плагина диаграммы будут показаны как обычные блоки кода.
Можно ли мне свободно копировать или переделывать главы?Нет. Текст распространяется по лицензии CC BY-NC-ND 4.0: им можно делиться с указанием авторства, но нельзя использовать в коммерческих целях или публиковать изменённые версии. Только Python-код в src/harness/ и src/diagrams/ распространяется по лицензии MIT и свободен для повторного использования.
Что такое «One Code»?One Code — это open-source агент для программирования от автора, построенный на среде выполнения «pi». Он применяет те же идеи обвязки, которые излагаются в этой книге.
Зачем писать агента с нуля, а не использовать фреймворк?Книга утверждает, что любой фреймворк для агентов — это всего лишь оболочка над одним и тем же циклом с JSON-массивом без состояния (Глава 10). Понимание этого цикла снимает ореол таинственности с любого фреймворка, которым вы воспользуетесь позже.
Рассматривает ли книга RAG и MCP?Да: Глава 15 переосмысливает RAG как шаблон обвязки, а Глава 11 рассказывает о расширении обвязки через MCP, Skills, отложенную загрузку и хуки.
Автор
IsuruMaduranga
Размер
1.8 MB
Звёзды
657
Обновлён
КоммитNov 02
Возраст
2 мес
Коммиты · 90 дней