[개발] 내가 사용하는 AI Code Assistant : 키오스쿨 SEO 다듬기

요즘 축제 시즌을 맞아 키오스쿨 서비스의 트러블슈팅 및 리팩토링 작업을 진행하고 있다. 빠른 생산성 향상을 위해 AI Code Assistant에 대한 의존도가 높아졌다.

최근 나에게 AI code assistant는 단순히 “코드를 대신 짜주는 도구”라기보다, 주어진 문제를 구조화하고 구현 계획을 세우고, 실제 배포 환경까지 함께 점검하는 작업 파트너에 가깝다.

이번 아티클에서는 Codex와 SEO skill을 활용해서 키오스쿨 랜딩페이지의 SEO를 개선한 과정을 정리해보려고 한다.

https://github.com/KioSchool/KioSchool/pull/486

어떤 AI assistant를 사용하였는가?

내가 사용한 방식은 단순했다. 먼저 Codex에게 키오스쿨의 홈(/) 과 소개(/info) 페이지를 중심으로 SEO 분석을 요청했다.

https://github.com/Bhanunamikaze/Agentic-SEO-Skill

여기서 SEO skill을 같이 활용하면, 지표 확인뿐 아니라 메타 태그, heading 구조, 구조화 데이터, sitemap, robots, prerender 여부 같은 항목을 꽤 체계적으로 점검할 수 있다. 특히 이번에는 로컬 코드만 보는 것이 아니라, 실제 prod URL을 기준으로 source와 응답 상태까지 같이 확인하게 했다.

이 과정을 통해 AI assistant는 세 가지 역할을 했다.

첫째, 로컬에서 관리하던 코드베이스에서 SEO 관련 수정 포인트를 빠르게 찾았다.

둘째, route별 metadata, JSON-LD, prerender, sitemap 같은 구현 계획을 구체적인 작업 단위로 바꿨다.

셋째, 배포 후에는 curl 기반 검증과 rewrite rule 문제 추적까지 같이 도와주면서, 어디서 실제 문제가 발생하는지 좁혀줬다.

왜 이 작업이 필요했나

새로운 디자인을 배포하면서 서비스의 접근성을 높이기 위해 SEO 지표를 체크하자는 의견이 있었다. 확인해 본 결과, 홈(/)과 소개 페이지(/info)가 실제 검색엔진 친화적으로 동작하지 않고 있었다. production URL을 직접 확인해보니, 두 경로 모두 같은 SPA shell HTML만 반환했고, title, description, Open Graph 메타도 사실상 동일했다. canonical도 없었고, sitemap.xml은 XML이 아니라 HTML을 응답하고 있었다.

즉 사용자는 /info에서 서비스 소개를 보고 있었지만, 검색엔진은 그 페이지를 “홈과 다른 페이지”로 충분히 이해하지 못하는 상태였다. 이 문제는 로컬 코드만 보는 것으로는 끝나지 않았다. 실제 배포 URL 기준으로 source를 봐야 했고, prerender와 hosting rewrite rule까지 함께 봐야 했다.

AI assistant를 어떻게 사용했나

이번 작업에서 AI assistant의 역할은 크게 세 가지였다.

첫째, 코드베이스를 빠르게 구조화해서 이해하는 데 도움을 받았다. 홈과 소개 페이지의 컴포넌트 구조, 라우팅 방식, 키오스쿨 합류 전 설정되어 있던 메타데이터가 어디에서 관리되는지, 현재 빌드와 배포가 어떤 흐름으로 이어지는지를 빠르게 정리할 수 있었다.

둘째, SEO 관점의 구현 계획을 기술 작업으로 바꾸는 데 썼다. “홈과 소개 페이지에 각각 다른 메타를 줘야 한다”는 요구를 react-helmet-async, route별 SEO 설정, JSON-LD, prerender, sitemap 생성으로 구체화했다. 단순 아이디어 수준이 아니라, 어떤 파일을 만들고 어떤 파일을 수정해야 하는지까지 작업 단위로 쪼갤 수 있었다.

셋째, 배포 이후 트러블슈팅에서 특히 유용했다. 로컬에서는 빌드가 잘 되는데 실제 prod, dev 환경에서는 /info가 여전히 홈 HTML을 내려주고, /sitemap.xml은 XML이 아니라 HTML을 응답하는 상황이 있었다. 이때 AI assistant는 코드 문제가 아니라 rewrite rule과 캐시 문제일 가능성을 빠르게 좁혀줬고, 실제로 그 방향이 맞았다.

이번에 적용한 SEO 개선

구현은 크게 네 가지 축으로 진행했다.

