CI 설정도 없다. Codex CLI가 설치되어 있고 인증되어 있으면 지금 바로 실행할 수 있다.
1-1. 낯선 저장소 빠르게 파악하기
처음 들어온 저장소가 어떻게 생겼는지, 어떤 부분이 복잡한지 빠르게 파악하고 싶을 때 쓴다. 저장소 루트에서 아래 한 줄을 실행하면 된다.
복붙하고 바로 실행
codex exec --sandbox read-only \
"이 저장소 구조를 요약하고, 복잡하거나 위험해 보이는 파일 3개를 경로와 함께 알려줘" \
> summary.md
ex)
- 응답 예시 (터미널 출력)
- summary.md 파일도 생성해서 해당 파일에 작성해 두었다.
결과가 summary.md 파일로 저장된다. --sandbox read-only는 Codex가 파일을 읽기만 하고 수정하지 않도록 막아준다. 처음엔 항상 이 플래그를 붙인다.
1-2. 특정 파일 집중 검토하기
새로 작성한 파일이나 수정이 많았던 파일을 빠르게 검토하고 싶을 때다. 파일 경로를 프롬프트에 직접 넣으면 된다.
복붙하고 파일명만 바꿔서 실행
codex exec --sandbox read-only \
"src/components/features/auth/Auth.tsx 파일을 검토해줘. 보안 문제나 빠진 예외 처리가 있으면 줄 번호와 함께 알려줘."
실행하면 이런 결과가 나온다
## 검토 결과: src/auth/login.ts
보안 문제
- 34번째 줄: password를 평문으로 로그에 출력 중 (console.log 제거 필요)
- 52번째 줄: 로그인 실패 횟수 제한 없음, brute-force 공격에 취약
빠진 예외 처리
- 67번째 줄: DB 연결 실패 시 500 에러가 그대로 클라이언트로 전달됨
- 89번째 줄: JWT 만료 토큰 처리 없음
ex) 실제로 수정해야하는 이슈들이 도출되었아. (실제 결과는 생략)
1-3. 커밋 전 30초 안전 체크
코드를 수정하고 커밋하기 직전, "혹시 놓친 게 있나?" 싶을 때 쓴다. 변경 내용을 파일로 저장해서 Codex에게 넘기는 패턴이다.
복붙하고 바로 실행 (git add 하기 전에 실행)
# 1. 변경 내용을 파일로 저장
git diff > /tmp/my-changes.txt
# 2. Codex에게 검토 요청
codex exec --sandbox read-only \
"/tmp/my-changes.txt 파일을 보고, 버그나 빠진 부분이 있으면 알려줘. 없으면 '이상 없음'이라고 해줘."
ex) 결과 예시
왜 파일로 저장하고 넘기나?
Codex는 지시한 파일을 직접 읽는다. git diff 출력이 길어도 파일로 넘기면 안정적으로 처리된다. 터미널 명령 중간에 직접 붙여 넣으면 내용이 잘리거나 파싱에 실패할 수 있다.
레벨 1 핵심 정리
--sandbox read-only를 항상 붙인다 — 파일을 수정하지 않으므로 실수할 걱정 없다
> 파일명.md로 결과를 저장한다 — 나중에 다시 보거나 팀에 공유할 수 있다
프롬프트에 파일 경로와 원하는 출력 형식을 명시할수록 결과가 구체적이다
레벨 2 — 팀 저장소에 등록하기
레벨 1 명령어가 익숙해지면, 팀원 누구나 같은 명령을 쓸 수 있도록 저장소에 등록한다.
복잡한 설정 없이 package.json 스크립트로 충분하다.
2-1. npm script로 팀 공유하기
package.json의 scripts에 등록하면 팀원 모두 npm run codex:check으로 같은 검토를 실행할 수 있다.
package.json에 추가하기
{
"scripts": {
"codex:check": "mkdir -p reports && codex exec --sandbox read-only 'src/ 폴더에서 타입 오류나 버그 가능성이 있는 부분을 파일 경로와 함께 알려줘' > reports/check.md && echo '완료: reports/check.md를 확인하세요'",
"codex:review-diff": "git diff > /tmp/pr-diff.txt && codex exec --sandbox read-only '/tmp/pr-diff.txt 파일을 보고 문제가 있으면 알려줘' > reports/diff-review.md"
}
}
ex) 상기 스크립트 추가
- 추가한 스크립트 실행 및 결과 예시
팀원은 이제 npm run codex:check 또는 npm run codex:review-diff만 치면 된다. 긴 명령어를 외울 필요가 없다.
reports/ 폴더 처리 팁
결과 파일이 저장되는 reports/ 폴더를 .gitignore에 추가하면 검토 결과가 커밋에 포함되지 않는다.
# .gitignore에 추가
reports/
2-2. 프롬프트를 파일로 관리하기
검토 기준이 길어지거나, 팀 내 리뷰 관점을 통일하고 싶다면 프롬프트를 파일로 분리한다. 파일로 관리하면 리뷰 기준 변경도 PR로 리뷰할 수 있다.
.github/codex-prompts/review.md 파일을 만들고:
이 코드를 리뷰해줘. 아래 관점으로만 확인하고, 코드는 수정하지 말아줘.
확인할 것:
- 버그나 논리 오류
- 빠진 예외 처리
- 보안 취약점 (SQL injection, XSS, 노출된 시크릿 등)
- 테스트가 필요한데 없는 함수
결과 형식:
각 문제를 "파일경로:줄번호 — 문제 설명" 형식으로 나열해줘.
문제가 없으면 "이상 없음"이라고만 해줘.
ex) 나의 경우는 AI에게 생성 요청하였다.
- 내 nextjs 프로젝트 기준, 프로젝트 폴더 기준에 맞게 변경하여 등록 해 보았다.
이 저장소의 코드를 리뷰해줘. 코드는 수정하지 말고, 아래 관점으로만 확인해줘.
리뷰 대상:
- 현재 git diff가 있으면 변경된 파일과 그 영향 범위를 우선 확인한다.
- diff가 없으면 `src/app`, `src/components`, `src/services`, `src/hooks`, `src/utils`, `src/constants`, `tests`를 중심으로 확인한다.
- 명확한 근거가 있는 문제만 보고하고, 단순 취향이나 스타일 취향은 제외한다.
프로젝트 전제:
- Next.js 16 App Router, React 19, TypeScript strict mode, Tailwind CSS 4 기반이다.
- 라우팅, 공개 경로, SEO metadata, AdSense 배치, API 프록시(`/api`, `/crawl`)가 사용자 영향도가 큰 영역이다.
확인할 것:
- 버그나 논리 오류: 라우팅 상수와 실제 페이지 경로 불일치, query param 처리 오류, 조건 분기 누락, 상태 갱신 순서 문제, 잘못된 memo/dependency 사용.
- Next.js App Router 경계: Server Component에서 브라우저 API 사용, Client Component에 필요한 `'use client'` 누락, `useSearchParams` 등 Suspense가 필요한 훅 사용 방식, hydration mismatch 가능성.
- 예외 처리 누락: API 호출 실패, 비정상 응답, 빈 데이터, 파일/파서 입력 오류, 환경 변수 누락, 외부 서비스 지연 또는 실패.
- 보안 취약점: XSS(`dangerouslySetInnerHTML`, markdown/html 변환, diff 렌더링), open redirect, 노출된 시크릿, 토큰/localStorage 취급, 인증 우회, 프록시/CORS 오용.
- SEO와 공유 메타데이터: title/description, canonical, OpenGraph, Twitter card, sitemap/robots 영향, 페이지 목적과 맞지 않는 metadata.
- AdSense와 성능: 정책 위반을 유도하는 문구나 보상형 UI, 광고/이미지 영역 예약 누락으로 인한 CLS, `next/image` 크기 지정 누락, LCP를 악화시키는 font/image 사용.
- 테스트 갭: 복잡한 분기, route guard, API 에러 상태, parser/formatter, hook, 주요 사용자 플로우에 필요한 Vitest 또는 Playwright 테스트 누락.
결과 형식:
- 각 문제를 `파일경로:줄번호 — 문제 설명` 형식으로 나열한다.
- 문제 설명에는 왜 실제 위험인지와 필요한 테스트가 있으면 함께 적는다.
- 문제가 없으면 `이상 없음`이라고만 쓴다.
on: pull_request — PR이 새로 열리거나 커밋이 추가될 때마다 자동 실행한다
permissions — 필요한 권한만 최소로 열어둔다. contents: read는 코드 읽기, pull-requests: write는 코멘트 달기에 필요하다
actions/checkout@v5 — PR의 코드를 내려받는다. 이게 없으면 Codex가 읽을 파일이 없다
prompt-file — 레벨 2에서 만든 프롬프트 파일을 그대로 재사용한다
sandbox: read-only — CI에서도 파일 수정 없이 읽기 전용으로만 실행한다
3-3. 실제로 어떻게 보이나
PR을 열면 몇 분 안에 Codex가 아래와 같은 코멘트를 자동으로 달아준다.
PR 코멘트 예시
## Codex 자동 리뷰 결과
발견된 문제
- src/payment/charge.ts:45 — 금액 계산에 부동소수점 오류 가능성 (정수 연산 권장)
- src/payment/charge.ts:67 — 결제 실패 시 롤백 처리 없음
- src/user/profile.ts:23 — XSS 취약점: 사용자 입력을 innerHTML에 직접 삽입
빠진 테스트
- charge() 함수의 실패 케이스 테스트 없음
이상 없는 파일: src/utils/format.ts, src/config/index.ts
주의: API key는 절대 코드에 직접 쓰지 않는다
워크플로우 파일에 key를 직접 쓰면 저장소에 노출된다. 반드시 ${{ secrets.OPENAI_API_KEY }} 형태로 참조한다.
레벨 3 핵심 정리
워크플로우 파일 1개, 프롬프트 파일 1개만 있으면 PR 자동 리뷰가 된다
API key는 GitHub secret에만 저장한다
처음에는 read-only로만 시작한다. 파일 수정이나 자동 커밋은 자동화가 안정적으로 동작한 뒤 천천히 추가한다
자동화 안전 규칙 5가지
자동화에서 문제가 생기는 대부분의 원인은 권한을 너무 넓게 열었거나, API key가 노출됐거나, 예상치 못한 입력이 프롬프트에 들어간 경우다. 아래 다섯 가지만 지키면 입문 단계에서 발생하는 대부분의 문제를 피할 수 있다.
처음엔 항상 read-only로 시작한다 — 파일을 수정하거나 커밋을 만드는 자동화는 read-only 리뷰가 안정적으로 돌아간 뒤에 추가한다
API key는 코드에 직접 쓰지 않는다 — 로컬은 환경변수, CI는 GitHub secret에만 저장한다. ~/.codex/auth.json 같은 파일도 git에 커밋하지 않는다
PR 본문이나 커밋 메시지를 프롬프트에 그대로 넣지 않는다 — 외부 기여자가 악의적인 지시문을 숨길 수 있다. 프롬프트는 내가 작성한 파일에서만 가져온다
결과는 파일이나 PR 코멘트로 남긴다 — 사람이 검토할 수 있는 형태로 남아야 자동화 결과를 신뢰할 수 있다
배포·push 자동화는 마지막에 추가한다 — 자동으로 코드를 수정하거나 push하는 단계는 수동 리뷰 → 파일 생성 → 제한된 브랜치 push 순서로 천천히 넓혀간다
정리
레벨
핵심 명령
결과
레벨 1
codex exec --sandbox read-only "..." > file.md
로컬에서 즉시 검토 결과
레벨 2
npm run codex:check
팀 전체가 같은 기준으로 검토
레벨 3
PR 오픈 시 워크플로우 자동 실행
PR마다 자동 리뷰 코멘트
세 레벨 모두 read-only로 시작하고, 결과를 파일이나 코멘트로 남기는 원칙이 공통이다. 이 두 가지만 지키면 자동화가 실수를 만들어도 코드베이스는 안전하다.
