# HARNESS.md

> HARNESS.md is one file that records the design of a project's agent harness: where a coding agent runs, what it reads, how it checks its own work, what stops a bad change, and what it may do without asking. This site holds the format specification, a hub of ready-to-use designs, and the documentation of the harness-md plugin.

To build a harness from a hub entry: read the entry's HARNESS.md, follow its "How to use this file" section, check its Context section against the project, show the user a plan, and build only after they approve.

## Specification

- [HARNESS.md format specification](https://hoshiori-dev.github.io/harness.md/spec.md): the frontmatter keys, the thirteen recommended sections, and what a validator reports

## Hub

- [exploratory-prototype](https://hoshiori-dev.github.io/harness.md/hub/exploratory-prototype/HARNESS.md): A deliberately thin agent harness for an exploratory prototype, proof of concept, demo, spike, or research experiment: one person, a coding agent supervised turn by turn, code that is thrown away or redesigned within a quarter, and nothing a wrong change can damage. Keeps only what still matters when everything else is disposable: isolation from host credentials, a secret scan, one command that runs the thing, a smoke check, and checkpoint commits. States the triggers for moving to a heavier design.
- [production-engineering](https://hoshiori-dev.github.io/harness.md/hub/production-engineering/HARNESS.md): A full agent harness for a production codebase maintained by a team for years, where a wrong change can reach users, data, or money, and coding agents work task by task with review in between or partly unattended. Hosted on GitHub or GitLab. Covers all seven layers: an isolated environment with scoped credentials and a tool inventory, a short entrypoint with routed knowledge files, fast and full verification an agent can run itself, pre-commit and CI gates behind one summary check, a written permission policy with a protected default branch and squash merges, specification-driven completion with recorded approval, and drift control with a harness self-check.
- [solo-open-source-library](https://hoshiori-dev.github.io/harness.md/hub/solo-open-source-library/HARNESS.md): A medium-weight agent harness for a public open-source library with one maintainer who accepts outside contributions: a long-lived package whose public API other projects depend on, hosted on GitHub or GitLab, where issues and pull requests bring in text and code anyone can write. Lets a contributor's coding agent succeed without the maintainer, protects against prompt injection from public content, gates the public API with a snapshot, semantic versioning, and a changelog, asks for a short proposal only when the API changes, and keeps ceremony low everywhere else.

## Plugin

- [The harness-md plugin](https://hoshiori-dev.github.io/harness.md/plugin.md): What the harness-md plugin does, how to install it in Claude Code, Codex, and Antigravity, and which workflow fits your situation.
- [The four workflows](https://hoshiori-dev.github.io/harness.md/plugin/workflows.md): What harness-design, harness-build, harness-extract, and harness-audit each do, and what they leave behind.
- [Skills and the verifier agent](https://hoshiori-dev.github.io/harness.md/plugin/skills.md): The format skill, the methodology manual, the seven layer builders, the everyday skills, and the read-only verifier agent that ship with harness-md.
- [Using a HARNESS.md without the plugin](https://hoshiori-dev.github.io/harness.md/plugin/without-plugin.md): How to turn a HARNESS.md from the hub into a working harness with any coding agent and nothing installed.

## Optional

- [规范 (zh)](https://hoshiori-dev.github.io/harness.md/zh/spec.md): HARNESS.md 格式规范：格式的定位、frontmatter、推荐章节，以及校验器报告什么。
- [harness-md 插件 (zh)](https://hoshiori-dev.github.io/harness.md/zh/plugin.md): harness-md 插件做什么，怎样安装到 Claude Code、Codex 和 Antigravity，以及你的情况该用哪个工作流。
- [四个工作流 (zh)](https://hoshiori-dev.github.io/harness.md/zh/plugin/workflows.md): harness-design、harness-build、harness-extract 和 harness-audit 各自做什么，做完留下什么。
- [Skill 与验证 Agent (zh)](https://hoshiori-dev.github.io/harness.md/zh/plugin/skills.md): harness-md 附带的格式 skill、方法论手册、七个分层 builder、日常 skill，以及只读的验证 Agent。
- [不装插件使用 HARNESS.md (zh)](https://hoshiori-dev.github.io/harness.md/zh/plugin/without-plugin.md): 不安装任何东西，用任意编码 Agent 把 hub 里的一份 HARNESS.md 变成能用的 harness。