하나를 바꾸고, 확인하고, 안전하게 되돌리기

훅은 모델 안에서 실행되는 코드가 아닙니다. Cursor가 별도 프로그램으로 실행하고 응답을 읽습니다. 거부 메시지를 받은 모델이 다음 행동을 바꿀 수는 있지만, 훅이 문장을 이해해 새 답변을 만드는 것은 아닙니다.

라우팅도 새 모델을 만드는 기능이 아닙니다. 같은 요청에서 모델이 문서를 직접 검토할지, 프로그램이 검사하고 모델이 결과를 설명할지 처리 순서를 정하는 것입니다.

먼저 생각해 보세요. “파일을 수정하지 마세요”라는 Rule이 있는데 수정 요청이 나왔다면, 실행을 실제로 멈추는 부품은 무엇일까요?

export PROJECT_ROOT="$PWD"는 현재 터미널의 작업 경로를 셸 변수에 저장합니다. 이어지는 cd는 그 위치로 이동합니다. 이 변수가 Cursor의 프로젝트를 바꾸거나 훅을 켜지는 않습니다.

훅은 Cursor가 보낸 workspace_roots의 첫 경로를 쓰고, 없으면 실행 중인 작업 폴더를 씁니다. 반면 prepare.py는 설치된 키트의 상위 폴더를 기준으로 삼습니다. 각각 같은 실습 폴더를 가리키게 준비합니다.

먼저 생각해 보세요. 새 터미널에서 변수가 없다는 오류가 나면 키트를 다시 설치해야 할까요?

두 설치 방법이 함께 사용하는 정식 파일 목록입니다. 각 원본도 아래에서 따로 펼쳐 복사할 수 있습니다.

1. install.py가 원본을 .cursor-harness-kit/에 두고, README가 없을 때 예제를 만듭니다.
2. 다음 단계의 prepare.py s1 …가 원본을 활성 경로로 복사하고 .cursor/hooks.json에 이벤트와 실행 명령을 등록합니다.
3. 그 뒤 Cursor에서 해당 이벤트가 발생해야 훅이 실행되고 기록이 생깁니다.

다운로드와 직접 만들기는 이 페이지의 같은 파일 목록에서 만들어집니다. 설치 방법이 달라도 활성화하는 원본은 같습니다. 전체 파일 목록에서 install.py, prepare.py, files/observe.py의 역할을 구분해 보세요.

먼저 생각해 보세요. Python 파일만 .cursor/hooks/에 복사하면 자동으로 호출될까요?

.cursor/hooks/cursor-harness-lab-observe.py는 hook_event_name을 읽습니다. pre/before이면 시도, postToolUseFailure이면 실패, 나머지 등록된 post/after이면 allow로 기록합니다. 정상 실행의 끝에서는 permission: allow를 출력합니다.

도구 요청 → 실행 전 훅: attempt 기록
          → 도구 실행
          → 실행 후 훅: allow 또는 실패 이벤트의 fail 기록

lab-results/CURRENT의 s1은 기록을 넣을 폴더 이름입니다. events.jsonl에는 JSON 객체 하나를 한 줄씩 덧붙입니다. 시도 한 줄과 결과 한 줄을 서로 다른 작업 두 번으로 세면 안 됩니다.

실행 뒤 생각해 보세요. attempt만 있으면 수정 성공이라고 할 수 있나요?

1. 등록: 언제 어떤 파일을 실행하나요?

S2 준비는 .cursor/hooks.json의 preToolUse에 기록 훅 다음으로 python3 .cursor/hooks/cursor-harness-lab-deny-write.py를 등록합니다. failClosed: true도 이 항목에 붙습니다. 파일이 존재해서가 아니라 실행 전 이벤트에 등록되어서 호출됩니다.

2. 입력: Cursor가 무엇을 보내나요?

{
  "hook_event_name": "preToolUse",
  "tool_name": "StrReplace",
  "workspace_roots": ["/project"],
  "tool_input": {"file_path": "README.md"}
}

Cursor가 별도 Python 프로세스의 표준입력(stdin)에 JSON을 보냅니다. 활성 파일의 payload = json.load(sys.stdin)이 이를 읽고, tool = payload.get("tool_name", "")이 도구 이름을 꺼냅니다.

3. 조건: 어느 줄이 차단을 결정하나요?

