AI 코딩 에이전트가 같은 실수를 반복하지 않게 하는 법 — 프로젝트 메모 파일 운영기

코딩 에이전트는 똑똑하지만 어제 일을 기억하지 못한다. 새 대화를 열 때마다 같은 함정에 다시 빠지고, 같은 구조를 다시 탐색한다. 몇 달 동안 여러 프로젝트를 에이전트와 함께 굴리면서 가장 효과가 컸던 것은 모델을 바꾸는 일이 아니라 프로젝트 메모 파일을 가꾸는 일이었다.

메모 파일이란

요즘 코딩 에이전트는 대부분 저장소 안의 지침 파일을 대화 시작 때 읽는다. 이름은 도구마다 다르지만 역할은 같다. "이 프로젝트에서 일하려면 알아야 할 것"을 적어 두는 곳이다. 여기에 무엇을 어떻게 적느냐에 따라 에이전트의 쓸모가 크게 달라졌다.

효과가 있었던 규칙

• 코드를 보면 알 수 있는 것은 적지 않는다. 폴더 구조나 함수 목록은 에이전트가 직접 읽으면 된다. 적어야 하는 것은 코드에 없는 것, 곧 "왜 이렇게 했는가"와 "이렇게 하면 안 된다"이다.
• 함정은 겪은 즉시 한 줄로. 문제를 해결한 직후 그 자리에서 에이전트에게 "방금 알게 된 것을 메모에 추가해"라고 시킨다. 눈에 띄는 표시를 붙여 두면 나중에 훑어보기 쉽다. 형식은 "증상 → 원인 → 이렇게 한다".
• 확인한 사실과 추측을 구분한다. "(실측)", "(추정)" 같은 꼬리표를 단다. 추측이 꼬리표 없이 들어가면 다음 대화의 에이전트는 그것을 사실로 믿고 그 위에 일을 쌓는다. 실제로 틀린 추측 한 줄 때문에 서비스 중단을 예상하지 못한 적이 있다.
• 사람의 결정을 적는다. "이 값은 내가 정한다, 추천하지 말 것", "발행은 사람이 직접" 같은 결정은 코드에서 읽어 낼 수 없다. 적어 두지 않으면 에이전트는 매번 친절하게 같은 제안을 다시 한다.
• 파일을 쪼갠다. 메모가 길어지면 모든 대화가 그 전부를 읽느라 느려지고, 관련 없는 내용이 섞여 판단이 흐려진다. 맨 위 파일에는 어디에나 해당하는 규칙만 두고, 나머지는 영역별·프로젝트별 파일로 내린다. 소유 경계(개인 것, 회사 것, 고객 것)로 나누니 "이 정보를 저쪽 산출물에 쓰면 안 된다"는 규칙도 자연스럽게 지켜졌다.
• "다시 찾아보지 말 것"을 적는다. 배포 절차나 서버 접속 방법처럼 반복되는 일은 메모가 정본이라고 못박는다. 그러지 않으면 에이전트는 성실하게 매번 처음부터 조사한다.

적지 말아야 할 것

• 비밀 값. 키, 토큰, 비밀번호는 절대 넣지 않는다. 메모 파일은 대화마다 모델에 통째로 전달되고, 저장소에 커밋될 수도 있다. "어느 파일에 있다"까지만 적는다.
• 끝난 일의 기록. "몇 월 며칠에 무엇을 고쳤다"는 버전 관리 기록에 있다. 메모에는 그 일에서 배운 것만 남긴다.
• 지금만 맞는 상태. "현재 작업 중" 같은 문장은 금방 거짓이 된다.

정리

에이전트와 일하는 것은 매일 아침 기억을 잃는 유능한 동료와 일하는 것과 비슷하다. 그 동료가 출근해서 가장 먼저 읽는 쪽지를 잘 써 두는 것이 프롬프트를 다듬는 것보다 훨씬 오래 남는 투자였다.