AI에게 코드를 시킬 때 통한 지시, 안 통한 지시

같은 날 오전에는 됐던 지시가 오후에는 안 먹히고, 어제 잘 만들어진 페이지를 오늘 손봐 달라고 하면 엉뚱한 파일까지 건드리는 순간이 옵니다. AI에게 코드를 시키는 법을 찾아보면 대부분 “이런 문장을 쓰면 잘 나온다”는 식의 주문 모음이 나오지만, 이 블로그를 만들며 실제로 겪은 건 그런 문제가 아니었습니다. 이 글은 클로드 코드로 이 사이트를 만드는 동안 실제로 통한 지시 방식과, 안 통해서 사고로 이어진 지시를 그대로 기록합니다.

매번 설명하는 대신 파일에 적어둔다

“이 사이트는 코딩을 모르는 사람이 본다”는 설명을 대화할 때마다 반복하면 AI는 그 세션에서만 기억하고 다음 세션에서는 잊습니다. 통했던 방식은 그 설명을 대화가 아니라 파일에 적어두는 것이었습니다.

이 프로젝트에는 CLAUDE.md라는 파일이 있습니다. “나는 코딩을 모른다”, “설명은 한국어로, 짧게 한다” 같은 규칙이 적혀 있고, 세션을 새로 열 때마다 자동으로 불러들여집니다. 글을 쓸 때 지킬 문체 규칙도 .claude/rules/writing-tone.md라는 별도 파일에 적어뒀습니다 — “과도한 비유법 금지”, “용어 풀이는 처음 나올 때 넣는다” 같은 내용입니다. 이 파일 하나 덕분에 매번 “비유 좀 줄여줘”라고 되풀이하지 않아도 됩니다.

이 프로젝트는 사회복지사가 읽는 글을 쓰는 곳이야.
앞으로 글을 쓸 때 지킬 규칙을 정리해서 .claude/rules/writing-tone.md 파일로 만들어줘.
- 어려운 개념은 비유 대신 직설적으로 설명할 것
- 비유는 꼭 필요할 때 1개 정도만 허용
- 용어는 처음 등장할 때 풀어서 설명할 것
이 파일을 만든 다음부터는 글을 쓸 때마다 이 규칙을 확인하고 따라줘.

한 번에 하나만 시킨다

“홈페이지도 손보고, 새 글도 쓰고, 디자인도 바꿔줘”처럼 한 번에 여러 일을 던지면 결과물이 뒤섞입니다. AI가 세 가지를 동시에 처리하다 어느 하나를 빠뜨려도, 어디서 빠졌는지 찾기가 어렵습니다.

통한 방식은 반대였습니다. “이번엔 이 기능 하나만” 하고 끊어서 시키고, 그게 끝났는지 확인한 다음에 다음 일로 넘어갔습니다. 이 원칙은 지금도 프로젝트 규칙 파일에 “한 번에 한 기능만 진행한다. 큰 작업을 한꺼번에 벌이지 않는다”고 그대로 적혀 있습니다.

오늘은 커스텀 도메인 연결 작업만 해줘.
다른 페이지 디자인이나 글 내용은 건드리지 말고,
이 작업 하나가 끝나면 무엇을 확인하면 되는지도 알려줘.

근거를 먼저 못 박는다

사실 확인이 필요한 글을 쓸 때, “이 내용으로 글을 써줘”라고만 시키면 AI는 그럴듯하지만 틀린 내용을 자연스러운 문장으로 만들어냅니다. 법 관련 글을 쓸 때 실제로 겪은 문제입니다.

통한 방식은 조사부터 따로 시키고, 그 결과를 문서 파일로 먼저 만든 다음, “여기 없는 내용은 지어내지 말고 글을 써라”고 못 박는 것이었습니다. 이 프로젝트에서는 국가법령정보센터 조문 원문을 대조해 docs/ai-law-facts-2026-08.md라는 파일을 먼저 만들었습니다. 이 근거 파일에는 확인된 사실뿐 아니라 “이렇게 쓰면 틀린다”는 항목도 따로 정리해뒀는데, 실제로 흔히 도는 통설 중 사실과 다른 내용이 있었기 때문입니다. 법·제도를 다루는 글 다섯 편 모두 이 방식으로 썼고, 나중에 되짚어 봐도 어긋난 내용이 없었습니다.

이 글은 docs/ai-law-facts-2026-08.md 에 정리된 내용만 근거로 써야 해.
이 파일에 없는 조문 번호나 수치는 절대 지어내지 마.
확실하지 않은 부분은 "확인이 필요합니다"라고 쓰고,
글을 다 쓴 뒤 어느 문장이 이 파일의 어느 항목에서 나왔는지 짚어서 알려줘.

진행 상황을 문서에 남긴다

세션 하나가 끝나면 그날 무엇을 했고, 다음에 무엇을 하면 되는지가 대화창 안에만 남습니다. 다음에 새 대화를 열면 그 내용은 사라집니다.

통한 방식은 그날 한 일과 다음에 할 일을 HANDOFF.md라는 파일에 통째로 다시 써서 남기는 것이었습니다. 새 세션을 시작하면 이 파일부터 읽고 이어서 작업합니다. 굳어진 결정(“이건 되돌리지 말 것”)과 아직 안 끝난 일(“다음에 할 것”)을 나눠 적어두면, 다음 세션이 지난 세션의 맥락을 처음부터 다시 설명받지 않아도 이어받습니다.

