4시간마다 무인으로 작동하는 Claude Code가 이전 회차의 중단된 작업을 마무리하는 절차

Claude Code를 스케줄러에서 주기적으로 실행하면, 도중에 멈추는 경우가 있습니다. 사용 한도에 도달했거나, 시간 제한을 초과하여 외부에서 강제 종료되거나, PC가 다운될 수 있습니다. 멈춘 회차의 Claude는 자신이 무엇을 하던 중이었는지 다음 회차에 남길 수 없습니다. 다음 회차 세션은 새로 시작되기 때문에 이전 회차의 대화 기록이 없기 때문입니다.

남아 있는 단서는 작업장(working directory)의 파일뿐입니다. 본 글에서는 git의 작업 트리에 남아있는 커밋되지 않은 변경 사항을, 다음 회차의 Claude Code가 스스로 파악하여 마무리하는 절차를 작성합니다.

준비물은 Claude Code를 CEO 역할로 4시간마다 실행하는 작은 메커니즘에 대한 기록입니다. Windows의 작업 스케줄러가 Python으로 작성된 실행 메커니즘을 작동시키고, 이 실행 메커니즘이 claude -p를 실행합니다. 실행된 Claude는 업무를 선택하고 서브 에이전트에게 맡긴 후, 회차 마감 시 일일 보고서(日報)를 작성합니다. 절차는 이 메커니즘의 헌장(매번 처음에 읽기로 정한 파일)에 있으며, 예시는 일일 보고서에서 가져왔습니다.

전제: 건별로 커밋하고 회차를 누적하지 않기

이 절차는 다음 두 가지가 성립할 때만 사용할 수 있습니다.

• 업무를 한 건 완료할 때마다 커밋(commit)한다. 회차 마감 시에 모아서 커밋하지 않는다.
• 같은 작업장에서 2개의 회차가 동시에 작동하지 않는다. 실행 메커니즘은 Claude를 시작하기 전에 잠금 파일(lock file)을 확인하여, 이전 회차가 작동 중이면 아무것도 하지 않고 종료된다. 시간 제한을 크게 초과한 오래된 잠금 파일은 다운된 회차의 잔해로 간주하고 무시한다.

건별로 커밋했다면, 끝까지 실행된 회차 이후의 작업 트리는 깨끗하게 정리됩니다. 따라서 회차 시작 시에 커밋되지 않은 변경 사항이 있다면, 이전 회차가 도중에 멈췄다고 의심할 수 있습니다. 다만, 남아 있는 변경 사항이 모두 이전 회차 Claude가 작성하던 것일 필요는 없습니다. 그 부분을 어떻게 구분하는지가 이 절차의 핵심입니다.

전체 절차

1. 회차 시작 시, 건드린 모든 작업장에서 git status를 확인한다
2. 남아있는 변경 사항을 소유자별로 3가지로 나눈다
a. 실행 메커니즘이 작성한 파일
... 

아래에 순서대로 적습니다.

1. 건드린 모든 작업장에서 git status를 확인하기

이 메커니즘에서는 Claude가 작성하는 리포지토리가 3가지로 나뉘어 있습니다. 회사 상태를 두는 것, 기사 원고를 두는 것, 새로운 수익 모델 시제품을 두는 것입니다. 회차 시작 시에 이 3가지 모두에서 git status를 확인합니다.

하나만 보고 끝내면 흔적을 놓칩니다. 회차가 멈췄을 때, 어느 리포지토리까지 커밋이 진행되었는지는 그 회차마다 다르기 때문입니다.

2. 소유자별로 나누기

커밋되지 않은 변경 사항을 발견했을 때, 가장 먼저 묻는 것은 '완료했는지'가 아니라 '누가 작성했는지'입니다. 소유자에 따라 다음 회차의 Claude가 해도 되는 일이 달라집니다.

메커니즘이 작성한 것들

기록에 나온 예시를 2가지 들겠습니다.

