AI가 쓰는 파이썬 코딩
0. 사람이 쓰는 코드와 무엇이 다른가
보통 파이썬은 사람이 쓰려고 짜지만, 여기서 다루는 파이썬은 쓰는 쪽이 AI입니다. 우리가 쓰는 코딩 에이전트인 클로드 코드가 일하는 동안 스스로 불러 쓰거나, 에이전트가 도구를 쓰려는 순간 끼어들어 막거나 알려 주는 작은 프로그램들이고, 만드는 목적은 둘입니다.
- 매번 새로 만들지 않기 위해서입니다. 배포가 됐는지 확인하는 코드, 문서를 위키에 올리는 코드를 세션마다 즉석에서 짜면 매번 조금씩 다르게 짜고, 매번 다른 곳에서 틀립니다. 한 번 제대로 만들어 두고 불러 씁니다.
- 같은 오류를 반복하지 않기 위해서입니다. AI는 지난 세션을 기억하지 못하고, 교훈을 문서로 남겨도 다음 세션의 AI가 그 문서를 읽는다는 보장이 없습니다.
더 무거운 쪽은 두 번째입니다. 2026년 9월에 레슨 기록 718건을 전수 조사해 보니 「레슨이 있는데도 또 틀린」 경우가 85건이었고, 레슨은 지금 1,000건을 넘었습니다. 가장 큰 덩어리는 완료를 틀린 방법으로 판정한 것이었습니다. 기록해도 안 읽으면 그만이라서 규칙을 문서에서 꺼내 코드로 옮겼습니다. 이 노드는 그렇게 옮긴 것들의 목록이고, 코드 대신 무엇을 하는지와 어떻게 작동하는지만 적습니다.
1. 끼어드는 자리 다섯 곳
클로드 코드에는 훅이라는 기능이 있습니다. 정해진 순간에 지정한 스크립트를 실행하는데, 스크립트는 표준입력으로 「지금 AI가 무엇을 하려는지」를 JSON으로 받고, 종료코드와 출력으로 답합니다.
| 순간 | 쓰임 |
|---|---|
| 세션 시작 | 오늘 조심할 것을 미리 띄운다 |
| 사람이 말을 입력했을 때 | 말에 걸리는 기억·안내서를 찾아 넣어 준다 |
| AI가 도구를 쓰기 직전 | 위험한 명령을 막거나 경고한다 |
| 도구를 쓴 직후 | 방금 만든 결과물을 바로 검사한다 |
| AI가 답을 끝내려 할 때 | 빠뜨린 마무리가 있으면 다시 돌려보낸다 |
답하는 방법은 종료코드 0으로 조용히 통과하기, 맥락에 안내문 한 덩이 넣기, 종료코드 2와 이유를 내며 막기의 세 가지뿐입니다. 막을 때 내보낸 이유 문장은 AI가 읽기 때문에 차단 메시지에는 항상 「대신 이렇게 해라」를 같이 씁니다.
현재 걸려 있는 훅 29개를 하는 일로 묶으면 아래와 같습니다.
2. 기억을 불러오는 장치
AI가 기억이 없다는 문제를 정면으로 다루는 묶음입니다.
메모리 회상
사람이 말을 입력하면 그 말의 낱말로 메모리 색인을 grep해 관련 줄만 맥락에 넣습니다. 메모리 400여 개를 전부 상주시키면 비싸고, 아무것도 안 올리면 잊으니 그 사이를 검색으로 메웁니다. 임베딩 검색을 일부러 안 쓰는 이유가 있습니다. 훅에는 시간 제한이 있어서 로컬 모델을 다녀오다 시간을 넘기면 오류 없이 결과가 비어 버리고, 아무도 모르게 기억이 빠지기 때문에 grep만 씁니다. 한 번에 5줄, 세션당 10번, 같은 줄 중복 금지로 상한도 걸었습니다. 상한이 없으면 맥락이 계속 불어납니다.
검색 코퍼스 분리와 회귀 시험
상주하는 목차와 검색 대상 전체 목록을 다른 파일로 나눴습니다. 목차를 짧게 줄이다가 검색어까지 같이 지워져 회상률이 56%에서 36%로 떨어진 적이 있습니다. 지금은 세션이 시작될 때마다 전체 목록을 다시 만들고, 목차를 손대기 전후로 회상률을 재는 회귀 시험 스크립트를 돌립니다. 분리한 뒤 매칭률은 36%에서 70%로 올랐습니다.
재발 상위 3건
「또 틀렸다」는 지적을 모은 재발 대장에서 횟수가 가장 많은 3건을 세션 시작 때 세 줄로 띄웁니다. 전부 띄우면 아무도 안 읽으니 세 줄만 띄웁니다.
주제별 안내서 주입
말에 구글 드라이브·지메일 같은 신호가 있으면 구글 작업용 명령줄 도구 사용법을, 깃허브 신호가 있으면 계정 고르는 법을 미리 넣어 줍니다. 「그 도구 있다고 몇 번을 말하냐」는 지적이 계기였습니다.
분류를 실제 대상으로 풀기
「AI방에 올려」처럼 분류 이름으로 부르면 그 분류에 속한 실제 대화방 목록을 넣어 줍니다. 짝이 되는 차단 훅이 「어느 방이요?」를 사람에게 되묻는 질문을 막습니다.
접속 기계 판별
사람이 어느 컴퓨터에서 붙었는지를 SSH 출발 주소로 알아내 세션 시작에 알려 줍니다. 매번 사람이 말해 주던 것을 없앴습니다.
3. 위험한 길목을 막는 장치
도구를 쓰기 직전에 명령을 읽고 판정합니다. 공통 원칙은 좁게 잡는다입니다. 넓게 잡으면 오탐이 쌓이고, 오탐이 쌓이면 결국 사람이 훅을 끕니다.
배포는 배포 담당만
배포 명령이면 실행 주체가 배포 담당 에이전트인지 보고 아니면 막는데, 사람이 「직접 배포해」라고 말한 직후만 예외입니다. 같은 지적이 세 번 반복된 뒤 만들었습니다.
끊기 전에 파급부터
VPN·SSH·터널 같은 원격 접속 통로를 내리는 명령, 또는 공개 서브도메인에 물려 있는 서비스를 멈추는 명령을 막습니다. 코드를 검색해 쓰는 곳이 0건이어도 터널이 그 포트를 외부에 열어 두고 있을 수 있습니다. 확인을 마쳤으면 명령에 정해진 주석을 붙여 통과시킵니다. 무심코 하는 실행과 의식하고 하는 승인을 구분하는 표식입니다.
미리보기 서버는 내 컴퓨터에만
파이썬 내장 웹서버 같은 미리보기 도구는 아무것도 안 적으면 모든 네트워크에 열립니다. 위키 빌드 결과물을 그렇게 띄우는 바람에 로그인 게이트가 없는 사본이 내부망에 몇 분간 열린 일이 두 번 있었습니다. 주소를 127.0.0.1로 묶지 않은 실행은 막습니다.
남의 서버는 천천히
남이 운영하는 서버에 간격 없이 반복 요청하는 명령을 막습니다. 수집 스크립트가 초당 12건으로 작은 조직의 홈페이지 서버를 세운 일이 있었습니다. 명령줄 훅은 파이썬 내부에서 나가는 요청을 못 보기 때문에, 파이썬이 시작될 때 자동으로 읽히는 모듈에 속도 조절기도 심었습니다. 이쪽은 막지 않고 늦추는 장치라서, 같은 호스트로 가는 요청을 1초 간격으로 줄 세우고, 서버가 403·429를 돌려주거나 오류가 연달아 나면 그때 멈춥니다. 우리 서버와 자체 한도가 있는 대형 API는 손대지 않습니다.
기다리는 방법을 바로잡기
「끝났나」를 프로세스 목록으로 확인하는 대기 루프를 막습니다. 원격으로 pgrep -f를 돌리면 그 명령줄 자체가 검색어를 품고 있어서 언제나 「실행 중」으로 나오는데, 이 오탐에 이틀을 헛돌았습니다. 완료는 프로세스가 아니라 산출물로 판정하라고 4절의 도구를 안내합니다.
정해진 도구로 돌리기
구글 서비스를 MCP 도구나 날 API 호출, 웹 긁기로 건드리면 막고 검증된 명령줄 도구로 보냅니다. MCP 쪽은 메일 초안까지만 되고 발송이 안 돼서, 결국 사람에게 버튼을 누르게 한 일이 있었습니다.
현장에서 멈추는 명령 빼기
윈도 PC 세팅 꾸러미에 특정 기능 설치 명령이 들어가면 막습니다. 그 명령이 현장 PC 앞에 사람을 20분씩 세워 둔 일이 두 번 있어서, 다른 설치 경로를 처방으로 안내합니다.
경고만 하는 훅
SSH 서버 설정으로 계정 접근 경계를 세우려 하면 「이 기계는 VPN의 자체 SSH가 받고 있어서 그 설정을 거치지 않을 수 있다」고 알려 주기만 하고 막지는 않습니다. 설정 확인 명령이 값을 정확히 돌려주는 것을 보고 「걸렸다」고 읽었다가, 실제로는 그 경계가 전부 무효였던 일이 계기입니다.
4. 「다 됐다」를 기계가 판정하는 도구
재발 85건 중 가장 큰 군집이 완료 판정 오류였습니다. 「배포했습니다」「보냈습니다」「켰습니다」라고 말해 놓고 실제로는 안 된 경우입니다. 그래서 영역마다 판정 스크립트를 하나씩 두고, 종료코드 0이 나와야 완료라고 정했습니다. AI의 문장이 아니라 종료코드가 완료를 말합니다.
| 영역 | 도구가 하는 일 |
|---|---|
| 배포 | 주소를 캐시를 피해 열고, 그 배포에만 있는 고유 문자열이 본문에 있는지 본다. 커밋 번호 대조, 로그인 게이트 유무도 본다 |
| 화면 | 헤드리스 브라우저로 페이지를 열어 자바스크립트 오류가 0건인지, 버튼을 누른 뒤 요소가 사라지는지 본다 |
| 서비스 | 서비스가 살아 있는지, 포트가 열렸는지, 주소가 응답하는지 셋을 같이 본다 |
| 메시지 발송 | 원고와 대상 방을 확인하고 보낸 뒤, 보낸 메시지 번호를 발송 대장에 남긴다. 「이미 보냈나」를 먼저 본다 |
| 백그라운드 작업 | 기대 산출물 목록, 로그의 완료 표시, 파일 개수 중 하나로 판정한다 |
| 데이터베이스 API | 행 수와 총계가 기대와 같은지, 없는 테이블이 404인지, 노출되면 안 되는 테이블이 404인지 본다 |
| 발표 덱 | 화면·인쇄 두 매체, 여러 화면 폭에서 요소가 겹치거나 넘치는지 좌표로 잰다 |
| 가시성 | 글자 크기 분포와 구분선 대비를 숫자로 잰다. 빔 화면 모드는 기준이 더 높다 |
| 대외 문장 | 한국어 문장의 번역투·AI 말투를 재고, 교정본이 원문 내용을 잃지 않았는지 대조한다 |
| 뒷정리 | 작업이 끝났다고 보고한 뒤에도 살아서 요청을 보내는 고아 프로세스를 찾는다 |
이 도구들에는 각각 「왜 이렇게 생겼는지」가 붙어 있는데, 몇 가지를 들면 이렇습니다.
- 배포 확인이 「200 응답」만 보면 안 됩니다. 페이지는 200인데 스크립트 문법 오류로 6시간 동안 로그인이 안 된 일이 있었습니다. 그래서 화면 판정 도구가 따로 생겼습니다.
- 데이터베이스 API에는 배포 확인 도구를 쓸 수 없습니다. 캐시를 피하려고 주소에 붙이는 임의 파라미터를 API가 컬럼 필터로 읽고 400을 냅니다. 배포 탓이 아닌 가짜 실패라서 전용 도구를 따로 뒀습니다.
- 「없는 테이블도 200이면, 그 200은 존재의 증거가 아니다.」 판정 도구에는 반드시 일부러 틀린 대조군을 같이 넣습니다.
- 덱 검사기는 처음에 인쇄 모드에서, 아래쪽 침범만 쟀습니다. 화면에서는 표가 제목을 54픽셀 덮고 있었는데도 「겹침 없음」을 냈습니다. 지금은 두 매체, 여러 폭, 위아래 양방향을 다 잽니다.
판정 도구가 실패를 내면 먼저 내 가정을 의심합니다. 서비스 포트를 잘못 알고 있던 것을 검사기가 잡아 준 일도 있었습니다.
5. 만든 순간 고치는 장치
지켜보다가 잡는 대신, 결과물을 만든 바로 그 순간에 검사해서 오류를 그 자리에서 없앱니다.
HTML 저장 즉시 문법 검사
.html 파일을 쓰거나 고치면 그 안의 스크립트를 바로 문법 검사합니다. 오류가 있으면 그 자리에서 AI에게 돌려보냅니다. 위에 적은 6시간 사고는 닫는 괄호 하나 때문이었습니다.
산출물 전달 누락 막기
AI가 답을 끝내려 할 때, 이번 턴에 만든 문서를 링크로만 적고 실제 파일 전송은 안 했으면 다시 돌려보냅니다. 데스크톱 앱에서 링크만으로는 파일이 열리지 않는데, 같은 지적이 대여섯 번 나왔습니다.
배포 담당의 마감 점검
배포 담당 에이전트가 일을 끝낼 때, 배포를 했으면 판정 도구가 종료코드 0으로 끝났는지 보고, 새로 겪은 함정을 런북에 적었는지, 적을 게 없으면 「추가 없음」과 이유를 보고서에 남겼는지 봅니다.
큰 변경이면 분담 확인
한 번에 100줄 넘게 쓰면 「개발 담당에게 맡겼나」를 묻는 안내가 뜨지만 막지는 않습니다.
6. 비용을 지키는 장치
이미지 대리 읽기
이미지는 한 번 맥락에 들어오면 세션이 끝날 때까지 매 턴 다시 전송됩니다. AI가 이미지 파일을 읽으려 하면 작은 모델이 먼저 이미지를 분석하게 하고, 큰 모델은 그 결과 텍스트를 읽습니다. 중간 파일은 바로 지우고 하루 지난 캐시는 쓸어 냅니다. 이 훅 때문에 읽기 자체가 실패하는 일은 없어야 하므로, 무슨 일이 생겨도 원본을 그대로 통과시키도록 짰습니다.
세션 이미지 누적 경고
세션에 쌓인 이미지가 기준을 넘으면 사람이 새 말을 입력할 때 한 번 알려 줍니다. 「이 세션을 접을까」는 사람이 판단할 일이라, 판단이 필요한 순간에만 띄웁니다.
7. 뒤에서 도는 반복 작업
턴마다 자동 백업
AI가 답을 끝낼 때마다 지시문·스킬·레슨 저장소를 커밋하고 푸시합니다. 큰 저장소 하나 때문에 턴마다 4초씩 멈춰서 백그라운드로 돌렸고, 겹치지 않게 잠금을 겁니다. 한 번은 이 백업이 접속 키가 든 원고를 그대로 올렸습니다. 그 뒤로 커밋 직전에 스테이징된 파일을 비밀값 검사기로 훑어 걸린 파일만 빼고, 롤백용 사본 파일도 뺍니다. 값은 로그에 찍지 않고 경로만 남깁니다.
위키 발행 한 줄
문서를 「누구만 보게」 위키와 구글 문서로 올리는 일을 명령 하나로 묶었습니다. 열람자 이름으로 계정을 찾고, 등급을 등록하고, 문서에 등급을 넣어 해당 폴더에 놓고, 공유하고, 마지막에 검증까지 하며, 다시 돌려도 결과가 같게 짰습니다.
재사용 빌더
발표용 PPT를 만들 때 도형·화살표·관계도 헬퍼와 최소 글자 크기를 강제하는 빌더를 씁니다. 매번 슬라이드 좌표를 새로 계산하지 않습니다.
8. 이 장치들의 공통 문법
훅 29개를 만들면서 굳어진 규칙이고, 새로 만들 때 이것부터 봅니다.
- 문서 말고 훅으로 막습니다. 같은 실수가 레슨을 남긴 뒤에도 또 나오면, 그 규칙은 문서에서 꺼내 명령이 나가는 자리로 옮깁니다.
- 훅의 고장으로 일이 멈추면 안 됩니다. 대상이 아니거나, 필요한 도구가 없거나, 입력을 못 읽으면 조용히 통과시킵니다.
- 막는 조건은 실제 사고의 모양으로 좁힙니다. 문서 본문에 위험한 단어가 들어 있다는 이유로 그 문서 저장까지 막은 오탐이 실제로 있었습니다.
- 꼭 필요하면 명령에 정해진 주석을 붙여 통과시킬 수 있게 해서, 실수와 의식적인 판단을 구분합니다.
- 남의 서버 보호처럼 정도의 문제는 차단보다 속도 조절이 맞습니다.
- 맥락에 넣는 안내는 줄 수와 횟수를 제한합니다. 상한이 없으면 맥락이 계속 불어납니다.
- 재지 못한 것은 「문제없음」이 아니라 「측정 못 함」으로 냅니다.
- 판정 도구는 처음 만든 계기가 된 실제 실패 사례를 잡아내는지부터 확인하고, 출력은 짧게 냅니다.
- 훅 스크립트는 입력을 표준입력으로 받기 때문에, 셸의 here-document로 감싸면 here-document가 표준입력을 차지해 입력이 사라집니다. 훅은 단독 실행 파일로 둬야 합니다.
9. 만드는 순서
- AI가 틀리면 사람이 지적합니다.
- 그 일을 레슨으로 남기는데, 여기까지는 문서입니다.
- 같은 일이 또 나오면 재발 대장에 증상, 횟수, 처방을 한 줄로 올립니다.
- 처방을 도구로 만듭니다. 판정이 필요하면 판정 스크립트를, 실행 전에 막아야 하면 훅을 만듭니다.
- 도구를 만들었는데도 AI가 안 부르면 그 도구를 훅에 겁니다. 「부르면 쓴다」에서 「안 부르면 막힌다」로 바꿉니다.
대부분은 3단계에서 시작됐고, 처음부터 훅을 만들지는 않습니다. 한 번 틀린 일에 장치를 세우면 장치가 너무 많아지고, 두세 번 틀린 일에는 세울 만한 값이 있습니다. 검증 한 번은 한 턴이 들고, 재발 한 건은 수백 턴이 듭니다.
10. 이 장치들이 못 하는 것
훅은 명령의 모양을 볼 뿐이라 「이 문장이 사실인가」「이 방향이 맞나」 같은 판단은 못 막습니다. 사람이 대화창에 직접 붙여 넣은 이미지도 못 거릅니다. 이미지 대리 읽기는 AI가 파일을 읽을 때만 작동하기 때문입니다.
장치는 계속 늘어나기 때문에 무엇을 왜 만들었는지 각 파일 첫머리에 사고 날짜와 함께 적어 둡니다. 계기가 사라진 장치는 지울 수 있어야 합니다.