Codex cli 잘 활용하기!

Codex cli 잘 활용하기!

업무하다가 “이거 그냥 나 대신 해주면 안되나…” 싶은 순간이 하루에 한 번은 온다.(사실 1329874287번)

그래서 요즘은 claude codex gemini같은 cli들을 정말 많이 사용한다.
근데 이것도 그냥 막 쓰면,

• 뭔가 열심히는 하는데 결과가 애매하거나
• 작업 범위가 커져서 내가 불안해지거나
• 세팅 때문에 처음부터 헤매거나(저요 저)

이런 일이 아주 많이 생긴다.

물론 cli에게 대충 ~~해줘 라고만 하더라도 해야 할 일의 “삽질과 노가다의 양”이 확실히 줄지만ㅎㅎ
우리의 더 나은 생상성과 효율을 위해 “Codex CLI를 덜 헤매고, 더 안전하게, 더 잘” 사용하는 방법을 정리해보겠다.

https://developers.openai.com/codex/cli/features

Codex CLI features

 

---

Codex CLI란?

https://openai.com/ko-KR/codex/

 

Codex CLI는 Open AI의 터미널에서 돌아가는 코딩 에이전트라고 보면 된다.
대화로 지시하면 프로젝트 파일을 읽고, 수정하고, 필요하면 명령도 실행한다.

특히 아래 경우에서 체감이 컸다.

• 반복 작업(리팩토링/정리/테스트 보강)에서 속도 이득
• “내가 놓친 거”를 코드리뷰처럼 잡아줄 때
• 쉘에서 바로 이어서 작업하니까 컨텍스트 전환이 덜함
• 마이크로 서비스의 경우 연관되는 n개의 서비스를 한번에 처리할 수 있음

---

0. 설치

설치는 공식적으로 npm 또는 Homebrew 가 많이 쓰인다. OpenAI Developers

Quickstart

(참고로 저는 맥북)

# npm
npm install -g @openai/codex

# homebrew
brew install codex

Codex CLI는 기본적으로 현재 디렉터리를 기준으로 파일을 읽고 바꾸니까, 프로젝트 루트에서 시작하는 게 마음 편하다.

---

1. 제일 먼저 해야 하는 것: “안전장치” 깔기

Codex는 코드베이스를 수정할 수 있다 보니, 공식 문서에서도 Git 체크포인트를 두는 걸 권장한다.

이런식으로 루틴으로 고정하면 좋다.

git checkout -b chore/codex-work
git status

그리고 Codex에게도 아예 이렇게 시킨다.

• “변경은 최소 단위로, 커밋은 자주 쪼개기”
• “바꾸기 전에 계획 먼저 설명하기”
• “실행/삭제 같은 위험 작업은 사전 승인 받기”

이걸 안 해두면, 나중에 diff 보고 “이게 왜 이렇게 됐지…?” 하게 된다(경험담 ㅠ).

---

2. Codex 에게 “작업지시서”처럼 요구하기

그냥 “리팩토링해줘”라고 하면 결과가 들쭉날쭉할 확률이 높다.
대신 아래 3가지를 꼭 붙이면 체감이 확 올라간다.

2-1) 목표(Outcome)

• “A와 B가 동일 출력 유지하면서 공통 함수로 분리”처럼 검증 가능한 형태로

2-2) 제약(Constraints)

• “외부 동작 동일”
• “테스트는 수정하지 말기”
• “public API 시그니처 변경 금지”
• “성능 영향 최소화”

2-3) 검증(Verification)

• “수정 후 npm test 실행하고 실패 시 롤백 제안”
• “변경 파일 리스트 + 핵심 diff 요약”

이렇게 주면 Codex가 “뭘 해야 하는지”를 덜 추측한다.

2-4) 절차(steps)

여기서 진짜 중요한 꿀팁이 하나 더 있다.

해야 하는 순서를 대략적으로라도 steps로 써주면 Codex가 일을 추측하는 비율이 줄어든다.

예를 들면 이런 느낌이다.

• 절차(steps)
  1. 관련 파일/로직 위치 찾기
  2. 변경 계획 3줄로 먼저 제시하기
  3. 최소 diff로 수정하기
  4. 테스트/린트 실행하기
  5. 실패하면 원인 요약 + 수정안 제시하기
  6. 성공하면 변경 요약 + 위험 변경 여부 체크하기

사람한테도 “이렇게 이렇게 해줘”가 명확하면 일이 잘 되듯이, 에이전트도 보다 잘 수행하는 것 같다.

 

난 보통 이런식으로 프롬프트를 작성한다.

• 목표
• 내가 codex에게 주는 input
• codex가 만들어야하는 output
• 현재 상황이나 문제 상황에 대한 구체적이지만 간결한 설명
• 절차
• 제약
• 검증

 

---

3. 슬래시 커맨드

Codex CLI는 터미널 UI 세션에서 슬래시 커맨드로 제어할 수 있다.

OpenAI Developers

Slash commands in Codex CLI

자주 사용하는 커멘드 위주로 손에 익으면 작업 속도가 훨씬 빨라져서 좋다.

 

---

4. “exec”로 반복 작업 자동화하기

Codex는 반복 가능한 워크플로우를 스크립팅할 수 있게 exec 같은 방식도 제공한다.

codex(대화형 UI)로 들어가는 게 아니라, 한 번의 명령으로 작업지시서를 실행하는 모드라고 보면 된다.