오늘 세션에서 한 것과 다음 세션이 이어서 할 것을 HANDOFF.md 에 정리해줘.
- 오늘 바꾼 파일과 무엇을 왜 바꿨는지
- 되돌리면 안 되는 결정
- 다음에 할 일을 순서대로
이 파일은 덧붙이지 말고 전체를 다시 써서 최신 상태로 유지해줘.

안 통했던 지시, 사고가 난 지시

여기까지는 실제로 효과가 있었던 방식입니다. 아래는 반대로 안 통했거나 사고로 이어졌던 지시입니다. 실제로 겪은 일이라 이 글에서 가장 값어치가 있는 부분입니다.

검증 없이 “다음으로 가자”고 하면, 안 되는 걸 된 줄 알고 넘어갑니다.

한 시기에 배포가 다섯 번 연속 실패한 적이 있습니다. 제 컴퓨터에서 빌드를 돌리면 오류 없이 통과됐기 때문에 “됐겠지” 하고 다음 일로 넘어갔는데, 정작 인터넷에 올라가는 단계에서 계속 죽고 있었습니다. 그 뒤로는 끝났다는 말을 믿지 말고 결과를 눈으로 확인한다를 규칙 파일에 못 박았습니다. 이 사고가 왜 났고 무엇을 확인해야 하는지는 3편에서 다룹니다.

여기서 얻은 지시 습관은 이겁니다. “다 됐어?“라고 묻는 대신, 무엇을 보면 끝난 줄 알 수 있는지를 먼저 정해서 같이 시킨다.

한 번에 여러 개를 동시에 시키면 서로의 작업을 덮어씁니다.

글 여러 편을 한꺼번에 여러 작업 단위에 나눠 쓰게 한 적이 있습니다. 그런데 두 작업이 같은 파일 하나(다른 글의 “관련 글” 목록)를 동시에 고치면서, 나중에 저장된 쪽이 먼저 저장된 내용을 지워버렸습니다. 이후로는 같은 파일을 건드릴 수 있는 작업은 동시에 진행하지 않고, 파일이 겹치면 순서를 정해 하나씩 처리하도록 방식을 바꿨습니다. 되돌리기 명령을 잘못 쓰다가 동시에 진행 중이던 다른 작업분이 통째로 사라질 뻔한 적도 있어서, 지금은 되돌리기 계열 명령 자체를 쓰지 못하게 막아뒀습니다.

확인 안 한 사실을 그럴듯하게 써냅니다.

법 관련 글을 쓸 때, 검색으로 나오는 2차 자료(뉴스레터·블로그 요약)만 근거로 삼으면 실제로 흔히 도는 통설을 그대로 옮기게 됩니다. 조문 원문과 대조해보니 그중 일부는 정확하지 않은 내용이었습니다. AI는 자신이 쓴 문장이 맞는지 스스로 의심하지 않으므로, 원문을 직접 대조하고 사람이 다시 검수하는 과정 없이는 이런 오류를 걸러낼 수 없었습니다.

결국 남는 감각

네 가지를 한 문장으로 묶으면 이렇습니다 — 일을 잘게 쪼개고, 근거가 필요한 일에는 근거를 먼저 만들어 못 박고, 그 결과를 사람이 직접 확인한다. 사회복지사가 실습생이나 자원봉사자에게 업무를 맡길 때 쓰는 감각과 다르지 않습니다. 무슨 일인지 정확히 알려주고, 참고할 자료를 챙겨주고, 다 끝난 뒤에는 결과를 눈으로 확인하는 것 — AI에게 코드를 맡기는 일도 똑같습니다.

다음 단계

이 시리즈의 1편 코딩 몰라도 블로그를 직접 만든 이유에서는 왜 직접 만들기로 했는지, 무엇을 썼는지를 다룹니다. 배포와 유지보수 과정에서 실제로 터진 사고는 3편 배포하고 나서 실제로 일어난 일에서 이어집니다. 프롬프트를 문서 작성에 바로 적용해보고 싶다면 AI 프롬프트 작성법도 참고하세요.

자주 묻는 질문

코딩을 전혀 몰라도 이런 방식으로 AI에게 코드를 시킬 수 있나요?

네. 이 글에서 다룬 방식은 코드 문법을 아는 것과는 상관없습니다. 일을 작게 나누고, 참고할 자료를 챙겨주고, 결과가 실제로 맞는지 눈으로 확인하는 것뿐이라 코딩을 몰라도 그대로 따라 할 수 있습니다. 실제로 이 블로그 전체가 그렇게 만들어졌습니다.

규칙 파일(CLAUDE.md 같은 것)은 꼭 미리 다 갖춰놓고 시작해야 하나요?

그렇지 않습니다. 처음에는 규칙 파일 없이 시작했고, 같은 설명을 반복하게 되거나 원치 않는 결과가 반복될 때마다 그 내용을 규칙 파일에 하나씩 추가했습니다. 미리 완벽하게 준비하기보다, 겪은 문제를 그때그때 파일에 적어두는 쪽이 실제로 더 잘 통했습니다.

검증은 구체적으로 어떻게 하나요? 저도 코드를 볼 줄 모르는데요.

코드를 읽을 필요는 없습니다. 이 프로젝트에서는 “빌드(변환 작업)가 오류 없이 끝나는지”와 “브라우저로 실제 페이지를 열어 눈으로 확인하는지” 두 가지만 기준으로 삼았습니다. 화면에 글이 잘 뜨는지, 링크를 눌렀을 때 원하는 페이지로 가는지처럼 눈으로 보이는 결과를 확인하는 것으로 충분합니다.