조금 규모가 큰 개발을 하던 때의 일입니다. 세션을 전환하지 않고, 하나의 채팅 세션 그대로 며칠 동안 개발을 강행해 버렸습니다.

그 결과, 채팅 이력이 비대해져 빈번하게 Compact (컨텍스트 자동 압축)가 발생했습니다.

불과 몇 시간 전에 대화로 결정했을 터인 「인증 API의 사양 변경」이나 「에러 핸들링 (Error Handling)의 공통 설계」가 AI의 단기 기억에서 차례차례 사라져 갔습니다.

기억을 잃은 AI 에이전트는 이미 수정했을 터인 오래된 버그를 코드에 다시 혼입시키거나, 의도하지 않은 리팩터링 (Refactoring)으로 정상적으로 동작하던 다른 기능을 파괴하기 시작했고, 결국 반나절 치의 작업이 되돌아오는(rework) 뼈아픈 경험을 했습니다.

Claude Code, Codex, OpenClaw 등, 자율적으로 파일을 읽고 쓰고 명령을 실행할 수 있는 「AI 에이전트」의 등장으로 우리의 개발 스타일은 극적으로 변화하고 있습니다.

처음에는 「매우 유능한 주니어 엔지니어」가 팀에 합류한 것처럼 척척 개발이 진행됩니다. 하지만 프로젝트가 중~대규모가 되고 코드베이스 (Codebase)가 커짐에 따라, 많은 사람이 다음과 같은 「에이전트의 열화」에 직면합니다.

기억 상실: 「방금 설명한 사양」이나 「어제 결정한 구현 방침」을 깨끗이 잊어버림.

설계의 드리프트 (Drift): 멋대로 기존 아키텍처 (Architecture)를 무시한 리팩터링을 시작하여 코드를 망가뜨림.

사고 정지: 테스트를 통과시키는 방법이나 빌드 (Build) 방법을 알 수 없게 되어, 에러와 수정의 무한 루프에 빠짐.

왜 이런 일이 일어날까요?

이유는 간단합니다. AI 에이전트와의 채팅 로그 (대화 컨텍스트)에만 의존하여 개발을 진행하고 있기 때문입니다.

본 기사에서는 이 문제를 근본적으로 해결하기 위한 기본 사상인 「대화는 작업 영역, 리포지토리는 기억 영역」과, 이를 구체화한 9개의 페이즈 (Phase)로 구성된 「AI 에이전트용 프로젝트 개발 라이프사이클 (Lifecycle)」을 해설합니다.

AI 에이전트 개발을 성공시키기 위한 골든 룰 (Golden Rule)은 다음 한 문장으로 집약됩니다.

대화는 작업 영역 (RAM), 리포지토리는 기억 영역 (SSD)

PC로 비유하자면, AI와의 채팅 스레드 (채팅 이력)는 일시적인 「RAM」입니다. PC의 전원을 끄면 RAM이 초기화되는 것과 마찬가지로, AI 에이전트와의 상호작용도 다음과 같은 타이밍에 간단히 초기화·리셋 (Clear)됩니다.

• 새로운 채팅 세션을 시작했을 때
• 토큰 (Token) 상한에 도달하여 컨텍스트가 자동으로 압축 (Compact)되었을 때
• 에이전트의 프로세스 (Process)를 재시작했을 때

이와 대조적으로, 프로젝트의 리포지토리 (Repository, Git으로 관리되는 코드나 Markdown 문서)는 「SSD」입니다.

AI 에이전트에게 「계속 기억해 주었으면 하는 것」이 있다면, 채팅으로 지시하는 것이 아니라, 문서로서 리포지토리에 저장하고 AI 스스로가 그것을 읽고 쓰게 할 필요가 있습니다.

리포지토리를 「유일한 진실의 원천 (Single Source of Truth)」으로 삼고, AI 에이전트 스스로가 그 문서의 유지보수를 담당하게 한다. 이것이야말로 중대규모 프로젝트를 파탄 내지 않고 계속 개발해 나갈 수 있는 열쇠입니다.

문서 주도 (Document-driven)로 AI와 협업 개발하기 위한 라이프사이클은 다음과 같은 9개의 페이즈로 구성됩니다.

