TypeScript

에이전트 협업 팀을 위한 TypeScript 코딩 컨벤션입니다. 역할에 맞는 이름과 직접 가져오기, 기존 타입 계약의 재사용, 외부 입력 검증, 절제된 보조 함수 추출을 다룹니다. 배열 정렬과 반복 조회의 동작을 보존하고 날짜 단위와 타임존, 선택 값과 기본값, JSDoc의 경계를 정합니다. React와 CSS 같은 위 계층 스킬이 함께 따르는 공통 규칙입니다.

규칙

1. 타입과 계약

함수 시그니처와 커스텀 타입에 계약을 명시하고, 기존 콜백과 타입을 재사용합니다. 독립된 객체 계약은 interface, 타입 계산과 조합은 type으로 선언합니다. as const 객체로 값과 타입을 함께 정의하고, 타입 단언 대신 unknown의 범위를 좁힙니다. 섹션 페이지

규칙	요지
1.1 새 타입을 선언하기 전에 이미 있는 타입과 스키마를 먼저 씁니다	뜻이 그대로면 기존 타입이나 스키마를 그대로 참조해 같은 형태를 두 번 선언하지 않습니다
1.2 부분집합은 `Pick` 대신 인덱스 접근 `interface`로 파생합니다	고른 필드의 이름과 출처를 드러내고 선택 여부와 읽기 전용 속성을 보존합니다
1.3 매개변수마다 표기하지 않고 함수를 담는 변수에 타입을 붙입니다	호출 계약을 한곳에서 읽고 같은 시그니처를 반복 선언하지 않습니다
1.4 커스텀 타입과 선언형 형태를 문서화합니다	구현을 읽기 전에 도메인 전용 계약을 이해할 수 있습니다
1.5 쓰지 않는 매개변수도 밑줄을 붙여 남깁니다	계약에 있는 매개변수를 유지하면서 사용하지 않는 매개변수를 표시합니다
1.6 단언으로 넘기지 않고 `unknown`을 좁혀서 씁니다	컴파일을 통과시키려고 타입 검사를 끄는 자리가 남지 않습니다
1.7 `enum` 대신 `as const` 객체를 씁니다	객체로 실행 값을 선언하고 같은 값에서 타입을 추출합니다
1.8 독립 객체 계약은 `interface`, 타입 조합은 `type`으로 선언합니다	선언 형식만 보고도 필드 계약인지 타입 사이의 관계인지 구분할 수 있습니다

2. 이름과 모듈 경계

식별자와 경로, 가져오기, 공개 진입점, 상수 위치에 소유자와 출처를 드러냅니다. 타입 이름은 값의 역할과 수명을 나타내고, 소유자 경로에 있는 정보를 반복하지 않습니다. 여기서 소유자는 자기 폴더가 있는 모듈 하나입니다. 그 폴더 안 파일은 그 소유자만 씁니다. 섹션 페이지

규칙	요지
2.1 프로젝트 전반의 상수는 루트 `constant` 폴더에 주제별 파일로 둡니다	프로젝트 전반의 상수를 주제별로 모아 위치와 이름을 일관되게 유지합니다
2.2 소유자 전용 상수는 소유자 `_constant` 폴더에 둡니다	소유자 전용 상수를 함께 관리하고 파일 이름과 상수 이름에서 소유자 표현을 반복하지 않습니다
2.3 파일과 심볼은 역할에 맞는 표기를 씁니다	파일과 심볼의 표기가 역할을 드러내 읽는 사람이 종류를 바로 압니다
2.4 `index.ts` 배럴을 만들지 않고 필요한 파일에서 바로 가져옵니다	배럴이나 재노출 계층 없이 선언의 출처를 직접 확인할 수 있습니다
2.5 가져오기 경로는 `@/`로 씁니다	가져오기 경로를 통일하고 가져오는 파일의 위치로 접근 범위를 판단합니다
2.6 환경 값은 `config/env.ts`를 거쳐서 읽습니다	환경마다 달라지는 값이 쓰는 파일로 흩어지지 않고 한 파일에서 읽힙니다
2.7 타입 이름은 값의 역할과 수명으로 짓습니다	이름만 읽고 값이 무엇이며 어느 시점에 존재하는지 구분할 수 있습니다

