작업지시서 쓰기

받는 쪽은 열정적인 신입 개발자다. 빠르고 지치지 않지만, 우리 사정을 모르고
모르는 걸 모른다고 잘 말하지 않는다. 지시서에 없는 것은 추측으로 메운다.
지시서의 목적은 추측할 여지를 없애는 것이다.

0. 쓰기 전에 — 무엇을 넘기지 않을지부터 정한다

지시서를 잘 쓰는 것보다 앞선 단계다.

• 결정은 넘기지 않는다. "A와 B 중 뭐가 낫나요"라고 물으면 실행자는
  모른다고 하지 않고 그럴듯한 선택을 만들어낸다. 근거처럼 보이는 설명까지 붙여서.
  방향·범위·우선순위·품질 기준은 사람이 정하고, 이미 정해진 것만 넘긴다.
• 판단이 많이 섞인 뼈대는 직접 잡는다. 통째로 넘기면 되돌리는 비용이
  직접 짜는 비용보다 크다. 뼈대는 사람, 반복 확장은 실행자.
• 되돌릴 수 없는 일(삭제·배포·외부 전송)은 넘기지 않거나 샌드박스로 막는다.

여기서 아직 안 정해진 것이 있으면 지시서를 쓰지 말고 사용자에게 먼저 묻는다.
미정 상태로 넘기면 실행자가 대신 정해버린다.

1. 구성

1. 배경        왜 이 일이 필요한가. 앞뒤 맥락. 실행자는 프로젝트를 모른다
2. 작업 범위    무엇을 하고, 무엇은 하지 않는가
3. 제약        환경·경로·금지사항 — 이유와 함께
4. 산출물      경로·형식·언어를 문자열 그대로
5. 완료 기준    체크박스. 검증 가능한 형태로

2. 각 항목의 원칙

배경 — 내가 아는 것을 실행자는 모른다. 다만 내 설명이 틀렸을 수 있으니
"직접 확인하고, 다르면 보고하라"를 넣는다. 실제로 배경 설명이 실물과 어긋나는
경우가 있고, 그때 실행자가 내 말을 그대로 믿으면 잘못된 전제 위에 작업이 쌓인다.

작업 범위 — 하지 않을 것을 함께 적는다. 범위가 열려 있으면 실행자가 넓힌다.

제약 — 반드시 포함할 것:

• 실행 환경을 경로 문자열 그대로 (인터프리터·가상환경·빌드 명령).
  "알아서 맞는 걸 쓰겠지"가 가장 자주 깨지는 가정이다.
• 금지사항은 이유와 함께. 이유를 모르면 우회한다 —
  "이 파일 고치지 마"라고만 하면 복사본을 만들어서 고친다.
• 애매하면 진행하지 말고 물어보라고 명시. 안 적으면 추측하고 진행한다.

산출물 — 경로·파일명·언어·형식. "적당히 정리"는 지시가 아니다.

완료 기준 — 확인할 수 없는 완료 기준은 완료 기준이 아니다.
"잘 동작한다"가 아니라 "파일 N개가 이 경로에 생성됨", "이 명령이 exit 0".

3. 정직성 요구 — 지어내기 쉬운 작업일수록 명시한다

조사·수집·측정처럼 없는 것을 그럴듯하게 만들어내기 쉬운 작업에는 다음을 넣는다.

• 확인하지 못한 것은 표에 넣지 말고 "미확인"으로 분리하라
• 출처 URL을 실제로 열어 확인하라. 기억에 의존하지 마라
• 수치는 출처에 적힌 값만 쓰고 어디서 봤는지 함께 적어라
• 접근이 막혔으면 그 사실을 보고하고 멈춰라. 우회해서 지어내지 마라

조사 결과물은 그 자체로 근거가 되지 않는다. 검수자가 인용된 출처를 전량 직접 읽어야
근거가 서기 때문에([[work-review]] §2-1), 지시서에 이렇게 못 박는다.

