🧰 Understand What a Harness Is
The harness defines: what the agent can see, which tools it can use, which actions it can take, which rules it must follow, how context is selected, how state is preserved, how results are verified, when to stop, and what requires approval. The differentiator isn’t in the prompt—it’s in the system built around the agent.
🆕 New here?
Harness literally means “harness”: the equipment that connects force to work and provides direction. Here, it means everything surrounding the model. Sandbox is a disposable environment, isolated from the rest. Observability is the set of logs and metrics that lets you reconstruct what happened after the fact.
How to read: the request comes in on the left and reaches the highlighted box (delivery) only after passing through isolated execution, tests, review, and gates. Notice that no arrow skips straight from the plan to delivery — it’s this absence of shortcuts that defines a harness.
See
Selected context
Do
Tools and permissions
Prove
Verifiers
Stop
Limits and approval
🗂️ Select Context Intentionally
Context is the set of files, documents, examples, and information relevant to the task. The temptation is to throw everything in. The result is an agent that imitates the repository’s worst pattern just as naturally as it imitates the best.
✓ Helpful context
- ✓The task specification (source of truth)
- ✓The 3–8 files that will actually be touched
- ✓An example good of the pattern you want replicated
- ✓The related tests and how to run them
- ✓The AGENTS.md with project commands and rules
✗ Context that gets in the way
- ✗The entire repository “just in case”
- ✗Outdated documentation that contradicts the code
- ✗Legacy code you specifically want to leave behind
- ✗Two sources of truth saying different things
- ✗Irrelevant chat history carried forward
💡 Practical tip
Before running the agent, write one line answering: "What does it need to read so it doesn’t make assumptions?" If the answer is more than ten files, the task is probably too large—break it down before running it.
Curation
Choosing is the work
Good example
Matters more than the description
Single source
Avoids conflicting instructions
Large task
Break it before running
🔑 Define Tools and Permissions
Tools include the terminal, editor, search, tests, database, and APIs. Permissions define what can be read, changed, run, or published with each one. Implicit permission means full permission — and most incidents involving agents come from access no one decided to grant, but simply didn’t deny.
🧪 Copyable exercise — declare the harness in AGENTS.md
Objective: move permissions out of your head and into a version-controlled file that the agent reads before acting. Create AGENTS.md at the repository root with this content, adjusting what’s between < >.
# AGENTS.md ## Comandos - instalar: <comando> - testar: <comando de teste> - lint: <comando de lint> - build: <comando de build> ## Pode (sem perguntar) - ler qualquer arquivo do repositório - criar branch e commitar na branch de trabalho - rodar testes, lint e build - criar e editar arquivos em <pastas permitidas> ## Não pode (exige aprovação humana explícita) - alterar arquivos de teste existentes - adicionar ou atualizar dependências - rodar migração de banco - alterar CI/CD, secrets, infraestrutura ou permissões - fazer push na branch principal ou deploy ## Limites - no máximo <N> arquivos alterados por tarefa - no máximo <N> tentativas de correção antes de parar e me perguntar - se a mesma falha ocorrer 2 vezes, pare e relate — não tente uma terceira ## Definição de pronto - os testes passam (cole a saída real, não resuma) - nenhum arquivo fora do escopo foi tocado - o diff cabe em uma revisão de 10 minutos
How to verify: ask the agent, "read the AGENTS.md and tell me, in a list, what you CANNOT do on this task." If it doesn't repeat your prohibitions correctly, the file is ambiguous—rewrite it before delegating anything.
⚠️ Attention
An agent with access to secrets, production, or CI/CD is a privileged user—treat it as such: its own identity, least-privilege credentials, and an audit trail. “It’s just an assistant” is not a threat model.
Least privilege
The default is deny
Written
A rule outside the file doesn’t exist
Identity
An agent is a user, not magic
Audit
Every action leaves a trace
📦 Isolate execution in a sandbox
A sandbox is an isolated environment where the agent runs without affecting production or your work environment. It’s what turns an “agent error” into a “discarded attempt”—and what lets you grant more autonomy with less fear.
Code isolation
Dedicated branch or git worktree separately. Discarding is git worktree remove — zero cost, without cluttering your working directory.
Execution isolation
Container or VM with restricted network access. The agent can run whatever it wants inside; what it can't reach, it can't break.
Data isolation
Disposable database with synthetic or anonymized data. Never point an autonomous agent at the production database—even for read access if it contains personal data.
Fail cheaply
It’s the purpose of the sandbox
Worktree
Cheap code isolation
Restricted network
Limits the actual scope
Synthetic data
Production stays out
🧠 Manage Memory, State, and Observability
Memory is what it carries; state is where it stopped; observability is what was recorded. The three solve different problems and are often confused.
📊 What to record in each run
- • Input: which spec, what context, which repository version (commit).
- • Actions: commands executed and files changed, in order.
- • Verification: actual test output—not the agent's summary.
- • Cost: time, attempts, and tokens consumed.
- • Outcome: success, abandonment, or interruption—and why.
Execution monitoring (illustrative recreation, not an actual screenshot)
[plan] 3 steps · 4 planned files
[exec ] edited src/pagamentos/idempotencia.ts
[test] 128 passed · 1 failed (duplicate)
[exec ] attempt 2/3 · fixed composite key
[test] 129 passed · 0 failed
[gate ] waiting for approval: migration detected
How to read: each line is an auditable event. "attempt 2/3" shows the limit working; the last line shows the loop stopping on its own in response to an irreversible action—exactly the behavior you want.
Memory
What it loads
State
Where it stopped
Log
What was proven
Actual output
Never its summary
✅ Install checkers and limits
Verifiers are the tests and validations that assess the quality of the result. Limits are caps on time, cost, attempts, modified files, and permitted actions. The quality of the verifier determines how much autonomy you can grant — not the model’s quality.
📏 The limits worth configuring today
- •Changed files: keeps the diff reviewable and flags scope creep.
- •Attempts: prevents repeating the same fix in a different guise.
- •Time and cost: turns “it ran all night” into an alert, not a bill.
- •Prohibited actions: deploy, migration, secret, main branch—always with a human.
Quick check: you want to increase an agent’s autonomy in a repository. Which investment will have the biggest impact?
Verifier
Authorize autonomy
Fast test
A loop only works if it’s fast
Limit
Brake when everything else fails
Approval
Part of the harness, not an extra
📌 Module Summary
Next Module:
2.2 - Loop Engineering: the cycle that runs, tests, fixes—and knows when to stop.