【Claude Code 활용】 PROGRESS.md 주도 개발로 세션을 넘나들며 개발하기

세션을 넘나드는 문제

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)

기사	제목
B1	Claude Code란 무엇인가·도입과 초기 설정
...

Discussion