개발이 끝난 SDD 문서, 지울 것과 도메인에 남길 것

2026.07.05 게시

이 시리즈는 작성 시점의 기록이다. 현재 기준은 Adaptive Agentic SDD 저장소에 정리해두었다.

개발이 끝난 SDD 문서, 지울 것과 도메인에 남길 것

이전 글에서는 백로그가 세션 연속성을 위한 영속 컨텍스트라고 정리했다. 그런데 그 컨텍스트는 세션이 끝난 뒤에도 계속 필요할까? 필요하다면 어디에 있어야 할까? 이번 글은 개발이 끝난 SDD 산출물을 놓고 실제로 고민한 내용이다.

1. SDD 산출물 6종을 다시 보면

지금까지 나는 SDD 흐름에서 다음과 같은 산출물을 작업 단위 폴더에 쌓아왔다.

/specs/feature-name/
  01-requirements.md
  02-impact-analysis.md
  03-implementation-plan.md
  04-backlog.md
  05-test-plan.md
  06-review-notes.md

작업 중에는 이 문서들이 전부 필요하다. 요구사항을 잊지 않기 위해, 영향 범위를 놓치지 않기 위해, 세션이 끊겨도 이어가기 위해.

그런데 PR이 merge되고 나면 상황이 달라진다.

- requirements: 이미 코드에 반영됐다. PR 설명에도 남아 있다.
- impact-analysis: 분석 당시의 스냅샷이다. 코드가 바뀌면 낡은 정보가 된다.
- implementation-plan: 계획이었을 뿐, 실제 구현과 어긋날 수 있다.
- backlog: 진행 상태 체크리스트다. 다 끝나면 전부 [x]다.
- test-plan: 테스트는 이미 코드로 존재한다.
- review-notes: 리뷰 시점의 대화 기록이다.

6개 중 실제로 “다음 작업에서도 유효한 정보”를 담고 있는 건 많지 않다. 대부분은 그 작업을 진행하는 동안에만 값어치가 있는 문서였다.

2. 진짜 문제: 문서 위치와 코드 위치가 다르다

처음엔 이 문서들을 그냥 두면 된다고 생각했다. 지우기 아까웠고, 나중에 비슷한 작업을 할 때 참고할 수 있을 것 같았다.

그런데 실제로 겪어보니 문제는 다른 데 있었다.

내 프로젝트에는 여러 도메인이 있고, 코드 변경도 도메인 단위로 일어난다. 반면 SDD 산출물은 docs/ 아래 작업 단위 폴더에 따로 쌓여 있다.

그 결과 이런 일이 생겼다.

- 주문 도메인을 다시 건드릴 일이 생겼다
- 예전에 비슷한 작업을 하면서 정리한 문서가 어딘가 있다
- 그런데 Agent는 그 문서의 존재를 모른다
- 결국 사람이 "이 파일 참고해"라고 매번 지정해줘야 한다

문서가 코드 옆에 있지 않으면, 그 문서는 “찾아서 알려줘야 하는 정보”가 된다. 이건 이전 글에서 말한 백로그의 목적, 즉 Agent가 알아서 참고할 수밖에 없는 상태를 만든다는 것과 반대되는 결과다.

3. 이력 문서 vs 현행 문서

여기서 구분이 필요하다는 걸 깨달았다. SDD 산출물은 크게 두 종류로 나뉜다.

이력 문서 — 그때 어떻게 결정했는가
  requirements, impact-analysis, implementation-plan,
  backlog, test-plan, review-notes

현행 문서 — 지금 이 로직이 어떻게 동작하는가
  (지금까지는 따로 존재하지 않았다)

이력 문서는 “왜 이렇게 됐는지”를 설명하지만, 시간이 지나면 코드와 어긋난다. 현행 문서는 존재한 적이 없었다. 그래서 다음 작업을 할 때마다 Agent는 코드를 처음부터 다시 읽고 추론해야 했다.

다음 SDD 작업에서 진짜 필요한 건 이력 문서 전체가 아니라, 지금 이 도메인이 어떻게 동작하는지에 대한 최신 요약이었다.

4. 남길 것: 도메인 옆에 두는 현행 문서

그래서 지금 잡고 있는 방향은 이렇다. 도메인 코드 옆에 비즈니스 로직 단위로 문서를 쌓는다.

여기서 핵심은 “반드시 소스 패키지 안에 md 파일을 넣는다”가 아니다. 중요한 건 Agent가 도메인 코드를 탐색할 때 자연스럽게 함께 발견할 수 있는 위치와 규칙을 만드는 것이다. 예를 들면 둘 다 가능하다.

