Zenn 웹 에디터용: Opus 4.8 기술 편

변호사·세무사 오타가키(@yoshiki_otagaki)입니다.

전문직 현장에서 실제로 가동 중인 AI 활용·업무 자동화에 대해 발신하고 있습니다.

Next.js + Supabase + Anthropic API + 독자적인 MCP 서버로 법률 사무소용 SaaS인 「LegalFlow」를 혼자서 개발·운영 중입니다.

본 기사는 note 버전인 「Opus 4.8과 1세션으로 법무 SaaS의 설계·구현·리뷰·머지(Merge)까지 통째로 돌린 기록」의 기술 편입니다. 「AI와 개발 사이클을 돌렸다」는 이야기 측면은 그쪽에 맡기고, 본 기사에서는 구현의 기술적 논점을 깊이 있게 다룹니다.

주제는 제가 혼자 개발·운영하고 있는 변호사용 SaaS 「LegalFlow」의 개수입니다. Opus 4.8로 설계·구현, GPT-5.5로 코드 리뷰, 인간이 판정, CI로 검증하는 랠리를 1세션 내에서 완수한 기록으로부터, 다른 개발에서도 전용할 수 있을 법한 논점을 뽑아냅니다.

TL;DR

PR을 기능별로 4개로 분할 (페이즈 기능·Teams 연동·UI/UX P0·타입 핫픽스). 하나의 세션 내에서도 PR 단위는 지켜야 한다 -
인증 방식 선택(앱 권한형 vs 위임형)은 AI에게 결정하게 하지 않는다. 업무 실태를 파악하고 있는 인간의 판단 영역 -
CI 정비 자체를 AI가 제안했고, 그것이 직후에 실제 버그를 검지하여 구했다 (클라이언트/서버 경계 위반) -
AI 간의 코드 리뷰 공방 (Claude 구현 → GPT 리뷰 → 인간 판정 → Claude 수정)을 통해 보안 관련 중요 지적 사항을 잡아냈다 -
AI의 실수보다 인간의 머지(Merge) 실수가 더 리스크가 크다. 컨플릭트(Conflict) 해결 실수로 main을 망가뜨렸다. 핫픽스 PR과 CI로 복구

1. PR 단위 설계

세션 내에서 구현이 길어지면, AI는 "하나의 브랜치에서 전부 끝내려고" 하는 경향이 있습니다. 여기에 휘말리면 리뷰가 파탄 나고 롤백(Rollback)도 어려워집니다.

명시적으로 **"PR은 기능 단위로 나누어라"**라고 처음에 지시한 후, 다음과 같이 4개로 분할했습니다.

PR #9는 본래 더 세밀하게 나누어야 했으나, 페이즈 기능은 **DB·타입·UI가 밀결합(Tight Coupling)**되어 있어 분할할 경우 리뷰 난도가 높아지기 때문에 의도적으로 하나로 묶었습니다. "분할하여 정리하기 쉬워지는 경우에만 분할한다"——이 판단 역시 AI에게 통째로 맡기지 않고 인간이 직접 쥐었습니다.

2. 인증 방식의 선택: AI에게 결정하게 하지 않는 영역

Microsoft Graph 연동 시 반드시 등장하는 논점이 인증 방식의 선택입니다.

양자는 기술적으로도 보안 모델도 다릅니다. AI는 이 선택을 독단적으로 내리지 않고, 선택지와 논점을 저에게 제시해 왔습니다.

LegalFlow의 현재 사용자는 "1변호사 = 1 Microsoft 계정"이 압도적 다수입니다. 사무소 단위의 일원적인 테넌트(Tenant) 관리자 승인은 현실적으로 얻기 어렵습니다. 반면, 향후 멀티 테넌트(Multi-tenant) SaaS로서 외판할 계획이라면 앱 권한형이 확장성이 더 높습니다.

위임형을 선택했습니다. 멀티 테넌트 확장성을 일부 희생하더라도, 현재의 사용자 실태에 맞춘 선택입니다. 판단의 논리는 명확히 하여, 나중에 보더라도 이유를 알 수 있는 형태로 기록하고 있습니다.

교훈: AI는 선택지를 정리해 오지만, 업무 실태에 비추어 결정하는 것은 인간의 일입니다. AI에게 "어느 쪽이 좋아?"라고 물으면 그럴싸한 답변이 돌아오게 되어 판단의 책임이 모호해집니다. 선택지와 논점을 AI에게 정리시키고, 판단은 스스로 한다——이 역할 분담을 명시하는 것이 중요합니다.

3. 토큰의 암호화 저장과 운영 환경 키 필수화

위임형 OAuth에서는 각 사용자의 리프레시 토큰 (Refresh Token)을 영구적으로 저장해야 합니다. 이를 평문으로 DB에 저장하면, DB 유출 시 모든 사용자의 Microsoft 계정이 탈취되는 치명적인 리스크가 발생합니다.