4-1) 일단 기본은 이렇게 시작한다

codex exec "<한 문장 작업지시서>"

근데 여기서 중요한 포인트가 있다.

• 기본적으로는 안전하게(읽기 위주로) 실행되는 편이라, 파일을 실제로 수정하게 하려면 권한/모드를 같이 주는 게 일반적이다
• 자동화용으로는 --full-auto 같은 옵션을 붙여서 “읽기→수정→검증” 루프를 한 번에 타게 만든다

루프 컨셉 예시 1

• 린트/포맷 → 테스트 → 변경 요약 → PR 메시지 초안

여기서도 2번에서 말한 것처럼 절차(steps)를 같이 써주는 게 핵심이다.

codex exec --full-auto \
"목표: 린트/포맷/테스트가 모두 통과하도록 최소 변경을 적용하기.

절차:
1) 린트 실행하고 실패 원인 요약하기
2) 포맷 적용하기
3) 테스트 실행하기
4) 실패하면 최소 diff로 수정하기(관련 없는 리팩토링 금지)
5) 성공하면 변경 요약 + PR 메시지 초안을 작성하기

제약: 동작(출력/예외/로그/공개 API) 변경 금지, 변경 범위는 src/ 와 tests/ 로 제한, 커밋은 하지 않기.
검증: 최종 테스트 커맨드 실행 결과를 붙이고, 변경 파일 리스트와 위험 변경 여부를 명시하기." 

이런 식으로 한 문장(한 번의 exec)으로 묶이면, 그 순간부터 진짜 도구가 된다.

루프 컨셉 예시 2

• 특정 폴더의 import 정리 → 타입 에러 해결 → 위험 변경 여부 체크

codex exec --full-auto \
"목표: src/modules/payments/ 아래의 import를 정리하고 타입 에러를 0으로 만들기.

절차:
1) 해당 폴더에서 타입 에러/린트 에러 위치를 먼저 정리하기
2) import 정리(불필요 import 제거, 정렬) 수행하기
3) 타입 에러를 최소 변경으로 해결하기
4) 다시 typecheck 실행하기
5) 변경 요약 + 위험 변경 여부 체크하기

제약: public API 시그니처 변경 금지, 동작 변경 금지, 수정 범위는 src/modules/payments/ 로 제한.
검증: typecheck(또는 tsc) 실행 결과 요약 + 변경 파일 리스트 제공." 

여기서도 절차(steps)를 안 적으면 Codex가 범위를 크게 잡아버리는 경우가 생긴다. 그래서 난 아예 steps를 기본 템플릿처럼 넣는 편이다.

 

요즘 아주 체감 중인데,

 

자주 하는 작업을 “한 문장”으로 돌릴 수 있게 만드는 순간부터, 진짜 도구가 된다.😆

---

5. MCP

Codex는 MCP(Model Context Protocol)로 외부 도구/컨텍스트를 붙일 수 있다.

이걸 쓰면, 예를 들어:

• 사내 문서 검색 도구
• 이슈 트래커
• 내부 API 스펙 도구

같은 걸 “Codex가 쓸 수 있는 도구”로 만들 수 있고, 만들어진 걸 사용할 수 있다.

 

MCP가 좋은 이유는

• Codex가 “추측”으로 답하지 않고
• 실제 도구를 호출해서 근거를 가져오고
• 그걸 기반으로 코드 변경까지 이어갈 수 있게 된다는 점이다.

개발할 때 서비스에 대한 공식 document들을 늘 참고해야하므로 AWS, github와 같은 mcp들을 많이 사용한다.

5-1) MCP 붙이는 방식

1. CLI로 추가하기

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp list

대화형 세션에서는 /mcp로 “지금 붙어있는 MCP 도구 목록”을 확인할 수 있다.

 

2. ~/.codex/config.toml을 직접 수정하기

# 예시(컨셉)
[mcp_servers.internal_docs]
command = "npx"
args = ["-y", "@your-org/internal-docs-mcp"]
env = { DOCS_BASE = "/path/to/docs" }

사용 예시 1

• “internal_docs MCP 도구로 ‘JWT refresh’ 문서 검색하고, 운영/보안 제약을 10줄로 요약하기. 그 제약을 반영해서 코드 수정 체크리스트를 만들기.”

사용 예시 2

• “issue_tracker MCP로 ABC-123 이슈를 읽고 요구사항/수용기준(AC)을 정리하기. 현재 브랜치 diff가 AC를 만족하는지 체크하고 부족한 부분만 최소 diff로 수정하기. 마지막에 이슈 코멘트에 붙일 요약 작성하기.”

!! MCP는 보안/운영 관점에서 한 번 더 확인하고 쓰는 게 좋다 !!

MCP는 “외부 도구를 실행/연결”하는 성격이 있다 보니, 레포를 처음 받았을 때는 아래 정도는 한 번 보는 편이 안전하다.

• CODEX_HOME 같은 환경변수가 레포에서 강제로 바뀌지 않는지
• ~/.codex/config.toml(또는 로컬 프로필)에 수상한 MCP 서버 커맨드가 등록되어 있지 않은지

---

6. 결론

정리하면,

1. Git 안전장치 먼저
2. Codex에게는 작업지시서 형태로 말하기
3. 인터랙티브에서는 슬래시 커맨드로 제어
4. 반복 작업은 exec로 자동화
5. 가능하면 MCP로 도구까지 연결

이제 끝! 바이~