AI 코딩 도구는 이제 많다.
하지만 생산성이 정말 오르는 팀은 모델이 좋아서가 아니라
에이전트가 참고할 규칙과 검증 루프를 먼저 세팅한 팀이다.

Builder.io의 글
The Perfect Cursor AI setup for React and Next.js도
결국 같은 얘기를 한다.
핵심은 기능 목록이 아니라, 문맥을 고정하고 결과를 자동으로 검증하는 흐름이다.

이 글에서는 그 원칙을 Cursor가 아니라
Codex를 기준으로 React/Next.js 프로젝트에 맞게 다시 정리해보겠다.

결론부터: Codex는 “설정”보다 “작업 환경 설계”가 중요하다

React와 Next.js에서 Codex를 잘 쓰려면 아래 네 가지가 먼저 잡혀야 한다.

  • 프로젝트 규칙을 한 곳에 적어둘 것
  • 어떤 문서를 우선 신뢰해야 하는지 정해둘 것
  • lint, typecheck, test를 검증 루프로 묶을 것
  • 에이전트가 한 번에 너무 큰 변경을 하지 않게 작업 단위를 작게 나눌 것

즉, Codex를 잘 쓰는 방법은
프롬프트를 화려하게 쓰는 게 아니라
좋은 기본 규칙 + 짧은 피드백 루프 + 명확한 코드베이스 문맥을 만드는 것이다.

왜 React와 Next.js에서 특히 설정이 중요할까

React와 Next.js 프로젝트는 AI가 실수하기 쉬운 지점이 꽤 분명하다.

  • 서버 컴포넌트와 클라이언트 컴포넌트 경계를 흐릴 수 있다
  • useEffect를 과하게 추가할 수 있다
  • 최신 라우팅 구조를 무시하고 예전 페이지 라우터 방식으로 코드를 만들 수 있다
  • Tailwind 클래스만 맞추고 접근성이나 상태 흐름은 놓칠 수 있다
  • 타입은 맞는 것처럼 보이지만 실제 런타임 흐름은 깨질 수 있다

그래서 이 스택에서는
AI가 “대충 돌아가는 코드”를 내놓는 것보다
우리 프로젝트 규칙을 어기지 않게 만드는 장치가 더 중요하다.

1. 가장 먼저 해야 할 일: AGENTS.md를 제대로 적기

Codex 계열 에이전트를 쓸 때 가장 먼저 손봐야 하는 파일은 보통 AGENTS.md다.
이 파일은 “우리 프로젝트에서 어떻게 일해야 하는가”를 고정하는 역할을 한다.

여기에는 최소한 아래 내용이 들어가야 한다.

  • 패키지 매니저는 무엇인지 (pnpm, npm, yarn)
  • 개발 서버/테스트/린트 명령어가 무엇인지
  • React와 Next.js에서 반드시 지켜야 할 규칙
  • 폴더 구조와 컴포넌트 배치 원칙
  • 스타일링 방식 (Tailwind, CSS Modules, styled-components)
  • 데이터 패칭 원칙
  • PR 전에 반드시 통과해야 하는 체크 항목

예를 들면 이런 식이다.

## 프로젝트 규칙

- Next.js는 App Router만 사용한다.
- 기본 컴포넌트는 서버 컴포넌트로 작성한다.
- 브라우저 API나 클라이언트 상태가 필요할 때만 `"use client"`를 추가한다.
- 데이터 패칭은 가능한 서버에서 먼저 처리하고, 꼭 필요하지 않다면 `useEffect`로 옮기지 않는다.
- 스타일링은 Tailwind CSS를 사용한다.
- 새 컴포넌트를 만들기 전에 `components/ui`의 기존 컴포넌트를 먼저 재사용한다.
- 의미 있는 변경 후에는 `pnpm lint`, `pnpm typecheck`, `pnpm test`를 실행한다.
- 명시적으로 요청받지 않았다면 새 의존성을 추가하지 않는다.

이 정도만 있어도 Codex의 출력 품질은 꽤 달라진다.
AI는 똑똑한 것 같아도, 기준이 없으면 매번 다른 스타일로 코드를 쓴다.

