[사이퍼즈 서포터] 사이트 개편 작업 회고 (v5)

5버전

 

2026.02.25 에 사이트 개편 작업을 마무리하고 배포까지 진행했습니다.

 

내부 개발 도구와 거의 모든 코드를 갈아엎으면서, 프로젝트를 다시 작성하는 수준으로 진행되었는데요.

 

최근 agentic coding을 업무에 적용해 보면서 사이퍼즈 서포터에도 적용해보면 좋을 것 같다는 가벼운 생각으로 시작했는데, 생각보다도 훨씬 더 결과물이 좋아 계속하다보니 꽤 많은 변경사항이 있었습니다.

 

작업 환경

codex cli와 cursor ide를 사용해 작업을 진행했습니다.

 

codex는 한도까지 다 사용하지는 않았는데, cursor는 claude opus 4.6을 쓰니 3시간만에 사용량이 다 털려버렸네요.

 

막바지 작업에는 opus를 주로 사용했는데 opus는 3배로 토큰이 과금됩니다.

 

codex는 한도가 넉넉하기도 하고, opus 같은 고급 모델은 사용하지 않아서 그런지 한도 걱정은 없었습니다.

 

 

작업 플로우를 요약하자면 "cursor 에서 프롬프트 작성 > codex 에서 프롬프트 md파일 전달 > cursor에서 코드 리뷰 및 수정" 으로 봐주시면 됩니다.

 

여전히 vscode 대신 cursor를 쓰고 있는 이유는 autocomplete 때문인데요.

 

cursor를 구독하더라도 autocomplete는 꺼버리는 분도 계셨는데, 저하고는 꽤 잘맞아서 문서나 코드를 작성/수정할 때 시간 단축에 큰 도움을 받고 있습니다.

 

claude 대신 codex를 사용한 이유

claude code 대신 codex를 사용한 이유는 GPT plus를 이미 구독하고 있어서 codex 가 무료 제공되어서 그렇습니다..

 

회사에서도 둘 다 써봤지만 당연히 claude code가 결과물이 더 좋았습니다만,

codex로도 충분히 가능하다고 생각했고 $20 의 추가 지출을 하기는 거부감이 들었습니다.

 

둘 중 하나를 구독하라면 코딩 작업에 한해서는 claude code를 추천하지만

저는 일상에서 쓰는 대화, 분석 등의 기능은 GPT가 더 좋다고 생각하여 덤으로 주는 codex를 사용했습니다.

 

README.md 생성 및 AGENTS.md 설정

혼자 관리하는 프로젝트다 보니 README.md 는 작성하지 않고 있었습니다.

 

codex가 정확한 동작을 할 수 있도록 README.md를 생성하고, AGENTS.md 에서 README를 먼저 읽도록 설정했습니다.

 

https://skillsmp.com/ko/skills/jeremylongshore-claude-code-plugins-plus-skills-skills-17-technical-docs-readme-generator-skill-md

 

직접 작성하는 것도 좋지만, 저는 readme-generator 스킬을 사용하여 README.md를 생성하고 결과물을 수정하는 방식으로 작업했습니다.

 

이후 AGENTS.md 를 아래와 같이 작성했습니다.

# Instructions

- 먼저 'README.md' 파일을 읽고 프로젝트를 파악하세요
  - 'README.md' 파일이 없다면, 'readme-generator' 스킬을 사용하여 'README.md' 파일을 생성하는 것을 권유합니다.
- 답변은 기본적으로 한국어(korean)로 출력해야 합니다.

 

AGENTS.md에 여러가지 주렁주렁 달아보기도 했는데, 그다지 도움은 안되고 지저분해지기만 해서 위 내용만 남기고 다 제거했습니다.

 

실제로 제가 유효하다고 느꼈던 지침은 한국어 답변 + README.md 읽기 뿐이었습니다.

 

MCP

mcp는 chrome-devtools-mcp와 context7 만 사용했습니다.

 

mcp가 여러 개 달려있으면 할 수 있는 일도 많아지지만 토큰 사용량이 증가하기도 하고, 그다지 필요한 기능도 없었습니다.

 

cli 상에서 잡히지 않는 오류(ex: 브라우저에서 페이지 로드 후 에러 발생)를 검증 및 수정시키기 위해 chrome-devtools-mcp를,

레거시 라이브러리에 대한 수정 작업이 포함될 것이기에 버전에 따른 할루시네이션을 줄이기 위해 context7을 사용했습니다.

 

Typescript 전환

typescript를 사용하지 않았을 때부터 개발한 프로젝트라서 코드의 절반은 js, jsx 로 작성되어 있습니다.

 

codex에게 아래 프롬프트를 전달하여 전환을 진행했습니다.

 

# Migrate js, jsx to ts, tsx

## description

js, jsx 파일을 ts, tsx파일로 변환합니다.

## Operation

