Claude Code 코드품질 자동화

구문 에러 루프·에러 무시·DoD 부재를 한 번에

Safety Guards 다음 과제: 코드 품질을 자동으로 지키는 구조

앞 장에서 Safety Guards로 파일 삭제·API 키 유출·잘못된 push를 막았다.

그러나 Safety Guards만으로는 충분하지 않다.

코드가 실행은 되지만 망가진 상태일 때, 혹은 Claude Code가 작업 완료를 잘못 판단했을 때 발생하는 문제들이 여전히 남아 있다. 이번에는 그 부분을 다루는 4가지 체크가 그 틈을 메운다.

체크 5: 파일 편집 직후 구문 체크를 자동 실행한다

어떤 일이 벌어졌나

Python 파일을 수정한 직후 테스트를 실행했다.

SyntaxError로 실패했다. Claude Code는 "에러를 수정하겠습니다"라고 말하며 파일을 다시 편집했다.

그 편집에서도 구문 에러가 생겼다. 테스트 실패 → 수정 시도 → 새 구문 에러 → 테스트 실패의 사이클이

10회 반복됐다.

왜 이런 일이 반복되나

Claude Code는 파일을 편집한 뒤 즉시 구문이 올바른지 확인하지 않는다. 실행 결과가 돌아와야 비로소 에러를 인지한다. 즉, 에러를 발견하는 타이밍이 항상 한 박자 늦다.

PostToolUse hook으로 편집이 완료되는 순간 구문을 검사하면, 이 지연을 없앨 수 있다.

해결책: syntax-check.sh를 PostToolUse에 등록

1단계. hook 스크립트를 배치한다.

---

curl -o ~/.claude/hooks/syntax-check.sh \

https://raw.githubusercontent.com/gaebalai/claude-code-hooks/main/hooks/syntax-check.sh

chmod +x ~/.claude/hooks/syntax-check.sh

---

2단계. ~/.claude/settings.json에 PostToolUse hook을 추가한다.

---

{

"hooks": {

"PreToolUse": [

{

"matcher": "Bash",

"hooks": [

{ "type": "command", "command": "bash ~/.claude/hooks/branch-guard.sh" },

{ "type": "command", "command": "bash ~/.claude/hooks/error-gate.sh" }

]

}

],

"PostToolUse": [

{

"matcher": "Edit|Write",

"hooks": [

{

"type": "command",

"command": "bash ~/.claude/hooks/syntax-check.sh"

}

]

}

]

}

}

---

3단계. hook이 지원하는 언어와 검사 방식을 확인한다.

※ 한국 개발 환경 참고: Django, FastAPI 등 Python 기반 백엔드를 사용하는 경우 python3 -m py_compile만으로는 임포트 오류를 잡지 못한다. 중요한 파일은 python3 -c "import 모듈명" 형태로 추가 검사를 CLAUDE.md에 명시해 두는 것을 권장한다. Next.js·NestJS를 사용하는 경우 tsc --noEmit을 PostToolUse hook에 추가하면 타입 오류까지 즉시 감지할 수 있다.

hook을 추가한 뒤부터 구문 에러 루프가 현저히 줄었다. Claude Code가 편집 직후 에러를 인지하고 같은 세션 안에서 즉시 수정하기 때문이다.

체크 6: bash 명령 출력에서 에러를 자동으로 감지·기록한다

어떤 일이 벌어졌나

---

npm install

---

이 명령이 ENOENT 에러로 실패했다. 하지만 Claude Code는 실패를 인지하지 못하고 이후 작업을 계속 진행했다. 의존성이 설치되지 않은 상태에서 빌드 명령이 실행됐고, 연쇄적으로 에러가 발생했다.

왜 이런 일이 생기나

Claude Code는 명령의 exit code를 항상 꼼꼼히 확인하지 않는다. 출력 텍스트가 길거나 에러 메시지가 출력의 중간에 묻혀 있으면 놓치는 경우가 있다.

별도의 로그 수집 구조를 두면, CC의 인지 여부와 무관하게 에러를 빠짐없이 기록하고 추적할 수 있다.

해결책: activity-logger.sh로 모든 bash 실행을 JSONL에 기록

1단계. hook 스크립트를 배치한다.

---