10월 5일 21시 46분 회차 시작 시, 개발 부서로 보내는 지시서가 추적되지 않은 채 남아 있었습니다. 지시서의 위치는 헌장에서 실행 메커니즘의 소유물로 되어 있습니다. CEO는 이것을 되돌리지 않고 커밋하고, 일일 보고서에 '실행 메커니즘이 작성하는 것이므로'라는 이유를 첨부했습니다. 지시서가 남아 있는 것은, 실행 메커니즘이 아직 그 지시를 처리하지 않았다는 의미이기도 합니다. CEO는 그 회차에 새로운 지시서를 내지 않았습니다.

10월 7일 21시 47분 회차는 사용 한도에 도달하여, 실행 메커니즘이 '보류' 기록을 작성했습니다. 이 기록은 추적되지 않은 채 남아 있었고, 다음 22시 23분 회차의 CEO가 커밋했습니다. 실패나 보류 기록은 Claude의 세션이 끝난 후에 실행 메커니즘이 작성합니다. 따라서 그것을 커밋하는 것은 다음 회차의 업무가 됩니다.

인간이 수정한 것

기사의 원고 리포지토리에는 제목 이미지를 만드는 스크립트의 커밋되지 않은 변경 사항이 남아 있는 경우가 있었다. 10월 4일 0시 회차부터 10월 6일 7시 20분 회차까지, 적어도 5번의 일보에 계속해서 등장한다. 일보에는 인간이 제목 이미지의 접는 방식을 수정한 것이라고 쓰여 있다.

이 스크립트가 놓인 곳은 Claude가 작성해도 되는 범위를 벗어난다. 10월 4일 0시 회차의 CEO는 커밋하려고 할 때 git add을 가드에 의해 막혔다. 회피책을 찾지 않고 인간에게 커밋을 부탁했다고 일보에 적었다. 이후 회차에는, 인간이 수정한 것이 범위 밖에 있으므로 건드리지 않았다고 일보에 써서 넘어간다.

인간의 미완성 작업은 완성되었는지 여부를 Claude가 결정해서는 안 된다. 만지지 않고 남겨두고, 발견한 사실만 적는다.

3. 이전 회차의 Claude가 작성한 것은 완성되었는지 확인하기

소유자가 이전 회차의 Claude임을 알게 되면, 내용을 살펴본다. 자(物差し)는 그 작업의 계획이나 규칙에 쓰여 있는 완료 기준이다. 원고라면 예정된 장이 갖춰져 있는지, 기사 소재 수요 조사라면 계획했던 검색어를 모두 돌렸는지와 같은 형태가 된다.

10월 7일 22시 23분 회차 시작 시, 기사 원고 리포지토리에 기사 소재 수요를 조사한 결과 파일이 커밋되지 않은 채 남아 있었다. 계획에 따라 조사하기로 결정한 검색어는 7개였고, 파일에는 모두 7개의 결과가 쓰여 있었다. CEO는 이를 완성으로 보고 다시 작성하지 않고 커밋했다.

망가졌다면, 파일을 지정하여 되돌리기

완성되지 않았다면, git restore로 마지막 커밋 상태로 되돌린다. 헌장은 파일을 하나씩 지목해서 되돌리라고 요구하고 있다.

# 되돌릴 파일을 하나씩 지목한다 (작업장별/파일별 1회)
git -C <작업장> restore <손상된 파일>

왜 지목해야 하는지는 헌장에 쓰여 있지 않다. 다만, 위 제목 이미지 스크립트처럼 같은 작업장에 인간의 미완성 작업이 며칠 동안 남아 있는 경우가 있기 때문이다. 작업 트리를 한 번에 되돌리면, 인간의 미완성 작업도 함께 사라진다. 지목해서 되돌리는 것은 이전 회차의 Claude의 미완성 작업만을 노리기 위함으로 읽힌다.

추적되지 않은 손상된 파일은 삭제하지 않고 남기기

한 번도 커밋되지 않은 새로운 파일은 git restore로는 사라지지 않는다. 지우려면 rm이나 git clean이 필요하지만, 이 시스템에서는 그 어느 것도 Claude에게 허용하지 않았다. 그래서 헌장은 추적되지 않은 손상된 파일은 지울 수 없으므로 일보에 써서 남기도록 한다.

삭제 권한을 주지 않는 대신 받아들이는 노력이다. 일보에 남아 있다면, 삭제할지 여부는 인간이 결정할 수 있다.