각 페이즈에서 무엇을 실시하고, 어떤 문서를 정비해야 하는지를 해설합니다.

시스템의 목적과 요구사항을 명확히 합니다. AI 에이전트는 갑자기 코드를 쓰고 싶어 하지만, 그것을 제지하고 「무엇을 만들어야 하는가」를 합의하는 페이즈입니다.

실시 내용: 시스템 목적 정리, 사용자 요구사항 정리, MVP 정의, 기술 선정, 개발 로드맵 (Roadmap) 책정.

성과물: docs/prd.md (Product Requirement Document)

docs/prd.md의 기재 항목 예시

프로젝트 개요: 왜 이 시스템을 만드는가

대상 사용자: 누가 어떤 상황에서 사용하는가

기능 요구사항 (MVP): 필수 기능 목록

비기능 요구사항: 퍼포먼스 (Performance), 보안 (Security), 확장성 (Scalability)

제약 사항: 사용하는 언어/프레임워크 (Framework), 외부 API 제약

개발 마일스톤 (Milestone): 출시까지의 단계적 스텝

요구사항을 시스템 구성이나 데이터 구조 (Data Structure)로 구체화합니다. AI가 「미아」가 되지 않고, 일관된 아키텍처로 코드를 작성하기 위한 지도가 됩니다.

