• /publish는 40줄짜리 셸 스크립트와 6단계의 수동 작업을 대체했습니다.

• /sync는 하나의 소스 파일로부터 3개의 플랫폼을 정렬된 상태로 유지합니다.

• /qa는 게시 전 깨진 링크와 단어 수 미달 오류를 잡아냅니다.

• 명령어 설계 교훈: 좁은 입력 범위, 단일 작업, 명확한 실패 알림

저는 1인 스튜디오를 운영하고 있습니다. 제 실수를 잡아줄 두 번째 사람이 없기에, 두 번째 사람이 되어줄 다섯 가지 Claude Code 슬래시 명령어 (slash commands)를 직접 만들었습니다. 이 명령어들은 약 200줄의 취약한 글루 코드 (glue code)와 기사당 약 30분 정도 소요되던 수동 점검 작업을 대체했습니다. 각 명령어가 무엇을 하는지, 무엇을 대체했는지, 그리고 실제로 사용되는 명령어를 설계하며 무엇을 배웠는지 소개합니다.

슬래시 명령어가 느슨한 스크립트보다 나은 이유

슬래시 명령어를 사용하기 전, 제 워크플로우는 실행 순서를 기억해야 하는 셸 스크립트 (shell scripts) 폴더로 이루어져 있었습니다. 하나를 실행하고, 출력을 복사해서, 다른 곳에 붙여넣으며, 단계를 건너뛰지 않았기를 기도해야 했습니다. 문제는 스크립트가 아니었습니다. 문제는 밤 11시에 4단계가 5단계보다 먼저 실행되어야 한다는 사실을 잊어버리는 저 자신이었습니다.

슬래시 명령어는 이러한 기억력 문제를 해결해 줍니다. 제가 /publish를 입력하면 Claude Code는 이미 실행 순서, 파일 경로, 그리고 점검 사항을 알고 있습니다. 명령어는 지침이 담긴 마크다운 (markdown) 파일일 뿐입니다. 이것이 핵심 비결입니다. 컴파일된 바이너리도, 프레임워크 (framework)도 없으며, 그저 Claude에게 무엇을 해야 할지, 어떤 도구를 사용할 수 있는지 알려주는 프롬프트 (prompt)가 있을 뿐입니다.

제가 처음으로 배운 것은 명령어가 단 하나의 작업만 수행해야 한다는 것입니다. 초기 시도는 빌드, 점검, 배포를 모두 수행하는 하나의 거대한 메가 명령어 (mega-command)였습니다. 하지만 한 부분이 고장 났을 때 어느 부분인지 알 수 없었기 때문에 끊임없이 실패했습니다. 이를 다섯 개의 좁은 범위의 명령어로 나누면서 디버깅 (debugging) 시간을 대략 절반으로 줄였습니다. 이제 각 명령어는 명확한 입력과 명확한 출력을 가집니다.

두 번째로 배운 점은 명령어가 실패할 때 확실하게 알려줘야 한다는 것입니다. 스크립트에서의 조용한 실패(silent failure)는 잘못된 게시물이 라이브로 올라가고, 제가 독자로부터 그 사실을 알게 된다는 것을 의미합니다. 그래서 제가 만든 모든 명령어는 통과(pass) 또는 실패(fail) 라인을 일반 텍스트로 출력하는 검증 단계(verification step)로 끝납니다. 만약 /qa가 깨진 링크를 발견하면, 제가 놓칠 수 없는 경고성 언어로 이를 알립니다. 모든 것이 실제로 통과되지 않는 한 초록색 체크표시는 나타나지 않습니다.

저는 이것들을 표준적인 Claude Code 프로젝트 설정 위에 구축했습니다. 아직 프로젝트 파일들을 구성하지 않았다면, 명령어보다 구조가 더 중요합니다. 저는 Claude Code Setup에서 이 명령어들이 읽어들이는 프로젝트 파일들을 다루는 전체 구성 과정을 설명했습니다. 먼저 그 기초를 제대로 잡으세요. 명령어는 그것이 기반하고 있는 컨텍스트(context)만큼만 유용할 뿐입니다.

세 번째 교훈은 입력 범위를 좁게 유지하는 것입니다. "무엇을 하고 싶나요?"라고 묻는 명령어는 쓸모가 없습니다. 하나의 파일 경로를 입력받아 그 파일에 대해 정확히 한 가지 일만 수행하는 명령어가 신뢰할 수 있습니다. 아래의 모든 명령어는 가능한 가장 작은 입력을 받습니다.

