시리즈 목차: 역할별 AI 페르소나 하네스 구축기
1편: [AI] 일관성이 보장된 AI 개발 환경 구축하기
2편: [AI] 지속가능한 AI 개발 환경 구축하기 (읽고있는 글)
프롤로그
최근 저는 혼자서 AI를 적극적으로 활용하여 디자인 시스템을 제작하고 있습니다. 제작중인 디자인 시스템은 모노레포 환경에서 UI 패키지와, Motion 패키지 2가지를 제공합니다. 해당 디자인 시스템을 제작하며 AI를 '가상의 팀원'으로 정의하고 규칙을 토대로 일관성 있는 개발을 할 수 있도록 하는 'AI 네이티브(AI-Native) 개발'을 함께 실험하고있습니다.
지난 1편에서는 "일관성이 보장된 AI 개발 환경 구축하기"라는 제목으로 "역할별 AI 페르소나 라우터 패턴"과 "라우터 자동 동기화 시스템"을 도입한 경험을 공유했습니다.
하지만 초기 작업 구성 이후 작업을 진행하다 보니 예상치 못한 장벽에 부딪혔습니다. AI 규칙들이 점차 고도화되면서 AI가 한 번에 읽어들여야 하는 통합 설계 문서가 기하급수적으로 비대해진 것입니다.
AI가 단 한 번의 사소한 질문에 답하기 위해, 당장 필요하지도 않은 세세한 UI 패키지 규칙부터 Motion 패키지 규칙, 심지어 문서화 규칙까지 전부 훑고 있어야 했습니다. 이는 프롬프트 입력 시 소모되는 기본 토큰을 극심하게 낭비할 뿐만 아니라, 쏟아지는 규칙들 속에서 AI가 핵심 맥락을 놓쳐 답변 품질이 떨어지는 문제로 이어졌습니다.
이번 글은 이렇게 비대해진 "통합 설계 문서를 작업 스펙별로 모듈화"하여 기본적으로 소모되는 토큰량을 최적화하고, 새로운 개발 스펙과 페르소나, 라우터가 추가되더라도 유연하게 대처할 수 있도록 "단방향 AI 워크플로우"를 구축한 이야기입니다.
1. 첫 번째 개선: 설계 문서의 모듈화 (Spec 나누기)
문제를 해결하기 위한 첫 번째 접근은 통합 설계 문서를 책임에 따라 스펙(Spec) 단위로 쪼개어 모듈화하는 것이었습니다.
기존 하나의 통합 설계 문서에 빽빽하게 몰려있던 세부 구현 규약들을 과감하게 덜어내고, 전문 영역별로 '세부 스펙 문서'들을 분리했습니다.
- UI 스펙: @harryk-ds/ui 패키지 컴포넌트 구현 패턴과 스타일 지침
- Motion 스펙: @harryk-ds/motion 패키지 애니메이션 로직 및 분리 패턴
- 문서화 스펙: 문서화 전문가를 위한 JSDoc과 Storybook 패턴 가이드
이 모듈화 작업의 효과는 놀라웠습니다. 문서를 작성하는 업무가 주어지면 UI와 Motion 관련 스펙은 무시하고 오직 문서화 스펙 하나만 참조하게 됩니다. 컴포넌트를 코딩할 때 담당하게될 작업의 UI 스펙이나 Motion 스펙에만 온전히 집중하게 됩니다. 즉, 꼭 필요한 스펙만 선별적으로 가져오게 함으로써, 낭비되던 프롬프트 토큰을 크게 절약할 수 있었습니다.
(위 그림에 기재된 ui.md, motion.md, documentation.md는 각각 UI, Motion, 문서화 스펙 입니다.)
2. 두 번째 개선: 단방향 AI 워크플로우 구축
하지만 문서를 쪼갠 것만으로는 부족합니다. 쪼개진 스펙 문서들과 페르소나들 사이에서 AI가 어떤 상황에 어떤 스펙 문서와 페르소나 문서를 꺼내 읽어야 할지 길을 잃지 않도록 만들어야 했습니다.
이를 위해 허브(Hub) 문서를 최상단에 두고, 프롬프트 입력부터 결과 출력까지 한 방향으로만 흐르는 단방향 AI 워크플로우를 완성했습니다.
현재 구축된 단방향 AI 워크플로우는 다음과 같은 과정으로 작업을 수행합니다.
- 사용자 프롬프트 입력
- 규약 파일 로딩 (Launcher): 각기 다른 AI 도구의 규약 파일들(CLAUDE.md, .cursorrules 등)은 실제 룰을 담지 않습니다. 오직 '허브 문서를 여세요'라는 지시만 내립니다. - c언어의 포인터라고 생각하시면 이해하기 쉬울 것 같아요.
- 허브 로딩 (Hub): 허브가 "작업을 위한 역할 부여는 페르소나 라우터를 참고하세요" 라고 안내합니다.
- 라우터 로딩 & 페르소나 매칭 (Router & Persona): 페르소나 라우터가 사용자가 입력한 프롬프트 맥락을 분석하고 타겟 페르소나(개발, 문서화, 코드 리뷰 등)를 결정해 로딩합니다.
- 스펙 or 아키텍처 로딩 (Spec or Architecture - Optional): 결정된 페르소나 내부에 정의된 '참조 지식'에 따라, 방금 전 잘게 쪼개둔 여러 모듈 중 지금 작업에 필요한 스펙 or 아키텍처 문서만 골라서 집중적으로 읽습니다.
- 결과물 출력
이 체계를 통해 AI는 초기 진입 시 아주 가벼운 텍스트(허브)만 읽어 토큰을 방어하고, 논리를 전개해 나가면서 깊은 컨텍스트가 필요할 때만 스스로 스펙 문서를 찾아 읽게 됩니다.
또한 Top-Down 구조의 Hub > Router > Persona > Spec or Architecture 4단계의 레이어를 명확하게 분리하여 추후 새로운 라우터, 페르소나, 스펙 등의 변화에 유연하게 대처할 수 있는 구조를 구축하게 됐습니다.
에필로그: '하네스'를 위한 다음 과제
두 차례의 개선을 통해 "어떻게 AI에게 컨텍스트와 규칙을 최소 작동 메모리로 영리하게 먹일 것인가", 즉 '지속 가능한 정보 주입(Input)'에 대한 아키텍처는 꽤 견고하게 구축되었습니다. AI가 헤매지 않고 올바른 문서를 찾아 읽는 체계를 성공적으로 안착시켰습니다.
하지만 진정한 하네스(Harness)는 반드시 '주입'과 '검증'이 한 세트로 존재해야 합니다.
현재 아키텍처는 룰 주입에는 뛰어나지만, 만약 AI가 환각 현상(Hallucination)을 일으켜 프로젝트의 엄격한 스펙이나 아키텍처 규칙을 무시했을 경우, 이를 차단할 시스템이 전무하며 그에 대한 책임은 온전히 개발자에게 돌아가게 됩니다.
그래서 다음 스텝을 정했습니다. 디자인 시스템의 신뢰도를 한 차원 더 끌어올리기 위해 '테스트 페르소나(Tester)'를 도입하고 테스트 환경을 덧붙이려 합니다. 그리고 CI/CD 파이프라인에서 AI가 실수한 작업 내용을 강력하게 걸러내는 '검증 레이어 도입 구조'를 설계해볼 생각입니다.
지금까지가 "AI를 효율적이고 일관되게 일 시키는 방법"이었다면 다음 3편은 "AI가 규칙을 어겼을 때 어떻게 시스템 레벨에서 방어할 것인가"에 대한 이야기가 될 것 같습니다.
'개발이야기 > AI' 카테고리의 다른 글
| [AI] 일관성이 보장된 AI 개발 환경 구축하기 (0) | 2026.03.05 |
|---|