I. 동기
평소 AI를 활용한 바이브 코딩을 하면서 프로그램을 완성하는 것뿐만 아니라, AI가 생성한 코드의 각 부분이 어떤 역할을 하는지 쉽고 체계적으로 학습할 방법이 필요하다고 느꼈다. 기존의 코드 설명 방식은 전체 내용을 한꺼번에 보여 주기 때문에 초보자가 특정 코드와 설명을 연결하여 이해하기 어렵다는 문제가 있었다. 나와 비슷한 어려움을 겪는 사람들이 코딩을 포기하지 않고, AI가 작성한 코드를 스스로 이해하며 배울 수 있도록 돕고 싶었다. 특히 코딩을 처음 접하는 사람도 복잡한 전문 용어에 부담을 느끼지 않고 코드의 원리와 흐름을 차근차근 익힐 수 있는 도구를 만들고자 했다. 이를 위해 사용자가 선택한 코드나 화면 속 코드를 AI가 분석하고, 관련된 코드 구간을 강조하면서 쉬운 설명 카드로 보여 주는 크롬 확장 프로그램을 개발하게 되었다.
II. 스스로 탐구
프로그램을 제작하기 위해 Figma make ai를 활용하여 팝업, 미니바, 분석창 등 프론트엔드 화면의 디자인을 설계했다. 이후 Codex의 GPT-5.5를 활용해 크롬 확장 프로그램의 기본 구조를 구현하고, GPT-5.6을 활용하여 긴 코드 분할 분석, 비동기 처리, 스트리밍 응답, 오류 복구, 수정 코드 검증 등의 심화 로직을 개발했다. 또한 Gemini 3.5 Flash 사고 모델을 활용하여 화면 구성과 CSS 스타일을 점검하고 개선했다. 개발 과정에서 발생한 문제를 직접 테스트하고 원인을 분석하며, AI가 제안한 코드를 그대로 사용하는 데 그치지 않고 실제 동작 여부를 확인한 뒤 반복적으로 수정·보완하였다.
III. 주요 기능과 작동 원리
1. 사용자 맞춤 분석 설정
설정 화면에서 코드 언어, 설명 분량, 사용자 수준, 분석 항목, 문법 설명 포함 여부, 사용할 Gemini 모델 등을 지정할 수 있다.
2. 코드 입력 및 추출
웹페이지의 코드를 드래그한 뒤 우클릭하여 분석하거나, 화면 캡처로 코드 영역을 선택할 수 있다. 드래그 입력은 줄바꿈과 들여쓰기를 최대한 유지하며, 캡처 입력은 LLM의 이미지 인식 기능으로 코드 텍스트를 추출한 뒤 분석한다.
3. 분할 분석과 결과 결합
추출된 코드 언어를 자동 감지하고, 긴 코드는 함수·객체·괄호 등의 구조 경계를 기준으로 여러 구간으로 나눈다. 각 구간을 독립적으로 분석한 뒤 원본 코드 순서에 맞게 결과를 결합한다.
4. 설명 카드와 코드 강조
LLM은 관련된 연속 코드 구간을 하나의 설명 카드로 구성한다. 현재 카드의 코드는 가장 밝게, 다른 카드 관련 코드는 중간 밝기로, 관련 없는 코드는 어둡게 표시하여 코드와 설명의 대응 관계를 쉽게 파악하게 한다.
5. 후속 질문
사용자는 코드의 동작, 오류 원인, 문법, 개선 방법을 추가로 질문할 수 있다.
IV. 제작 중 생긴 문제점/해결 과정
1. Gemini 응답 시간이 매우 불규칙한 문제
같은 코드라도 몇 초 만에 끝날 때와 100초 이상 응답하지 않을 때가 있었습니다. 특히 긴 코드, 구조화 JSON 출력, 많은 카드 생성이 동시에 요구되면 응답 지연과 중단 가능성이 커졌습니다.
해결 방법:
- 사용 가능한 모델 목록을 API에서 동적으로 조회
- 입력 크기와 모델의 토큰 한도를 비교해 모델 선택
- 사용자가 모델을 직접 지정할 수 있는 설정 추가
- 선택 모델 실패 시 자동 추천 모델로 재시도
- 첫 응답 지연, 전체 응답 지연, 스트림 중단을 구분
- 긴 코드는 여러 구간으로 분리하고 최대 2개씩 병렬 처리
- 성공한 구간은 유지하고 실패한 구간만 재시도
- 요청 모델, 시도 횟수, 입력 크기, 처리 시간을 기록
- 분석창을 닫아도 서비스 워커에서 작업을 계속 수행
완전한 응답 시간 보장은 불가능하지만, 한 번의 지연으로 전체 작업을 다시 시작해야 하는 문제는 크게 줄였습니다.
2. 긴 코드를 한 번에 분석할 때 타임아웃과 JSON 손상이 발생하는 문제
약 3만 자 이상의 코드를 한 번에 보내면 출력이 중간에 끊겨 다음과 같은 오류가 발생했습니다.
오류 예시:Unterminated string in JSON
해결 방법:
- 코드 길이에 따라 자동으로 분석 구간 생성
- 가능한 경우 함수·객체·닫는 괄호 등 구조 경계에서 분할
- 각 구간을 독립된 구조화 응답으로 분석
- 구간별 대기·분석 중·완료·실패 상태 관리
- 결과 카드는 원본 코드 순서대로 다시 병합
- 카드 개수에 고정 상한을 두지 않고 코드 구조에 따라 결정
- 한 줄씩 지나치게 쪼개지 않고 관련된 연속 코드를 묶도록 프롬프트 조정
이를 통해 3만 자 이상의 코드도 부분 결과를 잃지 않고 처리할 수 있게 되었습니다.
V. 알게 된 점
이 프로젝트를 통해 크롬 확장 프로그램의 전반적인 구조를 학습했다. 확장 프로그램의 이름과 설명, 실행 권한, 동작할 사이트의 범위 등은 manifest.json 파일에 반드시 명시해야 한다는 점을 알게 되었다. 또한 HTML, CSS, JavaScript로 구성되는 팝업 화면의 구조와 역할을 이해하게 되었다.
background.js는 별도의 서버는 아니지만, 확장 프로그램 내부에서 백엔드와 유사하게 기능의 실행 흐름, 상태 관리, 메시지 처리, API 통신 등을 담당한다는 사실을 배웠다. 특히 사용자가 팝업이나 분석창을 닫더라도 필요한 작업을 이어서 처리하는 과정에서 백그라운드 스크립트의 중요성을 확인할 수 있었다.
기능 구현뿐만 아니라 로딩 상태, 오류 안내, 긴 코드 처리, 결과 확인 방식 등 사용자의 경험을 고려하는 태도가 중요하다는 점도 느꼈다. 이와 함께 API의 기본 개념을 학습하고, 직접 만든 프로그램에 LLM API를 연결하여 요청을 전송하고 응답을 처리하는 방법을 심화하여 익힐 수 있었다.
비동기 처리의 중요성도 익혔다. API 요청은 결과가 즉시 반환되지 않으므로 로딩 상태, 요청 성공과 실패, 재시도, 타임아웃 등을 각각 구분하여 처리해야 했다.
또한 사용자의 API 키와 분석 기록을 다룰 때는 보안을 고려해야 한다는 점을 배웠다. API 키의 저장 여부를 사용자가 선택할 수 있도록 하고, 프로그램의 기능을 수행하는 데 필요한 데이터만 외부 API에 전달해야 했다.
VI. 추가 활동 계획
추가 활동으로 완성한 프로그램을 크롬 웹 스토어에 배포하고 홍보하여 실제 사용자를 확보하고 싶다. 사용자들의 의견과 사용 기록을 바탕으로 문제점을 발견해 보완하고, 필요한 기능을 추가하며 지속적으로 유지·보수할 계획이다.
또한 현재 프로그램의 코드 분석 기능을 VS Code와 같은 개발 도구의 확장 프로그램으로 응용하여 출시해 보고 싶다. 이와 함께 크롬 확장 프로그램을 다양한 분야에 활용할 수 있는 방법과 다른 프로그램 및 서비스와 연동하는 방법도 조사하고 싶다.
실제 사용자를 대상으로 테스트를 진행하고, 사용성, 분석 정확도, 응답 속도 등에 관한 설문을 실시하여 프로그램의 개선 전후 결과를 비교할 계획이다.
크롬 웹 스토어 배포에 필요한 개인정보 처리 방침, 권한 사용 목적, 확장 프로그램 심사 기준을 조사하고, 해당 기준에 맞게 프로그램을 보완할 계획이다.
사용자가 분석 결과를 더욱 편리하게 관리할 수 있도록 분석 기록을 파일로 내보내거나 여러 기기에서 동기화할 수 있는 기능도 개발하고 싶다.
마지막으로 GitHub 등을 활용하여 소스 코드와 개발 과정을 정리하고, 오류 수정 및 기능 추가 내역을 체계적으로 기록하고 관리할 계획이다.
