문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약·
빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한,
동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그
문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게
합치는지도 정한 곳이 없다.
고른 방법(소유자 결정 2026-11-11 「W3 설계대로」):
- 지식 스킬 be-* 10개(.claude/skills/). 각자 paths를 걸어 그 분야 파일을
만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 →
검증 → 이 repo에서 정한 것 순서이고, 정본 문서를 가리킨다. 초안은 이
repo 문서만 본 서브에이전트가 썼고, 경로는 relayout 배치에 맞췄다.
- 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는
be-domain을 미리 싣고 lead 공통 양식으로 돌려준다.
- .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의
「함정」·「검증」을 보게 하는 두 줄(평가에서 스킬 호출이 5번 중 2번이었다).
- docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도·충돌·비용. 루트
AGENTS.md 한 줄, CLAUDE.md 두 줄 고침(10줄 상한 유지), README 3절 4단계와
delegate.md 4.3절에 가리키는 말.
- 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 지식 스킬의 paths·
설명 300자·금지어·절 순서·150줄, 모든 paths glob이 추적 파일에 걸림,
명단이 모든 전문가를 담음.
버린 대안: 분야마다 서브에이전트. Anthropic 2026-10-22·2026-01-23·2026-04-07
글이 반대하고, 설명이 모든 세션에 든다.
위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이
병합돼야 받는다. 그전에는 lead를 가리키는 문장이 설명만 남는다.
검증: python3 -m unittest discover -s scripts/tests → 154건 통과. 새 시험 6개는
조건을 깰 때마다 실패했다. scripts/verify.sh docs → rc=0.
새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을
할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야
하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가
2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고
설명에 발동 조건을 문단으로 적기로 정했다(design-docs
harness/01-harness-design.md 5.5절, 13절 Q9·Q18).
- .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의
실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터
→ 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트).
- .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행
순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc →
테스트 수 → 잠금 대기 → 정리 → 보고 칸).
- 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은
327자·268자로 목록 상한(1,536자) 안이다.
- 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다.
- test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본
가리키기, skills-lock.json 없음)을 더했다.
버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함),
verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편
몫이라 여기서는 만들지 않는다).
위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른
스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다.
검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아
고쳤다), check-work-docs, check-repo-layout 모두 rc=0.
BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/
2026-11-harness.md 2절 6행.
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).
- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
따르는지 본다.
버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).
위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.
검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.
BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.