초보 개발자

랭크매스 SEO 16점→76점, API 함정 피하고 올린 과정

처음 랭크매스 점수를 확인했을 때 16점이 떴다. 대표 이미지도 넣었고, 카테고리도 설정했다. 뭘 더 해야 하는지 몰랐다.

왜 다 설정했는데 랭크매스 점수가 16점에서 안 움직였을까?

이상했다. 분명히 다 채웠는데 점수가 꼼짝을 안 했다. 처음엔 랭크매스 플러그인(WordPress에 설치해서 SEO를 관리하는 도구) 자체 문제인가 싶었다.

원인은 다른 데 있었다. API(Application Programming Interface, 프로그램끼리 데이터를 주고받는 통로)로 포커스 키워드(검색엔진에 “이 글은 이 단어에 집중합니다”라고 알려주는 핵심 단어)를 설정했는데, 그게 실제 랭크매스 에디터(글을 작성하고 편집하는 화면) 화면에는 반영이 안 되고 있었다. 코드로는 값을 넣었다. 근데 랭크매스는 그걸 모르는 상태였다.

겉으로는 다 설정된 것처럼 보였다. 실제 점수는 그대로였다. 이 두 가지가 동시에 사실이었다.

API로 설정한 SEO 정보, 실제로는 먹히지 않는다?

결론부터 말하면, 먹히지 않는다. 적어도 랭크매스 점수 계산에는.

Claude Code 같은 AI 도구로 WordPress API를 통해 글을 발행할 때, SEO 관련 메타(meta, 글의 제목·설명·키워드 같은 부가 정보) 값을 함께 넣을 수 있다. 기술적으로는 데이터가 전달된다. 문제는 랭크매스가 점수를 다시 계산하지 않는다는 거다.

wp-admin(WordPress 관리자 페이지) 에디터를 직접 열어보지 않으면 이걸 알 방법이 없다. 포커스 키워드 입력란이 비어 있다. 점수는 16점. API로 아무리 잘 넣어도 랭크매스 입장에선 설정 안 된 상태다.

이거 모르고 그냥 발행했으면 SEO 점수가 낮은 채로 글이 올라갈 뻔했다. 실제로 그럴 뻔했다.

위 화면이 그 상태다. API로 다 넣었다고 생각했는데, 에디터에서 확인하면 포커스 키워드 칸이 비어 있고 점수는 16점 그대로다.

에디터에서 포커스 키워드를 직접 입력했을 때 점수가 폭발한 이유

wp-admin에서 해당 글을 열었다. 랭크매스 패널(화면 한쪽에 붙어 있는 설정 영역)을 찾아서 포커스 키워드를 직접 손으로 입력했다. 저장했다.

16점에서 57점이 됐다.

한 단어 입력이 41점을 올렸다. 이게 왜 가능하냐면, 랭크매스는 포커스 키워드를 기준으로 점수를 계산하기 때문이다. 키워드가 없으면 제목에 키워드가 있는지, 본문에 키워드가 있는지 아무것도 판단을 못 한다. 기준이 생기자마자 이미 작성된 글의 내용들이 한꺼번에 점수에 반영된 거다.

API 설정이 쓸모없다는 게 아니다. 랭크매스 점수 계산만큼은 에디터 직접 입력이 기준이라는 거다. 이 차이를 모르면 계속 헤맨다.

57점에서 76점까지, 하나씩 고쳐가며 올린 체크리스트

57점에서 멈추지 않았다. 뭘 더 고쳐야 하는지 랭크매스가 항목별로 알려준다. 하나씩 고쳤다. 찔끔찔끔 올랐다. 이 과정이 은근히 나쁘지 않았다. 뭘 고쳤을 때 점수가 오르는지 직접 눈으로 보니까.

