[CCA-F] Claude Code in Action(2/2)

Hooks and the SDK

Introducing hooks

• Hook : 클로드가 tool 쓰기 전/후에 명령어 실행할 수 있게 함
  • 예시 1 : 코드 수정 전 Access 권한 있는지 확인
  • 예시 2 : 코드 수정하고 linter 실행, 테스트 수행, logging 등
• 종류
  • PreToolUse : tool call block 가능. 컨트롤.
  • PostToolUse : tool call 결과에 대한 추가 실행.
• Hook 설정 위치
  • global : ~/.claude/setting.json
  • project : .claude/settings.json
  • project(not commited) : .claude/settings.local.json

Defining hooks

다음의 과정을 거쳐 hook을 쓸 지 정의한다.

1. 시점 정하기 : Pre/Post
2. 어떤 tool call 에 의해 trigger 될 지 정하기
   • tool 종류 : Read, Edit, Write 등
3. tool call이 일어나면 어떤 명령어가 실행될지 정하기
   • 이 때, 실행되는 명령어는 stdin으로 json 형태의 tool call 실행 정보를 넘겨받는다.

     {
     "session_id": "2d6a1e4d-6...",
     "transcript_path": "/Users/sg/...",
     "hook_event_name": "PreToolUse",
     "tool_name": "Read",
     "tool_input": {
       "file_path": "/code/queries/.env"
     }
     }

     4. 명령어의 실행 결과(예 : exit 0, 2 등)를 클로드 코드에게 전달도 가능하다.

나는 PreToolUse는 언제 쓰나 싶어서 예시를 보니까, 클로드가 접근 가능한 파일인지 아닌지 PreToolUse에서 판단하고 되는지 안 되는지 여부를 알리는 용도로도 사용 가능하다고 한다.

hook을 settings.json에다가 이렇게 정의할 수 있다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          { "type": "command", "command": "node $PWD/hooks/read_hook.js" }
        ]
      }
    ]
  }
}

Gotchas around hooks

좀 더 안전한 hook을 사용하기 위한 지침 5가지

1. input 데이터 검증하고 정제하기
2. shell 변수는 quote(")로 감싸기
3. path 순회(traversal) 방지하기
4. 절대 경로 쓰기
5. .env나 .git, key가 담긴 파일 등 예민한 파일 접근에 주의하기

4번에 대해서는 차라리 $PWD를 쓰되, init-claude.js를 실행시킬 때 이 $PWD가 절대 경로로 대치되게끔 짤 수 있다.

Useful hooks!

여기서는 코드 수정 후 실행되는 여러 유용한 hooks을 소개한다.
query 작성 전에 duplication 유무 보는 hook의 경우 trade-off은 다음과 같다.

• 장점 : 중복을 없앨 수 있음
• 비용 : query가 담겨있을 디렉토리를 다 살펴봐야 한다.
• 추천 : query 수정 시, claude가 봐야 하는 디렉토리를 지정해서 그 디렉토리만 살피게 한다.

범용적으로 hook 만드는 아이디어 정리하기

• claude에게 피드백을 위해 linter/compiler output 사용
• code review process를 별도의 AI instance에게 맡기기
• 봐야 하는 범위(directory)를 명시할 것
• automation cost vs performance cost 비교해서 생각할 것

Another useful hook

여기서는 기존에 정의된 여러가지 hook들을 알려준다.
해당 챕터 참고

단 유의할 사항이 있다.

• hook이 실행하는 명령어에 전달되는 stdin input 형태의 json 데이터는 hook의 종류에 따라 바뀐다.
• tool_input은 어떤 tool이 hook 되는지에 따라 하위의 내용이 바뀐다.
• 그래서 post-log.json 이란 파일을 만들고, command에 어떤 json data가 들어가는지 확인할 수 있다.

        "PostToolUse": [ // Or "PreToolUse" or "Stop", etc
        {
          "matcher": "*",
          "hooks": [
            {
              "type": "command",
              "command": "jq . > post-log.json"
            }
          ]
        },
      ]

  The Claude Code SDKAgent SDK에 대해서 설명하는 부분. 클로드 코드를 내 어플리케이션에서 어떻게 코드로 쓸 수 있는지 잠깐 소개하는 파트. TS, Python, CLI를 지원한다고 되어있는데 다음 챕터(Building with the claude API)에서 SDK를 사용하는 예제가 나오니, 이런 것이 있구나 하고 알아두는 정도면 충분하다.