[4개월 개발기] 에피소드 3 — 우리의 적응 방식: 가드레일·메모리 뱅크·계약 검증

“4개월간의 금융 AI 개발기” 3편. 앞선 에피소드 2에서는 3명의 팀원이 각자 AI 에이전트들을 이끌고 병렬로 모듈을 개발한 과정을 다루었다. 이번 편에서는 이처럼 빠른 병렬 작업이 최종 통합 지점에서 산산조각 나지 않도록 단단하게 붙잡아 주었던 3가지 핵심 장치들 — CLAUDE.md 기본 규약, 메모리 뱅크, 인터페이스 계약 검증 — 의 구체적인 모습을 살펴본다.

3일 뒤, 통합의 현장

프로젝트 초반 어느 목요일의 일이다. 화요일부터 3개의 팀이 각자의 AI 에이전트에게 작업을 나누어 맡겼다. PM 팀은 모델을 구성하는 기본 스키마를, 엔지니어 1팀은 피처 스키마를 생성하는 전처리 파이프라인을, 그리고 엔지니어 2팀은 이 둘을 엮어 실제 모델을 학습시키는 스크립트 초안을 전담했다.

목요일 오후, 3명이 모여 각자의 결과물을 합치는 통합(Integration)을 시도했다. 결과는 처참했다. 30분 만에 런타임 에러가 5개나 터져 나왔다. 결과적으로 에러의 원인은 모두 **‘같은 이유’**에서 비롯된 변형들이었다. PM 팀이 작성한 스키마에서는 피처 그룹의 경계를 특정한 키(Key) 이름으로 저장했다. 그런데 엔지니어 1팀의 전처리 파이프라인은 이를 완전히 다른 이름으로 저장했고, 엔지니어 2팀의 학습 스크립트는 또 다른 이름으로 읽어 들이려고 시도했던 것이다. 셋 다 각자의 맥락에서는 매우 그럴듯하고 합리적인 이름이었다는 점이 문제였다.

이것이 바로 병렬 AI 작업에서 흔히 반복되는 중요한 실패 사례다. 각각의 에이전트는 자신에게 주어진 맥락 안에서 가장 합리적인 이름을 고르기 마련이다. 세 개의 각기 다른 맥락에서 AI들이 독립적으로 선택한 이름이 우연히 정확하게 일치할 확률은 사실상 0에 가깝다.

여기에 대응하는 방법은 두 가지뿐이다. 첫째, 병렬 작업을 깔끔하게 포기하고 하나씩 순서대로 직렬로 진행하는 것(물론 이렇게 되면 3일짜리 작업이 9일로 늘어난다). 둘째, 병렬로 작업한 결과물들이 어긋남 없이 한곳으로 매끄럽게 모이도록 사전 통제 장치를 깐깐하게 깔아두는 것. 우리가 택한 것은 당연히 후자였고, 그것이 바로 이번 에피소드의 핵심 주제다.

`CLAUDE.md` 기본 규약 — 코드 한 줄 쓰기 전에

프로젝트 루트 디렉터리에 위치한 CLAUDE.md 문서는 Phase C(개발 환경 정비) 단계에서 단 한 줄의 코드가 작성되기도 전에 가장 먼저 쓰였다. 이 순서는 매우 의도적인 것이었음을 이전 에피소드에서 짚은 바 있다. 결과적으로 이 파일 하나가 프로젝트 전체의 성격을 가장 크게 결정지었다.

지금이야 여러 번의 수정을 거쳐 15개가 넘는 섹션으로 뚱뚱해졌지만, 프로젝트 초기에 즉시 박아 넣었던 4가지 원칙이 가장 핵심이었다.

