Claude Code나 Cursor와 같은 AI 에이전트(AI Agent)와 개발하다 보면, 이런 경험을 해본 적이 없으신가요.

어제 그렇게나 논의하고, 설계 방침을 확정하고, 드디어 구현에 들어갔는데——

오늘 다시 새로운 세션을 열었더니, AI는 어제의 일을 아무것도 기억하지 못한다.

나「이 버그를 고쳐줘」
AI「알겠습니다! 우선 현재의 프로젝트 구성을 알려주시겠어요?」
나「……(또 처음부터 설명해야 하나)"

이것이 매일 반복됩니다. 프로젝트가 커질수록 설명에 걸리는 시간도 늘어납니다.

이것은 AI의 콜드 스타트 문제 (Cold Start Problem) 라고 부를 수 있는 현상으로, LLM(Large Language Model)이 세션을 넘나들며 기억을 유지할 수 없는 구조적인 제약에서 발생합니다.

세상의 컨텍스트 관리(Context Management)에 관한 기존 기법들을 바탕으로, 어떤 AI 에이전트(Cursor, Claude Code 등)라도 지금 바로 실천할 수 있도록 3층 구조로 체계화한 것이, 이번에 소개해 드릴 문서 설계 패턴인 「Warm Boot Protocol」입니다.

컴퓨터에는 두 종류의 재부팅이 있습니다.

콜드 부트 (Cold Boot): 전원을 완전히 껐다가 켬. 제로 상태에서 시작.
웜 부트 (Warm Boot): 셧다운하지 않고 재부팅. 이전 상태를 이어받아 빠르게 시작.

AI 세션은 매번 콜드 부트입니다. 어제의 문맥도, 결정한 방침도, 아무것도 이어받지 못합니다.

Warm Boot Protocol은 이것을 웜 부트로 바꿉니다.

새로운 세션을 연 AI가 프로젝트 문서를 읽는 것만으로 즉시 "지금 어떤 상황인가"를 파악하고, 설명 없이 작업을 시작할 수 있는 상태를 만드는——그것을 위한 문서 설계 패턴입니다.

Warm Boot Protocol은 다음과 같은 3층 구조로 문서를 정리합니다.

┌─────────────────────────────────┐
│ Layer 1: 엔트리 포인트 층 │ AI 설정 파일 (CLAUDE.md 등)
│ 세션 시작 시 자동으로 읽힘 │ → ai-context.md와 progress.md를 읽도록 유도
...

Claude Code라면 CLAUDE.md, Cursor라면 .cursorrules와 같이, 많은 AI 도구에는 세션 시작 시 자동으로 읽히는 설정 파일이 있습니다.

여기에 쓰는 것은 최소한의 유도뿐입니다.

## 작업 시작 시 참조처
- 개발 자료 인덱스: `ai-context.md`를 반드시 읽을 것
- 진척 상황·남은 과제: `progress.md`를 읽을 것

이 파일에 모든 것을 담고 싶어지겠지만, 그것은 삼가세요. AI 설정 파일은 글로벌하게 일원 관리하고 싶은 경우가 많으며, 프로젝트 고유의 정보를 적을수록 관리가 힘들어집니다. "다음에 무엇을 읽을 것인가"만을 적는 것이 정답입니다.

"이 프로젝트에서 무슨 일이 생겼을 때, 어떤 자료를 보면 되는가"를 목록화한 파일입니다.

# AI Context
## 기능 A에 관한 자료
| 자료 | 목적 |
...

이 파일의 특징은 변화가 적다는 것입니다. 자료의 위치는 좀처럼 바뀌지 않으므로, 한 번 작성하면 거의 손댈 필요가 없습니다. 태스크가 바뀔 때마다 업데이트가 필요한 progress.md와는 역할이 명확히 구분됩니다.

AI에게 "지금 어떤 상황인가"를 전달하는 파일입니다. 태스크 관리 도구라기보다는, "AI를 위한 브리핑 자료" 라고 이해하는 것이 정확합니다.

# Progress
> 개발 자료 인덱스는 `ai-context.md`를 참조.
## 남은 과제
...

작성해야 할 내용은 3가지입니다.

남은 과제·다음 액션, 설계 방침·판단 보류 중인 사항, 배경이나 경위 메모 ("왜 이렇게 되어 있는가")

반대로, 완료된 태스크의 상세 절차는 남기지 않습니다. 코드나 git log에 남아 있으므로, progress.md에 계속 쓰다 보면 비대해질 뿐입니다.

