oh-my-harness - AI 코딩 에이전트를 위한 훅 제너레이터 CLI 실전 가이드

oh-my-harness — AI 코딩 에이전트를 위한 훅 제너레이터 CLI

oh-my-harness - AI 코딩 에이전트를 위한 훅 제너레이터 CLI 실전 가이드

AI 코딩 도구를 쓰다 보면 한 번씩은 이런 상황을 겪는다. "테스트 먼저 고쳐줘"라고 분명히 지시했는데 에이전트는 "죄송합니다 테스트를 안 고쳤습니다"라고만 한다. main 브랜치에 커밋하지 말라고 했는데 어김없이 푸시 버튼을 누른다. .env 파일은 절대 건드리지 말라며 입을 닳일 정도로 말해왔지만 어제는 또 그 파일을 열어 들여다보았다. 이런 일들이 반복될수록 우리는 "제발 잘 부탁해"라는 말보다 실수하면 바로 멈춰주는 안전장치가 절실하다는 사실을 깨닫게 된다.

바로 그 자리에 등장한 도구가 oh-my-harness다. Claude Code와 Codex 같은 AI 코딩 에이전트를 쓸 때, 단순한 프롬프트 지시가 아니라 훅(hook)과 규칙 파일을 자동으로 생성해 주는 CLI다. 자연어 한 줄이면 프로젝트에 맞는 harness 설정을 뽑아내고, 에이전트가 위험한 동작을 시도할 때 즉시 차단한다.

oh-my-harness는 무엇인가

oh-my-harness는 npm으로 설치하는 가벼운 CLI 도구다. 프로젝트 디렉터리에서 omh init 명령을 실행하면, AI 에이전트가 따라야 할 작업 규칙이 담긴 harness.yaml을 만들고, 그 규칙을 바탕으로 Claude Code용 CLAUDE.md, Codex용 AGENTS.md, 그리고 각 런타임의 hook 설정을 함께 생성한다.

핵심 아이디어는 단순하다. 에이전트를 위한 안전장치를 코드로 강제한다. 사람이 매번 "main 브랜치에는 커밋하지 마"라고 상기시켜야 했던 작업을, hook 레벨에서 시스템이 대신 막아준다.

설치 방법은 다음과 같이 매우 간단하다.

npm install -g oh-my-harness

설치 후 프로젝트 루트에서 아래 명령을 실행하면 자연어 의도에서 알맞은 규칙 세트를 골라 harness를 만들어 준다.

omh init "React app with TDD"# 또는 별도 설명 없이 기본 규칙으로 초기화omh init

어떤 규칙들을 자동 생성하나

oh-my-harness가 만들어 내는 카탈로그(미리 준비된 쉘 스크립트 모음)는 현재 아래와 같은 행동을 에이전트 레벨에서 강제한다.

• main 브랜치나 이미 머지된 브랜치에 커밋하려는 시도를 차단한다.

• 커밋 직전에 테스트나 타입체크를 실행하도록 강제한다.

• 테스트를 먼저 고치지 않고 소스 코드만 수정하려는 시도를 TDD 규칙 위반으로 차단한다.

• node_modules, dist, .next, .env 같은 민감한 파일이나 디렉터리에 대한 접근을 보호한다.

• 위험한 shell command(예: rm -rf /, 무분별한 chmod 777, 환경 변수 덤프 등)를 걸러낸다.

이 모든 것은 자연어 한 줄에서 출발한다. omh init "React app with TDD"라고 쓰면 TDD에 맞는 카탈로그가 선택되고, "next.js blog"라고 쓰면 Next.js 프로젝트에 특화된 규칙 세트가 적용된다. 작성자 본인이 "이게 또 잘 안 지켜지더라"라고 토로한 것처럼, 프롬프트로 부탁하는 방식은 한계가 있다는 인식을 바탕으로 설계된 점이 인상적이다.

왜 단순한 CLAUDE.md 설정으로는 부족한가

Claude Code나 Codex를 써 본 사람이라면 한 번쯤 CLAUDE.md나 AGENTS.md에 이런 식으로 적어 본 경험이 있을 것이다.

- 테스트 먼저 고쳐줘- 커밋 전에 테스트 돌려줘- main 브랜치에는 커밋하지 마- node_modules나 dist는 건드리지 마- .env는 수정하지 마

의도는 분명하다. 하지만 실제로는 에이전트가 컨텍스트가 길어질수록 이런 지침을 점점 무시한다. 이미 머지된 브랜치인지 확인하라고 지시했는데, 어김없이 푸시 후 "아직 머지된 브랜치가 아닙니다"라고 우기는 상황이 실제로 벌어진다. 작성자는 이 현상을 "프롬프트에 배신당한다"고 표현했다.

oh-my-harness의 해법은 규칙을 텍스트가 아니라 실행 가능한 hook으로 옮긴 것이다. harness.yaml에 명시된 규칙들은 hook 시점에서 쉘 스크립트로 평가되므로, 에이전트가 "죄송합니다"라고 답할 여지가 없다. 차단이 결정되면 그 작업은 즉시 멈춘다.

