TypeScript 빨간 줄이 여러 개라면 첫 오류 하나만 복사하세요

AI 코딩 도구가 화면을 거의 만들어 줬는데 TypeScript 빨간 줄이 여러 개 남으면 어디서부터 손댈지 막막해집니다. Type 'undefined' is not assignable, Parameter implicitly has an 'any' type, Property does not exist 같은 문장을 한꺼번에 보면 코드 전체가 틀린 것처럼 느껴집니다. 이때 바로 "다시 만들어 줘"라고 하면 멀쩡한 구조까지 바뀔 수 있습니다. 먼저 할 일은 오류를 모두 없애는 것이 아니라 첫 오류 한 줄을 같은 명령으로 다시 보는 것입니다.

Tap to zoom

typescriptlang.org의 공식 TSConfig 문서에 따르면 noEmit은 JavaScript·source map·declaration 같은 출력 파일을 만들지 않고 TypeScript를 타입 검사기로 쓸 수 있게 합니다. 따라서 수정부터 시작하지 말고, 같은 첫 오류를 다시 볼 확인 명령부터 확보해야 합니다.

첫 번째 빨간 줄과 위치부터 복사합니다

오류 목록이 길어도 처음 볼 것은 하나입니다. 터미널이나 에디터 Problems 패널에서 가장 위에 있는 TypeScript 오류를 찾습니다. 마지막 오류나 가장 긴 오류가 아니라, 첫 번째 오류입니다. 앞쪽 타입이 틀리면 뒤쪽 오류가 줄줄이 따라오는 경우가 많습니다.

먼저 아래 네 줄을 채웁니다.

첫 오류 문장:
파일 경로:
줄 번호:
오류 코드:

예시는 이렇습니다.

첫 오류 문장: Type 'string | undefined' is not assignable to type 'string'.
파일 경로: app/profile/page.tsx
줄 번호: 42
오류 코드: TS2322

이 네 줄이 없으면 AI도 "전체 코드를 다시 확인하겠습니다"처럼 넓게 움직이기 쉽습니다. 반대로 첫 오류와 파일 경로를 주면 수정 범위가 작아집니다. 지금 필요한 것은 타입 이론 전체가 아니라, 오류가 시작된 한 줄입니다.

프로젝트 typecheck로 같은 오류를 재현합니다

에디터 빨간 줄만 보고 고치면 저장 상태나 확장 프로그램 상태에 흔들릴 수 있습니다. 프로젝트에 typecheck 스크립트가 있으면 먼저 그것을 씁니다.

npm run typecheck

없다면 프로젝트 루트에서 TypeScript 검사를 직접 실행합니다.

npx tsc --noEmit

이 명령은 JavaScript 출력 파일을 만들지 않고 타입 오류를 확인합니다. TypeScript CLI 문서는 파일명을 직접 넘기면 tsconfig.json이 무시될 수 있다고 설명하므로 npx tsc app.ts --noEmit처럼 파일 하나를 붙이기보다 프로젝트 스크립트나 루트의 npx tsc --noEmit을 우선합니다. 여기서 같은 첫 오류가 나오면 에디터 표시만의 문제가 아니라 프로젝트 타입 검사 문제로 보고 고칩니다.

Tap to zoom

결과를 AI에게 줄 때는 전체 로그를 던지지 말고 처음 20줄만 묶습니다.

npm run typecheck 결과입니다.

첫 오류:
[첫 오류 문장]

오류 주변 20줄:
[터미널 로그]

요청:
전체 파일을 다시 만들지 말고,
이 첫 오류가 생긴 타입 불일치만 설명해 주세요.
수정 후보는 최대 2개만 제안해 주세요.

이 요청에서 중요한 문장은 전체 파일을 다시 만들지 말라는 부분입니다. AI가 넓게 고치기 시작하면 원래 문제보다 변경 범위가 커집니다. AI가 코드를 저장하기 전 확인하는 체크리스트처럼 변경 파일과 재실행 결과를 함께 남기면 관련 없는 수정이 섞였는지도 볼 수 있습니다.

undefined 오류는 값을 보장할지, 먼저 거를지 나눕니다

string | undefined를 string에 넣을 수 없다는 오류는 초보자가 자주 만나는 빨간 줄입니다. 이 말은 "값이 없을 수도 있는데, 반드시 문자열이 필요한 곳에 넣었다"는 뜻입니다. 여기서 바로 as string을 붙이면 빨간 줄은 사라질 수 있지만, 실제 실행 중 값이 없을 때 문제는 그대로 남습니다.

TypeScript Handbook의 Narrowing 문서는 TypeScript가 if 같은 흐름과 타입 가드를 보면서 타입을 좁힌다고 설명합니다. 그러므로 먼저 질문을 둘로 나눕니다.

1. 이 값은 여기 오기 전에 반드시 있어야 합니까?
2. 없을 수도 있다면 이 화면은 무엇을 보여 줘야 합니까?

예를 들어 사용자 이름이 없을 수도 있다면 이렇게 먼저 거릅니다.

if (!user.name) {
  return <p>이름을 불러오지 못했습니다.</p>;
}

return <h1>{user.name}</h1>;

반대로 폼 입력처럼 기본값을 둘 수 있다면 빈 문자열을 명확히 넣습니다.

const displayName = user.name ?? "";

AI에게는 이렇게 물어보는 편이 안전합니다.

