마이그레이션 과정에서 Claude Code가 레거시(Legacy) 패턴과 새로운 아키텍처 패턴을 혼용하는 것을 방지하기 위해 CLAUDE.md에 결정 행렬(Decision Matrix)을 추가하세요. 827개의 커밋이 포함된 Flutter 프로젝트에서 사용된 이 기술은 마이그레이션 시간을 약 30% 단축했습니다.

핵심 요약 (Key Takeaways)

• 마이그레이션 중 Claude Code가 레거시와 새로운 아키텍처 패턴을 섞어서 사용하지 않도록 CLAUDE.md에 결정 행렬(Decision Matrix)을 추가하세요.
• 827개의 커밋이 있는 Flutter 프로젝트에서 이 기술을 적용하여 마이그레이션 시간을 약 30% 줄였습니다.

변경 사항 — AI 지원 마이그레이션의 실제 문제점

Claude Code에게 레거시 코드의 버그를 수정해 달라고 요청하면, 모델의 기본 본능은 그것을 "개선"하는 것입니다. 모델은 try/catch 블록을 보면 이를 더 세련된 에러 핸들링(Error-handling) 패턴으로 리팩터링(Refactor)하고 싶어 합니다. 이러한 본능은 새로운 기능을 개발할 때는 옳지만, 마이그레이션 중에는 재앙이 될 수 있습니다.

한 개발자는 스위스 소매업체를 위한 Flutter 이커머스 앱의 827개 커밋에 걸쳐 이 정확한 문제를 기록했습니다. 해당 앱은 85%의 크래시 프리(Crash-free) 비율과 세 가지의 서로 다른 에러 핸들링 스타일을 가지고 있었습니다. 해결책은 더 똑똑한 모델이 아니었습니다. 그것은 아키텍처 가드레일(Architecture guardrails)이 포함된 CLAUDE.md 파일이었습니다.

당신에게 주는 의미 — 가이드라인 대신 결정 행렬을 사용하세요

대부분의 CLAUDE.md 파일은 "Clean Architecture를 사용하세요" 또는 "상태 관리를 위해 Riverpod을 선호하세요"와 같은 아키텍처 규칙을 나열합니다. 그것만으로는 충분하지 않습니다. AI에게는 조건부 로직, 즉 수행 중인 작업에 따라 어떤 패턴을 사용할지 알려주는 결정 행렬(Decision matrix)이 필요합니다.

다음은 해당 프로덕션 프로젝트에서 가져온 단순화된 결정 행렬입니다:

## Architecture

This project uses Clean Architecture with feature-first organization.
...

핵심 통찰: 결정 행렬은 인간을 위한 문서가 아닙니다. 인간은 스탠드업 미팅(Standups)과 PR 리뷰를 통해 문맥(Context)을 파악합니다. 이것은 AI를 위한 문서입니다. 즉, 가이드라인 대신 결정 트리(Decision trees)를 사용하여 명시적이고 모호하지 않게 작성되어야 합니다.

지금 바로 시도해 보세요 — 자신만의 가드레일을 구축하세요

1단계: 코드베이스의 아키텍처 상태 매핑하기

현재 프로덕션에서 사용 중인 모든 유효한 패턴을 식별하세요. Flutter 앱의 경우, 다음과 같은 작업이 필요했습니다:

• 레거시 코드 (Legacy code): try/catch, ChangeNotifier
• 신규 코드 (New code): Riverpod을 사용한 TaskEither, AsyncNotifier
• 전환 코드 (Transition code): 절반만 마이그레이션된 기능 (마이그레이션 체크리스트를 따를 것)

2단계: 각 모드에 대한 커스텀 스킬(Custom skills) 생성

커스텀 스킬은 기본 컨텍스트를 재정의하는 Claude Code의 슬래시 명령어(slash commands)입니다. 다음 세 가지를 생성하세요:

/migration — 엄격한 순서를 강제합니다 (도메인 레이어 우선, 그다음 데이터, 프레젠테이션, 마지막으로 테스트).

/legacy-code — "기존 패턴을 따르세요. 클린 아키텍처 (Clean Architecture) 임포트를 도입하지 마세요. 주변 코드의 스타일과 일치시키세요."

/new-feature — "Riverpod과 TaskEither를 사용하여 클린 아키텍처 (Clean Architecture)를 사용하세요. 프로젝트의 현재 컨벤션을 따르세요."

3단계: 실제 작업으로 테스트하기

가드레일(guardrails)이 없는 상태에서 Claude Code에게 레거시 코드의 버그를 수정하도록 요청하세요. 그런 다음 /legacy-code를 활성화한 상태에서 다시 요청하세요. 차이점(diffs)을 비교해 보세요. 두 번째 버전은 주변 코드를 리팩터링하지 않고 오직 버그만 수정해야 합니다.

이것이 작동하는 이유 — 컨텍스트의 토큰 경제학 (Token Economics of Context)

코드를 "개선"하려는 AI의 본능은 깨끗한 코드를 작성할 때 보상을 받는 학습 데이터에서 기인합니다. 마이그레이션 과정에서 "가능한 최선의 코드"는 컨텍스트에 따라 달라집니다. 마이그레이션되지 않은 코드에서의 버그 수정은 레거시 패턴을 따라야 합니다. 반면 마이그레이션 중에 작성되는 동일한 로직은 새로운 아키텍처를 따라야 합니다. 어떤 모델 학습도 이러한 차이를 포괄하지 못하므로, 프로젝트별로 구성해야 합니다.

이 프로덕션 프로젝트의 결과: 마이그레이션 기간 약 30% 단축. 이는 AI가 완벽한 코드를 작성했기 때문이 아니라, 개발자가 판단이 필요한 결정을 내리는 동안 AI가 기계적인 부분을 처리했기 때문입니다.

출처: dev.to

원문은 gentic.news에 게시되었습니다.