AGENTS.md로는 부족했다 — 팀원이 AI에게 일을 맡기는 방식을 하네스로 묶기

이름을 붙이자면 Agent Coaching Harness에 가깝다. "AI야, 이 규칙 지켜"에서 끝나는 게 아니라, AI가 작업을 시작하기 전에 요청을 좁히고, 적용한 컨벤션의 이유를 설명하고, 검증 결과를 남기게 만드는 구조다.

여기서 중요한 건 8번과 9번이다. 개인이 AI에게 어떻게 요청하는지, 어떤 실수를 반복하는지는 꽤 민감한 정보다. 그걸 바로 팀 repo에 기록하면 하네스가 코칭 도구가 아니라 감시 장부처럼 보일 수 있다.

그래서 개인 메모리와 팀 메모리를 나눴다. 개인 코칭 메모리와 작업 로그는 .agent-local/ 아래에 둔다. 이 폴더는 gitignore 대상이다. AI가 내 요청 습관이나 반복 실수를 정리하더라도, 그건 일단 내 로컬에만 남는다.

다만 AI가 팀 문서를 바로 고치지는 않는다. 먼저 proposal을 만든다. 사람이 읽고 승인하면 그때 shared memory로 올라간다.

이 흐름이 생각보다 중요했다. AI 협업을 팀에 도입할 때 가장 위험한 건 기술 실패보다 신뢰 실패일 수 있다. "AI가 내 작업 습관을 어디에 기록하는지"가 불명확하면 사람은 하네스를 쓰기 어렵다. 그래서 기록 위치와 승격 절차를 먼저 정해야 했다.

폴더를 나눈 이유는 단순하다. 프론트엔드 컨벤션과 AI 협업 규칙은 비슷해 보이지만 책임이 다르다. docs/frontend-conventions는 "이 repo에서 코드를 어떻게 써야 하는가"를 말한다. docs/ai-harness는 "AI에게 일을 어떻게 맡기고, 그 결과를 어떻게 기록할 것인가"를 말한다.

그리고 명령어는 ai-harness:init 같은 일반 이름보다 clab-harness:init처럼 프로젝트 이름을 붙이는 쪽이 맞다고 봤다. OKF가 특정 CLI 명령어 이름을 정하는 표준은 아니기 때문이다. OKF는 지식을 agent-readable하게 묶는 파일 형식과 구조에 가깝지, pnpm ai-harness:init 같은 명령어 네이밍을 강제하지 않는다.

그러면 이 명령어는 표준 구현체가 아니라 CLAB repo 안의 운영 도구가 된다. 이쪽이 더 솔직하다. "우리는 OKF식으로 읽기 좋은 지식 구조를 참고하지만, 실제 실행 명령은 CLAB Coreteam에 맞춘 clab-harness로 제공한다"는 식이다.

나중에 Google의 Open Knowledge Format, 줄여서 OKF를 보면서 이 작업이 조금 다르게 보였다. 처음엔 그냥 repo 문서를 정리한다고 생각했는데, OKF 관점에서는 이게 사실상 agent-readable knowledge bundle에 가까웠다.

OKF의 핵심은 거창한 새 DB가 아니라, AI agent가 읽기 좋은 지식 묶음을 만드는 것이다. Markdown 문서에 YAML frontmatter를 붙이고, index.md로 디렉터리 의미를 설명하고, log.md로 변경 흐름을 남기고, 문서가 어떤 source에 기대는지 citations를 남기는 식이다.

그래서 CLAB 하네스에도 그 관점을 반영했다. 각 concept 문서에 frontmatter를 붙이고, docs/frontend-conventions/index.md, docs/ai-harness/index.md, log.md를 추가했다. AI가 아무 문서나 검색해서 주워 읽는 게 아니라, 어느 문서를 먼저 읽고 어떤 변경 이력을 신뢰해야 하는지 알 수 있게 하려는 의도였다.

이건 작은 차이처럼 보이지만 실제로는 꽤 크다. agent에게 긴 README 하나를 던지는 것과, entrypoint·index·log·concept 문서로 나뉜 지식 구조를 주는 것은 다르다. 후자는 사람이 보기에도 낫고, AI가 작업 전 context를 조립하기에도 낫다.

이 작업을 하면서 기준이 조금 바뀌었다. 좋은 AI 협업 환경은 좋은 프롬프트 모음이 아니었다. 프롬프트도 필요하지만, 그보다 먼저 사람이 일을 더 명확하게 맡기고, AI가 그 판단을 검증 가능한 형태로 남기게 하는 구조가 필요했다.

그래서 CLAB 하네스는 AI를 묶는 장치라기보다, 사람과 AI가 같이 일할 때 생기는 애매함을 줄이는 장치에 가깝다. 컨벤션은 그중 하나의 재료일 뿐이다. 진짜 핵심은 작업 경계, 설명, 검증, 기록, 그리고 팀 메모리로 승격되는 절차다.

다음에 이걸 더 발전시킨다면, 단순히 문서를 늘리는 방향은 아닐 것 같다. 실제 PR에서 AI가 어떤 질문을 되묻는지, 어떤 convention을 자주 놓치는지, 어떤 proposal이 팀 규칙으로 승격되는지를 봐야 한다. 하네스는 한 번 설치해서 끝나는 도구가 아니라, 팀의 작업 방식과 같이 자라는 구조에 더 가깝다.