레거시 코드에서 에이전트용 명세를 복원하는 방법

코드에서 명세를 복원해야 하는 이유

Reversa는 레거시 코드베이스에서 코딩 에이전트가 소비할 명세를 역추출하는 다중 에이전트 프레임워크다. 문서가 없는 코드에 에이전트를 투입하면, 전체를 읽고도 의도를 잘못 짚는 일이 반복된다. 사람이 문서를 새로 작성하는 방식은 비용이 크고 최신성을 유지하기도 어렵다.

그래서 문제의 중심은 문서 작성 인력의 확보가 아니라 자동 명세 복원으로 옮겨간다. 코드에 남아 있는 구조와 제약을 규격으로 굳히면 에이전트는 추측보다 참조에 기반해 수정할 수 있다. 다만 자동 추출 결과는 코드의 흔적을 옮긴 것일 뿐, 그것이 실제 설계 의도와 일치하는지는 별도로 검증해야 한다.

진입점에서 시작해 명세의 뼈대를 세운다

명세는 API 핸들러, 배치 잡, 이벤트 구독처럼 외부 요청이 코드로 들어오는 진입점부터 잡는다. 진입점은 곧 명세의 목차가 된다. 모듈부터 정리하면 무엇이 중요한지 판단할 기준이 없어진다.

진입점에서 호출 그래프를 추출해 어떤 모듈을 어떤 순서로 통과하는지 기록한다. 정적 분석이 놓치는 동적 호출과 리플렉션 구간은 별도로 표기해야 한다. 누락된 경로를 존재하지 않는 경로로 취급하면 명세는 눈에 띄지 않게 틀어진다.

그 위에 코드 속 명사를 모아 도메인 용어 사전을 만든다. 같은 대상을 가리키는 서로 다른 이름을 통합하지 않으면 에이전트가 하나의 개념을 다른 개념으로 취급해 수정 범위를 잘못 잡을 수 있다.

모듈 책임은 맡는 일뿐 아니라 맡지 않는 일까지 짧게 적는다. 에이전트의 오작동은 잘못된 모듈에 코드를 넣는 형태로 나타나는 경우가 많다.

검증 코드, 예외 처리, 방어 조건에서는 불변 조건 후보를 뽑는다. 이 후보는 확정된 규칙이 아니라 검토 대상이다. 코드에 남은 조건이 설계 의도인지 임시 방편인지는 코드만으로 판단할 수 없다.

⤢✕

신뢰도와 검수 경로를 명세에 포함한다

명세 항목에는 정적 분석 확정, 추론, 미확인의 세 등급을 붙인다. 등급이 없으면 모든 항목이 같은 무게로 읽히고, 추론이 확정 사실처럼 소비될 때 오류가 증폭된다.

검수자가 항목을 수정했다면 그 피드백은 다음 추출에 반영돼야 한다. 검수 우선순위는 신뢰도와 변경 빈도로 정한다. 전량 검수를 전제하면 절차가 시작되지 않는다.

코드가 바뀌면 변경 파일과 연관된 명세 항목을 찾아 재추출 대상으로 올리고, 갱신되지 않은 항목에는 오래됨 표시를 붙인다. 최신 여부를 알 수 없는 명세는 없는 명세보다 위험하다.

도입 범위를 좁혀 검증 가능한 상태로 시작한다

변경 요청이 잦고 사고가 반복되는 모듈부터 선택하면 명세의 효용을 빨리 확인할 수 있다. 곧 폐기될 모듈은 제외한다. 사라질 코드의 명세를 만드는 비용은 회수되지 않는다.

에이전트가 읽는 형식과 사람이 읽는 형식은 같은 원본에서 만들어야 한다. 두 벌을 따로 작성하면 결국 어긋난다. 항목 구조도 고정해야 한다. 형식이 흔들리면 에이전트는 참조 위치를 찾지 못하고 다시 전체 코드를 읽게 된다.

모듈별 검수 책임자를 정하고 검수에 필요한 시간을 업무로 인정한다. 담당자가 없는 모듈의 명세는 추론 등급으로 고정한다. 검수 없는 내용을 확정으로 올려서는 안 된다.

추출 명세의 표본을 실제 코드 동작과 대조하는 절차는 정기로 운영한다. 오류 유형을 분류해 추출 규칙에 반영해야 개선 방향이 나온다. 오류율만으로는 무엇을 고쳐야 하는지 알 수 없다.

명세는 대상 커밋과 함께 버전 관리해 어느 시점의 코드를 설명하는지 분명히 한다. 코드 저장소와 같은 위치에 둘지, 분리할지도 정해야 한다. 분리하면 갱신 누락이 생길 수 있고, 함께 두면 리뷰 부담이 늘어난다.

병합 시점에는 영향 명세 항목을 표시하고 일정 규모 이상 변경에는 재추출을 요구한다. 오래됨 표시가 일정 기간 방치된 항목은 에이전트 참조 대상에서 제외한다. 명세 형식 변경과 신뢰도 등급 기준 조정은 승인 대상으로 관리하며, 정확도 표본 검증 결과도 정기 보고 항목으로 편성한다.

자동 추출과 사람 문서화가 맡는 영역

