같은 실수가 두 번이면 레슨이 아니라 훅
AI의 되풀이 실수는 기억이 아니라 장치로 막는다
AI와 일하다 보면 같은 실수가 다시 나옵니다. 그때마다 「다음엔 이렇게 하자」를 레슨이라는 기록으로 남기지만, 기록은 AI가 다음에 읽어야만 효과가 있습니다. 이 글은 2026년 10월 21일 현장에서 같은 실수가 되풀이된 사례와, 그것을 클로드 코드의 「훅」으로 막은 방법을 정리했습니다.
1. 무슨 일이 있었나
현장 PC를 원격으로 잇는 꾸러미가 있습니다. 담당자가 PC에서 파일 하나를 관리자 권한으로 두 번 클릭하면, 원격 접속 문인 SSH가 열리고 AI가 그 PC에 붙을 수 있게 됩니다.
이 꾸러미의 2단계는 윈도의 「선택적 기능」 명령인 Add-WindowsCapability로 OpenSSH 서버를 설치합니다. 그런데 이 명령은 PC에 따라 윈도 업데이트를 거치느라 수십 분씩 멈춥니다.
- 10월 15일, 한 현장 PC에서 2단계가 멈췄습니다. AI는 8분 시간 제한을 붙이고 레슨을 적었습니다. 고친 것은 정본 꾸러미 하나였습니다.
- 10월 21일, 다른 현장 PC에 보낸 꾸러미가 같은 2단계에서 20분 넘게 멈췄습니다. 이 꾸러미는 정본이 아니라 10월 9일 판을 바탕으로 만들어져, 15일의 처방마저 빠져 있었습니다. 18일에 보낸 다른 PC 꾸러미도 같은 결함을 안고 있었습니다.
- 그동안 현장 담당자는 휴무날 PC 앞에 앉아 멈춘 화면을 지켜봤습니다.
15일의 레슨은 파일로 남아 있었습니다. 21일에 꾸러미를 새로 만든 AI는 그 레슨을 읽지 않았습니다.
2. 레슨으로는 왜 못 막았나
레슨은 읽혀야 작동합니다. 읽을지 말지는 다음 작업자의 몫입니다. AI는 매 작업마다 새로 시작하고, 수백 개의 기록 가운데 무엇을 읽을지는 그때그때의 검색에 달려 있습니다. 꾸러미를 「옛 판을 복사해 고친다」는 흐름으로 만들면, 「OpenSSH 설치 방식」에 관한 레슨을 찾아볼 계기가 생기지 않습니다.
게다가 15일의 처방 자체가 반쪽이었습니다. 시간 제한은 멈춤을 8분으로 줄였을 뿐, 사람을 화면 앞에 세워 두는 단계는 그대로 남겼습니다. 그리고 같은 모양이 퍼져 있는 다른 꾸러미들은 고치지 않았습니다.
정리하면 실패는 세 겹입니다.
- 눈앞의 한 자리만 고쳤다. 같은 모양이 퍼진 곳은 그대로 뒀다.
- 증상만 줄였다. 멈추는 명령을 빼지 않고 시간만 제한했다.
- 기록으로 끝냈다. 다시 못 하게 막는 장치를 걸지 않았다.
3. 훅이란
클로드 코드에는 훅이라는 장치가 있습니다. AI가 파일을 쓰거나 명령을 실행하거나 메시지를 보내려는 순간 자동으로 끼어들어 정해진 검사 프로그램을 돌리는 장치입니다.
- 설정 파일
settings.json에 「어떤 도구를 쓸 때」「어떤 프로그램을 돌릴지」를 적습니다. - 도구가 실행되기 직전에 검사 프로그램이 쓰려는 파일 내용이나 실행하려는 명령을 받습니다. 이 시점을 PreToolUse라고 부릅니다.
- 검사 프로그램이 종료코드 2로 끝나면 그 도구 실행이 막히고, 프로그램이 남긴 메시지가 AI에게 전달됩니다. AI는 왜 막혔는지 읽고 다른 길로 갑니다.
레슨과 훅의 차이는 하나입니다. 레슨은 AI가 읽어야 작동하고, 훅은 AI가 읽든 안 읽든 그 자리에서 작동합니다.
4. 이번에 건 훅
guard-win-capability.py는 윈도 꾸러미에 Add-WindowsCapability가 다시 들어가는 길을 막습니다.
막는 자리는 실수가 다시 나올 수 있는 길 네 곳입니다.
| 길 | 막는 조건 |
|---|---|
| 파일 쓰기·고치기 | .ps1·.bat 파일에 주석이 아닌 줄로 그 명령을 넣을 때 |
| 옛 꾸러미 복사·압축 | 복사·zip·업로드 명령이 가리키는 파일이나 zip 안 파일에 그 명령이 있을 때 |
| 메시지로 보내기 | 텔레그램으로 첨부하려는 zip 안에 그 명령이 있을 때 |
| 원격 실행 | ssh·powershell로 원격 PC에서 그 명령을 돌리려 할 때 |
통과시키는 것도 정해 두었습니다.
grep·cat같은 읽기는 통과합니다. 옛 꾸러미를 들여다보는 것까지 막으면 조사가 안 됩니다.- 주석 줄은 통과합니다. 「여기서 이 명령을 쓰지 마라」는 설명은 남아야 합니다.
- 꼭 필요할 때는 같은 줄에 정해진 표식을 적으면 통과합니다. 출구가 없는 장치는 결국 꺼집니다.
막힐 때 AI가 받는 메시지에는 무엇을 대신 써야 하는지 적었습니다. 깃허브 판 OpenSSH를 바로 설치하는 정본 꾸러미의 2단계 블록입니다. 막기만 하면 AI가 우회로를 찾습니다. 맞는 길을 같이 알려 줘야 합니다.
시험은 아홉 가지로 했습니다. 막혀야 할 것은 파일에 명령 쓰기, 옛 꾸러미 복사, 옛 zip 발송, 원격 실행, 텔레그램 첨부 다섯입니다. 통과해야 할 것은 새 정본 복사, 고친 꾸러미 발송, 읽기, 주석 넷입니다. 첫 시험에서 옛 zip 발송이 통과됐습니다. curl -F document=@경로의 @를 경로로 못 읽은 탓이었습니다. 고친 뒤 다시 막히는 것을 확인했습니다. 막힘과 통과를 둘 다 시험하지 않으면 훅은 쉽게 가짜가 됩니다.
5. 원칙
- 같은 실수가 두 번 나오면 레슨이 아니라 훅을 건다. 한 번은 기록, 두 번째는 장치입니다.
- 증상이 아니라 원인을 뺀다. 멈추는 명령에 시간 제한을 거는 대신, 그 명령을 쓰지 않고 깃허브 판을 바로 설치하는 길로 바꿉니다. 훅은 그 바꾼 길을 지키는 자리입니다.
- 고치면 전수로 고친다. 같은 모양이 남은 파일을 다 찾아 같이 고칩니다. 그다음에 훅을 겁니다. 훅부터 걸면 이미 나가 있는 옛 판이 남습니다.
- 실수가 다시 들어오는 길마다 건다. 쓰기만 막으면 복사로 들어오고, 복사만 막으면 발송으로 나갑니다.
- 읽기는 막지 않는다. 훅이 조사까지 막으면 사람이 훅을 끕니다.
- 막을 때 대신할 길을 알려 준다.
- 막힘과 통과를 둘 다 시험한다.
- 훅은 적게, 굵게. 모든 레슨을 훅으로 만들면 AI가 아무것도 못 합니다. 되풀이된 것, 사람의 시간을 쓰게 했거나 안전을 해친 것만 훅으로 올립니다.
6. 현장 AI에게도 같다
현장에는 그 조직 곁에서 일하는 AI가 따로 있습니다. 그 AI도 레슨 폴더에 하루 몇 건씩 「다음엔 이렇게」를 쌓습니다. 이 레슨들도 읽히지 않으면 그대로 되풀이됩니다.
현장 AI의 레슨 가운데 두 번 이상 나온 것은 그 AI의 설정 파일에 훅으로 거는 것을 권합니다. 예를 들어 「남에게 일을 넘기기 전에, 그 주제의 앞선 결정을 일지에서 찾았는가」를 넘기는 순간 확인하게 할 수 있습니다. 어느 실수를 훅으로 올릴지는 그 AI와 조직이 정합니다.
7. 시사점
- 이번에 일이 막힌 원인은 사람이 아니었습니다. AI가 만든 꾸러미와 기록 구조가 사람을 화면 앞에 세웠습니다. 되풀이되는 실수의 비용은 대개 현장 사람의 시간으로 치러집니다.
- AI는 같은 실수를 되풀이합니다. 다짐이나 기록에 맡기면 다음 판에서 또 납니다. 사람 조직이 체크리스트와 결재선으로 실수를 구조로 막듯이, AI는 훅으로 막습니다.
- 기록과 장치는 함께 갑니다. 레슨은 「왜」를 남기고, 훅은 「다시는」을 지킵니다. 훅 파일 머리에 그 레슨이 무엇이었는지 적어 두면, 나중에 훅을 고칠 사람이 왜 있는지 압니다.