if tool not in {"Write", "StrReplace", "Delete", "EditNotebook"}:
    print(json.dumps({"permission": "allow"}, ensure_ascii=False))
    raise SystemExit(0)

not in은 “목록에 없으면”입니다. Read는 이 분기에 들어가 allow를 출력하고 즉시 끝납니다. StrReplace는 목록에 있으므로 이 분기를 건너뛰고, 로그 기록 부분을 지난 뒤 마지막의 permission: deny 출력에 도달합니다. 이름은 대소문자까지 정확히 비교합니다.

4. 출력: return이 없어도 응답이 되나요?

Cursor
  └─ stdin: 요청 JSON → Python 훅
                         └─ stdout: {"permission": "deny"}
  ← 응답 JSON을 읽고 permission 확인
  └─ StrReplace 실행 차단

일반 함수의 return은 같은 Python 프로그램의 호출자에게 값을 돌려줍니다. Cursor는 별도 프로세스의 Python 반환값을 직접 받을 수 없으므로 표준출력(stdout)을 읽습니다. json.dumps()가 사전을 JSON 문자열로 만들고, print()가 그 문자열을 stdout에 씁니다.

허용 분기의 SystemExit(0)은 아래의 거부 출력까지 내려가지 않게 합니다. 거부 분기는 파일 끝에 도달하며 정상 종료하므로 종료 코드가 0이어도 deny일 수 있습니다. 디버깅 문장을 stdout에 섞으면 응답 파싱을 깨뜨릴 수 있으니 print("진단 내용", file=sys.stderr)처럼 표준에러(stderr)를 사용합니다.

5. 기록과 차단은 같은 일인가요?

CURRENT가 없으면 로그는 남기지 않지만 정상 실행에서는 여전히 deny를 출력합니다. 다만 현재 코드는 로그 쓰기 오류를 잡지 않습니다. 기록 중 예외가 나면 마지막 출력에 도달하지 못하고, 이때는 failClosed가 실패 시 처리를 맡습니다. reason=deny-write는 기록의 이유이고, Cursor가 읽는 결정은 stdout의 permission입니다.

같은 요청을 비교할 때: S2 준비는 S1에서 바뀐 README를 초기화하지 않습니다. 이미 추가된 줄을 보고 Agent가 수정 요청을 하지 않았다면 거부를 관찰한 것이 아닙니다. 실제 도구 기록을 확인하고, 조건 자체는 다음 직접 편집 장의 probe로 따로 확인하세요.

먼저 생각해 보세요. 파일 경로를 README.md에서 notes.md로 바꾸면 StrReplace가 허용될까요?

.cursor-harness-kit/files/probe.py는 subprocess.run()으로 활성 훅을 실행합니다. 두 도구 요청을 각각 stdin으로 보내고 stdout을 json.loads()로 해석합니다. 모델이 우연히 원하는 도구를 골라 주기를 기다리지 않습니다.

이 점검은 훅 조건의 입력→출력을 확인합니다. Cursor의 훅 등록이나 실제 파일 수정까지 검증하지는 않습니다. 그래서 target_created: false가 기대값입니다.

보고서는 custom 폴더에 따로 생기지만, 거부된 점검 요청은 현재 CURRENT=s2의 이벤트 로그에도 추가됩니다. 이때 생긴 StrReplace deny를 실제 Agent의 시도와 섞어 해석하지 마세요.

고치기 전에 예상해 보세요. 원본 키트만 고치고 활성 복사본을 그대로 두면 probe의 결과가 바뀔까요?

.cursor-harness-kit/manage.py의 disable은 실습 파일과 등록 항목을 백업한 뒤 실습 소유 항목만 제거합니다. registered_hook_entries: 0은 실습 훅 등록 수이며 사용자 훅 전체가 꺼졌다는 뜻은 아닙니다.

restore는 끄기 직전 상태를 돌려놓습니다. prepare는 키트 원본의 시나리오 상태를 새로 준비합니다. 어느 시점의 상태를 원하는지에 따라 선택합니다.

실행 전에 예상해 보세요. Write를 허용하도록 고친 뒤 disable→restore를 하면 Write는 무엇이 될까요?

prepare.py는 S3~S5에서 git rev-parse 또는 svn info가 성공하는지 확인하고 commit-input.txt를 바꿔 커밋할 재료를 만듭니다. 준비가 커밋을 실행하지는 않습니다.

