규칙 문서가 꼬일 때

ALT

산을 배경으로 한 한글 글꼴

📝 한줄 요약

앱의 개발 규칙을 정한 문서(DEV.md)가 있었는데, 나중에 급하게 붙인 화면 두 곳이 정확히 그 규칙을 어겼습니다. 규칙은 문서에 남겨두는 것만으로는 지켜지지 않고, 새 화면을 만들 때마다 대조해야 한다는 걸 배웠습니다.

Before: 규칙이 문서에만 있음
After: 규칙을 코드에 반영하는 과정을 추가

👥 이런 분께 추천

• 팀이 정한 개발 규칙을 어떻게 지킬 건지 고민하는 개발자

• “문서를 써도 지켜지지 않는다”는 경험이 있는 분

• 규칙을 문서로 남기기만 해선 부족한 이유를 알고 싶은 분

• 급한 일정 속에서도 기존 규칙을 지키는 방법을 찾는 분

🙋 내 스펙 & 환경

진행 방법

1. 개발 규칙이 있었습니다

처음 설계할 때 DEV.md 파일에 개발 제약을 정했습니다. 총 20개의 규칙인데, 그 중 우리가 마주친 것은:

규칙 1번: 화면은 전부 영어

• 배포된 앱이 한국 고객을 위한 것이지만, 사이트는 영어 기반입니다

• 이유: 시연 때 글로벌하게 보이게 하기 위함

규칙 4번: 브라우저 기본 날짜/시간 입력을 쓰지 않기

• input type="date", input type="time" 사용 금지

• 이유: 이 입력들은 보는 사람의 브라우저 언어를 따라가서, 형식이 통일되지 않음

• 대신: 커스텀 DateField, TimeField 부품을 만들어 씀

규칙 20번: 모든 날짜 칸에 요일과 공휴일 배지를 붙이지 않기

• 날짜가 판단 재료가 되는 칸(미팅 날짜)에만 배지를 붙임

• 단순히 기록하는 칸(확인일)에는 배지를 안 붙임

• 이유: 정보 과부하를 피하고 칸의 목적을 명확히 하기 위함

이 규칙들은 파일에 이유까지 명시되어 있었습니다. 그런데 새 화면을 만들 때 정확히 이 두 규칙이 어겨졌습니다.

2. 첫 번째 위반: 로그인 화면이 한국어

배포 중에 보안상 이유로 로그인 문을 빠르게 붙여야 했습니다. (전체 앱을 누구나 볼 수 있으니 접근 제한이 필요했음)

그때 로그인 화면을 만들 때:

• 제목: “로그인” (영어가 아니라 한국어)

• 레이블: “아이디”, “비밀번호” (역시 한국어)

• 에러 메시지: “아이디 또는 비밀번호가 잘못됐습니다” (한국어)

규칙 1번을 어겼습니다. 게다가 배포된 사이트에서 고객이 제일 먼저 보는 화면이 이것이었습니다.

왜 이런 일이 났나:

• 급한 일정에 다른 화면보다 먼저 다시 만들어야 했음

• “로그인은 임시니까”라는 생각으로 규칙 확인을 건너뜀

코드로 보면:

// 로그인 페이지 (login/page.tsx)
<label className="block text-sm font-medium mb-1">아이디</label>
<label className="block text-sm font-medium mb-1">비밀번호</label>
{error && <div>{error}</div>}  // 에러도 한국어

3. 두 번째 위반: 수정 모달의 브라우저 기본 날짜

확인된 건의 확인일을 수정하는 모달을 만들 때도 같은 일이 일어났습니다.

확인일 칸이 이렇게 만들어졌습니다:

// RecordsList.tsx의 EditMeetingModal
<input
  id="confirmedDate"
  type="date"  // 규칙 4번 위반
  value={confirmedDate}
  onChange={(e) => setConfirmedDate(e.target.value)}
/>

규칙을 어긴 이유:

• 모달은 제이리님의 검수 과정에서 추가 요청으로 나온 것

• 확인일 수정은 “나중에 꼭 필요한 기능”이라 빠르게 구현

• “날짜 칸이니까 input type="date" 쓰면 되겠지” 라는 단순한 생각

