AI가 말을 안 듣는다고? 8년차 개발자가 6개월간 Claude Code로 시스템을 구축하며 깨달은 프롬프트 엔지니어링의 본질

 

AI 프롬프트 엔지니어링을 제대로 활용하면 AI의 출력 품질이 완전히 달라집니다. 🚀

 

8년차 개발자의 6개월 실전 경험에서 나온 이야기인데요, Claude Code 하나로 수천 줄짜리 내부 프로그램을 혼자 처음부터 다시 만들며 구축한 시스템을 공개합니다.

 

그 핵심은 하나입니다. AI를 그냥 쓰면 50점짜리지만, 시스템을 만들어주면 95점짜리가 된다는 것.

 

AI 코딩 도구 하나만 가지고 혼자서 책 300~400건 분량의 프로그램을 6개월 만에 처음부터 다시 만들었다고 합니다.

 

어떻게 가능했을까요? 그 비밀 시스템을 하나씩 풀어보겠습니다. 🔍

 

 

 

🤔 AI가 말을 안 듣는 진짜 이유

 

AI를 써봤다면 이런 경험 한 번쯤 있을 겁니다.

 

뭔가를 시켰는데, 처음엔 잘 따라가다가 어느 순간 보면 완전히 다른 걸 하고 있어요. 😅

 

“우리 이거 하기로 했잖아” 하면 “아, 맞다 죄송합니다” 하면서 또 엉뚱한 방향으로 빠지고…

 

능력은 좋은데, 30분마다 자기가 뭘 하고 있었는지 까먹는 신입 직원 같은 거예요. 매뉴얼도 안 보고, ‘다 했다’더니 실수투성이고.

 

여기서 중요한 인사이트는, 문제는 AI의 능력이 절대 아니라는 점입니다.

 

아무리 능력 좋은 신입도 그냥 놔두면 헤맵니다. 업무 매뉴얼과 체크리스트, 보고 체계를 잡아주면 갑자기 에이스가 되죠.

 

AI도 마찬가지입니다. 시스템 환경이 전부에요.

 

‘왜 AI를 쓰는데 이렇게 답답하지?’ 싶었다면, 도구를 탓하기 전에 그 도구를 쓰는 ‘환경’부터 한 번 점검해봐야 합니다.

 

 

 

🛠️ 시스템 1 — 매뉴얼을 강제로 읽히는 자동화 장치

 

Claude Code에는 ‘스킬(Skills)’이라는 기능이 있습니다. 작업 유형별로 지침을 미리 적어두는 업무 매뉴얼이에요.

 

문제는, 제가 수천 줄짜리 가이드라인을 꼼꼼히 만들었는데… AI가 그걸 그냥 안 봤다는 거죠. 😤

 

설명서 안 보고 나사 반대로 끼우는 상황이 계속 반복됐어요.

 

해결책은 ‘후크(Hook)’ 기능을 활용한 자동 알림 장치를 만드는 것이었습니다. 두 가지로 구성됩니다.

 

 

🔔 시작 전 알림 장치

 

AI가 지시를 받는 순간, 내용을 분석해서 관련 매뉴얼을 먼저 전달합니다.

 

마치 옆자리 선배가 “야, 이 업무는 메뉴 3번 참고해야 돼” 하고 귀띔하는 느낌이에요.

 

 

✅ 완료 후 체크 장치

 

작업이 끝나면 “에러 처리는 추가했나요?”, “이 부분 확인했나요?” 하고 부드럽게 상기시킵니다.

 

 

🎯 매뉴얼 호출의 4가지 조건

 

어떤 매뉴얼을 꺼낼지 판단하는 조건을 정해뒀어요.

 

1. 키워드 (예: 백엔드, API)

2. 의도 파악 (예: “기능 추가”라는 명령)

3. 작업 위치 (수정 중인 폴더)

4. 파일 내용 (특정 코드 패턴 감지)

 

이 네 가지가 동시에 돌아가면서, 관련 매뉴얼이 자동으로 따라옵니다.

 

 

💡 한 가지 더 중요한 최적화

 

