세션 핸드오프 스킬
목적
대규모 컨텍스트 창은 토큰 수가 누적됨에 따라 명령어 준수, 추론 정밀도, 도구 정확도가 저하됩니다. 오래된 세션은 대체된 계획, 중단된 스크래치패드, 반복적인 오류 추적으로 가득 차게 됩니다. 새로운 세션으로 초기화하면 성능이 복원되지만, 컨텍스트를 맹목적으로 버리면 상태 손실, 환상적 진행, 반복적인 실수가 발생합니다.
session-handoff 스킬은 에이전트가 활성 상태를 스냅샷하는 방식을 표준화합니다. 일시적인 작업 메모리를 다음 세션을 위한 실행 가능하고 검증 가능한 브리지 문서로 변환합니다.
워크플로우: 세션 종료 (6단계)
에이전트 세션이 운영 한계에 도달하거나 작업을 중단할 때 이 순서를 실행하세요:
-
Git 및 작업 공간 상태 감사
git status -s및git diff --stat를 실행하여 현실에 기반한 상태를 파악하세요. 수정된 내용을 채팅 메모리에 의존하지 마십시오. 수정, 추적되지 않음, 스테이징된 파일을 식별하세요. -
목표 상태와 구현된 현실 캡처 원래 목표를 한 문장으로 정의하세요. 통과한 테스트 명령어나 런타임 검사를 통해 작동이 확인된 것을 부분적이거나 검증되지 않은 것과 정확히 구분하여 문서화하세요.
-
내린 결정과 폐기한 경로 기록 세션 중에 채택된 아키텍처 및 설계 결정과 구체적인 근거를 나열하세요. 부정적 결정(시도했다 폐기한 접근 방식)을 명시적으로 기록하여 다음 에이전트가 실패한 해결책을 다시 시도하지 않도록 하세요.
-
수정된 파일 및 관련 심볼 카탈로그 작성 수정되거나 참조된 주요 파일 경로, 함수, 클래스, 스키마 정의를 나열하세요. 관련된 경우 줄 번호를 포함하세요.
-
소유자와 검증이 있는 열린 루프 분리 해결되지 않은 모든 엣지 케이스, 실패한 테스트, 연기된 작업, 환경 제약 조건을 나열하세요. 모든 열린 루프는 누가 해결할지(인간 또는 에이전트)와 완료 여부를 어떻게 확인할지를 명시해야 합니다.
-
즉시 실행할 다음 작업 지정 다음 에이전트가 첫 번째 턴에 실행할 단일하고 원자적이며 모호하지 않은 명령어를 작성하세요. 광범위한 목록을 제공하지 말고, 먼저 실행할 정확한 명령어나 수정할 파일을 지정하세요.
운영 규칙
- 사실과 추측을 분리하세요: 통과한 테스트는 사실입니다. 컴파일되었다고 해서 코드가 작동한다고 가정하는 것은 추측입니다. 검증되지 않은 가정은 명시적으로
[UNVERIFIED]로 표시하세요. - 열린 루프에 소유자와 검증을 의무화하세요: 모든 열린 루프는 소유자(
Human또는Agent)와 결정론적 검증 기준(예:pytest tests/auth/test_token.py:test_refresh_rotation 통과)을 명시해야 합니다. - 모호한 연속을 금지하세요: "auth 작업 계속" 또는 "프론트엔드 컴포넌트 마무리"와 같이 작성하지 마세요. 정확한 심볼, 파일, 실패 모드를 명시하세요.
- 실제 작업 공간 식별자를 참조하세요: 코드에 대한 모든 참조는 정확한 파일 경로와 심볼 이름을 사용해야 합니다. 일반화된 의사코드 설명을 사용하지 마세요.
작업 예제: 세션 핸드오프 노트
# 세션 핸드오프: JWT 순환 구현
### 목표 및 현재 상태
- **목표**: FastAPI 인증 서비스에 리프레시 토큰 순환 및 철회 구현.
- **현재 상태**: 리프레시 토큰 데이터베이스 마이그레이션 적용 및 순환 엔드포인트 생성 완료. 토큰 생성 및 데이터베이스 저장은 작동함. 철회 블랙리스트 캐시가 아직 의존성 검증기에 연결되지 않음.
- **검증**: `pytest tests/test_auth_tokens.py` 통과 (4/4 테스트).
### 결정 사항 (이유 포함)
- **토큰 철회 목록에 Redis 사용**: 보호된 라우트에서 지연 시간을 5ms 미만으로 유지하기 위해 Postgres 조회 대신 Redis를 선택함.
- **무상태 리프레시 토큰 거부**: 처음에 JWT 클레임의 슬라이딩 만료(영속성 없음)를 평가했지만, 손상된 토큰을 자연 만료 전에 철회할 수 없어 폐기함.
- **토큰 형식**: 기존 세션 스토리지 스키마와의 호환성을 유지하기 위해 `jti` 클레임에 UUIDv4를 선택함.
### 변경된 파일
- `src/services/auth.py`: `rotate_refresh_token(old_token: str)` 함수 및 Redis 무효화 호출 추가.
- `src/models/tokens.py`: 토큰 패밀리 추적을 위한 `RefreshTokenRecord` SQLModel 테이블 추가.
- `alembic/versions/20261005_add_token_families.py`: `token_records` 테이블 생성 마이그레이션.
- `tests/test_auth_tokens.py`: 토큰 패밀리 생성 및 순환에 대한 단위 테스트 추가.
### 열린 루프
- [Agent] `verify_token_not_revoked`를 `src/api/deps.py`에 연결 -> `tests/test_auth_deps.py`가 블랙리스트된 토큰에 대해 실패하는지 확인.
- [Agent] 회전 중 Redis에 연결할 수 없는 경우 데이터베이스 롤백 처리 -> 단위 테스트에서 Redis 연결 실패를 모킹하여 확인.
- [Human] CI 실행을 위해 `REDIS_AUTH_URL` 시크릿을 `.env.test`에 설정.
### 다음 작업
`src/api/deps.py`를 열고 `src.services.auth`에서 `is_token_blacklisted`를 임포트하세요. JWT 디코드 검증 직후 `get_current_user`에 검사 로직을 삽입하세요.
### 주의 사항
- `src/core/config.py`에서 기존 `access_token` 만료 시간(현재 15분)을 수정하지 마세요.
- Alembic 마이그레이션 `20261005_add_token_families.py`는 로컬에서 API 서버를 시작하기 전에 실행해야 합니다(`alembic upgrade head`).
안티 패턴
- 채팅 기록 덤프: 핸드오프 노트에 원시 대화 로그를 붙여넣는 것. 다음 세션의 컨텍스트 창은 피하려던 대화 노이즈로 즉시 오염됩니다.
- 허상 통과: 모듈이 작성만 되고 실행되거나 테스트되지 않았는데 "완료"로 표시하는 것.
- 생략된 막다른 길: 실패한 해결책을 생략하는 것. 다음 에이전트는 코드베이스를 읽고 동일한 경로를 발견하여 실패한 접근 방식을 다시 구현할 것입니다.
- 추상적 다음 단계: "다음: 나머지 테스트 구현"으로 끝내는 것. 새 에이전트는 무엇을 테스트해야 하는지 발견하는 데 3-5턴을 불필요하게 소비합니다.
제한 사항
- 이 스킬은 문서화된 핸드오프만 생성합니다. 실행 중인 프로세스, 커밋되지 않은 터미널 출력, 인메모리 디버깅 컨텍스트와 같은 라이브 상태는 보존할 수 없습니다. 중요한 항목은 노트에 명시적으로 기록하세요.
- 핸드오프 품질은 종료 세션이 기록하는 내용에 의해 결정됩니다. 기록되지 않은 결정, 막다른 길, 파일 변경 사항은 다음 세션이 복구할 수 없습니다.
- 버전 관리나 이슈 트래킹을 대체하지 않습니다. 먼저 작업을 커밋하고 노트에 커밋이나 티켓을 참조하세요.