작업 요청서

작업 요청서는 복붙 프롬프트 모음이 아닙니다. Codex에게 무엇을, 어디까지, 무엇을 남기며 맡길지 적은 작은 일감 봉투입니다. 예전 이름인 “작업 패킷”은 목표, 범위, 금지선, 증거를 한 번에 묶어 보낸다는 뜻이었지만, 실제로는 “Codex에게 넘기는 작업 요청서”라고 이해하면 됩니다.

이 문서를 읽으면

첫 요청을 작고 안전하게 자르는 법을 배웁니다.
금지 범위와 중단 조건을 명확히 적습니다.
로컬 patch(수정), 클라우드 조사, CI 실패, PR 리뷰를 같은 형식으로 맡깁니다.

오늘 바로 해볼 일

다음 작업에서 “목표, 허용 범위, 금지, 증거” 네 줄만 먼저 적어보세요. 이 네 줄이 없으면 Codex가 똑똑해도 작업 경계가 흔들립니다. 처음에는 아래 요청서를 그대로 복사해 빈칸만 바꾸면 됩니다.

가장 작은 첫 요청서

이 요청서는 입문자가 첫 10분 안에 결과를 받아보기 위한 최소 단위입니다. 파일 하나, 작은 수정 하나, 완료 보고 하나로 닫히게 만듭니다.

실행 표면: CLI 또는 IDE extension
목표: 내가 고른 파일 1개에서 작은 문서/테스트 수정 하나를 끝내기
허용 범위: 지정한 파일 1개와 필요한 경우 가장 가까운 테스트 1개
금지: 패키지 설치, 설정 변경, 관련 없는 리팩터링
먼저 확인할 것: 현재 파일 구조와 바꿀 위치
수정 후 검증: 가능한 가장 작은 확인 명령 또는 diff 검토
남길 증거: 바뀐 파일, 핵심 diff (변경점), 확인하지 못한 것
중단 조건: 범위가 파일 1개를 넘거나 secret (비밀값)이 필요하면 멈추고 보고

첫 요청에서 중요한 것은 완벽한 결과가 아니라 경계를 지킨 결과입니다. Codex가 더 큰 수정을 제안하면 바로 넓히지 말고, 왜 범위를 넓혀야 하는지 먼저 보고하게 하세요.

기본 요청서 구조

실행 표면:
목표:
허용 범위:
금지:
먼저 확인할 것:
수정 후 검증:
남길 증거:
중단 조건:

요청서 품질 점검표

작업 요청서는 길다고 좋은 것이 아닙니다. 아래 7개 중 5개 이상이 보여야 Codex가 실패해도 사람이 다시 잡을 수 있습니다.

점검 항목	좋은 상태
목표	“무엇을 끝내는가”가 한 문장으로 보입니다.
허용 범위	수정할 파일, 디렉터리, 문서 범위가 좁게 적혀 있습니다.
금지	하지 말아야 할 일, 건드리지 말아야 할 파일, 승인 필요한 행동이 분리되어 있습니다.
먼저 확인할 것	Codex가 바로 수정하지 않고 읽어야 할 로그, 문서, 테스트, 화면이 있습니다.
검증	사람이 다시 실행할 수 있는 명령, 화면 확인, 링크 검사, 리뷰 기준이 있습니다.
증거	diff (변경점), test evidence (테스트 증거), review note (리뷰 메모), handoff (인수인계) 중 무엇으로 닫는지 적혀 있습니다.
중단 조건	secret (비밀값), 운영 환경, 권한 부족, 재현 실패처럼 멈춰야 할 조건이 있습니다.

실전 코칭이나 팀 교육에서 가장 먼저 보는 것도 결국 이 표입니다. “똑똑한 요청”보다 “되돌릴 수 있는 요청”이 팀 비용을 줄입니다.

나쁜 요청을 요청서로 바꾸기

처음에는 길게 쓰려고 하기보다, 애매한 요청을 네 줄짜리 요청서로 바꾸는 연습이 좋습니다.

나쁜 요청	좋은 요청
이거 알아서 고쳐줘	`src/content/docs/ko/packets.md`에서 예시가 부족한 부분만 보강하고, 빌드 결과를 남겨줘
CI 좀 봐줘	실패 job 이름과 로그를 먼저 분류하고, 설정 완화나 테스트 삭제 없이 최소 수정 후보를 제안해줘
문서 예쁘게 해줘	모바일에서 글이 넘치는지 확인하고, CSS 변경이 필요하면 해당 selector만 고쳐줘

좋은 요청은 Codex가 똑똑해지는 문장이 아니라, 실패했을 때 멈출 수 있는 문장입니다. 목표, 허용 범위, 금지, 검증이 있으면 결과가 흔들려도 다시 이어받기 쉽습니다.

로컬 patch(수정) 요청서

실행 표면: CLI 또는 IDE extension
목표: checkout retry 실패를 좁은 patch로 수정
허용 범위: payment adapter와 해당 테스트 파일
금지: 패키지 설치, 설정 완화, 테스트 삭제
먼저 확인할 것: 재현 경로와 의심 파일 요약
수정 후 검증: 관련 테스트 실행
남길 증거: diff (변경점), 테스트 명령과 결과, 남은 위험
중단 조건: 외부 sandbox 인증 정보가 필요하면 진행 중단 후 보고

