business 문서를 PR에서 갱신해보기

2026.07.14 게시

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

business 문서를 PR에서 갱신해보기

레거시 시스템을 운영하다 보면 같은 비즈니스 로직을 반복해서 분석하게 된다.

처음 보는 코드라서 분석하는 경우도 있지만, 예전에 확인했던 흐름을 새 작업이나 새 세션에서 다시 확인하는 경우도 많다. AI Agent가 나오면서 분석 자체는 쉬워졌지만, 매번 Controller부터 Service, SQL, 매핑 파일까지 다시 읽게 하면 그만큼 토큰과 도구 호출이 반복된다.

그래서 기능별 현재 로직을 business/*.md에 정리해두기 시작했다.

이 문서는 설계 문서라기보다 Agent를 위한 분석 결과 요약에 가깝다. 실제 코드는 계속 기준으로 남겨두되, 다음 작업에서는 business 문서를 먼저 읽고 필요한 코드만 확인하도록 하는 방식이다.

이전 글은 business 문서가 Agent의 탐색 왕복과 토큰 비용에 어떤 차이를 만드는지 설계 단계까지 측정한 실험이다.

Link - 문서는 토큰 청구서를 크게 줄이지 않는다 — 대신 Agent가 헤매는 시간을 줄인다

그 실험에서 business 문서가 있을 때 로직형 작업에서는 아래와 같은 차이가 있었다. 각 조건 1회 실행 결과다.

지표 문서 있음 문서 없음 차이
FRESH(탐색 토큰) 54,316 78,183 −30%
grep 호출 3 7 −57%
전체 도구 호출 9 12 −25%

적어도 문서를 읽는 쪽에서는 반복 분석 비용을 줄일 가능성이 있었다.

문제는 코드가 바뀐 뒤였다.

문서의 라이프사이클

전체 레거시를 먼저 분석해서 문서로 만들 생각은 없었다. 실제 수정이 필요한 영역만 그때 처음 생성한다.

business 문서 라이프사이클

business 문서는 변경 전 현재 상태를 설명하고, SDD 문서는 이번에 무엇을 바꿀지 설명한다. 구현이 끝나면 실제 코드를 기준으로 business 문서를 다시 갱신한다. 그러면 갱신된 문서가 다음 변경의 시작점이 된다.

이후에 해당 기능을 다시 수정하지 않는다면 문서를 갱신할 일도 없다. 전체 시스템을 미리 문서화하거나, 변경이 없는 문서를 주기적으로 다시 생성하지 않는다.

이 흐름에서 비어 있던 부분이 마지막 단계였다.

구현이 끝난 뒤 어떤 business 문서를 찾아서, 실제 구현 결과를 어떻게 반영할 것인가?

처음에는 이 과정을 PR Skill 하나로 묶으려고 했다.

/pr-business-docs

diff를 확인하고, 관련 코드를 따라가고, 갱신할 business 문서를 찾아서 현재 구현 내용으로 맞추는 흐름이다.

Skill보다 참조 규칙이 먼저 문제였다

바로 Skill을 만들지는 못했다. Skill이 참고할 project-pr-business-rules.md부터 해석할 여지가 많았다.

예를 들면 이런 표현들이다.

  • 코드에 물리적 경계가 있으면 문서를 그 위치에 둔다.
  • 이걸 모르면 로직을 틀리게 건드리는 내용을 포함한다.
  • 엔드포인트가 여러 개면 문서를 분리한다.
  • 대상 파일이 명확하지 않으면 분리 작업을 시작하지 않는다.

사람이 읽으면 대략적인 의도는 이해할 수 있지만 Agent는 매번 다르게 판단할 수 있다. 물리적 경계가 패키지인지 클래스인지도 정해져 있지 않았고, 문서 분리 조건과 중지 조건이 서로 충돌하는 경우도 있었다.

Skill을 만들기 전에 규칙부터 실제 프로젝트에 맞게 좁혔다.

  • 문서는 프로젝트의 기존 business/ 위치에 둔다.
  • 엔드포인트 또는 Kafka 토픽을 문서 구분 기준으로 사용한다.
  • 백로그는 있으면 교차검증에 사용하지만 필수 입력으로 두지 않는다.
  • 변경 파일은 분석의 끝이 아니라 호출 흐름을 찾기 위한 시작점으로 사용한다.
  • 문서 개수가 아니라 같은 호출 체인을 공유하는 범위로 작업을 묶는다.

처음에는 한 세션에서 문서 세 개까지만 처리하는 규칙도 생각했다. 하지만 실제 코드를 세어보니 같은 상품 영역의 문서 15개가 약 4,500줄의 호출 체인을 공유하고 있었다. 문서 개수로 나누면 같은 코드를 여러 세션에서 반복해서 읽게 된다.

반대로 문서가 세 개뿐이어도 서로 다른 호출 체인이라면 읽어야 할 코드는 더 많아진다. 그래서 고정된 숫자는 빼고 호출 체인을 기준으로 묶었다.

Skill을 만들기 전에 수동으로 한 번 돌렸다

정리한 규칙이 실제로 작동하는지 가격 변경 흐름을 대상으로 먼저 수동 실행했다.

처음에는 기존 가격 변경 문서 하나를 갱신하면 될 것으로 생각했다. 코드를 따라가니 실제 진입점은 세 개였다.

진입점 처리 방식 필요한 문서
기존 REST API 기존 Service 메서드 직접 호출 기존 문서 갱신
신규 REST API 판매 상태를 확인하는 공통 메서드 호출 신규 문서 생성
Kafka Consumer 신규 REST와 같은 공통 메서드 호출 기존 Kafka 문서 갱신

여기서 끝나지 않았다. 변경 파일과 백로그에는 없던 RetryListener가 여전히 예전 Service 메서드를 직접 호출하고 있었다. 현재는 비활성 상태지만 다시 켜면 본 처리와 Retry 처리의 동작이 달라질 수 있었다.

이 발견이 의미하는 것은 두 가지였다. 문서 갱신 대상은 변경 파일과 백로그 목록보다 넓을 수 있다는 것, 그리고 이렇게 남아 있는 이전 호출도 현재 동작의 일부이므로 business 문서에 기록될 대상이라는 것이다. 실제로 이후 Skill 실행에서 선정된 문서에는 이 Retry 진입점이 포함됐다.

수동 실행으로 확인한 내용은 이후 Skill의 탐색 절차에 반영했다.

  1. diff에서 변경 파일을 찾는다.
  2. Controller 또는 Listener까지 진입점을 역추적한다.
  3. 진입점이 호출하는 Service 메서드를 찾는다.
  4. 같은 Service 메서드를 호출하는 다른 진입점을 다시 찾는다.
  5. REST, Kafka, Retry에 연결된 business 문서를 함께 확인한다.
  6. 백로그가 있으면 변경 파일 목록과 교차검증한다.

별도 세션에서 Skill을 만들고 실행했다

규칙 정리와 수동 실행을 끝낸 뒤, 새 세션에서 pr-business-docs Skill을 만들었다. Skill 실행도 설계 대화와 분리된 세션에서 진행했다.

만들기 전에 실제 저장소 구조를 다시 확인하니 SDD 세트마다 백로그 폴더와 변경 파일 섹션의 이름이 달랐다. Agent는 특정 섹션 검색 결과가 0이라는 이유로 해당 정보가 없다고 판단했지만, 실제로는 ## 수정 대상 파일이라는 다른 이름으로 존재했다. 폴더명과 섹션명을 통일하면서 전체 검색이라는 예외 규칙도 제거했다.

docs/*/backlog/*.md  ->  ## 변경 파일  ->  본문에서 변경 파일 경로 추출

실행할 때 기능명이나 갱신할 문서 목록을 미리 정답처럼 주지 않았다.

/pr-business-docs Target product부터

문서 이름을 직접 지정하면 Skill이 같은 Service 메서드를 공유하는 다른 진입점을 찾지 않고 사람이 준 범위에 머물 가능성이 있기 때문이다. 사람이 주는 것은 시작 범위이고, 최종 문서 선정은 diff와 호출 관계를 기준으로 하게 했다.

실행 초반부터 예상하지 못한 문제가 나왔다. 저장소의 기본 브랜치가 오래된 상태라 base...HEAD로 비교하면 다른 변경까지 200개가 넘는 파일이 잡혔다. 실제 작업 내용은 아직 커밋하지 않은 워킹트리의 변경 파일 8개였다.

Skill에는 판정한 비교 기준을 출력해 사용자 확인을 받는 절차가 있었고, 그 절차가 여기서 작동해 멈췄다. 이번 실행에서는 워킹트리 변경을 기준으로 다시 진행했다.

그 결과 하나의 상품 호출 체인에서 business 문서 11개가 대상으로 선정됐다.

  • 신규 문서 2개
  • 기존 문서 갱신 9개
  • REST, Kafka, Retry 진입점 포함

수동 확인에서는 가격 Retry 하나만 찾았지만 Skill 실행에서는 등록, 재고, 가격 Retry 세 개가 모두 기존 처리에 남아 있는 것을 찾았다.

이 결과만 보면 Skill이 의도대로 범위를 확장했다고 볼 수 있었다.

첫 초안은 정확하지 않았다

문제는 문서를 작성한 다음에 나왔다.

Skill이 만든 Kafka 문서 초안에는 5xx 응답이 발생하면 Retry 토픽으로 재전송한다고 적혀 있었다. 저장을 위해 기존 파일을 여는 순간 충돌이 드러났다. 기존 문서에는 재전송 코드가 있지만 필요한 필드가 주석 처리돼 실제로는 재전송되지 않는다고 적혀 있었다. Agent가 코드를 다시 확인하니 기존 문서가 맞았다. 초안은 남아 있는 코드 모양만 보고 쓴 것이다.

기존 문서에 있던 내용도 일부 사라질 뻔했다.

  • 중복 상품의 일부 큐가 ING 상태에 남을 수 있는 조건
  • 가격 변경 이후 수행되는 후처리
  • 여러 옵션을 처리해도 마지막 응답만 반환되는 동작

원인은 당시 규칙에 있었다. 규칙은 선정된 문서의 전면 재작성을 요구했지만, 파일 전체의 근거를 읽으라는 짝이 되는 조항은 없었다. 그래서 변경된 코드만 읽고 문서 전체를 다시 쓰면서, 이번 diff가 건드리지 않은 기존 동작이 추정으로 채워졌다. 이 짝을 규칙에 명시하면 변경된 부분만 읽고 전체를 재작성하는 오류를 줄일 수 있다.

전면 재작성은 기존의 잘못된 설명을 고칠 수 있다는 장점이 있다. 실제로 기존 문서의 옵션값 위치가 코드와 다르게 적혀 있던 것도 이번에 발견했다. 하지만 전체 근거를 읽지 않은 전면 재작성은 검증된 내용을 지우고 추정한 내용을 채운다.

이번에는 두 규칙이 저장 전에 문제를 잡았다.

  • 모든 문장은 근거가 되는 코드 위치를 확인한다. 이번 diff가 건드리지 않은 영역의 문장에 댈 근거가 없어서, Agent가 해당 코드를 읽으러 가게 만들었다.
  • 초안을 바로 저장하지 않고 먼저 보여준 뒤 확정한다. 저장 전에 기존 파일을 다시 열게 되면서 초안이 기존 문서보다 얇다는 것과 서술이 충돌한다는 것이 드러났다.

이번 사건을 흐름으로 정리하면 이렇다.

잘못된 초안을 저장 전 검증에서 발견한 흐름

결과적으로 Skill이 처음부터 정확한 문서를 만든 것은 아니었다. 영향 범위는 예상보다 넓게 찾았지만, 문서 초안에는 실제 동작과 다른 내용이 있었다.

이 경험으로 무조건 전면 재작성이라는 규칙 자체를 다시 보게 됐다. 한 번 검증을 거친 문서는 전면 재작성 대신 변경이 닿은 부분만 수정하는 쪽으로 진행할 생각이다. 전면 재작성은 옵션값 사례처럼 기존 오류를 고치는 힘이 있지만, 그 힘은 전체 근거 읽기라는 비용과 위험을 함께 요구한다. 이미 검증된 문서에서 그 비용을 매번 치를 이유는 없다.

무엇이 달라졌나

이번 작업으로 개발 속도가 빨라졌다고 말하기는 어렵다. 규칙을 정리하고, 수동으로 확인하고, Skill을 만든 뒤, 다시 문서를 검토하는 데 적지 않은 비용이 들었다.

확인된 효과는 다른 쪽에 있다.

이전 방식 Skill 적용 후
개발자가 기억나는 문서를 선택 diff와 호출 관계로 대상 문서 확장
변경 파일 중심으로 확인 공유 Service를 따라 REST, Kafka, Retry까지 확인
새 세션에서 절차를 다시 설명 저장소의 규칙과 Skill로 절차 전달
코드와 문서 갱신이 분리 PR 시점에 실제 구현 결과와 문서를 다시 대조

business 문서를 만드는 목적은 문서 산출물을 늘리는 것이 아니다. Agent가 같은 레거시 로직을 매번 처음부터 분석하지 않도록 현재 동작을 짧게 남겨두는 것이다.

그러려면 문서가 오래된 상태로 남지 않게 해야 한다. 이번 Skill은 그 문서를 생성하는 도구라기보다, 어떤 문서가 이번 변경으로 오래됐는지 찾는 절차에 가깝다.

아직 판단하지 못한 것

현재 기록만으로는 이 방식의 전체 비용이 이득이라고 결론내리기 어렵다.

이전 실험에서는 business 문서를 읽을 때 분석 비용이 줄어드는 결과가 있었다. 이번에는 문서를 최신 상태로 유지하는 과정이 실제로 작동하는지 확인했다.

하지만 이번 비용에는 규칙 정립, Skill 제작, 첫 실행이 섞여 있다. 세션 전체로는 약 $12.35가 나왔지만 Skill 단독 비용이 아니다. 일반적인 PR에서 Skill 실행과 문서 검토만 어느 정도 비용이 드는지는 아직 분리해서 측정하지 못했다.

확인된 비용 구조는 하나 있다. 출력 토큰의 상당 부분은 같은 문서를 두 번 방출한 비용이었다. 초안을 먼저 보여주고 확정 후에 저장하기 때문이다. 검증 게이트의 가격인 셈인데, 이번에는 그 게이트가 실제 오류를 잡았다. 그리고 business 문서는 아직 git에 추적되지 않아 잘못 저장하면 되돌릴 수단이 없다. 게이트를 줄이려면 먼저 문서를 git에 넣어 안전망부터 만들어야 한다.

문서 갱신 방식도 남아 있다.

  • 기존 규칙 적용 전 문서는 전체 코드 기준으로 다시 작성할 것인가
  • 검증된 문서를 변경 부분만 수정하는 방식이 실제로 정보 손실 없이 반복되는가. 방향은 정했지만 아직 이 방식으로 실행해보지 않았다.
  • 전체 재작성이 필요하다고 판단했을 때 어디까지 사용자 확인을 받을 것인가
  • @Deprecated처럼 동작은 그대로인데 의미가 바뀐 변경을 갱신 대상으로 볼 것인가. 이번에는 규칙이 가르지 못해 사용자 확정으로 포함시켰다.

판단을 없애려고 복잡한 메타데이터와 템플릿을 추가하면 business 문서 자체가 또 다른 관리 시스템이 될 수 있다. 현재는 문서 형식을 크게 늘리기보다, 기존 내용을 폐기하는 전체 재작성만 사용자에게 이유를 보여주고 확인받는 정도가 현실적으로 보인다.

commit과 push까지 묶는 것도 아직 실행하지 않았다. 우선 문서 선정과 갱신이 안정적으로 반복되는지 더 확인한 뒤 붙이는 편이 낫다고 판단했다.

이 방식이 필요 없어지는 순간

이 고민은 Agent가 같은 코드를 반복해서 탐색하며 쓰는 토큰과 시간을 줄이자는 데서 시작했다.

하지만 AI의 코드 탐색 능력이 계속 좋아지고 토큰과 도구 호출 비용이 낮아진다면 전제가 달라질 수 있다.

문서 생성 + 검증 + 갱신 비용
>
Agent가 필요할 때 코드를 다시 탐색하는 비용

이 관계가 된다면 business 문서를 별도로 유지할 이유는 줄어든다. 문서를 만드는 순간부터 코드와 달라질 가능성이 생기고, 최신 상태를 유지하기 위한 절차도 필요하기 때문이다. 그 비용보다 Agent가 매번 실제 코드를 다시 읽는 비용이 더 싸고 정확하다면 재탐색을 허용하는 편이 단순하다.

그래서 이 방식을 장기적인 정답으로 보지는 않는다. 현재처럼 레거시 호출 흐름이 길고, 같은 영역을 여러 세션에서 반복해서 분석하며, 재탐색 비용이 큰 환경에서 사용할 수 있는 최적화에 가깝다. AI가 충분히 싸고 빠르게 전체 근거를 다시 확인할 수 있게 되면 이 문서와 Skill은 사용하지 않아도 된다.

중요한 것은 문서를 계속 유지하는 일이 아니라, 그 시점에 더 저렴하고 안전한 분석 시작점을 선택하는 것이다.

business 문서는 영구적인 자산이 아니라, 코드 재탐색 비용이 문서 유지 비용보다 비싼 동안 사용하는 캐시다.

첫 실행에서 확인한 것

이번 실험으로 확인한 것은 제한적이다.

  1. 규칙과 Skill을 통해 별도 세션에도 탐색 절차를 전달할 수 있었다.
  2. 변경 파일만 봤을 때 놓칠 수 있는 다른 진입점과 Retry 흐름을 추가로 찾았다.
  3. 검색이 0을 반환한 것을 Agent가 없다고 결론내는 판정 오류가 있었다. 존재는 이름이 아니라 역할로 확인해야 했다.
  4. Agent가 만든 첫 문서 초안은 정확하지 않을 수 있었고, 저장 전 코드 근거 확인이 실제 오류와 정보 손실을 막았다.
  5. business 문서를 유지하는 비용이 장기적인 분석 절감보다 작은지는 아직 알 수 없다.

처음 기대했던 것은 PR이 끝날 때 business 문서를 자동으로 갱신하는 간단한 Skill이었다. 실제로 해보니 어려운 부분은 작성이 아니라 그 앞뒤에 있었다.

business 문서를 다음 작업의 분석 시작점으로 남기는 흐름은 만들 수 있었다. 다만 그 문서를 안전하게 갱신하려면 Agent의 작성 능력보다 영향 범위 탐색과 저장 전 검증 절차가 더 중요했다.

공개용 규칙과 Skill

이 시리즈에서 사용한 작업 등급 규칙과 두 개의 Skill을 공개용으로 정리했다.

  • sdd-doc-scaffold: SDD 문서 골격 생성
  • pr-business-docs: PR 전 business 문서 갱신

실제 프로젝트의 경로와 업무 식별자는 제거했고, 각 Skill을 독립적으로 가져다 쓸 수 있도록 참조 규칙을 함께 묶었다.

agent-sdd-kit 저장소 보기

아직 반복 검증하지 못한 부분과 적용 범위는 저장소 README에 따로 적어두었다.