SEO 제목(검색 결과에 표시되는 글 제목)에 포커스 키워드 포함 — 제목 앞쪽에 키워드가 있어야 한다.
메타 설명(검색 결과에서 제목 아래 뜨는 짧은 소개글)에 키워드 포함 — 키워드가 자연스럽게 들어가야 한다. 억지로 끼워 넣는 느낌이면 별로다.
본문 시작 부분에 키워드 포함 — 글 앞쪽 한두 문단 안에 키워드가 나와야 한다.
소제목(h2, h3 태그로 표시되는 중간 제목)에 키워드 포함 — 모든 소제목에 다 넣을 필요는 없다. 한두 군데면 된다.
내부 링크(같은 사이트 안의 다른 글로 연결하는 링크) 1개 추가
외부 링크(다른 사이트로 연결하는 링크) 1개 추가

이 여섯 가지를 순서대로 적용했다. 76점까지 올랐다. 한 번에 다 한 게 아니라, 하나 고치고 저장하고 점수 확인하고, 다시 고치는 식으로 진행했다.

완벽한 100점을 목표로 하지 않아도 된다. 랭크매스 기준으로 70점 이상이면 초록색으로 바뀐다. 76점이면 충분하다.

API vs 에디터 직접 설정, 뭐가 다르고 어떻게 확인할까?

정리하면 이렇다.

구분	API 설정	에디터 직접 설정
데이터 저장	된다	된다
랭크매스 점수 반영	안 된다	된다
포커스 키워드 인식	안 된다	된다
확인 방법	wp-admin 에디터 열어봐야 앎	저장하면 바로 점수 업데이트

확인 방법은 하나다. wp-admin에서 해당 글의 편집 화면을 직접 열어라. 랭크매스 패널이 보이면 포커스 키워드 칸이 채워져 있는지 확인해라. 비어 있으면 API 설정은 점수에 아무 영향이 없는 상태다.

API로 글을 자동 발행하는 워크플로(작업 흐름)를 쓰고 있다면, 발행 후에 반드시 wp-admin에서 한 번 더 열어서 SEO 설정을 수동으로 확인해야 한다. 귀찮다. 근데 안 하면 낮은 점수로 그냥 올라간다.

자동화가 전부를 해결해주지는 않는다. 이번에 그걸 배웠다. 다음엔 발행 체크리스트에 “wp-admin SEO 확인” 항목을 아예 넣어둘 생각이다. 결국 랭크매스 점수 하나 때문에 발행 프로세스 자체를 다시 점검하게 됐다.

2026년 09월 12일

이미지가 삐져나가는 버그, 원인 찾고 자동화까지 한 후기
이미지가 삐져나가는 버그, 처음엔 그냥 넘어갈 뻔했다. 블로그 글을 올리고 나서 멀쩡히 보이는지 확인하는 건 습관이다. 그날도 그냥 훑어보고 있었다.

이미지가 삐져나가는 버그, 눈에 띄는 이상함: 스크린샷 하나가 삐져나가 보였던 이유

본문을 읽다가 뭔가 이상했다. 스크린샷 하나가 오른쪽으로 쏠려 있었다. 다른 이미지들은 멀쩡한데 그것만.

이유는 몰랐다. 그냥 딱 봐도 어색했다. 바로 Claude Code(클로드 코드, AI 기반 코딩 보조 도구)에 말했다. “지금 본문에서 이 이미지만 오른쪽으로 쏠려있어. 사이즈 조절해서 중앙으로 보기 좋게 다시 작성해줘.” 원인 분석보다 고치는 게 먼저였다.

아래가 당시 상태다. 텍스트 컬럼(column, 본문이 들어가는 세로 영역) 오른쪽으로 이미지가 넘쳐 있다.

이렇게 이미지가 본문 영역 밖으로 삐져나오면 레이아웃(layout, 화면 배치 구조) 전체가 깨진 것처럼 보인다. 작은 것 같지만 실제로 읽는 사람 입장에서는 바로 티가 난다.

원인은 간단했다: 업로드 스크립트가 이미지를 줄이지 않고 있었네

