MODULE 05 — 레거시 시스템 분석·문서화 + Codex 병용

01개념 · 15분

소스에서 문서를 뽑는다

질문으로 시작 — "인수인계 문서가 부실한 시스템을 맡아본 분?" (전원 손 든다)

핵심 메시지문서는 없어도, 소스는 거짓말을 안 한다.

활용 시나리오	결과물 (전부 문서다)
① 신규 투입자용 시스템 소개	구조·업무 흐름 문서
② 목록 추출	화면-테이블-배치 매핑표
③ 영향도 분석	"이 컬럼 바꾸면 어디가 영향?"
④ 로직 해설	낡은 쿼리·코드 해설 문서

도구가 여러 개다 — Codex

Codex = OpenAI의 코딩 에이전트. 개념은 Claude Code와 동일(폴더 접근·실행·파일 생성). 오늘의 관점: 같은 일을 두 에이전트에 시켜 교차 검증.

기준	권장
문서·분석·범용 업무 에이전트	Claude 중심
코드 중심 작업 보조	Codex 병용
중요한 분석 (영향도 등)	둘 다 시켜 교차 검증

신뢰 수준영향도 분석 결과는 "후보 목록"이다 — 최종 판단은 사람. 가치는 사람보다 누락이 적다는 것. "AI가 찾은 것에서 오답 걸러내기"가 "사람이 처음부터 다 찾기"보다 빠르고 안전하다.

02시연 1 · 12분

시스템 소개 문서 자동 생성

샘플: module5/legacy-src/ — 주석도 문서도 없는 JSP/Java/SQL.

Claude Code — 에이전트 (작업 폴더: legacy-src/)

이 폴더는 문서가 하나도 없는 레거시 주문관리 시스템 소스다. 다음 달 신규 투입자에게 줄 시스템 소개 문서를 만들어줘. - 시스템이 하는 일 (업무 관점 요약) / 전체 구조 (화면→처리→테이블 흐름) - 화면 목록과 사용하는 테이블 매핑표 / 배치 목록과 실행 주기 - 신규 투입자 주의 포인트 (하드코딩, 위험해 보이는 부분)

src/ 7개, web/ 3개, sql/ 3개 파일 분석 중…

업무 흐름 복원 완료

■ 시스템 요약 (소스에서 복원) 주문 접수(10) → 결제완료(20) → 주문확정(30) → 배송중(40) → 배송완료(50), 취소(90) 화면 3종(목록/상세/로그인) + 배치 3종(정산 02:00 · 등급 매월 1일 · 알림 09:00) ■ 신규 투입자 주의 포인트 · DBUtil.java — DB 접속정보(IP·계정·비밀번호) 하드코딩 · OrderDao.getOrderList — 상태 조건을 문자열 결합 (SQL 인젝션 위험) · CodeUtil.java — 상태코드-명칭이 코드에 하드코딩 (DB 코드 테이블 없음) · notify_batch.java — 상태코드를 숫자로 변환해 비교 (parseInt ≥ 30) · OrderService TODO 주석 — 2015년 WMS 전송 배치 이관 이력

docs_generated/시스템소개.mddocs_generated/화면_테이블_매핑.md

03시연 2 · 13분

영향도 분석 — Claude vs Codex 교차 검증

같은 질문을 Claude와 Codex에 각각 던진다.

ORDER_MST 테이블의 ORD_STAT 컬럼의 코드값을 변경하려 한다.
영향받는 파일·화면·쿼리·배치를 전부 찾아서
파일명, 위치(함수/라인), 영향 내용, 위험도로 표를 만들어줘.

영향 지점	Claude	Codex	비고
OrderDao.java — 조회·변경 쿼리 4곳	✓	✓	공통 발견 = 신뢰도 높음
OrderService.java — 상태 전이 하드코딩	✓	✓
order_list.jsp / order_detail.jsp — 표시·버튼 분기	✓	✓
daily_settle.sql / grade_batch.sql — WHERE 절	✓	✓	집계 누락 위험
CodeUtil.java — 코드-명칭 하드코딩 배열	✓	—	함정 1: 한쪽만 발견 → 추가 확인 대상
notify_batch.java — parseInt(stat) ≥ 30 숫자 비교	✓ 런타임 오류 경고	✓	함정 2: 영숫자 코드로 바꾸면 즉사