처음엔 매뉴얼 하나가 1,500줄이 넘었어요. 신입에게 일 시킬 때마다 300페이지짜리 책을 통째로 읽으라는 셈이었죠.

 

간략한 목차와 상세 챕터 파일로 분리했더니, AI가 소비하는 자원이 40~60% 줄었습니다.

 

불필요한 컨텍스트 소비가 없어지니 응답 속도도 빨라지고, 답변 품질도 올라갔어요.

 

이 셋업에 이틀이 걸렸고, 그 이후로 10배 이상 본전을 뽑았습니다.

 

 

 

🐠 시스템 2 — AI의 금붕어 기억력을 해결하는 3가지 문서

 

AI는 자신감은 하늘을 찌르는데, 기억력은 금붕어 수준입니다. 😵

 

아무리 완벽한 계획을 세워놔도, 대화가 길어지면 “우리가 뭘 하고 있었더라?” 이러거든요.

 

인테리어 업자가 30분마다 기억을 잃어서 “저희가 뭐 하기로 했죠?” 이러는 것과 같아요.

 

해결책은 AI의 외부 기억장치 역할을 하는 세 가지 문서를 만드는 것이었습니다.

 

 

📋 1. 계획서 (설계도)

 

이번에 뭘 만들 건지, 전체 프로젝트 진행 방향을 담은 문서입니다.

 

이 문서가 있으면 AI가 새 대화를 시작해도 방향을 잃지 않습니다.

 

 

📝 2. 맥락 노트 (시방서)

 

“왜” 이렇게 결정했는지를 기록한 문서입니다.

 

이전 대화에서 내린 판단의 근거, 참고 자료 위치 등이 담깁니다. 계획서와 달리 이유와 배경에 집중하죠.

 

 

✅ 3. 할 일 체크리스트 (공정표)

 

지금 어디까지 했는지 실시간으로 추적하는 문서입니다.

 

체크리스트가 있으면, AI가 완료된 항목을 다시 시작하는 사고를 막을 수 있어요.

 

 

🚦 실행 핵심 포인트

 

1. 계획 검토 필수: AI가 계획을 세우면 바로 넘어가지 말고 꼼꼼히 검토하세요. AI가 핵심을 오해하는 경우가 생각보다 훨씬 많습니다.

2. 문서화 후 재시작: 계획이 승인되면, 바로 달려들려는 AI를 멈추고, 세 개의 문서를 저장하게 하세요. 새 대화에서 “저장된 문서 읽고 이어서 작업해” 한 마디면 됩니다.

3. 한 번에 하나씩: 한 번에 전부 시키지 말고, 하나씩 끝내고 확인한 다음 다음 작업을 지시하는 게 핵심이에요.

 

이 방식으로 30분 전에 세운 계획이 2시간 후에도 그대로 유지됩니다.

 

 

 

🔬 시스템 3 — 자동 품질검사

 

“다 했습니다!” 하고 자신감 넘치게 말하는데, 뒤에서 보면 실수가 수두룩한 경우가 많죠. 🧐

 

AI가 일을 끝낼 때마다 자동으로 품질검사가 돌아가도록 만든 이유입니다.

 

 

📹 변경 기록 감시 (CCTV)

 

파일을 수정할 때마다 자동으로 기록하고, AI가 대답을 완전히 끝냈을 때 그 수정 내역을 검사합니다.

 

 

⏱️ 타이밍의 중요성

 

파일을 고칠 때마다 바로 검사를 돌리는 건 비효율적이었어요. 요리 중간에 간을 보면 당연히 안 맞잖아요?

 

“요리가 완성됐을 때 검사” 하는 방식으로 바꿨습니다.

 

 

🚨 에러 대응 프로토콜

 

오류가 적으면 즉시 수정, 오류가 많으면 ‘전문 수리 에이전트’를 투입하는 구조예요.

 

거기에 “에러 처리는 추가했나요?” 같은 셀프 체크 리마인더도 붙여뒀습니다.

 

이 시스템 도입 후로, AI가 실수를 남기고 넘어간 경우가 단 한 번도 없었습니다.

 

 

 