클라우드 조사 요청서

실행 표면: Web/Cloud 또는 Codex app
목표: 큰 코드베이스에서 인증 요청 흐름을 추적하고 개선 후보 제안
허용 범위: 읽기 전용 분석
금지: 파일 수정, DB 변경 작업(migration) 작성, 비밀값(secret) 접근
남길 증거: 요청 흐름 지도, 위험 목록, 제안 patch 후보
handoff (인수인계): 로컬 patch로 넘길 가장 작은 후보 3개

CI 실패 요청서

실행 표면: CLI + GitHub/CI
목표: 실패한 CI job을 실패 유형으로 분류하고 최소 수정 계획 수립
입력: job name, failing log, current diff
금지: CI 설정 완화, 테스트 삭제, lockfile 변경
남길 증거: 로컬 재현 여부, 원인 후보, 수정 diff (변경점), rerun (재실행) 결과
중단 조건: CI 환경에서만 재현되면 환경 차이로 보고

PR 리뷰 요청서

실행 표면: Codex app review 또는 GitHub
목표: PR을 merge 전 위험 중심으로 리뷰
초점: 정확성, 회귀, 누락 테스트, 보안, migration 위험
금지: 스타일 취향 위주 리뷰
남길 증거: finding 목록, 파일/라인 참조, 권장 확인
출력: 리뷰어가 바로 판단할 수 있는 review note (리뷰 메모)

유스케이스를 요청서로 번역하기

공식 유스케이스는 “무엇을 맡길 수 있는가”를 보여주지만, 실제 요청은 저장소 상황에 맞는 요청서로 줄여야 합니다. 아래 예시는 기능명보다 입력·범위·증거를 먼저 고르는 방식입니다.

상황	요청서에 꼭 넣을 것	닫히는 증거
프론트엔드 프로토타입	참고 이미지, 허용 컴포넌트, 반응형 기준, 브라우저 확인 범위	diff (변경점), 데스크톱/모바일 스크린샷, 남은 시각 위험
여러 파일 리팩터링	바꾸지 않을 동작, 단계별 write scope (수정 범위), 테스트 순서	작은 commit 후보, 관련 테스트, 회귀 위험 목록
triage (버그 분류)	입력 로그, 재현 조건, 우선순위 기준, 금지할 임시 우회	원인 후보, 최소 수정안, 재현/통과 증거
문서 최신화	비교할 공식 문서, 반영할 문서 범위, 인용/근거 위치	수정된 문서, 링크 검사, 변경 기록
MCP 기반 자동화	연결 앱, 접근 권한, 읽기/쓰기 구분, 실패 알림 대상	실행 로그, 승인 기록, 사람이 볼 요약

프론트엔드 프로토타입 요청서

실행 표면: CLI + 브라우저 확인
목표: 제공한 스크린샷을 기준으로 첫 화면 UI를 구현
입력: 스크린샷, 현재 디자인 토큰, 기존 컴포넌트
허용 범위: 해당 page와 관련 CSS만 수정
금지: 새 UI 라이브러리 설치, 관련 없는 레이아웃 리팩터링
검증: 데스크톱/모바일 스크린샷 확인, build 실행
남길 증거: diff (변경점), 스크린샷에서 확인한 점, 남은 시각 위험

MCP 자동화 요청서

실행 표면: Codex app 또는 Web/Cloud + MCP
목표: Linear issue를 읽어 이번 주 triage (버그 분류) 요약 생성
허용: 읽기 전용 issue 조회와 요약 문서 작성
금지: issue 상태 변경, 담당자 변경, 외부 공유
검증: 사용한 issue 범위와 누락 기준을 요약
남길 증거: triage (버그 분류) 결과, 불확실한 항목, 사람이 확인할 다음 액션
중단 조건: 쓰기 권한이나 비공개 고객 정보가 필요하면 멈춤

완료 보고까지 한 묶음으로 만들기

작업 요청서는 시작 문서에서 끝나지 않습니다. Codex에게 맡긴 뒤에는 같은 구조로 완료 보고를 받아야 리뷰가 빨라집니다.

완료한 목표:
바뀐 파일:
핵심 diff (변경점):
검증 명령과 결과:
확인하지 못한 것:
남은 위험:
handoff (인수인계):

좋은 완료 보고는 “끝났습니다”가 아니라 리뷰어가 어디를 보면 되는지를 줄여줍니다. 특히 확인하지 못한 것과 남은 위험이 비어 있으면 정말 없는 것인지, Codex가 놓친 것인지 다시 물어야 합니다.

좋은 요청서의 기준

사람이 읽어도 작업 경계가 보입니다.
Codex가 실패했을 때 멈출 조건이 있습니다.
결과가 말이 아니라 diff (변경점), 테스트 결과, review note (리뷰 메모), handoff (인수인계)로 남습니다.
다음 사람이 이어받을 수 있습니다.
외부 문서나 도구 출력(tool output)에 섞인 지시문보다 사용자 요청과 저장소 규칙이 우선한다는 기준이 보입니다.