각 기능의 README나 사양서입니다. 필요할 때만 참조합니다.

여기서 중요한 것은 **"AI 친화적(AI-friendly)으로 작성하는 것"**입니다. 인간을 위한 자료와 AI를 위한 자료는 작성 방식이 다릅니다.

AI는 모호한 지시를 받으면 「좋은 느낌」으로 해석하려고 시도하지만, 그 해석이 의도와 어긋날 수 있습니다. 이유를 명시하면 (Explicitly stating the reason) AI는 절차를 준수하기가 더 쉬워집니다.

변화 속도가 다른 것들을 같은 파일에 작성하면, 빈번한 변경이 일어날 때마다 안정적인 정보까지 건드리게 됩니다. 자주 다시 쓰는 progress.md와 좀처럼 바뀌지 않는 ai-context.md를 분리하는 이유가 바로 이것입니다.

AI가 자료를 추적하는 깊이는 얕을수록 좋습니다.

좋은 예: CLAUDE.md → ai-context.md → 상세 자료 (2홉 (Hop))
나쁜 예: CLAUDE.md → A.md → B.md → C.md → 상세 자료 (4홉 (Hop))

간접 참조가 깊어질수록, 중간에 읽고 지나칠(skip) 리스크가 증가합니다.

완료된 태스크의 설계 메모나 절차를 progress.md에 계속 써 내려가면 파일이 비대해져서 「지금 무엇이 남아있는지」 파악하기 어려워집니다. 완료된 내용은 코드, 커밋 메시지(Commit message), 상세 자료에 남으므로, progress.md에서는 삭제하여 「현재 위치」를 유지하십시오.

Linear나 GitHub Issues와 같은 티켓(Ticket)을 MCP를 통해 AI와 연동하는 사례도 늘고 있습니다. 이 경우, 태스크 관리는 외부 도구에 맡길 수 있습니다.

외부 도구를 사용하는 경우에도 progress.md가 없어지는 것은 아닙니다. 「티켓을 발행할 정도는 아닌 문맥 정보(Context information)」를 두는 장소로서 계속 기능합니다.

# Progress
> 태스크 관리는 Linear를 참조 (MCP 연동 완료).
## 방침 · 보류 판단
...

팀이 커질수록 progress.md는 「태스크 관리 파일」에서 「AI를 위한 문맥 브리핑(Context briefing) 자료」라는 본래의 역할로 순화되어 갑니다.

# CLAUDE.md (흔히 하는 실수 예시)
- 기능 A의 자료는 docs/a.md
- 기능 B의 자료는 docs/b.md
...

AI 설정 파일을 글로벌하게 일원 관리하고 있는 경우, 프로젝트 고유의 정보를 여기에 쓸 때마다 관리가 힘들어집니다.

성취감 때문에 기록해 두고 싶겠지만, 완료된 내용은 삭제하는 것이 정답입니다. 「지금 어떤 상황인가」만을 남기십시오.

## 남은 과제
- [ ] 기능 A를 구현하기 ← 어디를 봐야 할지 모르겠음

태스크만 적혀 있으면 AI는 어떤 자료를 읽어야 할지 모릅니다. 반드시 「구현 절차는 docs/feature-a/README.md 참조」와 같이 유도를 적어주어야 합니다.

새로운 프로젝트에 Warm Boot Protocol을 도입할 때의 체크리스트입니다.

• AI 설정 파일에 ai-context.md와 progress.md로의 유도를 적었다
• ai-context.md를 리포지토리 루트(Repository root)에 생성했다
• progress.md를 리포지토리 루트에 생성했다
• progress.md의 서두에 ai-context.md로의 유도를 적었다
• 각 태스크에 상세 자료로의 링크를 적었다
• 상세 자료에 「어떤 순서로 할 것인가」와 「왜 하는가」를 적었다
• AI 설정 파일과 리포지토리 관리 파일을 분리했다

Warm Boot Protocol은 파일을 3종류 준비하는 것뿐입니다.

이것만으로도, 새로운 세션(Session)을 연 AI가 "현재 상황을 알려줘"라고 말하지 않고 바로 작업을 시작할 수 있게 됩니다.

매일 아침 기억을 잃은 동료와 일하는 느낌에서, 인수인계가 완벽한 동료와 일하는 느낌으로.

꼭 한번 시도해 보세요.