harness-engineering-101 README

The project's README from github.com/IsuruMaduranga/harness-engineering-101. As one markdown file: 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)

Searching Database…

253 ·GitHub
Harness-engineering-101
What is this?This is a book (originally a blog series) that teaches how AI agents actually work by building a 'harness' from scratch in Python: the LLM is treated as a stateless brain, and the harness is the surrounding code that manages the conversation array, tools, and state.
Is this a book or a code repository?It's mainly a book of 16 chapters plus an epilogue and appendix, readable online or on GitHub, that grows a runnable ~300-line toy Python agent (in src/harness/) chapter by chapter alongside the text.
How is the book organized?It's split into four parts: The Wire, Running Long, The Ecosystem, and Trust/Domains/Data, covering 16 chapters total, an epilogue with the complete annotated toy harness, and four standalone appendix chapters on advanced topics.
What do I need to build the book locally?You need mdBook plus the mdbook-mermaid plugin to render the inline Mermaid diagrams used in the chapters; without the plugin, diagrams show up as raw code blocks instead.
Can I freely copy or remix the chapters?No. The prose is licensed CC BY-NC-ND 4.0, so you can share it with credit but not use it commercially or publish modified versions; only the Python code under src/harness/ and src/diagrams/ is MIT-licensed and free to reuse.
What is 'One Code'?One Code is the author's open-source coding agent, built on a runtime called 'pi', that applies the same harness ideas taught in this book.
Why build an agent from scratch instead of using a framework?The book argues every agent framework is just a wrapper around the same stateless JSON-array loop (Chapter 10), so understanding that loop demystifies whatever framework you later use.
Does the book cover RAG and MCP?Yes — Chapter 15 reframes RAG as a harness pattern, and Chapter 11 covers extending the harness with MCP, Skills, deferred loading, and hooks.
What are similar projects?ai-system-design, vibe-coding-cn, ai-engineer-notebooks, Agentic-Design-Patterns, Gnos, harness-engineering, zhijian-ai-bluebook-workbuddy-harness, ai-agent-book
Which topics is it in?harness-engineering, hooks, caching, context-engineering, harness, model-context-protocol, prompt-engineering, book, rag, skills, guide, learning-resources
Creator
IsuruMaduranga
Size
1.8 MB
Stars
253
Updated
CommitOct 19
Age
1mo
Commits · 90 Days