세션을 넘나드는 문제

Claude Code는 세션을 넘나들며 기억을 유지하지 않습니다. 새로운 세션을 시작하면, 지난번에 어디까지 진행했는지, 어떤 문제가 있었는지를 모두 잊어버린 상태에서 시작합니다.

이 문제를 해결하기 위해 고안한 것이 PROGRESS.md 주도 개발입니다.

PROGRESS.md의 설계

agent01의 PROGRESS.md는 다음과 같은 3가지 섹션으로 구성되어 있습니다.

## 현재 위치
**Phase D: 통합 ✅ 완료**
**모든 Step의 구현이 완료되었습니다.**
...

이 구조의 포인트는 3가지입니다.

• 현재 위치: 지금 어디에 있는지 한눈에 파악할 수 있음
• 전체 스텝 목록: 체크박스로 진척도를 가시화
• 완료된 Step 기록: 깨달은 점, 막혔던 부분, 인수인계 사항을 상세히 남김

실제 운용

agent01의 13 Step 개발을 통해 확립한 운용 사이클은 다음과 같습니다.

세션 시작 시:

「PROGRESS.md와 AGENT_SPEC.md를 읽어주세요.
그 후, Step ○○의 구현 지시서에 따라 구현을 진행해 주세요.」

이 한마디로 Claude Code는 프로젝트의 문맥(Context)을 파악하고, 이전의 인수인계 사항을 고려한 상태에서 작업을 시작합니다.

세션 종료 시:

구현 완료 후에 PROGRESS.md를 업데이트한 뒤 커밋(Commit)합니다.

「Step ○○가 완료되었습니다. PROGRESS.md를 업데이트한 후 커밋해 주세요.」

PROGRESS.md의 업데이트 내용은 다음 4가지 항목입니다.

• 해당 Step의 체크박스를 [x]로 변경
• 「현재 위치」를 다음 Step으로 업데이트
• 「완료된 Step」에 기록 추가
• 「인수인계 사항」에 환경 정보 및 깨달은 점을 기록

CLAUDE.md와의 조합

CLAUDE.md에는 PROGRESS.md의 업데이트 규칙을 명시했습니다.

## PROGRESS.md 업데이트 규칙
Step이 완료되면 다음을 업데이트한다.
1. 해당 Step의 체크박스를 `[x]`로 변경
...

이 규칙을 CLAUDE.md에 적어둠으로써, 「Step이 완료되면 PROGRESS.md를 업데이트한 후 커밋한다」는 흐름이 자동화되었습니다. 명시적인 지시가 없어도 Claude Code가 규칙을 준수하게 됩니다.

깨달은 점

PROGRESS.md의 「깨달은 점·막혔던 부분」이 기사의 소재가 되었다: 13 Step을 통해 기록한 깨달은 점(cp932 인코딩 문제, LLM 모델별 tool_use 대응 상황 등)이 그대로 Series A의 기사 콘텐츠가 되었습니다. 개발 로그와 기사 소재를 동시에 축적할 수 있는 설계입니다.

커밋 히스토리보다 「왜 그렇게 했는가」가 더 자세히 남는다: git log로는 「무엇을 변경했는가」는 알 수 있지만 「왜 그렇게 했는가」는 남지 않습니다. PROGRESS.md의 인수인계 사항에는 결정 배경도 기록할 수 있기 때문에, 나중에 다시 검토할 때 의사결정 경위를 추적할 수 있습니다.

새로운 개발자(다음 세션의 Claude Code)를 위한 인수인계로서 기능한다: PROGRESS.md는 「다음 세션의 Claude Code」를 위한 온보딩(Onboarding) 문서로서 기능합니다. 기존 팀에 새로운 멤버가 참여하는 것과 동일한 문맥 공유가 AI 에이전트와의 협업에서도 유효했습니다.

요약

PROGRESS.md 주도 개발은 Claude Code의 세션 간 기억 문제를 심플한 텍스트 파일로 해결하는 수법입니다. 「세션 시작 시 읽기·종료 시 업데이트하기」라는 사이클을 CLAUDE.md에 정의함으로써, 13 Step의 개발을 분산된 세션에서 착실히 진행할 수 있었습니다.

다음 회차

B8에서는 Claude Code로 Zenn 기사를 생성한 플로우 전체를 소개합니다. 지금 바로 읽고 계신 이 기사도 그 플로우로 생성되었습니다.

시리즈 링크 (Series B)

Discussion