목표: 키워드레이더의 글감·원고·KLI 흐름을 실제 운영 데이터로 확인하고, 확정된 기능을 보존하는 개발 기준 세우기
📖 소개
이번 작업은 버튼 문구와 화면 위치를 다듬는 일로 시작했지만, 실제로는 상태 판정과 API 비용, 백그라운드 작업, 브라우저 이동 기록, 운영 데이터 수집을 함께 바로잡는 작업이 됐습니다. 화면에서 원고 작성됨이라고 보여도 본문과 이미지가 없었고, 키워드 정보를 보기만 해도 글감 10개 생성이 시작됐습니다. 이미 확정했던 이미지 5장 배치가 다른 화면 경로에서 예전 UI로 돌아오는 문제도 있었습니다.
저는 문제가 생길 때마다 보이는 현상만 고치는 대신 실제 저장 데이터와 사용자의 전체 동선을 확인해 달라고 요청했습니다. Codex는 운영 API와 DB, 코드의 상태 분기, 브라우저 기록과 자동 검사를 대조했습니다. 이 과정에서 기능이 존재한다는 사실과 운영에서 정상 작동한다는 사실은 다르다는 점을 확인했습니다.
작업의 기준도 바꿨습니다. 새로운 기능을 추가하는 것만큼 지금까지 정상이라고 확정한 화면과 동작을 지키는 것이 중요했습니다. 변경한 코드 줄만 볼 것이 아니라 사용자가 누르는 순간부터 저장, 이동, 새로고침, 복원, 최종 표시까지 이어지는 흐름을 하나의 단위로 보기로 했습니다.
🛠️ 진행 방법
1. '작성한 글'이 비어 보이는 원인을 상태와 운영 데이터에서 찾았습니다
처음에는 작성한 글 화면에 기존 원고와 이미지가 하나도 나오지 않는 현상에 집중했습니다. UI를 추측으로 수정하기 전에 운영 DB에 데이터가 남아 있는지 확인했습니다. 운영 DB에는 원고 레코드가 9개 있었지만, 실제 본문과 이미지 URL 5개가 있는 완성 원고는 4개였습니다. 나머지 5개는 제목과 이미지 계획만 저장된 brief 상태였습니다.
문제는 화면마다 완료 상태를 판단하는 기준이 달랐다는 점입니다. 글감 목록은 프로젝트가 존재하기만 하면 원고가 작성됐다고 표시했고, 작성한 글 목록은 brief를 제외했습니다. 같은 데이터를 놓고 한쪽에서는 원고 열기가 보이고 다른 쪽에서는 아무것도 보이지 않았습니다. 저는 프로젝트 존재 여부가 아니라 실제 상태를 기준으로 버튼 하나만 보여주는 방향을 정했습니다.
원고가 없거나 brief이면 글 만들기
생성 작업이 남아 있으면 현재 작업을 계속할 수 있는 동작
본문과 이미지가 저장된 ready 또는 published이면 원고 열기
이 진단에서 중요한 점은 로컬 오류와 운영 장애를 섞지 않은 것입니다. 로컬에서는 샌드박스 네트워크 제한 때문에 Neon DB 연결이 실패했지만, 이를 곧바로 서비스 장애의 원인이라고 단정하지 않았습니다. 운영 API와 새 브라우저에서 완성 원고 4개 가 보이는지 따로 확인한 뒤 상태 판정 오류로 범위를 좁혔습니다.
2. 키워드 정보 조회와 유료 글감 생성을 분리했습니다
대시보드에서 키워드를 누르는 목적은 하나가 아니었습니다. KLI 해석, 네이버 관측값, 월간 검색 수요만 확인하고 싶을 수도 있는데, 기존 동작은 내 레이더로 이동하는 순간 글감 10개를 자동 생성했습니다. 화면은 느려지고 사용자가 원하지 않은 AI 비용도 발생할 수 있었습니다.
이동한 화면에서 사용자가 키워드를 직접 클릭하지 않았는데도 글감이 자동으로 생성되면 안 됩니다. 글감 생성은 사용자가 해당 화면으로 이동한 후, 그 키워드를 다시 클릭했을 때만 작동해야 합니다. 차라리 팝업창이 열리면서 "글감을 생성할까요? Yes"라고 표기를 해주는 게 나으려나? 왜 그러냐면, 우측에 있는 코스피 시황에 대한 KLI 해석 결과, 네이버 관측 원자료, 월간 검색 수요 같은 정보들을 보려고 키워드를 누를 수도 있단 말이야. 근데 누를 때마다 글감이 10개씩 생성되어 나오니까 속도도 느려지고 직관적이지 않잖아.
그러면 키워드를 눌렀을 때는 우측에 있는 정보들만 볼 수 있게 해주고, 글감 만들기는 버튼을 따로 제공하는 게 어떨까?
지금 칸이 넓으니까 우측에다가 배치하면 될 것 같아. 두 번째 첨부 이미지를 보면 지금 키워드들은 기본적으로 그렇게 길지 않잖아. 그러니까:
KLI 해석 결과를 조금 왼쪽으로 당기고
네이버 관측 정보도 당긴 다음에
맨 우측에다가 '글감 10개 만들기' 버튼을 따로 만들어 놓는 거지.
한국사이트 스크린샷
최종 흐름은 키워드 선택 시 분석 정보만 보여주고, 오른쪽의 글감 10개 만들기를 눌 렀을 때만 생성하는 방식으로 바꿨습니다. 생성 작업은 서버에 작업 ID와 상태를 저장해 사이드바 이동이나 새로고침 뒤에도 복원할 수 있게 했습니다. 대시보드, 내 레이더, 네이버 검색트렌드가 같은 선택 상태를 공유해 의도하지 않은 자동 동작이 생기지 않도록 화면별 선택도 분리했습니다.
브라우저 뒤로 가기도 함께 확인했습니다. 기존에는 메뉴와 상세 화면이 React 상태만 바꾸고 URL 기록을 남기지 않아 뒤로 가기를 누르면 앱 밖으로 빠졌습니다. 화면 상태를 쿼리 주소와 브라우저 기록에 연결한 뒤 상세, 글 만들기, 작성한 글, 대시보드 순서로 돌아갈 수 있게 했습니다.
3. 확정된 기능을 개발의 보호 기준선으로 기록했습니다
기능을 추가한 뒤 이미지 5장이 가로로 원고 위에 놓이던 최신 화면 대신, 본문 아래에 2열로 배치된 예전 편집 화면이 다시 나타났습니다. Git 커밋 자체가 과거로 돌아간 것은 아니었습니다. 최신 UI와 구형 UI가 코드에 함께 남아 있었고, 다른 동선을 연결하면서 구형 화면으로 들어가는 분기가 다시 활성화됐습니다.
한국사이트 스크린샷
저는 이 문제를 이미지 배치 하나의 실수로 보지 않았습니다. 확정된 사용자 경험을 제품 계약으로 다루지 않고, 수정한 파일과 코드 줄만 영향 범위라고 판단한 변경 관리 실패였습니다. 그래서 모든 개발 작업에 적용되는 상위 AGENTS.md에 다음 원칙을 저장했습니다.
확정된 UI·동작·데이터 흐름을 보호 기준선으로 취급하기
하나를 수정하기 전에 상태·라우팅·저장·화면·API·테스트 영향을 함께 확인하기
동일 기능은 중복하지 않고 짧고 단순한 구조로 통합하기
영향이 불분명하면 임의로 바꾸지 않고 먼저 확인하기
요청하지 않은 동작 차이가 있으면 커밋·push·배포를 중단하기
자동 검사도 새 기능의 성공 여부만 보지 않도록 바꿨습니다. 이미지가 5개인지뿐 아니라 원고보다 위에 있는지, 가로 영역이 유지되는지, 다운로드와 재생성 기능이 남아 있는지까지 보호 항목으로 고정했습니다.
4. KLI 검증 데이터는 글감 생성과 무관하게 쌓이도록 했습니다
화면에는 4주 KLI 검증 기록과 7일 후 결과 평가 대기가 표시됐지만, 문구만으로 실제 평가가 실행된다고 볼 수 없었습니다. 운영 DB를 확인하니 관측은 5일, 스냅샷은 76건이었고 이미 평가 시점이 지난 대상 4건의 결과가 0건이었습니다. 8월 6일 오전에 실행됐어야 할 일간 기록도 없었습니다.
한국사이트 스크린샷
저는 글감 생성은 KLI 데이터의 활용 기능일 뿐, 수집을 시작하는 조건이 되면 안 된다고 판단했습니다. 매일 오전 7시 30분에 관측하고 오전 9시 30분에 한 번 더 확인하되, 당일 수집과 밀린 7일 평가가 모두 끝난 날에는 외부 API를 다시 부르지 않도록 했습니다. 수집이나 평가가 빠진 경우에만 재시도가 이어집니다.
상태 문구도 대기 하나로 뭉뚱그리지 않고 28일 중 관측 일수, 일간 관측 지연, 7일 평가 지연을 구분했습니다. 과거 누락 날짜는 당시 KLI를 정확히 복원할 수 없으므로 새 값으로 채우지 않았고, 기존 76건은 보존했습니다. 이 변경은 단위 테스트, 린트, 운영 빌드, 데스크톱·모바일 UI와 실제 DB 읽기에서 확인한 뒤 96b0706으로 push하고 Vercel 운영 배포까지 완료했습니다.
5. 글 생성 설정이 실제 요청과 결과에 반영되는지 확인했습니다
문체 설정 화면은 넓고 길었지만 정작 원고 분량을 명확하게 선택할 수 없었습니다. 추가 키워드는 #키워드 뒤에 스페이스바를 눌러 확정하지 않으면 입력창에만 남았고, 장문 방향성은 API 요청에 들어가더라도 결과에서 지켜졌는지 검사하지 않았습니다.
그래서 문체 상세 설정은 접어서 필요한 경우에만 열게 했고, 원고 길이를 1,500~2,000자, 2,001~3,000자, 3,001~4,000자 세 단계로 저장하게 했습니다. 추가 키워드는 쉼표와 Enter로도 등록할 수 있게 바꾸고, 생성 직전에 최신 저장본을 다시 읽었습니다. 결과에 추가 키워드가 빠지면 한 번 자동으로 재생성하도록 했습니다.
한국사이트 스크린샷
브라우저 검사에서는 3,001~4,000자 설정, 추가 키워드 2개, 114자의 장문 방향성이 생성 요청 본문에 그대로 들어가는 것을 확인했습니다. 전체 단위 테스트 105개, 린트와 운영 빌드, 기존 이미지 5장 배치와 작성한 글 흐름도 함께 통과했습니다. 다만 실제 OpenAI 결과가 방향성의 의미를 어느 정도 충실하게 표현하는지는 실사용 생성 결과를 더 관찰해야 합니다.
마지막으로 생성 영역의 큰 제목을 기능명인 글과 이미지 한 번에 만들기에서 사용자가 선택한 글감 제목으로 바꾸고, 버튼을 글 + 이미지 한번에 만들기로 정리했습니다. 이 마지막 문구 수정은 로컬 브라우저 검증까지 완료했지만 아직 커밋·push·운영 배포 전입니다.
💡 결과와 배운 점
시행착오: 화면 하나를 수정하면서 상태 분기와 다른 진입 경로를 끝까지 확인하지 않아 구형 UI가 다시 노출됐습니다. 새 기능이 작동한다는 사실만 확인하고 기존 확정 기능의 위치와 동작을 보호하지 못한 것이 원인이었습니다.
상태 판정: 프로젝트가 존재한다는 것과 원고가 완성됐다는 것은 다릅니다. brief, draft, ready, published를 실제 저장 내용과 함께 판단해야 목록과 버튼이 일관됩니다.
비용과 의도: 키워드 정보 확인과 AI 생성을 같은 클릭에 묶으면 사용자가 원하지 않은 비용이 발생합니다. 조회와 생성을 별도 행동으로 나누고 호출 횟수로 검증해야 합니다.
운영 검증: 화면 문구나 단위 테스트만으로 Cron이 정상이라고 판단할 수 없습니다. 운영 DB의 관측일, 스냅샷, 평가 대상과 실제 실행 기록을 함께 봐야 합니다.
앞으로의 계획: 마지막 제목·버튼 수정을 커밋하고 운영 배포한 뒤, 실제 생성 원고에서 분량과 방향성 준수 정도를 계속 확인할 예정입니다.
📚 도움 받은 글 (옵션)
외부 글은 사용하지 않았습니다. 실제 Codex 대화 기록, 키워드레이더 저장소의 코드와 테스트, 운영 API·DB와 Vercel 배포 확인 결과만 근거로 작성했습니다.