1. 사용자에게 대상 파일 또는 디렉터리를 요구합니다.
2. 사용자가 요청한 파일 또는 디렉터리가 주어지면, `create-plan` 스킬을 사용하여 전환 계획을 수립한 다음 전환 작업을 수행합니다.

- 20개 이상의 파일이 대상일 경우, 20개씩 나누어 진행합니다.
  - 20개의 전환 작업이 완료되면, 남은 작업을 계속 진행할지 사용자에게 묻습니다.
- 전환은 병렬(parallel)로 진행합니다
- 해당 파일을 사용하는 다른 파일이 있는지를 살펴보고, 의존성이 겹치지 않는 작업끼리만 병렬로 실행합니다

3. 전환이 완료되었다면, `pnpm lint`, `pnpm test`, `pnpm typecheck` 를 실행하여 모두 통과하는지 확인합니다

- 실패했다면, 다시 수정하고 lnt, test, typecheck 실행을 반복합니다.

## Rules

- props 타입은 아래와 같은 규칙을 적용합니다
  - interface 대신 type 사용 (가능한 경우에)
  - props 타입은 컴포넌트 위쪽에 선언
  - props 타입 이름은 "컴포넌트 이름" + "Props" 로 지정

```tsx
//example

type ButtonProps = {...}
export const Button= ({}: ButtonProps)=> {};

```

 

 

이 작업을 가장 먼저 진행한 이유는, type은 그 자체로 문서 역할을 할 수 있기 때문입니다.

 

js로 되어 있는 것보다 type이 존재하면 AI가 올바른 코드를 유추하는 데 도움을 줄 수 있고,

잘못된 타입을 집어넣었을 때 typecheck 스크립트로 오류를 빠르게 잡아내고 수정할 수 있습니다.

 

기존에는 전체의 약 40%가 js, jsx코드였지만 지금은 95% 이상의 코드가 ts, tsx로 변경되었습니다.

 

create-react-app -> vite 전환

 

2019년에 생성한 프로젝트다보니 create-react-app 기반으로 작업되어 있습니다.

 

아시다시피 create-react-app은 개발이 중단되기도 했고, webpack 기반이라 속도가 정말 느립니다.

 

 

기존 webpack 기반으로는 github actions 기준으로 평균 2분 정도가 소요되었는데요.

 

빌드 속도가 느린 것 까지는 참을 수 있어도, 개발 모드 시작 시에도 굉장히 느렸다는게 문제입니다. 

 

가끔 개발 서버가 뻗어버리기도 하고, 여러모로 느린 속도와 복잡한 설정으로 개발에 많은 애로사항을 유발합니다.

 

codex를 사용해서 cra -> vite 전환 계획을 'create-plan' 스킬로 생성하게 하고,

해당 계획에 검증 조건(test, build 실행하여 정상 동작 확인)을 추가하여 codex에게 전달했습니다.

 

전환 작업 자체는 수월했고, 자잘한 오류들까지 잡는 시간까지 해서 1시간정도 걸렸던 것 같습니다.

 

 

vite로 전환 후에는 빌드에 16초밖에 걸리지 않습니다.

 

개발 모드 시작도 거의 실행과 동시에 완료되어 쾌적하게 다음 작업을 진행했습니다.

 

yarn -> pnpm 전환

기존에는 yarn pnp를 사용했습니다.

 

ci에서 매번 dependencies 를 설치하는 반복적인 과정이 낭비라고 생각되었기 때문입니다.

 

그런데 이제는 설치한 deps를 cache할 수 있게 되어 더 이상 모든 의존성을 repo에 저장할 필요가 없어졌습니다.

 

게다가 pnp 방식을 사용하면 오류가 나는 일부 의존성들도 있어 별도로 node-modules로 관리하거나 추가 설정을 해 주어야 합니다.

 

이 작업 역시 codex에게 yarn -> pnpm 전환 요청 프롬프트를 전달하고, 검증 스크립트(lint, test, build 등)가 성공하는지 체크하고 다시 수정하는 것을 반복하게 하여 30분도 걸리지 않아 완료했습니다.

 

yarn pnp

pnpm

 

오히려 이렇게 하니 repository 사이즈가 줄어들어서 그런지 actions 에서 checkout 시간이 4초에서 0초대로 줄어들었습니다.

 

deps 설치 및 리빌드(필요한 deps의 경우)도 50s -> 2s로 줄어들어 전체적으로 1분가량이 단축되었습니다.

 

material-ui -> tailwindcss + shadcn 전환

지금은 mui가 7버전까지 나와 있는데, 프로젝트 초기에 mui로 시작했던 터라 아직도 3버전을 쓰고 있었습니다.

 

여전히 material 디자인은 예쁘다고 생각하지만,

tailwindcss + shadcn 에서 AI 의 결과물이 상당히 좋은 데다 mui의 번들 사이즈가 크기 때문에 버전 업 대신 전환을 진행했습니다.

 

 material-ui/core, icons, labs 까지 mui 시리즈를 모두 사용하고 있어 작업 범위가 꽤나 커서 이건 한 번에 진행이 불가능했습니다.

 

