AI 에이전트(Claude Code)에게 새로운 Web 툴을 만들게 할 때, 처음에는 추상적인 명세서(spec)를 전달했습니다. 디자인 규약, 컴포넌트 규칙, 금지 사항 등 말이죠. AI는 spec를 읽고 그럴듯한 것을 만들어내지만, 품질은 80% 수준에서 멈춥니다. 나머지 20%는 수정 라운드(修正ラウンド)를 통해 채워야 합니다. 이를 수십 번 반복한 끝에, 스킬(skill) 설계를 근본적으로 바꾸었습니다.

결론부터 말씀드리면, spec를 읽게 하는 것을 그만두고, 이미 프로덕션에 배포된 '움직이는 레퍼런스(reference)'를 복사하게 합니다. 그리고 '새로 만드는 스킬'과 '기존 것을 고치는 스킬'을 완전히 분리합니다. 600개 규모의 툴을 운영하며 도달한 이 두 가지 설계 판단에 관한 이야기입니다.

1. 레퍼런스(reference) 구동: 「명세를 읽고 만들어라」에서 「움직이는 실물을 복사해서 개조하라」로

spec의 문제는 작성하는 순간부터 현실과 괴리되기 시작한다는 점입니다. 구현 과정에서 얻은 세세한 판단(이 패턴에서는 padding을 이렇게 한다, 이 경우에만 예외로 한다 등)을 전부 spec에 다시 기록하는 것은 지속 가능하지 않습니다. AI는 기록되지 않은 판단을 매번 자기 방식대로 채워 넣으며, 매번 다른 결과물을 만들어냅니다.

반면, 프로덕션에서 실제로 작동하는 툴의 코드에는 그 판단이 모두 녹아들어 있습니다. 그래서 스킬을 다음과 같이 변경했습니다.

스킬 본체는 얇은 래퍼(wrapper)로 만들고, 절차의 실체는 카탈로그(정본)에 집약합니다. 카탈로그는 의사결정 트리(Decision Tree)로 시작하여, 세 가지 질문을 통해 구현 패턴을 판정합니다(Canvas 2D 직접 그리기 / html2canvas / dom-to-image / 전용 라이브러리 / Pure SVG). 판정된 패턴의 프로덕션 레퍼런스 목록에서 2개를 골라 읽습니다. 하나는 베이스(base), 하나는 차분(diff) 참조용이며, 카탈로그의 각 행에는 「다운로드 처리는 몇 번째 줄, 묘사의 핵심은 몇 번째 줄」까지 적혀 있습니다. 그 후 베이스 레퍼런스를 파일째로 복사하여, 대상 툴의 데이터 구조에 맞춰 개조합니다.

이를 통해 첫 출력 품질이 「80% + 수정 라운드」에서 거의 프로덕션 품질로 바뀌었습니다.

spec는 부패하지만, 프로덕션에서 계속 움직이고 있는 코드는 움직이는 한 부패하지 않기 때문입니다.

여담이지만, 카탈로그에는 수렴의 기록도 남습니다. 이미지 출력 툴의 구현 패턴은 5가지를 시도했고, 프로덕션의 과반수가 Canvas 2D 직접 그리기로 수렴했습니다. 「고민된다면 Canvas 2D」라는 한 줄은 이러한 수렴 데이터가 있기에 쓸 수 있는 것입니다.

2. build 스킬과 repair 스킬을 분리하기

또 다른 판단은 신규 구축과 기존 수복을 별도의 스킬로 분리한 것입니다. 똑같은 「이미지 출력 툴」을 다루는데 왜 나누는 것일까요?

이를 하나의 스킬로 섞어버리면, build의 절차서에 repair 전용 분기(branch)가 축적되어 비대해지고, repair의 참조 자료에 build의 절차가 섞여 읽어야 할 양이 늘어납니다. 어떤 용도로 쓰든 관계없는 기술을 읽고 넘겨야 하는 비용을 AI에게 지불하게 만드는 셈입니다. AI의 컨텍스트(context)는 유한하기 때문에, 이는 품질과 직결됩니다.

repair 측은 「마더쉽(mother ship)」 구조로 만들었습니다. 증상을 받아들여 카테고리(레이아웃 깨짐 / 이미지 출력 외관 / 번역 품질 / 버튼 규약 / 설명문과 구현의 괴리 / 인터랙션)로 라우팅(routing)하고, 해당되는 레퍼런스만 열게 합니다. 아직 정비되지 않은 카테고리는 스텁(stub)과 정본을 향한 포인터로 처리하여, 존재하지 않는 절차서를 지어내지 않도록 합니다.

3. 스킬은 참고 자료, 강제는 hook으로

마지막으로 책임의 경계를 하나 정했습니다. 스킬(절차서)은 참고 자료일 뿐이며, 강제력은 없습니다. AI는 읽고 지나칠 때가 있습니다. 따라서 「절대로 통과해서는 안 되는 위반 사항」은 스킬에 적는 것뿐만 아니라, write 시의 hook을 통해 기계적으로 차단합니다.

실례를 들자면, 프리뷰 요소에 특정 CSS 클래스가 남아 있으면 JS로 설정한 높이가 시각적으로 무효화되어 UI가 카드를 뚫고 나가는 버그가 있었습니다. 이것이 두 개의 툴에서 재발했습니다. 스킬에 「지워라」라고 적어도 재발했기에, hook에서 해당 클래스의 쓰기 자체를 차단하도록 설정하여 겨우 멈출 수 있었습니다. 「스킬에 적었는데도 지켜지지 않는 것」은 스킬 작성법의 문제가 아니라, 강제성을 스킬에 기대하고 있는 것이 문제였습니다.

제한과 주의사항

레퍼런스 구동은 「레퍼런스의 품질 = 출력의 상한선」입니다. 첫 번째 결과물을 제대로 만들어내는 공정은 생략할 수 없습니다. 이 부분은 spec 구동보다 초기 비용이 더 많이 발생합니다.

레퍼런스(reference)가 운영 환경에서 사라지거나 대규모로 수정되면, 카탈로그의 행 번호 정보가 오래된 것이 됩니다. 카탈로그의 유지보수 비용이 완전히 제로(zero)인 것은 아닙니다.

그리고 이 구성은 툴을 양산하는 프로젝트이기 때문에 효과적입니다. 단 하나만 만드는 대상에 카탈로그를 정비할 의미는 없습니다.

검증 시기: 2026년 4~6월. 환경: Claude Code + 자체 제작 스킬군 / 5개 언어 × 600개 이상의 Web 툴 운영.

Discussion