code-fundamentals

Code Fundamentals — 변경하기 쉬운 코드의 4대 축

좋은 코드 = 변경하기 쉬운 코드. 토스 Frontend Fundamentals의 코드 품질 코어를 언어 불문 원칙으로 분리한 스킬이다. 예시 코드는 TS/React지만, 축 자체는 어떤 언어·계층(백엔드·CLI·앱)에도 그대로 적용된다.

축	질문
가독성	한 번에 고려해야 할 맥락이 적은가?
예측 가능성	이름·시그니처만으로 동작을 예측할 수 있는가?
응집도	같이 수정될 코드가 같이 묶여 있는가?
결합도	한 곳 수정 시 영향 범위가 좁고 예측 가능한가?

원칙들은 때로 충돌한다(예: 중복 제거 vs 결합도 낮추기). 이 스킬은 답을 강제하지 않고 트레이드오프를 드러내며, 맥락에 따라 선택을 돕는다.

⚠️ 로드 규율 — references/*.md는 on-demand로만 로드한다. 트리거 맵에서 패턴이 매칭됐을 때 1-2개씩만 연다. 본문 + 트리거 맵으로 충분한 리뷰가 대부분이다.

Lane 분할 (관점 1개당 컨텍스트 1개)

큰 diff 리뷰에서 한 컨텍스트가 모든 축을 평가하면 관점 오염이 생긴다. 두 lane으로 나누고, 각 lane은 자기 references만 본다 (병렬 디스패치 가능 환경에선 동시에).

Lane	관점	references
L1 readability+predictability	인지 부하·이름·시그니처·스코프 가시성	readability.md, predictability.md
L2 cohesion+coupling	모듈 경계·중복 vs 추상·디렉토리·결합	cohesion.md, coupling.md

Lane 간 통신 금지 — 각 lane은 같은 diff를 받되 자기 관점만 답한다.

빠른 트리거 맵 (코드 → 원칙 → 파일)

코드에 나타난 것	원칙	파일
중첩 삼항/조건, 4+ 줄 조건문	복잡한 조건 분해	readability.md #3, #5
의미 없는 숫자·문자열 상수	매직 넘버	readability.md #4 / cohesion.md #2
score >= 80 && score <= 100	부등호 순서 (min <= x && x <= max)	readability.md #8
한 단위에 배타적 역할(viewer/admin) 분기 혼합	배타 분기 분리	readability.md #1
한 함수/훅이 5개+ 상태·책임 관리	로직 종류별 분리	readability.md #6 / coupling.md #1
표준 라이브러리와 이름 겹치는 래퍼	이름 충돌	predictability.md #1
같은 종류 함수의 반환 타입 제각각	반환 타입 통일	predictability.md #2
시그니처에 없는 로깅·리다이렉트·IO	숨은 부작용	predictability.md #3
Boolean 이름이 상태인지 동작인지 모호	Boolean 네이밍	predictability.md #4
느슨한 비교(!= null, falsy 체크)	엄격 동등 비교	predictability.md #8
종류별 폴더(utils/·helpers/)로만 분리	도메인 중심 디렉토리	cohesion.md #1, #5
같은 의미 상수가 여러 곳 복제	상수 위치 = 범용성×지엽성	cohesion.md #4
환경 분기(typeof window 류) 산재	환경 분기 중앙화	cohesion.md #9
3+ 단 파라미터/props 전달	drilling	coupling.md #3
곳마다 달라지는 로직을 억지 공통화	과도한 DRY	coupling.md #2
core와 외부 환경(Router/Storage/SDK) 직결	어댑터 패턴 (얇은 인터페이스 + DI)	coupling.md #5
기존 API 유지하며 새 API 이전	/compat 어댑터	coupling.md #6

워크플로

A. 리뷰 모드 — ① 트리거 맵 스캔 ② 매칭된 reference만 로드 ③ 심각도 라벨([MUST] 명백한 결함 / [SHOULD] 권장 / [NIT] 취향) ④ 원칙 충돌 시 트레이드오프 명시.

B. 작성 모드 — 4축 질문으로 자가 점검; 트레이드오프 있는 선택(중복 허용, 공통화 회피)은 근거를 코드 곁에 남긴다.

C. 병렬 리뷰 (50줄+ diff) — L1·L2를 병렬 디스패치, 코디네이터가 같은 file:line dedup(강한 severity 우선) 후 severity→file→line 정렬.

체크리스트 (최소 스캔)

• [MUST] 매직 넘버/문자열 상수화 · 삼항 2중 중첩 금지 · 시그니처에 없는 부작용 금지 · 표준 라이브러리와 이름 충돌 금지
• [SHOULD] 범위 비교 부등호 순서 · 복잡식에 중간 변수명 · 배타 분기 비혼합 · 같은-수정-단위 파일 동거 · 상수 비복제 · drilling 3단 미만 · "곳마다 다른" 동작의 공통 훅 인자화 금지

출력 형식 (지적 1건 당)

### [MUST|SHOULD|NIT] [축] 원칙 이름
**문제** — 파일:라인 + 무엇이 어긋나는지
**Before / After** — 코드
**왜 나아지는가** — 2~3 bullet
**트레이드오프** (해당 시)

주의

• 교리가 아니다 — "가이드가 그렇게 해서"가 아니라 "이 코드베이스에 왜 더 맞는가"로 설득한다.
• 컨텍스트 우선 — 작은 스크립트에 도메인 폴더링을 밀어붙이면 과잉 적용이다.
• 자동화 가능한 건 자동화 — 린터/포매터/타입이 1차 방어선; 사람 리뷰는 그 위에.
• 프론트엔드 코드라면 toss-frontend-fundamentals를 함께 활성화한다 (a11y·React 런타임·디자인 토큰·플랫폼 철학은 그쪽 담당).