원인은 허무했다. 업로드 스크립트(script, 특정 작업을 자동으로 처리하는 코드 파일)가 이미지를 그대로 박아넣고 있었다. 리사이즈(resize, 이미지 크기를 줄이거나 늘리는 작업) 없이. 원본 그대로.

원본 이미지의 가로 크기가 본문 컬럼 폭보다 훨씬 넓었다. 그러니 오른쪽으로 넘칠 수밖에 없다. 알고 나니 별거 아니었다. 근데 이게 지금까지 계속 이렇게 올라가고 있었다는 게 더 문제였다.

이 버그(bug, 코드나 프로그램에서 발생하는 오류) 자체는 금방 고칠 수 있다. 문제는 따로 있다.

버그 수정만으로는 부족한 이유: 같은 실수가 반복되면?

지금 이 이미지만 고치고 끝내면 어떻게 될까. 다음에 글 올릴 때 또 같은 일이 생긴다. 스크립트가 그대로니까.

버그를 발견했을 때 그 버그만 패치(patch, 문제가 생긴 부분만 부분적으로 고치는 것)하고 넘어가는 건 임시방편이다. 원인이 코드 안에 남아 있으면 같은 실수는 반드시 다시 나온다. 타이밍만 다를 뿐이다.

그래서 바로 한 마디 더 붙였다. “처음부터 작성할 때 이런 것 체크해서 최종 마무리해줘.” 재발 방지까지 해야 진짜 끝난 거라고 생각했다.

자동화로 근본 해결하기: 스크립트에 리사이즈 기능 추가하기

수정 방향은 하나였다. 업로드 스크립트 자체를 고치는 것.

이미지를 올릴 때마다 수동으로 크기를 확인하는 건 지속 가능하지 않다. 귀찮으면 빠뜨리게 돼 있다. 그러니 스크립트가 알아서 처리하게 만드는 게 맞다.

Claude Code에 요청해서 업로드 스크립트를 수정했다. 핵심은 두 가지다.
- 새 글을 올릴 때 이미지가 자동으로 본문 폭에 맞게 리사이즈된다.
- 리사이즈된 이미지는 중앙 정렬(center align, 요소를 화면 가운데에 배치하는 것)로 삽입된다.
이제 이미지 크기를 신경 쓰지 않아도 된다. 스크립트가 처리한다. 이게 자동화(automation, 사람이 직접 하던 작업을 코드가 대신 처리하도록 만드는 것)의 의미다. 한 번 제대로 만들어두면 그 다음부터는 신경 끄면 된다.

재발 방지까지: 업로드 후 최종 확인 프로세스 정하기

스크립트를 고치는 것만으로는 완전하지 않다고 봤다. 코드가 제대로 동작하는지 눈으로 확인하는 단계가 없으면 또 다른 문제가 조용히 지나갈 수 있다.

그래서 규칙을 명확히 정했다. Claude Code에 이렇게 못 박았다.
- 이미지는 본문 폭 안에 딱 맞게, 중앙 정렬로 들어가야 한다.
- 업로드 후에는 Claude Code가 직접 최종 확인을 하고, 그 결과를 나한테 컨펌(confirm, 맞는지 확인하고 승인받는 것)받아야 한다.
- 스크린샷으로 실제 화면을 직접 확인하는 것을 기본으로 한다.
코드만 고치고 “됐겠지” 하고 넘어가지 않는다. 반드시 눈으로 확인한다. 이게 기준이다.

이 사례에서 배울 점: 코드만 고치지 말고 프로세스도 함께

이번 건 작은 버그였다. 이미지 하나가 삐져나간 것. 근데 거기서 멈추지 않은 게 핵심이다.

버그를 고치는 건 시작이다. 왜 생겼는지 파악하고, 같은 일이 반복되지 않도록 구조를 바꾸고, 확인 단계까지 만드는 것이 진짜 마무리다.

AI 도구를 쓸 때 “고쳐줘”만 하고 끝내는 사람이 많다. 그러면 똑같은 질문을 다음 달에 또 하게 된다. “왜 또 이러지?” 하면서.