구분	자동 명세 역추출	사람 작성 문서화
확보 속도	빠름	느림
의도 반영도	낮음	높음
커버리지	넓음	좁음
최신성 유지	자동 갱신 가능	방치되기 쉬움
오류 성격	그럴듯한 오류	누락 위주
초기 비용	낮음	높음

자동 명세 역추출은 수십만 줄 규모에서도 며칠 안에 전체 커버리지를 확보하고, 코드 변경 시 재추출로 최신성을 유지할 수 있다. 담당자가 떠난 모듈에도 적용할 수 있다. 반면 코드에 남은 흔적만 읽기 때문에 왜 그렇게 만들었는지에 해당하는 의도는 빠진다. 임시 방편을 설계 원칙으로 승격시키는 오류도 생길 수 있으며, 문법적으로 그럴듯해 검수 없이는 걸러지지 않는다.

사람이 작성한 문서는 의도, 배경, 폐기 예정 사실처럼 코드에 없는 정보를 담을 수 있다. 잘못 작성돼도 대개 누락으로 나타나 오해를 덜 유발한다. 그러나 작성 비용 때문에 일부 모듈만 문서화되기 쉽고, 코드 변경을 따라가지 못해 빠르게 낡는다. 원저자가 조직을 떠나면 복원 자체가 어려워진다.

자동 추출로 뼈대를 만들고, 의도가 중요한 항목에만 사람의 설명을 더하는 순서가 두 방식의 비용 구조를 나눈다.

전체 일괄 추출은 모듈 간 관계와 호출 경로를 한 번에 보여 주고, 용어 불일치도 초기에 정리할 수 있다. 대신 초기 비용이 크고 검수되지 않은 명세가 대량으로 쌓이며, 추출 직후 코드 변경으로 일부는 곧바로 낡는다.

변경 영역을 점진적으로 추출하면 지금 손대는 코드만 다뤄 초기 비용이 작고, 검수가 실제 작업 맥락에서 이뤄져 품질이 높다. 명세도 최근 상태를 반영한다. 하지만 손대지 않는 영역에는 명세가 생기지 않아 커버리지가 편중되고, 모듈 간 관계를 보기 어려워 변경 영향 범위 판단에 도움이 되지 않는다. 진입점과 호출 그래프 같은 전역 뼈대는 일괄로 추출하고, 상세 항목은 점진적으로 채우는 이층 구성이 이 문제를 함께 줄인다.

다중 에이전트 분업은 호출 그래프, 용어 사전, 불변 조건처럼 성격이 다른 작업을 각각 특화된 절차로 처리한다. 항목별 정확도를 높이고 병렬 실행으로 대규모 코드베이스의 처리 시간을 줄이며, 한 역할의 실패가 다른 산출물을 오염시키는 일을 막을 수 있다. 대신 역할별 산출물이 서로 다른 전제를 가져 용어와 경계가 어긋날 수 있고, 이를 맞추는 통합 단계가 필요하다. 실행 비용도 여러 배로 늘어난다.

단일 에이전트 통합 추출은 하나의 맥락에서 전체를 다뤄 용어와 모듈 경계의 일관성을 유지하기 쉽고 구현과 비용이 단순하다. 그러나 컨텍스트 한계 때문에 대규모 코드베이스에서는 뒤로 갈수록 앞의 내용을 잊고, 중요한 부분의 정확도를 끌어올릴 수단도 부족하다. 코드 규모가 컨텍스트 한계를 넘어서면 분업의 일관성 비용을 감수하는 것이 실무적 판단 기준이 된다.

재공학·요구사항·형상 관리로 보는 명세 복원

코드에서 설계 정보를 복원하는 절차는 소프트웨어 재공학의 역공학에 대응한다. 진입점 식별과 호출 그래프 추출은 프로그램 이해 활동의 표준 단계다.

불변 조건 후보를 도출하는 일은 코드에 내재한 제약을 요구사항으로 재구성하는 활동이다. 명세 신뢰도 표기는 요구사항의 확정 수준을 드러내는 추적 가능성 요건과 같은 구조를 가진다.

대상 커밋과 함께 명세를 버전 관리하는 방식은 산출물 형상 식별의 기본 요건이다. 코드 변경 시 영향 항목을 표시하는 절차는 변경 영향 분석과 형상 항목 갱신에 해당한다.

코딩 에이전트가 참조할 명세의 변화

코딩 에이전트가 참조하는 명세 형식은 사실상 표준으로 수렴하고, 도구 간 호환이 논점으로 부상하는 방향이다. 명세 역추출은 레거시 현대화 프로젝트의 선행 공정으로 편성되는 흐름에 있다.

명세 신뢰도 등급 표기는 에이전트 참조 대상을 고르는 기준으로 자리 잡는 방향이며, 코드 변경과 명세 갱신을 연결하는 검사는 병합 절차의 필수 항목으로 요구되는 흐름이다.

문서 없는 코드에 에이전트를 붙일 때 필요한 최소 구성은 진입점과 호출 그래프, 용어 사전, 신뢰도 등급, 변경 시 오래됨 표시다. 코드의 흔적을 명세로 옮길 수 있어도 그 이유와 의도는 여전히 사람의 검수 영역에 남는다. 오래됨 표시가 방치된 명세는 참조 대상에서 제외하는 규칙까지 있어야 이 구조가 실제로 작동한다.