본문으로 건너뛰기

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

제이리

2026.08.09

클로드가 PRD와 다르게 제작하기도 한다 본문 이미지

📝 한줄 요약

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

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

👥 이런 분께 추천

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

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

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

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

🙋 내 스펙 & 환경

항목

내용

직업

인사관리 담당자 (기획 문서 작성)

도구

Claude + TypeScript 웹사이트

문제 상황

”Reason 값(사유)“이 PRD와 코드에서 다르게 정의됨

발견 방법

화면을 보다가 느낌이 이상해서 문서를 다시 읽음


진행 방법

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 드롭다운에 "주문건, 납기, 품질, 기타" 보임
실제: 정확히 그렇게 보임
일치: ✓

완벽했습니다.

🛠 사용한 도구

도구

역할

PRD 문서

기획 내용 기록

VS Code

코드에서 “Reason” 찾아 비교

Claude

코드 수정 및 설명

웹사이트

실제 화면에서 값 확인


배운 점

💡 핵심 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와 협업할 때는 “기획 → 요청 → 검수”의 사이클에서 기획이 제일 중요하다는 것. 기획이 명확하면 요청도 쉽고, 검수도 빠르다는 것을 한번 더 느꼈습니다.

3

함께 이야기해요 3

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

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

사실 제이리님이 지금 하시는 작업은 prd만으론 어려울수 있어요. 제가 보기엔 깃허브의 스펙킷 스킬을 사용해보시면 좋을듯 합니다. 스펙주도 개발 방법론이라고 하는데 스펙에 따라 의도하는 바대로 그대로 개발하고 싶을때 사용하면 좋은 방법론 입니다. 개발자와의 소통에도 도움이 많이 되고요.

스펙킷 설명https://share.google/aimode/yJiTdYnOZisO71E40

아래 링크를 ai에게 던져주고 이걸 이용해서 작업하고 싶다고 하고, 사용법을 알려달라고 하시면 되요.

https://github.com/github/spec-kit

애진 프로필 이미지
애진2026.08.10

AI가 다르게 만든 결과를 단순 오류로 보지 않고, PRD의 모호함까지 돌아보신 과정이 꼼꼼하다고 느껴지네요! 특히 DB에는 개발 친화적인 영문 값을 저장하고 화면에는 이해하기 쉬운 한글을 보여주는 방식으로 정리한 부분이, 기획과 구현 사이의 간극을 잘 보여주는 사례 같아요. AI와 협업할수록 “기획 → 요청 → 검수”의 연결이 정말 중요하다는 걸 다시 느끼게 됩니다

뽀짝이 프로필 이미지
뽀짝이2026.08.09
"기획이 명확하지 않으면 AI도 다르게 만든다"는 핵심 포인트가 정말 잘 담겨 있어요. PRD의 ["주문건", "납기"]와 코드의 ["overtime_order", "overtime_deadline"]를 나란히 비교해서 불일치를 발견하신 과정이 특히 인상적이에요. 비개발자 시각에서 "뭔가 다른 느낌"이 들었을 때 그냥 넘기지 않고 문서로 돌아가서 대조해보신 게 핵심이었죠. DB 값(영문)과 화면 값(한글)을 분리해서 둘 다 PRD에 명시하는 방식으로 정리하신 것도 실무에서 바로 쓸 수 있는 패턴이에요. 나중에 앱이 커질수록 이 구분이 얼마나 중요한지 더 실감하시게 될 거예요. 체크리스트까지 직접 만드셔서 다음 화면 개발 때 바로 쓸 수 있게 정리하셨는데, 같은 시행착오를 겪는 분들한테 실질적인 도움이 될 것 같아요. 🐈‍⬛

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

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

이런 사례도 있어요

사례 전체 보기