서론

지난 기사에서는 Claude Code와 페어로 Wizardry 스타일의 3D 던전 RPG를 만들고 있는 이야기를 썼습니다. 이번에는 그 안에서 예고했던, 개발 운영의 핵심 이야기입니다.

AI 코딩 에이전트와 오랫동안 일해 본 사람이라면 아마 모두가 경험하고 있을 것입니다.

세션의 후반부로 갈수록 AI의 작업 품질이 떨어진다.

초반에는 매우 날카로웠는데, 2시간 뒤에는 분명히 정했던 사양을 잊어버린다. 테스트를 생략하기 시작한다. 요청하지 않은 파일까지 수정한다. 나는 이것을 「열화(劣化)」라고 부르고 있습니다.

이 기사는 열화와 정면으로 싸우는 것을 그만두고, **「1개 기능의 개발을 5단계(Phase)로 나누고, 단계마다 세션을 일회용으로 사용한다」**는 운영 방식으로 전환했더니 개발이 안정적으로 돌아가게 되었다는 이야기입니다. 약 1개월 반 동안 이 운영을 지속하여, 기능 단위의 머지(Merge) 40건 이상, 자동 테스트 1,808건 전원 통과(All Green)까지 도달했기에 재현 가능한 형태로 정리합니다.

열화는 왜 발생하는가

원인은 단순합니다, 바로 컨텍스트 윈도우(Context Window)의 비대화입니다.

AI와의 1개 세션은 대화, 읽은 파일, 도구의 실행 결과가 모두 문맥(Context)으로서 쌓여갑니다. 문맥이 비대해질수록 AI는 「지금 무엇이 중요한가」를 놓치기 쉬워집니다. 인간으로 치면 8시간 연속 회의의 종반부와 같은 상태입니다.

대책으로 가장 먼저 떠오르는 것은 「자주 요약하게 하기」, 「중요한 것을 반복해서 말하기」 정도이지만, 제 경험상 이들은 모두 연명책에 불과했습니다. 회의가 너무 긴 것이 문제라면, 회의를 짧게 나누고 의사록으로 잇는 것이 더 합리적입니다. 그것이 단계(Phase) 분할입니다.

AIの劣化とフェーズ分割によるリセット

1개 세션으로 계속 달리면 품질이 떨어진다. 단계 분할은 세션을 끊을 때마다 품질이 리셋된다

5단계의 내용

저희 개발의 기본 단위는 「슬라이스(Slice)」 — 「저장/로드(Save/Load)」, 「보물상자」와 같은 세로로 자른 기능 1개입니다. 1개 슬라이스를 다음 5단계로 나누고, 각 단계를 반드시 별도의 세션에서 진행합니다.

1スライス＝5フェーズ×別セッションの全体像

5단계의 전체상. 단계 말에 반드시 세션을 끊고, handoff 파일로 잇는다

포인트를 3가지 꼽겠습니다.

포인트 1: 단계 경계는 「끊고 싶은 곳」이 아니라 「끊어야 하는 곳」

단계의 경계점은 결과물의 전달 지점에 두고 있습니다. 사양서가 완성되었다(1→2), 구현이 끝났다(2→3), 인간의 테스트 대기 상태가 되었다(3→4). 모두 「여기까지의 문맥을 버려도, 결과물만 있다면 다음으로 진행할 수 있는」 지점입니다.

반대로 말하면, 결과물이 파일로 남지 않는 작업은 단계의 끝에 할 수 없습니다. 이 제약 덕분에 「사양서를 쓰지 않고 구현에 돌입하는」 것과 같은 AI의 폭주가 구조적으로 일어나지 않게 되었습니다.

포인트 2: 단계 3의 끝은 「인간 게이트(Human Gate)」로 강제 정지

자동 테스트가 모두 통과(All Green)되어도, 「조작감이 좋은가」는 기계가 알 수 없습니다. 단계 3의 끝에서 AI는 실기 테스트용 체크리스트를 작성하고 반드시 정지하며, 제가 실기로 플레이하여 ○×를 표시한 후에 단계 4가 시작됩니다.

인간의 테스트는 비동기 작업이므로, 여기서 세션이 끊기는 것은 오히려 자연스럽습니다. 운영에 인간의 생활 리듬을 편입시킨 형태가 되었습니다.

포인트 3: 무거운 단계는 도중에 끊어도 좋다

구현 태스크가 많은 슬라이스에서는 단계 2를 1개 세션으로 완주하려고 하면 바로 열화가 시작됩니다. 그래서 **「몇 개 태스크마다 완료 커밋의 SHA와 남은 태스크를 메모하고 도중에 세션을 끊어도 좋다」**라는 규칙을 만들었습니다 (2-a, 2-b라고 부르고 있습니다).

「1개 세션으로 끝내기」를 강제하지 않는 것이 컨텍스트 폭발에 대한 마지막 안전밸브입니다.

의사록의 정체: handoff 파일과 자동 주입

