PRD만 있으면 안 되는 이유

PRD만 있으면 안 되는 이유

처음에는 PRD만 있으면 된다고 생각했다. 제품이 무엇을 해야 하는지 적어두면, AI가 그걸 보고 구현하면 될 것 같았다.

하지만 실제로는 그렇지 않았다. PRD는 중요하지만, PRD만으로는 AI의 작업을 끝까지 통제하기 어렵다.

PRD는 “무엇을 만들 것인가”를 말한다. 하지만 AI가 실제로 일할 때는 더 많은 질문이 생긴다.

• 이 PRD가 최종본인가, 초안인가?
• 이 요구사항은 승인된 것인가, 아직 제안 상태인가?
• 어느 코드와 연결되는가?
• 어떤 테스트로 검증할 것인가?
• 이미 실패한 대안은 무엇인가?
• 지금 작업은 전체 아키텍처와 맞는가?

PRD는 이 모든 것을 혼자 해결하지 못한다.

Master PRD와 Active Digest를 분리해야 했다

가장 먼저 터진 문제는 “마스터 PRD가 무엇인가”였다.

파일명에 Master, Draft, Lv2, v2.0, ver1.0 같은 말이 섞여 있었다. 타임스탬프도 완전히 믿을 수 없었다. 어떤 파일은 오래전에 만든 초안인데 최근 수정되어 최신처럼 보였고, 어떤 파일은 이름은 드래프트처럼 보여도 실제로는 중요한 이주 소스였다.

그래서 역할을 나눴다.

Master PRD = 제품 철학, 장기 비전, 티어, 로드맵의 최상위 바이블 01_PRD.md = 지금 개발자가 읽기 좋은 Active Digest 02_REQUIREMENTS_TRACEABILITY.md = 요구사항 ID와 상태를 추적하는 RTM 03_ARCHITECTURE.md = 실제 시스템 구조와 데이터 흐름을 고정하는 Architecture Contract

이 분리가 없으면 01번 문서가 마스터 PRD처럼 보이거나, 반대로 마스터 PRD의 중요한 내용이 01번에 다 옮겨지지 않아 사라진 것처럼 보인다.

PRD 파일명은 규칙이 아니라 Registry로 관리해야 했다

blog 프로젝트에서 또 다른 문제가 나왔다. 중요한 PRD 파일명이 MASTER_PRD.md가 아니라 Tistory_Auto_Publish_PRD.md였다.

이 이름은 표준 파일명은 아니지만, 그렇다고 버릴 문서도 아니었다. 오히려 그 프로젝트의 초기 철학과 핵심 요구사항이 들어 있는 중요한 이주 소스였다.

그래서 결론은 이랬다.

권장 파일명은 docs/MASTER_PRD.md일 수 있다. 하지만 실제 Active Master 판정은 파일명이 아니라 Registry와 문서 상태로 한다.

00_PRODUCT_BRIEF.md 안에 Master PRD Registry를 두고, 각 파일을 다음처럼 분류한다.

• Active Master PRD
• Master PRD Candidate
• Migration Source
• Legacy Reference
• Superseded Draft
• Quarantined Scratch
• Deletion Candidate

이렇게 해야 비표준 파일명도 시스템 안으로 안전하게 편입할 수 있다.

PRD는 시작점이고, 운영체계는 연결망이다

내가 만든 구조에서는 PRD가 단독으로 존재하지 않는다.

docs/00_PRODUCT_BRIEF.md docs/01_PRD.md docs/02_REQUIREMENTS_TRACEABILITY.md docs/03_ARCHITECTURE.md docs/04_ADR_DECISIONS.md docs/05_TASK_BACKLOG.md docs/06_TEST_PLAN.md docs/13_LEGACY_INDEX.md docs/99_HANDOFF_CURRENT.md

각 문서는 서로 다른 역할을 가진다.

• 00_PRODUCT_BRIEF.md: 프로젝트 정체성과 문서 지도
• 01_PRD.md: 현재 구현 단계의 Active Digest
• 02_REQUIREMENTS_TRACEABILITY.md: 요구사항과 상태, 검증 기준
• 03_ARCHITECTURE.md: 흐름과 인터페이스 계약
• 04_ADR_DECISIONS.md: 왜 그렇게 결정했는지
• 05_TASK_BACKLOG.md: 지금 할 일
• 06_TEST_PLAN.md: 검증 방법
• 13_LEGACY_INDEX.md: 실패, 보류, 보존 자산 색인
• 99_HANDOFF_CURRENT.md: 다음 세션으로 넘길 현재 상태