icons와 labs는 각각 전환 프롬프트를 짜서 전달하였고,

material-ui/core의 경우에는 사용하고 있는 요소들이 많아 디테일하게 plan을 세우고 다시 여러 개의 Task로 나누어 진행했습니다.

 

 

전환 계획 문서를 생성하고, 아래에 Task list와 진행률을 agent가 수정하도록 했습니다.

 

아무래도 까다로운 작업이다 보니, 이 작업에서는 cursor의 claude opus 4.6 을 사용했습니다.

 

한 번에 처리하지 않고 여러 번의 Task로 나눠 진행하였고,

매 작업마다 문서 하단에 확인 방법을 명시하도록 하여 "작업 진행(ai)-> 작업 검증(개발자)" 을 반복했습니다.

 

 

수정한 코드 위치와 직업 확인할 수 있는 링크를 하단에 추가하도록 프롬프트를 작성하였기 때문에 검증 작업도 크게 어렵지 않았습니다.

 

여기에서 3시간만에 한달 치 커서 사용량이 전부 소진되었습니다.

 

사실 지금와서 생각해보면 sonnet 4.6으로도 충분했을 것 같네요.

 

번들 최적화

vite bundle analyze 세팅 후 아래 스킬을 사용해 과도하게 커진 번들을 축소시켰습니다.

 

---
name: build-analyze
description: analyze build output. Trigger when user request 'analyze build output' or 'optimize build output' or relative prompt.
---

# Build analyze

## Instructions

1. Run `pnpm only-build:analyze`.

- if not exist, check out `package.json` for finding build & analyze script.
  - if you cannot find build & analyze script, create adding script plan and print it. then terminate instructions.

2. Check build output.

- In this project, build output dir is `build/`. build report is `build/bundle-report.html`.

3. Analyze result and report.

- Analyze `bundle-report.html`
- Find problem about Most biggest bundle (essential)
- Find fix-required problem you think deeply
- Create plan about fixing problem solution.

 

bundle-report.html을 읽고 분석해야 하니 생각보다 토큰을 먹는 것 같은데 꽤 결과물이 좋습니다.

 

 

알아서 크기가 큰 번들을 찾아 원인을 분석하고, 다음 step을 제시해 줍니다.

 

제시한 이슈/계획을 검토하고 원하는 작업만을 수행시키면 됩니다.

 

결과는 아래와 같습니다.

 

첫 페이지에서 로드하는 모든 js 스크립트 크기: 350KB-> 293KB (-57KB)
메인 번들 크기: 292KB -> 197KB (-95KB)

 

기존에는 번들 분석 및 개선 작업을 따로 마음먹고 해야 했지만, 지금은 스킬 한번으로 간단히 처리할 수 있습니다.

 

UI 개선

UI 개선은 cursor 에서 gemini pro를 주로 사용했습니다.

 

경험 상 다른 모델보다 gemini pro가 UI 하나는 정말 예쁘게 잘 만들어 줍니다.

 

기존

 

UI 작업 후

 

그런데 유난히 AI 에게 UI 개선 작업을 시키면 border, shadow를 굉장히 많이 사용합니다.

 

이게 한두개 있을 땐 괜찮은데 사이트 전체에 border-radius, shadow가 떡칠된 요소가 많으면 난잡해보이기 때문에 프롬프트를 작성할 때 border-radius와 shadow는 사용하지 말 것(사용하더라도 xs, sm 사이즈로)을 포함해서 작업했습니다.

 

사이트 파비콘/메타 이미지 변경

 

 

새로운 사이트 마스코트를 chatGPT 와 nano banana를 사용해 만들었습니다.

 

제키엘 원본 이미지에 데포르메적 특징을 추가하도록 프롬프트를 작성했습니다.

 

이미지 프롬프팅은 처음 해보는데 손 모양, 구도와 같은 디테일한 부분 수정을 할 때 어려움이 가장 컸네요.

 

갑자기 손가락이 6개로 늘어났는데 무슨 프롬프팅을 해도 5개로 돌아오지 않기도 했고

게다가 프롬프트 입력 후 결과 이미지를 생성하는 시간이 유독 길어서 조금 짜증났었던 기억이 있습니다.

 

맺음말

처음에 말씀드렸듯 많은 개발 도구가 변경/업그레이드되고 거의 모든 코드를 다시 쓰는 수준의 큰 작업이었습니다.

 

이 포스트에서는 담지 못했던 자잘한 작업들도 많은데, 

어쨌든 중요한 것은 agentic coding 에 빨리 익숙해지는게 좋겠다는 생각이 듭니다.

 

옛날 방식대로라면 몇 배는 더 많은 시간이 들었을 작업들이지만

지금은 몇십 달러를 지불하고 간단한 사용법을 익히는 것 만으로도 많은 것을 해낼 수 있는 시대가 되었습니다.

 

감사합니다.