세션 저장 명령어

언제 쓰나

현재 진행 중인 작업을 나중에 전체 컨텍스트를 유지한 채 다시 시작해야 할 때

---
description: 현재 세션 상태를 ~/.claude/session-data/에 날짜별 파일로 저장하여, 향후 세션에서 전체 컨텍스트를 유지한 채 작업을 재개할 수 있도록 합니다.
---

# 세션 저장 명령어

이 세션에서 발생한 모든 일 — 무엇을 구축했고, 무엇이 작동했으며, 무엇이 실패했고, 무엇이 남았는지 — 을 캡처하여 날짜별 파일에 기록합니다. 이를 통해 다음 세션은 현재 세션이 중단된 지점에서 정확히 이어갈 수 있습니다.

## 사용 시점

- Claude Code를 종료하기 전, 작업 세션 종료 시
- 컨텍스트 제한에 도달하기 전 (먼저 이 명령을 실행한 다음, 새 세션을 시작하세요)
- 기억하고 싶은 복잡한 문제를 해결한 후
- 향후 세션에 컨텍스트를 넘겨야 할 때

## 절차

### 단계 1: 컨텍스트 수집

파일을 작성하기 전에 다음을 수집하세요:

- 이 세션 동안 수정된 모든 파일 읽기 (git diff 사용 또는 대화에서 회상)
- 논의되고, 시도되었으며, 결정된 내용 검토
- 발생한 오류와 해결 방법 (또는 해결되지 않은 방법) 기록
- 관련 있는 경우 현재 테스트/빌드 상태 확인

### 단계 2: 세션 폴더가 존재하지 않으면 생성

사용자의 Claude 홈 디렉토리에 표준 세션 폴더를 생성합니다:

```bash
mkdir -p ~/.claude/session-data
```

### 단계 3: 세션 파일 작성

`~/.claude/session-data/YYYY-MM-DD-<short-id>-session.tmp` 파일을 생성합니다. 오늘 날짜와 `session-manager.js`의 `SESSION_FILENAME_REGEX`에서 강제하는 규칙을 만족하는 짧은 ID를 사용합니다:

- 호환 문자: 영문 `a-z` / `A-Z`, 숫자 `0-9`, 하이픈 `-`, 밑줄 `_
- 호환 최소 길이: 1자
- 새 파일에 권장되는 스타일: 충돌을 피하기 위해 8자 이상의 소문자, 숫자, 하이픈 사용

유효한 예시: `abc123de`, `a1b2c3d4`, `frontend-worktree-1`, `ChezMoi_2`
새 파일에 피해야 할 예시: `A`, `test_id1`, `ABC123de`

전체 유효한 파일 이름 예시: `2024-01-15-abc123de-session.tmp`

레거시 파일 이름 `YYYY-MM-DD-session.tmp`도 여전히 유효하지만, 같은 날짜에 충돌하는 것을 피하기 위해 새 세션 파일은 짧은 ID 형식을 선호해야 합니다.

### 단계 4: 아래 모든 섹션의 내용으로 파일 채우기

모든 섹션을 정직하게 작성하세요. 섹션을 건너뛰지 마세요 — 섹션에 실제로 내용이 없다면 "아직 없음" 또는 "해당 없음"이라고 작성하세요. 불완전한 파일은 정직하게 비어 있는 섹션보다 나쁩니다.

### 단계 5: 사용자에게 파일 보여주기

작성 후, 전체 내용을 표시하고 다음을 질문하세요:

```
세션이 [실제 세션 파일 경로]에 저장되었습니다.

정확하게 보이나요? 닫기 전에 수정하거나 추가할 내용이 있나요?
```

확인을 기다립니다. 요청 시 편집합니다.

---

## 세션 파일 형식

```markdown
# Session: YYYY-MM-DD

**Started:** [알고 있다면 대략적인 시간]
**Last Updated:** [현재 시간]
**Project:** [프로젝트 이름 또는 경로]
**Topic:** [이 세션이 무엇에 관한 것인지 한 줄 요약]

---

## 무엇을 구축하고 있나요

[기능, 버그 수정 또는 작업에 대한 1-3 문단. 이 세션에 대해 전혀 기억이 없는 사람도 목표를 이해할 수 있을 만큼 충분한 컨텍스트를 포함하세요.
포함할 내용: 무엇을 하는지, 왜 필요한지, 더 큰 시스템에 어떻게 맞춰지는지]

---

## 무엇이 작동했나요 (증거 포함)

[작동이 확인된 것만 나열합니다. 각 항목에 대해 왜 작동하는지 — 테스트 통과, 브라우저에서 실행, Postman에서 200 반환 등 — 을 포함하세요. 증거 없이는 "아직 시도 안 함"으로 옮기세요.]

