Agent AI기반 UI 개발 자동화 시스템

🪄 프로젝트 소개

해당 프로젝트는 프론트엔드 UI 개발 자동화 과정에서, AI 에이전트가 긴 지침 문서를 한 번에 읽을 때 발생하는 한계를 해결하기 위해 만든 시스템이에요.
기존에는 AGENTS.md, Claude.md 같은 AI 에이전트 지침 문서 안에 전역 규칙, Storybook 작성법, 디자인 시스템 메타 구조, SSE 구현 규칙 같은 내용을 모두 넣으려다 보니, 에이전트가 "제가 놓쳤습니다." 혹은 "문서가 너무 커 일부 정책을 누락했습니다." 같은 식으로 응답하는 문제가 있었어요.

해당 시스템의 핵심 아이디어는 에이전트가 지켜야 할 규율과, 작업에 따라 선택적으로 참고해야 할 지식을 분리하는 것이었어요.

• 규율은 짧은 전역 정책으로 유지해 에이전트가 항상 읽게 했어요.
• 지식은 MCP 기반 가이드 시스템으로 분리해, 현재 작업에 필요한 것만 선택적으로 읽게 했어요.

구현은 두 축으로 진행했어요.

1. frontend-guidance-mcp를 통해 에이전트가 작업 설명과 수정 경로를 바탕으로 필요한 가이드를 찾을 수 있게 했어요.
2. Markdown 기반 가이드와 Storybook 메타 JSON을 함께 지식 베이스로 구성해, 공통 모듈 사용법, 컴포넌트 구현 규칙, Story 작성 규칙, 재사용 컴포넌트 props와 예제를 구조화된 형태로 참조할 수 있게 했어요.

특히 디자인 시스템 메타 문서는 npm run build-components-docs를 통해 Storybook 정적 산출물에서 자동 생성되도록 구성했어요. 이를 통해 AI가 Storybook 번들을 직접 해석하지 않아도 components.meta.json을 기준으로 컴포넌트 이름, props 메타, 대표 args, source 예제를 읽을 수 있도록 했어요.

🛠️ 기술 스택

✨ 주요 기능

• AGENTS.md와 구현 가이드를 분리한 프론트엔드 에이전트 작업 구조
• 작업 설명과 대상 경로를 기준으로 필요한 가이드를 추천하는 resolve_guides
• 선택된 가이드의 본문, source path, canonical source를 읽는 read_guide
• 공통 모듈 사용법, 컴포넌트 구현 규칙, Story 작성 규칙을 담은 Markdown 기반 지식 베이스
• Storybook 정적 산출물에서 components.meta.json을 생성하는 디자인 시스템 문서 자동화
• 재사용 컴포넌트의 props, 대표 args, story source를 AI가 읽기 쉬운 구조화된 JSON으로 제공

💼 담당한 일

저는 해당 프로젝트에서 프론트엔드 에이전트가 안정적으로 UI 작업을 수행할 수 있도록, 정책과 지식의 경계를 설계하고 이를 실제로 탐색할 수 있는 지식 베이스 구조를 구현했어요.

• 긴 AI 에이전트 지침 문서 하나에 모든 내용을 넣는 방식의 한계를 분석하고, 전역 규율과 구현 지식을 분리하는 구조를 설계했어요.
• frontend-guidance-mcp를 통해 resolve_guides, read_guide 기반의 선택형 지식 라우팅 구조를 구현했어요.
• Markdown 기반 지식 베이스를 정리해 공통 모듈 사용법, 컴포넌트 구현 규칙, Storybook 작성 규칙을 가이드 형태로 분리했어요.
• Storybook 정적 산출물을 파싱해 재사용 컴포넌트 메타 JSON을 생성하는 스크립트를 만들고, 이를 디자인 시스템 문서로 활용할 수 있게 했어요.
• AI가 JSON 문서를 더 잘 읽는다는 점을 고려해, 컴포넌트 메타데이터 구조와 활용 방식까지 함께 문서화했어요.

🧩 해결했던 과제

해당 프로젝트에서 가장 중요했던 과제는 AI 에이전트가 항상 읽어야 할 규율과, 작업별로 선택해서 읽어야 할 구현 지식을 어떻게 분리할 것인가였어요.

문제를 그대로 두면 에이전트는 모든 작업에서 불필요하게 많은 문서를 읽게 되고, 정작 중요한 전역 규칙과 현재 작업에 필요한 구현 지식을 구분하지 못했어요. 문서가 길어질수록 "정책을 일부 놓쳤다"는 식의 응답이 나오는 것도 같은 문제의 결과였어요.

이 문제를 해결하기 위해 구조를 세 층으로 나눴어요.

• 전역 정책은 web/AGENTS.md에만 남겨, 에이전트가 반드시 지켜야 하는 규칙만 짧게 유지했어요.
• 구현 방법과 세부 지식은 frontend-guidance-mcp를 통해 작업 맥락에 맞게 선택적으로 읽도록 만들었어요.
• 재사용 컴포넌트 정보는 Storybook 빌드 산출물에서 추출한 메타 JSON으로 제공해, AI가 구조화된 방식으로 props와 예제를 읽을 수 있게 했어요.

특히 문서 드리프트를 줄이기 위해, 가이드는 설명 텍스트만 제공하는 것이 아니라 실제 코드 경로와 생성 산출물 경로를 함께 참조하도록 설계했어요. 이를 통해 AI가 문서만 믿고 구현하는 것이 아니라, 실제 근거 파일을 다시 읽고 작업하도록 유도할 수 있었어요.

📝 회고

해당 프로젝트를 통해 AI 자동화에서 중요한 것은 모델이 얼마나 많은 지식을 한 번에 읽느냐가 아니라, 지금 작업에 필요한 지식을 얼마나 정확하게 고를 수 있느냐라는 점을 분명히 느꼈어요.

특히 정책과 구현 지식을 분리하고, 구현 지식도 다시 Markdown 문서와 구조화된 JSON 메타데이터로 나누어 제공하면서, 에이전트의 작업 안정성이 높아지는 과정을 직접 확인할 수 있었어요. 이 경험을 통해 AI 에이전트를 잘 활용하려면 단순히 좋은 프롬프트를 쓰는 것이 아니라, 에이전트가 참고할 지식의 형태와 탐색 흐름 자체를 설계해야 한다는 점을 많이 배웠어요.

또한 디자인 시스템 문서를 사람이 읽는 설명만으로 유지하는 것이 아니라, Storybook 산출물에서 다시 추출한 JSON 메타 문서로 관리하면서 AI가 잘 읽을 수 있는 문서 형태를 따로 설계하는 일 자체가 자동화 품질에 큰 영향을 준다는 점도 체감했어요. 결국 해당 프로젝트는 AI가 더 똑똑해지게 만드는 작업이라기보다, AI가 실무에서 덜 놓치고 더 안정적으로 일할 수 있는 환경을 설계하는 작업에 가까웠어요.