• 모든 사실 주장에 직접 열 수 있는 URL을 붙여라. 검색 결과 페이지나 "논문 제목으로
  검색하면 나옴"은 출처가 아니다. 논문이면 표·절 번호까지 적는다
• URL 없는 항목은 표에 넣지 마라. 알고 있어도 마찬가지다
• 접근이 막힌 출처는 막혔다는 사실과 시도한 경로를 함께 적어라 — 검수자가 다른
  경로로 재시도할 수 있게

지시서에 이걸 넣지 않으면 검수 단계에서 열 수 없는 출처가 무더기로 나오고,
그때는 조사를 통째로 다시 해야 한다.

3-1. 지시서가 만드는 실패

실행자가 헤맬 때 원인은 대개 지시서에 없던 것이다. 아래는 실제로 겪은 셋이다.

① 근거의 위치를 주지 않았다. "사내 자료에 이미 있다" 고만 쓰고 어느 문서인지
적지 않았다. 실행자는 프로젝트 폴더밖에 못 뒤지므로 찾지 못했고, 정직하게
"근거 문서를 찾지 못했다"고 보고했다. → 접근할 수 없는 근거는 근거가 아니다.
원문을 인용하거나 위치를 명시한다.

② 트레이드오프의 우선순위를 정하지 않았다. 후보 선정 기준을 여럿 줬는데
그중 무엇이 우선인지 안 적었다. 실행자는 대표성을 골랐고, 정작 필요했던 것은
작업 안정성이었다. 결과물이 목적에 안 맞아 다시 했다.
→ 기준이 둘 이상이면 무엇을 먼저 볼지 쓴다.

③ 보고 순서를 정하지 않았다. 완성도를 높이려다 턴이 끊겨 작업은 됐는데 보고가
없는 상태가 반복됐다(사용량 한도, 세션 종료). 매번 검토자가 로그를 파헤쳐 상태를
복원해야 했다.
→ 오래 걸릴 작업에는 "도달한 상태를 먼저 보고하고, 그 뒤에 개선하라" 를 넣는다.
중간 보고가 있으면 끊겨도 잃는 것이 없다.

④ 앞 지시서의 제약을 다음 지시서로 옮기지 않았다. 한 작업을 여러 지시서로 이어갈 때,
앞 회차에 적었던 금지사항과 보고 요구가 뒤 회차에서 조용히 사라졌다. 실측 사고:
금지 A가 4회차 지시서까지 매번 있다가 5회차에서 빠졌고, 미달 항목을 unfinished 에도
4회차에는 있었는데 5회차에서 빠졌다. 그 회차 보고에서 그대로 누락됐다.

프로젝트 문서에 결정이 적혀 있어도 소용없다 — 실행자는 지시서만 본다.
→ 이어지는 지시서를 쓸 때는 앞 회차의 제약 절을 먼저 그대로 복사하고,
이번에 바뀐 것만 고친다. 새로 쓰지 마라. 새로 쓰면 매번 무언가가 빠진다.

⑤ 내가 센 수치를 사실처럼 적었다. 지시서에 "덮어쓰기 11곳", "재기록 대상 354개"라고
단정해 적었는데 둘 다 틀렸다(실제 10곳·343개). 실행자가 전수 검색으로 잡아냈다.

위험한 지점은 "틀렸다"가 아니라 실행자에게는 지시서의 숫자가 사실로 보인다는 것이다.
1차 때 실행자가 "11곳"에 맞추려 했다면 경로를 정의하는 원본까지 고쳐 작업이 통째로
망가졌을 것이다. 2차의 원인은 정본에 값이 두 벌(원시 정수·백만 단위) 있는 것을
갈라 보지 않은 것이었다 — 한 번 훑어 센 값은 대개 이런 갈래를 놓친다.

→ 작성자가 센 수치는 "확인용 참고치"라고 명시하고, "직접 다시 세고 다르면 멈추고
보고하라"를 함께 붙인다. 개수·목록·집계는 실행자의 전수 검색이 더 정확하다.
→ 그리고 어긋났을 때 실행자를 탓하지 않는다. 두 번 다 실행자가 옳았다.