문제점:

• 한국어 브라우저: “연도-월-일” 형식

• 영어 브라우저: “MM/DD/YYYY” 형식 또는 다른 형식

• 화면 전체가 영어인데 이 칸만 다르게 보임

4. 발견과 즉시 수정

검수 과정에서 이 두 위반이 발견됐습니다. 발견 당일 둘 다 고쳤습니다.

로그인 화면 수정:

// Before
<label>아이디</label>
<label>비밀번호</label>
setError('아이디 또는 비밀번호가 잘못됐습니다')

// After
<label>ID</label>
<label>Password</label>
setError('Incorrect ID or password.')

수정 모달의 날짜 칸 수정:

// Before
<input type="date" value={confirmedDate} />

// After
<DateField
  id="confirmedDate"
  value={confirmedDate}
  onChange={setConfirmedDate}
  showWeekday={false}  // 규칙 20번: 확인일엔 요일 배지 안 붙임
/>

DateField는 이미 신청 폼에서 쓰던 부품이라, 복붙하고 옵션만 바꾸면 됐습니다.

배운 점

💡 핵심 교훈

1. 규칙은 문서에 남겨두는 것만으로는 지켜지지 않습니다

DEV.md에 명확히 적혀 있었고, 이유까지 설명되어 있었습니다. 그런데 우리는:

• 로그인 화면을 빠르게 다시 만들었고

• 수정 모달을 급하게 붙였고

• 둘 다 규칙을 어겼습니다

규칙이 살아있으려면:

1. 문서에 남기기 (이미 함)

2. 코드 리뷰 때마다 확인하기 (못 함)

3. 새 화면을 만들 때마다 규칙을 다시 읽기 (핵심)

문서를 “참조”하는 것과 “확인”하는 것의 차이입니다.

2. 급할수록 기존 규칙을 어기기 쉽습니다

“로그인은 임시니까”, “이건 모달이니까” 같은 생각이 규칙 위반을 정당화하게 됩니다. 하지만:

• 임시도 배포되면 고객이 봅니다

• 모달도 화면의 일부입니다

• 예외는 없습니다

3. 부품의 재사용이 규칙 적용의 지름길입니다

DateField를 이미 만들어둔 덕분에, 로그인과 달리 수정 모달의 날짜 칸은 빠르게 고칠 수 있었습니다. 규칙을 따르는 부품이 있으면, 새 화면을 만들 때 그냥 그 부품을 쓰기만 하면 됩니다.

적용할 점

🎯 결과

📋 복붙 가능한 체크리스트

새 화면을 만들 때 이 순서대로 확인합니다:

□ 현재 DEV.md를 다시 읽었나? (기억에 의존하지 않음)
□ 텍스트가 전부 영어인가? (규칙 1)
□ 날짜/시간이 커스텀 부품인가? (규칙 4)
□ 날짜 배지가 필요한 칸에만 붙어있나? (규칙 20)
□ 다국어 환경에서 봤을 때 일관되는가?

🔜 다음 계획

1. 규칙 확인을 프로세스로 넣기

   • 새 화면 구현 완료 후 → 즉시 DEV.md 다시 읽기 → 체크리스트 확인

   • “다다음 단계”가 아니라 “다음 단계”로 넣기

2. 부품 목록 만들기

   • DateField, TimeField, SelectField 같은 규칙 기반 부품들을 한 곳에 정리

   • “새 입력이 필요하면 먼저 기존 부품을 찾아보기”

3. 코드 리뷰에서 규칙 확인하기

   • PR을 만들 때 “규칙 어김이 없나” 체크 항목 추가

   • 단순한 기능 검토가 아니라 원칙 검토도 함께

솔직한 소감

규칙 문서가 있었는데도 규칙을 지키지 않습니다. “규칙을 정하는 것”과 “규칙을 지키는 것”은 다른 일이라는 것입니다.

문서를 잘 써도 부족하고, 코드 리뷰를 해도 놓칠 수 있습니다. 규칙이 살아있으려면, 새 화면을 만들 때마다 “규칙을 확인하는” 습관이 필요합니다. 다음 번부터는 이걸 프로세스에 넣겠습니다.