4. 상태 파일과 이력을 대조하기

파일 정리가 끝나면, 상태 파일을 본다. 이 시스템에서는 진행 중인 작업과 공정을 '운영 보드(経営ボード)'라는 하나의 파일에 작성하고, 건 하나 끝날 때마다 업데이트하여 커밋한다. 회차가 도중에 멈추면, 보드와 실제 커밋이 어긋난다.

10월 7일 22시 23분 회차에서는, 어긋남이 두드러졌다. 직전의 21시 47분 회차는 미루기 기록이었는데도, 보드에는 그 이후의 21시 48분과 21시 58분의 처리가 쓰여 있었다. 게다가 21시 58분에 CEO가 승인했다고 쓰인 조사 결과는 위에서 적은 대로 커밋되지 않은 채 남아 있었다. 어떤 경위로 그렇게 되었는지는 일보에는 쓰여 있지 않다.

실패나 미루기 기록만 보고, 이전 회차에 아무것도 하지 않았다고 결정해서는 안 된다. 작업 트리(作業ツリー), git의 이력, 상태 파일 3가지를 나란히 놓고, 차이점을 찾는다. 볼 것은 다음 두 가지이다.

• 보드에 '완료'라고 쓰여 있는 공정의 성과물이 이력에 있는지
• 이력에 있는 커밋의 공정이 보드에 쓰여 있는지

맞지 않으면, 이력에 맞춰 보드를 고친다. 보드는 Claude가 작성한 요약이고, 이력은 실제로 일어난 것의 기록이기 때문이다.

5. 일보에 적기

마지막으로, 무엇을 어떻게 정리했는지를 일보의 '상황'란에 적는다. 쓸 내용은 다음 항목이다.

• 어느 작업장에, 무엇이 남아 있었는지
• 소유자를 어떻게 판단했는지
• 커밋했는지, 되돌렸는지, 건드리지 않았는지. 커밋했다면, 그 커밋 번호
• 지울 수 없어 남긴 파일과, 인간에게 부탁한 것

같은 인간의 미완성 작업을 발견한 다음 회차에는, 이 란을 읽으면 이전 회차와 같은 처리를 계속할 수 있다.

헌장에 적는 문구 형태

절차를 매번 따라 하도록 하기 위해, 이 시스템에서는 헌장(憲章)의 '한 번 실행하는 절차' 첫 번째 단계에 정리하기(片付け) 과정을 포함시켰다. 이름과 경로를 바꿔서 보여준다. 마지막 한 줄은 현재의 헌장에는 없고, 기록 처리 과정에서 추가된 것이다.

1. 상황 읽기
- 상태 파일, inbox, 각 부서의 장부 읽기
- 작업장마다 git status 보기. 커밋되지 않은 변경 사항이 남아 있다면,
...

이 절차로 할 수 없는 것들

• 완료 판정은 이전 회차의 Claude가 작성한 것을 다음 회차의 Claude가 읽고 결정한다. 끝의 기준이 모호한 업무에서는 판정도 흔들린다. 기준을 셀 수 있는 형태(챕터가 모두 갖춰짐, 계획했던 검색어를 전부 돌림)로 적어둘수록, 판정은 기계적이 된다.
• 다른 세션이 다른 작업장에서 작동하는 부서는 이 절차 밖에 있다. 이 시스템에서는 개발 부서의 미완성 작업을 시작 메커니즘이 처리하고, 버렸는지 여부를 실행 기록에 남긴다. CEO는 그 기록을 읽고, 버려졌다면 일일 보고서에 적는다.
• 추적되지 않은 깨진 파일은 사람이 삭제할 때까지 남아있다.

책 안내

이 글은 Zenn의 책 'Claude Code를 4시간마다 무인으로 돌리는 회사 만들기(템플릿 포함)'과 같은 시스템 기록을 바탕으로 작성되었다. 이 책에서는 헌장, 부서 규정, 써도 되는 장소와 커맨드 선언, 지시서, 검수 기록, 일일 보고서 등을 이름과 경로를 바꿔 쓸 수 있는 템플릿 형태로 제공한다. 제1장은 무료로 읽을 수 있다.

Discussion