AI 코딩 에이전트가 세션 5에서 자기모순을 일으키는 이유 (그리고 세 파일 수정 방법)

고지: 이 기사는 AI 어시스턴트(Claude)를 사용하여 작성되었습니다. #ABotWroteThis

AI 코딩 에이전트는 매번의 세션을 시작할 때 이전 세션에 대해 아무것도 모르는 상태입니다. 바로 이 사실이 '에이전트가 자기모순을 일으킨다'는 불만 대부분을 설명해 줍니다. 모델 자체가 나쁜 것이 아닙니다. 메모리가 없으며, 사용자가 세션 1과 세션 5를 연결하는 유일한 고리입니다.

여기에 그 기억을 머릿속에서 에이전트가 읽을 수 있는 파일로 옮기는 설정 방법을 소개합니다. 이 방법은 작은 파일 세 개와 짧은 프롬프트, 그리고 위험한 작업을 위한 하나의 규칙으로 구성됩니다.

두 가지 실패 사례

컨텍스트 손실(Context loss). 새로운 세션을 열고 기억에 의존하여 프로젝트 배경을 다시 입력합니다. 무심코 제약 조건을 빠뜨려 출력이 잘못되지만, 나중에야 그 사실을 발견하게 됩니다.

재개된 결정(Reopened decisions). 가격 페이지를 상상해 보세요. 충분히 고민한 끝에 세 가지 등급으로 정했습니다. 새로운 세션은 미완성된 페이지를 보고 두 가지 등급을 제안하며, 왜 사용자가 세 개를 선택했는지 알 방법이 없습니다. 결국 다시 논쟁하거나 그 오류(regression)를 받아들여야 합니다.

두 사례 모두 같은 근원에서 발생합니다. 즉, 프로젝트의 배경 지식이 사용자 머릿속이나 이미 닫힌 채팅창에 존재한다는 것입니다.

해결책: 세 개의 레이어

마스터 프롬프트는 시작할 때 붙여넣거나 참조하는 안정적인 배경 지식입니다. 세션 라인은 오늘 할 작업 범위와

좋은 기록이란 놀라움입니다: 생성된 파일, 특이한 도구, 공개 복사본에 관한 규칙 등이 될 수 있습니다. 나쁜 기록은 기본값("깨끗한 코드를 작성하라")을 반복하거나 변경되는 사항("현재 웹훅(webhook) 작업을 진행 중이다")을 붙잡고 있는 경우입니다. 만약 어떤 줄이 에이전트가 어차피 할 일을 단순히 반복하는 것이라면, 삭제하십시오. 하나의 경험칙은 약 40줄 정도를 유지하는 것입니다.

DECISIONS.md: 결정 사항, 이유, 대안, 재검토 시점

모든 실제 결정은 고정된 형식으로 날짜가 기록됩니다:

### D-004: 결제 정보를 역할별로 구성 테이블을 통해 매핑
- Date: 2026-03-11
- Decision: 가격 식별자는 config/prices.js의 티어 역할에 매핑된다.
...

각 필드는 고유한 역할을 수행합니다:

• **Why (이유)**는 미래 세션이 추측하는 대신 엣지 케이스(edge cases)를 판단할 수 있게 합니다.
• **Alternatives considered (고려된 대안)**는 같은 옵션이 반복적으로 제안되는 것을 막아줍니다.
• **Revisit if (재검토 시점)**은 해당 선택을 재개정할 정당성을 부여하는 증거를 명시합니다.

절대 기록을 삭제하지 마십시오. 결정을 되돌릴 때는 그 결정에 우선권을 가지는 새로운 결정을 추가하고 이전 결정을 Superseded by D-NNN으로 표시하십시오. 역사가 핵심입니다.

PROGRESS.md: 아무것도 기억하지 못하는 세션을 위해 작성됨

이 파일은 세 가지 질문에 답합니다: 현재 어디에 와 있는지, 무엇이 막혀 있는지, 다음 단계는 무엇인지.

## 현황판 (Status board)
| Phase | State | Gate |
|---|---|...

이 파일을 유용하게 유지하는 세 가지 습관이 있습니다:

1. **다음 행동(next action)**은 주제가 아니라 구체적인 단일 단계여야 합니다.
2. 단계는 작업이 끝났다고 느껴질 때가 아니라, 게이트(gate)를 통과했을 때만 완료된 것으로 간주합니다.
3. 파일 업데이트는 세션을 종료하기 직전에 항상 수행해야 합니다.

위험한 작업을 위한 게이트: 계획, 승인, 구축

돈, 고객 데이터, 공개 여부 또는 삭제와 관련된 어떤 작업이든 세 단계로 분할하십시오:

1. 계획(Plan). 에이전트는 자신이 무엇을 할지, 어떤 순서로 할지, 무엇에 접근할지, 그리고 무엇이 잘못될 수 있을지를 작성합니다. 아무것도 구축하지 않습니다.
2. 승인(Approve). 사용자가 계획을 읽고 승인하는 내용과 변경 사항을 서면으로 회신합니다.
3. 구축(Build). 에이전트는 승인된 계획에 따라 구축하고 모든 편차를 보고합니다.

오늘: 결제 웹훅 핸들러. 먼저 계획을 세우세요. 수정할 파일 목록, 처리할 이벤트, 그리고 실패 케이스를 나열하세요. 제 승인을 기다리세요.

여기서 한 가지 세부 사항이 중요합니다. 대화에서 주었던 승인이 다음 세션에 존재하지는 않습니다. 이를 PROGRESS.md에 기록하세요("Phase 2 webhook plan: approved 2026-03-12 with one change, 7-day activation expiry"). 만약 적혀 있지 않다면, 주어지지 않은 것으로 간주하세요. 그리고 계획을 승인하는 것이 라이브(live)로 전환하는 것을 승인하는 것은 아닙니다.

열고 닫는 루틴 (The open-and-close routine)

열기(Open): 마스터 프롬프트를 붙여넣은 다음, 세션 라인을 추가하세요(범위(scope), "먼저 PROGRESS.md를 읽으세요", 그리고 게이트가 있다면 그것).

닫기(Close): 에이전트에게 PROGRESS.md를 업데이트하도록 하세요(상태(status), 다음 조치(next action), 블로커(blockers)). 새로운 결정 사항은 DECISIONS.md 항목을 받도록 요청하세요. 무엇을 변경했고 무엇을 검증하지 않았는지 말하도록 요청하세요.

읽는 것은 신뢰할 수 있지만, 기억하는 것은 그렇지 않습니다. 5분 동안의 종료 루틴이 다음번에 컨텍스트를 재구성하는 데 소비될 시간을 절약해 줍니다.

15분 안에 시도해 보세요

• 자신의 명령어와 초심자를 놀라게 할 만한 관례들만 담아 CLAUDE.md를 생성하세요.
• 재논의하기 싫은 지난 세 가지 결정 사항과 그 이유를 적어 DECISIONS.md를 만들세요.
• 상태 보드, 다음 조치 하나, 그리고 블로커 목록을 포함하여 PROGRESS.md를 만드세요.
• 다음 세션에서는 다음과 같이 시작하세요: "먼저 PROGRESS.md와 DECISIONS.md를 읽은 다음, X를 수행하세요."

만약 어떤 결정 사항이 계속해서 돌아온다면, 해당 항목에는 "왜(why)" 또는 "재검토할 경우(revisit if)"가 빠져 있다는 의미입니다. 당신의 에이전트는 무엇을 계속 다시 여는 것일까요?