첫 번째 Claude의 구현은 이 점이 안일했습니다. 토큰을 평문과 다름없이 DB에 저장하고 있었습니다.

이 문제를 해결한 것이 뒤에서 설명할 **GPT-5.5에 의한 코드 리뷰 (Code Review)**입니다. 지적 내용:

• 토큰은 **서버 측에서 대칭키 암호화 (Symmetric Key Encryption)**를 거친 후 DB에 저장해야 함
• 운영 환경에서는 암호화 키가 환경 변수에 설정되어 있지 않으면 구동되지 않도록 설정해야 함 (페일 세이프 (Fail-safe))
• 개발 환경에서는 완화해도 좋지만, 운영 모드에서는 엄격한 체크가 필수

이를 Claude에게 다시 전달하여 수정했습니다. 최종적으로는 다음과 같은 구조가 되었습니다.

• AES-GCM 기반의 암호화 유틸리티
• 환경 변수로부터의 키 로드 및 운영 모드에서의 존재 검증 (미설정 시 구동 실패)
• DB 스키마 레벨에서 토큰 컬럼을 '암호화 완료 전제'로 명시

이는 보안 중요 사항을 AI 단독 구현만으로는 놓칠 수 있다는 리스크가 현시화된 좋은 사례입니다.

4. 테넌트 경계 침범 방지 가드 (Guard)

또 하나, GPT-5.5로부터 강력한 지적을 받은 것이 바로 **테넌트 경계 침범 (Tenant Crossing)**이었습니다.

구체적으로는 사용자 A의 OAuth 토큰을 사용하여 실수로 다른 테넌트의 리소스(사용자 B의 Teams)를 조작하게 될 리스크를 의미합니다. SaaS로서는 절대로 일어나서는 안 될 사고입니다.

Claude의 초기 구현에서는 요청 처리 계층에서 '현재 로그인 중인 사용자의 토큰'을 가져와 사용하는 단순한 구조였습니다. 이것만으로는 다음과 같은 문제가 남습니다.

• 작업 큐 (Job Queue)를 통한 비동기 처리 시, 잘못된 사용자 컨텍스트가 섞일 가능성
• 멀티 세션 환경에서 토큰이 뒤바뀔 가능성

수정 후에는 다음과 같은 구조로 변경되었습니다.

• 모든 토큰 사용 지점에서 tenant_id와 user_id를 명시적으로 전달
• API 클라이언트 계층에서 토큰과 쌍을 이루는 사용자 식별자가 일치하지 않을 경우 즉시 에러 발생
• 비동기 작업의 페이로드 (Payload)에 실행 컨텍스트(누구의 요청으로 동작하고 있는지)를 반드시 포함

이것들은 '동작에는 영향을 주지 않지만, 사고 발생 시 피해를 국소화하는' 방어 계층입니다. AI 구현 시 놓치기 쉬우며, 리뷰를 통해 잡아내야 하는 전형적인 사례입니다.

5. CI가 잡아낸 실제 버그: 클라이언트/서버 경계

이번 세션에서 가장 아찔했던 순간은 CI가 직후에 잡아낸 실제 버그였습니다.

CI (GitHub Actions를 통해 빌드, 타입 체크, Lint를 자동 실행) 설정은 이번 세션에서 Claude가 "PR을 올리면 빌드를 자동으로 실행해야 한다"고 제안하여 도입한 것입니다.

이를 도입한 직후의 PR에서 CI가 즉시 에러를 출력했습니다. 서버 전용 API를 클라이언트 측(브라우저에서 실행되는 코드)에서 import 하고 있는 부분이 있었던 것입니다.

Next.js 계열의 프레임워크에서는 Node.js 전용 모듈(파일 시스템 API 등)을 클라이언트 번들(Client Bundle)에 포함하면 빌드가 깨집니다. 이는 타입 체크만으로는 잡아낼 수 없으며, 실제로 빌드를 돌려봐야만 알 수 있는 버그였습니다.

만약 CI 없이 머지(Merge)했다면, 운영 환경에서 브라우저를 여는 순간 **하얀 화면 (White Screen)**이 나타났을 것입니다. CI가 안전망으로서 기능한 순간이었습니다.

교훈: AI에게 맡기는 속도가 빨라질수록 CI의 가치는 상대적으로 높아집니다. "빌드가 통과된다", "타입이 통과된다", "Lint가 통과된다"는 것만으로도 AI 구현의 사고율은 극적으로 낮아집니다. CI 자체의 정비도 AI에게 맡길 수 있는 시대이므로, 첫 세션에서 반드시 포함할 것을 권장합니다.

6. AI 간의 리뷰 공방: 실제 운영 플로우

이번 세션에서 가장 새로운 경험이었던 것은 Claude (Opus 4.8)의 구현에 대해 GPT-5.5로 코드 리뷰를 진행하는 랠리(Rally)였습니다.

실제 운영 플로우는 다음과 같습니다:

