개발자 가이드 · 작업 18개
개발자를 위한 AI: 코딩 에이전트, 비용, 안전하게 맡기기
이미 코드 자동 완성과 채팅을 쓰고 있다면, 다음 단계는 저장소를 읽고 명령을 실행하고 풀 리퀘스트를 여는 에이전트예요. 시간이 절약되는지는 모델보다 설정에 더 달려 있어요. 첫 부분은 어떤 코딩 에이전트에도 통하고, Claude Code와 Codex 부분은 공식 문서를 바탕으로 각각의 명령, 파일, 설정을 다뤄요.
모든 코딩 에이전트
01
끝냈다는 걸 증명할 수 있는 작업을 에이전트에게 주기
에이전트는 “이걸 개선해 주세요”에는 실패하고, 검사로 끝나는 작업에는 성공해요. 통과해야 하는 실패 중인 테스트, 출력이 바뀌어야 하는 명령 같은 것이요. 작업에 증명 방법을 적어 두면 에이전트는 끝난 것처럼 보일 때 멈추지 않고 실제로 끝날 때까지 계속해요.
예시
“ISO 주 날짜를 처리하도록 날짜 파서를 고쳐 주세요. 2026-W01에 대한 새 테스트를 포함해 npm test -- dates가 통과하면 완료예요. 테스트는 바꾸지 마세요.” 에이전트는 테스트가 통과할 때까지 실행하고 출력을 붙여 넣어요. 나는 추측이 아니라 30줄짜리 diff를 검토하면 돼요.
하는 방법
- 1맡기기 전에 검사를 쓰거나 알려 주세요. 실패 중인 테스트, 또는 명령과 그 예상 출력이요.
- 2이 페이지의 프롬프트로 작업을 주고, 바꿔도 되는 파일과 안 되는 파일을 알려 주세요.
- 3검사는 에이전트가 직접 실행하고 최종 출력을 붙여 넣게 하세요.
- 4diff는 동료의 풀 리퀘스트처럼 검토하세요. 검사 통과는 리뷰의 시작이지 끝이 아니에요.
기본 제공
복사할 프롬프트
작업: [변경 내용]. 완료 기준: [테스트 또는 명령]이 통과하고 [예상 출력]을 출력해야 해요. 끝내기 전에 실행하고 결과를 붙여 넣어 주세요. 바꿔도 되는 것: [경로]. 바꾸면 안 되는 것: [경로], 의존성, 테스트. 통과시킬 수 없다면 검사를 우회하지 말고 멈춘 뒤 이유를 설명해 주세요.잘못되기 쉬운 지점
- 에이전트는 테스트를 약하게 고쳐서 통과시키기도 해요. 테스트 변경을 금지하고, diff에서 그런 부분을 찾아보세요.
- 검사 하나로 확인하기에 너무 큰 작업은 한 번에 맡기기에도 너무 커요. 나누세요.
02
다른 일을 하는 동안 클라우드에서 작업 돌리기
클라우드 에이전트는 자체 환경에서 내 저장소를 작업하고 검토할 변경 사항을 가지고 돌아와요. 그래서 내가 다른 일을 하는 동안 여러 작업이 돌아가요. 효과가 있는 건 명확하게 정의된 작업뿐이에요. 모호한 작업은 일일이 풀어 봐야 하는 커다란 diff로 돌아와요.
예시
점심 전 작은 작업 세 개: 의존성 하나 업그레이드, 빠진 데이터베이스 인덱스 추가, 불안정한 테스트 수정. 작업마다 자체 검사와 함께 클라우드 에이전트에 보내고, 오후에는 맥락을 세 번 전환하는 대신 풀 리퀘스트 세 개를 검토해요.
하는 방법
- 1내 코드가 있는 곳과 가까운 것을 고르세요. Codex Cloud, GitHub의 Copilot 클라우드 에이전트, Claude Code on the web이 있어요.
- 2그 환경에서 의존성을 설치하고 테스트를 실행할 수 있는지 확인하세요. 그게 안 되면 에이전트는 추측으로 일해요.
- 3위 작업처럼 작고 독립적인 작업을 각자의 검사와 함께 보내세요.
- 4풀 리퀘스트마다 자동 리뷰어가 먼저 읽게 하고, 그다음 직접 검토하세요.
기본 제공
복사할 프롬프트
이 저장소에서: [작업]. 맥락: [코드의 위치, 관련 이슈]. 완료 기준: 작업 환경에서 [테스트 또는 명령]이 통과하면 완료예요. 그 출력을 풀 리퀘스트 설명에 넣어 주세요. 풀 리퀘스트의 변경 줄 수는 [n]줄 미만으로 유지해 주세요. 더 필요하면 멈추고 어떻게 나눌지 제안해 주세요.잘못되기 쉬운 지점
- 설정하지 않은 시크릿이나 서비스가 필요한 테스트는 건너뛰거나 실패해요. 그런 테스트 없이 통과한 결과는 별로 증명하는 게 없어요.
- 관련된 코드에서 여러 에이전트가 일하면 서로 충돌하는 풀 리퀘스트가 나와요. 병렬 작업은 서로 다른 영역에 두세요.
03
내가 없어도 검사가 돌아가게 하기
기계가 확인할 수 있는 것에 리뷰 시간을 쓰지 마세요. 훅은 에이전트가 변경할 때마다 포매터, 린터, 테스트를 실행하고, 리뷰 봇은 내가 보기 전에 풀 리퀘스트마다 읽어요. 그러면 내 리뷰는 오타가 아니라 설계를 다뤄요.
예시
훅이 편집할 때마다 포매터와 단위 테스트를 실행해요. 에이전트의 변경으로 테스트 두 개가 깨지면, 에이전트가 훅 출력에서 실패를 보고 내가 보기 전에 고쳐요. 그다음 리뷰 봇이 처리되지 않은 오류 사례 하나를 지적하는데, 그건 내가 판단해요.
하는 방법
- 1빌드, 테스트, 린트 명령을 에이전트가 세션을 시작할 때마다 읽는 지침 파일에 넣으세요. 파일 이름은 에이전트마다 문서에 나와 있어요.
- 2Claude Code에서는 편집할 때마다 포매터와 테스트를 실행하는 훅을 추가하세요. 그러면 에이전트가 실패를 보고 고쳐요.
- 3모든 풀 리퀘스트를 봇이 리뷰하게 하세요. Codex에서 “Automatic review”를 켜거나, Copilot을 리뷰어로 요청하세요.
- 4에이전트가 같은 실수를 두 번 하면 테스트로 만들거나 지침 파일에 규칙으로 넣으세요.
기본 제공
복사할 프롬프트
이 저장소를 읽고 코딩 에이전트용 지침 파일을 써 주세요. 1. 설치, 빌드, 테스트, 린트, 포맷에 쓰는 정확한 명령. 2. 10줄 이내의 프로젝트 구조. 3. 이 저장소에서 새로 온 사람이 자주 틀리는 규칙과 각각의 예시 하나. 4. 이 저장소에서 에이전트가 절대 하면 안 되는 일. 예: 마이그레이션 변경, 생성된 파일 편집. 실제로 실행에 성공한 명령만 적고, 나머지는 “검증 안 됨”으로 표시해 주세요.잘못되기 쉬운 지점
- 더 이상 작동하지 않는 명령이 든 지침 파일은 에이전트에게 그 파일을 무시하라고 가르치는 셈이에요. 설정이 바뀌면 명령을 다시 실행해 보세요.
- 리뷰 봇도 자신 있게 틀려요. 봇의 코멘트는 제안으로 다루세요.
04
최소한의 권한으로 에이전트를 도구에 연결하기
에이전트는 볼 수 있는 것만큼만 잘해요. 이슈, 문서, 로그, 데이터베이스 스키마 같은 것이요. MCP가 이것들을 연결해 주지만, 모든 연결은 곧 접근 권한이고, 외부에서 읽어 온 텍스트에는 지시가 숨어 있을 수 있어요. 읽기 전용으로 시작하고, 작업에 필요할 때만 넓히세요.
예시
에이전트가 트래커에서 이슈 482를 읽고, 로그에서 스택 트레이스를 찾고, 라이브러리 문서를 확인한 다음 문제가 있는 파일을 짚어요. 모두 읽기 전용 토큰으로요. 수정은 내 저장소에 쓰고, 나는 평소처럼 그걸 검토해요.
하는 방법
- 1이슈, 오류 로그, 문서, 스키마처럼 채팅에 가장 자주 붙여 넣는 것을 적어 보세요. 그것부터 연결하세요.
- 2각각의 공식 MCP 서버를 읽기만 가능한 토큰으로 추가하세요. Gemini CLI에서는 확장 프로그램 하나에 MCP 서버와 그 설정을 함께 묶을 수 있어요.
- 3그 연결이 필요한 작업을 주고, 맞는 것을 호출했는지 확인하세요.
- 4몇 주마다 더 이상 쓰지 않는 서버를 제거하세요.
기본 제공
복사할 프롬프트
아무것도 바꾸기 전에: 트래커에서 이슈 [ID]를 읽고, 로그에서 오류를 찾고, [라이브러리] 문서를 확인해 주세요. 각각에서 알게 된 것과 어느 파일에 문제가 있다고 보는지 말해 주세요. 연결된 도구에는 아무것도 쓰지 마세요.잘못되기 쉬운 지점
- 웹 페이지, 이슈, 문서에는 에이전트를 조종하려고 쓴 텍스트가 들어 있을 수 있어요. 외부 콘텐츠를 읽는 도구에는 쓰기 권한을 주지 마세요.
- 설정 파일에 넣은 토큰은 유출돼요. 클라이언트의 시크릿 보관소나 환경 변수를 쓰고, 저장소에는 절대 넣지 마세요.
05
구독과 토큰당 결제 중에 고르기
에이전트 세션은 파일을 읽고 여러 단계를 실행하기 때문에 채팅보다 토큰을 훨씬 많이 써요. 고르기 전에 내 평소 사용량 일주일 치의 비용을 계산해 보세요. 구독은 직접 쓰는 사용량에 한도가 있고, 토큰당 과금은 자동 실행마다 한도를 걸 수 있어요.
예시
매일 에이전트를 쓰면 일주일에 입력 토큰 약 4,000만 개, 출력 토큰 300만 개가 돼요. API 가격 페이지에서 쓰는 모델 기준으로 비용을 계산해 구독 한 달 요금과 비교하세요. 구독이 더 싸고 한도가 내 일주일 사용량에 맞으면 구독을 택하고, CI용으로는 한도를 건 API 키를 따로 두세요.
하는 방법
- 1이미 돈을 내고 있는 게 뭔지 확인하세요. ChatGPT 플랜에는 Codex가, Claude 유료 플랜에는 Claude Code가 포함돼 있어요.
- 2에이전트가 토큰 사용량을 보여 주는 곳에서 평소 세션 몇 개의 사용량을 적어 두세요.
- 3그 사용량의 비용을 저희 API 가격 페이지에서 계산해 구독과 비교하세요.
- 4자동화와 CI에는 지출 한도를 건 API 키를 써서, 루프가 돌다가 요금이 불어나지 않게 하세요.
기본 제공
복사할 프롬프트
평소 세션 [n]개의 사용량이에요: [입력 및 출력 토큰]. 저는 일주일에 약 [일수]일 일해요. 이 가격 기준으로 토큰당 과금 시 월 비용을 추정해 주세요: [API 가격 페이지에서 붙여 넣기]. 월 [가격]인 구독과 비교해 주세요. 제가 확인할 수 있게 계산 과정을 보여 주세요.잘못되기 쉬운 지점
- 구독에도 사용 한도가 있어요. 작업 중간에 한도에 걸리면 시간을 잃어요. 가격만 보지 말고 한도도 확인하세요.
- 요금을 가장 크게 바꾸는 건 모델이에요. 실제로 쓰는 모델 기준으로 비교하세요.
Claude Code
06
CLAUDE.md로 모든 세션을 같은 출발점에서 시작하기
세션을 시작할 때마다 빌드 명령과 규칙을 설명하고 있다면, CLAUDE.md가 할 일을 직접 하고 있는 거예요. Claude는 세션을 시작할 때마다 이 파일을 읽어요. 짧고 정확하게 유지하면 같은 실수가 다시 나오지 않아요.
예시
Claude가 프로젝트의 pnpm test:unit 대신 계속 npm test를 실행하고, 생성된 파일을 계속 편집하던 저장소. CLAUDE.md에 올바른 명령과 “src/gen/은 절대 편집하지 말 것” 두 줄을 넣자 두 실수가 모두 멈춰요.
하는 방법
- 1저장소에서 /init을 실행하세요. 코드베이스를 분석해 기본 CLAUDE.md를 써 주거나, 이미 있는 파일의 개선점을 제안해요.
- 2빌드 및 테스트 명령, 코딩 표준 같은 팀 규칙은 ./CLAUDE.md에 두고 커밋하세요. 개인 취향은 모든 프로젝트에 적용하려면 ~/.claude/CLAUDE.md에, 이 프로젝트에만 적용하려면 CLAUDE.local.md에 넣으세요.
- 3긴 문서는 붙여 넣지 말고 가리키세요. @path/to/file은 시작할 때 다른 파일을 가져와요.
- 4Claude가 같은 걸 두 번 틀릴 때마다, 그걸 막았을 한 줄을 추가하세요.
복사할 프롬프트
이 저장소를 읽고 CLAUDE.md를 개선해 주세요. 60줄 미만으로 유지해 주세요. 1. 빌드, 테스트, 린트에 쓰는 정확한 명령. 2. 몇 줄로 요약한 프로젝트 구조. 3. 이 저장소에서 새로 온 사람이 자주 틀리는 규칙. 4. 절대 편집하면 안 되는 파일과 폴더. 더 이상 사실이 아닌 내용은 지워 주세요. 실행해 보지 않은 명령은 “검증 안 됨”으로 표시해 주세요.잘못되기 쉬운 지점
- CLAUDE.md의 모든 내용은 세션마다 불러와져 컨텍스트를 차지해요. 세부 내용은 CLAUDE.md가 가져오는 파일로 옮기세요.
- 더 이상 맞지 않는 지침은 없는 것보다 나빠요. 설정이 바뀌면 명령을 다시 확인하세요.
공식 문서에서: Claude Code docs: How Claude remembers your project
07
먼저 계획하고, 그다음 편집하게 하기
여러 파일에 걸친 변경에서 비싼 실수는 잘못된 한 줄이 아니라 잘못된 접근 방식이에요. plan 모드에서 Claude는 소스 파일을 편집하지 않고 조사해서 계획을 써요. 내가 계획을 바로잡은 다음 승인하면 돼요.
예시
14개 파일에 걸쳐 인증 방식을 쿠키에서 토큰으로 옮기는 작업. 첫 계획은 모바일 클라이언트를 빠뜨려요. 내가 짚어 주면 계획에 단계가 하나 추가되고, 그제야 Claude가 편집을 시작해요.
하는 방법
- 1상태 표시줄에 “plan mode on”이 나올 때까지 Shift+Tab을 누르거나, 프롬프트를 /plan으로 시작하세요.
- 2바꿀 내용과 바뀌면 안 되는 것을 설명하세요. Claude는 계획하는 동안에도 탐색을 위해 명령을 실행할 수 있지만, 파일은 편집하지 않아요.
- 3계획은 설계 메모처럼 읽으세요. 잘못된 파일, 빠진 경우, 너무 큰 변경이 없는지요. 맞을 때까지 수정을 요청한 다음 승인하세요.
- 4관련 없는 다음 작업을 하기 전에 /clear로 새로 시작하세요.
복사할 프롬프트
/plan [목표]를 위해 [무엇]을 바꿔 주세요. 제약 조건: [바뀌면 안 되는 것]. 건드릴 파일, 변경 순서, 각 단계를 증명할 테스트, 확실하지 않은 점을 나열해 주세요. 제가 승인할 때까지 아무것도 편집하지 마세요.잘못되기 쉬운 지점
- 예상보다 많은 파일을 건드리는 계획은 경고 신호예요. 승인하기 전에 이유를 물어보세요.
- plan 모드에서도 탐색을 위해 명령을 실행해요. 낯선 저장소를 안전하게 실행할 수 있게 해 주지는 않아요.
공식 문서에서: Claude Code docs: Choose a permission mode · Claude Code docs: Commands · Claude Code docs: Best practices
08
같은 명령을 쉰 번씩 승인하지 않기
테스트를 실행할 때마다 직접 승인하다 보면 읽지 않고 승인을 누르는 습관이 들어요. 안전하고 반복되는 명령은 프로젝트 설정에서 한 번에 허용하고, 위험한 명령은 거부하고, 나머지는 계속 확인 요청을 받으세요.
예시
한 팀이 공유 프로젝트 설정에서 테스트와 린트 명령은 허용하고 .env 파일 읽기는 거부해요. 확인 요청은 읽어 볼 가치가 있는 몇 가지 명령으로 줄고, 누구의 세션도 키를 열 수 없어요.
하는 방법
- 1/permissions를 열면 모든 규칙과 각 규칙이 어느 설정 파일에서 왔는지 볼 수 있어요.
- 2팀 규칙은 .claude/settings.json에 넣고 커밋하세요. 개인 규칙은 ~/.claude/settings.json이나 .claude/settings.local.json에 넣으세요.
- 3규칙은 deny, ask, allow 순서로 확인돼요. 그래서 deny 규칙 하나가 어떤 allow 규칙보다도 우선해요.
- 4Shift+Tab으로 모드를 바꾸세요. acceptEdits는 작업 디렉터리 안의 파일 편집을 승인해요. bypassPermissions는 확인 요청과 안전 검사를 끄는데, 문서에서는 인터넷에 연결되지 않은 격리된 컨테이너나 VM에서만 쓰라고 해요.
복사할 프롬프트
이 세션에서 실행한 명령을 살펴봐 주세요. .claude/settings.json에 넣을 권한 규칙을 제안해 주세요. 매일 쓰는 읽기 전용 명령과 테스트 명령은 허용하고, 시크릿을 읽거나 프로젝트 밖에서 삭제하는 것은 모두 거부하고, 나머지는 ask로 남겨 주세요. 규칙마다 한 줄로 설명해 주세요.잘못되기 쉬운 지점
- 아무 명령에나 맞는 allow 규칙은 확인 요청이 없는 것과 같아요. 정확한 명령만 허용하세요.
- .claude/settings.json의 규칙은 커밋하면 팀 전체에 적용돼요. 코드처럼 검토하세요.
공식 문서에서: Claude Code docs: Configure permissions · Claude Code docs: Settings files and precedence · Claude Code docs: Choose a permission mode
09
세션마다 한 가지에 집중하기
관련 없는 작업 세 개를 거친 세션은 컨텍스트에 세 작업이 모두 남아 있고, 그게 결과에 드러나요. 작업 사이에는 컨텍스트를 비우고, 긴 작업은 초점을 정해 압축하고, 넓은 범위의 검색은 서브에이전트가 자기 컨텍스트에서 하게 하세요.
예시
버그를 고친 뒤 같은 세션에서 리팩터링을 요청하면, 버그를 피하려고 썼던 예전 우회 방법을 계속 따라가요. /clear를 하고 맥락을 한 문장 알려 주면 그러지 않아요.
하는 방법
- 1관련 없는 작업 사이에는 /clear를 쓰세요. 빈 컨텍스트로 새 대화를 시작해요.
- 2긴 작업에서는 “/compact 계획과 실패하는 테스트는 유지해 주세요”처럼 초점을 정한 /compact가 앞의 내용을 요약해요.
- 3넓은 범위의 검색은 서브에이전트에 맡기세요. 서브에이전트는 각자의 컨텍스트 윈도우에서 실행되므로 답만 내 세션으로 돌아와요.
- 4Claude Code는 한도에 가까워지면 스스로 압축하기도 해요. 적당한 때 직접 압축하면 내가 고른 내용을 남길 수 있어요.
기본 제공
복사할 프롬프트
/compact 유지할 것: 목표, 계획, 지금까지 바꾼 파일, 아직 실패하는 테스트. 탐색 과정은 버려 주세요.잘못되기 쉬운 지점
- /clear는 대화를 잊어요. 다시 필요할 내용은 먼저 CLAUDE.md에 넣으세요.
- 돌아오는 건 서브에이전트의 답뿐이에요. 결론만이 아니라 파일 경로와 줄 번호도 요청하세요.
공식 문서에서: Claude Code docs: Commands · Claude Code docs: Best practices · Claude Code docs: Create custom subagents
10
충돌 없이 두 작업을 동시에 실행하기
한 체크아웃에서 두 세션이 돌면 서로 모르게 같은 파일을 편집해요. claude --worktree는 세션마다 자체 브랜치에 별도 사본을 주므로, 리팩터링과 버그 수정을 나란히 실행할 수 있어요.
예시
한 워크트리에서는 의존성 업그레이드, 다른 워크트리에서는 UI 수정이 돌아가는 동안 세 번째 풀 리퀘스트를 검토해요. 어느 세션도 다른 세션의 반쯤 끝난 파일을 보지 않아요.
하는 방법
- 1세션마다 claude --worktree <name>(또는 -w)으로 시작하세요. .claude/worktrees/<name>/ 아래에 worktree-<name> 브랜치로 git 워크트리를 만들어요.
- 2문서의 권장대로 .claude/worktrees/를 .gitignore에 추가하세요.
- 3세션마다 자체 검사가 있는 작업을 하나씩 주세요. 그래야 하나씩 검토할 수 있어요.
- 4브랜치마다 다른 풀 리퀘스트와 똑같이 검토하고 병합하세요.
복사할 프롬프트
지금 worktree-[이름] 브랜치의 워크트리에서 작업하고 있어요. 작업: [변경 하나]. 완료 기준: [테스트 또는 명령]이 통과하면 완료예요. 이 브랜치에만 커밋하고, 다른 브랜치를 병합하거나 리베이스하지 마세요.잘못되기 쉬운 지점
- 워크트리는 각각 별도의 폴더라서 의존성과 빌드 결과물이 공유되지 않아요. 워크트리마다 설치하세요.
- 같은 파일을 건드리는 두 작업은 워크트리를 쓰든 안 쓰든 병합할 때 충돌해요.
공식 문서에서: Claude Code docs: Run parallel sessions with worktrees
11
되감기로 잘못된 방향 되돌리기
세션이 잘못 흘러갔을 때 Claude에게 자기 변경을 되돌리라고 하면 엉망이 하나 더 생기기 쉬워요. 되감기는 대화, 코드 또는 둘 다를 실수 이전 시점으로 복원해요. 셸 명령이 한 일은 되돌릴 수 없으니, 위험한 단계 전에는 커밋하세요.
예시
프롬프트 세 개 전에 잘못된 방향으로 간 리팩터링. 그 이전으로 되감으면 파일과 대화가 복원되고, 코드를 되돌리라고 실랑이하는 대신 요청을 다시 쓰면 돼요.
하는 방법
- 1빈 프롬프트에서 Esc를 두 번 누르거나 /rewind를 입력하세요(/checkpoint와 /undo도 돼요).
- 2일이 잘못되기 전 시점을 골라 대화, 코드 또는 둘 다를 복원하세요.
- 3한계를 알아 두세요. rm, mv, cp 같은 셸 명령으로 바뀐 파일은 복원되지 않고, Claude Code 밖이나 다른 세션에서 한 편집도 복원되지 않아요.
- 4위험한 단계 전에는 커밋하세요. 체크포인트는 세션 안에서 빠르게 복구하기 위한 것이지 git을 대신하지 않아요.
복사할 프롬프트
시작하기 전에 현재 상태를 “[작업] 전 체크포인트”라는 메시지로 커밋해 주세요. 그다음 [작업]. 파일을 삭제하거나 옮기는 명령은 실행하기 전에 저에게 물어봐 주세요.잘못되기 쉬운 지점
- 되감기는 명령이 삭제한 파일을 되살리지 못해요. 그건 git만 할 수 있어요.
- 그사이 직접 손으로 한 편집도 기록되지 않아요. 되감기 전에 커밋하세요.
공식 문서에서: Claude Code docs: Checkpointing · Claude Code docs: Commands
12
스크립트와 CI에서 실행하기
같은 에이전트를 채팅 없이 실행할 수 있어요. claude -p는 프롬프트를 받아 작업한 뒤, 스크립트가 확인할 수 있는 종료 상태를 남기고 끝나요. CI에서 --bare를 쓰면 로컬 훅, 스킬, MCP 서버, CLAUDE.md를 건너뛰어서 어디서 실행해도 똑같이 동작해요.
예시
야간 작업이 “오늘 병합된 풀 리퀘스트로 변경 로그를 업데이트해 주세요”와 --output-format json으로 claude -p를 실행하고, 종료 상태가 0이 아니면 빌드를 실패 처리해요. 그래서 실패한 실행을 다음 날 아침에 알아챌 수 있어요.
하는 방법
- 1claude -p "..."는 비대화형으로 실행돼요. --output-format json이나 stream-json을 쓰면 스크립트가 파싱할 수 있는 출력이 나와요.
- 2성공하면 0으로, 실패하면 0이 아닌 값으로 종료하므로 CI가 이에 따라 분기할 수 있어요.
- 3CI에서는 로컬 설정에 의존하지 않는 실행을 위해 --bare를 추가하세요.
- 4풀 리퀘스트에는 /install-github-app으로 Claude Code GitHub Actions를 설정하세요(github.com 저장소만 해당). 그다음 풀 리퀘스트나 이슈 코멘트에서 @claude를 멘션하면 돼요.
복사할 프롬프트
claude -p "main 브랜치와의 diff를 읽어 주세요. 의존성을 추가하거나, 인증을 건드리거나, 데이터베이스 마이그레이션을 바꾸는 변경을 모두 JSON으로 나열해 주세요: {\"files\": [], \"reason\": \"\"}. 해당하는 게 없으면 빈 목록을 돌려주세요." --output-format json잘못되기 쉬운 지점
- 스크립트는 내가 준 권한으로 실행돼요. CI에는 꼭 필요한 최소 권한만 주세요.
- /install-github-app은 github.com의 저장소에서만 작동해요.
공식 문서에서: Claude Code docs: Run Claude Code programmatically · Claude Code docs: GitHub Actions
Codex
13
AGENTS.md: 모든 Codex 작업의 출발점이 되는 지침
Codex는 작업을 시작하기 전에 전역 파일부터 작업 중인 폴더까지 AGENTS.md를 읽어요. 명령과 규칙은 적용되는 코드 가까이에 한 번만 쓰세요. 가장 가까운 파일이 우선해요.
예시
웹 앱과 결제 서비스가 있는 저장소. 루트의 AGENTS.md에는 공통 명령이 있고, payments/AGENTS.md는 “테스트 없이 통화 반올림을 절대 바꾸지 말 것”을 추가해요. payments/ 안의 작업은 둘 다 따르고, 서로 다른 부분에서는 더 가까운 파일이 우선해요.
하는 방법
- 1CLI에서 /init을 실행하면 현재 폴더에 기본 AGENTS.md를 써 줘요.
- 2개인 지침은 ~/.codex/AGENTS.md에, 프로젝트 규칙은 저장소에 넣으세요. 하위 폴더마다 자체 파일을 둘 수 있고, Codex가 작업하는 곳에 더 가까운 파일이 우선해요.
- 3파일은 짧게 유지하세요. 전체 크기에 상한이 있고, 기본값은 32 KiB예요.
- 4“## Code Review Rules” 섹션을 추가하세요. GitHub에서 Codex가 하는 리뷰는 이 섹션을 따라요.
복사할 프롬프트
이 저장소를 읽고 AGENTS.md를 써 주세요. 1. 설치, 빌드, 테스트, 린트에 쓰는 정확한 명령. 2. 몇 줄로 요약한 프로젝트 구조. 3. 이 저장소에서 새로 온 사람이 자주 틀리는 규칙. 4. 리뷰어가 항상 지적해야 할 것을 담은 “## Code Review Rules” 섹션. 실제로 실행에 성공한 명령만 적고, 나머지는 “검증 안 됨”으로 표시해 주세요.잘못되기 쉬운 지점
- 긴 파일은 오히려 불리해요. 전체 크기의 상한이 기본 32 KiB예요.
- 아무 말 없이 루트 파일과 어긋나는 하위 폴더 파일은 Codex만큼 사람도 헷갈리게 해요. 무엇을 덮어쓰는지 밝혀 두세요.
공식 문서에서: Codex docs: AGENTS.md · Codex docs: CLI commands · Codex docs: GitHub integration
14
Codex가 혼자 할 수 있는 범위 정하기
권한 모드는 Codex가 묻지 않고 무엇을 할지 정해요. “Ask for approval”은 작업 공간 안에서 일하고, 그 밖으로 나가기 전에 멈춰요. “Full access”는 샌드박스와 확인 질문을 없애요. 한 번 정하고 끝내지 말고 작업마다 고르세요.
예시
낯선 저장소를 읽기 전용으로 읽은 다음, 버그 하나를 고치려고 “Ask for approval”로 바꿔요. Codex는 저장소 안에서는 편집하지만, 그 밖으로 나가기 전에는 멈추고 물어봐요.
하는 방법
- 1CLI에서는 /permissions로 모드를 바꾸고, /status로 현재 적용 중인 승인 정책과 쓰기 가능한 폴더를 볼 수 있어요.
- 2권장 기본값인 “Ask for approval”은 작업 공간 안에서 편집하고 명령을 실행하며, 그 밖으로 나가기 전에 멈춰요.
- 3“Approve for me”는 같은 샌드박스를 유지하지만, 승인 요청을 나에게 보내는 대신 자동 검토로 보내요.
- 4“Full access”는 파일 시스템과 네트워크 제한을 없애요. 문서에도 주의 문구가 있으니, 버려도 되는 환경에서만 쓰세요.
복사할 프롬프트
시작하기 전에 /status를 실행하고 승인 정책과 쓰기 가능한 폴더를 알려 주세요. 그다음 [작업]. 네트워크가 필요하거나 이 저장소 밖에 쓰는 명령은 실행하기 전에 물어봐 주세요.잘못되기 쉬운 지점
- “Approve for me”에서는 요청을 하나하나 읽는 사람이 없어요. 잘못된 동작을 쉽게 되돌릴 수 있는 곳에서만 쓰세요.
- “Full access”는 저장소만이 아니라 컴퓨터 전체에 적용돼요.
공식 문서에서: Codex docs: Permission modes · Codex docs: Sandboxing · Codex docs: Approvals and security · Codex docs: CLI commands
15
스크립트와 CI에서 Codex 실행하기
codex exec는 채팅 없이 작업을 실행해요. 진행 상황은 stderr로, 최종 메시지만 stdout으로 나가므로 스크립트가 답을 바로 쓸 수 있어요. 기본은 읽기 전용이니, 작업에 필요할 때만 쓰기 권한을 주세요.
예시
릴리스 스크립트가 “마지막 태그 이후의 커밋으로 릴리스 노트를 써 주세요”로 codex exec를 실행하고 stdout을 RELEASE.md에 저장해요. 파일은 스크립트가 직접 쓰므로 읽기 전용이면 충분해요.
하는 방법
- 1codex exec "..."는 비대화형으로 실행되고, 기본값은 읽기 전용 샌드박스예요.
- 2파일을 편집해야 할 때는 --sandbox workspace-write를 추가하세요. --full-auto는 더 이상 사용되지 않아요.
- 3--json은 모든 단계가 필요한 스크립트를 위해 이벤트를 JSON Lines 스트림으로 내보내요.
- 4GitHub Actions에서는 openai/codex-action@v1이 codex exec를 대신 실행해 줘요.
복사할 프롬프트
codex exec "[v1.2.0] 태그 이후의 변경 사항을 읽어 주세요. 추가, 변경, 수정으로 묶어 릴리스 노트를 써 주세요. 변경마다 한 줄씩, 사용자가 이해할 수 있는 말로 쓰고, 커밋 해시는 넣지 마세요."잘못되기 쉬운 지점
- 예전 가이드에는 아직 --full-auto가 나와요. 더 이상 사용되지 않는 옵션이니 --sandbox workspace-write를 쓰세요.
- 읽기만 하는 작업은 CI에서도 읽기 전용으로 두세요.
공식 문서에서: Codex docs: Non-interactive mode · Codex docs: GitHub Action
16
푸시하기 전에 리뷰받기
Codex는 작업 트리, 브랜치, 풀 리퀘스트를 리뷰해요. GitHub에서는 가장 심각한 문제인 P0와 P1만 지적하므로 코멘트를 읽어 볼 가치가 있어요. 푸시하기 전에 실행하고, 모든 풀 리퀘스트를 리뷰하게 하세요.
예시
마이그레이션을 푸시하기 전에 /review가 새 열에 기본값이 없어서 기존 행이 실패할 거라고 지적해요. 배포 실패 대신 푸시 전 1분이면 돼요.
하는 방법
- 1CLI의 /review는 작업 트리를 리뷰해요. codex review는 채팅 없이 같은 일을 하며, 기준 브랜치, 커밋, 커밋하지 않은 변경 사항을 대상으로 리뷰해요.
- 2GitHub에서는 풀 리퀘스트에 @codex review라고 코멘트를 다세요.
- 3Codex 설정의 “Personal preferences”에서 자동 리뷰를 켜세요. 그러면 코멘트를 달 필요가 없어요.
- 4팀 규칙을 AGENTS.md의 “## Code Review Rules” 섹션에 쓰세요.
기본 제공
복사할 프롬프트
## Code Review Rules - 인증이나 권한에 대한 모든 변경을 지적해 주세요. - 되돌릴 방법이 없는 데이터베이스 마이그레이션을 지적해 주세요. - 새 의존성을 지적하고 꼭 필요한지 말해 주세요. - 포맷은 무시해 주세요. 린터가 처리해요.잘못되기 쉬운 지점
- GitHub 리뷰는 P0와 P1 문제만 지적해요. 코멘트가 없다고 설계가 옳다는 뜻은 아니에요.
- 리뷰는 테스트 실행이 아니라 두 번째 의견이에요. 테스트는 그대로 유지하세요.
공식 문서에서: Codex docs: CLI commands · Codex docs: GitHub integration
17
Codex Cloud에 작업 맡기기
Codex Cloud는 컴퓨터가 잠자는 동안에도 계속 일해요. 작업마다 한 번 설정해 둔 환경으로 만든 별도의 작업 공간에서 실행돼요. 제대로 된 환경이 있으면 설치, 빌드, 테스트를 할 수 있고, 없으면 추측으로 일해요.
예시
회의 전에 codex cloud exec로 작은 리팩터링 네 개를 보내면, 같은 환경에서 만든 각자의 작업 공간에서 돌아가요. 가장 까다로운 작업은 세 번 시도하게 해서 가장 좋은 것을 남기고, 회의가 끝나면 diff 네 개를 검토해요.
하는 방법
- 1작업에 필요한 저장소, 의존성, 도구, 접근 설정을 갖춘 환경을 만드세요. 새 환경에는 설치 스크립트와 시작 스킬이 기록돼요.
- 2환경마다 인터넷 접근을 설정하세요. 패키지 관리자만, 선택한 도메인만, 또는 전부 허용할 수 있어요.
- 3작업은 ChatGPT에서, 긴 작업이라면 IDE 확장 프로그램에서, 또는 터미널에서 codex cloud exec로 시작하세요. --attempts 1-4를 쓰면 비교할 수 있게 여러 번 시도해요.
- 4Code Review와 GitHub 및 Linear 연동은 아직 예전 Codex Cloud(Legacy)에서 돌아가며, OpenAI는 이를 종료할 계획이에요.
기본 제공
복사할 프롬프트
codex cloud exec --attempts 3 "작업: [변경 내용]. 맥락: [파일]. 완료 기준: 이 환경에서 [테스트]가 통과하면 완료예요. diff는 [n]줄 미만으로 유지해 주세요."잘못되기 쉬운 지점
- 인터넷을 제한 없이 열어 두면 작업이 어떤 사이트에든 접근할 수 있고, 거기에는 작업을 조종하려고 쓴 페이지도 포함돼요. 작업에 필요한 것만 허용하세요.
- 설치 스크립트가 없으면 테스트가 실행되지 않았을 수 있어요. 작업에서 실제로 테스트를 실행했는지 확인하세요.
공식 문서에서: Codex docs: Cloud environments · Codex docs: CLI commands · Codex docs: IDE extension
18
Codex 한 번만 설정하기: 설정 파일, 프로필, MCP
세션마다 모델과 설정을 직접 바꾸고 있다면 config.toml에 넣으세요. Codex는 매번 ~/.codex/config.toml을 읽고, 신뢰할 수 있는 프로젝트에서는 프로젝트 설정도 읽어요. 프로필을 쓰면 설정 묶음 전체를 한 번에 바꿀 수 있어요.
예시
설계 질문에는 추론 강도가 높은 “deep” 프로필을, 간단한 수정에는 기본값을 써요. 아키텍처 질문 전에는 codex --profile deep, 나머지는 그냥 codex.
하는 방법
- 1기본 모델과 추론 강도는 ~/.codex/config.toml에서 설정하세요(model과 model_reasoning_effort). CLI와 IDE 확장 프로그램이 이 파일을 함께 써요.
- 2프로필은 ~/.codex/<name>.config.toml이라는 별도 파일로 만들고, --profile <name>으로 시작하세요.
- 3MCP 서버는 codex mcp add <name> -- <command>로 추가하세요. 서버마다 [mcp_servers.<name>] 테이블이 되고, /mcp로 활성화된 서버 목록을 볼 수 있어요.
- 4/status는 현재 적용 중인 설정을 보여 주고, codex resume --last는 이 폴더의 마지막 세션을 이어서 시작해요.
복사할 프롬프트
~/.codex/config.toml과 이 프로젝트의 .codex/config.toml을 읽어 주세요. 현재 적용 중인 모델, 추론 강도, 샌드박스, MCP 서버와 각각이 어느 파일에서 왔는지, 그리고 서로 충돌하는 것이 있는지 알려 주세요.잘못되기 쉬운 지점
- 프로젝트 설정은 신뢰할 수 있는 프로젝트에서만 불러와요. 설정이 무시되는 것 같으면 그것부터 확인하세요.
- 이제 프로필은 별도 파일이에요. config.toml 안에 [profiles.name]을 넣는 가이드는 오래된 거예요.
공식 문서에서: Codex docs: MCP · Codex docs: Config basics · Codex docs: Advanced config · Codex docs: CLI commands
개발자 규칙
- 시크릿, 키, 고객 데이터는 절대 프롬프트에 붙여 넣지 말고, 인덱싱되는 폴더에도 두지 마세요.
- 에이전트는 명령 실행 전에 확인을 요청하는 권한 설정으로 브랜치에서 실행하고, 모든 diff를 검토하세요.
- 에이전트가 쓴 코드를 병합하기 전에 테스트를 직접 실행하세요.
- 에이전트가 쓰는 API 키에는 모두 지출 한도를 설정하세요.
더 알아보기
- 알맞은 맥락 주기 레슨, 약 8분
- 예시와 원하는 형식 보여 주기 레슨, 약 8분
- 답을 단계별로 개선하기 레슨, 약 8분
- Claude Code 101 Anthropic (Claude Academy)
- Get Started with Codex OpenAI (OpenAI Academy)
- AI Agents Course Hugging Face
- Full Course: Spec-Driven Development with Coding Agents DeepLearningAI on YouTube