[Claude]실무에서 자주 보는 TypeScript 코드 작성 기준 정리

프로젝트를 하다 보면 이런 요구사항을 자주 보게 됩니다.

• TypeScript strict 모드
• 에러 핸들링 필수
• 함수 30줄 이내
• 테스트 코드 포함
• import 순서 정렬

처음 보면 막연하지만, 사실은 코드 품질을 위한 기본 원칙들입니다.
하나씩 쉽게 정리해보겠습니다.

---

1. TypeScript strict 모드

tsconfig.json에서 다음 설정을 의미합니다.

 

{
"compilerOptions": {
"strict": true
}
}

 

strict 모드란?

TypeScript의 타입 검사를 가장 엄격하게 수행하는 옵션입니다.

예를 들어:

 

function greet(name) {
return "Hello " + name;
}

 

❌ strict 모드에서는 에러
→ name의 타입이 명시되지 않았기 때문

올바른 예:

 

function greet(name: string): string {
return "Hello " + name;
}

 

strict 모드를 사용하는 이유

• 런타임 에러 감소
• 타입 안정성 확보
• 협업 시 실수 방지
• 리팩토링 안정성 증가

👉 한마디로 안전한 코드 작성을 강제하는 옵션

---

2. 에러 핸들링 필수

예외 상황을 반드시 처리하라는 의미입니다.

예를 들어:

 

function parseJson(json: string) {
return JSON.parse(json);
}

 

❌ 문제점
잘못된 JSON이 들어오면 애플리케이션이 그대로 터집니다.

개선된 코드:

 

function parseJson(json: string): unknown {
try {
return JSON.parse(json);
} catch (error) {
console.error("JSON 파싱 실패:", error);
throw new Error("Invalid JSON format");
}
}

 

왜 중요한가?

• 서버 다운 방지
• 사용자 경험 보호
• 디버깅 용이

👉 “에러는 반드시 예측하고 다뤄야 한다”는 원칙입니다.

---

3. 함수는 30줄 이내

하나의 함수는 30줄을 넘기지 말라는 규칙입니다.

왜 제한할까?

• 가독성 향상
• 유지보수 용이
• 단일 책임 원칙(SRP) 준수

❌ 나쁜 예

• 로그인 + DB 조회 + 토큰 생성 + 로깅을 한 함수에서 처리

✅ 좋은 예

 

validateUser()
findUser()
generateToken()
logLogin()

 

👉 작은 함수 여러 개가 큰 함수 하나보다 훨씬 좋습니다.

---

4. 테스트 코드 포함

작성한 코드에는 반드시 테스트를 작성하라는 의미입니다.

예시 (Jest):

 

import { greet } from "./greet";

describe("greet", () => {
it("이름을 받아 인사말을 반환한다", () => {
expect(greet("Tom")).toBe("Hello Tom");
});
});

 

테스트 코드의 장점

• 버그 조기 발견
• 리팩토링 안정성 확보
• 자동 검증 가능 (CI/CD)
• 코드 품질 향상

👉 테스트 없는 코드는 “검증되지 않은 코드”입니다.

---

5. import 순서 정렬

import를 일정한 규칙에 따라 정렬하라는 의미입니다.

일반적인 정렬 방식:

 

// 1. Node 내장 모듈
import fs from "fs";

// 2. 외부 라이브러리
import express from "express";

// 3. 내부 모듈 (절대 경로)
import { logger } from "@/utils/logger";

// 4. 상대 경로
import { helper } from "./helper";

 

또는 알파벳 순으로 정렬하기도 합니다.

왜 필요할까?

• 코드 일관성 유지
• 충돌 감소
• 가독성 향상
• 자동 포맷팅 도구(ESLint, Prettier)와 연동 가능

---

결국 이 규칙들의 핵심은?

이 모든 조건은 한 가지를 위한 것입니다.

"읽기 쉽고, 안전하고, 유지보수 가능한 코드를 작성하라"

항목목적

strict 모드	타입 안정성
에러 핸들링	런타임 안정성
30줄 제한	가독성 & 책임 분리
테스트 코드	품질 보증
import 정렬	코드 일관성

 

---

Claude Code에 넣기 좋은 “규칙 프롬프트” 템플릿

아래를 Claude Code 시스템/지시문에 붙이면 잘 따라옵니다.

 

TypeScript 프로젝트 규칙:

1) tsconfig: "strict": true 기준으로 타입 안전하게 작성.
2) any 금지. 필요하면 unknown 사용 후 타입가드로 좁힐 것.
3) 에러 핸들링 필수: 외부 입력/외부 호출(API/DB/파일)은 실패 케이스 처리.
- throw는 Error만.
- 공통 AppError(code, message, status?) 패턴 사용.
4) 함수는 30줄 이내. 길어지면 검증/변환/비즈니스/IO 단계로 분리.
5) 모든 public 함수는 반환 타입 명시.
6) 테스트 코드 포함:
- happy path + error 케이스 + 경계값 최소 1개씩
- Given-When-Then 형태
7) import 정렬:
- built-in -> external -> internal(@/) -> relative
- 알파벳 정렬 유지
8) ESLint/Prettier 기준 위반 없게 작성. (불필요한 주석/중복 로그 금지)
9) 결과물:
- src 코드 + tests + 필요한 설정/스크립트 제안까지 포함해서 출력.

마무리

이런 기준은 단순한 형식 맞추기가 아닙니다.
팀 단위 개발에서 반드시 필요한 최소한의 안전장치입니다.

처음에는 번거롭게 느껴질 수 있지만,
결국 개발자를 편하게 만들어주는 규칙들입니다.

 

 

출처 - https://www.threads.com/@ma_ne_23/post/DVRJAaYj_YK?xmt=AQF05af-yMMi-XuIBb33ZhPtqHOXBTzXe2rXyW2aQiXSTuvqtCAr3FokU-M6Hl-6w5E5aGdH&slof=1