- **[작동하는 것]** — 확인 증거: [구체적인 증거]
- **[작동하는 것]** — 확인 증거: [구체적인 증거]

아직 아무것도 확인되지 않았다면: "아직 확인된 작동 사례 없음 — 모든 접근 방식은 진행 중이거나 테스트되지 않았습니다."

---

## 작동하지 않은 것 (그리고 그 이유)

[이것이 가장 중요한 섹션입니다. 실패한 모든 시도된 접근 방식을 나열하세요. 각 실패에 대해 다음 세션에서 같은 시도를 반복하지 않도록 정확한 이유를 작성하세요. 구체적으로 작성하세요: "X 오류가 Y 때문에 발생함"은 유용합니다. "작동하지 않음"은 유용하지 않습니다.]

- **[시도한 접근 방식]** — 실패 이유: [정확한 이유 / 오류 메시지]
- **[시도한 접근 방식]** — 실패 이유: [정확한 이유 / 오류 메시지]

실패한 것이 없다면: "아직 실패한 접근 방식 없음."

---

## 아직 시도되지 않은 것

[유망해 보이지만 아직 시도되지 않은 접근 방식. 대화에서 나온 아이디어. 탐색할 가치가 있는 대안 솔루션. 다음 세션에서 정확히 무엇을 시도해야 하는지 알 수 있도록 구체적으로 작성하세요.]

- [접근 방식 / 아이디어]
- [접근 방식 / 아이디어]

대기열에 아무것도 없다면: "아직 식별된 구체적인 시도되지 않은 접근 방식 없음."

---

## 현재 파일 상태

[이번 세션에서 다룬 모든 파일. 각 파일의 상태를 정확하게 명시하세요.]

| 파일              | 상태         | 참고사항                      |
| ----------------- | -------------- | -------------------------- |
| `path/to/file.ts` | PASS: 완료    | [무엇을 하는지]             |
| `path/to/file.ts` | 진행 중 | [완료된 부분, 남은 부분] |
| `path/to/file.ts` | FAIL: 고장남      | [무엇이 잘못되었는지]             |
| `path/to/file.ts` | 시작 안 함 | [계획되었지만 아직 건드리지 않음]  |

수정된 파일이 없다면: "이번 세션에서 수정된 파일 없음."

---

## 결정된 사항

[아키텍처 선택, 수락된 절충안, 선택된 접근 방식 및 그 이유. 다음 세션에서 이미 결정된 사항을 재검토하지 않도록 합니다.]

- **[결정]** — 이유: [대안 대비 이것이 선택된 이유]

중요한 결정이 없다면: "주요 결정 사항 없음."

---

## 차단 요소 및 미해결 질문

[다음 세션에서 해결하거나 조사해야 할 해결되지 않은 사항. 제기되었지만 답변되지 않은 질문. 대기 중인 외부 종속성.]

- [차단 요소 / 미해결 질문]

없다면: "현재 활성 차단 요소 없음."

---

## 정확한 다음 단계

[알고 있다면: 재개 시 수행해야 할 가장 중요한 단일 작업. 재개 시 시작 지점에 대해 전혀 생각할 필요가 없을 정도로 정확하게 작성하세요.]

[알고 있지 않다면: "다음 단계 미정 — 방향을 결정하기 전에 "아직 시도되지 않은 것" 및 "차단 요소" 섹션을 검토하세요."]

---

## 환경 및 설정 참고사항

[관련 있는 경우에만 채우세요 — 프로젝트 실행에 필요한 명령어, 필요한 환경 변수, 실행해야 하는 서비스 등. 표준 설정이면 건너뛰세요.]

[해당 사항이 없다면: 이 섹션을 완전히 생략하세요.]
```

---

## 예시 출력

```markdown
# Session: 2024-01-15

**Started:** 오후 2시경
**Last Updated:** 오후 5:30
**Project:** my-app
**Topic:** httpOnly 쿠키를 사용한 JWT 인증 구축

---

## 무엇을 구축하고 있나요

Next.js 앱을 위한 사용자 인증 시스템. 사용자는 이메일/비밀번호로 등록하고, httpOnly 쿠키(localStorage 아님)에 저장된 JWT를 받으며, 보호된 경로는 미들웨어를 통해 유효한 토큰을 확인합니다. 목표는 토큰을 JavaScript에 노출하지 않고 브라우저 새로고침에 걸쳐 세션 지속성을 유지하는 것입니다.

---

## 무엇이 작동했나요 (증거 포함)