2. “무엇을 기억해야 하는가”를 규칙으로 분리하기

Builder 글이 Cursor의 Rules, Docs, Memories를 강조한 이유는 단순하다.
AI는 코드만 읽고도 어느 정도 일할 수 있지만,
팀의 취향과 예외 규칙은 코드만으로는 잘 못 배운다.

Codex에서도 같은 원칙을 적용하면 된다.

정리 기준은 이렇다.

  • 오래 유지될 규칙: AGENTS.md
  • 특정 폴더/기능에만 적용되는 규칙: 각 디렉터리의 문서 파일
  • 자주 틀리는 구현 포인트: 예제 코드와 테스트

예를 들어 Next.js 프로젝트라면 아래 항목은 문서로 명시해두는 편이 좋다.

  • app/ 아래 라우트 구성 규칙
  • 서버 액션 사용 기준
  • loading.tsx, error.tsx, not-found.tsx 처리 원칙
  • 캐싱/재검증 정책
  • 인증 상태를 어디서 읽는지
  • 공통 UI 컴포넌트의 import 경로

중요한 건
설명을 길게 쓰는 게 아니라 에이전트가 반복해서 참고할 수 있게 짧고 단정하게 적는 것이다.

3. 공식 문서를 우선 참조하게 만들어라

AI가 가장 자주 헷갈리는 순간은
“예전에 맞던 답”을 지금도 맞다고 가정할 때다.

특히 React와 Next.js는 변화가 빠르기 때문에
다음 우선순위를 미리 정해두는 게 좋다.

  1. React 공식 문서
  2. Next.js 공식 문서
  3. 팀 내부 규칙 문서
  4. 현재 저장소의 실제 코드

실제로 Codex에 일을 시킬 때도 이렇게 요청하는 편이 낫다.

이 저장소의 현재 라우팅 구조를 기준으로 작업해줘.
기존의 서버 우선 데이터 패칭 방식을 유지해줘.
프레임워크 동작이 애매하면 React와 Next.js 공식 문서 기준에 맞춰줘.

이 한 줄이 중요한 이유는
AI가 “비슷한 예제”가 아니라 이 프로젝트와 맞는 정답을 찾도록 방향을 잡아주기 때문이다.

4. ESLint와 TypeScript는 선택이 아니라 필수다

Builder 글에서도 lint 자동 수정 루프를 강하게 밀고 있는데,
이건 Codex에서도 거의 그대로 적용된다.

AI가 만든 코드는 얼핏 그럴듯해 보여도
실제로는 아래 같은 문제가 자주 생긴다.

  • 사용하지 않는 import
  • 잘못된 hook 사용
  • 타입 단언 남용
  • client/server 경계 위반
  • 접근성 속성 누락

그래서 React/Next.js 프로젝트에서 Codex를 쓴다면
적어도 아래 스크립트는 정리되어 있어야 한다.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "lint": "next lint",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  }
}

그리고 에이전트에게도 명시적으로 요구하는 편이 좋다.

변경 후에는 lint와 typecheck를 실행해줘.
수정한 영역에 테스트가 있으면 함께 실행해줘.
코드만 생성하고 끝내지 말고, 검증이 통과할 때까지 수정해줘.

핵심은 “코드 생성”에서 끝내지 않는 것이다.
생성 -> 검증 -> 수정이 한 묶음이어야 한다.

5. 테스트 기반 루프를 만들면 Codex가 훨씬 안정적이다

React와 Next.js에서 AI가 제일 잘하는 일 중 하나는
빈 화면에서 처음부터 모든 걸 맞히는 일이 아니라,
실패하는 조건을 보고 점진적으로 고치는 일이다.

그래서 새 기능을 만들 때는 아래 순서가 좋다.

  1. 먼저 테스트나 기대 동작을 적는다
  2. Codex에게 그 조건을 만족하는 최소 구현을 시킨다
  3. lint/typecheck/test를 돌린다
  4. 실패 원인을 보고 다시 수정한다

예를 들면 이렇게 요청할 수 있다.

`SignupForm` 컴포넌트 테스트를 먼저 작성해줘.
로딩 상태, 유효성 검사 오류 상태, 성공 상태를 포함해줘.
그 다음 테스트를 통과하는 최소 구현을 만들어줘.
컴포넌트는 작게 유지하고 기존 UI 컴포넌트를 재사용해줘.

