하네스가 명령어가 되면 안 됐다 — CLAB Agent Harness를 repo-local skill pack으로 줄인 이유

별것 아닌 차이처럼 보일 수 있다. 하지만 팀에 AI 협업 방식을 넣을 때는 이 차이가 꽤 크다. 신규 인원에게 "이 명령어를 순서대로 실행하세요"라고 말하면, 하네스는 또 하나의 내부 도구가 된다. 반대로 "평소처럼 AI에게 말하면 되고, repo가 AI에게 필요한 규칙을 알려준다"라고 만들면 진입 장벽이 낮아진다.

그래서 .claude/commands/*도 기본 구조에서는 뺐다. Claude Code에서 편의용 slash command를 둘 수는 있지만, 그게 하네스의 중심이 되면 안 된다고 봤다. 중심은 tool-specific command가 아니라 repo-local skill이다.

그렇다고 스크립트를 버린 건 아니다. 오히려 스크립트는 더 분명한 역할을 갖게 됐다. 사람에게 노출되는 명령어가 아니라, agent가 내부에서 실행하는 결정론적 helper다.

예를 들어 "테스트해줘"라고 하면 AI는 먼저 현재 diff를 보고, .agent-local/이나 .env, .next, node_modules 같은 파일이 섞였는지 확인한다. 그다음 변경 파일을 기준으로 lint/build/test 후보를 고른다. UI 변경이면 PR에 붙일 screenshot evidence 후보도 만든다.

여기서 중요한 건 사용자가 이 스크립트 이름을 몰라도 된다는 점이다. 스크립트는 하네스의 부품이지 인터페이스가 아니다. 사람이 말하는 문장은 자연어이고, agent는 그 자연어를 skill과 script로 번역한다.

이번 정리 과정에서 테스트 이야기도 나왔다. root에는 turbo run test가 있지만, 실제 패키지별로 보면 아직 테스트 체계가 잡혀 있다고 보긴 어렵다. apps/member에 Vitest와 Playwright 관련 의존성은 있지만, test script와 실제 테스트 파일은 아직 거의 없다. apps/land도 lint/build 중심이다.

그래서 지금의 clab-test는 엄밀히 말하면 unit test runner가 아니라 검증 skill에 가깝다. diff hygiene, local-only file check, lint/build 추천, screenshot plan을 묶어 "이 브랜치가 PR에 올릴 수 있는 상태인지"를 보는 쪽이다.

테스트 코드를 제대로 넣는 일은 볼륨이 크다. member 앱의 validation이나 순수 util부터 Vitest seed를 넣고, 이후 Playwright smoke test를 붙이는 식으로 가는 게 맞다. 다만 그건 이번 하네스 MVP의 범위는 아니라고 봤다. 지금은 먼저 자연어 트리거와 검증 흐름을 안정시키고, 테스트 인프라는 차후 개선으로 남긴다.

정리하면 이번 방향 전환은 기능을 줄인 게 아니라, 표면을 줄인 작업이었다.

이전 글에서 말한 Agent Coaching Harness의 문제의식은 그대로다. AI가 작업 경계를 묻고, 적용한 컨벤션의 이유를 설명하고, 검증 결과와 PR 초안을 남기게 하려는 방향은 바뀌지 않았다. 다만 그걸 구현하는 repo 표면이 달라졌다.

하네스가 너무 많이 보이면, 사람은 하네스를 쓰기 전에 하네스부터 배워야 한다. 이건 별로 좋은 방향이 아니다. 좋은 하네스는 사용자가 명령어를 외우게 만드는 장치가 아니라, 사용자가 평소처럼 말했을 때 AI가 팀의 기준 안에서 움직이게 만드는 주변 구조에 가깝다.

이번 정리로 기준이 조금 더 좁아졌다. CLAB 하네스는 거대한 문서 시스템이나 별도 제품이 아니라, repo 안에 들어가는 얇은 skill pack이어야 한다. 사람은 자연어로 요청하고, agent는 entrypoint를 통해 skill을 고르고, 필요한 rule과 script를 읽고, 결과를 .agent-local/에 남긴다.

그리고 팀 규칙으로 올릴 만한 내용은 바로 공유 문서에 쓰지 않는다. 먼저 .agent-local/proposals/에 후보로 남기고, 사람이 승인한 뒤 .agent/rules/나 Notion으로 올린다. 개인 코칭과 팀 규칙의 경계는 계속 지켜야 한다.

결국 이번 하네스의 첫 버전은 "AI를 잘 쓰는 방법 문서"가 아니라 "AI가 CLAB repo에서 덜 엇나가게 만드는 실행 표면"에 가깝다. 그래서 더 작아졌고, 오히려 더 실제 사용에 가까워졌다.