본문으로 건너뛰기

장시간 자율 작업 기준으로 내 하네스 재점검하기

Fri-mer

2026.10.14

장시간 자율 작업 기준으로 내 하네스 재점검하기 본문 이미지

소개

2주차 지식 공유가 든 장시간 자율 작업의 기준(상태 파일, 줄 수 제한, 종료 코드 2 hook, 위임)으로 제 저장소 8곳과 전역 설정을 명령어로 다시 재고, 1주차에 쟀던 값도 같은 명령으로 다시 재서 나란히 놓았습니다. 하네스를 만들어 놓고 한 번 점검한 뒤 얼마나 달라졌는지 확인해 보지 않은 분, 규칙은 많은데 hook으로 걸어 둔 것이 있는지 궁금한 분이 읽으면 좋겠습니다.

2주차는 새 강의 없이 참여자 사례 발표가 중심이었고, 마지막에 스터디장 개발자F 님이 지식 공유를 붙였습니다. 주제는 사람이 매번 시키지 않아도 몇 시간씩 이어지는 작업을 어떻게 낭비 없이 멈추고 다시 이어 가는가였습니다. 백로그를 JSON으로 두고 모델이 직접 읽지 못하게 막는 것, 작업 상태를 in-progress로 먼저 기록하는 것, 줄 수 제한을 hook과 git 훅에 이중으로 거는 것, 메인 에이전트는 조율만 하고 일은 하위 에이전트에 넘기는 것이 나왔습니다. 자막과 채팅에서 새 과제 안내는 확인되지 않았고, 이 스터디는 1주차부터 자유 주제여서 이번에도 과제는 따로 없었습니다.

저는 청강생입니다. 1주차 글에서 제 저장소의 검사 hook이 0개라는 것을 확인하고 다음 주 계획 다섯 가지를 적어 두었습니다. 이번 글은 그 계획이 실행됐는지, 같은 명령으로 다시 세면 값이 어떻게 달라졌는지, 그리고 2주차 기준을 제 작업에 새로 대 보면 무엇이 나오는지를 기록한 것입니다. 측정은 2026-10-13에 했습니다. 측정 대상 저장소와 설정 파일은 읽기만 했고, hook은 이 글의 작업 폴더 안에 시제품으로만 만들었습니다.


진행 방법

사용 도구: Claude Code, git, Python 3, pytest

Step 1. 2주차 기준을 항목표로

지식 공유와 사례 발표에서 명령으로 셀 수 있는 것만 골랐습니다.

기준

발표에서 나온 내용

잴 것

작업 상태

작업을 문서에 쌓았더니 문서 하나가 4,000줄을 넘어 열 때마다 컨텍스트를 채웠다. JSON으로 바꾸고 모델이 직접 읽지 못하게 hook으로 막았다

상태 문서의 줄 수, 백로그 JSON 수, 읽기를 막는 hook 수

줄 수 제한

파일당 300줄을 hook에 넣고, 우회에 대비해 git 훅에도 같은 검사를 걸었다

300줄 초과 파일, 줄 수 hook 수

종료 코드 2

hook이 종료 코드 2와 오류 메시지를 돌려주면 모델에 강제로 전달된다

시제품을 만들어 동작 확인

기계로 되는 것은 hook, 판단은 rules

린트와 빌드는 hook에, 디자인 패턴처럼 판단이 드는 것은 rules에. 그 덕에 CLAUDE.md가 150줄도 안 된다고 했다

상시 로딩 줄 수, 기계로 검사할 수 있는 규칙의 hook 연결

메인은 조율만

하위 에이전트에 일을 넘겨 메인의 컨텍스트를 아낀다

Agent 호출의 모델 지정 비율

메인 브랜치 직접 커밋 차단

메인에 실수로 푸시한 사례를 듣고, 메인에 커밋하는 동작 자체를 hook으로 막는다고 했다

