Cursor와 Claude Code 설정을 12개의 재사용 가능한 파일로 변환하기

Ko-Fi: https://ko-fi.com/s/fdb0e60135

대부분의 Cursor 및 Claude Code 설정은 결국 똑같은 문제로 퇴보합니다. 모호한 시스템 프롬프트 (System Prompt)를 붙여넣고, 매 프로젝트마다 동일한 패턴을 AI에게 반복해서 가르쳐야 하며, 실제로 어디에도 영구적으로 인코딩된 것이 없기 때문에 출력 결과가 일관되지 않습니다.

저는 몇 주 동안 제가 효과를 보았던 패턴들 — 즉, 매번 처음부터 다시 설명해야 했던 것들 — 을 실제 파일로 만드는 데 시간을 보냈습니다. 적절한 형식으로 말이죠. Cursor와 Claude Code가 기대하는 형식입니다. 파일들을 넣어두기만 하면 바로 작동합니다.

제가 무엇을 만들었는지, 그리고 각 결과물(Artifact)을 제대로 만들기 위해 왜 실제적인 반복 작업(Iteration)이 필요했는지 설명하겠습니다.

코드 리뷰어 서브에이전트 (The Code Reviewer Subagent)

Claude Code는 서브에이전트 (Subagents)를 지원합니다. 이는 .claude/agents/ 디렉토리 내에 모델, 설명 (자동 위임(Auto-delegation)을 제어함), 그리고 시스템 프롬프트 (System Prompt)를 정의하는 YAML 프런트매터 (YAML frontmatter)가 포함된 .md 파일로 존재합니다. 여러분이 "내 코드를 리뷰해줘"라고 말하면, Claude Code는 모든 에이전트의 설명 필드를 읽고 적절한 에이전트에게 작업을 위임합니다.

code-reviewer 에이전트의 시스템 프롬프트는 출력을 네 가지 카테고리 — 정확성 버그 (Correctness bugs), 보안 문제 (OWASP 태그 포함), 데이터 손실 위험 (Data-loss risks), 성능 문제 (Performance problems) — 로 구조화하며, 심각도 테이블 (Severity table)과 머지 판결 (Merge verdict)을 요구합니다. 마지막 부분이 중요한데, 이것이 없으면 모든 리뷰가 모호하게 끝나고 결국 여러분이 직접 판단을 내려야 하기 때문입니다.

OWASP 태깅을 정확하게 만드는 데는 여러 번의 반복 작업이 필요했습니다. 모델은 문제가 명백한 인젝션 (Injection)이나 인증 우회 (Auth bypass)가 아닐 경우 이를 건너뛰곤 했습니다. 해결책은 시스템 프롬프트에 제약 조건을 거는 것이었습니다: 모든 보안 발견 사항은 반드시 OWASP Top 10 참조를 포함하거나, 이유와 함께 "매핑되지 않음 (not mapped)"이라고 명시적으로 기재해야 합니다. 이제 모델은 이를 일관되게 수행합니다.

나머지 세 개의 서브에이전트도 동일한 패턴을 따릅니다:

test-generator — 테스트 프레임워크(Vitest, Jest, pytest)를 감지하고, 기존 컨벤션(Conventions)을 읽어 실제 단언(Assertions)이 포함된 스텁이 없는(zero-stub) 테스트를 생성합니다. 가장 어려웠던 점은 플레이스홀더(Placeholder) 구조가 아닌 실행 가능한 테스트를 생성하도록 만드는 것이었습니다. 이제 시스템 프롬프트(System prompt)는 테스트 본문 내의 // TODO 및 pass 사용을 명시적으로 금지합니다.
dependency-auditor — 사용 가능한 경우 네이티브 감사 도구(npm audit, pip-audit)를 실행하며, 그렇지 않을 경우 명명된 CVE ID를 포함한 수동 분석으로 전환합니다. 실제 CVE를 명명하는 것이 반복적인 개선 과정이었습니다. 그렇지 않으면 모델이 우선순위 지정에 쓸모없는 모호한 "잠재적 취약점(potential vulnerability)" 메모를 생성하곤 했습니다.
migration-runner — 가장 많은 작업이 필요했던 에이전트입니다.