4. 중간 게이트

같은 일을 여러 건 반복하는 작업이면 앞의 한두 건에서 끊고 검수하도록 지시한다.
전부 끝난 뒤에 보면 전부 다시 해야 한다.

5. 규칙이 바뀌면 소급 적용을 명시한다

"이렇게 고쳐라"라고만 하면 실행자는 그 시점 이후에 만드는 것에만 반영한다.
지시를 어긴 게 아니라 언제부터 적용인지를 안 적은 것이다.
→ **"이미 만든 산출물에도 소급 적용하라"**를 문장으로 넣는다.
안 그러면 산출물마다 기준이 달라져 서로 비교가 깨진다.

6. 권한 경계를 지시서에 박아둔다

실행자가 자기 권한을 넘어서려 할 때 스스로 멈추고 되돌려보내도록 다음을 넣는다.

다음에 해당하면 진행하지 말고 보고하라:
- 두 가지 이상의 방식 중 무엇을 택할지 정해야 할 때
- 지시서에 없는 범위로 넓혀야 할 때
- 데이터셋·모델·라이브러리를 새로 고르거나 바꿔야 할 때
- 되돌릴 수 없는 작업(삭제·배포·외부 전송)이 필요할 때
- 배경 설명이 실제와 다를 때
이건 실패가 아니라 정상적인 보고다. 추측해서 진행하는 것이 실패다.

같은 문구가 [[implementation-conduct]] §1에도 있다(받는 쪽이 지키는 규칙).
한쪽을 고치면 다른 쪽도 함께 고친다. 두 곳에 있는 같은 규칙은 언젠가 어긋난다.

연계

• 결과를 받으면 [[work-review]] 로 검증한다.
• 무엇으로 검증할지(수치·기록된 산출물·화면 조작)는 [[verification-route]] 에서 고르고,
  고른 것을 지시서 §3에 적는다. 적지 않으면 실행자는 가장 편한 수단을 쓴다.
• 실행자에게 실제로 넘기는 절차(세션 유지·호출 규약)는 설치된 워크플로우의 위임 스킬을
  따른다. 워크플로우마다 실행자와 전달 방식이 다르므로 이 스킬은 그것을 지정하지 않는다.

이력 (필수 기록)

• 생성일: 2026-08-26
• 업데이트 횟수: 5
• 최근 업데이트: 2026-09-15 (이력의 사례를 §3-1 본문과 대조해 중복 제거)
• 사용 이력 — 교훈은 전부 §3-1 에 있다. 여기는 언제 무엇이 늘었는지만.
  • 2026-09-15 — 이력이 §3-1 을 그대로 되풀이하던 것을 압축. 원본은 SKILL.md.bak_20260915
  • 2026-09-01 — §3-1 ⑤(작성자가 센 수치) 추가. 한 지시서에서 두 번 연속 관리자 집계가
    틀렸고(11곳→10곳, 354개→343개) 두 번 다 실행자의 전수 검색이 맞았다.
    §6 권한 경계 문구 덕에 둘 다 수정 전에 잡혔다
  • 2026-08-31 — §3-1 ④(제약 승계 누락) 추가. 5회차 지시서에서 앞 회차 금지사항이 빠졌고
    그 회차 보고에서 똑같이 빠졌다
  • 2026-08-31 — §3-1(지시서가 만드는 실패) 신설. 셋 다 같은 과제에서 연달아 겪었고
    전부 실행자가 아니라 지시서의 결함이었다
  • 2026-08-28 — §3(조사 결과물은 그 자체로 근거가 되지 않는다) 추가.
    [[work-review]] §2-1 과 짝을 맞춘 것 — 한쪽만 고치면 검수에서 열 수 없는 출처가 쏟아진다
  • 2026-08-26 — 위임 메커니즘 스킬에서 분리. 위임 대상(사람·서브에이전트·Codex)과 무관하게 쓰인다