AI 1. Claude Code 에 한 세션 한 작업만 시키기: 작업 게이트와 PreToolUse 훅으로 수정 범위 막기

AI 코딩 도구와 오래 작업하다 보면 두 가지가 문제가 됩니다. 하나는 한 세션이 길어지면서 토큰을 많이 쓰고 앞의 결정을 잊는 것, 다른 하나는 부탁하지 않은 파일까지 “개선” 하는 것입니다. 연습용 프로젝트면 웃고 넘기는데, 코인 선물 자동매매 봇이나 연금 계좌 점검 시스템처럼 실제 돈이 걸린 저장소에서는 곤란합니다.

그래서 그 두 저장소에는 작업 게이트를 두었습니다. 파이썬 스크립트 하나(tools/gate.py)와 Claude Code 훅 두 개로 되어 있습니다.

작업은 tasks/tasks.json 에 카드로 적습니다. 카드마다 맡길 모델과 추론도, 선행 작업, 사람이 할 일, 목표와 산출물, 완료 조건을 확인하는 스크립트, 그리고 수정해도 되는 경로(scope)가 있습니다.

규칙은 CLAUDE.md 에 이렇게 적었습니다.

• 세션을 시작하면 지금 작업 카드를 보여 준다.
• 한 세션에 작업 하나. 작업 시작은 사용자가 요청했을 때만.
• 카드의 수정 허용 경로 밖은 고치지 않는다. 넓혀야 하면 멈추고 묻는다.
• 끝나면 완료 조건 스크립트를 통과해야 완료로 바꿀 수 있다. 사용자 확인이 필요한 작업은 사용자가 실제로 남긴 문장을 그대로 넣는다. 문구를 지어내지 않는다.
• 완료한 세션에서 다음 작업을 시작하지 않는다.

규칙만 적어 두면 지켜지지 않을 때가 있어서 훅으로 강제했습니다.

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command",
      "command": "python \"$CLAUDE_PROJECT_DIR/tools/gate.py\" brief --session-start" }] }],
    "PreToolUse": [{ "matcher": "Edit|Write|MultiEdit|NotebookEdit",
      "hooks": [{ "type": "command",
        "command": "python \"$CLAUDE_PROJECT_DIR/tools/gate.py\" guard" }] }]
  }
}

SessionStart 훅은 세션이 열릴 때 지금 작업 카드를 출력합니다. 매번 “지금 뭐 하는 중이었지” 를 설명하지 않아도 됩니다.

PreToolUse 훅은 파일을 고치는 도구가 불릴 때마다 guard 를 실행합니다. 훅은 표준입력으로 도구 입력을 받으니 file_path 를 꺼내서, 프로젝트 밖(메모리나 임시 폴더)이면 통과, 프로젝트 안이면 지금 작업의 scope 와 항상 허용되는 경로에 맞는지 봅니다. 안 맞으면 이유를 표준에러로 쓰고 종료 코드 2 로 끝냅니다. Claude Code 는 종료 코드 2 를 “막음” 으로 받아서 그 수정을 하지 않고, 메시지를 모델에게 보여 줍니다. 메시지는 이런 모양입니다(경로와 작업 번호는 예시).

차단: core/signal.py 는 현재 TASK T05 의 수정 허용 경로(services/trader/**, tests/trader/**) 밖입니다.
범위를 넓혀야 하면 작업을 멈추고 사용자에게 먼저 물어보세요.

진행 중인 작업이 없으면 프로젝트 안 파일은 전부 막힙니다. 작업을 시작해야만 고칠 수 있습니다.

완료는 gate.py done 이 완료 조건 스크립트를 돌려서 통과해야만 됩니다. 완료하면 다음 세션을 새로 열어야 다음 작업을 시작할 수 있게 상태 파일에 표시해 둡니다.

빈틈도 있습니다. 훅이 보는 건 파일 편집 도구뿐이라 셸 명령으로 파일을 쓰면 막지 못합니다. 그래서 CLAUDE.md 에 “Bash 로 우회해 파일을 쓰지 않는다” 를 따로 적어 두었는데, 이건 규칙일 뿐 강제는 아닙니다.

그래도 쓰는 입장에서는 마음이 편해졌습니다. 세션이 짧아지고, 작업 카드에 맡길 모델이 적혀 있으니 쉬운 작업에 비싼 모델을 쓸 일도 줄었습니다. 무엇보다 바뀐 파일이 작업 카드의 범위 안에 있다는 걸 믿고 볼 수 있습니다. 모델 배분은 다음 글에 따로 적었습니다.

참고: Claude Code hooks, https://docs.claude.com/en/docs/claude-code/hooks