코드와 계획의 괴리, Ground Truth 기반의 플랜 리라이팅 전략

Context

코드베이스는 최신 상태를 유지했으나 설계 문서인 Plan 파일들이 실제 구현과 동기화되지 않은 상태. 정적 분석 도구나 CI 파이프라인이 없는 문서 특성상 인지하지 못한 채 정보 부패(Rot) 발생. 잘못된 우선순위 설정과 중복 작업 수행의 원인으로 작용.

Technical Solution

• Claude Code를 활용해 85개 API route, 49개 DB table 등 전체 시스템의 현재 상태를 추출하는 인벤토리 생성 과정
• 기억이나 기존 문서가 아닌 실제 코드 기반의 Ground Truth를 최우선 기준으로 설정하는 분석 방식
• 플랜 간 중복과 충돌을 발견하기 위해 병렬 검토가 아닌 순차적(Sequential) 읽기 전략 채택
• Credential 관리와 Notification 채널의 중복 패턴을 식별하여 단일 DB 패턴으로 통합하는 설계 최적화
• 다중 테넌트 감사 문서의 중복 항목을 소유 단계로 재배치하고 잔여 항목만 체크리스트로 분리하는 구조 개선
• 리라이팅 세션당 단일 커밋을 유지하여 문서의 변화 과정과 이력을 추적 가능한 형태로 기록

Impact

• 1회 커밋으로 22개 파일 변경
• 코드 라인 수 +893행, -288행 조정

Key Takeaway

솔로 개발 환경에서는 문서 검토를 강제하는 프로세스가 부재하므로 실제 시스템 상태를 먼저 덤프하고 이를 문서와 대조하는 정기적인 동기화 메커니즘이 필수적임.