[Codex] 하네스 엔지니어링으로 풀스택 개발 시작하기

0. 배경

최근에 React + Spring 기반 풀스택 프로젝트(ChaekList)를 시작하면서 “Codex를 활용한 하네스 엔지니어링 방식으로 개발”을 적용해봤다.

하네스 엔지니어링이란?

https://miniberry-coding.tistory.com/31

계획부터 구현까지 Codex를 통해서 작업이 가능하다

결론부터 말하면,

AI를 팀원처럼 만들어 “명확한 제한과 방향성을 명시하는 과정”이었다.

---

1. Codex 처음 사용하면서 느낀 점

처음에는 이렇게 생각했다.

• “Chat GPT보다 코드 조금 더 잘 짜주는 모델인가?”

실제로 써보니까 완전히 달랐다.

• 프로젝트 전체 구조를 읽음
• 실행 방법을 분석
• 작업을 계획

처음 실행했을 때 나온 결과:

• frontend / backend 구조 분석
• 실행 명령 자동 정리

“Codex는 실제로 프로젝트를 이해하고 상황에 맞는 코드를 제시한다”

---

2. 첫 기능: Health Check API 구현

Codex가 추천한 첫 작업은 GET /api/health 엔드포인트 만들기

• frontend + backend 연결 확인 가능
• 복잡한 도메인 없이 구조 검증 가능
• 개발 환경 정상 여부 체크 가능

결과:

• /api/health → {"status":"ok"}
• 실제 서버 실행 후 정상 응답 확인

여기까지는 매우 순조로웠다.

---

3. 예상 못한 문제: 테스트 깨짐

문제는 여기서 발생했다.

GradleWorkerMain ClassNotFoundException

그냥 넘어갈 수도 있었지만, 하네스 관점에서는 중요했다.

코드 → 테스트 → 검증

이 루프가 깨지면 드의 신뢰도가 떨어지기 때문

---

4. 문제 해결 과정

Codex에게 문제 해결을 맡겼다.

• 원인: Windows 사용자 경로의 비ASCII 문자 문제
• 해결: GRADLE_USER_HOME을 프로젝트 내부 경로로 변경

수정된 부분:

• gradlew.bat
• gradlew

결과:

BUILD SUCCESSFUL

 

이 순간이 중요했다.

“나는 지시한 뒤, 확인하고 승인만 하면 된다”

---

5. 프론트엔드 연결까지 완료

Next.js에서 /api/health 호출

• http://localhost:3000/api/health → 정상 응답
• rewrite 설정 통해 backend 연결

---

6. 리뷰에서 발견된 문제

Codex 리뷰 결과는 localhost 하드코딩 문제

http://localhost:8080

 

• 배포하면 깨짐
• 포트 바뀌면 깨짐
• 환경별 설정 불가능

“AI는 코드만 만드는 게 아니라, 리스크도 찾아준다”

---

7. 하네스 엔지니어링의 핵심: AGENTS.md

여기서 가장 중요한 작업을 했다.

AGENTS.md 중 일부

AGENTS.md 작성

• Codex 행동 규칙 정의
• 작업 범위 제한
• 검증 방식 지정
• 언어 설정 (한국어)

핵심 내용:

• frontend / backend 분리
• 테스트 필수
• PR 기반 작업
• 하드코딩 금지

효과:

• AI가 이상한 방향으로 안 감
• 매번 같은 설명 안 해도 됨
• 작업 품질 상승

---

8. Codex 사용 방식 변화

처음에는

codex "Read AGENTS.md first. Act as a backend specialist..."

지금은

codex "AGENTS.md를 먼저 읽고 backend 개발자 역할로 동작해..."

 

터미널에서 Codex를 사용했기 때문에 영어로 명령하는 것이 편하지만, AGENTS.md에 한글로 명시가 가능하고 CLI에서도 한글로 명령하는것이 가능했다.

생산성을 위해 한글로 전환하였다.

---

9. 가장 큰 깨달음

이번 경험에서 가장 크게 느낀 점:

에이전트는 도구가 아니다
하네스 엔지니어링을 통해 “환경을 어떻게 설계하느냐에 따라 성능이 결정된다”

---

10. 앞으로 방향

이제 다음 목표는:

• CI/CD 자동화
• Codex PR 리뷰 자동화
• 배포까지 연결

완전한 AI 기반 개발 파이프라인 구축

---

마무리

이번 경험을 통해 느낀 건 하나다.

“이제 개발자는 코드를 짜는 사람이 아니라
시스템을 설계하는 사람이 되어야 한다”

앞으로는 단순한 코딩보다
하네스 엔지니어링 능력이 더 중요해질 것 같다.