Agent의 셸 요청은 beforeShellExecution과 실행 후 afterShellExecution에서 기록됩니다. 이 랩의 관찰 코드는 후자에 allow를 붙일 뿐 셸 종료 코드를 해석하지 않습니다.

실행 뒤 생각해 보세요. “nothing to commit”이라는 도구 결과와 allow가 함께 보이면 모순일까요?

추가 또는 메시지 조건을 직접 설계하고 별도 결과 이름을 쓰세요. 본편 프롬프트 B는 사용하지 않습니다.

.cursor/hooks/cursor-harness-lab-deny-commit.py는 beforeShellExecution에서 command와 lab-results/vcs.txt를 읽습니다. lab-results/cursor_harness_lab_shell.py의 analyze(command, vcs)가 요청 전체를 분석하고, 훅이 그 결과를 permission: allow / deny로 바꿉니다. 분석기는 명령을 실행하지 않습니다.

문자열 안의 commit만 찾으면 안 됩니다. git commit -m "lab"은 커밋이지만 echo "git commit"은 출력할 글자이고, git add commit의 commit은 파일 이름입니다. 따옴표·주석·이스케이프를 구분한 뒤 실행 파일과 옵션, 하위 명령을 확인합니다.

입력: git add -A && git commit -m x
분석: 첫 명령은 add, 두 번째 명령은 commit
판단: 선택한 Git의 커밋 발견 → reason=deny-commit
응답: {"permission": "deny"}
결과: 요청 전체가 실행되지 않음. 앞의 add도 실행되지 않음.

지원 범위는 값이 정해진 단순 명령과 &&, ||, ;, |, &, 줄바꿈 연결입니다. 연결된 명령을 모두 검사하므로 뒤에 커밋이 있어도 거부합니다. env LAB=1 git commit, command git commit 같은 지원하는 래퍼도 검사하며, SVN에서는 commit과 같은 동작인 ci를 함께 막습니다.

중첩 셸(bash -c 등), 변수·명령 치환, 제어문, 리다이렉션, 따옴표 밖의 와일드카드 등 미지원 구문은 deny-unsupported-shell로 거부합니다. sudo·xargs 같은 미지원 실행 래퍼, Python·Node 실행 요청, 목록에 없는 VCS 하위 명령·앞쪽 옵션도 같은 분기입니다. 따라서 S4에서는 커밋 없는 테스트 실행도 거부될 수 있습니다. 이 제한은 S4 정책이 켜진 동안 적용됩니다.

닫히지 않은 따옴표 등 잘못된 구문은 deny-invalid-shell로 거부합니다. 두 구문 거부 모두 커밋을 발견했다고 기록하지 않고 command_family=unknown으로 남깁니다. 지원하는 단순 명령으로 표현할 수 있다면 나누어 요청하고, 다른 실행 경로가 필요한 작업이라면 실습 훅 끄기에서 정책을 의도적으로 해제합니다.

failClosed: true는 Python 실행 오류처럼 훅이 판단을 끝내지 못할 때를 맡습니다. 반면 위 구문 거부는 훅이 정상 종료하면서 deny를 반환한 결과입니다. 둘 다 실행을 막지만 이유가 다릅니다.

이 실습의 경계. Cursor Agent의 셸 요청을 검사하는 훅이며, 사람이 터미널에서 직접 실행하는 명령 전체를 막는 장치는 아닙니다. 스크립트·외부 프로그램·별칭·Git 설정 안쪽의 동작까지 실행해 추적하지 않습니다. OS 샌드박스나 저장소 권한 격리를 대신하지 않습니다. git add와 git push 전체를 금지하는 정책으로 바꾼 것도 아닙니다.

먼저 예상해 보세요. Git 선택 상태에서 git status && git diff와 git status && git commit -m x는 어떻게 다를까요?

JSONL은 한 줄에 JSON 객체 하나가 든 형식입니다. json.loads(line)으로 읽고 outcome을 비교하면 거부 기록만 골라낼 수 있습니다. 앞서 실행한 명령은 이 필터를 수행하며 정책이나 기록은 바꾸지 않습니다.

원본을 event → phase → tool/command → outcome → reason 순으로 읽으세요. 같은 Shell 요청이 일반 도구 훅과 셸 훅에 모두 보일 수 있어 로그 줄 수를 곧바로 작업 수로 볼 수는 없습니다.

