본문으로 건너뛰기

규칙 문서가 꼬일 때

제이리

2026.08.10

규칙 문서가 꼬일 때 본문 이미지

📝 한줄 요약

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

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

👥 이런 분께 추천

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

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

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

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

🙋 내 스펙 & 환경

항목

내용

직업

초과근무관리 앱 제작

코딩 경험

TypeScript, React, Next.js

현황

MVP 5개 화면 완성, 검수 및 규칙 적용 중

규칙 문서

DEV.md (개발 제약 20개 나열)


진행 방법

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


적용할 점

🎯 결과

위반

규칙

원인

대책

로그인 한국어

규칙 1 (전부 영어)

급한 일정 + 규칙 확인 건너뜀

새 화면마다 DEV.md 다시 읽기

브라우저 기본 날짜

규칙 4 (커스텀 입력만)

부품 재사용 생각 안 함

규칙 따르는 부품 목록화

📋 복붙 가능한 체크리스트

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

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

🔜 다음 계획

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

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

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

  2. 부품 목록 만들기

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

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

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

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

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


솔직한 소감

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

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

5

함께 이야기해요 5

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.08.10

"참조"와 "확인"의 차이를 이렇게 명확하게 짚은 글은 처음 봤어요. 로그인 화면이 배포 후 고객이 제일 먼저 보는 화면이었다는 맥락이 규칙 위반을 더 아프게 만드는데, 발견 당일 바로 고쳤다는 것도 중요한 포인트예요.

DateField를 이미 만들어둔 덕에 수정 모달은 옵션 하나만 바꾸면 됐다는 부분 — 규칙을 따르는 부품이 있으면 급한 상황에서도 빠르게 고칠 수 있다는 게 설득력 있게 전달됐어요. "임시도 배포되면 고객이 봅니다"라는 문장, 많이 공감해요.

체크리스트까지 공유해주신 덕에 바로 써먹을 수 있겠어요. 고롱고롱... 이런 글 보면 흐뭇해요 ✨

애진 프로필 이미지
애진2026.08.10

규칙을 문서에 잘 적어두는 것과, 실제 화면 구현에서 계속 지키는 것은 다른 일이라는 점이 정말 공감돼요. 특히 급하게 추가한 로그인 화면과 수정 모달에서 규칙이 어겨진 사례가 현실적으로 와닿고, 이미 만들어 둔 DateField를 재사용해 빠르게 일관성을 되찾은 부분도 좋았습니다. 규칙을 기억에 맡기지 않고 새 화면마다 확인하는 프로세스로 바꾸신 게 가장 든든한 개선 같아요

아루나 프로필 이미지
아루나2026.08.11

규칙 문서가 길어지면은 사실 추론 모델의 특성상 규칙을 완전히 지키지 않을 확률도 올라갑니다. 정말 완벽하게 규칙을 지키게 하고 싶다면은 규칙을 기계적으로 지킬 수 있게 하는 스크립트로 변환할 수 있는지를 한번 알아보시고 기계적으로 지킬 수 있는 부분은 추론으로 하지 말고 코드로 강제적으로 지킬 수 있게 하는게 필요합니다.

박준_JoonLab 프로필 이미지
박준_JoonLab2026.08.19

오 규칙이 어겨진 두 곳을 발견 당일에 다 고치시고, 원인까지 "급한 일정 + 규칙 확인 건너뜀"으로 적어두신 게 정말 좋네요. 보통은 고치고 끝내는데 왜 어겨졌는지를 같이 남기셨으니 대책이 실제로 나올 수 있었던 것 같습니다.

여기서 한 발 더 나아가면, 20개 규칙을 기계가 판정할 수 있는 것과 사람이 판단해야 하는 것으로 갈라보시면 좋을 것 같습니다. 규칙 4번은 'type="date"' 문자열을 찾는 것만으로 결정론적으로 잡히고 규칙 1번도 소스에서 한글 음절 범위를 정규식으로 훑으면 잡히는데, 규칙 20번은 칸의 목적을 봐야 하니 체크리스트에 남는 쪽이 맞습니다.

저는 "다 했습니다"라는 선언을 믿지 않고, grep이나 건수 대조로 확인되는 건 말로 묻지 않게 바꿨습니다. Claude Code를 쓰신다면 그 검사를 훅으로 파일 저장·커밋 시점에 걸 수 있어서, 급한 날에도 체크리스트가 건너뛰어지지 않게 되더라고요.

사례 공유 감사합니다!

김도경 프로필 이미지
김도경2026.09.27

잘 읽었습니다~

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기