AI 코딩 하네스

무엇인가

AI 코딩 하네스는 코딩 에이전트가 무언가를 망가뜨리지 않으면서 자율적으로 동작할 수 있도록 에이전트 주위에 구축하는 강제(enforcement) 및 검증 스캐폴딩이다. 가드레일이 직접 기억해야 하는 습관(테스트를 돌려라, diff를 읽어라)이라면, 하네스는 당신 대신 기억해 주는 기계다. 에이전트의 의도와 실제 세계 사이에 자리 잡고, 위험한 단계마다 기록하거나 경고하거나 차단한다. dancinlab/harness는 프로젝트에 구애받지 않는 레퍼런스 엔진이다 — 공유되는 TypeScript 코어를 두고, 각 저장소는 오직 harness.config.json과 몇 개의 .harness/*.json 데이터 파일로만 차이를 둔다.

강점

가드레일을 선택적 습관에서 코드로 강제되는 규칙으로 바꿔 준다 — 에이전트가 건너뛸 수 없다.
도구 생애주기 전체를 통제한다: 명령이 실행되기 전, 파일이 쓰이기 전, 프롬프트 시점, 커밋 시점, 푸시 시점.
추가 전용(append-only) JSONL 원장(ledger)은 에이전트가 한 모든 일을 변조 탐지 가능한 형태로 기록한다 — 쓰기 비용은 저렴하고 감사는 손쉽다.
어떤 저장소에도 끼워 넣을 수 있다: 동작은 포크된 코드가 아니라 설정과 데이터로 정의된다.
문제가 없을 때는 조용히 있도록 설계되어, 경고가 떴을 때 그 의미가 살아 있다.

트레이드오프

이것은 배관(plumbing)이지 마법이 아니다: 하네스는 실수를 값싸게 잡아내도록 만들 뿐, AI를 옳게 만들어 주지는 않는다.
초기 설정과 프로젝트의 위험 구역에 맞춘 설정 튜닝이 필요하다.
지나치게 엄격한 규칙은 마찰을 만든다. "bitter-gate" 규율(새 규칙을 추가하기 전에 잠들어 있는 규칙을 폐기하라)은 바로 이를 막기 위해 존재한다.
실제 사용자가 있는 실제 프로젝트에서 가장 가치 있다 — 일회성 프로토타입에는 과하다.

어디에 가장 좋은가

에이전트가 여러 파일에 걸친 변경을 하고 명령을 대부분 감독 없이 실행하도록 맡기는 진지한 바이브 코딩, 그리고 잘못된 동작의 비용을 0에 가깝게 유지해야 하는 경우.

다섯 가지 원칙 (H1–H5)

H1 성공은 조용히, 실패는 시끄럽게 — 무시하는 법을 배우게 될 소음을 만들지 마라.
H2 절대 자동 수정하지 마라 — 제안하거나, 차단하거나, 경고하라. 결정은 사람이나 사정을 아는 에이전트가 한다.
H3 Bitter-gate — 새 규칙을 추가하기 전에 잠들어 있는 규칙을 폐기하라.
H4 설정 기반 — 하나의 엔진, 프로젝트별 harness.config.json.
H5 AI 네이티브 — 추가 전용 JSONL 원장, 조용히 다시 쓰는 것이 불가능하다.

어떻게 생겼나

최소 설정 스케치:

// harness.config.json
{
  "lockedPaths": ["src/auth/**", "infra/**", ".github/**"],
  "blockCommands": ["rm -rf", "git push --force", "curl * | sh"],
  "verify": ["npm run lint", "npm run typecheck", "npm test"],
  "ledger": ".harness/ledger.jsonl"
}

그리고 단일 에이전트 동작을 둘러싼 pre/post 훅 흐름:

agent intends an action
        │
   ┌────▼─────────────┐
   │ pre  (PreToolUse) │  block dangerous? warn? → else allow
   └────┬─────────────┘
        │  command runs / file is written
   ┌────▼──────────────┐
   │ post (PostToolUse) │  record to JSONL · warn if a locked file was touched
   └────┬──────────────┘
        │  at commit / push
   ┌────▼─────┐
   │  verify  │  lint · typecheck · tests (parallel) → green or stop
   └──────────┘

에이전트는 결코 이 게이트를 우회할 수 없다 — 그것이 바로 핵심이다.