domain/order/
  controller/
  service/
  mapper/
  business/
    order-cancel-policy.md
    order-discount-rule.md
    order-refund-eligibility.md
docs/business/order/
  order-cancel-policy.md
  order-discount-rule.md
  order-refund-eligibility.md

소스 폴더 안에 문서를 두는 걸 프로젝트가 꺼린다면 뒤쪽처럼 도메인 구조를 그대로 미러링해도 된다. 어느 쪽이든 “코드를 보는 김에 자연스럽게 같이 보인다”는 조건만 지키면 된다.

그리고 여기서 중요한 건 기술 계층이 아니라 비즈니스 로직 단위로 나누는 것이다. 하나의 규칙은 보통 endpoint → service → SQL을 관통해서 존재한다. 계층별로 문서를 쪼개면 결국 Agent가 규칙 하나를 이해하려고 여러 파일을 다시 조합해야 하고, 그러면 처음부터 목표했던 것이 흐트러진다.

문서 하나의 내용은 이 정도면 충분하다.

# 주문 취소 정책

## 이 규칙이 존재하는 이유
결제 완료 후 배송 시작 전까지만 취소를 허용한다.
운영팀 문의 다수가 배송 시작 후 취소 요청이라 정책을 명확히 했다.

## 핵심 규칙
- 결제 완료 ~ 배송 시작 전: 전액 취소 가능
- 배송 시작 후: 취소 불가, 반품 절차로 안내
- 부분 취소는 지원하지 않는다

## 관련 위치
- OrderController#cancelOrder
- OrderService#validateCancelable
- OrderMapper.xml #selectShippingStatus

## 주의할 예외 케이스
- 배송 상태가 아직 동기화되지 않은 경우 취소 가능 처리하면 안 된다
- 부분 환불 요청이 들어와도 정책상 거부해야 한다

이력 문서에 있던 “결정된 사항”, “주의할 점” 같은 항목 중 지금도 유효한 것만 여기로 옮겨온다. 나머지, 즉 그 결정에 이르기까지의 논의 과정이나 진행 체크리스트는 옮기지 않는다.

남기면 안 되는 것, 남아야 하는 것

business 문서는 회의록도, 개발일지도, Agent의 기억장치도 아니다. 지금 이 로직이 어떻게 동작하는지만 담아야 한다.

남기면 안 되는 것 — 이력·과정:

- 1차 구현에서는 A 방식으로 하려 했으나 실패했다
- B 방식도 검토가 필요하다
- 테스트는 아직 다 못 끝냈다
- TODO: 나중에 다시 확인
- 리뷰어가 성능을 우려했다

남아야 하는 것 — 지금의 규칙:

- 주문 취소는 결제 완료 후 배송 시작 전까지만 허용한다
- 배송 상태가 외부 물류 시스템과 동기화되지 않은 경우 취소 가능으로 판단하면 안 된다
- 부분 취소는 현재 정책상 지원하지 않는다
- 관련 검증은 OrderService#validateCancelable에서 수행한다

다만, 아직 명확하지 않은 부분

비즈니스 로직 하나를 문서 하나로 대응시킨다고 했을 때, 그 로직 자체가 비대하면 문서도 같이 비대해진다. 처음엔 “문서가 한 화면을 넘어가면 로직을 잘못 묶은 것 같다”는 감으로 대하고 있었는데, 조금 더 구체화하면 기준은 길이보다 변경 이유에 가까운 것 같다.

같은 PR에서 자주 함께 바뀌는 규칙이면 하나의 문서로 둔다.
서로 다른 정책 담당자, 서로 다른 화면, 서로 다른 장애 원인을 갖는다면 문서를 나눈다.

다만 이것도 여러 번 검증해본 기준은 아니라서, 계속 다듬어갈 부분이다.

5. 단, 현행 문서는 코드처럼 관리해야 한다

business 문서를 만드는 것보다 더 중요한 건 그 문서를 낡게 두지 않는 것이다. 현행 문서이기 때문에, 코드와 어긋나는 순간 오히려 없는 것보다 위험해진다. Agent가 낡은 문서를 최신 정보로 믿고 잘못된 판단을 내릴 수 있기 때문이다.

그래서 최소한 다음 원칙은 지키려고 한다.

