어떤 어시스턴트에게든 "nombre 컬럼을 nombre_completo로 이름을 변경해 줘"라고 요청하면, 가장 가능성이 높은 것은 ALTER TABLE ... RENAME COLUMN 구문을 생성하는 것입니다. 이는 사용자의 로컬 환경에서는 작동합니다. 하지만 실제 운영(Production) 환경에서 배포되는 코드는 여전히 nombre을 찾으려고 시도하며, 배포가 완료될 때까지 오류를 일으킵니다.
이 튜토리얼에서는 Claude Code의 **스킬(skill)**을 생성하여 기본적으로 안전한 마이그레이션을 수행하도록 학습시키는 방법을 다룹니다.
스킬이란 무엇인가요 (Qué es una skill)
스킬은 프로젝트 내 .claude/skills/ 또는 모든 프로젝트에 적용되는 ~/.claude/skills/ 경로 안에 있는 SKILL.md 파일을 포함하는 폴더입니다. 이 파일은 YAML 프론트매터(frontmatter)로 시작합니다:
---
name: migraciones-bd
description: "운영 환경을 위한 안전한 데이터베이스 마이그레이션을 생성하고 검토합니다 (긴 블록킹 없음, 데이터 손실 없음, 되돌릴 수 있음, 배포된 코드와 호환됨). 사용자가 마이그레이션 생성, 스키마 변경, 컬럼 이름 변경 또는 삭제, 인덱스 추가 또는 기존 마이그레이션 검토를 요청할 때 사용하세요."
...
여기서 description 부분이 가장 중요합니다. Claude Code는 이 설명을 사용하여 언제 스킬을 로드해야 할지 결정합니다. 실제로 사용하는 구문("이 컬럼 이름을 변경해 줘", "인덱스를 추가해 줘")으로 작성해야 합니다. 프론트매터 아래에는 마크다운(Markdown) 형식의 메서드를 작성합니다.
메서드: 확장 및 축소 (El método: expandir y contraer)
핵심 아이디어는 배포 과정 중 현재 버전의 코드와 새로운 버전의 코드가 공존하므로, 스키마가 두 버전에 모두 서비스할 수 있어야 한다는 것입니다. 이 스킬에서는 이를 Claude가 참조할 수 있는 표 형태로 표현합니다:
| 작업 | 안전한 방법 |
|---|---|
| 컬럼 추가 | Nullable 또는 상수 기본값 설정. 이후 배치로 채우기. 필요하면 `NOT NULL` 적용 |
...
이렇게 하면, "컬럼 이름을 변경해 줘"라는 요청이 들어왔을 때 Claude는 단계별 변화와 배포 순서를 제안하게 됩니다.
생각하도록 강제하는 체크리스트 (Una checklist que obliga a pensar)
'마이그레이션에 주의하세요' 같은 모호한 지침은 아무것도 바꾸지 못합니다. 구체적인 질문들이 실제로 변화를 만듭니다:
ORM이 생성할 실제 SQL도 요청하세요 (alembic upgrade --sql, python manage.py sqlmigrate): 많은 문제가 오직 그곳에서만 보입니다.
명시적 제한 사항 (Límites explícitos)
스킬은 절대로 당신의 허가 없이 다음을 수행해서는 안 됩니다: 로컬 외부에서의 마이그레이션 실행, migrate:fresh, db:reset, prisma migrate reset 또는 모든 DROP. 스킬은 Claude에게 방향을 제시할 뿐 기술적인 장벽은 아닙니다. 만약 정말로 명령어를 차단하고 싶다면, .claude/settings.json에서 deny 규칙과 결합하세요.
사용해보기 (Pruébala)
- 파일을
.claude/skills/migraciones-bd/SKILL.md에 저장합니다.
- Claude Code의 새 세션을 엽니다.
- 다음을 요청합니다: "사용자(usuarios) 테이블의
nombre 필드를 nombre_completo로 이름 변경해야 합니다."
스킬이 활성화되었다면, 직접적인 RENAME 대신 단계별 계획, 첫 번째 단계 마이그레이션, 생성된 SQL 및 배포 순서를 볼 수 있습니다.
도움이 되었나요? 이 예시는 **Claude Code를 위한 고급 DB 스킬 팩 (스페인어)**의 일부입니다: 원하시는 금액을 지불하세요(최소 1 USD). 더 많은 무료 자료는 GitHub에서 확인하세요.