먼저 생각해 보세요. attempt 뒤에 deny가 있으면 도구가 실행된 뒤 취소된 것일까요?

도구 한 번의 거부는 대화 전체의 종료가 아닙니다. 모델은 거부 응답 뒤 다른 도구를 요청할 수 있습니다. 앞서 읽은 예제는 Write 거부 뒤 Shell 요청으로 이어집니다. deny-write가 검사하지 않는 경로입니다.

세션과 훅 로그에서 같은 도구·명령·파일 경로와 주변 순서를 맞춰 보세요. 이 랩에는 공통 호출 ID가 없으므로 같은 시각이라는 이유만으로 같은 호출이라 단정하지 않습니다. 생략된 부분 때문에 연결할 수 없다면 그것도 표시합니다.

분석 전에 생각해 보세요. Write 거부 한 줄로 “README는 바뀌지 않았다”고 결론낼 수 있을까요?

규칙 문구와 직접 만든 입력을 바꿔 별도 결과로 비교하세요.

.cursor/rules/cursor-harness-lab-no-commit.mdc는 alwaysApply: true인 프로젝트 지시입니다. prepare.py는 S5에서 이 파일을 넣고 커밋 거부 훅 등록을 뺍니다. 모델이 읽는 지시는 Python 조건문 같은 강제 분기가 아닙니다.

S5: Rule → 모델이 커밋을 요청하지 않음 → 커밋 시도 없음
S4: 커밋 요청 → 훅이 deny 응답 → 실행 전 차단

실행 뒤 생각해 보세요. S5 로그에 커밋 시도가 없으면 “훅이 막았다”고 써도 될까요?

lab-results/route_summary.py는 문서 Read와 프로그램 실행 기록을 구분합니다. direct_document_read는 직접 Read의 근거이지 답변 품질 점수가 아닙니다.

document-before.sha256는 실행 전 문서 바이트로 계산한 지문입니다. 실행 뒤 지문과 같으면 시작과 끝의 문서가 같습니다. 읽지 않았다는 뜻도, 중간에 바꿨다가 되돌리지 않았다는 증거도 아닙니다.

먼저 예상해 보세요. R1과 R2가 같은 문제 세 가지를 답하면 라우팅도 같다고 볼 수 있나요?

1. .cursor/rules/cursor-harness-lab-review-route.mdc가 프로그램 명령과 보고서 경로를 알려 줍니다.
2. lab-results/review_doc.py가 문서를 줄 단위로 읽어 Markdown 제목과 아래 내용을 나눕니다.
3. REQUIRED_HEADINGS로 누락을 찾고, Counter(headings)로 중복을 세며, 제목 아래 내용이 비었는지 검사합니다.
4. findings와 실행 정보인 route_receipt를 JSON 파일로 씁니다. 모델은 원문 대신 이 결과를 읽습니다.

프로그램은 AI를 호출하지 않습니다. 정해진 형식 검사는 반복하기 좋지만 문장의 설득력이나 사실관계까지 평가하지는 않습니다. 실행 영수증도 위조 불가능한 서명이 아니라 프로그램이 적은 정보입니다. 요약은 셸 실행·보고서·보고서 Read를 함께 확인합니다.

route-matched는 요약기가 확인하는 조건을 만족했다는 뜻입니다. 호출 순서나 추가 Grep·Glob까지 모두 검사하지는 않습니다. 정확한 순서가 궁금하면 원본 로그와 세션을 함께 읽으세요.

실행 뒤 생각해 보세요. 보고서는 있지만 Agent가 읽은 기록이 없다면 기대 경로를 마친 것일까요?

.cursor/hooks/cursor-harness-lab-route-policy.py는 allowed = False에서 시작합니다. Shell이면 command == APPROVED_COMMAND, Read이면 경로가 정확히 lab-results/r3/review-report.json인지 확인합니다. 조건에 맞을 때만 allow로 바뀝니다.

훅이 보는 것은 Cursor의 도구 요청입니다. 승인된 Python이 내부에서 문서를 여는 것은 별도의 Cursor Read 요청이 아닙니다. 프로그램은 원문을 읽고 모델에는 보고서만 읽게 역할을 나눕니다. 그래서 승인 프로그램 자체도 확인해야 합니다.

명령은 문자열을 정확히 비교합니다. 앞에 cd를 붙이거나 뒤에 다른 명령을 연결하면 거부됩니다. 파일 경로는 resolve()로 프로젝트 기준 절대 경로를 맞춰 비교합니다.

