피진 영어(Pidgin English)로도 이제 부품을 찾을 수 있습니다. 제가 이를 어떻게 만들었는지 소개합니다.

몇 달 전 SpareIQ 개발을 시작했지만 완성하지 못했습니다. 마침내 완성했을 때 어떤 일이 일어났는지 소개합니다.

이 글은 GitHub Finish-Up-A-Thon Challenge를 위한 제출물입니다.

제 아버지는 제 어린 시절 대부분 동안 자동차 정비사이자 부품 판매업자로 일하셨습니다.

저는 고객들이 매일 똑같은 문제를 안고 아버지의 가게로 들어오는 것을 보았습니다. 그들은 부품이 필요했지만 그것의 명칭이 무엇인지 몰랐습니다. 그들은 "바퀴 근처에 있는 소리가 나는 둥근 고무 같은 것"이라거나 "사이드 미러를 고정하는 금속 조각" 같은 식으로 설명하곤 했습니다. 아버지는 항상 그들이 무엇을 의미하는지 알고 계셨습니다. 하지만 아버지는 한 명뿐이었고, 항상 그곳에 계실 수는 없었습니다.

그 이미지는 수년 동안 제 머릿속을 떠나지 않았습니다.

코딩을 배우기 시작했을 때, 저는 그 문제를 해결할 무언가를 만들 생각을 했습니다. 나이지리아 자동차 부품 상점들을 위한 플랫폼으로, 고객들이 엔지니어가 부품 카탈로그에 적는 방식이 아니라 실제로 말하는 방식으로 검색할 수 있는 플랫폼 말입니다. 저는 시작했습니다. 기본적인 구조를 잡았습니다. 그리고 멈췄습니다.

삶은 흘러갔고, 저는 계속해서 학습했습니다. 프로젝트는 절반만 만들어진 채 아무것도 하지 못하고 그대로 놓여 있었습니다.

Finish-Up-A-Thon은 제가 다시 돌아갈 이유를 주었습니다.

제가 만든 것

SpareIQ는 나이지리아 자동차 시장을 위해 특별히 구축된 AI 기반 부품 재고 관리 및 검색 플랫폼입니다.

제가 가장 자랑스럽게 생각하는 기능은 AI 부품 검색기(AI Part Finder)입니다. 이 기능을 열고 부품을 자연스럽게 설명하는 방식 그대로 입력하면 됩니다. 영어로 하든, 피진 영어(Pidgin)로 하든, 혹은 어떤 단어가 떠오르든 상관없습니다. AI는 기술적인 명칭을 식별하고, 카테고리를 분류하며, 실시간 재고에서 일치하는 결과를 검색합니다.

제가 "the thing wey dey stop my Toyota when I press the pedal" (페달을 밟을 때 내 토요타를 멈춰주는 그것)이라고 입력하자, 브레이크 패드(Brake Pads)라는 결과가 나왔습니다.

AI 검색기 외에도 SpareIQ는 검색 및 카테고리 필터, 부품 상세 페이지, 보호된 상점 주인 대시보드, 이미지 업로드가 포함된 전체 재고 관리 기능을 갖춘 공개 스토어프런트를 제공하며, Firebase가 모든 것을 실시간으로 구동합니다.

🌐 라이브 사이트: https://spareiq.netlify.app
💻 GitHub: https://github.com/mudimurtala/spareiq

데모 (Demo)

다음은 실제로 작동하는 SpareIQ의 전체 과정입니다:

AI 검색기 (AI finder)를 직접 테스트해보고 싶다면, spareiq.netlify.app에 접속하여 다음과 같이 입력해 보세요:

"the thing wey dey stop my Toyota when I press the pedal"

어떤 일이 일어나는지 확인해 보세요.

재기 스토리 (The Comeback Story)

이 프로젝트로 다시 돌아왔을 때, 저는 첫 한 시간 동안 과거의 제가 무엇을 만들어 놓았는지 이해하려고 클릭하며 살펴보는 데만 시간을 보냈습니다.

어떤 것들은 작동하고 있었습니다. 라우팅 (Routing)도 되어 있었고, Firebase도 연결되어 있었습니다. 페이지에 부품들도 표시되었습니다. 하지만 많은 것들이 조용히 망가져 있었으며, 만약 누군가에게 이 상태를 보여줬다면 매우 창피했을 수준이었습니다.

