migrate-to-shoehorn

migrate-to-shoehorn 스킬 개요

migrate-to-shoehorn 스킬이 하는 일

migrate-to-shoehorn 스킬은 테스트 코드에서 깨지기 쉬운 as 캐스팅을 @total-typescript/shoehorn으로 바꿔, TypeScript와 씨름하지 않고도 부분적인 테스트 데이터를 만들 수 있게 도와줍니다. 크고 무거운 fixture를 다루거나, 중첩 필드 몇 개만 중요하거나, 테스트에서 as unknown as Type 패턴을 정리하고 싶을 때 특히 잘 맞습니다.

누가 사용하면 좋은가

TypeScript 테스트 스위트를 다루면서 보일러플레이트를 줄이고 더 안전하게 fixture를 구성하고 싶다면 이 migrate-to-shoehorn 스킬을 쓰면 됩니다. 특히 기존 테스트를 손보는 엔지니어, 새 통합형 테스트를 작성하는 사람, 캐스팅이 많은 mock에 의존하던 코드베이스를 표준화하려는 경우에 유용합니다.

왜 유용한가

핵심 가치는 단순한 문법 치환이 아닙니다. 테스트 셋업의 마찰을 줄이면서도 타입 의도를 눈에 보이게 유지한다는 데 있습니다. 이 스킬은 불완전한 객체에는 fromPartial()을, 테스트가 의도적으로 타입 형태를 깨는 경우에는 fromAny()를 사용하도록 유도해, 그 트레이드오프가 캐스팅 안에 숨지 않고 명확하게 드러나게 합니다.

migrate-to-shoehorn 스킬 사용 방법

migrate-to-shoehorn 스킬 설치하기

다음 명령으로 설치합니다:

npx skills add mattpocock/skills --skill migrate-to-shoehorn

설치한 뒤에는 먼저 SKILL.md를 읽고, 환경에 링크된 저장소 파일이 있다면 함께 확인하세요. 이 repo에서는 스킬 내용이 한 파일에 집중되어 있으므로, 실무적인 안내가 구현 예제와 가깝게 배치되어 있습니다.

대충의 목표를 좋은 프롬프트로 바꾸기

migrate-to-shoehorn를 가장 잘 활용하려면 막연한 요청보다 구체적인 테스트 스니펫에서 시작하는 편이 좋습니다. 예를 들면 “이 테스트를 as Request에서 fromPartial()로 바꾸되 기존 assertion 동작은 유지해줘” 또는 “as unknown as로 만든 fixture를, 테스트가 의도적으로 잘못된 데이터를 넣는 부분은 fromAny()를 쓰도록 다시 써줘”처럼 요청하면 좋습니다.

스킬이 기대하는 입력

객체의 shape, 테스트 프레임워크 문맥, 그리고 제거하고 싶은 정확한 캐스트 패턴을 함께 주세요. fixture가 깊게 중첩되어 있다면 실제로 중요한 프로퍼티를 명시하는 것이 좋습니다. 이 스킬은 필요한 필드만 남기고 가짜 구조는 과감히 덜어낼 때 가장 효과적입니다.

실무 워크플로와 repo 읽는 순서

먼저 SKILL.md에서 마이그레이션 패턴을 확인하고, 그다음 테스트에서 현재 as Type 또는 as unknown as Type를 쓰는 위치를 찾으세요. migrate-to-shoehorn 안내를 적용할 때는 먼저 테스트가 유효한 부분 데이터가 필요한지, 아니면 의도적으로 잘못된 데이터가 필요한지 결정해야 합니다. 이 선택에 따라 fromPartial()과 fromAny() 중 어떤 대체가 맞는지가 정해집니다.

migrate-to-shoehorn 스킬 FAQ

migrate-to-shoehorn은 테스트에만 쓰는 건가요?

네. 이 스킬은 프로덕션 코드가 아니라 테스트 코드 전용으로 설계되었습니다. 런타임 검증이나 프로덕션에서 안전한 coercion이 필요하다면 migrate-to-shoehorn은 맞는 도구가 아닙니다.

fromPartial()과 fromAny()는 언제 써야 하나요?

객체가 완전하지는 않지만 목표 타입과 구조적으로는 맞아떨어질 때는 fromPartial()을 사용하세요. 테스트가 의도적으로 잘못되었거나 불가능한 값을 넣어야 해서 해당 시나리오에서 타입 체크를 우회해야 할 때는 fromAny()를 사용하면 됩니다.

migrate-to-shoehorn 스킬이 일반적인 프롬프트보다 나은가요?

대체로 그렇습니다. 넓은 조언이 아니라 집중된 마이그레이션 패턴을 주기 때문입니다. 일반적인 프롬프트는 “캐스트를 피하라”고 말할 수 있지만, migrate-to-shoehorn 스킬은 어떤 대체를 써야 하는지와 큰 fixture 객체를 어떻게 다뤄야 하는지까지 알려줘서 리라이트를 추측으로 하지 않게 해줍니다.

초보자도 쓰기 쉬운가요?

기본적인 TypeScript 테스트를 이미 이해하고 있다면 그렇습니다. 가장 큰 학습 곡선은 fixture가 “부분적이지만 유효한지”, 아니면 “의도적으로 안전하지 않은지”를 구분하는 일입니다. 이 판단이 어떤 helper를 쓸지 결정하기 때문입니다.

migrate-to-shoehorn 스킬 개선 방법

스킬에 실제 테스트 의도를 알려주기

가장 좋은 migrate-to-shoehorn 입력은 객체 리터럴만이 아니라 테스트가 무엇을 증명하는지도 함께 담고 있습니다. 예를 들어 “이 테스트는 body.id와 headers.authorization만 중요하다”라고 적으면, “이 fixture를 변환해줘”라고만 하는 것보다 훨씬 더 좋은 결과가 나옵니다. 스킬이 의미 있는 최소 shape로 객체를 줄일 수 있기 때문입니다.

흔한 두 가지 실패 모드 피하기

첫 번째 실패 모드는 fixture 잡음을 너무 많이 남기는 것입니다. 그러면 migrate-to-shoehorn을 쓰는 목적이 흐려집니다. 두 번째는 모든 곳에 fromAny()를 쓰는 것입니다. 이렇게 하면 타입 신호가 약해집니다. 테스트 의도에 가장 잘 맞는, 가능한 한 좁은 helper를 선택하세요.

첫 변환 후에는 한 번 더 다듬기

초기 migrate-to-shoehorn 적용이 끝나면, 테스트가 여전히 계약을 분명하게 전달하는지 확인하세요. 출력 결과에 불필요한 프로퍼티가 남아 있다면 지우고, unsafe 값이 꼭 필요했다면 fromAny() 선택이 의도적이며 시나리오 자체로 설명되는지 확인하세요.

repo별 제약에 맞게 프롬프트 조정하기

코드베이스에 테스트 규칙이 있다면 처음부터 알려주세요. 예를 들어 Jest 또는 Vitest, factory helper, 공용 request 객체, import에 대한 lint 규칙 등이 여기에 해당합니다. 이런 문맥이 있으면 migrate-to-shoehorn 스킬이 단순히 문법만 바꾸는 것이 아니라, repo에 맞는 변경을 만들어내는 데 도움이 됩니다.