Claude Code 세션이 테스트·문서·adapter·게이트 기준·기능 폴더를 고칠 때
읽을 규칙이 루트 한 파일에 섞여 있었고, desktop 실행과 새 기능 절차를
부르는 스킬, 결과만 받는 리뷰어 정의가 없었다.
- .claude/rules/: tests, docs, adapters, gates-and-budgets, features.
paths로 그 파일을 열 때만 읽힌다.
- .claude/skills/: desktop-gates(scripts/verify.sh로 desktop에서 돌리기),
new-feature(create:feature부터). 소유자 결정대로 모델이 부르고, 설명에
발동 조건을 문단으로 쓴다. 본문은 정본 playbook을 가리킨다.
- .claude/agents/: arch-reviewer(경계 규칙), verify-app(desktop에서
빌드·브라우저 확인), code-simplifier. 쓰기 도구가 없다.
- .claude/settings.json: 하네스 플러그인 harness@claude-harness를 켜고
실제 .env 읽기·쓰기를 막는다. Agent deny는 두지 않는다.
- .gitignore: .claude/는 이 넷만 추적하고 worktree·훅 상태·
settings.local.json은 무시한다.
버린 대안: Agent deny 유지(소유자 결정 2026-11-07 Q5가 풀었다), 스킬을
사용자 호출 전용으로(Q9가 모델 호출을 골랐다).
위험·한계: 규칙 paths는 지금 있는 파일로 시험하지만 Claude Code가 실제로
읽는지는 이 세션에서 보지 않았다(설정은 세션 시작에 읽힌다).
검증: python3 -m unittest scripts/tests/test_claude_setup.py 통과
(서브에이전트 쓰기 도구 없음, 스킬 설명 길이와 발동 조건, 규칙 paths가
가리키는 파일 있음).
Refs: design-docs harness/01-harness-design.md 13절 Q3·Q5·Q9
루트에는 리뷰 기준만 담은 CLAUDE.md(26줄)가 있었다. 꼭 지킬 경계 규칙,
지도, 검증 진입점, 맡은 일 라우터가 없었고, "서브에이전트를 병렬로"는
소유자 결정(2026-11-07)과 맞지 않았다.
AGENTS.md(35줄)에 무엇인가 · 꼭 지킬 것 5 · 지도 · 맡은 일 · 검증 ·
일하는 방식을 둔다. CLAUDE.md는 @AGENTS.md와 Claude 전용 줄(10줄)이다:
settings·훅, 하네스 플러그인과 비대화형 설치 두 명령, 규칙·스킬·
서브에이전트 위치, 리뷰 기준이 옮겨 간 곳, 소유자 환경. 리뷰 기준과
전체 리뷰 절차는 docs/work/reference/review-criteria.md와
docs/work/improve.md 4.1절로 옮겼다.
scripts/check-work-docs.py는 백엔드 검사기를 옮긴 것이다: 지도 40줄,
CLAUDE.md 15줄, README 80줄, playbook 150줄, 진입 경로 350줄, 9절 뼈대,
진입 문서의 이력 ID 0, 상대 링크. 이력 패턴에 이 repo의 꼴(1105 README,
P-43·O-12·D-14)을 더했다. 표준 라이브러리만 써서 노트북에서 돈다.
버린 대안: CLAUDE.md만 두기(다른 에이전트가 못 읽는다), 심볼릭 링크
(Claude 전용 줄을 둘 수 없다).
위험·한계: 지도 40줄은 자료와 백엔드에 맞춘 값이다. brief 상한 80보다
좁다.
검증: python3 scripts/check-work-docs.py rc=0,
python3 -m unittest scripts/tests/test_check_work_docs.py 통과.
Refs: design-docs harness/01-harness-design.md 4.3절·13절 Q1·Q2