/publish 및 /sync: 일상의 일꾼들

/publish는 제가 가장 자주 실행하는 명령어입니다. 이 명령어는 초안 마크다운(markdown) 파일을 가져와 저의 Shopify 블로그로 전송합니다. 이전에는 인증 토큰(auth tokens), 이미지 업로드, API 호출을 처리하는 40줄짜리 셸 스크립트(shell script)였습니다. 잘 작동하다가도, 보통 토큰이 만료되거나 에러 메시지가 200줄의 curl 출력 속에 파묻혀 버리면 작동하지 않곤 했습니다.

이제 /publish는 초안을 읽고, 단어 수가 범위 내에 있는지 확인하며, 히어로 이미지(hero image)를 업로드하고 게시합니다. 완료되면 라이브 URL을 출력합니다. 만약 무엇이라도 실패하면, 즉시 중단하고 정확히 어느 단계에서 문제가 생겼는지 알려줍니다. 명령어 자체는 약 25줄의 지침으로 이루어져 있습니다. 실제 무거운 작업은 여전히 Shopify 관리자 API를 통해 이루어지지만, 저는 더 이상 가공되지 않은 요청(raw request)을 직접 만지지 않습니다. 저는 원하는 결과만을 설명하고, 명령어는 그 배관 작업(plumbing)을 처리합니다.

저를 놀라게 했던 점은 확인 단계(confirmation step)가 얼마나 중요한가 하는 것이었습니다. /publish는 맹목적으로 게시하지 않습니다. 제목, 태그, 단어 수를 보여준 뒤 기다립니다. 그 2초간의 일시 정지 덕분에 플레이스홀더(placeholder) 제목이 포함된 초안을 세 번이나 게시할 뻔한 상황을 면했습니다. 일시 정지의 비용은 아무것도 아닙니다. 하지만 플레이스홀더가 그대로 게시되었을 때의 비용은 당혹스러운 수정 이력(edit history)입니다.

/sync는 두 번째 핵심 도구(workhorse)입니다. 저는 한 번 작성하면 동일한 콘텐츠가 세 곳, 즉 블로그, 소셜 스케줄, 그리고 이메일 대기열(email queue)에 나타나야 합니다. 이전에는 일일이 복사하여 붙여넣고 수동으로 형식을 맞추었는데, 이는 시간이 지남에 따라 세 버전이 서로 어긋나게(drift) 만든다는 것을 의미했습니다. 블로그에서 수정한 오타가 소셜 버전에는 여전히 틀린 상태로 남아있곤 했습니다.

이제 /sync는 하나의 소스 파일(source file)을 읽어 세 가지 형식을 생성합니다. 블로그 버전은 전체 길이를 유지합니다. 소셜 버전은 플랫폼 제한에 맞춰 내용을 자르고 링크를 포함합니다. 이메일 버전은 제목과 미리보기 스니펫(preview snippet)을 생성합니다. 저는 Buffer를 통해 소셜 스케줄을 내보내는데, 이를 통해 한 번의 실행으로 일주일 치 게시물을 정렬할 수 있습니다. 단 하나의 진실된 원천(source of truth)만이 존재하기 때문에 어긋남(drift) 문제는 사라졌습니다.

/sync를 통해 얻은 설계 교훈은 출력 형식 지정(output formatting)에 관한 것이었습니다. 각 플랫폼은 서로 다른 규칙을 가지고 있으므로, 저는 명령어가 추측하게 두는 대신 명시적인 형식 블록(format blocks)을 제공했습니다. 추측하게 했을 때는 제한 글자 수를 15자 초과하여 단어 중간에 잘려버리는 게시물이 생성되었습니다. 명시적인 규칙을 적용하자 매번 완벽하게 들어맞는 게시물이 생성되었습니다.

/qa: 저의 실수를 잡아내는 명령어

/qa는 품질 면에서 가장 큰 차이를 만들어낸 명령어입니다. 이 명령어는 /publish를 실행하기 전에 작동하며, 제가 계속해서 어기는 모든 규칙에 대해 초안을 검사합니다. 단어 수가 범위 내에 있는지, 깨진 내부 링크는 없는지, 금지된 단어는 없는지 확인합니다. 최소 3개의 외부 링크가 있는지, 통화 형식이 올바른지, 헤딩 구조(heading structure)가 온전한지 등을 체크합니다.

