에이전트 여러 개가 같은 코드베이스에서 병렬로 작업하면, 코드가 읽기 쉬운지만큼 여러 변경을 충돌 없이 합칠 수 있는지도 중요해진다. 이 글은 공용 파일에 변경이 몰리지 않도록 모듈 경계를 분명히 하고, 각 변경의 범위를 작게 만드는 것이 도움이 된다고 주장한다.
기존의 클린 코드 원칙은 사람이 파일을 읽고 수정하는 상황을 주로 고려했다. 하지만 에이전트가 많아지면 한 파일의 가독성만으로는 부족하다. 여러 변경이 같은 파일, 특히 같은 위치에 모이면 Git 충돌이 늘어난다. 예를 들어 에이전트 10개가 같은 목록 끝에 한 줄씩 추가할 경우, 첫 변경이 합쳐진 뒤 나머지가 차례로 충돌하면 마지막 변경이 반영되기까지 최대 45번의 리베이스와 CI 재실행이 생길 수 있다고 글은 설명한다.
변경이 계속 덧붙는 CHANGELOG 같은 파일에는 .gitattributes에 merge=union을 설정해 양쪽 내용을 모두 유지하는 방법이 있다. 더 넓은 해결책으로는 경로를 처리기 옆에서 선언하고, 이벤트는 이를 발생시키는 모듈에 두며, 변경 기록은 변경마다 별도 파일로 저장한 뒤 릴리스 때 모으는 방식을 제시한다. 이렇게 하면 기능 두 개가 같은 파일을 수정할 가능성을 줄일 수 있다.
텍스트 충돌 없이도 문제가 생길 수 있다. 한 에이전트가 함수 이름을 바꾸는 동안 다른 에이전트가 이전 이름을 사용하는 코드를 추가하면, 두 변경은 각각 검사를 통과하고 Git에서도 충돌하지 않을 수 있지만 합친 결과는 깨진다. 글은 이를 막으려면 타입 검사와 테스트를 통합 결과에 실행하는 병합 대기열이 필요하다고 본다.
모듈 간에는 내부 구현이 아니라 기계가 확인할 수 있는 약속이 있어야 한다. 타입 시그니처, 스키마, 테스트가 포함된 공개 인터페이스가 그 예다. 명시적 계약은 에이전트가 추측에 의존하지 않게 하고, 작은 인터페이스는 작업 전에 읽어야 할 맥락도 줄인다. 계약 위반을 타입 검사로 빠르게 잡으면 병합 단계에서 문제를 발견할 수 있다는 설명이다.
글은 한 모듈을 수정해 기능 하나를 더하고 자체 검사를 통과한 변경은 별도 조율 없이 병합하기 쉽다고 본다. 반대로 여러 모듈을 건드리는 변경은 진행 중인 다른 작업과 순서를 조정해야 할 수 있다. 따라서 에이전트가 병렬로 작업하는 환경에서는 작은 변경이 충돌 가능성을 낮추는 효과가 가독성이나 검토 편의성만큼 중요해진다는 주장이다.
다만 공유 파일을 어디까지 나눠야 사람이 탐색하기 어려워지지 않는지, 충돌률을 코드베이스의 건강 지표로 삼을 수 있는지는 열린 질문으로 남긴다. 클린 코드 원칙의 효과에 관한 연구도 함께 소개한다. 트리베디와 슈미트(Trivedi and Schmitt)의 Claude Code 실험 660회에서는 깔끔한 저장소와 복잡한 저장소 사이에 통과율 차이가 없었지만, 깔끔한 쪽은 입력 토큰을 7.1% 적게 쓰고 다시 살펴본 파일도 34% 적었다. 보르그(Borg) 등의 연구에서는 Code Health 점수가 9 이상인 파일을 오픈 모델이 리팩터링할 때 오류가 덜 발생했지만, Claude Code에서는 그 차이가 유의미하지 않았다. 글은 이 결과를 독립적인 결론이 아닌 자신의 근거 해석으로 제시한다.
또한 Claude Code 실험에서 핵심 로직은 그대로 둔 채 주변 헬퍼 함수를 추출한 정리는 에이전트 입력 토큰을 8% 늘렸다. 글은 확장성을 위해 추가한 간접 구조가 맥락 비용을 키울 수 있다고 지적하면서도, 클린 코드 원칙의 상당수는 여전히 유효하다고 본다. 현재의 판단 기준을 정리한 저장소 making-code-agent-friendly는 병렬 작업에서 충돌할 지점을 찾고, 변경 사항을 검토하며, 수정할 가치가 있다고 판단한 문제를 리팩터링하는 데 쓰인다고 소개한다.
관련 자료: Code Quality Still Matters, explicit over implicit, the harness around the agent, Humans Out of the Loop, Trivedi and Schmitt 연구, Borg et al. 연구.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요