AI 워커 지시서를 자기완결로 쓰는 법: 경로 참조 대신 본문, 출력 첫 글자, 확인 불가 표시

정해진 시각에 블로그 초안을 쓰는 AI 워커를 돌리고 있습니다. 2026년 7월 27일 07:00 슬롯에서 글 한 편이 발행에 실패했고, 확인해 보니 앞서 다른 글 한 편도 같은 이유로 실패해 있었습니다. 원인은 제가 쓴 지시서였습니다. 지시서에 “레포의 이 파일 본문을 그대로 사용”이라고 경로를 적었는데, 워커는 자기 작업 폴더 밖을 읽을 수 없었습니다.

고친 방법을 먼저 적으면 네 가지입니다.

1. 참고 자료는 경로 대신 지시서 본문에 붙여 넣는다
2. 출력 형식을 첫 글자까지 정한다
3. 못 할 때 어떻게 답할지도 정해 둔다
4. 뒷단은 형식이 어긋난 결과를 버리기 전에 남기고 알린다

아래는 이 네 가지에 이르기까지 확인한 순서입니다.

실패 로그에서 먼저 본 것

서버 로그에는 이렇게 남아 있었습니다.

블로그 발행 실패. entryId=blog:10,
reason=Blog publish failed: frontmatter(---) 로 시작하지 않는 문서입니다
saved=/data/content/blog-drafts/blog_10.md

발행 스크립트는 글이 ---(frontmatter)로 시작해야 받아 줍니다. 워커가 돌려준 문서가 그렇게 시작하지 않아서 거부된 것입니다. 스케줄러는 07:00:04에 정확히 작업을 올렸고, 실패한 초안은 따로 보존됐고, 텔레그램 알림도 왔고, 상태도 실패로 표시됐습니다. 실패를 알아채고 초안을 따로 남기는 부분은 설계대로 동작했고, 문제는 워커에 들어간 지시서였습니다.

보존된 초안에 AI가 적어 둔 답

남아 있는 초안을 열어 보니 첫 문단이 글이 아니었습니다. 경로만 줄이면 이렇게 적혀 있었습니다.

이 작업의 핵심 지시가 “새로 쓰지 말 것 — 레포의 (파일 경로) 본문을 그대로 사용”인데, 해당 파일에 접근할 수가 없습니다. 이 세션의 샌드박스는 작업 디렉토리 (폴더 경로)로 제한돼 있어서 …

지어낸 것도 없고 얼버무리지도 않았습니다. 정확한 답이었는데, 뒷단은 완성된 글만 기다리고 있어서 그 답을 받을 자리가 없었습니다. AI는 제대로 말했고, 제 쪽에서 그 말을 못 받은 셈입니다.

앞서 실패한 다른 한 건은 조금 달랐습니다. 이번에는 본문을 쓰긴 썼는데 맨 앞에 “원작 파일이 이 워킹 디렉토리에 없어 …”로 시작하는 한 줄을 붙였습니다. 절반은 답하고 절반은 아는 만큼 채운 경우입니다. 첫 글자가 ---가 아니어서 이것도 거부됐는데, 그 한 줄이 없었다면 원본을 못 본 채 쓴 글이 그대로 나갔을 겁니다. 이쪽이 더 알아채기 어렵습니다.

같은 시기에 실패로 표시된 건이 하나 더 있었지만, 그건 실제로는 발행됐는데 상태만 잘못 기록된 다른 문제였습니다. 실패 3건 가운데 지시서 때문인 건 2건이었습니다.

지시서 고치는 법 1: 경로 대신 본문을 붙여 넣는다

워커가 어디까지 읽을 수 있는지는 실행 환경마다 다릅니다. 샌드박스에서 도는 에이전트, 다른 컴퓨터에서 도는 워커, API로 부르는 모델은 내 컴퓨터의 파일을 볼 수 없다고 보는 편이 맞습니다. 그래서 “이 파일 참고”, “레포의 그 문서대로”처럼 위치를 가리키는 문장을 지웠습니다.

• 원문 인용이 필요하면 본문을 지시서 안에 그대로 복사합니다
• 실측 수치·명령어도 지시서에 직접 적습니다
• 붙여 넣을 수 없을 만큼 큰 자료가 필요한 작업은 워커에 맡기지 않습니다

큐에 남아 있던 지시서 3건도 이 기준으로 다시 썼습니다.

지시서 고치는 법 2: 출력 첫 글자를 정한다

