Claude Code가 새로운 웹 도구를 구축하도록 시키기 시작했을 때, 저는 디자인 컨벤션(design conventions), 컴포넌트 규칙, 금지된 패턴과 같은 추상적인 명세(specs)를 전달했습니다. 그러면 Claude Code는 명세를 읽고 그럴듯한 결과물을 만들어냈지만, 품질은 80% 수준에서 멈췄습니다. 나머지 20%를 채우기 위해서는 여러 차례의 수정 과정이 필요했습니다. 이를 수십 번 반복한 끝에, 저는 기술 아키텍처(skill architecture)를 처음부터 다시 구축했습니다.

결론부터 말씀드리자면, 에이전트에게 명세를 읽게 하지 마세요. 대신 실제 운영 환경에 배포된 라이브 참조(live, production-deployed reference)를 복사하게 만드세요. 그리고 "새로 구축하기"와 "기존 것 수정하기"를 완전히 별개의 기술(skills)로 분리하세요. 이는 600개의 도구 플릿(fleet)을 운영하며 얻은 두 가지 설계 결정입니다.

1. 참조 기반(Reference-driven): "명세를 읽고 구축하기"에서 "작동하는 결과물을 복사하고 수정하기"로

명세의 문제는 작성하는 순간부터 현실과 괴리되기 시작한다는 점입니다. 구현 과정에서 내려지는 모든 작은 판단들 — 이 패턴에는 이 정도의 패딩(padding)을 넣는다거나, 이 케이스는 예외로 한다거나 하는 결정들 — 이 다시 명세에 기록되지 않습니다. 이는 지속 가능하지 않습니다. 결국 AI는 기록되지 않은 이러한 판단들을 매번, 그리고 매번 다르게 자신만의 방식으로 채워 넣게 됩니다.

반면, 프로덕션 코드(Production code)에는 그러한 모든 판단이 이미 녹아 있습니다. 그래서 저는 기술(skills)을 다음과 같이 재구조화했습니다.

기술 파일(skill file) 자체는 얇은 래퍼(thin wrapper)일 뿐이며, 실질적인 내용은 카탈로그(catalog, 정식 문서)에 존재합니다. 카탈로그는 결정 트리(decision tree)로 시작하며, 세 가지 질문을 통해 구현 패턴(직접 Canvas 2D / html2canvas / dom-to-image / 전용 라이브러리 / 순수 SVG)을 선택합니다. 선택된 패턴에 대해 카탈로그 목록에서 두 개의 프로덕션 참조(production references)를 골라 읽습니다. 하나는 베이스(base)로 사용하고, 다른 하나는 차이점(diffing)을 비교하기 위해 사용합니다. 각 카탈로그 행에는 다운로드 핸들러(download handler)가 어디에 있는지, 렌더링 코어(render core)가 어디에 있는지와 같은 라인 번호가 기록되어 있습니다. 그런 다음 베이스 참조를 통째로 복사한 뒤, 새로운 도구의 데이터 구조에 맞게 수정합니다.

그 결과, 첫 번째 패스(First-pass) 출력물의 품질이 "80% + 수정 단계"에서 사실상 프로덕션 품질로 올라갔습니다.

명세는 부패하지만, 프로덕션에서 계속 실행되는 코드는 계속 실행되는 한 부패하지 않습니다.

부수적인 이점: 카탈로그는 수렴(convergence)을 기록합니다. 저는 이미지 출력 도구(image-output tools)를 위해 다섯 가지 구현 패턴을 시도했습니다. 그중 대다수의 프로덕션은 직접적인 Canvas 2D로 결정되었습니다. "의심스러울 때는 Canvas 2D를 사용하라"는 이 한 줄의 원칙은 이러한 수렴 데이터가 존재하기에 기록될 수 있었습니다.

2. 구축 기술(build skills)과 수리 기술(repair skills)의 분리

두 번째 결정: 새로운 도구의 구축(construction)과 기존 도구의 수리(repair)는 서로 다른 기술(skills)에 존재합니다. 동일한 도메인인데 왜 분리할까요?

이 둘을 하나의 기술로 병합하면 두 가지 나쁜 일이 발생합니다. 구축 절차에는 수리 전용 분기(branches)가 쌓여 비대해지고, 수리 참조 자료는 구축 단계와 섞여 희석됩니다. 어느 쪽이든, 에이전트(agent)는 매번 읽을 때마다 '무관한 부분 건너뛰기 비용(skip-the-irrelevant-parts tax)'을 지불하게 됩니다. 에이전트의 컨텍스트(context)는 유한하며, 이 비용은 출력 품질(output quality)에서 직접적으로 차감됩니다.

수리 측면은 "모선(mothership)"이 되었습니다. 수리 기술은 증상을 받아 이를 카테고리(레이아웃 깨짐 / 이미지 출력 충실도 / 번역 품질 / 버튼 컨벤션 / 명세와 구현의 괴리 / 상호작용)로 라우팅하고, 해당 카테고리의 참조 자료만 엽니다. 아직 구축되지 않은 카테고리는 표준 소스(canonical source)를 가리키는 스텁(stub)으로 남겨둡니다. 따라서 에이전트가 존재하지 않는 절차를 환각(hallucinate)할 수 없게 만듭니다.

3. 기술은 참조 자료이며, 강제는 훅(hooks)의 역할이다

마지막 경계입니다. 기술(절차 문서)은 권고 사항일 뿐이며, 강제력(enforcement power)을 갖지 않습니다. 에이전트는 때때로 이를 대충 훑고 지나갑니다. 따라서 절대 배포되어서는 안 되는 위반 사항들은 단순히 기술에 적혀 있는 것이 아니라, 쓰기 시점의 훅(write-time hook)에 의해 기계적으로 차단됩니다.

구체적인 예시: 미리보기 요소에 남아있던 CSS 클래스가 JS로 설정된 높이(height)를 시각적으로 무효화하여, UI가 카드 밖으로 튀어나오는 현상이 발생했습니다. 이는 두 개의 도구에서 반복되었습니다. 스킬(skill)에 "이 클래스를 제거하라"고 작성하는 것은 이를 막지 못했습니다. 하지만 해당 클래스의 작성을 차단하는 훅(hook)은 즉각적으로 문제를 해결했습니다. "스킬에 그렇게 적혀 있었는데도 여전히 발생했다"는 것은 스킬 작성의 문제가 아닙니다. 그것은 조언(advice)으로부터 강제성(enforcement)을 기대하는 실수입니다.

한계 및 주의사항

참조 기반(Reference-driven) 방식은 참조의 품질이 결과물의 상한선(ceiling)이 된다는 것을 의미합니다. 첫 번째 참조를 제대로 구축하는 과정을 생략할 수 없으며, 이는 명세 기반(spec-driven) 방식보다 초기에 더 많은 비용이 듭니다.

참조가 프로덕션에서 제거되거나 대대적으로 재작업될 때, 카탈로그의 라인 번호(line-number) 데이터는 오래된 정보(stale)가 됩니다. 카탈로그 유지보수는 공짜가 아닙니다.

그리고 이 아키텍처는 제가 도구들을 대량으로 생산하기 때문에 보상을 제공합니다. 일회성 프로젝트를 위해 카탈로그를 구축하는 것은 의미가 없습니다.

검증됨: 2026년 4월–6월. 환경: Claude Code + 커스텀 스킬 / 600개 이상의 웹 도구 × 프로덕션 내 5개 로케일(locales).