04실습 · 60분

직접 해보기

미션 1

신규 투입자용 문서 생성

20분

시연 1과 같은 과제 + 본인이 궁금한 항목 1개 이상 추가 (예: "예외 처리가 허술한 곳", "성능 걱정되는 쿼리").
생성된 문서에서 2개 항목을 골라 소스와 직접 대조 검증.

예상 결과 화면 보기

Claude Code — 에이전트 (작업 폴더: legacy-src/)

이 폴더는 문서가 하나도 없는 레거시 주문관리 시스템 소스다. 다음 달 신규 투입자에게 줄 시스템 소개 문서를 만들어줘. - 시스템이 하는 일 (업무 관점 요약) / 전체 구조 (화면→처리→테이블 흐름) - 화면 목록과 사용하는 테이블 매핑표 / 배치 목록과 실행 주기 - 신규 투입자 주의 포인트 (하드코딩, 위험해 보이는 부분)

src/ 7개, web/ 3개, sql/ 3개 파일 분석 중…

업무 흐름 복원 완료

■ 시스템 요약 (소스에서 복원) 주문 접수(10) → 결제완료(20) → 주문확정(30) → 배송중(40) → 배송완료(50), 취소(90) 화면 3종(목록/상세/로그인) + 배치 3종(정산 02:00 · 등급 매월 1일 · 알림 09:00) ■ 신규 투입자 주의 포인트 · DBUtil.java — DB 접속정보(IP·계정·비밀번호) 하드코딩 · OrderDao.getOrderList — 상태 조건을 문자열 결합 (SQL 인젝션 위험) · CodeUtil.java — 상태코드-명칭이 코드에 하드코딩 (DB 코드 테이블 없음) · notify_batch.java — 상태코드를 숫자로 변환해 비교 (parseInt ≥ 30) · OrderService TODO 주석 — 2015년 WMS 전송 배치 이관 이력

docs_generated/시스템소개.mddocs_generated/화면_테이블_매핑.md

미션 2

영향도 분석

15분

CUST_INFO 테이블의 CUST_GRADE 컬럼을 1자리에서 2자리로 확장하려 한다.
영향받는 곳을 전부 찾아 파일명/위치/영향 내용/위험도 표로 정리해줘.

예상 결과 화면 보기

Claude Code — 에이전트

영향 지점 6곳 발견

· tables.sql — CUST_INFO.CUST_GRADE VARCHAR2(1) → DDL 변경 필요 · CustomerDao.java — 조회/갱신 (길이 무관하나 확인 대상) · CodeUtil.getGradeNm — equals("V") 등 1자리 전제 · login_check.jsp — substring(0,1) 사용: 1자리 전제 로직 ★ 최고 위험 · grade_batch.sql — CASE 'V'/'G'/'S'/'N' 산정 값 · order_detail.jsp — 등급명 표시 (간접)

받은 표에서 2건 이상 원본 소스로 직접 확인한다.

미션 3

Codex 교차 실행 + 비교표

15분

미션 2와 같은 과제를 Codex로 실행.
비교표 작성: 찾은 지점 수 / 한쪽만 찾은 것 / 문서 품질 / 소요 시간.

Codex 미설치자 — Claude에게 같은 과제를 표현을 바꿔 2회 시키고 결과 차이를 비교 (교차 검증 개념은 동일하게 체험).

미션 4

(여유 시) 본인 시스템 적용

10분

보안 허용 범위의 본인 담당 소스 일부로 미션 1 재실행. 불가하면 미션 1 문서의 완성도 올리기.

05공유 · 20분

마무리

취합 — 비교표 결과를 화이트보드에: 두 도구가 각각 잘 잡은 것 → "도구는 취향이 아니라 용도로 고른다".
논의 — "우리 시스템 인수인계 문서, 이걸로 만들 수 있겠는가?" 만든다면 무엇부터?
미니 과제 — 본인 담당 시스템에서 "문서로 뽑고 싶은 것" 목록 (보안 검토 포함).