먼저 홈(/)과 소개(/info)에 route별 메타데이터를 넣었다. 각 페이지마다 다른 title, description, canonical, Open Graph, Twitter card를 반환하게 만들었다. 구조화 데이터도 홈에는 WebSite와 Organization, 소개 페이지에는 Organization과 Service를 붙였다.

다음으로 /info 페이지 상단에 전용 hero 섹션을 추가했다. 이 페이지가 단순히 내부 링크로 들어오는 보조 페이지가 아니라, 검색엔진이 “대학 축제 주점 운영을 위한 QR 주문 서비스 소개 페이지”로 이해할 수 있도록 단일 h1, 요약 문구, 핵심 기능 설명을 넣었다.

그리고 빌드 단계에서 / 와 /info를 prerender 하도록 구성했다. SPA에서 클라이언트가 렌더링한 후에야 보이는 메타가 아니라, 검색엔진이 처음 받아가는 HTML source 자체에 중요한 SEO 정보가 들어가도록 바꿨다. 이와 함께 sitemap.xml 과 robots.txt 도 빌드 결과에 맞게 생성되도록 정리했다.

마지막으로 dev 환경은 의도적으로 noindex 상태가 되게 분리했다. 이건 꽤 중요했다. (사실 초기 작업 시에는 이 지점을 까먹었다. plan 단계에서 체크하지 못 한 초보 개발자) dev 도메인에서 Lighthouse SEO 점수가 떨어지도록 수정하였다. 실제 SEO 평가는 release/prod에서만 의미가 있도록 운영과 개발 환경의 목적을 분리했다.

가장 인상 깊었던 트러블슈팅

이번 작업에서 가장 흥미로웠던 부분은 “코드가 맞는데도 결과가 틀리는 순간”이었다.

처음에는 SEO 구현 자체에 집중했다. 로컬 빌드 결과를 보면 / 와 /info 각각 다른 HTML이 잘 생성됐고, build/sitemap.xml 도 정상적으로 만들어졌다. 그런데 실제 배포 URL을 curl로 확인해보니 /info는 여전히 홈 HTML을 반환했고, /sitemap.xml도 HTML을 돌려주고 있었다.

문제는 코드가 아니라 Amplify rewrite rule이었다. /info를 /info/index.html로 보내야 했는데 SPA fallback이 먼저 잡고 있었고, sitemap.xml은 xml 예외가 빠져 있어서 index.html로 rewrite되고 있었다. 이걸 수정하고 재배포한 뒤에야 /info는 소개 페이지 전용 메타를 반환했고, /sitemap.xml도 진짜 XML로 내려오기 시작했다.

또 하나의 트러블슈팅은 CI 빌드였다. prerender 과정에서 Emotion cache 타입이 로컬과 CI fresh install 환경에서 다르게 풀리면서 TypeScript 에러가 났다. 처음엔 캐스팅으로 우회할 수 있었지만, 결국 더 깔끔한 해결은 Emotion 패키지 버전을 같은 계열로 정렬하는 것이었다. 이 과정에서 “일단 빌드만 통과시키는 임시방편”과 “패키지 해상도까지 일관되게 맞추는 근본 해결”의 차이를 분명히 느낄 수 있었다.

AI skill을 쓴다는 건 무엇인가

이번 작업을 하면서 느낀 건, AI assistant를 잘 쓰는 능력은 단순히 프롬프트를 잘 쓰는 능력과는 조금 다르다는 점이다. 오히려 중요한 건 “어떤 문제를 AI에게 맡기고, 무엇은 직접 검증해야 하는지 아는 것”에 가까웠다.

예를 들어 SEO 같은 작업은 AI가 계획 수립, 코드 수정, 점검 포인트 정리에는 강하다. 하지만 최종 검증은 반드시 실제 배포 URL, 응답 헤더, source, rewrite rule, 캐시 상태를 함께 봐야 한다. 즉 AI skill은 답을 받아내는 기술이 아니라, 문제를 구조화하고 검증 루프를 빠르게 돌리는 능력이라고 느꼈다.

또, 어떤 skill이 있는지 미리 파악하지 못 한다면 원하는 기술을 제때 활용하지 못 할 수도 있다. AI 생태계의 빠른 변화에 적응하고 꾸준한 관심을 가지는 것도 중요하다.

마무리

작성하다 보니 SEO 개선 회고가 되었지만, 필자의 초기 의도는 AI code assistant를 어떤 방식으로 서비스에 활용하고 있는지 떠들고 싶었다. 이번 작업에서 AI는 빠르게 구조를 파악하고, 구현 계획을 세우고, 트러블슈팅 가설을 제시하는 데 큰 힘이 됐다. 하지만 결과를 완성한 건 결국 실제 환경에서 검증하고, 잘못된 가정을 하나씩 지워 나간 과정이었다.