실전 활용 시나리오

실제 개발 현장에서 oh-my-harness가 특히 빛나는 시나리오를 정리했다.

1. TDD 강제

레거시 코드베이스에서 새 기능을 TDD로 추가하려고 할 때, 에이전트가 테스트 작성 없이 소스만 수정하는 일이 자주 발생한다. oh-my-harness는 테스트 파일이 변경되지 않은 상태에서 소스 파일만 수정하려는 시도를 hook 단에서 차단한다. 이 규칙은 자연어 의도에서 "TDD"라는 단어만 들어가도 자동으로 활성화된다.

2. main 브랜치 보호

main 브랜치에 직접 커밋하거나 푸시하려는 시도를 차단한다. GitHub Flow로 일하는 팀에서 이 규칙은 거의 필수인데, 에이전트가 작업하던 컨텍스트를 잃고 main에서 작업하는 사고를 막아준다.

3. 환경 변수 누설 방지

.env 파일을 읽거나 수정하려는 시도를 차단한다. AI가 가끔 디버깅 과정에서 .env 내용을 출력하려 하거나 수정하려 하는 경우가 있는데, 이 hook이 동작하면 작업 자체가 거부된다.

4. 위험한 명령어 필터링

rm -rf, chmod 777, 환경 변수 덤프(env, printenv) 같은 명령은 위험도 평가 후 차단하거나 경고를 출력한다. 자동화 도구에서 이런 명령은 의도하지 않은 데이터 손실을 일으킬 수 있으므로, hook 레벨에서의 필터링이 효과적이다.

Claude Code와 Codex에서 동시에 쓰기

oh-my-harness의 또 다른 강점은 두 런타임을 동시에 지원한다는 점이다. harness.yaml 하나를 기준으로 Claude Code용 CLAUDE.md와 Codex용 AGENTS.md를 함께 생성한다. 두 도구를 병행해서 쓰는 개발자라면, 프로젝트마다 동일한 안전 규칙을 두 환경에 일관되게 적용할 수 있다.

또한 agent용 CLI뿐 아니라 사람이 직접 확인할 수 있는 TUI도 함께 제공한다. 터미널에서 어떤 규칙이 활성화되어 있는지, 어떤 hook이 어떤 시점에 동작하는지 시각적으로 살펴볼 수 있다. 이 부분은 단순한 도구가 아니라 작은 대시보드를 곁들인 셈이다.

설치와 첫 실행

# 1. 전역 설치npm install -g oh-my-harness# 2. 프로젝트 디렉터리로 이동cd my-awesome-project# 3. 자연어로 의도 전달omh init "Next.js app with strict TypeScript and TDD"# 4. 생성된 파일 확인ls -la CLAUDE.md AGENTS.md harness.yaml

설치가 끝나면 바로 Claude Code나 Codex를 띄워 평소처럼 작업을 시작하면 된다. 에이전트는 CLAUDE.md/AGENTS.md의 지침을 읽고, 위험한 동작을 시도할 때 hook이 작동해 작업이 차단된다.

전망과 한계

아직 초기 프로젝트라 부족한 부분이 많다. 작성자 본인도 "사용해보시고 많은 의견 부탁드립니다. 기여도 환영합니다!"라고 명시적으로 호소할 정도다. 카탈로그에 포함된 규칙은 현 시점의 실무 경험을 토대로 한 것이므로, 프로젝트의 특수한 요구사항에 따라서는 harness.yaml을 직접 수정해 확장해야 할 수도 있다.

그럼에도 방향성은 분명하다. AI 코딩 도구가 단순한 코드 자동 완성을 넘어 에이전트로서 자율적으로 파일을 읽고 쓰고 커밋하는 흐름으로 진화하면서, "제발 잘 부탁해" 방식의 프롬프트 의존도에서 시스템 레벨 안전장치 중심으로 개발 워크플로우가 재편되고 있다. oh-my-harness는 그 흐름의 작은 첫 사례라 할 수 있다.

핵심 정리

• oh-my-harness는 AI 코딩 에이전트용 hook과 규칙 파일을 자동으로 생성하는 CLI다.

• 자연어 한 줄로 harness.yaml을 만들고, 그에 맞춰 CLAUDE.md/AGENTS.md를 함께 생성한다.

• main 브랜치 보호, TDD 강제, .env 접근 차단, 위험한 명령어 필터링을 hook 레벨에서 강제한다.

• 단순한 프롬프트 지시가 무시되는 문제를 시스템 레벨 차단으로 해결한다.

• Claude Code와 Codex를 동시에 지원하므로 멀티 런타임 환경에서 일관된 규칙을 적용할 수 있다.

• npm으로 즉시 설치 가능하며, TUI를 통해 활성화된 규칙을 시각적으로 확인할 수 있다.

AI 코딩 도구를 "잘 부탁해" 방식이 아니라 실수하면 멈춰주는 안전망 위에서 적극적으로 활용하고 싶다면, oh-my-harness는 가장 가볍게 시작해 볼 수 있는 선택지다.

---

📚 출처

• https://news.hada.io/topic?id=30100