AI 코딩 에이전트에게 규칙을 알려 줬는데도 어깁니다. 어떻게 해야 못 어기게 할 수 있을까요?
답부터 적습니다. 규칙을 문서가 아니라 커밋 단계에 둡니다. 문서에 적은 규칙은 부탁이라서 지킬지 말지를 에이전트가 정합니다. .git/hooks/pre-commit 이 커밋을 거부하면 어떤 에이전트도, 사람도 그 규칙을 지나치지 못합니다. 그렇게 만든 도구가 agents-scaffold 입니다.
다만 게이트도 코드라서 틀립니다. 2026-11-18 에 빈 저장소에 새로 깔아 다시 시험했습니다. 막아야 할 것 가운데 일부는 통과했고, 막지 말아야 할 커밋 하나는 막혔습니다. 아래 수치는 모두 그날 직접 잰 값입니다.
그림으로 줄이면 이렇습니다. 커밋 문 앞의 검문 로봇은 .env 상자를 막습니다. 그래도 담장에는 --no-verify 쪽문이 있어서, 그 뒤에 CI 검문소를 하나 더 둡니다.
에이전트는 문서의 규칙을 지나칩니다
Claude Code 같은 에이전트를 매일 쓰면 같은 문제를 되풀이해서 만납니다.
- 어제 세션에서 알려 준 규칙을 오늘 세션은 모릅니다.
- 에이전트가
.env파일을 커밋합니다. - 타입 오류가 남은 채로 커밋이 올라갑니다.
- 팀원마다
CLAUDE.md가 달라서 같은 프로젝트인데 결과가 다릅니다.
규칙을 잘 써 두어도 문서 안에만 있으면 언젠가 지나칩니다. 그래서 agents-scaffold 는 규칙을 설명으로 두지 않고 커밋을 막는 게이트로 만듭니다.
강제하는 자리는 에이전트 밖이어야 합니다
처음 판은 이렇지 않았습니다. 2026-08-22 전까지 기본 설치(Claude Code 용)는 런타임의 훅에만 기댔습니다. .claude/settings.json 의 PreToolUse 훅(hook, 도구를 쓰기 직전에 런타임이 부르는 스크립트)입니다. 이 훅은 Claude Code 세션이 셸 도구로 git commit 을 부를 때만 돕니다. 사람이 터미널에서 커밋하거나 다른 에이전트가 커밋하면 게이트가 걸리지 않았습니다.
같은 날 커밋 b8dc378 이 이 구조를 바꿨습니다. 커밋 메시지의 결론은 한 줄입니다. “결정적 강제선은 하네스 밖(.git/hooks + CI)에 두고 하네스 훅은 조기 피드백으로 남긴다.” 지금은 어떤 옵션으로 깔아도 git 훅이 연결됩니다. 그 훅은 두 줄입니다.
#!/usr/bin/env bash
exec "$(git rev-parse --show-toplevel)/.claude/hooks/pre-commit.sh"
검사 본문은 저장소에 커밋되는 pre-commit.sh 하나입니다. Claude Code 의 훅도, Codex·Antigravity 용으로 생성한 훅도, git 훅도 모두 이 파일을 부릅니다. 자리마다 놓치는 것을 나란히 놓으면 이렇습니다.
| 강제하는 자리 | 언제 도나 | 놓치는 것 |
|---|---|---|
AGENTS.md 의 문장 | 에이전트가 읽고 따를 때 | 따르지 않은 경우 전부 |
| 에이전트 런타임의 훅 | 그 런타임이 커밋할 때 | 사람과 다른 에이전트의 커밋 |
.git/hooks/pre-commit | 누가 커밋하든 | git commit --no-verify |
| CI | 푸시와 MR 마다 | 사용자가 직접 설치해야 한다 |
런타임마다 다른 훅 형식은 에이전트 세 종류에 같은 ‘작업자 확인 문’을 단 글에 따로 정리했습니다.
설치는 명령 한 줄이고, 파일 255개가 생깁니다
curl -fsSL https://raw.githubusercontent.com/leeyudok/agents-scaffold/main/bin/agents-scaffold.sh | bash -s -- --stack nextjs --yes
Python 스택으로 빈 저장소에 깔아 보니 2.8초가 걸렸습니다. 커밋할 파일은 255개였습니다. AGENTS.md, 경로별 규칙 6개, 스킬 24개, 서브에이전트 19개, 커밋 게이트가 들어갑니다. README 는 한국어 설치를 “대략 190개"로 적고 있어서 실제와 다릅니다.
이 명령은 그 순간의 main 을 받아 실행합니다. README 가 버전 고정용으로 적은 v1.0.0 태그는 아직 없고, 그 주소는 404 를 돌려줍니다(2026-11-18 확인). 버전을 고정하려면 직접 검토한 커밋 SHA 를 주소에 넣습니다.
시험 1 — .env 는 막지만 이름이 다르면 통과합니다
커밋을 네 가지로 시도했습니다.
| 시도 | 결과 |
|---|---|
.env 에 비밀번호를 넣고 git add -f 로 커밋 | 차단 |
값이 빈 견본 .env.example 커밋 | 차단 |
같은 비밀번호를 config.env 에 넣어 커밋 | 통과 |
.env 를 --no-verify 로 커밋 | 통과 |
$ echo 'DB_PASSWORD=hunter2' > .env
$ git add -f .env app.py && git commit -m "feat: add config"
Blocked: a .env-type file is staged. Commit is not allowed.
게이트는 파일 이름 규칙 (^|/)\.env($|\.) 만 봅니다. 내용은 보지 않습니다. 그래서 흔히 커밋하는 견본 파일은 막고, 이름만 다른 비밀 파일은 통과시킵니다. 이 검사는 실수를 줄이는 장치입니다. 비밀 값을 찾아내는 탐지기가 아닙니다.
시험 2 — 린트 도구가 없으면 검사를 건너뜁니다
Python 스택의 게이트는 ruff 와 mypy 를 돌립니다. 시험한 맥에는 ruff 가 없었습니다. 그래서 쓰지 않는 import 가 든 파일도 그대로 커밋됐습니다. 게이트는 이렇게만 알렸습니다.
pre-commit: ruff not installed — skipping lint
pre-commit: passed
의도한 동작입니다. 2026-11-10 커밋 deeb4a0 이 Go·Rust·Flutter·Next.js 게이트를 고쳤습니다. 그전에는 도구가 없는 것을 빌드 실패로 읽어 커밋을 막았습니다. 도구가 없는 PC 에서 모든 커밋이 막히는 것보다는 낫습니다. 대신 그 PC 에서 이 게이트는 .env 만 보는 게이트가 됩니다.
시험 3 — ruff 를 깔자 게이트가 스스로 깐 파일에 걸렸습니다
프로젝트 가상환경에 ruff 0.17.5 를 깔았습니다. 그리고 린트를 통과한 app.py 하나만 커밋했습니다. 그런데도 막혔습니다.
Found 139 errors.
Blocked: ruff check failed. Run 'ruff check --fix .' before committing.
139건은 모두 스캐폴드가 깔아 준 파일에서 나왔습니다. 스킬 폴더 124건, 훅 10건, 보조 스크립트 5건이고 내 코드는 0건입니다. 게이트가 스테이징한 파일이 아니라 ruff check . 로 저장소 전체를 보기 때문입니다. ruff 의 예전 기본 규칙(E4·E7·E9·F)만 켜도 25건이 남습니다. ruff 설정이 없는 새 저장소라면 ruff 를 까는 순간 모든 커밋이 막힙니다.
게이트 테스트가 이 문제를 못 잡은 이유도 보입니다. 스택 게이트 테스트(8d10086)는 가짜 도구 바이너리로 차단과 통과 분기만 확인합니다. 진짜 ruff 가 스캐폴드의 파일을 읽는 경우는 시험하지 않습니다. 2026-11-18 현재 이 문제는 고쳐지지 않았습니다.
게이트가 있다고 막는 것은 아니었습니다
지난 기록에서도 같은 종류의 일이 두 번 있었습니다.
첫째, Python 게이트의 mypy 검사는 결과를 | tail -5 || true 로 삼켰습니다. 타입 오류가 있어도 종료 코드가 늘 0 이라서 한 번도 커밋을 막지 못했습니다. 첫 커밋(2026-08-16)부터 deeb4a0(2026-11-10)까지 86일 동안 그랬습니다. 옛 글은 “타입 오류가 남은 채로 올라가는 커밋"을 막는 예로 들었지만, Python 에서는 막지 못하고 있었습니다.
둘째, 옛 글은 “인지 복잡도가 15를 넘는 함수는 경고한다"고 적었습니다. 검사 스크립트 cc-check.py 도 있고 단위 테스트도 있습니다. 그런데 이 스크립트는 settings.json 에 한 번도 연결된 적이 없습니다. 내부 구조 문서는 “PostToolUse(Bash, git commit) → CC > 15 경고"라고 적고 있습니다. 문서에만 있는 경고였습니다. 지침이 코드보다 먼저 낡는다는 글에서 다룬 것과 같은 종류의 어긋남입니다.
해석은 이렇습니다. 게이트는 규칙을 강제하지만, 게이트 자신의 동작은 아무도 강제하지 않습니다. 게이트가 무엇을 막는지는 문서가 아니라 실제로 커밋을 시도해서 확인해야 합니다.
문서 규칙은 여전히 출발점입니다
게이트가 모든 규칙을 맡지는 않습니다. 설치하면 에이전트는 규칙을 읽고 시작합니다. AGENTS.md 하나를 Claude Code·Codex·Antigravity 가 모두 직접 읽습니다. 런타임 고유 기능까지 실측으로 확인한 full 등급은 Claude Code 하나입니다. Codex 와 Antigravity 는 baseline 등급입니다. 2026-11-04 에 Claude Code 2.1.318, codex-cli 0.166.0, agy 1.5.0 으로 쟀습니다.
| 장치 | 하는 일 | 강제 여부 |
|---|---|---|
| P0·P1·P2 규칙 | P0 은 시크릿 노출·파괴적 SQL·force push 처럼 예외가 없는 규칙이다 | P0 일부만 게이트와 권한 설정이 막는다 |
| 경로별 규칙 | paths: 에 맞는 파일을 읽거나 고칠 때만 실린다 | 아니다 |
| 권한 설정 | Claude Code 에서 .env 읽기·수정, rm -rf, force push 를 거부한다 | Claude Code 안에서만 |
| 기억과 자기 개선 | 실수를 스킬의 “Learned warnings” 로 옮긴다. 이 저장소에서는 스킬 7개에 32줄이 쌓였다 | 아니다 |
| worktree 격리 | 1세션 = 1worktree = 1이슈 = 1브랜치 | 아니다 |
--no-verify 뒤에는 CI 를 둡니다
로컬 훅은 git commit --no-verify 로 건너뜁니다. 시험 1 의 마지막 줄이 그 예입니다. Claude Code 의 권한 설정 기본값에도 --no-verify 를 막는 규칙은 없습니다. 스캐폴드는 CI 를 깔지 않으므로 마지막 방어선은 사용자가 둬야 합니다.
pre-commit.sh 를 CI 에서 그대로 돌리면 안 됩니다. 이 스크립트는 스테이징한 파일(git diff --cached)을 보므로 CI 에서는 볼 것이 없습니다. CI 에서는 추적 중인 파일 전체를 봅니다.
if git ls-files | grep -E '(^|/)\.env($|\.)'; then
echo "Blocked: a .env-type file is tracked." >&2; exit 1
fi
시험 저장소에서 --no-verify 로 들어간 .env 를 이 검사가 잡았습니다. 스택 검사는 CI 에 도구를 깔고 같은 명령을 돌립니다. 훅과 CI 가 잡는 것은 기계로 판정할 수 있는 실수뿐입니다. 설계가 맞는지는 여전히 사람이 봅니다.
이 판단이 틀리는 경우
- 혼자서 에이전트 하나로 작은 저장소를 다룬다면 직접 쓴
AGENTS.md로 충분합니다. 파일 255개를 들일 값이 없습니다. - 검사 한 번에 몇 분이 걸리는 스택은 게이트가 개발을 막습니다. Spring Boot 게이트가 커밋마다 테스트를 돌리지 않고 컴파일까지만 보는 이유입니다(
deeb4a0). - 에이전트가
--no-verify를 쓰기로 마음먹으면 로컬 게이트는 소용이 없습니다. CI 가 없는 저장소라면 이 글의 결론은 절반만 맞습니다.
정리
에이전트가 규칙을 못 어기게 하려면 규칙을 커밋에서 막습니다. 런타임 안의 훅은 빨리 알려 주는 용도이고, 막는 결정은 git 훅과 CI 가 합니다. 그리고 게이트도 코드라서 문서와 다르게 돌 수 있습니다.
게이트를 깐 저장소가 있다면 하나만 해 봅니다. 쓰는 린트 도구를 깐 상태에서 깨끗한 파일 하나를 커밋하고, 이어서 .env 하나를 커밋해 봅니다. 앞은 통과하고 뒤는 막혀야 맞습니다.
이 글은 2026-08-25 에 옛 블로그에 올린 글을 2026-11-18 에 다시 확인하고 고쳐 쓴 것입니다.