- 관련 로직을 수정하면 같은 PR에서 business 문서도 함께 수정한다
- 코드와 문서가 충돌하면 코드를 우선한다
- 더 이상 맞지 않는 문서는 지우거나 deprecated로 표시한다
- 확신할 수 없는 내용은 단정적으로 쓰지 않는다

이 중 첫 번째가 제일 지키기 어렵다. 로직을 고치면서 옆의 문서까지 같이 고치는 걸 잊기 쉽다. 지금은 PR 체크리스트에 “관련 business 문서 확인”을 한 줄 넣어두는 정도로 대응하고 있는데, 결국 사람이 잊지 않고 챙겨야 하는 방식이라 한계가 있다.

6. 지운다기보다, 작업 폴더에 남기지 않는다

반대로 다음 산출물은 병합 후 작업 폴더에 별도로 유지하지 않는다.

- backlog: 진행 상태 체크리스트
- test-plan: 실제 테스트 코드가 대신한다
- review-notes: 리뷰 시점의 논의였을 뿐이다

여기서 말하는 “남기지 않는다”는 히스토리를 완전히 없앤다는 뜻이 아니다. 작업 폴더에 별도 파일로 계속 들고 있지 않는다는 뜻이다.

결정 과정과 변경 이유는 이미 PR 설명, 커밋 메시지, 리뷰 기록에 남는다. 그중에서 다음 작업에도 계속 참조해야 하는 규칙만 business 문서로 승격하고, 나머지는 그 자리에 남겨두면 충분하다.

requirements, impact-analysis, implementation-plan도 마찬가지다. SDD 산출물은 영구 보존 문서가 아니라 작업 중 컨텍스트이고, 그 역할이 끝나면 굳이 파일로 계속 안고 있을 이유가 없다.

7. 토큰 관점에서 보면

이렇게 나누는 이유가 정리정돈만은 아니다. 실무에서 더 크게 체감하는 건 토큰이다.

business 문서가 도메인 옆에 없으면, Agent는 다음 작업 때 관련 코드를 전부 훑거나, 옛 이력 문서 6종을 처음부터 다시 읽어야 한다. 반대로 도메인 옆에 짧은 현행 문서가 있으면, Agent는 그 문서를 기준으로 분석 범위를 좁힐 수 있다.

문서 없음 → 관련 코드 전체 탐색 → 컨텍스트 소모 큼
이력 문서만 있음 → 어디까지가 유효한지 다시 판단 필요
현행 문서 있음 → 문서 기준으로 범위 좁혀서 분석 → 컨텍스트 소모 작음

문서를 남기는 기준이 “나중에 참고하면 좋을 것 같아서”가 아니라 “다음 Agent가 덜 헤매고, 덜 읽게 하기 위해서”가 되어야 하는 이유가 여기에 있다.

8. 정리: 개발 완료 시 체크리스트

지금 기준으로 정리하면 이렇다.

1. business 문서에 이번 작업으로 바뀐 로직이 반영되어 있는가
   - 없으면 새로 만든다
   - 있으면 바뀐 부분만 현행화한다
2. backlog, test-plan, review-notes는 작업 폴더에 남기지 않는다
3. requirements, impact-analysis, implementation-plan 중
   지금도 유효한 결정 사항만 business 문서로 옮기고, 나머지는 PR에 맡긴다
4. "왜 바꿨는가"는 PR 설명과 커밋 메시지에 맡기고 별도 파일로 남기지 않는다
5. 코드와 business 문서가 어긋나 있지 않은지 마지막으로 확인한다

9. 마무리

SDD 산출물은 작업 중에는 전부 필요하지만, 병합 후에는 그 자체로 유지할 대상이 아니다. 남겨야 하는 건 작업 과정이 아니라 지금 이 도메인이 어떻게 동작하는가뿐이다.

그리고 그 정보는 세션 밖이 아니라 코드 옆에 있어야 다음 Agent가 찾아서 알려주지 않아도 스스로 참고한다. 다만 이 승격 작업을 사람의 기억에만 맡기면, 바쁠 때 또 누락된다. 언젠가는 이 부분도 프로젝트 규칙이나 Agent 지시 흐름에 못박아서, PR이 끝나는 시점에 자동으로 점검되게 만들고 싶다. 지금은 아직 그 앞 단계, 그러니까 “무엇을 남기고 무엇을 남기지 않을지” 기준을 사람이 먼저 명확히 하는 단계에 있다.

백로그가 세션 밖의 영속 컨텍스트였다면, business 문서는 그 컨텍스트가 결국 도착해야 하는 자리다.