클로드가 PRD와 다르게 제작하기도 한다

ALT

PRD9

📝 한줄 요약

클로드에게 화면을 만들도록 요청했는데, 뭔가 다르다는 느낌이 들었어요. 원인을 찾아보니 PRD(기획 문서)에 정한 값과 실제 코드가 달랐습니다. 이 경험을 통해 “문서와 코드를 일치시키는 게 왜 중요한지” 배웠습니다.

Before: 클로드가 만든 것을 그냥 신뢰하기만 함
After: 문서와 코드를 직접 비교하고 맞춰서 안정성 확보

👥 이런 분께 추천

• 클로드나 AI와 협업하면서 “뭔가 다른데?”라는 느낌이 드는 분

• AI가 만든 결과물을 어떻게 검증할지 모르는 분

• 개발자와 일하면서 “문서와 코드가 다르다”는 말을 들은 분

• 비개발자인데 기획한 것이 제대로 구현되었는지 확인하고 싶은 분

🙋 내 스펙 & 환경

진행 방법

1. 왜 문제를 발견했나

초과근무 앱의 “Report(통계)” 화면을 만들었어요. 클로드가 만든 걸 보니 “초과근무 사유(Reason)“라는 필드가 있었어요.

그런데 문제가 있었어요. 초과근무 사유는 정해진 값들(주문건, 납기, 품질 등)이 있는데, 어디서 이 값들을 가져와야 할까요?

해결 방법:

PRD 문서를 다시 읽어봤어요. 그러다가 발견했어요:

• PRD에서 정한 Reason 값: [“주문건”, “납기”, “품질”, “기타”]

• 코드에서 쓴 Reason 값: [“overtime_order”, “overtime_deadline”, …]

완전히 달랐어요!

2. 첫 번째 발견: 값 형식이 다르다

PRD에는 “사람이 읽을 수 있는 한글”로 썼는데, 코드에는 “프로그래밍 방식의 영문”으로 정의돼 있었어요.

이건 문제예요. 왜냐하면:

• 데이터베이스에 “주문건”이라고 저장되면, 나중에 찾기 어려워져요

• 코드에서 “overtime_order”라고 하면, 사용자는 뭔지 못 알아요

원인: 클로드가 실수한 게 아니라, 제가 기획을 명확하게 안 했어요. “값은 이렇게 정할 거”를 PRD에 명확히 안 썼거든요.

3. 두 번째 벽: “어느 쪽이 맞나?”

그럼 어느 쪽으로 통일할까요?

옵션 1: PRD를 코드처럼 바꾸기

• Reason: [“overtime_order”, “overtime_deadline”, …]

• 장점: 프로그래밍 방식. 확장성 좋음

• 단점: 비개발자는 뭔지 못 알아봄

옵션 2: 코드를 PRD처럼 바꾸기

• Reason: [“주문건”, “납기”, “품질”, “기타”]

• 장점: 사람이 읽기 쉬움

• 단점: 데이터베이스에 한글을 저장하는 게 복잡할 수 있음

해결 방법:

두 가지를 모두 섞기로 했어요. 데이터베이스에는 영문(“order_reason”)으로 저장하고, 화면에 보여줄 때는 한글(“주문건”)로 표시하는 거예요.

그리고 PRD에 이 규칙을 명확히 적어두기로 했어요.

4. 최종 일치

PRD를 이렇게 정확히 다시 써서 클로드와 공유했어요:

Reason 필드의 값

데이터베이스에 저장되는 값 (개발자용):
- order_reason: 주문으로 인한 초과근무
- deadline_reason: 납기로 인한 초과근무
- quality_reason: 품질로 인한 초과근무
- other_reason: 기타

화면에 보여지는 값 (사용자용):
- 주문건
- 납기
- 품질
- 기타

이제 명확해졌어요.

5. 검증: 문서와 코드가 일치하나

웹사이트에서 Report 화면을 열었어요.

예상: Reason 드롭다운에 "주문건, 납기, 품질, 기타" 보임
실제: 정확히 그렇게 보임
일치: ✓

완벽했습니다.

🛠 사용한 도구

배운 점

💡 핵심 1: AI도 “기획이 애매하면” 다르게 만든다

클로드가 잘못 이해한 게 아니라, 제 기획이 불명확했어요.

“Reason 값이 뭐야?”라고 물었을 때:

• 저는 “사용자가 보는 것”만 생각했어요 (주문건, 납기…)

• 클로드는 “데이터베이스에 저장되는 것”도 정의해야 한다고 생각했어요

둘 다 맞는데, 처음부터 두 가지를 다 명확히 했으면 문제가 없었어요.

💡 핵심 2: 문서와 코드를 비교하는 방법

“다르다”는 느낌이 들 때, 어떻게 확인할까요?

1. PRD에서 “이렇게 정했다”는 부분을 찾기

2. 코드에서 그 부분 찾기 (Ctrl+F로 검색)

3. 같은지 다른지 비교하기

4. 다르면 원인 찾기

💡 핵심 3: “데이터베이스 값”과 “화면 값”은 다를 수 있다

이건 중요해요.

• 데이터베이스: 편의성과 확장성 중심 (영문, 간단한 형식)

• 화면: 사용자 경험 중심 (한글, 이해하기 쉬운 형식)

이 둘을 구분해서 생각해야 혼란이 없어요.

💡 핵심 4: 명확한 기획 문서의 가치

AI와 협업할 때, 기획 문서가 명확할수록 좋은 결과가 나와요. 왜냐하면:

• 클로드가 “뭘 해야 할지” 정확히 이해

• 저는 “이게 맞나” 쉽게 검증 가능

• 오류가 줄어듦

적용할 점

🎯 다음부터 PRD를 쓸 때

1. 값은 두 가지를 정하기

   • 데이터베이스에 저장되는 값 (개발자용)

   • 사용자가 보는 값 (사용자용)

2. 예시를 구체적으로 들기

   • “상태는 어떤 값들이 있어?” ❌

   • “상태는: [대기중=waiting, 승인됨=approved, 거절됨=rejected]” ✓

3. 주요 필드는 표로 정리하기

   • 필드명, 데이터베이스 값, 화면 값을 한 표에 담기

📋 문서와 코드 일치 체크리스트

새로운 화면을 만들 때, 이 체크를 해요:

• PRD에 정한 필드들이 코드에 다 있나?

• 값(Enum 또는 options)이 PRD와 코드에서 같나?

• 값의 한글/영문 구분이 명확하게 되어 있나?

• 실제 화면에서 보는 것과 데이터베이스의 것이 다르면, 문서에 그 차이를 써두었나?

🔜 다음 단계

1. 현재: Reason 값을 명확히 정하고 PRD 갱신 ✓

2. 다음: 초과근무 앱의 모든 필드를 같은 방식으로 정리하기

3. 그다음: 향후 기획할 때는 처음부터 “데이터베이스 값/화면 값” 구분 해서 쓰기

솔직한 소감

“클로드가 제대로 만들지 못했다”고 생각했는데, 알고 보니 제가 기획을 명확하게 안 했어요.

AI와 협업할 때는 “기획 → 요청 → 검수”의 사이클에서 기획이 제일 중요하다는 것. 기획이 명확하면 요청도 쉽고, 검수도 빠르다는 것을 한번 더 느꼈습니다.