[AI 주식 알람] PRD를 AI 에이전트가 읽게 만들기: SRS를 따로 쓰는 이유

PRD를 다 쓰고 나면 보통 바로 개발로 들어가고 싶어진다. 그런데 이번 프로젝트는 Cursor, Claude Code, Antigravity 같은 여러 AI 코딩 도구를 동시에 굴리면서 진행했고, 이 도구들에게 "PRD 읽고 알아서 개발해줘"라고 던지면 매번 다른 해석을 내놓는 문제가 있었다. PRD는 사람이 의도를 이해하기 위한 문서지, 에이전트가 그대로 코드로 변환하기엔 너무 느슨하다. 그래서 SRS(Software Requirements Specification)를 별도 문서로 분리했다.

이번 편은 PRD와 SRS를 왜 나눴는지, 그리고 SRS를 ISO/IEC/IEEE 29148 표준 형식으로 쓴 이유를 정리한다.

1. PRD와 SRS의 역할 분리

docs/PRD_v1.md와 docs/SRS-v1.md를 나눠 놓고 AGENTS.md에 이렇게 우선순위를 못박았다.

구현 세부사항이 충돌하면 PRD → SRS → AGENTS.md → 코드 순서를 따른다.

 

PRD는 "왜"를 담당한다 — Pain, KPI, 페르소나, ADR. SRS는 "무엇을, 어떤 계약으로"를 담당한다 — REQ ID, API 스펙, AC(Acceptance Criteria), Prisma 엔터티. 실제로 에이전트에게 작업을 시킬 때는 거의 항상 SRS 쪽 문서를 참조시켰다. PRD는 방향이 흔들릴 때 다시 열어보는 문서에 가깝다.

2. REQ ID 체계 — 요구사항에 좌표를 찍는다

SRS의 핵심은 모든 요구사항에 REQ-FUNC-xxx / REQ-NF-xxx 형태의 ID를 매기는 것이다. 이렇게 하면 커밋 메시지, 이슈, 테스트 코드 어디서든 같은 좌표로 요구사항을 참조할 수 있다.

기능 요구사항은 Given/When/Then 형태의 AC로 못박는다. 예를 들어 "핵심 후보 압축" 스토리의 AC 하나는 이렇다.

Given 사용자가 관심 종목 또는 섹터를 1개 이상 저장했고
When 홈 화면에 진입하면
Then 추천 카드 API는 3개 이하 카드를 반환해야 하며, 응답 p95는 800ms 이하여야 한다.

 

이게 왜 중요하냐면, "카드는 3개 이하"라는 문장은 사람이 봐도 모호하지 않지만, 에이전트 입장에서는 이걸 테스트 코드로 바로 옮길 수 있다는 게 핵심이다. AC 하나 = 테스트 케이스 하나로 거의 1:1 대응이 된다.

SRS 중 일부

3. 용어집을 먼저 확정한다

SRS 앞부분에 용어집(Definitions)을 크게 넣어뒀다. Confidence Score, Direction, Hold Days, No Call, Risk Mode 같은 단어들의 정의를 표로 박아둔다. 별거 아닌 것 같지만 실제로 효과가 컸다 — 에이전트마다 "리스크 모드"를 다르게 구현하려는 시도를 이 용어집 한 줄이 매번 막아줬다. 특히 No Call(데이터 부족으로 추천을 생성하지 못하는 상태) 같은 개념은 정의가 없으면 어떤 에이전트는 빈 배열을 반환하고, 어떤 에이전트는 500 에러를 던지는 식으로 갈렸을 것이다.

4. 스택을 SRS 안에 강제로 박아넣는다 (C-TEC)

SRS 0.2 개정에서 가장 크게 바뀐 부분이 C-TEC-001~007 기술 스택 정합성이다. Next.js App Router 단일 풀스택, Prisma + SQLite/PostgreSQL, Vercel AI SDK + Gemini의 streamObject(), NextAuth — 이런 스택 결정을 SRS 레벨에서 명시했다.

이유는 간단하다. 프로젝트 초기 스캐폴드가 레거시(Vite SPA) 흔적을 갖고 있었는데, 이 상태에서 에이전트에게 자유도를 주면 익숙한 스택(Express, Redis, Kafka 같은 걸 들고 오는 경우도 있었다)으로 돌아가려는 경향이 있었다. AGENTS.md에도 "package.json이 레거시 스캐폴드를 반영하고 있어도, 새 작업은 SRS C-TEC를 따른다"고 명시해 이 문제를 막았다.

SRS 내 C-TEC 정의

5. 개정 이력을 남기는 이유 — SRS도 틀릴 수 있다

SRS 0.1 → 0.3 개정 이력을 보면 /api/events라는 엔드포인트를 뺀 기록이 남아있다. 초안에는 있었는데, PostHog로 이벤트 수집을 위임하기로 하면서 자체 엔드포인트를 걷어냈다. EventLog, NotificationLog 같은 테이블도 같은 이유로 DB 스키마에서 제외했다.

SRS를 한 번 쓰고 끝내지 않고 버전을 올리면서 개정 이력에 "무엇을 왜 뺐는지"를 남긴 게 나중에 도움이 됐다. 에이전트가 예전 버전 기억으로 /api/events를 다시 만들려고 하면, 개정 이력을 보여주고 "이거 이미 논의돼서 뺀 거다"라고 바로 정정할 수 있었다.

6. 정리

SRS를 따로 쓰는 건 문서 작업이 하나 늘어나는 게 아니라, 여러 AI 도구가 같은 계약을 보고 개발하게 만드는 장치에 가까웠다. REQ ID, AC, 용어집, 스택 고정, 개정 이력 — 이 다섯 가지가 실제로 에이전트 간 해석 차이를 줄여준 부분이었다. 다음 편에서는 이 SRS를 실제로 Git 커밋 단위 태스크로 쪼갠 과정을 다룬다.