6.4아키텍처 문서화와 구현 가이드

일반적인 코드베이스에서도 문서는 낡습니다. LLM 시스템에서는 그 속도가 더 빠르고, 낡았을 때의 피해도 더 큽니다. 세 가지 이유가 있습니다.

첫째, 프롬프트가 코드처럼 관리되지 않습니다. 프롬프트 한 문장을 고치는 일은 코드 수정보다 가벼워 보여서, 리뷰 없이 반영되는 경우가 많습니다. 그 결과 시스템 프롬프트에는 왜 있는지 아무도 모르는 문장이 쌓입니다. 대개 과거의 어떤 실패를 막으려고 넣은 것인데, 이유가 기록되지 않아 다음 사람이 "군더더기"로 보고 지웁니다. 그리고 그 실패가 재발합니다.

둘째, 품질 판정의 근거가 사람 머릿속에 있습니다. "이 정도면 괜찮다"는 감각은 몇 달 동안 결과를 봐 온 사람에게만 있습니다. 인계받은 사람에게는 없습니다. 평가셋이 문서화되지 않으면, 새 담당자는 자신이 만든 변경이 좋아진 것인지 나빠진 것인지 알 수 없습니다.

셋째, 재현 조건이 여러 곳에 흩어져 있습니다. 모델 버전, 온도 같은 파라미터, 검색 인덱스의 스냅숏, 도구 정의가 각각 다른 곳에 있으면 "지난달과 같은 결과"를 만들 수 없습니다. 결과가 달라졌을 때 원인을 좁힐 수 없다는 뜻이기도 합니다.

이 세 가지가 겹치면 인계는 형식만 남습니다. 문서는 넘어갔지만 다음 사람이 아무것도 안전하게 바꿀 수 없는 상태가 됩니다.

구조도와 API 목록은 대개 잘 만들어집니다. 정작 빠지는 것은 다음 넷입니다.

1. 평가셋과 그 출처. 무엇으로 품질을 판정하는지, 그 사례들이 어디서 왔는지를 남깁니다. 사례마다 출처(운영 로그, 사용자 신고, 합성)를 표시해 두면 나중에 갱신할 때 어떤 것을 교체해도 되는지 판단할 수 있습니다. 이것이 넷 중 가장 중요합니다. 평가셋이 없으면 다른 세 가지가 있어도 변경을 검증할 수 없습니다.

2. 프롬프트 각 블록의 존재 이유. 시스템 프롬프트를 블록으로 나누고, 블록마다 왜 있는지를 한 줄로 붙입니다. 특히 특정 실패를 막으려고 넣은 문장에는 그 실패 사례를 함께 적습니다.

[출력 형식]  — 구조화된 출력으로 강제하므로 여기서는 예시만 든다
[금지 사항]  — 2026-03 사고: 사용자 요청 없이 환불 안내를 덧붙임. 아래 문장으로 차단
[어조]       — 상담팀 요청. 품질 지표와 무관하므로 자유롭게 수정 가능

이렇게 두면 다음 사람이 어디를 건드려도 되고 어디를 조심해야 하는지 알 수 있습니다.

3. 실패 사례 모음. 과거에 실제로 잘못된 입력과 출력을 원본 그대로 모아 둡니다. 요약하지 말고 원문을 남기는 편이 좋습니다. 요약하면 재현에 필요한 단서가 지워집니다.

4. 재현 절차. 모델 버전과 파라미터, 검색 인덱스 판본, 도구 정의를 한곳에 모아 고정합니다. "이 설정으로 이 입력을 넣으면 이 출력이 나온다"를 확인할 수 있어야 합니다.

이 넷을 갖추면 인계받은 사람이 첫 주에 할 수 있는 일이 생깁니다. 평가셋을 돌려 현재 점수를 확인하고, 작은 변경을 넣어 점수가 어떻게 움직이는지 보는 것입니다. 이것이 가능한 상태가 실질적인 인계 완료 지점입니다.

문서를 넘길 때 흔한 실패는 모든 것을 규정하려는 것입니다. 규정이 많으면 지켜지지 않고, 지켜지지 않는 규정은 문서 전체의 신뢰를 떨어뜨립니다. 강제할 것과 재량으로 둘 것을 구분하십시오.

성격	예	처리
어기면 사고가 나는 것	권한 범위, 개인정보 처리, 안전 필터	강제. 자동 검사로 막는다
어기면 품질이 내려가는 것	프롬프트 블록 순서, 캐시 접두부 구성	강제하되 이유를 적는다
팀 취향인 것	코드 구조, 로그 문구 형식	재량으로 둔다

강제는 문서가 아니라 장치로 거는 것이 원칙입니다. "이렇게 하지 마십시오"라고 적는 것보다 검사로 막는 편이 확실합니다. 권한 범위는 설정으로 제한하고, 안전 조건은 테스트로 걸고, 캐시 접두부 순서는 구성 코드에서 보장합니다. 문서에만 있는 규칙은 결국 지켜지지 않습니다.

팀에 넘기는 절차 자산도 함께 정리하십시오. Claude Code를 쓰는 팀이라면 저장소의 메모리 파일과 스킬이 여기에 해당합니다. 반복되는 작업 절차를 이런 자산으로 남기면, 문서를 읽지 않아도 절차가 따라옵니다. 다만 자산에 넣을 것과 문서에 남길 것을 구분해야 합니다. 절차는 자산으로, 판단의 근거는 문서로 남기는 편이 유지에 유리합니다.

구현 가이드에는 하지 않아도 되는 것도 적으십시오. 인계받은 팀이 가장 많이 하는 질문은 "이것도 해야 하나요"입니다. 범위 밖 항목을 명시하면 불필요한 작업과 문의가 함께 줄어듭니다.

문서 유지의 핵심은 부지런함이 아니라 구조입니다. 사람이 성실해야만 유지되는 문서는 반드시 낡습니다.

단일 출처를 정합니다. 같은 정보가 두 곳에 있으면 반드시 어긋납니다. 모델 버전이 설정 파일과 문서에 각각 적혀 있으면, 얼마 지나지 않아 다른 값이 됩니다. 문서에는 값을 적지 말고 어디를 보면 되는지를 적으십시오.

자동으로 만들 수 있는 것과 아닌 것을 나눕니다.

자동 생성 가능	사람이 써야 함
도구 목록과 스키마	도구를 그렇게 나눈 이유
현재 평가셋 점수	평가셋이 무엇을 대표하는지
모델과 파라미터 설정값	그 값을 고른 근거와 재검토 조건
의존성과 권한 목록	각 권한이 필요한 이유

왼쪽은 문서에 적지 말고 생성하십시오. 오른쪽만 사람이 관리하면 유지 부담이 크게 줄고, 낡을 여지도 그만큼 줄어듭니다.

검토 시점을 사건에 묶습니다. "분기마다 문서를 검토한다"는 규칙은 대체로 지켜지지 않습니다. 대신 이미 일어나는 사건에 붙이십시오.

• 모델을 바꿀 때 재현 절차와 결정 기록을 함께 갱신한다
• 평가셋을 갱신할 때 그 대표성 설명을 함께 고친다
• 사고가 났을 때 실패 사례 모음에 원문을 추가한다

마지막으로 문서의 첫 화면에 최종 검증 시점을 적으십시오. "이 문서는 2026-08-11에 평가셋 v3 기준으로 확인함"이라는 한 줄이 있으면, 읽는 사람이 어디까지 믿어도 되는지 스스로 판단할 수 있습니다. 낡은 문서보다 위험한 것은 얼마나 낡았는지 모르는 문서입니다.