제가 이 명령어를 만든 이유는 제 스타일 규칙을 어긴 기사들을 계속해서 발행했기 때문입니다. '나(I)' 대신 '우리(we)'라고 쓰거나, 습관적으로 엠 대시(em dash)를 빠뜨리거나, 아직 존재하지 않는 페이지로 링크를 거는 등의 실수를 저질렀습니다. 각각의 실수는 작았습니다. 하지만 그것들이 모여 블로그를 지저분하게 만들었고, 지저분한 블로그는 아무도 신뢰하지 않습니다.

이 명령어는 산문(prose)을 위한 린터(linter)처럼 작동합니다. 파일을 읽고, 각 체크 항목을 실행한 뒤, 통과(pass)와 실패(fail) 라인이 담긴 표를 출력합니다. 체크에 실패하면 발행이 차단됩니다. 제가 처음 일주일 동안 이 명령어를 실행했을 때, 4개의 기사에서 11개의 문제를 잡아냈습니다. 저는 분명 깨끗하다고 확신했을 내용들이었습니다. 한 기사에서는 동일한 핸들(handle)에 대해 서로 다른 앵커 텍스트(anchor text)로 연결된 두 개의 링크가 발견되었는데, 이는 눈으로는 절대 찾아낼 수 없었을 것입니다.

/qa를 구축하면서 가장 어려웠던 부분은 무엇을 '강제 실패(hard fail)'로 간주하고 무엇을 '경고(warning)'로 둘지 결정하는 것이었습니다. 초기에는 모든 것을 강제 실패로 설정했는데, 명령어가 너무 엄격해서 아무것도 발행할 수 없었습니다. 수동태 문장 하나만 있어도 기사 전체가 차단되었습니다. 그것은 품질 관리(quality control)가 아니라 인질극이었습니다. 저는 대부분의 스타일 문제를 경고로 옮기고, 깨진 링크, 범위를 벗어난 단어 수, 금지된 용어, 누락된 내부 링크와 같은 진짜 문제들만 차단 항목으로 남겨두었습니다.

이 구분이야말로 핵심적인 교훈입니다. 모든 것을 차단하는 QA 도구는 하루 만에 비활성화됩니다. 진정으로 해로운 것들은 차단하고 나머지는 단순히 표시(flag)만 해주는 QA 도구는 영원히 사용됩니다. 저는 경고를 확인하고, 중요한 것을 수정하여 발행합니다. 강제 실패는 협상의 여지가 없습니다. 경고는 조언입니다. 무엇이 무엇인지 아는 것이 설계의 전부입니다.

시각적인 측면을 위해, /qa가 파일을 체크하기 전에 Magnific을 통해 히어로 이미지(hero images)를 처리하므로, 이미지 링크는 이미 활성화되어 있어 첫 실행에서 체크를 통과합니다. 단계의 순서를 올바르게 정하는 것은 반복 작업(loops)을 줄여준다는 것을 의미합니다.

/seo 및 /audit: 서서히 효과를 내는 도구들

/seo와 /audit은 제가 실행 빈도는 낮지만 시간이 지날수록 가장 가치 있다고 느끼는 두 가지 명령어입니다. /seo는 완성된 초안을 가져와 검색 의도 (search intent)와 대조하여 확인합니다. 제목이 주제와 일치하는지, 주요 키워드가 처음 100단어 이내에 있는지, 헤딩 (headings)이 재치 있는 표현 대신 설명적인 표현을 사용하고 있는지 확인합니다. 또한 독자가 던질 법한 명백한 질문에 대해 글 상단에 명확한 답변이 있는지 체크합니다.

이 명령어는 키워드 스터핑 (keyword stuffing)을 하지 않습니다. 저는 키워드 스터핑이 로봇이 쓴 것처럼 느껴지게 만들어 독자들이 떠나게 만든다는 것을 초기에 배웠습니다. 대신 /seo는 기사가 제목이 약속한 질문에 실제로 답변하고 있는지를 확인합니다. 만약 제목에는 "5가지 명령어"라고 되어 있는데 기사에서 네 가지만 다룬다면, 이를 표시해 줍니다. 그런 종류의 불일치가 사람들이 페이지를 이탈하게 (bounce) 만드는 원인이 되며, 자신의 초안에 너무 몰입해 있을 때는 이러한 문제를 발견하기 어렵습니다.

