코드는 계속 바뀌는데 문서는 언제 갱신할까: 릴리즈 수동·CI 정기·MR 트리거

지난 글에서 acquire-codebase-knowledge 스킬로 낯선 코드베이스를 docs/codebase/의 7개 문서로 정리하는 방법을 다뤘습니다. 스킬을 한 번 돌리고 나면 자연스럽게 따라오는 질문이 있습니다. 코드는 매주 바뀌는데 이 문서는 언제 다시 만들어야 할까? 한 번 만든 문서를 방치하면 며칠 만에 현실과 어긋나기 시작합니다. 그리고 어긋난 문서는 없느니만 못합니다. 앞 글에서 짚었듯 팀 전체가 틀린 지도를 들고 개발하게 되기 때문입니다.

모던웹연구소가 실제로 써보며, 고객사들과 소통하며 정리한 갱신 방식은 세 가지입니다. 결론부터 말하면 셋 중 하나를 고르는 문제가 아닙니다. 손으로 돌리는 ①로 시작해 정기 자동화인 ②를 얹고, ③은 문서를 다시 만드는 용도가 아니라 어긋남을 잡아내는 검사로 쓰는 조합이 현실적입니다. 아래에서 자동화 정도가 낮은 것부터 하나씩 살펴봅니다. 예시는 GitLab 기준이지만 원리는 다른 CI에도 그대로 옮길 수 있습니다.

① 릴리즈 주기 수동 갱신

가장 단순한 방식은 릴리즈 체크리스트에 한 줄을 더하는 것입니다. '스킬 재실행 후 변경분을 MR로 올린다' 정도면 충분합니다. 릴리즈를 준비할 때 acquire-codebase-knowledge를 다시 돌리고, 새로 생성된 문서와 기존 문서의 diff를 눈으로 확인한 뒤 MR로 병합합니다.

이 방식의 장점은 검증이 항상 사람 눈을 거친다는 점입니다. 에이전트가 새로 쓴 문서를 개발자가 diff로 확인하니 엉뚱한 내용이 그대로 들어갈 일이 없습니다. 대신 두 가지 약점이 있습니다. 릴리즈와 릴리즈 사이에 벌어진 어긋남은 다음 릴리즈까지 방치됩니다. 그리고 체크리스트의 항목은 바쁠 때 가장 먼저 잊힙니다. 도입 초기, 아직 문서를 팀이 신뢰하기 전 단계에 알맞은 방식입니다.

사람 없이 돌리는 한 줄, claude -p

아래 ②③을 이해하려면 부품 하나를 먼저 알아야 합니다. 바로 claude -p입니다. Claude Code 대화 안에서 앞에 !를 붙여 !ls처럼 치는 것은 '대화 세션 안에서 셸 명령을 실행'하는 것입니다. 반대로 claude -p "..."는 셸에서 Claude Code를 한 번 호출합니다. 대화형으로 창을 열지 않고 한 번 묻고 답을 출력한 뒤 그대로 끝나는 비대화형 모드입니다.¹ 문서에는 headless 모드라고 부르고, 스크립트와 CI 파이프라인에 넣으라고 안내합니다.

직접 감을 잡고 싶다면 터미널에 claude -p "다음 문장을 한국어로 번역해줘: hello world"를 한 번 쳐보길 권합니다. 창이 열리지 않고 답만 출력되고 끝나는 걸 보면 됩니다. 아래 두 방식은 이 한 줄을 CI가 대신 실행하게 만드는 것뿐입니다.

② CI 정기 잡으로 자동 재생성

GitLab의 Pipeline Schedules 기능으로 파이프라인을 주기적으로 돌릴 수 있습니다. 예를 들어 매주 월요일 새벽에 문서를 다시 생성하고, 변경이 있으면 자동으로 MR을 만들게 합니다. 사람은 올라온 MR을 리뷰만 하면 됩니다.

# .gitlab-ci.yml — 주 1회 문서 재생성 (주기는 Pipeline Schedules에서 설정)
docs-refresh:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  script:
    - claude -p --permission-mode acceptEdits "acquire-codebase-knowledge 스킬로 docs/codebase/ 문서를 다시 생성해줘"
    - |
      if ! git diff --quiet; then
        git checkout -b "docs/refresh-$CI_PIPELINE_ID"
        git add -A
        git commit -m "docs: refresh codebase knowledge"
        git push origin "docs/refresh-$CI_PIPELINE_ID"
        glab mr create --fill --yes
      fi