3. 함수와 보조 함수 경계

함수 선언 형태와 시그니처를 일관되게 유지합니다. 보조 함수는 재사용되거나 함수 형태가 필수일 때, 또는 렌더 파일 밖으로 요청 조립을 옮길 때 이름을 붙입니다. 보조 함수는 결과가 드러나는 이름을 붙여 정해진 위치에 둡니다. 변수는 재계산을 막거나 판정을 설명할 때만 만듭니다. 파일 안 선언 순서를 정하고, 넓은 스코프에서 let 재할당과 push로 값을 누적하지 않습니다. 섹션 페이지

규칙	요지
3.1 함수는 `const` 화살표로 선언합니다	함수 선언과 본문 형식을 통일해 변경 범위를 줄이고 선언 순서를 확인하기 쉽게 합니다
3.2 시그니처가 복잡해지면 이름 붙인 객체 매개변수로 묶습니다	긴 시그니처를 읽기 쉽게 유지하고 인자 위치를 헷갈리지 않으면서 입력을 늘립니다
3.3 보조 함수는 재사용되거나 함수 형태가 필수일 때만 이름을 붙입니다	불필요한 함수 분리를 줄여 호출부에서 처리 흐름을 읽을 수 있습니다
3.4 보조 함수는 대표 함수 폴더의 `_` 파일 하나에 하나씩 둡니다	보조 함수를 개별 파일로 관리하고 폴더로 소유 관계를 드러냅니다
3.5 파일 안 선언은 위에서 아래로 읽히게 놓습니다	파일을 열면 내보낸 함수가 먼저 보이고 호출부에서 호출 대상으로 이어집니다
3.6 소유자를 지워도 남는 함수만 루트 `util`로 올립니다	소유자 전용 함수를 구분하고 호출부 수가 달라져도 배치 기준을 유지합니다
3.7 넓은 스코프에서 `let` 재할당과 `push`로 값을 쌓지 않습니다	분기로 공유 지역 변수를 바꾸지 않아 넓은 스코프의 값 조립이 선언형으로 남습니다
3.8 변수는 재계산을 막거나 복잡한 판정에 이름을 붙일 때만 만듭니다	사용 횟수보다 계산 비용과 판정의 복잡성을 기준으로 변수 선언 여부를 판단합니다
3.9 함수 이름은 결과나 효과가 드러나게 짓습니다	함수 이름으로 반환값이나 효과를 파악할 수 있습니다

4. 값과 자료구조

값을 다루는 관용구를 한 가지로 고정합니다. 넘겨받은 배열은 제자리에서 바꾸지 않고, 반복되는 조회는 Set과 Map으로 모읍니다. 객체의 값은 구조분해하지 않고 체인으로 읽어 출처를 남깁니다. 한 곳에서 쓸 값은 조회표로 우회하지 않고 사용처에서 직접 고릅니다. 뜻이 있는 숫자는 쓰는 자리에 적지 않고 상수로 선언합니다. 값 보조 함수는 직접 만들기 전에 es-toolkit에서 찾습니다. 날짜는 dayjs로 다룹니다. 같은 판정은 경계에서 한 번만 하고 결과를 데이터로 전달합니다. 섹션 페이지