실행 뒤 생각해 보세요. 앞서 실행한 자체 점검에서 deny가 나오면 Agent도 금지된 Read를 시도했다고 볼 수 있나요?

SKILL.md 머리말의 name과 description은 이름과 용도를 알려 줍니다. disable-model-invocation: true로 정해 사용자가 /lab-document-review를 직접 불러옵니다. 본문은 프로그램 실행→보고서 읽기→설명을 지시합니다.

슬래시 호출은 지시를 불러오는 시작점입니다. 실제 Python 실행은 그 지시를 따른 Agent의 Shell 요청이며 활성 훅이 있으면 똑같이 검사받습니다. Skill이 R3의 제한을 건너뛰지는 않습니다.

여기서는 R2의 Rule도 함께 둡니다. 결과만으로 Skill 때문에 경로가 바뀌었다고 판정하지 않습니다. 이 장에서는 재사용 절차를 직접 불러오고 실제 실행 근거를 확인하는 방법을 익힙니다.

이 장의 준비 명령처럼 R2에서 시작하세요. R3를 유지하면 Skill의 준비 상태 확인을 위해 CURRENT를 직접 Read하는 요청도 거부됩니다. R3에서는 정확한 승인 프로그램이 내부에서 CURRENT를 확인한다는 점을 구분해야 합니다.

먼저 생각해 보세요. Skill에 “모든 도구를 허용한다”고 적으면 훅의 deny가 풀릴까요?

deny-write는 CURRENT가 없으면 기록을 건너뛰고 정상적으로 deny를 출력합니다. 이 정책 하나에는 결과 폴더가 필수가 아닙니다. 복사한 훅의 메시지에 lab-results를 보라는 문구가 있어도 이 프로젝트에는 로그가 없을 수 있습니다. 반면 R3는 CURRENT=r3와 정확한 프로그램·보고서 경로를 전제로 하므로 같은 방식으로 옮기면 안 됩니다.

S4의 커밋 거부를 옮길 때는 조건이 다릅니다. 커밋 훅과 함께 lab-results/cursor_harness_lab_shell.py도 같은 상대 경로에 필요합니다. SVN을 선택하려면 lab-results/vcs.txt도 옮깁니다. 기록용 CURRENT가 없어도 거부는 동작하지만, 공통 모듈이 없으면 정상 판단이 아니라 훅 실행 오류가 됩니다.

앞서 실행한 로컬 점검은 응답만 확인합니다. hooks.json 연결은 새 Cursor 대화에서 작은 읽기·수정 요청을 보내 도구 결과까지 확인해야 합니다. 새 프로젝트 터미널에서는 그 폴더에서 PROJECT_ROOT도 다시 설정하세요.

옮기기 전에 설명해 보세요. 언제 실행하는가, 무엇을 검사하는가, 오류 나면 어떻게 하는가는 각각 어디에 있나요?

로그가 없다는 것만으로는 판단할 수 없습니다. 등록이 없거나 다른 프로젝트·시나리오에 기록됐거나 기록 전에 오류가 났을 수 있습니다. failClosed가 true이면 정상 deny 로그 없이도 훅 오류로 차단될 수 있습니다.

1. manage.py status와 hooks.json으로 호출 연결을 봅니다.
2. 활성 파일, CURRENT, 실제 도구 이름을 확인합니다.
3. 훅 오류와 stdout의 JSON 형식을 봅니다. 진단 문장은 stderr로 보냅니다.
4. 조건이 의심되면 직접 편집 장의 probe로 같은 입력을 비교합니다.

먼저 생각해 보세요. probe는 맞는데 Cursor에서 다르게 보이면 어디부터 볼까요?

1. Write는 허용하고 StrReplace는 거부하고 싶습니다. 무엇을 바꿀까요?
2. 프로그램을 먼저 쓰도록 안내하되 다른 경로는 허용하고 싶습니다. 무엇을 쓸까요?
3. 프로그램 보고서만 읽게 강제하고 싶습니다. 무엇을 더할까요?
4. deny를 출력한 훅의 종료 코드가 0입니다. 오류일까요?

막히는 질문은 훅의 입력과 응답, Rule과 거부의 차이, 검사 프로그램, 허용 경로로 돌아가 실제 파일에서 근거를 찾아보세요.