동작 순서를 풀면 이렇습니다. rules의 $CI_PIPELINE_SOURCE == "schedule"은 이 잡을 예약 실행에서만 돌게 묶는 조건입니다.² claude -p로 스킬을 돌려 문서를 다시 쓰고, git diff --quiet로 실제로 바뀐 게 있는지 확인합니다. 이 명령은 변경이 있으면 실패 코드를 돌려주므로 if ! git diff --quiet가 곧 '바뀐 게 있으면'이라는 조건이 됩니다. 바뀐 게 있을 때만 브랜치를 파서 커밋·푸시하고 glab mr create로 MR을 엽니다. 변경이 없으면 아무 일도 하지 않습니다.

무인 실행이라 챙길 게 하나 있습니다. 파이프라인에는 사람이 없으니 권한 프롬프트가 한 번이라도 뜨면 그 자리에서 멈춥니다. 그래서 --permission-mode acceptEdits로 파일 수정을 자동 승인하게 했습니다. scan.py 실행처럼 셸이 필요한 도구는 --allowed-tools로 미리 열어둬야 합니다.

③ MR 트리거로 어긋남만 잡기

세 번째는 MR이 올라올 때마다 도는 방식입니다. 다만 MR마다 문서 전체를 재생성하면 diff 노이즈와 토큰 비용이 지나치게 커집니다. 그래서 이 자리에서는 claude -p를 문서를 다시 쓰는 용도가 아니라 '불일치 검사'로 씁니다. '이 MR의 diff가 docs/codebase/ 문서와 어긋나는 부분이 있으면 파일·라인과 함께 지적해줘'라고 시키고, 그 결과를 MR 코멘트로 남깁니다.

# .gitlab-ci.yml — MR마다 문서 불일치 검사
docs-drift-check:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - |
      claude -p --permission-mode plan \
        "이 MR의 변경이 docs/codebase/ 문서와 어긋나는 부분이 있으면 파일·라인과 함께 짚어줘. 없으면 OK만 출력해줘." \
        > drift.md
    - glab mr note "$CI_MERGE_REQUEST_IID" --message "$(cat drift.md)"

--permission-mode plan은 에이전트가 파일을 고치지 못하게 묶습니다. 문서를 다시 쓰는 게 아니라 읽고 지적만 하는 검사라 이 모드가 맞습니다. 이 방식의 장점은 어긋남이 생기는 바로 그 순간에 잡힌다는 점입니다. 문서를 실제로 고치는 일은 사람이 ①이나 ②의 흐름으로 처리합니다. ③은 '지금 이 변경이 문서와 어긋난다'고 알려주는 역할까지만 맡습니다.

세 방법 비교

정리

세 방법 중 하나를 고르는 문제가 아니라 순서의 문제입니다. 처음부터 ②③을 걸어두면 아무도 읽지 않는 자동 MR과 코멘트만 쌓입니다. 먼저 ①로 문서를 손수 갱신하며 이 문서가 쓸모 있다는 경험을 만듭니다. 손으로 돌리기가 귀찮아질 무렵 ②로 정기 재생성을 자동화합니다. 그리고 팀이 이 문서에 진짜로 의존하기 시작했을 때 ③으로 어긋남을 실시간으로 잡습니다. 문서에 대한 팀의 신뢰가 자라는 만큼 자동화 수준을 한 단계씩 올리는 셈입니다.

세 방식 모두 밑바탕은 claude -p 한 줄입니다. 대화 세션에 사람이 앉아 있어야만 코딩 에이전트를 쓸 수 있는 게 아니라, CI 파이프라인이 대신 호출하게 만들면 문서 갱신 같은 반복 작업을 사람 손에서 떼어낼 수 있습니다. acquire-codebase-knowledge로 문서를 한 번 만드는 것이 시작이라면, 그 문서를 코드와 함께 살아 있게 유지하는 것은 이 세 방식의 몫입니다. 같은 claude -p로 문서 갱신을 넘어 릴리즈 노트 검수처럼 사람의 판단이 필요한 일까지 파이프라인에 맡기는 방법은 다음 글에서 다룹니다.

1. Anthropic, Claude Code CLI reference, Claude Code Docs.

   ↩

2. GitLab, CI_PIPELINE_SOURCE predefined variable, GitLab Docs.

   ↩