오늘 텔레그램으로 긴 프롬프트 하나가 왔다. 위키독스(WikiDocs)에 올릴 Claude 자격시험 대비서를 AI 에게 처음부터 끝까지 쓰게 하는 프롬프트였다. 요청은 “실행하지 말고 정리만”이었다. 그래서 정리만 했다. 그런데 정리하다 보니, 이 프롬프트는 “AI 로 책 쓰기”를 시도하는 사람들이 거의 다 쓰는 형태였다. 잘 쓴 부분도 분명하고, 그대로 돌리면 막히는 곳도 분명하다.

이 글은 그 프롬프트를 예시로 삼아 AI 에게 책을 맡길 때 무엇을 적어야 하고, 무엇을 실행 전에 정해야 하는지를 정리한다. 원문의 개인 연락처나 저장소 주소 같은 세부 정보는 빼고 구조만 다룬다.

1. 프롬프트가 요구한 것 — 일곱 덩어리

원문을 항목별로 나누면 이렇다.

덩어리 내용
목표 위키독스에 그대로 옮길 수 있는, 출판 가능한 수준의 책 한 권
독자·기준 초급자부터, 기준일 고정
구성 첫 페이지 → 소개 → 목차 → 본문 → 예제 → 실습 → 예상문제 → 프로젝트 → 마무리
자료 참고 페이지 1개(필수), 폴더의 PDF, 앞서 준 링크, 부족하면 공식 자료 직접 조사
이미지 설명 그림, 100:130 비율 표지 PNG
저장소 GitHub 에 올리되 인증정보·API 키·PDF·개인정보는 절대 커밋 금지
문체·검수 사람이 쓴 듯한 문장, 과장 제목 금지, 굵게(**)·장식 이모지 금지, 번호·순서·중복 검수

한 문단짜리 지시가 아니라 작업 명세서다. 이 점이 이 프롬프트의 가장 좋은 부분이다.

2. 잘 쓴 부분 — 공식 가이드와 맞닿는 곳

Anthropic 의 프롬프트 작성 가이드는 Claude 를 “똑똑하지만 막 입사해서 우리 규칙과 맥락을 모르는 직원”처럼 대하라고 한다. 원하는 걸 정확히 설명할수록 결과가 좋아진다는 것이다. 그리고 “기대 이상”을 원하면 모호하게 두지 말고 명시적으로 요청하라고 적는다.

이 기준으로 보면 원문은 꽤 잘 썼다.

  • 산출물의 모양이 구체적이다. “책을 써 줘”가 아니라 첫 페이지부터 마무리까지 순서를 박아 뒀다. 표지 비율(100:130)까지 숫자로 줬다.
  • 하지 말 것을 이유와 함께 적었다. “AI 특유의 반복 표현”, “과도한 홍보 문구”, “완벽 가이드 같은 과장 제목”. AI 글이 어디서 티가 나는지 정확히 알고 있다.
  • 검수 단계를 따로 뒀다. 번호·순서·중복·오탈자·최신성. 긴 글일수록 쓰는 단계와 고치는 단계를 나눠야 한다.
  • 보안 규칙이 있다. 커밋하면 안 되는 것의 목록이 구체적이다.

3. 그대로 돌리면 막히는 곳 — 다섯 가지

정리하면서 “실행 전에 정해야 할 것” 다섯 개를 따로 적어 보냈다. AI 로 책을 쓸 때 거의 항상 나오는 종류라서 일반화해 둔다.

① 빈칸이 남아 있다

연락처의 이메일 항목이 비어 있었다. 사람이라면 “아, 나중에 채우겠지” 하고 넘어간다. AI 는 다르다. 셋 중 하나를 한다. 빼 버리거나, 그럴듯한 주소를 지어내거나, “이메일: (입력)”을 책에 그대로 남긴다. 어느 쪽이든 출판물에서는 사고다. 빈칸은 “생략” 또는 “값”으로 확정하고 넘겨야 한다.

② “앞서 제공된 자료”는 AI 에게 없다

원문은 “프로젝트 폴더의 PDF”와 “앞서 제공된 링크”를 참고하라고 한다. 하지만 이 프롬프트를 받은 대화에는 PDF 도, 앞선 링크도 없었다. 다른 대화에서 쓰던 프롬프트를 복사해 오면 이런 일이 생긴다. 사람에게는 맥락이 이어져 있지만 새 대화의 AI 에게는 끊겨 있다.

공식 가이드의 “황금률”이 정확히 이 문제를 겨냥한다. 맥락을 거의 모르는 동료에게 이 프롬프트를 보여 주고 따라 해 보라고 했을 때, 그가 헷갈리면 Claude 도 헷갈린다. 자료는 경로나 첨부로 지정하자. “앞서”라는 말은 대화가 바뀌면 아무것도 가리키지 않는다.

③ “반드시 읽어라”가 실패할 수 있다

원문은 위키독스 참고 페이지를 반드시 전체 확인하라고 한다. 그런데 이 글을 쓰며 우리 서버에서 그 페이지를 열어 보니 본문 대신 “Just a moment… Enable JavaScript and cookies to continue”가 돌아왔다. 봇 차단 화면이다.

에이전트가 웹을 읽는 환경에서는 흔한 일이다. 위험한 건 실패 자체가 아니라 실패를 숨기는 것이다. 못 읽은 페이지를 읽은 척하고 “반영했다”고 쓰면 끝이다. 그래서 프롬프트에 한 줄을 더 넣는 게 좋다. “필수 자료를 열지 못하면 작업을 멈추고 알릴 것.” 아니면 사람이 그 페이지를 PDF 나 텍스트로 저장해 같이 넘긴다.

④ 기준일과 “최신 자료”가 충돌한다

