Claude Code에서 「또 설명부터인가요」를 없애기

필자는 J-Quants API 데이터 취득 배치, Discord bot, Unity 검증용 툴 등 여러 프로젝트를 Claude Code와 병행하여 진행하고 있습니다.

그러다 보니 다음과 같은 고민이 생깁니다.

• 지난번에 어디까지 구현했는지 기억나지 않는다
• 다음에 무엇을 할 예정이었는지 잊어버렸다
• 새로운 세션마다 똑같은 배경 설명을 입력해야 한다

매번 세션 도입부에서 경위를 다시 설명하는 것은 은근히 시간을 뺏는 일입니다.

이 기사에서는 세션 종료 시에 작업 이력을 자동으로 기록하고, 다음 세션 시작 시에 자동으로 읽어들이게 하는 메커니즘을 Python으로 만듭니다.

전체적인 메커니즘은 3단계

하는 일은 간단합니다.

• 세션 종료 시 로그(JSONL 형식의 트랜스크립트)에서 최근의 대화 내용을 추출한다
• 요약을 CLAUDE.md의 「최근 작업 로그」 섹션에 다시 쓴다
• 다음 세션 시작 시, Claude Code가 CLAUDE.md를 자동으로 읽기 때문에 다시 설명할 필요가 없어진다

특별한 DB나 서버는 필요하지 않습니다.

로컬 파일 조작만으로 완결된다는 점이 포인트입니다.

단계 1: 세션 종료 시 요약을 자동 생성하기

Claude Code에는 훅 (Hook)이라는 메커니즘이 있어, 세션 이벤트에 맞춰 임의의 명령어를 실행할 수 있습니다.

먼저 훅에서 호출될 Python 스크립트를 준비합니다.

#!/usr/bin/env python3
"""stop_hook_record_memory.py
Claude Code의 Stop 훅에서 호출하여, 최근의 대화 내용을 요약하여 파일에 남긴다.
...

트랜스크립트는 1행 1JSON 형태의 로그 파일이므로, 끝에서부터 거슬러 올라가며 user / assistant 텍스트만 골라내고 있습니다.

장문은 그대로 붙여넣으면 비대해지기 때문에, 1건당 200자로 압축하고 있습니다.

다음은 추출한 요약을 CLAUDE.md와 이력 파일 양쪽에 쓰는 처리입니다.

def write_memory(project_dir: Path, summary_lines: list) -> None:
memory_dir = project_dir / ".claude" / "memory"
memory_dir.mkdir(parents=True, exist_ok=True)
...

history.md에는 전체 이력을 추가하고, CLAUDE.md 쪽은 항상 최신 1건만 유지하도록 설계했습니다.

이렇게 함으로써 다음에 읽어들일 정보량을 일정하게 유지하면서, 과거의 경위를 history.md를 통해 거슬러 올라가며 확인할 수 있습니다.

단계 2: 훅의 입력을 받는 엔트리 포인트 (Entry Point)

훅은 JSON을 표준 입력(Standard Input)을 통해 받는 형태입니다.

def main() -> None:
raw = sys.stdin.read()
try:
...

에러 발생 시에는 sys.exit(0)으로 정상 종료시켜, 훅 실행 자체가 세션을 중단시키지 않도록 하고 있습니다.

단계 3: settings.json에 훅을 등록하기

스크립트를 .claude/scripts/에 두고, settings.json의 Stop 훅으로 등록합니다.

{
"hooks": {
"Stop": [
...

이로써 세션이 종료될 때마다 요약이 자동 생성되며, 다음 기동 시에는 CLAUDE.md를 통해 자동으로 컨텍스트(Context)에 포함됩니다.

수동으로 명령어를 입력할 필요는 전혀 없습니다.

보너스: Discord로 요약 보내기

Discord bot을 평소에 운용하고 있는 분들을 위해, 요약을 Webhook으로 통지하는 코드도 추가해 둡니다.

def notify_discord(summary_lines: list) -> None:
webhook = os.environ.get("DISCORD_WEBHOOK_URL")
if not webhook:
...

Webhook URL은 반드시 환경 변수에서 읽어오도록 하여, 코드나 리포지토리에 직접 작성하지 않도록 합니다.

운용 팁: 비대화 방지

history.md는 방치하면 끝없이 늘어납니다.

• 월초 등의 타이밍에 오래된 엔트리를 아카이브한다
• CLAUDE.md

측면은 항상 최신 1건만 유지하는 설계를 깨뜨리지 않는다 - 기밀 정보(API 키나 개인 정보)를 요약에 포함하지 않도록, 추출 시 마스킹(Masking)한다.

특히 리포지토리(Repository)를 공개하고 있는 경우는 주의가 필요합니다.

요약

Claude Code의 Stop 훅(Stop hook)과 CLAUDE.md의 자동 읽기를 조합하면, 세션을 넘나드는 작업 기억의 인계를 실현할 수 있습니다.

이번에 만든 메커니즘의 포인트는 다음 세 가지입니다.

• 트랜스크립트(Transcript)에서 직전의 상호작용을 Python으로 추출한다
• CLAUDE.md의 특정 섹션만 최신화하여 정보량을 일정하게 유지한다
• 전체 이력은 별도 파일로 대피시켜, 필요할 때만 거슬러 올라갈 수 있도록 한다

여러 프로젝트를 오가는 개발자일수록 효과를 실감하기 쉬울 것입니다.

우선 자신의 프로젝트 하나에서 작게 시도해 보며, 요약의 입도(Granularity)를 조정해 나가는 것을 추천합니다.

참고

※ 본 기사는 AI(Claude)의 지원을 받아 집필되었으며, 필자가 리뷰 및 코드 동작 확인을 수행했습니다.

Discussion