harness.md
中文 · Website ·
Specification · Hub
HARNESS.md is one file that records how a project is set up for coding agents:
where the agent runs, what it reads, how it checks its own work,
what stops a bad change, and what it may do without asking.
That setup is the project's agent harness.
It is not another instructions file.
AGENTS.md, the knowledge files, the permission settings, the hooks,
and the CI checks are what an agent works with on every task.
HARNESS.md is the design they are built from, written down with its reasons.
An agent opens it only when the harness itself is being built, checked,
or changed.
This repository holds four things:
- the format specification;
- the hub, a collection of ready-to-use designs;
harness-md, a plugin for Claude Code, Codex,
and Antigravity that writes the file for a project,
builds the harness it describes, and checks one against the other;- the website,
where the hub can be searched.
Try it without installing anything
- Pick a design from the hub,
for example
solo-open-source-library.
- Save it as
HARNESS.md in the root of your project.
- Tell your coding agent what the project
is for and ask it to build what the file describes.
The agent comes back with a plan before it writes anything.
Expect the plan to list an AGENTS.md, a few knowledge files,
the commands that check its work, hooks and CI jobs, and permission settings.
The file is written so that an agent with no plugin
and no knowledge of the format can follow it.
Afterwards you can delete the file,
or keep it as the project's record of the design and check the harness
against it later. The format is meant for both.
The format in one minute
A HARNESS.md is YAML frontmatter that identifies the design (name,
description, and optionally version, license, metadata),
followed by a free-form Markdown body.
The body opens with a title and an introduction:
who the harness serves, what it is for, and what stays with a human.
No section is required. The format recommends thirteen English headings,
in this order, so that readers find the same subject in the same place:
| Section | What it usually covers |
|---|
| Context | The conditions the design has to fit |
| Invariants | Rules every task follows |
| Style | What the code should look like so agents can work in it |
| File Structure | The layout the design expects |
| Environment | Where the agent runs and what it can reach |
| Knowledge | What the agent reads, and when |
| Feedback | How the agent verifies its own work |
| Gates | Which checks stop defects |
| Authority | What the agent may do on its own, and what needs a human |
| Completion | How a goal is agreed and what counts as done |
| Entropy | How the harness stays consistent with the code |
| Open Questions | What is undecided |
| References | What the design drew on |
The format has one goal: the specification helps you write a HARNESS.md,
and reading one does not depend on it.
Everything in the body is ordinary prose,
and because agents rarely load the file, it can be as long as the design needs.
The specification has a Chinese translation.
The plugin
Install
- Claude Code:
/plugin install harness-md --marketplace hoshiori-dev/harness.md
(one step on Claude Code 2.1.275 or later;
on earlier versions run /plugin marketplace add hoshiori-dev/harness.md
first, then install). For local development, claude --plugin-dir ..
- Codex:
codex plugin marketplace add hoshiori-dev/harness.md,
then codex plugin add harness-md@harness-md.
- Antigravity:
agy plugin install https://github.com/hoshiori-dev/harness.md.
The scripts that ship with the skills are Python.
You need uv to run them.
What you can do with it
| You want to | Use |
|---|
| Set up a new project for agents | harness-design, then harness-build |
| Find out what is wrong with an existing setup and fix it | harness-audit, then harness-design and harness-build |
| Keep improving a project that already works with agents | harness-audit with the symptom you see |
| Write down the design a project already has (your own project, or one you want to learn from) | harness-extract |
Bring a project in line with a given HARNESS.md | harness-build |
These four skills are workflows. They run only when you invoke them by name:
/harness-md:harness-design in Claude Code, $harness-design in Codex.
Each one hands the layers of the design (Environment, Knowledge,
and so on) to the skill that knows that layer.
Validate a file
The validator checks the frontmatter, the title,
and the order and repetition of the recommended headings, and nothing else.
It requires no section and never judges the prose.
With the plugin installed, ask your agent to validate the file.
From a clone of this repository:
uv run skills/harness-md/scripts/lint_harness_md.py path/to/HARNESS.md
Contribute a hub entry
A hub entry is a complete design in hub/<name>/HARNESS.md.
The rules are in hub/README.md.
Entries come in by pull request.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
