단편 레슨 · 내 파일을 다루는 AI 도구 만들기 · 레슨 05 / 5
만든 도구를 계속 쓰이게 만들기
내 파일을 다루는 AI 도구 만들기 5강 — 한 달 뒤에도 돌아가는 도구로 만들어요. 사용법 문서, 고장 알림, 점검 루틴, 그리고 남에게 넘기기까지.
지난 편에서 나만의 프로젝트를 배포했어요. 지금은 잘 돌아가죠. 문제는 3주 뒤예요.
3주 뒤의 나는 이 폴더를 열고 이렇게 생각해요. "이거 어떻게 돌리는 거였지?" 파일 이름은 낯설고, 어떤 순서로 실행하는지 기억나지 않고, 지난주에 조용히 실패했다는 사실도 몰라요. 도구는 멀쩡히 살아 있는데 아무도 안 쓰는 상태가 돼요.
이건 실력 문제가 아니에요. 만든 사람만 아는 지식이 머릿속에만 있어서 생기는 일이에요. 오늘은 그 지식을 폴더 안으로 옮겨요.
오늘 접시에 올릴 것
한 달 뒤에 열어도 3분 안에 다시 돌릴 수 있는 도구예요. 사용법이 적혀 있고, 실패하면 조용히 넘어가지 않고, 정해진 날에 스스로 점검받아요. 그리고 옆자리 동료에게 폴더째 넘겨도 그 사람이 혼자 돌릴 수 있어요.
재료
- 지난 편에서 만든 내 프로젝트 폴더
- 30~40분
- 3주 뒤의 나를 떠올리는 상상력 조금
조리
1. 3주 뒤의 나에게 쪽지 쓰기
가장 먼저 할 일은 README예요. 개발자들이 쓰는 관례지만 이유는 단순해요. 폴더를 열었을 때 제일 먼저 눈에 띄는 설명서거든요.
직접 쓰지 말고 시키세요. 에이전트는 이미 이 폴더의 모든 파일을 읽을 수 있어요.
이 폴더의 파일을 전부 읽고 README.md를 만들어 줘.
읽는 사람은 3주 뒤의 나야. 코딩은 모르고, 이걸 왜 만들었는지도 가물가물해.
다음 순서로, 짧게 써 줘:
1. 이 도구가 뭘 해 주는지 한 문장
2. 돌리는 방법 — 복사해서 그대로 붙여넣을 수 있는 명령 한 줄
3. 어떤 파일을 어디에 넣어야 하는지
4. 자주 나는 오류 두세 개와 각각의 해결법
5. 건드리면 안 되는 파일
전문 용어는 쓰지 말고, 실제로 이 폴더에 있는 파일 이름만 언급해 줘.
추측해서 지어내지 말고, 확실하지 않으면 "확인 필요"라고 표시해.
마지막 문장이 중요해요. 이걸 빼면 에이전트는 그럴듯한 설명을 지어내요. 있지도 않은 파일 이름이 README에 박히면 3주 뒤의 나는 더 헤매요.
받은 README를 그대로 믿지 말고 한 번 읽어보세요. 2번의 명령을 실제로 복사해서 돌려봐요. 안 돌아가면 그 자리에서 고쳐 달라고 하면 돼요.
2. 조용한 실패를 시끄럽게 만들기
자동화가 위험해지는 순간은 고장 났을 때가 아니에요. 고장 났는데 내가 모를 때예요.
매일 아침 파일을 정리하던 도구가 화요일부터 멈췄다고 해봐요. 화면에는 아무 일도 안 일어나요. 나는 정리되고 있다고 믿고, 금요일에야 폴더가 엉망인 걸 발견해요.
그래서 성공했을 때가 아니라 실패했을 때 흔적을 남기게 만들어요.
이 도구가 실행될 때마다 log.txt에 한 줄씩 기록하게 고쳐 줘.
- 언제 실행됐는지, 성공인지 실패인지, 몇 개를 처리했는지
- 실패하면 왜 실패했는지도 함께
- 성공한 줄은 짧게, 실패한 줄은 앞에 [실패] 를 붙여서 눈에 띄게
그리고 log.txt가 너무 길어지지 않게, 최근 100줄만 남기고 오래된 건 지워 줘.
이제 log.txt만 열면 도구가 살아 있는지 알 수 있어요. [실패]를 검색하면 끝이에요.
여기서 한 걸음 더 갈 수도 있어요. 실패가 두 번 연속 나면 나에게 메일이나 알림을 보내게요. 다만 알림은 처음부터 만들지 마세요. 로그부터 두고, 실제로 실패를 겪은 다음에 필요하면 붙이는 편이 좋아요. 안 오는 알림을 미리 만들면 그것도 관리 대상이 되거든요.
3. 스스로 점검받게 만들기
도구는 세상이 안 변할 거라고 가정하고 만들어져요. 그런데 파일 형식이 바뀌고, 폴더 이름이 바뀌고, 쓰던 서비스가 응답을 다르게 줘요.
한 달에 한 번, 도구가 자기 점검을 하게 만들어요. 방법은 간단해요. 정상일 때의 모습을 적어 두고, 그것과 비교하게 하는 거예요.
CHECKUP.md 파일을 만들어 줘. 이 도구가 "정상"일 때의 조건을 체크리스트로 적어 줘.
예: 입력 폴더에 CSV가 있는가 / 출력 파일이 오늘 날짜로 생겼는가 /
log.txt 마지막 줄이 성공인가
그리고 이 체크리스트를 순서대로 확인해서 결과를 알려주는 방법도
README에 한 줄로 적어 줘. 내가 매달 1일에 이걸 한 번 돌릴 거야.
매달 1일에 에이전트를 열고 "CHECKUP.md 대로 점검해 줘"라고 한 마디만 하면 돼요. 30초면 끝나고, 문제가 있으면 그 자리에서 고쳐 달라고 하면 돼요.
4. 넘겨줄 수 있는 상태로 만들기
마지막 관문이에요. 내 도구가 진짜 도구인지, 아니면 나만 쓸 수 있는 마법인지 가르는 시험이요.
내 컴퓨터가 아닌 곳에서 돌아가나요?
확인하는 방법이 있어요. 에이전트에게 이렇게 물어보세요.
이 폴더를 통째로 다른 사람 컴퓨터에 복사한다고 해보자.
그 사람이 이걸 돌리려면 뭐가 더 필요할까?
내 컴퓨터에만 있는 것에 의존하는 부분을 전부 찾아 줘.
예: 내 계정 정보, 내 컴퓨터에만 있는 폴더 경로, 미리 깔아둔 프로그램.
찾은 것마다 어떻게 고치면 되는지도 알려 줘.
비밀번호나 API 키가 파일 안에 그대로 적혀 있으면 특히 알려 줘 — 중요해.
마지막 줄을 꼭 넣으세요. 급하게 만들다 보면 비밀번호나 키를 코드에 그냥 적어두게 돼요. 그 상태로 폴더를 남에게 주거나 인터넷에 올리면 그대로 새어 나가요.
에이전트가 찾아낸 것들을 고치고 나면, 이제 이 폴더는 선물할 수 있는 물건이 돼요.
태워먹었을 때
README를 봤는데 명령이 안 돌아가요. 에이전트가 폴더를 읽고 쓴 게 아니라 일반적인 사용법을 지어낸 경우예요. "README의 2번 명령을 실제로 이 폴더에서 실행해보고, 안 되면 실제로 되는 명령으로 고쳐 줘"라고 시키세요.
log.txt가 안 생겨요. 도구가 실행되는 위치와 로그를 쓰는 위치가 다를 때 자주 생겨요. "log.txt를 이 스크립트 파일과 같은 폴더에 만들어 줘"라고 명시하면 해결돼요.
점검했더니 전부 실패로 나와요. 체크리스트가 너무 빡빡하게 쓰였을 수 있어요. CHECKUP.md를 열어서 조건을 직접 읽어보세요. "오늘 날짜로 파일이 생겼는가" 같은 조건은 주말엔 실패하는 게 정상이에요. 조건을 현실에 맞게 고치면 돼요.
비밀번호가 파일에 적혀 있다고 나왔어요. 좋아요, 찾아냈으면 이긴 거예요. 에이전트에게 "이 값을 환경변수로 빼고, 원래 값이 있던 자리는 안내 문구로 바꿔 줘"라고 시키세요. 그리고 그 비밀번호는 새로 발급받으세요. 한 번 파일에 적혔던 값은 이미 안전하지 않아요.
Order up
나가기 전에 하나씩 확인해요:
- 폴더에 README.md가 있고, 거기 적힌 명령이 실제로 돌아가요
- 도구를 한 번 돌리면 log.txt에 줄이 하나 늘어요
- 일부러 망가뜨려 봤을 때
[실패]줄이 남아요 - CHECKUP.md가 있고, 매달 언제 점검할지 정했어요
- 내 컴퓨터에만 있는 것들을 찾아서 고쳤어요
- 비밀번호나 키가 파일에 그대로 적혀 있지 않아요
여섯 개가 다 체크됐다면, 만든 건 스크립트가 아니라 도구예요. 3주 뒤의 나도, 옆자리 동료도 쓸 수 있는 물건이요.
여기까지가 이 강의의 마지막 편이에요. 첫 페이지를 배포했고, 내 데이터를 다루는 도구를 만들었고, 그 도구를 오래 쓰이게 만들었어요.
다음은 사람이 쓰는 앱이에요. 나 혼자 쓰는 도구가 아니라, 남이 들어와서 입력하고 그게 저장되는 것. 3강 · 사람들이 쓰는 웹앱 만들기에서 이어가요.