이 오류는 undefined 가능성 때문입니다.
as string으로 강제로 통과시키지 말고,
1. 값이 없을 때 화면을 멈춰야 하는지
2. 기본값을 넣어도 되는지
둘 중 하나로 나눠서 최소 수정안을 제안해 주세요.

강제 타입 단언보다 값이 없는 경우를 먼저 정하는 것이 초보자에게 더 안전합니다.

any 오류는 타입을 새로 외우기보다 입력 모양을 적습니다

Parameter implicitly has an 'any' type은 함수 인자의 타입을 TypeScript가 알 수 없다는 뜻입니다. TypeScript의 noImplicitAny 문서는 타입을 추론할 수 없을 때 any로 떨어질 수 있고, 이 옵션이 켜져 있으면 오류를 낸다고 설명합니다. 이 오류는 TypeScript가 까다롭게 구는 것이 아니라 놓칠 수 있는 실수를 앞에서 잡아 주는 신호입니다.

예를 들어 이벤트 핸들러에서 이런 오류가 날 수 있습니다.

function handleChange(event) {
  setTitle(event.target.value);
}

초보자는 여기서 event: any를 붙이고 싶어집니다. 하지만 더 좋은 첫 질문은 "이 함수가 받는 값의 모양이 무엇인가"입니다. React 입력 이벤트라면 이렇게 좁힐 수 있습니다.

function handleChange(event: React.ChangeEvent<HTMLInputElement>) {
  setTitle(event.target.value);
}

API 응답이라면 먼저 필요한 필드만 적습니다.

type UserResponse = {
  id: string;
  name: string;
};

AI에게는 아래처럼 묻습니다.

Parameter implicitly has an 'any' type 오류가 납니다.
any를 붙이지 말고,
이 함수가 실제로 받는 값의 최소 타입을 만들어 주세요.
필요한 필드만 포함하고, 관련 없는 타입은 새로 만들지 마세요.

이 요청은 타입을 크게 설계하라는 말이 아닙니다. 지금 오류를 만든 입력값의 모양만 적으라는 말입니다.

as를 붙이기 전에는 실행 때 달라지는지 봅니다

TypeScript Handbook의 Everyday Types 문서는 타입 단언이 컴파일러에 의해 제거되고 런타임 동작에는 영향을 주지 않는다고 설명합니다. 즉 as SomeType은 TypeScript에게 "내가 맞다"고 말하는 장치이지, 실제 데이터를 바꾸는 장치가 아닙니다.

그래서 아래 코드는 빨간 줄을 줄일 수는 있어도 데이터가 실제로 없으면 화면 문제를 막지 못합니다.

const title = data.title as string;

as를 쓰기 전에 세 가지를 확인합니다.

1. 외부 API나 사용자 입력처럼 값이 바뀔 수 있는 데이터입니까?
2. 값이 없을 때 보여 줄 화면이나 중단 조건이 있습니까?
3. 타입 정의가 틀린 것인지, 실제 데이터가 불안정한 것인지 구분했습니까?

외부에서 들어오는 값이라면 먼저 방어 코드를 둡니다.

if (typeof data.title !== "string") {
  throw new Error("title 값이 문자열이 아닙니다.");
}

내부에서 직접 만든 상수나 DOM 요소처럼 상황을 이미 확인한 경우에만 타입 단언을 검토합니다. 초보자 기준에서는 as는 첫 번째 해결책이 아니라 마지막 확인 카드로 두는 편이 낫습니다.

AI에게는 타입 오류 재현 묶음을 줍니다

타입 오류를 줄이는 마지막 단계는 AI에게 다시 시키는 문장입니다. "빨간 줄 없애줘"라고 하면 AI는 넓게 바꿀 수 있습니다. 아래 묶음처럼 주면 수정 범위가 작아집니다.

Tap to zoom

TypeScript 오류를 고치고 싶습니다.

상황:
AI가 만든 React/Next.js 코드에서 타입 오류가 납니다.

확인 명령:
npm run typecheck 또는 npx tsc --noEmit

첫 오류:
[첫 오류 문장]

파일 경로와 줄:
[파일 경로:줄 번호]

관련 코드:
[오류 줄 주변 20줄]

요청:
1. 오류 원인을 undefined, any, 속성 없음, 타입 불일치 중 하나로 분류해 주세요.
2. 전체 파일을 다시 만들지 말고 최소 수정만 제안해 주세요.
3. as 타입 단언을 쓰는 경우에는 왜 안전한지 먼저 설명해 주세요.
4. 수정 뒤 다시 실행할 확인 명령을 알려 주세요.

수정안을 적용한 뒤에는 처음 사용한 npm run typecheck 또는 npx tsc --noEmit을 다시 실행합니다. 첫 오류가 사라졌는지, 새 오류가 더 앞에 생기지 않았는지 확인하고 다음 오류로 넘어갑니다. 실행 명령·첫 오류·관련 파일·환경을 한 묶음으로 남기는 방식은 AI에게 다시 질문할 오류 정보 묶음에서도 이어서 사용할 수 있습니다.

오늘 남길 결과물은 완벽한 타입 설계가 아닙니다. 첫 오류 줄, 파일 경로, 확인 명령, 원인 분류, 최소 수정 요청입니다. 이 묶음을 만든 뒤 같은 명령의 첫 오류가 바뀌었는지 확인하세요.

참고 출처

• Narrowing (TypeScript Handbook)
• noEmit (TypeScript TSConfig)
• noImplicitAny (TypeScript TSConfig)
• Everyday Types: Type Assertions (TypeScript Handbook)
• tsc CLI Options (TypeScript)

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.