이 방식이 좋은 이유는
AI가 멋있어 보이는 코드를 쓰는 대신
통과해야 할 기준을 중심으로 움직이게 만들기 때문이다.

6. 작업 단위는 작게 쪼개야 한다

Codex를 포함한 대부분의 에이전트는
한 번에 너무 많은 걸 시키면 품질이 급격히 흔들린다.

특히 아래 요청은 실패 확률이 높다.

  • “대시보드 전체를 새 디자인으로 갈아줘”
  • “Next.js 구조 전부 최신 방식으로 바꿔줘”
  • “상태 관리도 정리하고 성능도 개선하고 테스트도 추가해줘”

반대로 이런 요청은 훨씬 안정적이다.

  • “이 페이지를 서버 컴포넌트로 유지한 채 데이터 패칭만 정리해줘”
  • “이 폼에서 유효성 검사와 제출 상태만 분리해줘”
  • “이 파일의 useEffect를 줄이고 불필요한 상태를 제거해줘”

좋은 에이전트 사용법은
큰 일을 한 번에 맡기는 것이 아니라
작은 단위를 연속적으로 위임하는 것에 가깝다.

7. React/Next.js용 Codex 프롬프트는 이렇게 바꾸는 게 좋다

아래처럼 막연하게 시키면 결과가 흔들리기 쉽다.

이 페이지를 더 좋게 만들어줘.

반면 이렇게 조건을 걸면 훨씬 낫다.

이 페이지를 현재 Next.js 라우팅 구조에 맞게 리팩터링해줘.
클라이언트 컴포넌트로 바꾸지 말고 지금의 서버 렌더링 구조를 유지해줘.
새 의존성은 추가하지 마.
`components/ui`의 기존 컴포넌트를 우선 재사용해줘.
추상화를 늘리기보다 상태 흐름을 단순하게 유지해줘.
변경 후에는 lint와 typecheck를 실행해줘.

포인트는 두 가지다.

  • 기술 제약을 먼저 적는다
  • 검증 조건을 마지막에 붙인다

이 두 줄만 붙여도
AI가 “예쁜 코드”보다 프로젝트에 맞는 코드를 낼 확률이 올라간다.

8. 내가 추천하는 React/Next.js용 Codex 기본 체크리스트

새 프로젝트든 기존 프로젝트든, 시작점은 아래 정도면 충분하다.

  • AGENTS.md에 라우팅 구조, 스타일링, 데이터 패칭, 테스트 규칙 작성
  • package.json에 lint, typecheck, test 스크립트 정리
  • 공통 컴포넌트 경로와 재사용 원칙 명시
  • 서버 컴포넌트와 클라이언트 컴포넌트 경계 규칙 명시
  • 의존성 추가 금지 또는 승인 기준 명시
  • 큰 작업은 작은 단계로 나눠 요청
  • 구현 후 반드시 검증 명령 실행

여기까지 맞추면 Codex는 단순 코드 생성기가 아니라
팀 규칙 안에서 움직이는 보조 개발자에 가까워진다.

마무리

Builder의 Cursor 설정 글을 읽고 가장 동의했던 부분은
“좋은 AI 활용은 모델 선택보다 작업 환경 설계에 가깝다”는 점이다.

Codex도 마찬가지다.
React와 Next.js에서 정말 중요한 건
에이전트를 똑똑하게 보이게 만드는 프롬프트가 아니라, 틀리기 어려운 환경을 먼저 만드는 것이다.

정리하면 React/Next.js에서 Codex 설정의 핵심은 아래다.

  • 규칙은 AGENTS.md에 고정한다
  • 공식 문서와 저장소 패턴을 우선 참조하게 만든다
  • lint/typecheck/test를 작업 루프에 포함한다
  • 한 번에 큰 작업보다 작은 수정 단위로 맡긴다

이 네 가지만 지켜도
AI 코딩 경험은 꽤 안정적으로 바뀐다.

chanhee.kim's profile image

chanhee.kim

2026-03-27 16:32

Read more posts by this author