모든 부품 카드에 있는 '상세 보기 (View Details)' 버튼은 아무런 동작도 하지 않았습니다. 처음에는 에러가 발생해서 잘못된 페이지로 리다이렉트 (Redirect)되는 것이라고 생각했지만, 클릭해도 그냥 아무 일도 일어나지 않았습니다. 코드를 살펴보니 버튼 안에 다음과 같은 코드가 들어 있었습니다:

onClick={(e) => {
  e.preventDefault();
}}

이전에 제가 만든 프롬프트 (Prompt)가 상상 속의 더블 클릭 문제를 방지하기 위해 이 코드를 추가했는데, 그 과정에서 모든 내비게이션 (Navigation) 시도를 조용히 취소해 버린 것이었습니다. 해당 라인을 삭제하자 모든 기능이 작동하기 시작했습니다.

대시보드 (Dashboard)의 개요 페이지에는 사이드바 (Sidebar)가 있었습니다. 하지만 재고 관리 (Inventory Management)나 새 부품 추가 (Add New Part)를 클릭하는 순간, 사이드바가 완전히 사라져 버렸습니다. 브라우저의 뒤로 가기 버튼 외에는 대시보드로 돌아갈 방법이 없는 페이지에 고립되었습니다. 저는 재사용 가능한 DashboardLayout 컴포넌트 (Component)를 만들고 모든 대시보드 페이지를 이 컴포넌트로 감쌌습니다.

홈페이지의 히어로 검색 (Hero search)은 부품 (Parts) 페이지로 이동시켜 주었지만, 도착하는 순간 검색어가 사라져 버렸습니다. 부품 페이지는 사용자가 무엇을 입력했는지 전혀 알지 못했습니다. 저는 검색어가 함께 전달되어 결과가 미리 채워질 수 있도록 URL 쿼리 파라미터 (URL query parameter)를 추가했습니다.

이것들이 수정 사항들이었습니다.

그다음은 제가 새로 추가한 기능들입니다.

홈페이지가 너무 길었습니다. 부품을 단 하나도 보기 전에 스크롤을 해야만 했습니다. 저는 히어로 섹션의 패딩 (padding)을 줄였고, 그 결과 추천 부품 그리드 (featured parts grid)가 즉시 화면에 나타나게 되었습니다.

히어로 섹션과 추천 부품 섹션 사이에 '카테고리별 탐색 (Browse by Category)' 섹션을 추가했습니다. 클릭 가능한 카드 형태로, 각 카테고리마다 하나씩 구성했습니다: 엔진 (Engine), 브레이크 (Brakes), 전기 (Electrical), 서스펜션 (Suspension), 차체 부품 (Body Parts), 냉각 시스템 (Cooling System). 각 카드를 클릭하면 부품 페이지가 해당 카테고리로 필터링됩니다.

플랫폼의 차별점을 설명하는 세 개의 열로 구성된 'Why SpareIQ' 섹션을 추가했습니다. 그리고 연락처 정보, 빠른 링크, 그리고 어떤 웹사이트든 완성된 느낌을 주는 저작권 표시가 포함된 제대로 된 푸터 (footer)를 구축했습니다.

이 챌린지 이전: 작동하지 않는 버튼들, 사라지는 내비게이션, 자신의 콘텐츠를 숨기고 있는 홈페이지를 가지고 있었습니다.

이 챌린지 이후: 실제로 누군가에게 보여줄 수 있는 배포된 제품을 갖게 되었습니다.

GitHub Copilot 사용 경험

저는 GitHub Copilot을 어떻게 사용했는지에 대해 솔직해지고 싶습니다. 왜냐하면 다듬어진 버전보다 솔직한 버전이 더 유용하다고 생각하기 때문입니다.

GitHub Copilot이 SpareIQ를 만든 것이 아닙니다. 제가 만들었습니다. 하지만 그것은 무언가를 5일 만에 만드는 것과 5주 만에 만드는 것의 차이였습니다.