- **`/api/auth/register` 엔드포인트** — 확인 증거: Postman POST 요청 시 200 반환 (사용자 객체 포함), Supabase 대시보드에 행 표시, bcrypt 해시가 올바르게 저장됨
- **`lib/auth.ts`의 JWT 생성** — 확인 증거: 단위 테스트 통과 (`npm test -- auth.test.ts`), jwt.io에서 디코딩된 토큰이 올바른 페이로드 표시
- **비밀번호 해싱** — 확인 증거: 테스트에서 `bcrypt.compare()`가 true 반환

---

## 작동하지 않은 것 (그리고 그 이유)

- **Next-Auth 라이브러리** — 실패 이유: 사용자 지정 Prisma 어댑터와 충돌하며, 모든 요청에서 "Cannot use adapter with credentials provider in this configuration" 오류 발생. 디버깅할 가치가 없음 — 우리 설정에는 너무 의견이 강함.
- **localStorage에 JWT 저장** — 실패 이유: SSR 렌더링은 localStorage가 사용 가능하기 전에 발생하므로, 모든 페이지 로드 시 React 하이드레이션 불일치 오류 발생. 이 접근 방식은 Next.js SSR과 기본적으로 호환되지 않음.

---

## 아직 시도되지 않은 것

- 로그인 경로 응답에서 JWT를 httpOnly 쿠키로 저장 (가장 가능성 높은 해결책)
- `next/headers`의 `cookies()`를 사용하여 서버 컴포넌트에서 쿠키 읽기
- `middleware.ts`를 작성하여 쿠키 존재 여부를 확인하여 경로 보호

---

## 현재 파일 상태

| 파일                             | 상태         | 참고사항                                           |
| -------------------------------- | -------------- | ----------------------------------------------- |
| `app/api/auth/register/route.ts` | PASS: 완료    | 작동함, 테스트 완료                                   |
| `app/api/auth/login/route.ts`    | 진행 중 | 토큰은 생성되나 아직 쿠키 설정 안 됨      |
| `lib/auth.ts`                    | PASS: 완료    | JWT 헬퍼, 모두 테스트 완료                         |
| `middleware.ts`                  | 시작 안 함 | 경로 보호, 쿠키 읽기 로직 우선 필요 |            |
| `app/login/page.tsx`             | 시작 안 함 | UI 시작 안 됨                                  |

---

## 결정된 사항

- **localStorage 대신 httpOnly 쿠키** — 이유: XSS 토큰 도용 방지, SSR과 호환
- **Next-Auth 대신 자체 인증** — 이유: Next-Auth가 Prisma 설정과 충돌하여, 싸울 가치가 없음

---

## 차단 요소 및 미해결 질문

- `cookies().set()`은 Route Handler 내에서 작동하는가, 아니면 Server Actions에서만 작동하는가? 확인 필요.

---

## 정확한 다음 단계

`app/api/auth/login/route.ts` 파일에서 JWT 생성 후, `cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })`을 사용하여 httpOnly 쿠키로 설정합니다. 그 후 Postman으로 테스트하면 응답에 `Set-Cookie` 헤더가 포함되어야 합니다.
```

---

## 참고사항

- 각 세션은 자체 파일로 저장됩니다 — 이전 세션 파일에 절대 추가하지 마세요.
- "작동하지 않은 것" 섹션이 가장 중요합니다 — 향후 세션은 이 정보 없이는 실패한 접근 방식을 맹목적으로 반복할 것입니다.
- 사용자가 세션 중간에 저장을 요청하면 (단순히 끝이 아니라), 현재까지 알려진 내용을 저장하고 진행 중인 항목을 명확하게 표시하세요.
- 이 파일은 다음 세션 시작 시 `/resume-session`을 통해 Claude가 읽을 수 있도록 작성됩니다.
- 표준 전역 세션 저장소를 사용하세요: `~/.claude/session-data/`
- 새 세션 파일에는 짧은 ID 형식 (`YYYY-MM-DD-<short-id>-session.tmp`)을 선호하세요.

1. 1

   SKILL.md 저장

   아래 버튼으로 복사 → 다음 경로로 저장.

   SKILL.md 복사

   macOSLinuxWindows

   ~/.claude/skills/everything-claude-code-162/SKILL.md경로 복사
2. 2

   호출

   Claude Code 채팅창에서 자연어로 부르면 자동 발동:

   예) 현재 진행 중인 작업을 나중에 전체 컨텍스트를 유지한 채 다시 시작해야 할 때

   트리거가 안 잡히면 SKILL.md의 description 줄에 더 구체적인 한국어 키워드를 추가해보세요.