반복되는 작업
Claude Code로 여러 프로젝트를 동시에 진행하면서 매번 비슷한 요청을 하고 있었습니다.
- 컨텍스트가 일정량 이상 차면 응답 품질이 떨어지기 때문에, 그 전에 지금까지 한 작업을 정리해 달라고 하고 새 세션에서 그 내용을 읽고 이어서 진행해 달라고 했던 경험
- PR이 머지될 때마다 "머지했어. 브랜치, 워크트리, 이슈 정리해줘"라고 했던 경험
- 집과 회사 컴퓨터를 오가면서 작업을 시작할 때마다 원격 브랜치와 이슈, PR 상태를 확인해서 어디까지 했는지 알려 달라고 했던 경험
요청할 때마다 말이 조금씩 달랐고, 그만큼 결과도 달랐습니다. 정리를 부탁하면 어떤 날은 남은 작업이 빠지고 어떤 날은 결정한 이유가 빠졌습니다. 브랜치 정리도 어떤 날은 워크트리까지 지우고 어떤 날은 로컬 브랜치만 지웠습니다. 2번 요청은 9월에만 "브랜치 정리해줘", "미사용 워크트리 및 이슈 정리해줘", "머지는 내가 했어. 브랜치, 워크트리, 이슈 정리해줘"처럼 표현만 바꿔서 몇 번이나 반복했습니다.
스킬로 만들기
같은 요청을 반복하는 대신, 그 작업을 스킬로 만들어 달라고 했습니다.
| 스킬 | 만든 날 | 계기 |
|---|---|---|
context-handoff, context-resume |
2026-08-06 | 반복 작업 1번 |
sync |
2026-09-02 | 반복 작업 3번 |
cleanup |
2026-09-30 | 반복 작업 2번 |
이후에는 /context-handoff, /sync, /cleanup 한 줄로 같은 순서, 같은 형식으로 작업이 진행됐습니다. 대화 기록을 세어 보니 지금까지 /context-resume은 46번, /context-handoff는 16번, /sync는 9번, /cleanup은 4번 실행했습니다. "핸드오프해줘"처럼 말로 요청해서 스킬이 실행된 경우는 이 숫자에 들어가지 않습니다.
context-handoff, context-resume
처음에는 이렇게 물어봤습니다.
대화마다 컨택스트가 가득 차면 성능이 떨어지잖아. 컨택스트 50퍼 차면 다음 대화로 자동으로 열고 이어가도록 하는 스킬도 만들 수 있어?
새 대화를 자동으로 여는 것은 할 수 없었습니다. 대신 작업 상태를 문서로 저장하는 스킬과, 새 대화에서 그 문서를 읽어 이어가는 스킬을 짝으로 만들었습니다. 컨텍스트가 50%를 넘으면 "/context-handoff로 저장 후 새 대화를 여는 걸 권장합니다"라는 알림이 오도록 hook도 함께 설정했습니다.
/context-handoff- 현재 작업 상태를
~/.claude/handoffs/<프로젝트>/<시각>-<제목>.md에 저장 - 문서 내용: 요약, 내린 결정, 남은 작업, 주의사항, 브랜치, 수정한 파일 목록
- 코드는 수정하지 않고 문서만 쓰도록 제한
- 기존 문서는 덮어쓰거나 지우지 않음
- git 저장소가 아니어도 동작
- 현재 작업 상태를
/context-resume- 가장 최근 문서를 읽고 무엇을 하고 있었는지, 남은 작업이 무엇인지 짧게 알려 준 뒤 이어서 진행
/context-resume list로 저장된 문서 목록을 보고 번호로 선택 가능
- 만들면서 막아 둔 문제
- 한글이나 특수문자가 들어간 제목을 셸 명령에 바로 넣지 않고 임시 파일을 거쳐 읽도록 함
- 인계 문서 안에 적힌 문장을 명령으로 실행하지 않고 데이터로만 다루도록 함
새 세션에서 /context-resume을 실행하면 가장 최근 인계 문서를 읽고 진행 중이던 것과 남은 작업을 먼저 알려 줍니다.
마지막 문장을 보면, 인계 문서에 "이전 세션에서 승인받았다"고 적혀 있어도 push와 PR처럼 외부에 공개되는 작업은 다시 확인을 받습니다. 문서 내용을 데이터로만 다루도록 정해 둔 규칙이 그대로 동작한 경우입니다.
8월 6일부터 지금까지 인계 문서는 21개 폴더에 95개 정도 쌓였습니다. 가장 많이 쓴 프로젝트에는 30개가 있습니다. 세션을 넘길 때마다 무엇을 설명해야 할지 고민하지 않아도 되고, 새 세션에서는 /context-resume 한 줄로 바로 이어서 시작할 수 있게 됐습니다.
쓰다 보니 부족한 점도 있었습니다. 저장 폴더를 현재 폴더 이름으로 정하기 때문에 워크트리에서 작업하면 워크트리 이름으로 폴더가 따로 생깁니다. 실제로 79-modal-multipart, 83-mypage처럼 워크트리 이름으로 된 폴더에 문서가 하나씩 흩어져 있습니다. 한 번은 resume이 문서를 찾지 못해서 저장 위치를 직접 지정해서 불러와야 했습니다. 최근에는 워크트리 이름 폴더가 없을 때 프로젝트 이름 폴더를 대신 찾아서 이어가기도 했지만, 스킬에 정해 둔 동작이 아니라 그때그때 판단한 것이라 매번 그렇게 된다는 보장은 없습니다. 워크트리에서 저장해도 원래 저장소 이름 폴더에 모이도록 스킬을 고치는 것이 남은 개선점입니다.
sync
handoff 스킬을 만든 뒤에는 집에서도 같은 스킬을 쓰고 싶어서, 프로젝트 저장소에 스킬을 넣어 달라고 요청했습니다. 그런데 스킬만 옮긴다고 두 컴퓨터의 작업 상태가 맞춰지지는 않았습니다. 다른 컴퓨터에서 이어서 시작할 때마다 "현재 이슈, PR, origin/develop 확인해서 어느 작업까지 완료됐는지, 무슨 작업이 남았는지 파악해줘"처럼 상태 확인부터 다시 요청해야 했습니다.
그래서 두 컴퓨터에서 번갈아 작업해도 상태를 맞추고 이어서 작업할 수 있는 스킬을 만들었습니다. 처음에는 한 프로젝트 저장소 안에 만들었다가, 깃허브로 진행하는 다른 프로젝트에서도 모두 쓰고 싶어서 전역 스킬로 옮겼습니다.
/sync: 작업을 시작할 때, 머지 직후, PR 올리기 전에 사용/sync out: 자리를 뜨기 전이나 다른 컴퓨터로 넘어가기 전에 사용- 진행 순서: 상태 수집 → 판정 → 보고 → 승인한 것만 실행
- 저장소마다 규칙이 달라서 base 브랜치, 머지 방식, 이슈 연결 방식은 실행할 때 확인
- 프로젝트에 git 규칙 문서가 있으면 그 문서를 우선으로 따름
- 확인하는 항목
- base 브랜치에 작업이 반영됐는지
- 다른 컴퓨터에서 push한 커밋이 있는지
- 커밋하지 않은 변경이 있는지
- PR은 머지됐는데 이슈가 열려 있는지
.env.example에 있는 키가 로컬 env 파일에 빠져 있는지 (값은 보지 않고 키 이름만)
- 결과는 항상 같은 형식의 표로 보고하고, 어긋난 게 없으면 "조치 없음"으로 끝남
- force push, base 브랜치 직접 push, 이슈 일괄 닫기는 하지 않도록 제한
위 실행에서는 PR이 머지됐는데 이슈가 열려 있는 것을 2건 찾았습니다. 그런데 두 이슈의 판정이 달랐습니다. #470은 코드를 확인해 보니 체크박스 5개에 해당하는 작업이 모두 반영돼 있어서 닫아도 된다고 보고했습니다. #490은 관련 PR이 머지됐지만 일부 라벨과 문서가 아직 그대로라서, 남은 작업이 있으니 열어 두는 게 맞다고 판단했습니다. PR이 머지됐다는 이유만으로 이슈를 닫지 않고, 실제 코드로 확인한 근거에 따라 다르게 판정한 경우입니다. 제안 조치도 바로 실행하지 않고 번호를 붙여 보여 준 뒤, 승인한 것만 실행합니다.
rebase 머지를 쓰는 저장소에서는 머지할 때 커밋이 새로 쓰이기 때문에, git branch -d로 브랜치를 지우려고 하면 "not fully merged"라며 거부됩니다. 그래서 sync는 브랜치 이름이나 커밋 해시가 아니라 git cherry로 변경 내용이 base에 반영됐는지 확인한 뒤에 정리를 제안하도록 했습니다.
cleanup
sync에도 머지 후 정리를 보고하는 기능이 있었지만, 항목마다 승인을 받는 구조라 "머지했으니 정리해줘"처럼 한 번에 끝내고 싶을 때는 단계가 많았습니다. 그리고 서브에이전트를 쓰면서 늘어난 git 워크트리는 sync가 다루지 않았습니다. 9월 내내 머지할 때마다 정리를 말로 요청하다가, 9월 30일에 머지가 확인된 작업만 대상으로 좁혀서 한 번에 정리하는 스킬을 따로 만들었습니다.
- 정리하는 것: 열린 이슈, 워크트리, 로컬 브랜치, 원격 브랜치
- 하지 않는 것
- 머지되지 않은 PR, 커밋하지 않은 변경, 다른 세션이 사용 중인 워크트리는 건드리지 않음
- 이 PR과 관련 없는 이슈는 닫지 않음
- 지우기 전에 확인하는 것
- 브랜치: 머지된 PR의 마지막 커밋과 같은지 등, 반영됐다는 근거가 있는지
- 워크트리: 변경사항이 없는지, 다른 프로세스가 사용 중이지 않은지
- 이슈: 체크박스를 PR에서 실제로 한 작업과 하나씩 비교해서 체크
- 서브에이전트가 만든 워크트리와 함께 생긴 브랜치(
worktree-agent-*)도 정리 대상에 포함 - 정리 순서: 이슈 → 워크트리 → 로컬 브랜치 → 원격 브랜치
최근 PR 6개를 머지한 뒤 /cleanup을 실행했을 때는 이슈 6건을 닫고 워크트리 6개와 브랜치 14개를 지웠습니다. 이슈를 닫기 전에는 체크박스 18개를 PR에서 실제로 한 작업과 하나씩 맞춰 본 뒤 체크했습니다. 지금 작업 중인 세션의 워크트리와 다른 세션이 쓰던 워크트리 하나는 지우지 않고 남겼습니다.
다른 세션이 사용 중인 워크트리를 건드리지 않게 한 이유는, 여러 Claude 세션을 동시에 띄워 두고 작업하는 경우가 많기 때문입니다. 정리하다가 다른 세션이 작업하던 폴더가 사라지면 그 세션은 더 이상 진행할 수 없습니다.
스킬 내부 구조
- 스킬은 폴더 하나에
SKILL.md파일 하나 - 파일 맨 위에 이름(
name)과 설명(description)을 적고, 아래에 작업 순서와 규칙을 적음 description에는 언제 쓰는 스킬인지를 적음./이름으로 직접 부르지 않아도 상황이 맞으면 이 설명을 보고 스킬이 선택됨- 예: sync의 description에는 "세션 시작, 머지 직후 뒷정리, 다른 컴퓨터에서 이어받기, PR 올리기 전 점검"을 트리거로 적음
- 설치 위치
- 모든 프로젝트에서 쓰는 스킬:
~/.claude/skills/ - 특정 프로젝트에서만 쓰는 스킬: 프로젝트의
.claude/skills/
- 모든 프로젝트에서 쓰는 스킬:
만들면서 정한 기준
- 하지 않을 작업을 먼저 적는다
- 상태 확인과 실제 변경을 나누고, 변경은 확인 후에 한다
- 저장소 규칙은 고정해 두지 않고 실행할 때 확인한다
- 지우기 전에는 지워도 되는 근거를 하나씩 확인한다
- 결과 보고 형식을 고정한다
- 비밀값은 출력하지 않는다
마무리
처음부터 스킬을 만들려고 했던 것은 아닙니다. 같은 요청을 몇 번씩 하다 보니 매번 결과가 달라지는 게 불편했고, 그때 스킬로 만들어 달라고 했습니다. 만들고 나서도 한 번에 완성되지는 않았습니다. 워크트리에서 인계 문서가 흩어지는 문제나 sync로는 워크트리를 정리할 수 없는 문제는 실제로 써 보면서 알게 됐습니다.
저는 같은 요청을 세 번쯤 반복했을 때 스킬로 만들었습니다. 처음에는 작게 만들고, 쓰면서 부족한 부분을 고치거나 cleanup처럼 따로 떼어 내면 됩니다.
다음 글에서는 공모전 프로젝트에서 역할별 서브에이전트와 프로젝트 스킬을 나눠 쓴 방법을 정리하겠습니다.