메인 브랜치의 직접 커밋 수

Step 2. 1주차와 같은 명령으로 다시 재기

1주차에 쓴 스크립트(harness_audit.py)를 그대로 다시 실행했습니다. 저장소 경로는 그사이 ~/projects/hackathon/으로 바뀌어 있었습니다. 읽기 전용 규칙을 지키려고 git fetch는 하지 않았고, 1주차에 가져온 원격 추적 브랜치까지 합쳐 센 값입니다.

cd ~/projects
python3 -I harness_audit.py econ-radar VeriVar paper-production-harness paper-radar \
  paper-analysis-harness hackathon/KoreaAgenticAIhackathon hackathon/AgentForgeAI hackathon/healthcareai
wc -l ~/.claude/CLAUDE.md ~/.claude/rules/*.md | tail -1     # 720 total
grep -l '^paths:' ~/.claude/rules/*.md | wc -l                # 0

값이 달라진 네 칸 가운데 커밋 기록으로 원인을 확인할 수 있는 두 칸입니다.

  • 테스트 동반 커밋은 40/138에서 41/143이 됐습니다. 비율은 29%로 그대로입니다. 코드를 고친 커밋이 5건 늘었고 이 가운데 테스트까지 고친 것은 1건입니다. KoreaAgenticAIhackathon의 10월 9일 커밋 1건은 코드와 테스트를 같이 고쳤고, healthcareai의 10월 4일 오후부터 5일 새벽까지의 코드 커밋 4건은 테스트 파일이 없었습니다.

  • 300줄을 넘는 파일은 48개에서 49개가 됐습니다. healthcareai에 10월 5일 00시 56분 새로 들어온 fill_hwpx.py가 314줄입니다. 새 파일이 처음부터 300줄을 넘은 경우입니다.

  • 나머지 두 칸(전역 CLAUDE.md와 상시 로딩 줄 수)은 Step 3에서 따로 확인합니다. 표의 다른 여섯 줄(검사 hook, paths rules, 테스트 저장소 수, 린트 설정, 읽기 전용 리뷰어, 백로그 JSON)은 1주차와 같았습니다.

Step 3. 상시 로딩 줄 수 다시 재기

1주차에 environment.md를 rules/ 밖으로 옮겨 673줄을 512줄로 줄였습니다. 같은 명령으로 다시 세면 720줄입니다.

세션마다 먼저 읽히는 전역 지침의 줄 수. 10월 4일 673줄, 10월 6일 이동 뒤 512줄, 10월 13일 720줄. 강의가 권한 200줄 선을 세 시점 모두 넘는다

늘어난 208줄 가운데 확인된 것은 새 규칙 파일 두 개(agent-routing.md 15줄, knowledge-wiki.md 60줄)와 CLAUDE.md의 9줄입니다. 나머지 124줄은 기존 규칙 파일이 길어진 것으로 보이며, 10월 6일 시점의 사본이 없어서 어느 파일에서 늘었는지는 확정하지 못했습니다. 수정 시각으로는 writing-style.md와 work-discipline.md(10월 11일), headings.md(10월 9일)가 후보입니다. 한 파일로 옮겨 164줄을 줄인 것보다 닷새 만에 더 많이 늘었고, paths를 단 규칙은 여전히 0개입니다. CLAUDE.md가 가리키는 파일 경로 20개는 모두 실제로 있었습니다.

Step 4. 상태 문서 크기와 읽기 차단

개발자F 님이 말한 4,000줄과 비교하려고, 저장소 8곳과 24기 폴더에서 HANDOFF, TODO, PLAN, LOG류 문서 14개의 줄 수를 쟀습니다.

TASKLIKE = r"(^|/)(TASKS?|PRD|BACKLOG|ROADMAP|TODO|PLAN|SPEC|HANDOFF|LOG)[^/]*\.(md|json|ya?ml)$"
# git ls-files 로 모은 뒤 줄 수와 바이트를 센다
작업 상태를 적어 둔 Markdown 문서 14개의 줄 수. 가장 긴 healthcareai의 LOG가 910줄이고 4,000줄 선에는 근처에도 가지 못한다

가장 긴 문서가 910줄(58KB)이고 4,000줄을 넘는 것은 0개입니다. 제 문서는 아직 JSON으로 바꿀 만큼 크지 않다는 뜻입니다. 다만 모델이 이 문서를 직접 읽지 못하게 막는 hook은 0개이고(PreToolUse hook의 matcher에 Read가 없고, 전체 도구에 걸린 hook 스크립트에도 읽기 차단이나 종료 코드 2가 없습니다), 작업 백로그를 담은 JSON도 0개입니다. 저장소에 있는 상태 JSON은 healthcareai의 gate_status.json 하나인데, 검사 5개의 통과 여부를 적는 파일입니다.

Step 5. 줄 수 hook 시제품과 과거 커밋 재생

줄 수 hook은 1주차 계획의 두 번째 항목이었습니다. 이번에 시제품을 만들었고, 먼저 검사를 쓰고 실패하는 것을 본 뒤 구현했습니다. 규칙은 하나입니다. 코드 파일이 300줄을 넘으면서 새 파일이거나 직전 커밋보다 길어졌을 때만 종료 코드 2로 되돌립니다. 이미 긴 파일을 그대로 두거나 줄이는 수정은 막지 않습니다. 기존 초과 파일 49개에 일괄 차단을 걸면 작업이 모두 멈추기 때문입니다.

python3 -I -m pytest -q test_hooks.py     # 훅 스크립트가 없을 때
# 5 failed in 3.19s
python3 -I -m pytest -q test_hooks.py     # 구현한 뒤
# 5 passed in 3.41s

실패를 볼 때 얻은 것이 하나 있습니다. 스크립트 파일이 없어도 파이썬은 종료 코드 2로 끝납니다. hook이 막는 신호와 hook이 죽은 신호가 같은 2라서, 종료 코드만 확인하는 검사는 스크립트가 없는 상태에서도 통과합니다. 오류 메시지의 내용까지 함께 확인하는 검사로 바꿨습니다.

이 hook이 과거에 걸려 있었다면 몇 번이나 걸렸을지, 8개 저장소의 코드 커밋 143개를 읽기 전용으로 재생해서 셌습니다.

python3 -I replay_line_limit.py
# 합계  코드 커밋 143  걸렸을 커밋 60  걸렸을 파일 96
저장소별로 코드를 고친 커밋과 줄 수 hook이 걸렸을 커밋의 수. 합계 143개 중 60개로 42%이고 KoreaAgenticAIhackathon이 19개로 가장 많다

코드를 고친 커밋 143개 가운데 60개(42%)가 300줄 넘는 파일을 새로 만들었거나 더 길게 만든 커밋이었습니다. 한 번의 커밋에서 편집 여러 번을 묶은 값이라 hook이 실제로 울리는 횟수와는 단위가 다르고, 처음 한꺼번에 들여온 커밋도 포함됩니다. 그래도 파일을 작게 나누는 일이 습관으로 지켜지지 않았다는 것은 분명합니다. 300줄 초과 파일 49개 가운데 5개는 .claude/skills/ 아래에 같은 내용의 사본이 하나 더 있어서(내용 해시가 같음), 서로 다른 파일로는 44개입니다.

Step 6. 문체 규칙의 hook 연결

기계로 검사할 수 있는 규칙이 hook에 걸려 있는지는 문체 규칙으로 확인했습니다. 24기 사례글을 쓸 때 check_style.py라는 검사기를 쓰는데, 이 검사기는 제가 기억해서 실행할 때만 돌아갑니다. 전역 settings.json에서 check_style을 찾으면 0건입니다.

  • 문체 규칙 파일 writing-style.md에서 규칙 항목으로 보이는 줄(목록 머리가 굵은 글씨인 줄)은 110개이고, 검사기가 보는 패턴은 10개입니다.

  • 같은 검사기를 24기 폴더의 강의정리와 과제 문서 50개에 걸어 보면 7개 문서에서 19건이 나옵니다. 사례글 23편은 제출 전에 직접 돌렸기 때문에 모두 0건입니다.

사례글은 걸러지고 강의정리는 새는 차이가 검사를 실행하는 시점에서 생깁니다. 이 검사기를 PostToolUse hook으로 감싼 시제품(style_hook.py)을 같은 테스트에 넣어 확인했습니다. 금지 표현이 있으면 종료 코드 2와 해당 행을 돌려주고, 코드블록 안이나 .md가 아닌 파일은 통과시킵니다. 설치는 하지 않았습니다. 전역 설정을 고치는 일은 이 글의 범위 밖이어서 사용자 결정으로 남겼습니다.

Step 7. 서브에이전트 호출의 모델 지정

agent-routing 규칙(10월 8일 수정)은 "Agent 호출에는 model을 지정한다"입니다. 이 규칙이 실제로 지켜졌는지는 세션 로그에서 셀 수 있습니다. 규칙 파일의 수정 시각(10월 8일 01시 04분) 앞뒤로 Agent 호출의 model 인자를 나눠 집계했습니다.

python3 -I measure_agent_routing.py --until 2026-10-07T16:04:00 --out pre.json
python3 -I measure_agent_routing.py --since 2026-10-07T16:04:00 --out post.json
서브에이전트 호출에서 model을 지정하지 않은 비율. 규칙 이전 253회 중 185회(73%), 규칙 이후 133회 중 8회(6%). 메인 세션의 출력 토큰 비중은 95.6%에서 95.8%로 거의 같다

모델을 지정하지 않은 호출이 73%에서 6%로 줄었습니다. 문장으로 적은 규칙이 작동한 사례입니다. 그런데 메인 세션이 낸 출력 토큰의 비중은 규칙 이전 95.6%, 이후 95.8%로 그대로였습니다. 모델 지정은 단가를 낮추지만 일을 위임하는 양까지 바꾸지는 못했다는 뜻이고, "메인은 조율만 한다"는 기준에는 아직 못 미칩니다. 이 집계에는 이 글을 쓰는 세션의 호출도 들어 있습니다.

Step 8. 메인 브랜치 직접 커밋과 1주차 계획 확인

기본 브랜치(main 또는 master)에서 병합이 아닌 커밋을 첫 부모 기준으로 셌습니다.

git -C <저장소> rev-list --first-parent --no-merges main | wc -l    # 직접 커밋
git -C <저장소> rev-list --first-parent --merges main | wc -l       # 병합 커밋

8개 저장소 합계로 직접 커밋이 550개이고 병합이 5개입니다. 승인한 것만 병합하는 흐름은 paper-production-harness 한 곳(직접 1개, 병합 4개)에만 있었습니다. 메인 커밋을 막는 hook은 0개입니다. 다만 econ-radar의 341개에는 클라우드 루틴이 발행물을 올리는 자동 커밋이 많이 섞여 있어서, 이 저장소를 빼면 직접 커밋은 209개입니다.

1주차 계획 다섯 항목은 파일 수정 시각, 설정 파일, 커밋 기록으로 확인했습니다.

1주차 계획 다섯 항목의 실행 여부. 실행은 재측정 하나, 일부 실행은 지침 정리, 시제품만 만든 것은 줄 수 hook, 실행 0은 VeriVar의 pytest hook과 읽기 전용 리뷰어

VeriVar의 pytest hook은 만들지 않았습니다. 이 저장소의 프로젝트 설정 파일은 6월 16일 이후 고치지 않았고 마지막 커밋도 8월 28일입니다. 대신 hook으로 걸 수 있는지 가늠하려고 테스트를 한 번 실행해 봤습니다.

/opt/anaconda3/envs/rag/bin/python -m pytest tests/ -q -p no:cacheprovider
# 7 failed, 385 passed in 32.55s

전체가 32.6초 걸려서 편집할 때마다 전부 실행하는 hook은 무겁고, 수정한 파일과 관련된 테스트만 골라 실행해야 합니다. 실패 7개 중 6개는 이 환경에 rank_bm25가 없어서 생긴 오류이고, 1개(test_stale_guard_on_current_manuscripts)는 원고에 폐기한 수치(0.902)가 남아 있다는 검사입니다. 기본 python3에는 pydantic도 없어서 테스트 수집부터 실패했습니다. CI는 requirements.txt를 설치한 뒤 실행하지만 제 손에 있는 환경에서는 그대로 통과하지 않으므로, hook을 걸기 전에 실행 환경부터 정해야 합니다.


결과와 배운 점

측정 결과 (2026-10-13, 전역 설정과 ~/projects 저장소 8곳)

항목

값

Claude Code 검사 hook (린트, 테스트, 줄 수)

0개 (1주차와 같음). 전역 hook 18개는 그대로

세션마다 상시 로딩되는 전역 지침

720줄 (1주차 673줄, 이동 직후 512줄, 기준 200줄)

paths가 달린 rules

0 / 11개

코드 커밋 중 테스트 동반

41 / 143 (29%). 1주차 40 / 138 (29%)

300줄 초과 코드 파일

49 / 250 (고유 44개). 1주차 48 / 249

줄 수 hook이 과거 커밋에 걸렸을 건수

60 / 143 커밋 (42%), 재생

작업 상태 문서

14개, 최대 910줄. 4,000줄 이상 0개. 백로그 JSON 0개

Agent 호출 중 모델 미지정

규칙 이전 185 / 253 (73%), 이후 8 / 133 (6%)

기본 브랜치의 직접 커밋

550개, 병합 5개. 직접 커밋 차단 hook 0개

1주차 계획 실행

5개 중 실행 1, 일부 1, 시제품 1, 실행 0이 2

배운 점

  1. 문장으로 적은 규칙은 작동했고, 구조를 바꾸는 규칙은 작동하지 않았습니다. 모델 지정 규칙은 한 줄이었고 미지정 호출이 73%에서 6%로 줄었습니다. 반면 같은 규칙이 겨냥한 메인 세션의 출력 비중은 95%대로 그대로입니다. 1주차에서 확인한 "테스트 동반 29%"가 그대로인 것도 같은 이야기입니다. 숫자 하나를 바꾸는 지시는 지켜지고, 일하는 방식을 바꾸는 지시는 문장만으로는 지켜지지 않은 것으로 보입니다.

  2. 규칙을 hook으로 옮기는 일은 기록으로 이득을 계산할 수 있습니다. 줄 수 hook이 과거에 걸렸을 커밋이 143개 중 60개였습니다. 이 숫자를 보고 나니 "300줄을 넘기지 않는다"는 문장을 CLAUDE.md에 더 적는 것보다 이 hook 하나가 낫다는 판단이 섰습니다. 새 파일과 늘어난 파일에만 걸게 한 것은, 기존 초과 파일에 일괄 차단을 걸면 작업이 멈춘다는 1주차의 결론을 반영한 것입니다.

  3. hook이 막는 신호와 죽은 신호는 같은 종료 코드일 수 있습니다. 종료 코드 2는 모델에게 되돌리는 약속인데, 파이썬이 스크립트를 못 찾아도 2로 끝납니다. hook을 걸 때는 종료 코드만이 아니라 오류 메시지가 나오는지까지 검사해야 합니다. 설치한 hook이 사실은 매번 죽고 있어도 화면에는 "막혔다"로만 보일 수 있습니다.

  4. 지침을 한 번 줄여도 그대로 있지 않습니다. 164줄을 옮겨 512줄이 됐는데 일주일 만에 720줄로 돌아왔습니다. 규칙을 한 줄 더하는 비용은 그 순간에는 보이지 않고, 줄 수를 다시 재 볼 때만 드러납니다. paths를 달아 필요한 파일에서만 읽히게 하지 않으면 줄이는 일이 반복됩니다.

  5. 제 규모에서는 JSON 백로그가 아직 급하지 않습니다. 개발자F 님이 4,000줄 문서를 문제로 삼았는데 제 상태 문서는 가장 긴 것이 910줄입니다. 먼저 hook으로 옮길 대상은 줄 수와 문체처럼 기계로 이미 검사할 수 있는 규칙입니다. 강의 기준을 그대로 옮기지 않고 제 숫자로 우선순위를 다시 정한 부분입니다.

시행착오

  • 1주차 스크립트의 기본 저장소 목록에는 hackthon/ 경로가 들어 있는데, 지금 폴더 이름은 hackathon/입니다. 기본값으로 실행하면 해당 저장소 세 곳이 오류 없이 빈 값(커밋 0, 파일 0)으로 나오고, 합계가 1주차보다 크게 줄어서야 알아차렸습니다. 경로를 직접 넘겨 다시 쟀습니다.

  • 처음에는 CLAUDE.md의 경로 참조 20개 중 2개가 없다고 나왔습니다. 하나는 스킬 폴더 안의 상대경로이고 다른 하나는 프로젝트 안의 상대경로여서, 기준 폴더를 맞춰 확인하자 둘 다 있었습니다.

  • 모델 지정 집계의 규칙 이후 구간에는 이 글을 쓰는 작업에서 띄운 서브에이전트도 포함되어 있습니다. 지정 비율이 낮아진 일부는 제가 이번 주에 의식해서 지정한 영향일 수 있고, 규칙 파일을 읽은 효과와 분리하지는 못했습니다.

  • git fetch를 하지 않아서 1주차 이후 원격에 올라온 커밋은 세지 않았습니다. 코드 커밋 수 비교에는 영향이 작지만 econ-radar처럼 원격이 앞서는 저장소는 이후 값이 더 클 수 있습니다.

  • 줄 수 재생은 커밋 단위이고 한 커밋 안의 여러 번 편집은 하나로 셉니다. 실제 hook은 편집마다 울리므로 횟수는 더 많을 수 있습니다.

이 측정은 2026년 10월 13일 ~/.claude의 전역 설정과 ~/projects 아래 제가 개발한 git 저장소 8곳의 추적 파일, 병합을 뺀 커밋 기록, 2026년 10월 기준 제 Claude Code 세션 로그의 Agent 호출 인자를 Python과 git으로 센 결과입니다. 팀 저장소와 포크, 다른 기기의 설정은 보지 않았고, 테스트 여부는 파일 이름 규칙으로, 줄 수 재생은 커밋 단위로 판정했습니다. hook 시제품은 설치하지 않았습니다.


도움 받은 글

  • 24기 CTO 2주차 지식 공유 (개발자F): 백로그 JSON과 읽기 차단, in-progress 기록, 종료 코드 2로 되돌리는 hook, 줄 수 제한의 이중 검사, 메인 에이전트는 조율만 하는 구조

  • 24기 CTO 2주차 사례 발표 (물결): 코드 9.5만 줄 중 한 파일이 2만 줄이 된 뒤 파일당 300줄과 전체 1만 줄을 hook에 넣고 다시 만든 과정

  • 24기 CTO 2주차 사례 발표 (리부티너): 메인 브랜치에 실수로 푸시한 이야기

  • 24기 CTO 1주차 사례글 (본인): 1주차 측정 명령과 기준값, 다음 주 계획 다섯 가지

함께 이야기해요 0

로그인하고 댓글을 남겨 주세요

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기