모델은 앞에 설명을 붙여 주는 경우가 많습니다. 사람이 읽을 때는 괜찮지만, 뒤에서 기계가 형식을 검사하면 그 한 줄 때문에 통째로 버려집니다. 지시서 맨 앞에 다음 블록을 넣었습니다.

[출력 규칙 · 필수] 응답의 첫 글자는 반드시 --- 로 시작한다.
설명·서두·사과·메모 문장을 앞에 붙이면 발행이 실패한다.
[자료 규칙] 외부 레포·파일 접근 불가. 메모에 적힌 사실만 사용.

[자료 규칙]은 워커에게 아래 적힌 것이 전부라고 미리 알려 주는 줄입니다. 빈칸을 짐작으로 채우지 말라는 뜻도 같이 들어 있습니다.

지시서 고치는 법 3: 확인 불가일 때 답할 자리를 만든다

이번에 제가 빠뜨린 건 이 부분이었습니다. 못 하겠다는 답에도 정해진 형식이 있어야 버려지지 않습니다. 예를 들어 이렇게 적어 둡니다.

확인할 수 없는 내용이 있으면 지어내지 말고, 맨 앞에 '확인 불가'라고만 적는다.

뒷단에서 이 표시가 붙은 결과를 실패와 따로 분류하면, 지시서를 고쳐야 하는 경우와 워커 쪽 문제를 나눠 볼 수 있습니다.

나중에 한 줄을 더 넣었습니다. 9월 30일 자동으로 쓴 글 도입부에 받은 적 없는 질문(“~라는 질문을 받았는데”)이 들어간 일이 있었고, 그 뒤로 지시서 머리에 항상 이 줄을 둡니다.

[사실 규칙] 겪지 않은 일화·받지 않은 질문·독자 반응을 지어내지 말 것. 도입은 메모의 사실로만 연다.

결과를 받는 코드에서 고친 세 군데

지시서만 고치면 다음에 경로 한 줄을 실수로 넣었을 때 같은 일이 생깁니다. 받는 쪽도 세 군데를 손봤습니다.

고친 곳	바뀐 동작
워커 시스템 프롬프트	첫 글자 ---, 서두 금지, 외부 파일 접근 불가 안내를 항상 넣음
결과 처리	첫 --- 앞 문장은 잘라 내고 다시 검사, 잘랐다는 사실은 WARN 로그로 남김
실패 알림	발행 스크립트 종료 코드를 같이 실어, 스크립트 문제인지 뒤처리 문제인지 알림만 보고 구분

잘라 낸 사실을 로그에 남기는 건 조용히 고쳐 놓고 넘어가지 않으려는 것입니다. 서두 한 줄이 자주 잘리면 그 지시서를 다시 봐야 한다는 신호로 씁니다. 실패를 조용히 넘기지 않는 쪽 이야기는 조용한 실패를 막는 에러 핸들링에 따로 적었습니다.

AI 워커가 엉뚱한 결과를 낼 때 볼 곳

워커가 엉뚱한 결과를 내거나 아무것도 안 낼 때 이 순서로 봅니다.

1. 실패 로그의 사유 한 줄: 형식 검사에서 걸렸는지, 실행 자체가 실패했는지
2. 보존된 원본 출력: 첫 문단에 “접근할 수 없습니다”, “파일이 없어서” 같은 말이 있는지
3. 지시서 안의 위치 표현: 경로, “그 문서”, “지난번 것”처럼 워커가 볼 수 없는 곳을 가리키는 말
4. 워커의 실행 위치: 어느 폴더 안에서 도는지, 그 밖을 읽을 수 있는지

2번이 가장 빠릅니다. 형식이 틀렸다고 내용까지 틀린 건 아니어서, 원인은 대개 버려진 출력 안에 적혀 있습니다. 그래서 형식 검사에서 떨어진 결과도 지우지 않고 남겨 두는 게 먼저입니다.

자기완결인지 확인하는 질문 두 개

지시서를 넘기기 전에 이 두 가지를 물어봅니다.

• 이 문서 하나만 들고, 아무 사정도 모르는 사람이 결과를 만들 수 있는가
• 만들 수 없을 때 그 사람이 어디에 대고 그 말을 할 수 있는가

첫 번째를 통과하지 못하면 모델도 못 만듭니다. 두 번째를 비워 두면 못 하겠다는 답이 그냥 실패로 처리됩니다. 개발이 아닌 일에 같은 방법을 쓰는 이야기는 AI는 못 하겠다고 답했는데, 제가 그 말을 못 받았습니다에 있습니다.