Harness Factory

Harness Factory

Answer a few questions → download a production-ready agent harness for Claude Code, Codex, or Cursor — with deterministic guardrails wired in.

▶️ Try it live — open the hosted Harness Factory

[](http://134.185.104.194:8000)

Harness engineering is the highest-ROI lever for coding agents — but writing a good CLAUDE.md, wiring skills, picking MCP servers, and setting safe guardrails by hand is tedious and easy to get wrong. Harness Factory turns that setup into a 4-step survey and hands you a drop-in bundle.

[](https://github.com/Kimyongari/harness-factory/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/) [](#-supported-tools)

> Available in English and Korean — toggle in the top-right of the wizard. 한국어 안내는 아래 [한국어](#-한국어) 섹션을 보세요.

> 🌐 Try it live — no install: Open the hosted Harness Factory → > A hosted instance is running on Oracle Cloud free tier. Just open it, answer the 4-step survey, and download your harness .zip.

---

Why

> "Check the harness before changing the model — it's usually the best ROI." — the lesson teams keep relearning in 2026.

A model is only as good as the environment around it. Harness Factory bakes in the hard-won best practices so you don't have to:

• Context hygiene — a thin router file instead of a 1,000-line encyclopedia (avoids "everything important = nothing followed").
• Karpathy-style behavioral rules baked into skills — Think before coding, simplicity first, surgical changes, goal-driven execution. Inspired by andrej-karpathy-skills; rephrased and wired in as the default skill bodies.
• Mechanical enforcement (runtime, not prompt) — destructive commands and protected paths are blocked by hooks the runtime fires; the LLM cannot opt out. See [Deterministic enforcement](#deterministic-enforcement) below.
• Selective tools — pick only the MCP servers you need (connecting all of them rots the context window).
• Secrets stay safe — tokens go to .env only; config files reference ${VARS}, never inline.

Deterministic enforcement

Three tools, one enforcement story — the runtime (not a prompt) fires every script below:

| Event | Claude Code | Codex | Cursor | |---|---|---|---| | Before any Bash | PreToolUse → guard-bash.sh | [[hooks.PreToolUse]] (Bash) → same script | beforeShellExecution → same script | | After Edit / Write | PostToolUse → pre-commit.sh | — | afterFileEdit → same script | | After every tool call | PostToolUse (*) → trace.sh | [[hooks.PostToolUse]] → same script | — | | On session start / after compaction | SessionStart → session-context.sh | [[hooks.SessionStart]] → same script | — | | Before "done" | Stop → verify.sh | [[hooks.Stop]] → same script | via git hooks ↓ | | On commit / push (tool-agnostic) | .githooks/pre-commit + pre-push | same | same | | Always loaded | CLAUDE.md | AGENTS.md | .cursor/rules/00-overview.mdc (alwaysApply) | | Auto-attach by file type | — | — | .cursor/rules/*.mdc (globs) | | Least-privilege permissions | settings.json allow/ask/deny | — | — | | OS-level sandbox / approval | settings.json sandbox (Seatbelt/bubblewrap) | sandbox_mode=workspace-write + approval_policy=on-request | — |

guard-bash.sh blocks — before the command runs — rm -rf, force-push (incl. -f and +refspec, but not the safe --force-with-lease), --no-verify, pipe-to-shell (curl … | sh), privilege escalation (sudo, chmod 777), and any write or staging of your dev.never_touch paths (so secrets can't be committed). It extracts and decodes the command first, then matches — so quoted arguments (e.g. git commit -m "x" --no-verify) can't sneak a dangerous flag past it. verify.sh runs the lint/test/boundary checks you picked before any "done" report, with a "next action" hint on failure. trace.sh appends every tool call to .trace/tools.jsonl (git-ignored) for failure analysis. On Claude Code, settings.json's sandbox adds OS-level filesystem/credential isolation for your never-touch paths and .env.

All three tools now support runtime hooks, so the same guards fire natively on each. The bundle also ships tool-agnostic git hooks (.githooks/, enabled with git config core.hooksPath .githooks) as a backstop for commit/push. Everything is plain bash — extend by editing the files; no plugin or daemon to install. (Codex requires a one-time /hooks trust step before command hooks run — the generated config.toml says so.)

References: Claude Code hooks, Codex hooks, Cursor rules.

What you get

A 4-step survey produces a harness covering 4 domains — development, documentation, web research, and GitHub workflow — adapted to the tool you choose.

your-project/
├── CLAUDE.md / AGENTS.md / .cursor/rules/    # tool-specific instructions (Karpathy-style rules baked in)
├── .claude/skills/ · .skills/ · .cursor/rules/   # the 4 domain skill-sets / rules
├── .claude/agents/         # explorer + reviewer subagents (Claude Code)
├── .docs/                  # hierarchical context (design, specs, plans, references)
├── .scripts/
│   ├── verify.sh           # the "before done" gate — boundaries → pre-commit → post-commit
│   ├── pre-commit.sh       # fast checks you picked (lint, format, typecheck)
│   ├── post-commit.sh      # heavier checks you picked (tests)
│   ├── check-boundaries.sh # layer-direction enforcement
│   ├── guard-bash.sh       # PreToolUse guard: rm -rf, force push, pipe-to-shell, sudo/chmod 777, never_touch
│   ├── trace.sh            # PostToolUse trace: every tool call → .trace/tools.jsonl (git-ignored)
│   ├── session-context.sh  # SessionStart: re-inject branch + PLAN.md pointer after compaction
│   └── precompact-note.sh  # PreCompact: remind to persist state before lossy compaction
├── .githooks/              # tool-agnostic pre-commit + pre-push (git config core.hooksPath .githooks)
├── .claude/settings.json   # hooks + least-privilege permissions + native OS sandbox — Claude Code
├── .codex/config.toml      # sandbox + approval + the same hooks — Codex
├── .cursor/hooks.json      # beforeShellExecution + afterFileEdit runtime hooks — Cursor
├── .mcp.json / .cursor/mcp.json   # selected MCP servers per tool
└── .env(.example) + .gitignore   # tokens stay in .env; .gitignore is always included

Pick more than one tool and each output nests under claude-code/, codex/, cursor/.

📦 What's inside the harness (and why each part helps)

Every bundle is built on one idea: steer the agent with structure, and enforce the must-haves with code — not hope. In plain terms, here's what you get and why it matters.

• A thin instruction file, not a wall of text (CLAUDE.md / AGENTS.md / .cursor/rules). Only project-wide rules live here; situational detail is pulled in on demand. Bloated instruction files make agents ignore your rules — this keeps the always-loaded part small on purpose.
• 4 ready-made skills — development, doc-writing, web-research, github-workflow. Each is a focused playbook the agent loads only when relevant (progressive disclosure), with Karpathy-style habits baked in: think before coding, keep it simple, make surgical changes, work goal-first.
• Guardrails the agent can't talk its way past (guard-bash.sh + runtime hooks). Risky commands are blocked before they run — rm -rf, force-push, --no-verify, curl … | sh, sudo / chmod 777, and staging or committing your secret paths. Prompt rules are advice; these are mechanical and fire every time.
• A "before done" gate (verify.sh). The agent can't claim success until your lint / format / test / boundary checks actually pass — and on failure it gets a concrete "next action," not just red output.
• Least-privilege permissions (Claude settings.json). Reads and the checks you picked are auto-allowed; push / merge ask first; reading .env and secret paths is denied — so secrets never slip into context.
• Two helper subagents (.claude/agents/explorer, reviewer). One explores the codebase read-only; the other reviews finished work with a fresh context. They keep the main conversation clean and add an independent second pair of eyes.
• A tool-call trajectory log (trace.sh). Every tool call lands in .trace/tools.jsonl (git-ignored, auto-rotated) — agent failures are hard to reproduce, so the trace is what lets you find which tool or command went wrong.
• Secrets stay out of git — tokens live in .env only (config files reference ${VARS}), and a .gitignore covering .env plus your never-touch paths is always shipped.
• The same guards everywhere — they run on Claude Code (native hooks), Codex (config.toml hooks), and Cursor (via tool-agnostic git hooks, since Cursor rules are advisory only).

> New to harnesses? Generate one, unzip it, and skim CLAUDE.md — it routes you to everything else. The agent does the same.

🚀 Quickstart

> Don't want to install anything? A live instance is hosted — open Harness Factory and skip straight to the survey.

git clone https://github.com/Kimyongari/harness-factory.git
cd harness-factory

python -m venv .venv && source .venv/bin/activate
pip install -e .

harness-factory          # starts the web app at http://127.0.0.1:8000

Open the browser, pick English or Korean (top-right toggle), walk through the 4 steps, and download your .zip. Unzip it into your project root and you're done.

🐳 Or run with Docker

docker build -t harness-factory .
docker run --rm -p 8000:8000 harness-factory
# open http://127.0.0.1:8000

CLI

Generate from a JSON answer file (--lang ko|en):

python -m harness_maker.engine --lang en --answers tests/sample_answers.json --out harness.zip

🧩 Supported tools

| | Claude Code | Codex | Cursor | |---|---|---|---| | Instructions | CLAUDE.md | AGENTS.md | .cursor/rules/00-overview.mdc (always) | | Skills / Rules | .claude/skills/*/SKILL.md | .skills/* (referenced from AGENTS.md) | .cursor/rules/*.mdc (globs / agent-requested) | | MCP config | .mcp.json | .codex/config.toml [mcp_servers.X] | .cursor/mcp.json | | Secrets | .env (${VAR} refs) | .env (env_vars refs) | .env (${VAR} refs) | | Deterministic hooks | .claude/settings.json (SessionStart / PreToolUse / PostToolUse / PreCompact / Stop) | .codex/config.toml (same events) | .cursor/hooks.json (beforeShellExecution / afterFileEdit) + .githooks/ backstop | | Permissions / sandbox | settings.json allow/ask/deny + native sandbox | sandbox + approval policy | — | | Subagents | .claude/agents/explorer, reviewer | — | — |

Pick one or several — choosing multiple nests each under its own folder (claude-code/, codex/, cursor/). Every tool also gets the tool-agnostic .githooks/ so enforcement survives even where runtime hooks don't exist.

📋 The survey (4 steps)

1. Project — name, language, framework, package manager (dropdowns; type your own if it's not listed).
2. Dev conventions (skippable → safe defaults) — install/run commands, per-check picks for pre-commit and post-commit (each option has a one-line description so you know what it does), never-touch paths, layer boundaries, commit style.
3. Documentation (skippable → defaults) — language, tone, format.
4. Integrations & auth (skippable) — pick MCP servers, enter only the tokens they need.

Only 5 fields are required; everything else has a sensible default, so juniors can ship a good harness in under a minute.

> Wizard self-explains the bundle. Step 2 includes an inline panel describing what every .scripts/*.sh does and which runtime event fires it — no need to grep the zip to understand the layout.

🔌 MCP catalog

Curated for everyday development. Pick what you need:

GitHub · Filesystem · Brave Search · Fetch · Notion · Slack · Sentry · PostgreSQL · Sequential Thinking · Playwright

Token-based servers reveal their auth fields only when selected. Your tokens are written to .env (git-ignored) and referenced from config — never hard-coded.

🛠 How it works

survey.{ko,en}.yaml ─┐
mcp_catalog.yaml ────┤
checks_catalog.yaml ─┤→ engine: validate → defaults → substitute {{FILL}} → per-tool adapter → .zip
template/{ko,en}/ ───┘

• template/ is the framework-neutral harness, full of {{FILL:key}} placeholders.
• survey.yaml is the single source of truth for what users fill in.
• checks_catalog.yaml lists every check preset (id, command, kind, bilingual description) — the wizard renders these as a multi-select; the engine inlines the chosen commands into pre-commit.sh / post-commit.sh.
• Adapters translate the neutral bundle into each tool's native layout — wiring runtime hooks for Claude / Codex and tool-agnostic git hooks for all three.
• evals/ holds golden tasks (fix a failing test, fix a lint error) so the generated harness can be exercised against a real agent, not just unit-tested.

📂 Project structure

harness-factory/
├── survey.ko.yaml / survey.en.yaml   # 4-step survey schema (per language)
├── mcp_catalog.yaml         # curated MCP servers (bilingual descriptions)
├── checks_catalog.yaml      # 17 lint/format/typecheck/test/security check presets
├── template/ko/  ·  template/en/     # the neutral harness (filled + zipped)
├── src/harness_maker/
│   ├── engine.py            # validate · default · substitute · adapt · zip
│   ├── app.py               # FastAPI: /api/survey, /api/generate, /api/preview
│   └── static/index.html    # 4-step wizard UI (KO/EN toggle, in-line preview)
├── evals/                   # golden tasks to exercise a generated harness with a real agent
├── Dockerfile
└── tests/                   # pytest suite (120+ tests, incl. regression guards)

🧪 Development

pip install -e ".[dev]"
pre-commit install                 # lint/format hooks on commit
pre-commit install --hook-type pre-push   # run tests before push
pytest -q

Code quality is enforced by pre-commit hooks (ruff lint + format, plus YAML/JSON/TOML checks, large-file/merge-conflict/private-key guards) and a GitHub Actions CI that runs ruff check, ruff format --check, and pytest on every push and PR.

🤝 Contributing

Issues and PRs welcome — new MCP servers, new target adapters, more checks_catalog entries, and better default rules are especially appreciated. Adding a target is just one more adapter in engine.py.

📄 License

MIT — see [LICENSE](LICENSE).

---

🇰🇷 한국어

설문 몇 개에 답하면 Claude Code · Codex · Cursor용 프로덕션급 에이전트 하네스를, 결정론적 가드레일까지 박힌 상태로 zip으로 받습니다.

▶️ 바로 써보기 — 호스팅된 Harness Factory 열기

[](http://134.185.104.194:8000)

하네스 엔지니어링은 코딩 에이전트에서 ROI가 가장 높은 레버입니다. 하지만 좋은 CLAUDE.md를 쓰고, 스킬을 엮고, MCP 서버를 고르고, 안전한 가드레일을 손으로 세팅하는 일은 번거롭고 틀리기 쉽습니다. Harness Factory는 그 셋업을 4단계 설문으로 바꿔 바로 끼워 넣을 수 있는 번들을 만들어 줍니다.

> 🌐 설치 없이 바로 써보기: Harness Factory 열기 → — Oracle Cloud 무료 티어에 올려둔 라이브 인스턴스입니다. 접속해서 4단계 설문에 답하고 하네스 zip을 받으면 됩니다.

왜

> "모델을 바꾸기 전에 하네스부터 점검하라 — 대개 그게 ROI가 가장 높다." — 2026년에도 팀들이 계속 다시 배우는 교훈.

모델은 그것을 둘러싼 환경만큼만 좋습니다. Harness Factory는 어렵게 얻은 베스트 프랙티스를 기본으로 넣어, 직접 고민하지 않아도 되게 합니다.

• 컨텍스트 위생 — 1,000줄짜리 백과사전 대신 얇은 라우터 파일("전부 중요 = 아무것도 안 지켜짐" 방지).
• 스킬에 박힌 karpathy식 행동 규칙 — 생각하고 코딩 / 단순성 우선 / 외과적 변경 / 목표 주도 실행. andrej-karpathy-skills에서 영감을 받아 재서술해 기본 스킬 본문으로 엮음.
• 기계적 강제(프롬프트 아님, 런타임) — 파괴적 명령과 보호 경로는 런타임이 발동하는 훅이

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Kimyongari
• Source: Kimyongari/harness-factory
• License: MIT

Install and usage instructions live in the source repository linked above.