AI가 짠 대형 코드베이스 유지보수 다들 어떻게 함?.txt

Claude Code로 Opus 4.5 쓰고 있음. 요새 이걸로 NextJS 앱 짜게 시키는데 결과물 꽤 지림.

근데 문제는 코드는 잘 돌아가는데, 이게 내 머릿속에서 나온 구조가 아니다 보니 유지보수가 헬임. 어떤 서비스가 있고 코드베이스 전반이 어떻게 돌아가는지 파악하고 추적하기가 너무 빡셈.

코드베이스 전체를 조감도(Bird's eye view)처럼 하이레벨로 딱 요약해서 보여주는 다이어그램이나 순서도(flowchart) 있는 GUI가 있으면 진짜 좋겠음. 혹시 이런 거 해주는 앱이나 전략 아는 사람 있음? Claude Skills나 Hooks 같은 거 써서 될라나?

내가 상상하는 건 앱 전체를 관제하는 "컨트롤 센터" 같은 대시보드임. 모든 모듈, 서비스, 코드 덩어리들 쫙 리스트업 해주고, Claude한테 instruction(지침) 줘서 코드베이스 털끝만큼이라도 수정하면 알아서 대시보드도 싹 업데이트하게 만드는 거지. 혹시 이렇게 구축해본 사람 있음?

이제 코드 짜는 건 거의 정복된 거 같고(일반적인 앱 기준), 다음 타겟은 AI로 짠 코드를 어떻게 '규모 있게(at scale)' 굴리느냐인 듯함.

• 문서화 찾고 있는 듯.

  • 코드 위키.

• 클로드한테 프로젝트 문서화 생성해달라고 해봤는데 전혀 도움 안 됐음. 그걸 다 읽어야 한다고 생각함? 컴퓨터쟁이들은 참 이상함.

  • 이 뻔뻔한 댓글에 왜 추천이 박히는지 모르겠음. 작성자는 코드베이스 시각화 도구를 찾는 중인데, 제대로 된 소프트웨어 추천해 줄 사람 없음?

    • 코드베이스 시각화 도구라... IDE 아님? 그게 바로 IDE가 하는 일 아님?

      • 아님. 작성자가 말하는 건 의사코드 플로우차트 같은 거임. 코드 짜기 전에 시각화하는 용도로 흔히 쓰임. AI가 코드베이스 보고 이런 차트 실시간으로 그려주면 개쩔긴 할 듯.

  • 구글에서 이미 'Code Wiki'라는 무료 도구 제공 중임. 2분만 검색해도 나왔을 텐데:

  • CodeSee: 코드 변경에 따라 코드베이스 맵 자동 생성 및 업데이트.

  • CodeCharta: 코드베이스를 3D 도시 맵으로 시각화해서 복잡도 보여줌. 로컬 분석 방식.

  • Emerge: 브라우저 기반 상호작용형 시각화, 의존성 및 품질 지표 지원.

  • Madge: JS/CSS 모듈 의존성 그래프 생성 및 순환 참조 확인.

  • 아니면 Claude Code로 30분 만에 직접 도구 만들어서 도널드 크누스(Donald Knuth) 헌정용으로 이름 붙여보든가.

    • 추천 고마움. 이게 작성자가 원한 답에 제일 가까운 듯. 근데 코드 위키는 공개 저장소에서만 작동하고, 아까 "그런 도구 아직 없다"는 댓글도 있었으니 공유할 가치가 있음. 근데 네 답변 좀 AI가 쓴 것 같음.

• 문서화는 완전 20세기 유물임.

• 코드 생성에 AI를 많이 쓴다면 아키텍처 파악에도 써보는 게 어떰? 의존성 매핑이나 모듈화 계획 제안 같은 거.

  • 문제는 "언제 멈춰야 할지" 모른다는 거임. LLM은 아키텍처 제안을 멈추지 않음. 코드베이스가 커질수록 기존 구조를 무시하거나 코드를 더 엉망으로 만들 확률이 높음. 결국 본인이 코드가 어떻게 돌아가는지 알아야 함. 버스 운전대는 사람이 잡아야 함.

• 인간이 AI의 병목지점이라는 말 진짜 공감함.

  • ㅇㅇ.

  • "고객은 자기가 뭘 원하는지 모른다"는 문제가 상단까지 올라온 격.

• 요약: 지름길은 없음. 자기 코드베이스를 이해 못 하는 건 무책임한 일임. 특히 클라이언트 작업이면 더더욱. 다만 다음 방법들은 추천함:

  • 사람이 직접 관리하는 시스템 지도(ARCHITECTURE.md) 만들기. AI가 작성을 도울 순 있지만 책임은 사람이 짐.

  • 클로드를 코드 생성기가 아니라 아키텍처 조수로 활용하기. 의존성 매핑이나 ASCII 다이어그램 요청하기.

  • 아키텍처 먼저 정의하기. 폴더 구조나 데이터 흐름을 먼저 짜고 클로드한테 구현만 시키기.

  • "헬리콥터 뷰" 파일 생성. 전체 코드를 하나의 파일로 합쳐서 클로드에게 통째로 던져주기.

    • 거대 저장소에서는 파일 하나로 안 됨. 앱/패키지마다 README를 두고 파일 한 줄 설명을 다 적어야 함. 루트에는 원칙과 규칙을 담은 CLAUDE.md 같은 게 필수임. 문서화 업데이트하는 요원(Agent)도 필요함.

    • 오 개쩐다! 이제 게시글 읽고 자동으로 의견 댓글 다는 봇도 만들자. 그럼 우리가 읽고 배울 필요 없이 완벽해질 듯.

• 진짜 실력을 키워야 함. AI에 의존하면 뇌가 썩고 장기적인 안정성도 없음.

• 솔직히 당신이 찾는 그런 시각화 도구는 아직 존재하지 않음.

  • 맞음. 근데 빠르게 발전 중임. Syntax의 Scott이 보여준 'Beads' 같은 것도 있고, 2026년은 또 다를 거임.

• gitlantis 확인해보셈.

• 내가 만들고 있는데 아직 출시 안 함.

• 출시 임박함. 레거시 C#이랑 유니티 지원 잡느라 좀 걸림. 조만간 데모 올림.

• 코드가 커질수록 한 번에 수정하는 양은 적어져야 함.

  • 이분 최소 개발 좀 해보신 분.

• 팁 하나 주자면, 파이썬 스크립트 짜서 코드베이스 전체를 하나의 .md로 합치고 계층 구조 상단에 박으셈. 그걸 클로드 웹 버전 프로젝트 파일에 넣으면 11만 줄 넘어도 아키텍처 결정 잘 내려줌.

• 규모가 커지면 기능 하나 추가할 때 3개가 깨짐. AI 컨텍스트가 미묘하게 어긋나기 때문임. 10년 차 엔지니어인 나도 이 문제는 겪음. 입력값이 어떻게 구성되고 전달되는지 시각화하는 개념이 절실함. 나중에 아이디어 찾으면 공유하러 오겠음.

• 코드 생성될 때 매의 눈으로 감시해야 함. CLAUDE.md에 아키텍처 명시하고 지름길 찾지 마셈.

• 자기가 클로드 시켜서 만드는 소프트웨어 아키텍처를 본인이 모른다고? 그걸 AI가 그려주길 바람? 프롬프트 짤 줄도 모름?

  • 이건 개인 워크플로우 자동화용이라 작동만 하면 장땡임. 내가 검증하니까 상관없음.

    • 본문에서 말한 거랑 다르잖음.

• 다이어그램이랑 플로우차트 보여주는 GUI 있으면 좋겠음.

  • 그거 Opus 4.5한테 시키면 바로 만들어줌. TDD랑 문서화 병행하면 껌임.

• 사람이 짠 거대 코드베이스는 어떻게 유지보수함?

• 세 가지 팁: 1. Windsurf 써보셈. 코드맵이랑 자동 문서화 기능 좋음. 2. 작고 독립적인 모듈들로 쪼개고 API 계약만 잘 관리하셈. 3. 개발자가 아니라 분석가처럼 생각하셈. 코드를 다 이해 못 해도 시스템의 이상적인 동작과 제약 조건을 알면 AI를 제대로 부릴 수 있음.

• 파일이 1,000줄 넘어가면 모듈화 리뷰 들어가야 함. 500~1,000줄 단위로 쪼개면 계층 구조 자체가 지도가 됨.

• 그냥 앉아서 본인 코드베이스 공부할 생각은 안 해봄?

  • 작성자는 합리적인 해결책을 찾으러 온 게 아님!

• 나 개발자인데 코드 이해는 함. 근데 클로드랑 사람 둘 다 보기에 좋은 문서화 구성법이 궁금함. Claude.md는 짧게 유지하고 상세 문서는 따로 둬서 필요할 때만 링크 걸어주면 되나?

  • 맞음. Claude.md에는 아주 간결한 요약이랑 링크만 걸어두셈. 효과 직임.

• 이건 꼭 필요한 제품임. 없으면 누군가 만들 것임. 아니면 본인이 '바이브(Vibe)'로 짜보든가.

• 그거 그냥 본인이 직접 만드셈.

• 클로드랑 소통하는 대시보드 직접 만들었음. 문서, 의존성 그래프, 감시용 파이썬 스크립트 다 들어감. 일주일 정도 걸렸는데 시간 존나 아껴줌.

• 그래서 내가 'Agent Provisioner' 만듬. 깃허브 분석해서 CLAUDE.md랑 설정 자동 생성해줌. AI한테 코드베이스 재탐색 시키지 말고 아키텍처 컨텍스트를 주셈.

• 무조건 "모듈화"가 답임. 모든 걸 클래스로 나누고 인터페이스화하셈. FastAPI + HTMX + DaisyUI 조합 추천.

• 여기 여론이 틀렸음. 설계 단계가 부족한 거임. 코드베이스 전체 접근권 가진 모델이랑 기능 구상하고, 철저히 조사한 뒤에 구조화된 문서로 프롬프트 한 방에 구현시켜야 함. 유닛 테스트 필수고. 3개월 치 일 한 번에 던지지만 않으면 안 틀림.

• 바이브 코딩(Vibe coding)은 기술 부채로 가는 직행열차임. 자기가 이해 못 하는 코드는 유지보수 못 함.

• 'Noderr' 확인해보셈. 코드베이스 분석해서 각 노드(클래스/패키지)별로 스펙 MD 만들고 의존성 기록해줌. 작업 세션마다 스펙 업데이트하고 검증하는 프롬프트 시스템임. 컨텍스트 윈도우 짧을 때 유용함.

• Mermaid 차트 처음부터 관리하셈. 사용자 흐름이랑 DB 관계 시각화에 짱임. 마크다운에서 바로 렌더링됨.

• 구현할 때마다 Mermaid 다이어그램도 같이 그리라고 시키셈.

• 자기 코드베이스 모르면 그건 자기 거 아님. 너무 서두르지 말고 리뷰 좀 하셈.

• CodeScene 써보셈. 만든 사람이 천재임.

• AI는 그냥 내 스케줄에 맞춰주는 페어 프로그래머일 뿐임. 이해도 못 하면서 거대 코드베이스 유지하겠다는 건 어리석은 생각임.

• 게으름 피우지 말고 좀 배우는 게 어떰?

• SAP Fiori 앱 확장 프로그램 쓰면 테이블, 서비스, UI 패턴 다 시각화해줌. 이런 거 조만간 100배는 더 쏟아질 거임.

• 지름길 찾지 마셈. 구성 요소나 전체적인 의견 정도만 물어보고 집중해야 함.

• 실력 부족.

• 아키텍처 디자인에 패턴이랑 구조 명시해두고 주기적으로 리뷰하셈. 설계에서 벗어난 해결책은 거부해야 함.

• 우린 BMAD 씀.

  • 그게 뭔데.

• 그냥 이직하셈. 그럼 유지보수 걱정 안 해도 됨.

• /init 치고 CLAUDE.md나 읽으셈.

• 유닛 테스트랑 e2e 테스트(Cypress 등)가 코드의 품질임. 그것만 제대로 이해해도 스케일업 가능함. 인증 시스템 같은 건 직접 짜지 말고 기성품 쓰셈.

• 아키텍처랑 플로우차트 먼저 정의하고 컴포넌트 분리한 다음, 클로드한테는 구현이랑 테스트 커버리지 채우는 것만 시키셈.

• AI랑 같이 짰으면 알아야지. 본인이 준 아키텍처가 코드의 위치를 결정함.

• SRP(단일 책임 원칙) 적용하고 모킹(mocking)이랑 테스트하기 쉽게 짜달라고 항상 요구하셈. 그래야 유지보수 가능함.

• 백엔드 기준 컨트롤러, 서비스, 모델 등 기본 구조 직접 잡고 AI 투입함. 모든 변경 사항 철저히 리뷰하고 리팩토링도 자주 함. TDD랑 버전 관리 필수임.

• "거대함"의 정의가 뭐임?

• 그래프 시각화에는 Neo4j 써보셈.

• 제미나이 코드 위키(Gemini code wiki)가 지식 레이어 쌓기에 좋음.

• Frappe Framework + Cursor + MCP 조합 추천.

• RooCode에서 Opus 4.5 쓰는데 플로우차트 그려달라면 완벽하게 그려줌.

• aetherlight.ai 써보셈. 알파 버전인데 프로젝트/스프린트 계획 짜주고 코드랑 문서 정리 잘 해줌.

• 인덱싱이 필요함. 그래야 AI가 포괄적인 문서 작성 가능함.

• 수백 명이 10년 넘게 짠 코드를 어떻게 유지하겠음? 문서화, 코드 리뷰, 테스트뿐임.

• 개발은 코드 줄 수가 아니라 아키텍처 싸움임. 모델한테 구조를 맡기고 결과물만 받아먹으면 지름길은 없음. 대시보드나 차트가 해결 못 해줌. 멘탈 모델이 있어야 요약도 의미가 있는 거임.

• LLMC라는 로컬 RAG 데이터베이스 만들어서 컨텍스트 최소화함. 그러면서 아키텍처 존나 공부함.

• 각 컴포넌트별로 draw.io 다이어그램 그리라고 시키셈.

• 마크다운 파일 하나에 파일 위치, 모듈 설명, 서비스 상호작용 개요만 가볍게 적으셈. 대시보드는 그냥 그 마크다운 예쁘게 보여주는 HTML 페이지면 됨. 사람들이 욕해도 이건 정당한 아이디어임.

• 각 클래스/서비스별로 사양서(spec) 만들고 로직 단계별로 설명하게 시키셈. 그거 읽고 수정할 거 피드백 주는 식으로 관리 가능함.

• 제미나이에 올리고 Nano Banana Pro로 아키텍처 이미지 생성하셈.

• 코드베이스가 머릿속에 없어서 문제라고? 본인이 답을 말했네. 에이전트 코딩한다고 이 단계를 건너뛰면 안 됨.

• 릴리즈 전 단계인 내 방식 있는데 의견 궁금함.

• 모든 코드 머지(merge) 직접 리뷰하셈. 노력이 필요함.

  • 엔지니어링적인 해결책을 찾는 거임. 넥스트제이에스 같은 웹 개발은 이게 마지막 장벽이라고 봄.

• Gene Kim의 'Vibe Coding' 패턴 읽어보셈. 의도적인 코드베이스 구축에 도움 됨.

• README.md에 Mermaid 써서 다이어그램 그리게 시키셈.

• AI로 템플릿 빌드하고, 나는 마이크로 매니징하면서 결함 찾는 식으로 함.

• CodeSee 추천.

• TDD랑 통합 테스트 하셈. 요구사항 만족하는지 보여주기 전까지는 AI를 가만 안 둠.

• 그게 포인트임. 유지보수 안 함!

• 클로드 코드 대시보드 오픈소스로 풀었음(ELF). 여러 프로젝트 흐름 파악하기 좋음.

• 코드베이스를 그래프 DB로 만들어주는 도구(code-grapher) 만들었음. Neo4j로 시각화해서 보면 클로드도 코드베이스 탐색 훨씬 잘함.

• Cursor랑 Git 쓰셈.

• 멘탈 모델을 가지고 AI를 그냥 도구로만 써야 함. 시작하기 전에 AI랑 구조만 몇 번씩 다시 잡기도 함.

• UML 다이어그램 그려달라고 하셈.

• CLAUDE.md에 Mermaid 다이어그램 포함해서 문서 짜달라고 하셈. 헷갈리면 폴더 하나씩 설명해달라고 하고. 결국 코드가 가장 정교한 문서임.

• AI한테 실행을 맡기되, 파일명이나 구조 같은 세부 가이드라인은 본인이 꽉 잡고 있어야 함. 그래야 이해도가 안 떨어짐.

• 무조건 모듈화.

• 이미 답 알고 있잖음. 바뀐 거 없음.

• 프로젝트를 논리적 단위로 쪼개고 'Spec Kitty'로 개발 추진함. 상위 기획도 별도 프로젝트로 관리함.

• 파일 하나가 기능 하나, 그 안의 함수들이 각각 목적을 가지게 쪼개면 아키텍처 이해하기 쉬움.

• MCP 써서 지라(Jira) 같은 관리 시스템이랑 연동하셈. 계획이나 PRD를 코드 구조와 동일하게 문서화하면 AI 컨텍스트 잡기 편함.

• AI가 썼으면 AI가 유지보수하게 하셈. 바이브 코딩된 앱은 어차피 유지보수 힘듦.

• 개발자로서 코드 짜는 시간 아껴서 코드 읽는 데 쓰셈. 책임은 결국 사람이 지는 거임.

• 제대로 된 유닛 테스트, 코딩 표준, 통합 테스트, 엄격한 컨텍스트 가이드라인이 답임.

• 코드 모르면 읽어야지.

  • 안 읽을 거임. 계속 눈 감고 코딩할 거임.

• RAG 쓰셈.

• 26개 언어 지원하는 시각화 앱 조만간 출시함. 코드 그래프 생성, 중복 감지, 보안 감사 다 됨. 거대 저장소도 밀리초 단위로 검색 가능함.

• 클로드 코드한테 Mermaid 다이어그램 .md 파일로 만들어달라고 해서 깃허브에서 보셈.

• 클로드한테 프로젝트용 도구(정적 분석 등) 만들게 시키셈. 테스트 유도하고 CI 파이프라인(GitHub Actions) 태우면 테스트 가능한 코드가 나오고, 그게 곧 아키텍처 개선으로 이어짐.

• AI한테 유지보수 시키셈.

• 주요 모듈 폴더마다 가벼운 AGENTS.md 두셈. 루트에 있는 건 색인 역할. 에이전트가 삽질하면 바로 가이드 업데이트하셈.

• 코드 이해 못 하면 곧 벽에 부딪힐 거임.

• AI한테 시키면 파일 하나에 코드를 다 때려 박음. 1만 줄짜리 리액트 패널 만든 거 보고 컴포넌트로 쪼개라고 시켰더니 사용량 제한 걸림.

• 유지보수 못 함.

• 클로드 코드 + Opus 4.5 마스터하고 싶은데 관련 영상이나 튜토리얼 공유 좀. 학술 연구자인데 아이디어 구현하고 테스트하는 과정에서 Opus 4.5 다루기가 너무 힘듦.

from reddit