Files
clean-architecture-backend-…/docs/upgrade/2026-11-harness.md
T
DongHyeonka 2921f596a5 feat(harness): 하네스 플러그인 harness@claude-harness를 켠다
공통 훅·스킬(되돌릴 수 없는 명령 차단 H12, 비밀 값 알림, 예측·실측
장부 기록, estimate·retro·techdebt)은 claude-harness repo의 플러그인이
준다. 이 repo는 그 플러그인을 켜지 않아 새 세션이 그것들을 받지 못했다.

.claude/settings.json에 extraKnownMarketplaces(claude-harness, git URL)와
enabledPlugins를 더했다. 기존 deny와 repo 훅은 그대로다. 사용자 전역에
같은 H12가 등록돼 있으면 플러그인 H12는 스스로 아무것도 하지 않는다
(소유자 기계가 그렇다). 비대화형(claude -p)은 플러그인을 자동 설치하지
않으므로 CLAUDE.md와 docs/upgrade/2026-11-harness.md 9번에 수동 설치 두
명령을 적었다.

위험: 이 세션은 ~/.claude를 바꾸지 않으므로 플러그인 설치 자체는 하지
않았다. 대화형 앱이 처음 열 때 설치를 묻는지는 확인하지 않았다(claude-
harness README도 같은 미확인).

검증: settings.json JSON 파싱, check-work-docs.py rc=0(CLAUDE.md 10/10줄).
2026-11-08 11:29:55 +09:00

6.3 KiB

업그레이드 안내 — 2026-11 Claude Code 작업 환경(하네스)

  • 범위: 지침 파일 배치(leaf 규칙 문서 이름, 루트 AGENTS.md·CLAUDE.md), .claude/의 권한·훅·규칙·스킬·서브에이전트, 예측·실측 장부
  • 근거: 소유자 결정(2026-11-07), design-docs harness/01-harness-design.md 13절, docs/work/reference/decisions.md 「지침 배치」

1. 누가 읽나

이 템플릿을 받아 도메인을 채운 파생 서비스가 읽는다. 코드·설정·빌드의 동작은 바뀌지 않았다. 바뀐 것은 지침 파일의 자리와 Claude Code 세션 설정이다.

2. 바뀐 것과 할 일

