Why this matters beyond the buzzwords
You won't ship a hand-built harness into production. Claude Code and Cursor have more funding and more testing than anything one engineer builds solo.
The case for building one is narrow. Your team already relies on these tools, and understanding the mechanism lets you evaluate and debug them.
CI/CD makes this concrete. An agent with shell access in a pipeline has its own blast radius and its own line between reading a log and pushing a fix. Someone on the team has to answer what happens when it gets something wrong.
It also cuts through the buzzwords. An agent harness is an architecture pattern: a tool-calling loop with guardrails around it. The pattern holds while vendor names rotate every few months, so it repays more study than this quarter's popular tool.
You can be fluent with a tool and still not know what it's doing. Knowing what a well-built harness needs is how you tell a thin demo from something that holds up.
Why build this yourself
Build the harness from scratch instead of wiring up a framework or cloning a template. You learn the loop that turns a model reply into an action and feeds the result back, and the guardrails that keep that loop from doing anything reckless. It also makes a stronger portfolio story, because a candidate who built the mechanics reads better than one who integrated a library.
This plan uses an AI agent, Claude Code or similar, as a debugging partner. Each phase ends with a narrow question worth handing to an agent when you get stuck. The bar for each phase is code you can explain line by line in an interview.
Before you start
- Use Python for the harness core. It has a mature SDK for Groq's OpenAI-compatible API and reads clearly to anyone reviewing AI-adjacent code. You build phase 4's viewer separately in React.
- Groq is the backend for this build: sign up at console.groq.com, no card needed, and create an API key.
openai/gpt-oss-120bis a solid default,openai/gpt-oss-20bis a faster option worth trying later. - Create the repo on GitHub first, then clone it locally. Phase 0 covers how. Use one repo,
agent-harnessor similar, with git tags marking each phase (v0.1-hello,v0.2-loop, and so on), and push as you go so the history builds on GitHub instead of appearing all at once at the end. - Write down each phase's definition of done before starting it, not after. Each phase gives one to start from.
Using an agent without letting it build this for you
Don't paste a phase's goal into Claude Code and ask it to write the phase. You'd get working code you can't defend in an interview, which defeats the reason you're doing this yourself.
Better questions to ask an agent:
- "Here's my code and the exact error, what's wrong?" (after you've tried, not instead of trying)
- "What's a reasonable design for X, what am I likely missing?" (before you write, as a sanity check)
- "Review what I just wrote for obvious mistakes." (after a phase, not during)
There's no purity test here. If an agent generates a chunk of code, read every line before it goes in and be able to explain why it's shaped that way. The bar is whether you understand the code.
Publishing checklist
- README that opens with what the harness does and a 30-second GIF or terminal recording. Skip the essay.
- Git tags per phase (
v0.1throughv0.6) so the history shows how it was built in stages. - A short section on the design decisions that mattered: why sandboxing works the way it does, why provider abstraction, what you'd change at scale.
- Link the repo wherever you present a portfolio, and be ready to walk through phase 2 specifically in an interview. What you chose to allow, block and approve says more about you than any other file in the repo.