단계 분할의 생명선은 인수인계입니다. 세션을 끊을 때마다 기억은 제로가 되므로, 「어제의 AI와 오늘의 AI가 타인」인 문제를 시스템으로 해결해야 합니다.

저희는 docs/wip/<브랜치명>.md라는 「handoff 파일」에 다음 내용을 세션 말에 기록해 둡니다.

• 현재 페이즈 (다음 세션이 가장 먼저 확인하는 항목) - 완료된 작업과 커밋 SHA
• 미해결 과제 및 확정된 버그 리스트
• 함정 (환경적 함정, 하지 말아야 할 것)
• 다음 세션의 준비 사항

그리고 가장 중요한 것은, 이것을 AI에게 "읽어줘"라고 부탁하지 않는 것입니다. SessionStart 훅(세션 시작 시 자동으로 실행되는 스크립트)을 통해, handoff 파일의 전문과 워크플로우 문서를 강제적으로 AI의 문맥(Context)에 주입하고 있습니다. 부탁 기반의 운영은 AI가 읽고 지나치는 순간 붕괴하기 때문입니다.

결과적으로, 제가 다음 세션에서 말하는 것은 암호 하나뿐이 되었습니다.

"3D 던전 RPG의 다음을 계속하자!!"

AI는 handoff의 "현재 페이즈" 항목을 보고 "지금 페이즈 4네요, 확정된 버그 수정부터 재개하겠습니다"라며 즉시 움직이기 시작합니다. 이 재개의 매끄러움은 솔직히 조금 미래를 느끼게 합니다.

운영을 지속하며 추가한 규칙

운영을 시작한 후, 실제 사고를 겪으며 추가한 규칙이 몇 가지 있습니다. 실패담과 함께 소개합니다.

컨텍스트 예산 (문서가 너무 비대해지는 것에 대한 경고)

handoff나 로드맵은 내버려 두면 끝없이 비대해지며, 그 자체가 성능 저하의 원인이 됩니다. 그래서 주요 문서에 글자 수 예산을 정해두고, SessionStart 훅이 초과를 감지하면 "📏경고"를 띄워 해당 세션의 마지막에 반드시 내용을 쳐내는(Pruning) 운영 방식을 도입했습니다. 오래된 정보는 아카이브 파일로 퇴피시킵니다.

회의록이 너무 비대해지면 회의가 길어지는 것과 같다는 당연한 이야기지만, 기계가 감시하게 하지 않으면 인간도 AI도 게으름을 피웁니다.

사고 깊이(Reasoning Depth)의 5단계 지정

태스크의 무게에 맞춰 AI의 사고 깊이(Reasoning effort)를 "특소/중/대/초대/최대"의 5단계로 암호에 덧붙여 지정하고 있습니다. 사양 검토는 "대", 구현 및 머지(Merge) 작업은 "초대", 다음 슬라이스(Slice) 선정은 "중"——페이즈마다 권장 깊이를 정해두었기에 망설임이 없습니다.

영역 침범 금지

가장 많았던 사고는 AI가 페이즈의 범위를 넘어 작업해 버리는 것이었습니다. 페이즈 3이어야 하는데 의욕이 앞서 수정까지 시작해 버리는, 이른바 "좋은 의도로" 하는 행동입니다. 대책으로서 워크플로우 문서의 서두에 **"해당 페이즈의 범위만 실행하고, 페이즈 종료 시 반드시 세션을 끊을 것"**을 명시하여 훅을 통해 매번 주입하고 있습니다. 일 잘하는 직원을 멈추게 하는 규칙이 필요할 줄은 몰랐습니다.

효과 요약

가장 큰 효과는 수치로 나타나지 않는 부분으로, "오늘은 어디서부터 무엇을 할지"를 매번 고민하지 않아도 된다는 점입니다. 판단에 쓰는 에너지를 사양 검토와 리뷰에 온전히 쏟을 수 있게 되었습니다.

마치며

이 운영 방식은 특별한 도구를 전혀 사용하지 않습니다. 마크다운 파일 몇 장과, 세션 시작 시 문맥을 주입하는 훅 하나뿐입니다. AI의 성능 저하는 능력의 문제가 아니라 운영의 문제이며, 공정 설계로 해결할 수 있다는 것이 한 달 반 동안 운영하며 느낀 실감입니다.

제조업 출신으로서 결국 이것은 "준비(Setup)와 검사 공정, 그리고 추적성(Traceability)"라는 제조업의 고전 그 자체였습니다. AI 개발의 최첨단이 현장의 카이젠(개선)과 닮아가는 것이 흥미롭지 않나요?

다음에는 페이즈 2의 내용인 **"서브 에이전트 주도 개발(Sub-agent Driven Development)——1태스크 1AI + 2단계 리뷰"**를 쓸 예정입니다. AI가 AI의 결과물을 검수하고, 날조된 보고를 찾아내는 이야기입니다.

개발 중인 게임 「Abyssgate」(가제)의 진척 상황은 X에서 주 1회 발신하고 있습니다. 관심 있으신 분은 팔로우해 주세요.

그럼, 지하 미궁에서 기다리고 있겠습니다.

Discussion