1. Claude: PR 생성 (구현 + 자기 리뷰)
2. 인간: PR의 diff를 GPT-5.5에 복사하여 리뷰 요청
   "보안, 성능, 유지보수성 측면에서 엄격하게 검토해줘"
...

3~5 라운드 정도면 수렴합니다. 중요한 것은 인간이 최종 판단(Judge)을 쥐고 있어야 한다는 점입니다. GPT-5.5의 지적 중에는,

• 보안 및 실제적인 지적 (수용해야 함)
• 설계 의도를 이해하지 못한 채 "베스트 프랙티스(Best Practice)에 어긋난다"라고 말하는 과도한 지적
• 문화적·스타일적 선호도의 차이

가 혼재되어 있습니다. 전부 수용하면 AI의 취향에 휘둘려 본래의 설계가 무너지고, 전부 거절하면 실제적인 지적을 놓치게 됩니다. 인간이 수용 여부를 판별하는 것이 이 랠리의 핵심입니다.

제가 체감한 수용/거절 비율은 대략 "수용 4 : 거절 6" 정도였습니다. 수용한 지적의 질은 높았고, 거절한 지적 중에도 "논점으로서 일리가 있는" 것들이 포함되어 있었습니다. 1인 개발의 리뷰 부재 문제를 다른 AI가 부분적으로 메워준다——이 경험은 분명히 개발의 질을 높여줍니다.

7. 나의 실수: 머지 컨플릭트(Merge Conflict)로 main을 망가뜨리다

솔직하게 쓰겠습니다. 이번에 가장 큰 실수는 AI가 아니라 제가 저질렀습니다.

PR #11을 머지할 때, PR #9와 #10의 머지 후 상태와 컨플릭트가 발생하여 제가 수동으로 컨플릭트를 해결했습니다. 이때, 양쪽 브랜치의 수정 사항을 통합해야 할 부분에서 한쪽을 지워버렸습니다.

결과적으로 main의 빌드(Build)가 깨졌습니다. CI가 즉시 빨간 깃발(Red Flag)을 올렸고, 운영 환경 배포(Production Deploy)는 중단되었습니다.

대응은 빠르게 할 수 있었습니다.

• CI 실패 로그를 통해 누락된 타입 정의(Type Definition)를 특정
• 핫픽스(Hotfix)용 브랜치를 생성
• Claude에게 "이 타입 정의가 누락되었으니 되돌려줘"라고 지시
• PR #12로서 최소한의 diff로 수정
• CI 그린(Green)을 확인하고 머지

10분 정도 만에 복구되었습니다. 실제 사용자에게는 영향이 없었습니다.

교훈: AI의 작업 속도가 올라가면, 인간의 머지(Merge) 조작 실수가 상대적으로 병목(Bottleneck)이 됩니다. "컨플릭트 해결도 AI에게 맡긴다", "머지는 GitHub UI가 아니라 자동 머지 툴에 맡긴다" 등, 인간의 수작업을 줄이는 방향으로 나아가야 합니다.

8. 요약: 앞으로 AI 개발을 본격화할 분들에게

이번 세션을 통해 얻은 실용적인 지침입니다.

• PR은 기능 단위로 나눈다. AI에게 통째로 맡기면 하나의 브랜치에서 모든 것을 처리하려고 하므로, 명시적으로 지시해야 한다.
• 업무 실태와 관련된 판단은 AI에게 결정하게 하지 않는다. 선택지의 정리는 시키되, 판단은 스스로 한다.
• CI를 가장 먼저 정비한다. AI가 CI 정비 코드도 작성해 준다. 이것이 안전망의 핵심이다.
• 다른 AI로 코드 리뷰를 시킨다. 1인 개발의 리뷰 부재 문제에 강력한 효과가 있다. Claude vs GPT는 궁합이 좋다.
• 인간의 머지 실수를 경계한다. AI의 작업보다 인간의 Git 조작이 버그를 만들기 더 쉽다.
• 보안 관련 사항(암호화, 테넌트 격리, 운영 키 필수화 등)은 리뷰에서 잡아낸다. AI의 초기 구현에서는 느슨해지기 쉽다.
• 수정 사이클이 빨라지면 할 수 있는 일의 질이 달라진다. 3주에서 1일로 변하는 속도의 변화는 개발 경험을 근본적으로 바꾼다.

스토리로서의 전체적인 모습, 인간과 AI의 분업에 관한 이야기는 note 버전에 적어두었습니다:

관련:

🛠 LegalFlow → https://flow.legal-consulting.jp

오타가키 요시키 (Yoshiki Otagaki)

변호사 (도쿄 변호사회·등록 번호 51084) / 세무사 / 소프트웨어 개발자.

Next.js + Supabase + Anthropic API + 독자적인 MCP 서버로 법률 SaaS 「LegalFlow」를 개발 및 운영.

note: https://note.com/yoshiki_otagaki ｜ X: https://twitter.com/yoshiki_otagaki

Discussion