AI 작업 상태와 인계AI Task State and Handoffs
📅
들어가기 전에 🔗
AI와 한 시간 동안 버그를 분석하고 구현을 절반쯤 마쳤습니다.
다음 날 새 세션에서 “어제 하던 작업 이어서 해”라고 요청했더니, 이미 확인한 파일부터 다시 읽고 기각한 가설을 다시 제안합니다.
반대로 이전 대화를 통째로 붙여 넣으면 오래된 로그와 실패한 수정까지 새 컨텍스트를 채웁니다.
작업을 이어가려면 다음 세션이 판단할 수 있는
현재 상태와 확인 근거
가 필요합니다.
무엇을 하려는지, 실제 코드가 어디까지 바뀌었는지, 무엇을 검증했고 다음에 무엇을 해야 하는지를 남깁니다.
이번 글에서는 대화 압축과 작업 인계를 구분하고, 저장소에 짧은 기록을 두어 작업을 재개하는 방법을 정리합니다.재개와 인계 🔗
대화를 복원하는 일과 현재 코드 상태를 확인하는 일은 별개의 절차입니다.
같은 도구에서 이전 세션을 다시 열 수 있다면 대화를 이어가는 편이 편리합니다.
하지만 대화가 저장됐다고 해서 그사이 사람이 수정한 파일이나 바뀐 브랜치까지 자동으로 일치하는 것은 아닙니다.
새 세션으로 넘길 때뿐 아니라 기존 세션을 재개할 때도 현재 작업 경로와 변경 상태를 확인합니다.
| 방식 | 이어지는 정보 | 별도로 확인할 것 |
|---|---|---|
| 이전 세션 재개 | 저장된 대화와 도구가 복원하는 상태 | 현재 작업 경로·파일·실행 환경 |
| 대화 압축 | 다음 작업에 필요한 대화 상태 | 중요한 조건과 근거가 유지됐는지 |
| 인계 기록으로 새로 시작 | 명시적으로 남긴 목표·상태·다음 행동 | 기록이 현재 코드와 일치하는지 |
OpenAI는 긴 대화를 이어가기 위한 압축 기능을 설명하며, API가 반환하는 압축 항목은 사람이 읽는 요약 문서가 아닌 불투명한 상태라고 구분합니다.
OpenAI 대화 압축 문서↗
즉, API 압축 항목과 사람이 검토하는
handoff.md는 같은 형식이나 기능이 아닙니다.
인계 기록은 다른 도구나 새 세션에서도 작업의 근거를 확인할 수 있도록 만드는 팀의 문서입니다.기록할 상태 🔗
전체 대화를 줄여 쓰기보다 다음 판단에 필요한 네 가지를 남깁니다.
검색 필터의 뒤로 가기 오류를 수정하던 작업이라면 다음처럼 정리할 수 있습니다.
| 항목 | 남길 내용 | 예시 |
|---|---|---|
| 목표와 경계 | 완료 조건, 변경·제외 범위 | URL과 입력값 복원, API 변경 제외 |
| 현재 코드 | 작업 경로, 기준 커밋, 변경 파일 | 검색 폼 수정 중, 테스트 파일 미추적 |
| 검증 근거 | 명령과 결과, 적용한 코드 상태 | 타입 검사 통과, 뒤로 가기 테스트 실패 |
| 다음 행동 | 미완료 작업, 남은 판단 | URL 변경 시 로컬 상태 갱신 경로 확인 |
작업 인계 기록의 목표와 경계, 현재 코드, 검증 근거, 다음 행동을 정리한 인포그래픽
사실과 가설 🔗
“뒤로 가기 때 URL은 alpha로 돌아오지만 입력창은 beta”는 관찰입니다.
“초기값만 읽어서 상태 동기화가 빠졌다”는 원인 가설입니다.
기록에서 둘을 나누면 다음 세션이 추측을 확정된 사실처럼 받아들이는 일을 줄일 수 있습니다.
기각한 접근도 필요한 경우에만 이유와 함께 남깁니다.
예를 들어 “검색 API 캐시가 원인이라는 가설은 입력창 상태만 어긋나는 재현과 맞지 않아 보류”라고 적습니다.
실패한 시도의 모든 로그와 코드를 본문에 복사할 필요는 없습니다.
원본 로그 위치나 관련 파일을 참조할 수 있게 남깁니다.
👨💻
다음 세션의 첫 행동을 한 단계로 적어 보시기 바랍니다.
“검색 기능 마무리”보다 “SearchForm의 URL 변경 구독과 로컬 입력 상태 갱신을 확인”이 작업을 시작하기 쉽습니다.
인계 문서 🔗
다음은 작업별 상태 문서의 예시입니다.
파일 이름과 위치는 도구가 특별 취급하는 규약이 아니라 팀이 정한 저장 방식입니다.
새 세션의 요청에서 경로를 명시해야 실제로 읽도록 안내할 수 있습니다.
task: search-history
updated_at: "2026-10-15T15:00:00+09:00"
goal: 뒤로 가기와 새로고침 뒤 URL과 입력값을 함께 복원
scope:
include: 검색 폼 상태와 관련 테스트
exclude: 검색 API와 정렬 규칙
workspace:
path: /Users/dev/work/shop
head: "git rev-parse HEAD로 확인한 커밋 해시"
uncommitted: true
changed_files:
- src/features/search/SearchForm.tsx
untracked_files:
- tests/search-history.spec.ts
observed:
- alpha → beta → 뒤로 가기에서 URL은 alpha, 입력창은 beta
hypothesis:
- URL 변경을 로컬 입력 상태가 다시 반영하지 않을 수 있음
checks:
- command: npm run typecheck
result: passed
- command: npx playwright test tests/search-history.spec.ts
result: failed
detail: 입력값 alpha를 기대했으나 beta가 남음
- command: npm run build
result: not_run
evidence_scope: 위 변경 파일 상태에서 실행한 예시 결과
next_action: URL 변경과 로컬 상태 동기화 경로 확인내용은 형식을 설명하는 가상 예시이며 실제 프로젝트의 실행 결과가 아닙니다.
실제 기록에는 현재 경로와 커밋 해시, 실행한 명령과 결과를 넣습니다.
로그를 남긴 경우 해당 경로를 추가하고, 다음 세션이 볼 수 있는 위치인지 확인합니다.
특히
커밋 해시만으로 미커밋 변경까지 전달되지는 않습니다.
같은 체크아웃에서 이어간다면 파일이 남아 있는지 확인합니다.
다른 환경으로 옮긴다면 필요한 변경을 커밋·패치 등 팀이 선택한 방식으로 별도 전달해야 합니다.
작업 경로만 적어 두었다고 다른 환경에 파일이 생기는 것은 아닙니다.갱신 시점 🔗
상태 기록을 매 대화마다 길게 다시 작성하면 기록 비용이 커집니다.
다음과 같이 작업 단계가 바뀌는 시점에 갱신하는 편이 실용적입니다.
- 원인 분석이 끝나고 구현으로 넘어갈 때
- 검증 실패가 다음 수정의 기준으로 확정됐을 때
- 작업을 중단하거나 새 세션·다른 도구로 넘길 때
- 완료 뒤 남은 한계와 최종 검증을 정리할 때
이미 끝난 항목을 계속 누적하기보다 현재 판단에 필요한 내용으로 갱신합니다.
상세 이력이 필요하면 Git 변경 이력과 원본 근거를 참조합니다.
코드 상태 대조 🔗
인계 기록을 읽은 다음에는 실제 저장소 상태와 대조합니다.
macOS 터미널에서 아래 명령으로 현재 경로와 커밋, 추적 파일 변경, 새 파일을 확인할 수 있습니다.
Git 명령은 Windows·Linux에서도 같고 경로 표기만 환경에 맞춰 바꿉니다.
git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git status --short
git diff --stat
git diff --cached --stat
git ls-files --others --exclude-standardgit diff만 보면 스테이징된 변경과 미추적 파일을 놓칠 수 있습니다.
관련 파일의 실제 diff와 새 파일 내용도 필요한 범위에서 읽습니다.
위 목록은 무시된 환경 파일이나 외부 DB 상태까지 보여 주지 않으므로, 작업에 필요한 실행 환경은 별도로 확인합니다.
인계 기록 읽기, 실제 코드 상태 대조, 검증 결과 확인, 다음 작업 실행으로 이어지는 새 세션 재개 절차
👍
HEAD가 같아도 미커밋 파일이 바뀌었다면 이전 테스트 결과의 적용 범위가 달라집니다.
반대로 다른 커밋이라고 무조건 모든 검사를 다시 할 필요는 없습니다.
변경된 부분과 기존 근거의 관계를 확인하고, 영향을 받는 검사를 다시 실행합니다.
세션 재개 🔗
Claude Code는 현재 디렉터리의 최근 세션을
claude --continue로 이어갈 수 있습니다.
이전 대화 목록에서 선택하려면 claude --resume을 사용합니다.
Claude Code 대화 재개↗claude --continueCodex CLI는
codex resume으로 저장된 대화를 선택해 이어갈 수 있습니다.
앱에서는 해당 프로젝트의 기존 채팅을 열어 작업을 이어갑니다.
Codex 프로젝트와 채팅↗codex resume어떤 방식이든 올바른 작업 디렉터리와 채팅을 선택했는지 확인합니다.
“계속해”라는 한 문장만 보내기보다 현재 기록과 실제 코드를 대조한 뒤 남은 작업을 수행하도록 요청하면 좋습니다.
대화 압축 🔗
같은 작업을 계속하는데 대화만 길어졌다면 압축을 검토할 수 있습니다.
Claude Code는 자동 압축과
/compact를 제공하고, 보존할 내용을 지시할 수도 있습니다.
Claude Code 컨텍스트 관리↗/compact 목표와 제외 범위, 변경 파일, 검증 결과, 남은 판단을 보존압축은 현재 작업을 계속하기 위한 기능이고, 인계 문서는 사람이 근거를 확인하거나 다른 세션으로 옮기는 데 쓰는 기록입니다.
도구별 압축 동작을 같다고 가정하지 말고, 중요한 상태는 실제 파일과 함께 확인합니다.
서로 관련 없는 작업으로 넘어간다면 필요한 인계 기록을 남긴 뒤 별도 세션을 시작하는 편이 맥락을 관리하기 쉽습니다.
새 세션 요청 🔗
새 세션에 대화 전체를 복사하는 대신 기록 경로와 시작 절차를 알려 줍니다.
다음 요청에서 인계 파일 경로와 작업 이름을 현재 환경에 맞춰 바꿉니다.
docs/tasks/search-history-handoff.yaml을 읽고 작업을 이어가세요.
먼저 현재 경로, HEAD, 미커밋·미추적 변경을 기록과 대조하세요.
차이가 있으면 관련 파일을 확인해 현재 상태를 갱신하세요.
통과·실패·미실행 검사를 구분하고 결과의 적용 범위를 확인하세요.
다음 행동에 필요한 파일부터 읽고, 기존 목표와 제외 범위를 지키세요.
수정 뒤 관련 검증을 실행하고 인계 기록을 최신 상태로 바꾸세요.새 세션이 처음 읽을 파일 수를 제한하더라도 필요한 의존성을 읽을 수 없게 막지는 않습니다.
목표는 관련 없는 재탐색을 줄이는 것이지 확인 과정을 생략하는 것이 아닙니다.
🖐️
이전 기록의 “완료”나 “테스트 통과”를 현재 코드의 증명으로 취급하지 마십시오.
기록과 실제 상태가 어긋나면 기록을 근거로 코드를 덮어쓰지 말고, 무엇이 바뀌었는지부터 확인합니다.
기록의 수명 🔗
2편의
AGENTS.md·CLAUDE.md에는 저장소에서 반복 적용할 규칙을 둡니다.
이번 작업의 실패 로그와 다음 행동까지 공통 지침에 계속 추가하면 모든 작업이 같은 오래된 맥락을 읽게 됩니다.
정보가 얼마나 오래 유효한지에 따라 위치를 나눕니다.| 정보 | 적합한 위치 | 갱신 기준 |
|---|---|---|
| 공통 규칙과 검증 명령 | 저장소 지침 | 규칙·환경 변경 시 |
| 이번 작업의 현재 상태 | 작업별 인계 문서 | 단계 전환·중단·재개 시 |
| 자세한 실패 출력 | 로그와 테스트 산출물 | 실행 결과별 보관 |
| 최종 설계와 사용 방법 | 정식 문서·PR 설명 | 구현과 합의 반영 시 |
완료한 인계 문서는 활성 작업 목록에서 제외하거나 완료 상태로 정리합니다.
다음 작업이 오래된 미완료 지시를 현재 요청으로 오해하지 않게 합니다.
재사용할 가치가 있는 결론만 정식 문서나 공통 지침으로 옮깁니다.
👨💻
인계의 품질은 문서 길이보다 다음 세션이 무엇을 다시 확인했는지로 판단해 보시기 바랍니다.
이미 끝난 탐색을 반복했는지, 미완료 작업을 놓쳤는지, 현재 코드와 다른 기록 때문에 재작업이 생겼는지를 확인합니다.
결론 🔗
AI 작업을 이어가기 위해 필요한 것은 짧은 대화 요약과 함께 남기는 코드 상태와 근거입니다.
목표·변경 경계·미커밋 파일·검증 결과·다음 행동을 기록하고, 재개할 때 실제 상태와 대조해야 합니다.
기록 읽기 → 코드 상태 대조 → 근거 확인 → 다음 행동 실행
을 작업 시작 절차로 만들어 보시기 바랍니다.
11편에서는 이 기록과 작업 경계를 바탕으로 여러 작업을 병렬로 진행하고 결과를 통합하는 방법을 다룹니다.