Migration Runner: 라이브 데이터베이스를 위한 안전한 SQL

프로덕션 데이터베이스에서 실행해도 안전한 SQL 마이그레이션(Migrations)을 작성하는 것은 한 번에 해결되는 문제가 아닙니다. 실패 사례를 보면, 테스트 데이터베이스에서는 잘 작동하지만 프로덕션의 5,000만 행이 있는 테이블에 기본 잠금(Primary lock)을 걸어버리는 마이그레이션이 발생하곤 합니다.

migration-runner 서브에이전트는 SQL을 생성하기 전에 작업별로 잠금 위험(Lock risks)을 분석합니다. 기본값이 포함된 ADD COLUMN NOT NULL은 이전 버전의 PostgreSQL에서 마이그레이션이 진행되는 동안 테이블을 차단합니다. 안전한 방식은 세 단계의 작업으로 구성됩니다: 컬럼을 Nullable로 추가하고, 배치(Batch) 단위로 데이터를 채운(Backfill) 다음, 제약 조건(Constraint)을 별도로 추가하는 것입니다.

시스템 프롬프트는 이를 구체적으로 인코딩(Encodes)하고 있습니다. 에이전트가 ADD COLUMN NOT NULL을 발견하면, 이를 자동으로 3단계 시퀀스로 재작성하고 그 이유를 설명합니다. 각 마이그레이션에는 작동하는 down 블록도 포함됩니다. 단순히 "이 작업을 수동으로 되돌리세요"라고 적힌 주석이 아니라, 실제 롤백(Rollback) 스크립트입니다.

이 재작성 로직을 완성하는 데 약 한 시간의 반복 작업이 필요했습니다. 배치 크기를 적절하게 설정하고, 제약 조건 이름을 일관되게 처리하며, 세 단계 각각에 대해 down 블록이 독립적으로 정확하게 작동하도록 만드는 과정이었습니다.

Exit 2를 통해 차단하는 Lint Hook

Claude Code hooks는 도구 라이프사이클 (lifecycle)의 특정 시점에 셸 스크립트 (shell scripts)를 실행합니다. PreToolUse 훅은 Edit, Write, 또는 MultiEdit 호출이 발생하기 전에 실행됩니다. 만약 훅이 종료 코드 (exit code) 2로 종료되면, Claude Code는 해당 편집을 차단합니다.

pre-commit-lint 훅은 정확히 이 역할을 수행합니다. 이 훅은 JS/TS 파일에 대해서는 ESLint를, Python 파일에 대해서는 Ruff를, 또는 Rust 파일에 대해서는 cargo clippy를 실행하고, 그 출력을 파싱하여 문제가 있을 경우 2로 종료합니다. Claude Code는 훅 출력에서 린트 (lint) 에러를 확인하고, 편집을 재시도하기 전에 이를 수정합니다.

직관적이지 않은 부분은, 훅이 편집을 차단하지 않으면서 린터 (linter)가 설치되어 있지 않은 경우를 처리해야 한다는 점입니다. 설치되지 않은 린터는 2로 종료하여 모든 것을 망가뜨리는 대신, 조용히 0으로 종료되어야 합니다. lint.sh 스크립트는 각 린터를 호출하기 전에 설치 여부를 확인하며, 부재 시 깔끔하게 건너뜁니다.

post-edit-test 훅은 이와 반대되는 역할을 합니다. 이 훅은 각 편집 후에 실행되며, 프로젝트에서 감지된 관련 테스트 (Vitest, Jest, 또는 pytest)를 실행하고 [test-hook] PASS / FAIL / SKIP을 출력합니다. 이 훅은 절대 2로 종료하지 않으며, 차단하지 않고 정보만 제공합니다.

훅을 연결하려면 JSON 스니펫 (snippet)을 .claude/settings.json에 병합해야 합니다. 이 팩 (pack)에는 셸 스크립트와 정확한 병합 결과가 문서화된 JSON 스니펫이 모두 포함되어 있습니다.

