Claude Code와 실시간 음성 AI를 개발하면서, 어떤 결단에 도달했다——인간은 코드를 읽지 않는다. 읽는 것은 AI이며, 인간은 도식과 의도를 가진다. 이 분업을 성립시키기 위해 했던 일을 공유한다.

도식을 draw.io가 아닌 Mermaid로 쓰는 이유

"구조를 UML로 그려줘, 코드는 읽지 않을 거니까"라고 부탁했더니, AI의 제안은 draw.io가 아닌 Mermaid(텍스트 작도 기법)였다. 이유는 3가지:

• GitHub가 README나 Markdown 내에서 자동으로 렌더링한다
• 텍스트이므로
  PR에서 차이(diff)를 리뷰할 수 있다 - AI가 생성·갱신할 수 있다 =
  구현을 변경하는 PR에 도식 업데이트를 동봉할 수 있다

도식은 코드와 마찬가지로, 현실과 어긋나는 순간 가치가 마이너스가 된다. draw.io의 XML은 차이를 읽을 수 없어 업데이트가 번거로워지고, 확실히 부패한다. Mermaid라면 코드와 동일한 리뷰의 장(場)에 올라탈 수 있다.

docs/architecture.md

에 6장의 도식(전체상, 중계 서버의 2루프 구조, PTT의 1턴, function calling의 전표 플로우, 인증, 재연결의 상태 전이)을 배치하고, "구현을 변경하는 PR에서는 해당 도식도 업데이트한다"를 운영 규칙으로 정했다.

실제로 이후의 PR에서, 코드를 읽지 않는 인간이 도식을 보고 "Responses API도 OpenAI니까, OpenAI임을 알 수 있도록 테두리를 치는 게 좋겠다"라고 설계의 모호함을 지적했고, AI가 도식과 코드를 수정했다. 분업이 돌아가기 시작한 순간이었다.

리팩터링(Refactoring)은 "트리거(Trigger)"를 정해두고 미룬다

522행으로 성장한 main.py를 7개 모듈(조립/설정/인증/중계 본체/페르소나/이력/검색)로 분할했다. 흥미로운 점은, 이 분할을 처음부터 하지 않았다는 것이다.

당초 "분할할 필요가 있을까?"라고 물었을 때, AI의 대답은 "지금은 없다. 트리거(두 번째 툴 추가·800행 초과·공동 개발자의 등장)를 정해두고, 그때까지는 건드리지 마라"였다. 리팩터링은 "읽기 어려워 곤란해진 실적"이 나온 뒤에 하는 것이 가장 비용이 적게 든다. 이번에는 다음 기능(WebRTC 구현)을 위한 사전 준비로서 발동되었다.

동작을 1mm도 바꾸지 않는 순수 리팩터링이지만, 검증은 모든 경로에 대해 E2E(인증·WebSocket·실제 음성 왕복)로 진행했다. 순수 리팩터링이야말로 회귀(Regression)가 무섭다.

규칙은 감정이 아니라 설정으로 지킨다

docs만 수정하는 것을 PR 없이 master에 직접 커밋(Direct Commit)하는 운영을 했을 때, 예전에 비슷한 일을 했다가 Slack에서 30줄에 걸쳐 질책받았던 기억이 떠올랐다.

지금 생각하면 그것은 프로세스의 결함이었다. master로의 직접 커밋이 그렇게 중대하다면, 브랜치 보호(Branch Protection, GitHub 설정 하나)로 물리적으로 불가능하게 만들 수 있다. 그것을 하지 않고 인간의 자제심에 맡긴 뒤, 규칙이 깨지면 감정적으로 질책하는 것은 "기계가 막아야 할 일을 인간을 비난하며 해결하려는" 행위다. 포카요케(Poka-yoke) 사상——지나갈 수 있는 문을 열어두고, 지나간 사람을 꾸짖는 것은 문 설계자의 패배이다.

그리하여 운영은 다음과 같이 되었다: 개인 리포지토리는 "동작이 바뀌면 PR, docs는 직접 커밋"하는 하이브리드 방식. 공유 리포지토리를 갖게 되는 날이 오면, 첫날에 브랜치 보호를 적용한다.

개발기의 전체 내용은 본래 블로그에서 확인하세요:

Discussion