규칙	요지
4.1 원본을 바꾸지 않고 배열을 정렬합니다	프롭스, 상태, 모듈 상수에서 온 배열을 정렬할 때 원본이 바뀌는 버그를 피합니다
4.2 같은 조회를 반복하면 `Set`이나 `Map`으로 정리합니다	반복 조회 구조를 한 번 만들어 목록 전체를 되풀이해 비교하는 비용을 줄입니다
4.3 객체는 구조분해하지 않고 체인으로 읽습니다	값이 어느 객체에서 왔는지가 쓰는 자리마다 남아 이름만 보고 출처를 되짚지 않습니다
4.4 의미 있는 숫자는 사용처에 적지 않고 상수로 선언합니다	숫자의 의미를 이름으로 드러내고 한곳에서 변경할 수 있습니다
4.5 한 곳에서 쓸 값을 조회표로 고르지 않습니다	값과 선택 조건이 사용처에 함께 남아 선택 기준을 바로 읽을 수 있습니다
4.6 값을 다루는 보조 함수는 `es-toolkit`을 먼저 사용합니다	중복 제거와 표기 변환을 파일마다 다르게 만들지 않고 검증된 구현 하나로 모읍니다
4.7 날짜는 `dayjs`로 다룹니다	날짜의 단위와 타임존을 드러내고 파싱과 표시 형식을 일관되게 유지합니다
4.8 판정은 한 번만 하고 결과를 데이터로 전달합니다	같은 판정을 반복하지 않고 사용처가 전달된 결과를 사용합니다

5. 없는 값 다루기

값이 없을 수 있는 상태를 다루는 규칙을 모읍니다. 값이 없다는 사실은 임의의 기본값으로 감추지 않고 사용처까지 전달합니다. 타입이 이미 보장하는 것은 다시 검사하지 않습니다. 값이 들어오는 경계에서 한 번 검사하고, 중간 함수는 검증된 타입을 사용합니다. 섹션 페이지

규칙	요지
[5.1 `??`, `
5.2 기본값은 값이 들어오는 경계에서 한 번만 채웁니다	기본값이 선언 한 곳에 남아 아래쪽 코드에서 `??`가 되풀이되지 않습니다
5.3 타입이 보장하는 것을 다시 검사하지 않습니다	불필요한 검사를 줄이고 값이 실제로 없을 수 있는 경우만 확인합니다
5.4 없을 수 있는 값은 경계에서 한 번만 검사합니다	값이 들어오는 경계에서 검사해 중간 함수의 중복 검사를 줄입니다

6. JSDoc과 주석 규약

함수 본문 주석에는 의도와 긴 절차의 단계를 적고 코드 내용을 반복하지 않습니다. 선언 위 문서 주석은 어디에 붙일지, 어떤 형식으로 쓸지, 태그를 붙일지를 규칙마다 따로 정합니다. 본문은 목적과 제약만 짧은 한국어 명사형으로 적고, 규칙이 허용한 예외에는 확인할 수 있는 이유를 남깁니다. 섹션 페이지

규칙	요지
6.1 본문 안 설명은 `//`로 적고 의도와 단계를 남깁니다	코드를 옮겨 적은 주석은 막고 읽는 데 필요한 설명은 남깁니다
6.2 경계가 되는 선언에는 JSDoc 헤더를 붙입니다	구현을 읽기 전에 중요한 경계를 찾고 설명할 수 있습니다
6.3 주석에는 목적과 제약만 짧은 한국어 명사형으로 적습니다	몇 해 뒤에 코드를 여는 사람도 주석을 한눈에 읽고 고칠 수 있습니다
6.4 JSDoc은 한 줄로 쓰지 않고 여러 줄 블록으로 씁니다	선언 위 주석 형태가 파일마다 같아 주석을 검색하고 훑어보기 쉬워집니다
6.5 컨벤션 예외에는 확인할 수 있는 이유를 적습니다	예외가 취향인지 근거가 있는지 코드에서 바로 드러납니다

7. 도구 설정

자동 검사할 항목은 biome으로 설정하고, 도구가 검사하지 못하는 항목은 리뷰에서 확인합니다. 섹션 페이지

규칙	요지
7.1 Biome 설정으로 자동 검사할 규칙을 명시합니다	자동 검사와 리뷰의 역할을 구분해 판단이 필요한 내용에 집중합니다

Navigation