학습 목표
- AI가 기존 기능을 망가뜨리지 않게 하기의 역할과 적용 조건을 설명할 수 있다.
- 수정 전 현재 변경사항과 관련 호출 경로를 분석하세요.
- 변경 diff와 실제 검증 결과·복구 지점을 기록하세요.
사전 지식
앞선 AGENTS.md와 프로젝트 지침 만들기를 먼저 읽으면 용어를 이해하기 쉽습니다. 이미 아는 내용이면 이 장부터 시작해도 됩니다.
개념 이해
기존 프로젝트를 수정할 때는 새 코드의 품질뿐 아니라 이미 동작하던 약속을 유지해야 합니다. 변경 전의 구조·호출 경로·데이터 형식을 파악하고 필요한 부분만 고칩니다.
코드 분석과 영향 범위
관련 화면·API·규칙·테스트·환경설정을 따라가며 수정이 닿는 경계를 적습니다. 한 함수가 다른 화면에서도 쓰이는지 검색합니다.
계획과 작은 수정
요구에 직접 필요한 최소 변경부터 진행합니다. 관련 없는 리팩터링과 의존성 업데이트를 같은 변경에 섞지 않습니다.
기존 기능·검증·diff
성공·실패·취소·권한 동작을 전후로 비교합니다. 변경 파일과 생성 파일·환경 파일이 포함됐는지 확인합니다.
롤백 전략
작업 전 저장 지점을 만들고 코드와 데이터 복구를 구분합니다. 공유 브랜치와 다른 사람의 작업을 덮어쓰지 않습니다.
실제 사용 사례
인증 오류 수정 중 프로필 데이터 스키마까지 바꾸면 영향이 커집니다. 인증 요청과 세션 cleanup만 고쳐 원래 프로필 저장 동작이 유지되는지 먼저 확인하세요.
단계별 실습
실습은 운영 서비스가 아닌 별도 연습 프로젝트에서 진행하세요. 기존 파일이 있다면 변경 전 기록을 남깁니다.
- 수정 전 현재 변경사항과 관련 호출 경로를 분석하세요.
- 영향 받는 기능과 보존할 행동을 적으세요.
- 한 가지 원인을 작은 수정으로 해결하세요.
- 변경 diff와 실제 검증 결과·복구 지점을 기록하세요.
코드와 프롬프트
아래 요청에서 대괄호 부분을 내 프로젝트에 맞게 바꾼 뒤 AI 도구에 전달하세요.
AI에게 요청하기
먼저 현재 프로젝트 구조와 관련 코드를 분석해줘. 기존 기능을 유지하면서 [요청 기능]만 구현하고 수정 전 영향 범위를 설명해줘. 불필요한 리팩터링을 피하고 작업 후 변경 파일, 실제 검증 결과, 미확인과 롤백 방법을 정리해줘.자주 발생하는 문제와 해결
| 문제와 원인 | 해결 방법과 확인 기준 |
|---|---|
| 요청 기능 외 파일이 대량 변경됨 | 불필요한 형식 변경과 재작성은 분리하고 diff를 다시 검토합니다. |
| 다른 작업자의 수정이 사라짐 | 현재 미커밋 변경을 보존하고 충돌 부분의 의도를 확인합니다. |
핵심 요약
- 먼저 읽고 변경 범위를 좁힙니다.
- diff와 회귀 확인으로 기존 기능을 보호합니다.
완료 확인
참고자료
확인 기준일: 2026-10-20. 요금·사용 한도·제품 기능·설정 경로는 변경될 수 있으므로 작업 직전 공식 문서와 설치 버전을 확인하세요.