Config-driven(설정 주도) 원칙. 모든 파라미터는 무조건 YAML 설정 파일에서 읽어 들여야 한다. 컬럼명, 경계값, 시나리오 목록, AWS 상수 등을 절대 코드 안에 하드코딩해서는 안 된다. 왜 이것이 가장 으뜸가는 기본 규약이 되었을까? AI 에이전트는 “그럴듯해 보이는 상수”를 코드 깊숙한 곳에 조용히 박아 넣는 데 매우 능숙하기 때문이다. 만약 batch_size=5632 같은 숫자가 아무런 주석도 없이 학습 스크립트에 스며들게 되면, 불과 3주만 지나도 도대체 왜 그 값이 쓰였는지 팀원 중 아무도 기억하지 못하게 된다. 이 모든 값을 Config 파일 위로 끌어올리면, 문서화와 변경의 편의성을 한 번에 확보할 수 있다.

관심사 분리 (Separation of Concerns). 어댑터(Adapter)는 오직 원본 데이터를 표준화된 DataFrame으로 변환하는 역할만 수행한다. 파이프라인 러너는 전처리, 피처 생성, 레이블 파생, 정규화, 텐서 저장까지의 몫이다. 그리고 학습 스크립트는 완성된 데이터를 로드하여 모델을 빌드하고 학습시키는 역할에만 집중해야 한다. 만약 파일 하나가 500줄을 넘어간다면? 우리는 그것을 관심사 분리가 제대로 되지 않은 경고 신호로 간주했다.

앞서 언급한 목요일의 끔찍했던 통합 사고 역시 원인은 여기에 있었다. 엔지니어 2팀의 학습 스크립트 안에 전처리 로직의 일부가 흉하게 인라인(Inline)으로 박혀 있었고, 이것이 엔지니어 1팀이 만들어둔 스키마와 충돌을 일으켰던 것이다. 이 사고 직후 관심사 분리 원칙을 사후에 엄격하게 적용하여, 230줄에 달하는 전처리 코드를 제자리(Phase 0)로 뜯어 옮겼다.

데이터 리키지(Data Leakage) 방지. 스케일러(Scaler)는 반드시 학습(Train) 데이터셋에서만 피팅(Fit)되어야 한다. 시계열 데이터를 나눌 때(Split)는 반드시 며칠간의 간격(gap_days)을 두어야 한다. 또한 본격적인 학습에 들어가기 전에는 무조건 LeakageValidator를 호출하여 점검을 강제했다. 이 조항과 관련된 어려운 데이터 무결성 사냥 이야기는 에피소드 5에서 아주 자세히 다룰 예정이다.

완료 보고의 4단계 요건. AI가 작업을 “다 마쳤습니다”라고 선언하려면 다음의 4가지 관문을 성공적으로 통과해야만 한다. 컴파일 검증, 인터페이스 계약 검증(아래에서 별도로 설명한다), 하드코딩 스캔, 그리고 앞서 말한 관심사 분리 점검이다. 에이전트가 혼자 들떠서 완료를 외치더라도, 이 4단계 중 한두 개만 대충 끝낸 상태라면 파이프라인은 머지않아 조용히, 그리고 치명적으로 깨지고 만다.

메모리 뱅크 — 수동 관리에서 자동 기억(Auto-memory)으로

CLAUDE.md가 프로젝트 전체를 지배하는 규약집이라면, 개별 작업 세션 간의 끊어진 맥락을 매끄럽게 이어주는 장치가 바로 ‘메모리 뱅크(Memory Bank)‘다. 이 기억 장치의 운영 방식은 프로젝트가 진행되는 동안 크게 두 번 바뀌었다.