# 바뀐 것 서비스가 할 일
1 leaf·family 지역 규칙 문서가 src/**/CLAUDE.md에서 같은 폴더 src/**/AGENTS.md로 옮겨 갔다. 그 폴더 CLAUDE.md는 @AGENTS.md 한 줄이다 서비스가 leaf CLAUDE.md를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 AGENTS.md로 옮기고 CLAUDE.md는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 src/<leaf>/CLAUDE.md의 내용을 읽으면 AGENTS.md로 바꾼다(git grep -n 'CLAUDE\.md' -- docs src)
2 루트 AGENTS.md가 규칙 정본이자 지도(40줄 이하: 비전·HARD-STOP·지도·맡은 일·검증·일하는 방식)가 됐다. 루트 CLAUDE.md는 @AGENTS.md와 Claude 전용 몇 줄이다. 옛 AGENTS.md의 절은 옮겨 갔다: 「Gradle 정책 권위」 → src/build-logic/AGENTS.md, 「테스트 전략」의 작성 규칙 → .claude/rules/java-tests.md(계층별 기준은 각 계층 AGENTS.md 「테스트」), 「모듈 책임」 → src/adapter/inbound/AGENTS.md·src/adapter/outbound/AGENTS.md·각 core AGENTS.md, 「부가 기능(capability) 모듈 규칙」 → docs/manual/10-capabilities.md, 「설정과 런타임」 → .claude/rules/settings-and-runtime.md, 「템플릿 재사용 체크리스트」 → 루트 README.md 「새 서비스로 시작하기」. 「Superpowers Workflow」·「강제 수준」·「금지된 지름길」·「작업 보고 규칙」은 HARD-STOP·전역 규칙과 같은 말이라 지웠다 서비스가 루트 AGENTS.md나 CLAUDE.md를 고쳤다면 merge에서 충돌이 난다. 서비스 고유의 줄은 새 AGENTS.md의 같은 절(40줄 안)이나 위 새 자리에 옮긴다. 서비스 문서가 옛 절 이름(「Gradle 정책 권위」 등)을 가리키면 새 자리로 바꾼다
3 .claude/rules/(경로별 규칙)를 추적한다. .gitignore에 !.claude/rules/를 더했다 서비스 .gitignore가 .claude/*를 무시하면 같은 줄을 더한다
4 .claude/settings.json에 repo 훅을 걸었다(본체 scripts/hooks/hooks.py, 설명 scripts/hooks/README.md): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 .env·.env.local·.env.lane 읽기·쓰기를 권한으로 막는다 서비스가 .claude/settings.json을 고쳤다면 두 쪽을 합친다. 훅은 src/config/architecture/modules.json, src/gradle/libs.versions.toml의 googleJavaFormat, applied-migrations.sha256을 읽으므로 그 경로를 옮긴 서비스는 hooks.py 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다
5 Agent 도구 금지를 풀었다(.claude/settings.json의 "Agent" deny 삭제). 결과만 받는 일은 서브에이전트(.claude/agents/의 arch-reviewer·verify-api·code-simplifier)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(docs/work/delegate.md 4.3절). .gitignore에 !.claude/agents/를 더했다 서비스가 Agent 도구를 계속 막으려면 자기 .claude/settings.json에 "Agent" deny를 남긴다. verify-api는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다
6 repo 스킬 둘을 더했다: .claude/skills/new-feature(새 기능 실행 순서), .claude/skills/desktop-gates(Gradle·Docker를 desktop에서 돌리는 순서). 모델이 설명의 발동 조건을 보고 부른다. 설치된 스킬이 없던 skills-lock.json을 지웠다. .gitignore에 !.claude/skills/를 더했다 desktop-gates는 소유자 환경을 가정하므로 서비스 환경에 맞게 고치거나 지운다. 서비스가 skills-lock.json을 썼다면 merge에서 삭제 충돌이 난다. 쓰면 남긴다
7 예측·실측 장부 docs/ledger/estimates.jsonl(형식 docs/ledger/README.md)을 두었다. .gitattributes가 이 파일에 merge=union을 준다 서비스는 템플릿의 줄을 지우고 자기 작업의 줄부터 쌓는다. 템플릿 줄은 템플릿 작업의 기록이다
8 지역 규칙이 200줄을 넘던 셋(src/application-core, src/adapter/outbound/persistence-jpa, src/adapter/inbound/graphql)의 표와 계약을 같은 폴더 README.md 끝 「지역 규칙에서 옮긴 표와 계약」 절로 옮겼다. 템플릿 패키지 목록(「패키지 소유」 표)의 정본도 src/application-core/README.md다 서비스가 그 절을 고쳤다면 README의 같은 절로 옮긴다. 서비스 문서·테스트가 src/application-core/AGENTS.md의 「Package ownership」 표를 읽으면 README.md로 바꾼다
9 .claude/settings.json에 하네스 플러그인 마켓(extraKnownMarketplaces의 claude-harness, git URL https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git)과 enabledPlugins: {"harness@claude-harness": true}를 더했다(2026-11-08). 플러그인이 되돌릴 수 없는 명령 차단(H12), 비밀 값 알림, 장부 기록 훅과 estimate·retro·techdebt 스킬을 준다. 사용자 전역에 같은 H12 훅이 있으면 플러그인 H12는 아무것도 하지 않는다. 기존 deny와 repo 훅은 그대로다 서비스가 .claude/settings.json을 고쳤다면 두 키를 합친다. 대화형 Claude Code는 폴더를 처음 믿을 때 설치를 묻는다. 비대화형(claude -p)이면 그 폴더에서 claude plugin marketplace add <위 URL> --scope project와 claude plugin install harness@claude-harness --scope project를 한 번 돌린다. 플러그인을 쓰지 않으려면 두 키를 지운다