실시 내용: 시스템 구성도 정리, API 설계, 디렉터리 구성 결정, 데이터 모델·DB 스키마 설계. -
성과물: docs/architecture.md (시스템 전체상, 컴포넌트 구성), spec.md (상세 사양), api.md (API 엔드포인트 정의, 스키마), README.md (프로젝트 실행 방법, 개요)`

AI 에이전트가 프로젝트에 참여할 때의 「헌법」을 정의합니다. 많은 AI 에이전트(특히 Claude Code 등)는 리포지토리 루트 직하의 CLAUDE.md를 기동 시 자동으로 읽어들입니다.

목적: AI의 행동(에이전트로서의 성격) 통일, 코딩 규약 공유, 빌드 및 테스트 명령어 정의. -
주의: 일시적인 TODO나 작업 진행 상황은 여기에 적지 않습니다 (정적인 규칙만 기재).

# 프로젝트 개발 가이드
## 개요
[프로젝트에 대한 짧은 설명. 예: AI 에이전트용 컨텍스트 관리 도구]
...

개발 계획을 태스크(Task) 레벨로 관리하며, AI와 인간의 공통된 「간판(Kanban)」으로 삼습니다.

성과물: TODO.md

관리 방법: Markdown의 체크박스를 사용하여 상황(미착수 [ ], 진행 중 [/], 완료 [x])을 명시합니다.

# 개발 태스크 목록
## 🚀 MVP (최소 기능 제품)
- [x] 프로젝트 초기화 · Prisma 설정
...

여기서부터 비로소 코드 구현에 들어갑니다.

원칙: 「1 세션 = 1 기능」을 철저히 지킵니다. 한 번에 너무 많은 기능을 구현하게 하려고 하면, AI의 컨텍스트가 파탄 나고 버그의 온상이 됩니다. -
프로세스:

• 태스크를 하나 선택한다 (TODO.md를 [/]로 변경)

• 구현 코드를 작성한다

• 테스트를 실행하여 통과하는지 확인한다

• 리뷰 (인간에 의한 확인)

• Git Commit (의미 있는 최소 단위로 커밋)

• 태스크를 하나 선택한다 (

설계 변경이 발생한 경우: 채팅으로 "역시 이렇게 하자"라고 전달하는 대신, 후술할 ADR (Architecture Decision Record)을 작성·갱신합니다.

개발을 중단할 때, 혹은 하나의 정리된 작업을 마칠 때, 반드시 현재 상황을 문서로 기록합니다.

성과물: sessions/current.md

기록 내용: 무엇을 수행했는지, 무엇이 남아 있는지, 무엇이 과제인지.

세션을 종료하고 스레드를 전환하기 전에, AI에게 이 파일을 업데이트하게 하는 것이야말로 컨텍스트 압축 (Compact)에 의한 정보 손실을 방지하는 최대의 방어책이 됩니다.

# 세션 요약 (2026-06-27 16:30)
## 🎯 완료된 사항 (Done)
- 인증 기능 기본 구현 (`src/auth/` 하위의 컨트롤러와 서비스 생성)
...

개발을 재개할 때(또는 AI 에이전트를 다시 실행할 때)는, AI에게 다음 순서로 파일을 읽게 함으로써 이전의 컨텍스트를 완전히 복원시킵니다.

CLAUDE.md (프로젝트의 기본 규칙)

TODO.md (전체 진행 상황)

sessions/current.md (지난번에 어디까지 했는지, 다음 태스크는 무엇인지)

• 필요에 따라 docs/architecture.md나 docs/adr/

💡

AI에게 주는 지시 예시:

"개발을 재개합니다. 먼저 CLAUDE.md, TODO.md, sessions/current.md를 읽고 현재 상황을 이해한 뒤, 다음 액션에 대해 제안해 주세요."

개발 중에 발생한 설계 방침의 변경이나 기술 선정의 의사 결정은 docs/adr/ 디렉터리 하위에 「ADR (Architecture Decision Record)」로서 기록합니다.

명명 규칙: docs/adr/0001-use-prisma.md와 같이 일련번호를 부여합니다. -
장점: AI가 "왜 이러한 코드가 작성되었는지"에 대한 배경(컨텍스트)을 이해하게 하여, 동일한 잘못된 설계 변경을 제안하는 것을 방지합니다.

ADR 기재 항목 예시

상태 (Status): 제안 중 / 승인됨 / 기각됨 -
배경 (Background): 해결하고자 하는 과제나 당시의 상황 -
채택안 (Proposed Solution): 결정된 사항 -
기각안 (Rejected Solution): 검토했으나 채택하지 않은 대안과 그 이유 -
영향 범위 (Impact): 이 결정으로 인해 무엇이 변하는가

프로젝트가 몇 주, 몇 달간 지속되더라도 이 라이프사이클 (Lifecycle) 루프를 계속해서 돌립니다. "구현이 끝나면 문서를 업데이트한다", "커밋하기 전에 세션 요약 (Session Summary)을 업데이트한다"라는 습관을 AI 에이전트 스스로 철저히 지키게 합니다.

AI가 "알겠습니다!"라고 말하더라도, 그것은 현재 스레드 (Thread) 내에서만 유효한 일시적인 이해입니다. 내일이면 잊어버린다고 생각하십시오. 필요한 정보는 반드시 "코드" 또는 "문서"로서 리포지토리 (Repository)에 저장합니다.

AI가 참조하는 정보는 모두 리포지토리 내에서 완결되는 상태를 목표로 합니다. 외부의 Notion이나 Slack 대화 내용을 전제로 하면, AI는 이를 참조할 수 없어 불일치가 발생합니다.

인간이 모든 문서를 최신 상태로 유지하는 것은 매우 힘든 일입니다. AI 에이전트에게 다음과 같은 규칙을 부여하십시오.

• "설계를 변경하는 코드를 작성한다면, 먼저 ADR을 작성할 것"
• "태스크 (Task)를 완료하면, 자율적으로 TODO.md를 업데이트할 것"
• "작업을 마치기 전에 sessions/current.md를 업데이트할 것"

AI를 "말하는 대로 코드를 쓰는 노동자"가 아니라, "프로젝트의 문서와 코드의 일관성을 스스로 지키는 자율적인 동료"로 대함으로써, AI 에이전트 개발은 비로소 그 진가를 발휘합니다.

AI 에이전트를 활용한 개발은 기존의 "코드를 작성하는 작업의 효율화"에서 "설계와 기억 관리의 효율화"로 전환되고 있습니다.

"대화는 작업 영역, 리포지토리는 기억 영역"이라는 원칙을 철저히 지키고, 문서 주도 개발 라이프사이클을 운영함으로써, 중~대규모 프로젝트에서도 AI의 힘을 100% 끌어내어 안전하고 빠르게 개발을 진행할 수 있게 됩니다. 꼭 여러분의 프로젝트에도 도입해 보시기 바랍니다.