기술 (Skills): 지침이 아닌 프로토콜

기술 (Skills)은 Claude Code의 최신 프리미티브 (primitive)입니다. 이는 .claude/skills/ 폴더 내에 SKILL.md 파일을 포함하며, Claude Code는 기술의 설명을 바탕으로 자동 위임 (auto-delegate)할 때 이 파일을 읽습니다.

이 팩에 포함된 두 가지 기술은 지침 (instructions)이라기보다 프로토콜 (protocols)을 인코딩합니다:

long-running-tasks — 체크포인트 기반의 실행 프로토콜 (checkpoint-based execution protocol)입니다. 다단계 작업을 시작하기 전에 단계 목록과 현재 인덱스가 포함된 _state.json을 작성합니다. 각 단계가 완료되면 상태 파일을 업데이트합니다. 실패하거나 재시작할 경우, 상태 파일을 읽고 마지막으로 완료된 단계부터 재개합니다. 이 기술에는 state.template.json과 _progress.log 형식이 포함되어 있습니다. 이를 통해 Claude Code에서 크래시(crash)가 발생하더라도 진행 상황을 잃지 않고 수 시간 동안 지속되는 파이프라인 (pipeline)을 실행할 수 있습니다.
api-integration — 다음을 포함하는 프로덕션급 (production-grade) API 통합 프로토콜입니다: 환경 변수로부터의 자격 증명 조회 (절대 하드코딩하지 않음), 연결 타임아웃 (connection timeouts), 지터 (jitter)를 포함한 지수 백오프 (exponential backoff), Retry-After 헤더 처리, POST 요청 시의 멱등성 키 (idempotency keys), 서킷 브레이커 (circuit breaker) 상태, 그리고 웹훅 서명 검증 (webhook signature verification). 이 기술이 활성화된 상태에서 Claude Code가 작성하는 모든 통합 코드는 전체 프로토콜을 따릅니다.

이것이 무엇이며 무엇이 아닌가

이것들은 기능적인 파일들입니다. 이 파일들이 작동하는 이유는 Cursor와 Claude Code가 기대하는 형식 — 프론트매터 (frontmatter), 글로브 패턴 (glob patterns), 훅 라이프사이클 (hook lifecycle), 기술 디렉토리 구조 (skill directory structure) — 에 맞춰 제작되었기 때문입니다. 이 파일들을 넣는 것은 단순한 설정 단계가 아니라, 설치 (installation)입니다.

각 파일은 30~60분간의 실제 반복 작업 (iteration)을 나타냅니다: 첫 번째 버전을 작성하고, 실제 입력값으로 실행해 보고, 실패 모드 (failure modes)를 찾아내고, 수정 사항을 제약 조건 (constraints)으로 인코딩하는 과정입니다. 당신은 그 작업을 건너뛰는 것입니다.

이것은 프롬프트 팩 (prompt pack)이 아닙니다. 프롬프트는 대화 시작 시 모델에 전달하는 지침 (instructions)입니다. 이 파일들은 툴체인 (toolchain) 자체의 동작 방식을 수정합니다 — 즉, 어떤 요청에 어떤 에이전트 (agent)가 실행되는지, 어떤 규칙이 어떤 파일에 부착되는지, 편집 라이프사이클 (edit lifecycle)의 어느 시점에 어떤 훅 (hooks)이 실행되는지를 결정합니다.

이 팩은 12개의 파일로 구성됩니다: 4개의 서브에이전트 (subagents), 4개의 Cursor 규칙 (rules), 2개의 훅 스크립트 (hook scripts) + 2개의 JSON 스니펫 (snippets), 2개의 기술 폴더 (skill folders).

만약 당신이 Cursor 또는 Claude Code를 매일 사용하며, 매 프로젝트마다 처음부터 가르치지 않아도 설정이 시니어 엔지니어처럼 동작하기를 원한다면: https://ko-fi.com/s/fdb0e60135