/seo를 통해 얻은 교훈은 훌륭한 검색 엔진 최적화 (SEO)와 훌륭한 글쓰기는 본질적으로 같은 것이라는 점입니다. 명확한 헤딩은 독자와 검색 엔진 모두에게 도움이 됩니다. 상단에 배치된 직접적인 답변 역시 양쪽 모두에게 유용합니다. 저는 SEO를 별개의 작업으로 취급하는 것을 멈추고, 최종 가독성 검토 (readability pass) 단계로 취급하기 시작했습니다. 이 명령어는 제가 피곤할 때 이 단계를 건너뛰는 대신, 실제로 검토를 수행하도록 강제합니다.

/audit은 서서히 효과를 나타내는 도구입니다. 일주일에 한 번, 이 명령어는 제가 발행한 기사들을 크롤링 (crawling)하여 블로그 전체를 하나의 시스템으로서 보고합니다. 어떤 기사에 내부 링크 (internal links)가 연결되어 있지 않은지, 어떤 클러스터 (clusters)가 빈약한지, 어떤 오래된 포스트가 변경된 핸들 (handles)로 링크를 걸고 있는지 등을 파악합니다. 고립된 페이지 (orphan-page) 문제를 가장 잘 잡아냅니다. 지난달에 저는 인바운드 링크 (inbound links)가 전혀 없는 기사가 6개나 있었는데, 이는 독자들이 해당 기사에 직접 도달할 수는 있어도 브라우징을 통해서는 절대 찾을 수 없음을 의미합니다. /audit은 이 6개 모두를 나열해 주었습니다. 저는 링크를 추가했고, 그제야 클러스터가 결합되기 시작했습니다.

/audit을 구축하면서 저는 가장 유용한 명령어는 단일 파일이 아니라 시스템 전체를 대상으로 작동한다는 것을 배웠습니다. /publish와 /qa는 기사 하나에 집중합니다. 반면 /audit은 기사들이 서로 어떻게 연관되어 있는지를 살핍니다. 이러한 두 번째 관점이 구조적인 문제 (structural problems)를 잡아내며, 구조적인 문제야말로 조용히 가장 많은 독자를 잃게 만드는 원인이 됩니다.

이 명령어들이 실제 작업 스튜디오에서 어떻게 맞물려 돌아가는지 전체적인 그림을 보고 싶다면, Claude Blueprint에서 프로젝트 파일부터 발행에 이르기까지 전체 시스템을 처음부터 끝까지 설명하고 있습니다. 여기서 소개하는 다섯 가지 명령어는 해당 블루프린트(blueprint) 위에 놓인 운영 계층 (operational layer)입니다.

핵심 요약 (Bottom Line)

각각 하나의 좁은 작업만을 수행하는 다섯 가지 명령어가 약 200줄의 글루 코드 (glue code)와 기사당 약 30분의 수동 확인 작업을 대체했습니다. 이것이 수치상의 핵심이지만, 진정한 승리는 일관성 (consistency)에 있습니다. 이제 저는 단계를 잊어버리지 않습니다. 명령어가 저 대신 그 단계들을 기억해주기 때문입니다.

이 설계 원칙 (design principles)은 여러분이 만드는 어떤 도구에도 적용될 수 있습니다. 명령어당 하나의 작업. 좁은 입력값 (narrow inputs). 명확한 실패 알림 (loud failures). 차단하는 것과 단순히 경고하는 것 사이의 명확한 구분. 파일 수준의 관점과 병행되는 시스템 수준의 관점. 이 중 어느 것도 영리한 기교가 아닙니다. 그저 1인 운영 체제가 스스로 만든 프로세스에 빠져 허우적거리지 않게 해주는 규칙들일 뿐입니다.

이미 Claude Code를 사용하고 있다면, 다섯 개가 아니라 한 개의 명령어부터 시작하세요. 가장 짜증 나는 반복 작업을 해결해 주는 명령어를 먼저 만들고, 일주일 동안 사용해 본 뒤 다음 명령어를 만드세요. 복리 효과는 명령어 세트에서 오지만, 습관은 첫 번째 명령어가 안정적으로 작동하는 데서 옵니다. 기본 설정을 제대로 잡고, 좁게 구축하며, 실패 시 명확히 알리고, 기억하는 일은 명령어에게 맡기세요.

이 기사에는 제휴 링크가 포함되어 있습니다. 이 링크를 통해 가입하시면, 귀하에게 추가 비용 부담 없이 저에게 소정의 수수료가 지급될 수 있습니다. (광고)