Skip to content
cloud-native-pills
Go back

Harness engineering: my quick notes

Edit page

2 min read · Intro

Overview

After experimenting with several projects built with AI, I’ve gathered the key elements of what is known as harness engineering, which consists of setting a series of guidelines and limits for AI agents so they can develop autonomously with a minimum degree of “determinism”.

From instructions you don’t want to keep repeating in prompts, such as “Act as a senior Java developer”, to specifications to implement (specs), here are the basic elements, broken down.

My goal is twofold: to practice and absorb the concepts, and to leave a dated snapshot to see how this constantly changing technology evolves.

Where everything lives

<project-root-folder>/        # the project
├── AGENTS.md                 # instructions for any agent working here
└── docs/specs/blog.md        # the spec: what to build and why

~/.agents/skills/             # reusable skills, shared across projects
├── find-skills/
└── show-me/

~/.<agent-folder>/            # the agent's memory (depends on the tool)
├── checkpoints/              # summaries of what was done and decided
├── files/                    # artifacts that don't belong in git
└── research/                 # notes gathered while investigating

What each piece is

  • Spec: what you want, written down before coding. Here I wrote it afterwards; ideally the agent builds from it.
  • AGENTS.md: a README for agents. It tells them how to work in the repo (commands, conventions, docs).
  • Skills: reusable instructions the agent loads only when the task matches.
  • Commands: saved prompts you run with /name to repeat the same task the same way.
  • Harness: everything around the model that makes it useful: tools, permissions, sub-agents and context management. The model thinks; the harness acts.
  • Checkpoints: summaries the harness saves so a long session keeps its context. There is no standard: each tool stores them its own way.
  • MCP: a standard protocol to connect the agent to external tools and data.

References



Leer en español