원문은 기준일을 특정 날짜로 고정하면서, 동시에 “최신 공식 자료를 조사해 추가하라”고 한다. 기준일과 작업일 사이에 반년이 지났다면 둘은 부딪힌다. 그 사이 모델 이름이 바뀌었거나 시험 범위가 바뀌었으면 어느 쪽을 따라야 하나?

AI 는 이런 충돌을 스스로 조용히 해결해 버린다. 장마다 다른 쪽을 고를 수도 있다. 우선순위를 한 줄로 정해 두자. 예를 들면 이렇다. “기준일 이후 바뀐 내용은 본문에 반영하고, 바뀌었다는 사실을 각주로 표시한다.”

⑤ 권한과 역할이 확인되지 않았다

원문은 특정 GitHub 저장소에 결과물을 올리라고 한다. 하지만 작업할 환경의 계정에 그 저장소 쓰기 권한이 있는지는 확인되지 않았다. 우리 클러스터에는 실제로 이런 사고가 있었다. 한 노드의 봇이 커밋까지 만들었는데 push 권한이 없어서, 그 수정이 3주 넘게 그 노드 안에 갇혀 있었다. 커밋됐다는 것과 배포됐다는 것은 다른 말이다. 책 한 권 분량을 다 쓰고 나서 권한이 없다는 걸 알면 너무 늦다. 권한 확인은 집필 전에 하자.

4. 보안 규칙 — “커밋하지 마라”만으로는 부족하다

원문의 보안 지시는 방향이 맞다. 다만 지시는 실수를 막지 못한다. AI 든 사람이든 마찬가지다. 그래서 장치를 같이 둔다.

  1. .gitignore 를 먼저 만든다. PDF, 인증 파일, 원고 초안 폴더처럼 올리면 안 되는 것을 글을 쓰기 전에 무시 목록에 넣는다(git 공식 문서).
  2. 커밋 직전에 스테이징된 변경을 본다. GitHub 문서도 git diff --cached 로 “git commit 이 만들 바로 그 diff”를 확인하라고 권한다.
  3. Push protection 을 켠다. GitHub 의 push protection은 사후에 알리는 대신 비밀값이 든 push 를 저장소에 닿기 전에 막는다.
  4. 새어 나갔다면 기록 삭제보다 키 교체가 먼저다. GitHub 의 민감 정보 제거 문서는 비밀번호·토큰이 올라갔다면 첫 단계로 그 비밀을 폐기하거나 교체해야 한다고 적는다. 기록을 지워도 이미 복제된 사본은 남는다.

그리고 한 가지 더. 인증정보를 프롬프트 안에 직접 붙여 넣지 않는다. 프롬프트는 로그로 남고, 다른 대화로 복사되고, 지금처럼 다른 사람에게 전달된다. 환경 변수나 이미 로그인된 CLI 를 쓰게 하는 편이 낫다.

5. 고쳐 쓴 프롬프트의 뼈대

위 내용을 반영하면 프롬프트는 이런 순서가 된다. 원문의 좋은 부분은 그대로 두고, 빈 곳만 채웠다.

[목표]     위키독스에 그대로 옮길 수 있는 ○○ 대비서. 독자는 초급자.
[자료]     ① 참고 페이지 사본: ./ref/style-sample.pdf
           ② 시험 자료: ./ref/*.pdf  (저장소에 올리지 않음)
           ③ 부족하면 공식 문서만 추가 조사. 출처를 각주로.
[실패 규칙] 필수 자료를 열지 못하면 멈추고 알린다. 추측으로 채우지 않는다.
[기준일]   기준일 2026-04-05. 이후 바뀐 내용은 반영하되 "변경됨" 각주.
[구성]     첫 페이지 → 소개 → 목차 → … → 마무리 (원문 유지)
[연락처]   이메일: 넣지 않음 / 단톡방: (링크)
[저장소]   쓰기 권한 확인 후 시작. .gitignore 먼저. 커밋 전 diff 확인.
[문체]     과장 제목 금지, 굵게·장식 이모지 금지 (원문 유지)
[진행]     목차부터 제출 → 승인 → 장별 집필 → 장별 검수 → 전체 검수

가장 중요한 줄은 마지막 줄이다. 책 한 권을 한 번에 쓰게 하지 말자. 목차를 먼저 받아 사람이 승인하고, 장 단위로 쓰고 고친다. 원문의 검수 지시(번호·순서·중복)는 다 쓰고 나서 한 번에 하면 놓치기 쉽다. 목차가 확정돼 있으면 “Part 3 Chapter 2 가 두 번 나온다” 같은 오류가 애초에 덜 생긴다.

정리 — AI 로 책을 쓸 때 사람이 할 일

사람이 정할 것 왜
빈칸을 값이나 생략으로 확정 AI 는 빈칸을 지우거나 지어내거나 그대로 남긴다
자료를 경로·첨부로 지정 “앞서 준 자료”는 새 대화에선 없다
못 읽으면 멈추라는 규칙 읽은 척이 가장 위험한 실패다
기준일과 최신성의 우선순위 안 정하면 장마다 다르게 고른다
권한 확인과 보안 장치 지시만으로는 실수를 못 막는다
목차 승인 후 장 단위 진행 검수는 끝에 몰면 놓친다

AI 는 원고를 빨리 쓴다. 하지만 무엇이 확정이고 무엇이 아직 빈칸인지는 여전히 사람이 정해야 한다. 이번 프롬프트에서 실행보다 정리를 먼저 한 건 결과적으로 맞는 순서였다. 다섯 개의 빈칸이 원고 수백 쪽 뒤가 아니라 첫 페이지 앞에서 드러났기 때문이다.

References