초기 접근 — 수동으로 관리하는 8개의 파일 구조. 2025년 말에서 2026년 초까지만 해도, Claude Code가 세션 간의 지식을 기억하는 능력은 꽤 제한적이었다. 그래서 우리는 .claude/memory-bank/라는 디렉터리를 직접 파고, 그 안에 8개의 핵심 파일을 만들어 매 세션이 시작될 때마다 에이전트가 이를 꼼꼼히 읽도록 강제했다. 파일은 프로젝트 요약, 현재 작업 맥락, 이정표 체크리스트, 기술 스택 노트, 제품 맥락, 반복 패턴, 태스크 상태, 그리고 스타일 가이드로 나뉘어 있었다. 굳이 이렇게 여러 개의 파일로 잘게 쪼갠 것은 철저히 실패를 통한 경험칙이었다. 하나의 파일에 모든 정보를 추가하면, 에이전트가 방대한 정보량에 압도되어 정작 중요한 핵심을 번번이 놓쳐버렸기 때문이다.

이 시기에는 여러 AI 도구를 병행해서 썼기 때문에, .claude/RULES.md 파일과 .cursorrules 파일을 원본과 파생본 관계로 일관되게 유지시켜 주는 동기화 스크립트까지 따로 돌려야 했다. 도구마다 참고하는 규칙 파일이 다르면 결국 뱉어내는 코드의 규격이 어긋나게 되고, 이는 곧 통합 지점에서의 주요한 에러로 직결되었기 때문이다.

2026년 2분기 초 — Claude Code의 Auto-memory 도입 이후. 2026년 4월, Claude Code v2.1.59+ 버전에 대망의 ‘auto-memory’ 기능이 정식으로 도입되었다. 이때부터 마법처럼 세션 간의 지식이 에이전트의 머릿속에 자동으로 쌓이기 시작했다. 복잡한 빌드 명령어, 어려운 디버깅 과정에서 얻어낸 귀중한 통찰, 아키텍처에 대한 굵직한 노트, 코딩 스타일의 선호도, 특유의 워크플로 습관까지. 이전에 우리가 수동으로 8개의 파일에 욱여넣으며 힘겹게 관리하던 정보의 대부분이, 이제는 에이전트가 알아서 빠르게 기억하고 꺼내 쓰는 영역으로 성공적으로 넘어간 것이다.

현재 우리는 초기 8개의 수동 파일 중 대부분을 폐기했다. 살아남은 것은 단 두 개뿐이다. 프로젝트의 거대한 목표와 제약 조건을 명시해 둔 ‘최상위 요약 파일’ 하나, 그리고 너무나 빈번하게 바뀌어서 자동 기억에만 의존하기엔 리스크가 큰 **‘현재 태스크 상태 파일’**이다. 그 외의 자잘한 맥락들은 auto-memory가 훌륭하게 대신해 주고 있다. 골치 아프던 .cursorrules 동기화 스크립트 역시 단계적으로 걷어냈다. 주요 작업 환경이 Claude Code 쪽으로 일원화되면서 굳이 도구 간의 규칙을 병행 유지할 실익이 사라졌기 때문이다.

우리는 이 거대한 전환의 과정에서 아주 중요한 사실을 하나 깨달았다. **“도구가 멍청하고 약할 때 어쩔 수 없이 세워두었던 복잡한 가드레일을, 도구가 스스로 강력해진 뒤에도 관성적으로 남겨두어서는 안 된다”**는 점이다. 수동 메모리 뱅크는 2026년 초의 우리에겐 생명줄처럼 꼭 필요한 장치였지만, 불과 몇 달 뒤에는 시스템을 무겁게 만드는 낡은 유물이 되어버렸다.

인터페이스 계약 검증 — 병렬 작업 직후의 필수 루틴

글의 서두에서 언급했던 목요일의 심각한 통합 사고 — 똑같은 개념을 두고 세 팀의 AI가 각기 다른 변수명으로 저장하고 읽어 들였던 그 환장할 문제 — 를 두 번 다시 겪지 않기 위해, 우리는 모든 병렬 작업 세션이 끝날 때마다 다음과 같은 루틴이 기계적으로 돌아가게 만들었다.