물어봐야 할 건 두 가지다.
- 지금 이걸 어떻게 고치냐.
- 앞으로 이게 안 생기려면 뭘 바꿔야 하냐.
두 번째 질문을 안 하면 첫 번째 질문을 계속 반복한다.

다음에는 업로드 스크립트 전체를 한 번 훑어볼 생각이다. 이미지 말고 다른 곳에서도 비슷한 게 조용히 지나가고 있을 수 있다. 결국 이미지가 삐져나가는 버그 하나가 전체 업로드 파이프라인을 점검하게 만든 셈이다.

비슷한 패턴은 다른 데서도 반복됐다. WPCode로 보안 헤더 추가하다 코드가 깨진 사례도 결국 같은 교훈이었다 — 자동화 도구를 만들 땐 “일단 되는 것”과 “제대로 확인된 것”은 다르다.
2026년 09월 09일
Claude Code로 UI 재설계하면서 배운 AI 협업 꿀팁과 함정
Claude Code 사용법을 실전에서 익혔다. Claude Code로 블로그 UI를 처음 손봤다. 홈 화면 재설계, 스크롤 목차, 로봇 로고 브랜딩까지 한꺼번에 작업했다. 결론부터 말하면, 빠르지 않았다. 하지만 혼자 했으면 못 끝냈을 작업을 끝냈다.

Claude Code 사용법, UI를 직접 만들어보니 어땠나?

Claude Code는 AI(인공지능) 기반 코딩 도구다. 터미널(terminal, 텍스트로 컴퓨터에 명령을 내리는 창)에서 명령어를 치면, AI가 코드를 직접 읽고 수정하고 실행까지 해준다. 에디터(editor, 코드를 작성하는 프로그램)를 오가며 복사 붙여넣기 할 필요가 없다.

이번에 작업한 항목은 세 가지였다. 홈 화면 레이아웃(layout, 화면 구성 방식) 재설계, 글 목록을 따라다니는 스크롤 목차, 그리고 블로그 로고 교체. 규모가 작지 않았다.

재설계를 마친 지금 홈 화면이다. 글 목록이 카드 그리드로 정리됐다.

처음엔 속도가 붙는 느낌이었다. “홈 화면 카드 간격 늘려줘”, “목차 위치 고정해줘” 같은 말만 해도 AI가 코드를 찾아서 고쳐줬다. 근데 작업이 길어질수록 문제가 생기기 시작했다.

텍스트 안 보임, 위치 계산 오류… 실제로 마주친 버그들

제일 시간을 잡아먹은 버그는 두 가지였다. 텍스트가 안 보이는 문제, 그리고 요소(element, 화면을 구성하는 개별 블록) 위치 계산 오류.

텍스트가 안 보이는 건 CSS(Cascading Style Sheets, 화면의 색상·크기·위치를 정하는 코드) 문제였다. 배경색이랑 글자색이 같아져버리는 식이다. 눈에 안 보이니까 버그인지도 한참 몰랐다. 위치 계산 오류는 더 번거로웠다. 스크롤 목차가 엉뚱한 곳에 붙거나, 화면 밖으로 튀어나갔다.

새로 만든 헤더다. 로봇 로고와 카테고리 메뉴가 나란히 붙었다.

이런 버그들은 Claude Code한테 증상을 설명하면 고쳐줬다. 완전히 못 고친 건 아니다. 다만 시간이 걸렸다. “텍스트가 안 보여”라고 말하면 원인을 찾고, 수정하고, 다시 확인하는 과정을 반복해야 했다. 빠른 척하지만 한 번에 되는 경우는 드물었다.

모르는 버그가 더 있을 수 있다는 것도 문제다. 눈에 보이는 버그는 고칠 수 있다. 눈에 안 보이는 버그는 존재 자체를 모른다.

AI가 기억을 못 하는 문제, 어떻게 대처했나?

이게 진짜 스트레스였다.

