Claude Code를 사용하면서 개발 방식이 많이 바뀌었다.
프로젝트 전체를 기반으로 코드를 분석하고 수정할 수 있다는 것은 생각보다 컸다.
하지만 사용하면서도 여러 유튜브 영상이나 자료들을 보았는데 나는 단순하게 사용만 하고 있었다.
같은 분석을 반복하고, 같은 형태의 질문을 던지고, 이전 작업에 대한 정보는 에이전트가 잊을때가 있었다.
편해지긴 했지만 그냥 코딩을 대신 해주는 느낌에 그쳤었다.
카카오톡에서 GPT Pro 이용권을 5개월치 싸게 팔아 Codex를 써보기로 했다.
여러 자료들을 보면서 claude가 성능이 더 좋음을 인지하고 있었고, 실제로 단순하게만 사용했는데도 내 질문 대비 결과물이 claude가 더 나았다.
하지만 Codex도 새로운 모델들이 평이 좋았고, 사용량 문제도 있는데다가 학습용이기 때문에 Codex를 활용해보기로 했다.
Codex를 제대로 사용하기
Codex를 활용하면서 AI 도구를 활용하는 방법을 조금 더 학습해보기로 했다.
AI는 코드를 잘 만들어주는 도구, 질문 잘하면 좋은 결과물을 주는 모델 정도로 썼던 것에서 관점을 바꿔야 한다.
AI가 코드 생성기가 아닌 작업을 맡길 수 있는 시스템이 되어야 한다.
이 기능 구현해줘, 이 에러 고쳐줘 수준에서 그친다면 제대로 활용하는 사람과의 생산성 차이는 매우 클 것이다.
목표, 문맥, 제약, 완료 조건을 입력해야 한다.
형식적인 프롬프트가 아닌 작업을 일종의 계약처럼 명령하는 것이다. 어디까지 해야 하는지, 무엇을 건드리면 안되는지, 언제 작업이 끝난 것으로 간주할지
이러한 부분들을 명확하게 해주어야 결과가 안정적이다.
그럼 어떻게 이런 부분들을 쉽게 적용할 수 있을까?
AGENTS.md 적용
AI 도구를 활용할 때 중요한 것은 문서이다.
내가 작업하고 있는 이 저장소에서 AI가 어떻게 행동해야 하는지 정의하는 규칙서같은 것이다.
예를 들면 아래와 같다.
1
2
3
4
5
- 코드 수정 전 구조를 먼저 분석한다.
- 관련 파일을 먼저 식별한다.
- 변경 범위를 최소로 유지한다.
- DB, 환경변수는 직접 수정하지 않는다.
- 완료 조건에 검증 방법을 포함한다.
이렇게 했을 때 AI는 그럴싸한 결과물이 아닌 개발자의 통제선에서 예측 가능한 결과물을 만들어낼 수 있다.
그런데 여기에 또 너무 많은 내용을 담아서는 안된다. 자동 생성한 md 파일을 썼을 경우 오히려 역효과가 발생할 수 있다고 한다.
토큰 사용량이 과도하게 늘고, 간단한 작업에도 명령을 따르려고 하기 때문이다.
그렇다고 사용을 하지 말라는 뜻은 아니고 잘 사용해야 한다. 강제형을 조건부 권고형으로 작성하면 된다.
브랜치를 만들어라 같은 말 대신 새 기능이나 큰 변경은 브랜치를 권장으로, 전체 테스트를 돌려라 대신 로직 변경이 포함된 경우 관련 테스트 실행 이런 방식인 것이다.
저장소에서만 통하는 반드시 필요한 부분만 강제하고 나머지는 AI 판단에 맡기는 것이다. 특정 폴더는 건드리면 안된다 같은 것만 필수로 남기고 일반적인 개발 프로세스는 조건부로 바꾸는 것이 포인트이다.
AGENTS.md 예시
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
# AGENTS.md
## 목적
이 저장소에서 AI는 **예측 가능한 작은 변경**을 우선한다. 중고거래 플랫폼 특성상 거래 상태, 금액, 개인정보, 권한 관련 변경은 특히 보수적으로 다룬다.
## 우선순위
1. 사용자/거래 데이터 무결성
2. 기존 기능 안정성
3. 작은 변경 범위 유지
4. 읽기 쉬운 코드와 설명
## 반드시 지킬 것
- 코드 수정 전 요청과 직접 관련된 흐름을 먼저 확인한다. 최소한 **진입점(API/Controller)**, **비즈니스 로직(Service/UseCase)**, **데이터 모델(Entity/Schema)**, **검증/권한 코드**를 식별한 뒤 수정한다.
- 변경 범위는 최소로 유지한다. 요청과 무관한 리팩터링, 네이밍 정리, 포맷 변경은 함께 하지 않는다.
- 거래 상태 전이(`판매중`, `예약중`, `판매완료` 등)는 기존 규칙을 깨지 않도록 다룬다. 상태 전이 조건을 바꾸면 영향 범위를 설명한다.
- 금액, 수수료, 포인트, 정산, 환불, 쿠폰 등 **돈과 연결되는 로직**은 임의로 단순화하지 않는다. 기존 계산식과 예외 처리를 먼저 확인한다.
- 인증/인가, 사용자 식별, 소유권 검증은 우회하지 않는다. 판매자/구매자/관리자 권한 경계를 유지한다.
- 개인정보를 로그, 테스트 데이터, 예시 응답에 그대로 남기지 않는다. 전화번호, 주소, 계좌, 채팅 내용, 이메일은 마스킹한다.
- DB 스키마, 마이그레이션, 시드, 환경변수, 배포/인프라 설정은 작업 요구가 명확할 때만 수정한다. 수정 시 영향과 롤백 포인트를 함께 남긴다.
- 이미지/파일 스토리지 경로, 삭제 정책, 공개 URL 규칙은 함부로 변경하지 않는다.
- 완료 보고에는 **검증 방법**을 반드시 포함한다.
## 권장 작업 방식
- 먼저 관련 파일과 영향 범위를 짧게 정리한 뒤 작업한다.
- 새 기능이나 큰 구조 변경은 브랜치 작업을 권장한다.
- 로직 변경이 있으면 **관련 테스트만 우선 실행**한다. 자동화 테스트가 없으면 재현/검증 시나리오를 남긴다.
- API 요청/응답, 에러 코드, 이벤트 스키마가 바뀌면 관련 문서나 예시도 함께 갱신한다.
- 쿼리 변경이 있으면 N+1, 인덱스, 페이징, 정렬 조건 영향을 함께 점검한다.
- 동시성 가능성이 있는 로직(예약, 구매 확정, 상태 변경, 재시도 처리)은 **중복 요청**을 가정하고 확인한다.
## 도메인 체크포인트
### 상품
- 상품 생성/수정 시 소유권과 노출 상태를 확인한다.
- 삭제 대신 비노출/소프트 삭제 정책이 있으면 그 규칙을 따른다.
### 거래
- 예약/판매완료 전환 시 중복 처리와 되돌리기 가능 여부를 확인한다.
- 거래 취소, 분쟁, 신고 흐름이 연결되어 있으면 함께 확인한다.
### 채팅/알림
- 메시지 본문과 개인정보는 최소 범위로만 다룬다.
- 알림 발송 조건을 바꾸면 중복 발송 여부를 확인한다.
### 검색/목록
- 정렬, 필터, 페이지네이션 변경 시 기존 조회 성능과 캐시 영향을 확인한다.
### 리뷰/평판
- 거래 완료 조건과 리뷰 작성 가능 조건의 연결을 깨지 않는다.
## 변경하지 말아야 할 것
- 요청과 무관한 전역 리팩터링
- 운영 비밀값이나 외부 서비스 키
- 명시되지 않은 대규모 의존성 교체
- 근거 없는 성능 최적화 또는 캐시 도입
## 완료 조건
- 요청한 범위만 수정했는지 설명할 수 있다.
- 관련 권한, 상태 전이, 금액 계산이 깨지지 않았다.
- 관련 테스트 또는 수동 검증 시나리오를 제시했다.
- 필요한 경우 문서, 예시, 타입, 스키마를 함께 맞췄다.
## 확장 원칙
- 이 문서는 짧고 실제로 반복되는 규칙만 유지한다.
- 같은 실수가 두 번 이상 반복될 때만 새 규칙 추가를 고려한다.
- 더 구체적인 규칙이 필요하면 해당 하위 디렉토리에 별도의 `AGENTS.md`를 둔다.
우선 학습용 프로젝트이기 때문에 모두 한글로 작성한다.
Backend AGENTS.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
# AGENTS.md
## 목적
이 디렉토리의 AI 작업은 **중고거래 플랫폼 백엔드의 안정성**을 우선한다.
특히 거래 상태, 권한, 금액, 개인정보, 외부 연동은 보수적으로 변경한다.
## 우선순위
1. 사용자/거래 데이터 무결성
2. 인증/인가와 소유권 검증
3. 기존 API 계약 안정성
4. 작은 변경 범위 유지
5. 성능과 운영 안정성
## 반드시 지킬 것
- 코드 수정 전 요청과 직접 연결된 흐름을 먼저 확인한다. 최소한 **API 진입점**, **서비스/유스케이스**, **모델/스키마**, **권한/검증 코드**를 식별한 뒤 수정한다.
- 변경 범위는 최소로 유지한다. 요청과 무관한 리팩터링, 네이밍 정리, 포맷 변경은 함께 하지 않는다.
- 거래 상태 전이(`판매중`, `예약중`, `판매완료` 등)는 기존 규칙을 깨지 않도록 다룬다. 상태 조건을 바꾸면 영향 범위를 설명한다.
- 금액, 수수료, 포인트, 할인, 환불, 정산 등 **돈과 연결되는 로직**은 임의로 단순화하지 않는다. 기존 계산식과 예외 처리를 먼저 확인한다.
- 인증/인가, 사용자 식별, 리소스 소유권 검증은 우회하지 않는다. 판매자/구매자/관리자 권한 경계를 유지한다.
- 개인정보를 로그, 예시 데이터, 테스트 출력에 그대로 남기지 않는다. 전화번호, 주소, 이메일, 계좌, 채팅 내용은 필요 시 마스킹한다.
- DB 스키마, 마이그레이션, 시드, 환경변수, 배포/인프라 설정은 작업 요구가 명확할 때만 수정한다. 수정 시 영향과 롤백 포인트를 함께 남긴다.
- 외부 결제, 알림, 스토리지, 인증 제공자 연동은 관련 설정과 실패 케이스를 먼저 확인한 뒤 수정한다.
- 완료 보고에는 **검증 방법**을 반드시 포함한다.
## 권장 작업 방식
- 먼저 관련 파일과 영향 범위를 짧게 정리한 뒤 작업한다.
- 새 기능이나 큰 구조 변경은 브랜치 작업을 권장한다.
- 로직 변경이 있으면 **관련 테스트 우선 실행**을 권장한다. 테스트가 없으면 수동 검증 시나리오를 남긴다.
- API 요청/응답, 에러 형식, 이벤트 스키마가 바뀌면 관련 문서나 예시도 함께 갱신한다.
- 쿼리 변경이 있으면 N+1, 인덱스, 정렬, 페이지네이션, 락/트랜잭션 영향을 함께 점검한다.
- 예약, 구매 확정, 상태 변경, 재시도 처리처럼 동시성 가능성이 있는 로직은 **중복 요청**을 가정하고 확인한다.
## 도메인 체크포인트
### 상품
- 상품 생성/수정/삭제 시 작성자 소유권과 노출 상태를 확인한다.
- 삭제 대신 비노출 또는 소프트 삭제 정책이 있으면 그 규칙을 우선 따른다.
- 이미지/파일 삭제 정책과 공개 URL 규칙은 함부로 바꾸지 않는다.
### 거래
- 예약/판매완료/취소 전환 시 중복 처리, 경쟁 상태, 되돌리기 가능 여부를 확인한다.
- 거래 취소, 신고, 분쟁, 리뷰 가능 조건이 연결되어 있으면 함께 확인한다.
- 구매자와 판매자에게 보이는 상태가 다를 수 있음을 고려한다.
### 채팅/알림
- 메시지 본문과 개인정보는 최소 범위로만 다룬다.
- 알림 발송 조건을 바꾸면 중복 발송, 누락 발송, 비동기 재시도 영향을 확인한다.
### 리뷰/평판
- 리뷰 작성 가능 조건은 거래 완료 조건과의 연결을 깨지 않도록 유지한다.
- 평점 집계 로직은 반올림, 캐시, 비동기 집계를 사용하는지 먼저 확인한다.
### 검색/목록
- 검색 조건, 필터, 정렬, 페이지네이션 변경 시 기존 응답 계약과 성능 영향을 함께 확인한다.
- 지역, 카테고리, 상태 필터가 결합될 때 누락 조건이 없는지 본다.
## 변경하지 말아야 할 것
- 요청과 무관한 전역 리팩터링
- 운영 비밀값이나 외부 서비스 키
- 명시되지 않은 대규모 의존성 교체
- 근거 없는 캐시 도입 또는 성능 최적화
- 사용 중인 에러 코드 체계의 임의 변경
## 완료 조건
- 요청한 범위만 수정했는지 설명할 수 있다.
- 관련 권한, 상태 전이, 금액 계산, API 계약이 깨지지 않았다.
- 관련 테스트 또는 수동 검증 시나리오를 제시했다.
- 필요한 경우 문서, 타입, 스키마, 예시 응답을 함께 맞췄다.
## 이 문서에 추가할 규칙의 기준
- 이 디렉토리에서 반복적으로 발생한 실수이거나,
- 저장소 특성상 반드시 지켜야 하거나,
- AI가 자주 과하게 변경하는 영역일 때만 추가한다.
일반적인 개발 상식이나 상황별 선택이 가능한 절차는 가능한 한 권고형으로 유지한다.
Skills
Claude에도 있는 개념으로 반복 작업을 재사용 가능한 workflow로 만드는 것을 뜻한다.
skill은 많이 만드는 것이 아닌 반복되는 것을 묶는 것이 중요하다.
남들이 만들어놓은 skill을 그대로 활용해도 좋고, 내가 실제 작업을 하면서 두 번 이상 하게되는 작업이라면 그때부터 skill로 만들어 활용해도 좋다.
멀티에이전트
대부분의 Agent 사용자는 단일 에이전트만 사용하게 된다.