👨‍💼 시스템 4 — 전문 에이전트 시스템

 

하나의 AI한테 이것저것 다 시키면, 대충 넘어갈 때도 있습니다.

 

품질관리팀, 테스트팀, 기획팀처럼 역할별 전문 AI 팀원을 배치한 이유예요.

 

 

📊 구체적 보고 요구

 

중요한 건 “다 했습니다” 대신 “구체적인 보고서”를 요구하는 것입니다.

 

“무엇을 발견했고, 무엇을 수정했고, 왜 그렇게 판단했는지 정리해서 와라.”

 

 

👁️ 제3자의 눈

 

특히, AI가 만든 결과물을 다른 AI 팀원이 검토하게 하면, 누락된 부분이나 보안 취약점 같은 것들을 꽤 잘 잡아냅니다.

 

 

 

🌉 마치며: AI 시스템 구축, 생각보다 멀지 않습니다

 

Claude든 ChatGPT든, 어떤 AI를 써도 이 원리는 같습니다.

 

셋업에 이틀을 투자하고 이후 10배 이상 본전을 뽑았다는 말이, 단순한 과장처럼 들릴 수 있지만…

 

매뉴얼을 AI가 알아서 읽게 만들고, 기억 문서로 맥락을 유지하면, 실제로 체감 품질이 달라지기 시작합니다.

 

다음에 AI한테 뭔가 시킬 때, 먼저 “매뉴얼 한 장”만 써줘 보세요.

 

“이 작업을 할 때는 이것을 지켜야 해”라는 문서 하나. 그 차이가 생각보다 큽니다.

 

 

 

❓ Q&A: 궁금할 수 있는 질문들

 

1. 이 시스템을 구축하려면 프로그래밍 지식이 필수인가요?

> 전반적인 개념은 도구에 상관없이 적용 가능합니다. Claude Code의 ‘스킬’과 ‘후크’ 같은 고급 기능을 쓰려면 약간의 설정이 필요하지만, ChatGPT에서도 프롬프트에 “항상 다음 가이드라인을 먼저 참고해라”고 명시하는 식으로 기본 원리를 적용할 수 있습니다.

 

2. 매뉴얼을 작성하는 데 얼마나 시간이 걸리나요?

> 처음에는 시간이 걸립니다. 하지만 자주 반복되는 작업(예: API 만들기, 에러 처리)에 대한 매뉴얼을 우선순위로 작성하면, 한 번 투자한 시간이 이후 엄청난 시간을 절약해줍니다. 점진적으로 확장해나가는 것이 핵심입니다.

 

3. ‘기억 문서’는 매번 직접 작성해야 하나요?

> 아닙니다. AI가 계획을 세우거나 결정을 내릴 때, “이 내용을 계획서/맥락노트에 요약해줘”라고 지시하면 AI가 대부분 작성해줍니다. 사용자는 검토와 보정만 하면 됩니다.

 

4. 소규모 프로젝트에도 이렇게까지 시스템화할 필요가 있을까요?

> 프로젝트 규모보다 ‘작업의 복잡성’이 더 중요한 기준입니다. 간단한 질문엔 과할 수 있지만, 30분 이상 소요되거나 여러 파일이 관여되는 작업이라면, 시스템의 일부(예: 체크리스트)만 적용해도 실수율이 현저히 줄어듭니다.

 

5. 가장 먼저 시작해야 할 것은 무엇인가요?

> ‘가장 자주 반복되고, 가장 실수하기 쉬운 작업’ 하나를 골라, 그 작업만을 위한 1페이지 분량의 간단한 매뉴얼을 작성하는 것입니다. 그 한 가지에서 생산성과 품질 향상을 체감한 후, 다른 부분으로 확장해나가세요.

2026.02.19 - [Ai] - AI 시대, 2026년 이후 살아남을 진짜 유망 학과는? 전기전자·통계학과의 기회 분석

AI 시대, 2026년 이후 살아남을 진짜 유망 학과는? 전기전자·통계학과의 기회 분석