Claude Code는 대화 맥락(context, AI가 기억할 수 있는 대화의 범위)이 길어지면 앞에서 한 말을 잊는다. 정확히는 잊는다기보다 우선순위가 밀린다. 내가 “이 스타일은 건드리지 마”라고 했어도, 나중에 다른 수정을 요청하면 그 스타일을 다시 바꿔놓는 경우가 생겼다.

더 황당한 경우도 있었다. 내가 특정 레퍼런스(reference, 참고할 예시)를 요청했는데, AI가 그걸 무시하고 자기가 찾은 걸 벤치마킹(benchmarking, 다른 사례를 참고해 기준을 잡는 것)해버렸다. 내 요구사항이 아니라 AI가 판단한 방향으로 가버린 거다. 이건 버그인지 특성인지도 모르겠다.

글을 스크롤하면 옆에 목차가 따라다니고, 지금 읽고 있는 항목이 강조 표시된다.

그래서 이렇게 대처했다.
- 작업 단위를 작게 쪼개야 한다. 한 번에 많은 걸 요청하면 맥락이 흔들린다.
- 중요한 조건은 매 요청마다 반복해서 명시해야 한다. 한 번 말했다고 AI가 기억한다고 믿지 마라.
- AI가 자의적으로 바꾼 부분이 없는지 결과물을 꼭 직접 확인해야 한다. 확인 없이 넘어가면 나중에 더 꼬인다.
- 레퍼런스를 요청할 때는 URL(인터넷 주소)이나 구체적인 예시를 함께 줘야 한다. 막연하게 “이런 느낌으로”는 AI 마음대로 해석된다.
궁극적으로는 버그를 스스로 찾아서 고치는 AI를 원하는데, 지금 Claude Code는 거기까지는 못 간다. 내가 발견한 것만 고친다. 이 한계는 명확히 알고 써야 한다.

로봇 로고를 선택한 이유: AI 시대를 표현하다

로고를 바꿨다. 이전 로고 얘기는 길게 안 한다. 중요한 건 왜 로봇으로 바꿨냐는 거다.

지금이 AI 시대다. 이 블로그도 AI 도구를 활용하는 내용을 다룬다. 그걸 가장 직관적으로 보여주는 이미지가 로봇이라고 판단했다. 복잡한 이유는 없다.

최종적으로 정한 로봇 로고 아트웍이다.

스타일 방향은 Claude Code가 몇 가지 후보를 제안했고, 그중에서 로봇 아이콘을 직접 골랐다. AI 시대를 표현하는 데 제일 직관적인 이미지라고 판단했다. 지금 보니 잘 고른 것 같다.

로고 작업 자체는 다른 버그들에 비해 순탄했다. 방향이 명확하면 AI도 잘 따라온다. 방향이 흐릿할 때 문제가 생긴다.

완성 후 느낀 점: 완벽함보다는 계속된 개선이 정답

버그 때문에 시간은 오래 걸렸다. 하지만 완성은 했다.

완성된 걸 보고 “완벽하다”는 생각은 안 들었다. 완성인지 미완성인지도 솔직히 아직 모른다. 지금은 만족스럽다. 근데 계속 쓰다 보면 만족스럽지 못한 부분이 또 나올 거다. 그게 당연한 과정이다.

워드프레스에 등록된 로봇 파비콘이다. 브라우저 탭에 이렇게 뜬다.

지금은 계속 사용하면서 버그를 잡고 있다. 더 유용한 기능이나 플러그인(plugin, 기존 프로그램에 기능을 추가하는 확장 도구)이 있는지도 알아보는 중이다. Claude Code도 계속 쓰면서 어떻게 하면 더 잘 쓸 수 있는지 파악하고 있다.

AI 도구는 만능이 아니다. 기억을 못 하고, 자의적으로 판단하고, 눈에 안 보이는 버그는 그냥 둔다. 그걸 알고 쓰는 것과 모르고 쓰는 건 결과가 다르다. 다음 작업은 이번에 파악한 한계를 기준으로 접근할 생각이다.
2026년 09월 06일