윤문 하네스를 만들고 나면 다음 질문이 따라옵니다. 이걸 어떻게 남들이 쓰게 하지? 이 도구는 Claude Code, Codex CLI, Gemini CLI 세 환경에서 모두 동작해야 했고 세 환경은 스킬을 로드하는 방식도 에이전트를 실행하는 능력도 서로 달랐습니다. 하나의 하네스를 세 갈래로 배포하며 부딪힌 문제와 그 해법을 정리합니다.
같은 지식을 세 번 복사하지 않는다
가장 먼저 정한 원칙은 분류 체계와 처방 플레이북 같은 핵심 지식을 한 벌만 유지하는 것이었습니다. 환경마다 도구 정의를 따로 두더라도, 그것들이 참조하는 지식 문서는 단일 진실 공급원 하나여야 했습니다. 지식을 세 벌로 복사하면 하나를 고칠 때 나머지가 뒤처지고 곧 세 환경의 동작이 미묘하게 어긋납니다.
그래서 저장소 안에 참조 문서를 한곳에 두고 각 환경의 스킬 정의가 그 문서를 가리키게 했습니다. Codex 쪽 스킬의 참조 폴더는 Claude 쪽 참조 폴더를 심링크로 공유합니다. 분류표를 한 번 고치면 세 환경이 같은 개정을 즉시 물려받습니다. 지식과 실행을 분리하고 지식은 절대 중복하지 않는다는 규칙이 배포 설계의 뼈대가 됐습니다.
설치는 심링크로 즉시 반영되게
설치 스크립트도 복사가 아니라 심링크를 기본으로 삼았습니다. 저장소를 클론한 뒤 스크립트를 한 줄 실행하면, 각 환경의 스킬 디렉토리와 에이전트 디렉토리에 저장소 파일을 가리키는 심링크가 걸립니다. 사용자가 저장소를 수정하면 그 변경이 즉시 반영됩니다. 개발자 도구답게, 쓰면서 고치고 고친 게 바로 도는 흐름을 만들었습니다.
스크립트는 설치된 환경을 자동으로 감지합니다. Claude만 있으면 Claude용만, 세 환경이 다 있으면 셋 다 연결하고 한쪽만 원하면 옵션으로 지정합니다. 제거와 업데이트 스크립트도 짝으로 두어 새 버전이 나오면 저장소를 당겨 받고 재설치하는 과정을 명령 한 줄로 끝냅니다. Claude Code에서는 별도로 플러그인 마켓플레이스 설치도 지원해 클론 없이 명령만으로 붙일 수 있게 했습니다.
환경의 실력 차이를 인정한다
가장 까다로운 문제는 세 환경의 실행 능력이 같지 않다는 점이었습니다. Claude Code는 여러 서브에이전트를 나눠 실행하는 다단계 파이프라인을 결정적으로 돌릴 수 있지만 Codex와 Gemini는 그 방식을 안정적으로 재현하지 못합니다. 억지로 같은 파이프라인을 세 곳에 강요하면, 능력이 부족한 환경에서 결과가 들쭉날쭉해집니다.
그래서 환경별로 제공하는 모드를 달리했습니다. Claude Code에서는 짧은 글용 단일 호출 모드와 긴 글용 다단계 정밀 모드를 모두 제공하고 Codex와 Gemini에서는 단일 호출 모드만 제공합니다. 정밀 검증이 필요하면 Claude Code를 쓰라고 안내하고 각 환경은 자기가 잘하는 것만 확실하게 합니다. 모든 환경에서 똑같이 동작하는 척하기보다, 환경의 한계를 솔직히 드러내고 그에 맞춰 기능을 조정하는 편이 신뢰를 얻는 길이었습니다.
오픈소스로 열어 둔다는 것
이 도구는 MIT 라이선스로 공개돼 있습니다. 도구를 쓰는 것뿐 아니라 분류 체계와 처방과 지표 코드까지 저장소에서 뜯어볼 수 있고 자신의 용도에 맞게 고쳐 재배포해도 됩니다. 판단 기준을 블랙박스로 감추지 않고 문서로 열어 둔 것 자체가, 이 도구가 어떤 태도로 만들어졌는지를 보여 줍니다.
이 배포 구조가 감싸는 파이프라인은 윤문 하네스의 에이전트 파이프라인에서, 환경별로 제공하는 정밀 모드의 내부는 내용을 지키는 윤문 가드레일에서 다룹니다. 전체 도구의 설계는 한글 AI 티 탐지·윤문 오픈소스 툴 사례에서 볼 수 있습니다.
자주 묻는 질문
같은 도구를 세 CLI에 어떻게 함께 유지하나요?
분류 체계와 처방 같은 핵심 지식을 단일 진실 공급원 한 벌로 두고 각 환경의 스킬 정의가 그 문서를 심링크로 공유하게 했습니다. 지식을 복사하지 않으니 한 번 고치면 세 환경이 같은 개정을 즉시 물려받아 동작이 어긋나지 않습니다.
왜 환경마다 기능이 다른가요?
Claude Code는 여러 에이전트를 나눠 실행하는 다단계 파이프라인을 안정적으로 돌릴 수 있지만 Codex와 Gemini는 그 방식을 결정적으로 재현하지 못합니다. 그래서 그 두 환경에는 단일 호출 모드만 제공하고 정밀 검증이 필요하면 Claude Code를 쓰도록 안내합니다. 환경의 한계에 맞춰 기능을 조정한 결과입니다.
오픈소스인가요? 설치는 어떻게 하나요?
MIT 라이선스로 공개돼 있습니다. Claude Code에서는 플러그인 마켓플레이스로 클론 없이 설치할 수 있고 세 환경 모두 저장소를 클론한 뒤 설치 스크립트를 한 줄 실행하면 심링크로 연결됩니다. 저장소를 고치면 변경이 바로 반영되고 업데이트와 제거도 스크립트로 처리합니다.