convez.ai
AgenteAutomaçãoIntermediário
HoangTechCS-AIE

Harness Kit

HoangTechCS-AIE/harness-kit

Setup de repo para coding agents em 5 níveis de maturidade — um comando

Ver no GitHub
InicialPluginScore · de 0 a 100

Kit de inicialização para preparar repositórios como agents de IA coding (Claude Code) em 5 níveis de maturidade. Instala artefatos, configurações de guardrails, context management e observabilidade em um único comando npx.

Instalação

$npx convez-ai HoangTechCS-AIE/harness-kit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Configurar repositórios para agents Claude Code com boas práticas
  • Implementar guardrails e constraints de segurança em agents
  • Escalar trabalho de longa duração de agents com observabilidade

Veredito

Ferramenta sólida para engenheiros que querem estruturar repos para agents com disciplina. Os 5 níveis (foundation, context, guardrails, long-running, evals) cobrem falhas reais; instalação idempotente reduz atrito.

README

A tradução para o português deste README ainda está na fila.

harness-kit

Set up any repo for a coding agent (Claude Code) across the 5 maturity levels of harness engineering — in one command.

npm license node

Vietnamese · English


Harness = everything around the model (context, instructions, tools, safety constraints, orchestration, measurement) that makes an agent reliable. This kit packages it into installable artifacts plus a tutorial that teaches when to use each. The kit ships files; the tutorial teaches the discipline.

1. How it works

flowchart LR
    D([You]) -->|"npx @htechcs/harness-kit"| I[["harness-kit<br/>installer"]]
    I --> R1[".claude/<br/>settings.json · agents/"]
    I --> R2["repo root<br/>setup.sh · TASK.md"]
    I --> R3["~/.claude/skills/<br/>init-harness"]
    I --> R4["docs/harness/<br/>tutorial + guides"]
    R1 --> A([Claude Code<br/>reads every session])
    R2 --> A
    R3 --> A
    R4 --> A

One npx command drops artifacts in the right places; from there Claude Code reads them every session.

2. Quick install

npx @htechcs/harness-kit              # pick levels interactively, then install
npx @htechcs/harness-kit --all        # install all 5 levels
npx @htechcs/harness-kit --levels=1,3 # specific levels only

Requires Node ≥18. The command saves all docs into docs/harness/ so your team keeps them. Idempotent — safe to re-run (--force to overwrite).

3. The 5 levels — each prevents a failure mode

flowchart TD
    L1["Level 1 · Foundation — CLAUDE.md"] --> L2["Level 2 · Clean context"]
    L2 --> L3["Level 3 · Guardrails"]
    L3 --> L4["Level 4 · Long-running"]
    L4 --> L5["Level 5 · Evals & Observability"]
    L5 -.->|"surface a failure → reinforce the harness"| L1
LevelWithout itArtifact
1 — Foundationthe agent has no durable repo guidance/init-harness skill → generates CLAUDE.md
2 — Clean contextcontext floods, the agent's attention dilutessample subagent + MCP audit checklist
3 — Guardrailsagent deletes/pushes by mistake, asks permission nonstopsettings.json (deny/ask/allow)
4 — Long-runninglong tasks break mid-way, can't resumesetup.sh, new-worktree.sh, TASK.md
5 — Evals & Obsno idea whether the agent does well or badlygolden-task template + observability guide

4. Manual install per level

The installer just automates the cp commands below — expand them to understand/do it by hand.

cp -r skills/init-harness ~/.claude/skills/   # then run /init-harness in the target repo
mkdir -p .claude/agents && cp templates/agents/repo-explorer.md .claude/agents/

Read templates/agents/README.md + templates/mcp-audit.md.

mkdir -p .claude && cp templates/settings.json .claude/settings.json

First thing to do: add your repo's test/lint commands to allow (see templates/guardrails/README.md).

cp templates/setup.sh templates/new-worktree.sh . && chmod +x setup.sh new-worktree.sh
cp templates/long-running/TASK.md .            # when starting a long task
mkdir -p evals/cases && cp templates/evals/cases/example-task.md evals/cases/

Read templates/evals/README.md (includes a no-harness baseline step) + observability.md.

mkdir -p docs/specs && cp templates/spec/FEATURE.md docs/specs/<feature>.md

5. Level dependencies

  • Level 1 first — it's the backbone; later levels reference CLAUDE.md.
  • Levels 3 & 4 both "point CLAUDE.md to" their artifacts → require Level 1 done.
  • Level 5 needs at least one level applied to have a change to measure (see the feedback loop above).

6. Guardrails benchmark

The Level 3 guardrails are measured, not asserted. A reproducible benchmark runs a 25-op risk suite (catastrophic commands, secret-file reads, safe dev ops) through the permission rules and scores what is denied / gated / allowed.

The shipped defaults gate 68% of the suite out of the box; a hardened profile raises it to 92% — blocking 6/8 catastrophic ops and 7/7 secret-file reads. This measures guardrail policy coverage, not task success.

node bench/guardrails-bench.js                                                       # default
node bench/guardrails-bench.js templates/settings.json bench/settings.hardened.json  # before / after

See bench/RESULTS.md for methodology and the two residual gaps.

7. Docs

docs/harness-engineering-tutorial.en.md (Vietnamese) — the why + when to use each piece (after install: docs/harness/). Full industry-wide source catalog: Awesome Harness Engineering.

8. License

MIT.

Ver o original no GitHub

Bom para

Relacionados