수정을 마친 파일의 ‘저장(Save) 함수’가 정확히 어떤 키(Key) 이름으로 딕셔너리를 저장하는지 추출한다.
같은 브랜치 내에 있는 다른 파일의 ‘로드(Load) 함수’가 정확히 어떤 키 이름으로 데이터를 읽어 들이려고 기대하는지 추출한다.
이 두 집합의 차이(Diff)를 엄격하게 대조한다. 저장만 해놓고 아무도 안 읽는 키는 없는지, 읽으려고 하는데 정작 저장되지 않은 키는 없는지, 양쪽에 존재하긴 하지만 철자나 스네이크/카멜 케이스 등 이름이 미묘하게 다른 키는 없는지 샅샅이 뒤진다.

우리는 이 지루하고 치밀한 루틴조차도 AI 에이전트에게 통째로 위임했다. 병렬로 작업하던 2–3개의 에이전트가 코딩을 끝마치면, 오직 이 ‘인터페이스 계약 검증’만을 전담하는 네 번째 에이전트가 날카로운 눈으로 호출된다. 개별 에이전트들은 각자 자신이 부여받은 좁은 맥락 안에서 “이 정도면 그럴듯한데?” 싶은 이름을 마음대로 선택하겠지만, 이 네 번째 검증 에이전트는 전체 시스템을 위에서 내려다보는 넓은 시야를 가지고 런타임을 터뜨릴 불일치 요소들을 사전에 즉시 식별해 낸다.

만약 이 네 번째 에이전트가 없었다면, 우리는 매주 목요일마다 똑같은 통합 사고를 반복하며 허무한 디버깅에 3시간씩 청춘을 낭비했을 것이다. 하지만 이 든든한 수문장 덕분에, 그 고통의 3시간은 단 20분으로 획기적으로 줄어들었다. 통합이 어긋날 징조를 CI(지속적 통합) 빌드가 터지기도 훨씬 전, 즉 코드가 작성된 직후에 미리 잡아내어 고칠 수 있었기 때문이다.

가드레일이 AI 협업에만 쓰이는 건 아니다

이 세 가지 장치 — CLAUDE.md 규약, 세션 간 맥락 유지, 계약 검증 — 는 마치 AI 에이전트만을 위해 고안된 것처럼 들리지만, 실은 인간 팀의 협업에도 똑같이 적용되는 원칙이다. 사람이 병렬로 작업할 때 흔히 겪는 문제(변수명 불일치, 맥락 유실, 규칙이 점차 어긋나는 현상)는 AI 3기가 병렬로 작업할 때 발생하는 문제와 본질적으로 같다. 우리가 이 해결책을 AI 협업 과정에서 먼저 체계화했을 뿐, 그 근본은 인간 팀 협업의 오랜 지혜와 맞닿아 있다.

이게 한국 금융권의 중소 규모(3–5인) 팀에도 이 구조가 성공적으로 이식 가능한 이유다. 반드시 Claude Code 구독이나 고도화된 AI 도구를 갖추지 않아도 괜찮다. CLAUDE.md 수준의 명확한 프로젝트 규약집, 팀원 간의 공유 맥락 문서, 그리고 매 통합 전 인터페이스를 검증하는 루틴은 그대로 작동한다. AI가 있으면 훨씬 더 빠르겠지만, AI가 없어도 이 시스템은 견고하다.

다음 편

이어지는 에피소드 4에서는, 이처럼 철저한 가드레일 위에서 마침내 웅장한 모습을 드러낸 실제 아키텍처 — 7개의 이종 전문가 네트워크 — 가 도대체 어떻게 도출되었는지를 분석하여 본다. HGCN, PersLay, Causal, OT, Temporal Ensemble, DeepFM, LightGCN. 우리는 왜 하필 이 7가지를 선택했을까? 그 과정에서 아깝게 기각당한 후보 모델들은 무엇이었나? 무려 11개의 서로 다른 학문 분야에서 ‘구조적 동형사상’의 개념을 차용해 오기까지의 흥미진진한 여정이 공개된다.

원문 자료: 개발 스토리 (KO, PDF) §3 “품질 관리 전략”.