실제로 작동하는 방식은 이랬습니다: 저는 무엇을 만들고 싶은지 알고 프로젝트에 임했습니다. 머릿속에는 아키텍처 (architecture)가 있었고, 기능 요구 사항 (feature requirement)은 명확했으며, 원하는 사용자 경험 (user experience)도 결정된 상태였습니다. 그런 다음 저는 때로는 문단 길이만큼 상세한 프롬프트 (prompt)를 작성하여, 정확한 파일, 정확한 동작, 스택 제약 사항 (stack constraints), 엣지 케이스 (edge cases)를 설명했습니다. 그러면 Copilot이 코드를 생성했습니다. 저는 그것을 읽고, 테스트하고, 맞는지 결정했습니다.

마지막 단계가 가장 중요합니다. Copilot이 완벽하게 컴파일되고 완전히 합리적으로 보이지만 미묘하게 틀린 코드를 생성할 때가 있었습니다. 제가 언급했던 e.preventDefault() 버그는 Copilot이 Finish-Up-A-Thon 기간 동안 도입한 것이 아니었습니다. 그것은 몇 달 전 원래 빌드 과정에서 추가된 것이었으며, 제가 충분히 주의 깊게 읽지 않았기 때문에 잡아내지 못했던 것이었습니다.

제가 계속해서 배우고 있는 교훈은 AI 도구가 저를 더 빠르게 만들어 주지만, 저의 이해력을 대체하지는 못한다는 것입니다. 만약 코드를 읽고 그것이 맞는지 판단할 수 없다면, 조용한 버그(quiet bugs)들을 놓치게 될 것입니다.

저를 깊은 인상을 주었던 순간 중 하나는, DashboardLayout 컴포넌트를 구현하고 모든 대시보드 페이지를 감싸도록 Copilot에게 방대한 프롬프트(prompt)를 주었을 때였습니다. Copilot은 코드를 생성하고, 빌드(build)를 실행하고, 스스로 도입한 TypeScript 에러를 포착하여 수정하고, 다시 빌드를 실행한 뒤, 통과할 때까지 이 과정을 반복했습니다. 저는 아무것도 하지 않고 그 루프(loop)가 일어나는 것을 지켜보았습니다. 예전 같으면 디버깅(debugging)하는 데 몇 시간이 걸렸을 자가 수정(self-correction) 과정이었습니다.

AI Finder를 만드는 것 자체가 가장 흥미로운 부분이었습니다. 처음 시도했던 모델은 할당량 에러(quota errors)를 반환했습니다. Copilot은 전체 요청 구조를 다른 제공업체의 모델로 깔끔하고 빠르게 교체할 수 있도록 도와주었습니다. 재고 매칭(inventory matching)이 카테고리만으로 매칭되어 잘못된 결과를 반환할 때, 저는 제가 원하는 점수 산정 시스템(scoring system)을 평이한 언어로 설명했고, Copilot은 가중치 점수(weighted scoring)가 적용된 키워드 추출(keyword extraction)을 구현하여 매칭을 정확하게 만들었습니다.

이 프로젝트에서 GitHub Copilot과 함께 작업하는 것은, 정밀한 지침이 필요하며 감독 없이는 항상 신뢰할 수는 없지만 매우 빠른 계약업자와 함께 일하는 것과 같은 기분이었습니다. 제가 명확한 방향을 제시했을 때 결과물은 훌륭했습니다. 제가 모호하게 말했을 때 결과물은 일반적이었습니다. 그것이 구축한 결과물의 품질은 거의 전적으로 제가 요청한 내용의 품질에 의해 결정되었습니다.

SpareIQ의 기술 스택

• React 18
• TypeScript
• Tailwind CSS
• Vite
• React Router v6
• TanStack Query
• Firebase Auth 및 Firestore
• 이미지 호스팅을 위한 Cloudinary
• AI 모델 액세스를 위한 OpenRouter API
• 배포를 위한 Netlify

마지막으로

저는 나이지리아 출신의 독학 개발자입니다. 대학에서 미생물학을 공부했으며, 제가 실제로 이해하고 있는 문제들을 해결하고 싶어서 코딩을 시작했습니다.

SpareIQ는 아버지가 필요한 부품의 이름을 말하지 못하는 고객들과 대화하는 모습을 지켜보며, 더 나은 방법이 있어야 한다고 생각한 데서 시작되었습니다.

이를 완성하는 것은 오랫동안 열려 있던 루프(loop)를 닫는 듯한 기분이었습니다.

만약 여러분도 어딘가에 절반만 만들어진 무언가를 두고 있다면, 이것이 다시 시작할 수 있는 계기(nudge)가 되기를 바랍니다.