PRD는 “소스 오브 트루스”일 수 있지만, 실행의 전부는 아니다. 실행에는 추적표와 검증 계획이 필요하다.

상태가 없으면 AI는 마음대로 완료한다

가장 위험한 문제는 상태였다.

AI는 종종 “완료되었습니다”라고 말한다. 하지만 실제로는 다음 중 하나일 수 있다.

• 파일을 만들지 않았다.
• 코드를 수정했지만 테스트하지 않았다.
• 문서만 만들고 구현은 안 했다.
• 실패 로그를 무시했다.
• 사용자가 승인하지 않았는데 완료 처리했다.

그래서 요구사항 상태 흐름을 명시했다.

Proposed → Accepted → Implemented → Verified → Completed

이 흐름에서 AI가 마음대로 올릴 수 없는 상태가 있다.

Verified Completed

이 상태는 사람이 명시적으로 승인해야 한다.

RTM은 AI의 길찾기 지도다

RTM은 Requirements Traceability Matrix의 줄임말이다. 쉽게 말하면 요구사항 추적표다.

비개발자에게 RTM은 조금 딱딱하게 느껴질 수 있다. 하지만 AI 개발에서는 매우 유용하다.

RTM은 이런 질문에 답한다.

• 이 기능은 어떤 요구사항에서 왔는가?
• 어떤 작업 패키지와 연결되는가?
• 어느 파일이 바뀌었는가?
• 어떤 테스트로 검증됐는가?
• 현재 상태는 무엇인가?

AI가 작업하다 길을 잃었을 때, RTM은 “지금 무엇을 하고 있었는지”를 되찾게 해준다.

Architecture는 “다시 그 길로 가지 마라”를 담는다

PRD는 목적을 말하지만, 아키텍처는 길을 말한다.

특히 중요한 것은 실패한 길을 반복하지 않는 것이다. AutoVideo에서는 고부하 로컬 생성, Wan 14B OOM, 8종 모션 품질 안정화 같은 이력이 있었다. 시간이 지나면 AI는 그 실패한 대안을 다시 꺼내오곤 했다.

그래서 아키텍처 문서와 레거시 인덱스가 필요했다.

docs/03_ARCHITECTURE.md docs/13_LEGACY_INDEX.md

이 문서들은 “어떤 길로 가야 하는가”뿐 아니라 “어떤 길로 다시 가면 안 되는가”를 기록한다.

Test Plan이 없으면 검증은 감상문이 된다

AI가 “테스트했습니다”라고 말해도, 무엇을 어떻게 테스트했는지 없으면 의미가 약하다.

그래서 테스트 계획이 필요하다.

docs/06_TEST_PLAN.md

여기에는 최소한 다음이 들어가야 한다.

• 어떤 명령을 실행했는가
• 어떤 입력으로 테스트했는가
• 기대 결과는 무엇인가
• 실제 결과는 무엇인가
• 실패했다면 로그는 어디 있는가
• 실행하지 않은 것은 무엇인가

특히 blog 프로젝트에서는 “원고 업데이트”와 “실제 블로그 발행”을 분리해야 했다. 문서 업데이트는 할 수 있지만, Playwright 브라우저 실행이나 실제 발행은 별도 승인 없이는 하면 안 된다.

체크리스트

PRD를 만들었다면 다음도 같이 확인하자.

• Master PRD와 Active Digest가 분리되어 있는가?
• 비표준 PRD 파일명을 Registry로 편입할 수 있는가?
• 요구사항 상태 흐름이 있는가?
• RTM이 있는가?
• 아키텍처와 연결되는가?
• 작업 백로그가 있는가?
• 테스트 계획이 있는가?
• AI가 임의로 완료 처리하지 못하게 막았는가?

다음 편 예고

다음 편에서는 여러 프로젝트를 한 작업장에 둘 때 왜 <WORKSPACE_ROOT>와 <PROJECT_ROOT>를 나눠야 했는지 다룬다. 프로젝트가 늘어나면 “어디서 실행하는 명령인가”가 생각보다 큰 문제가 된다.