feat(claude): 분야 전문가를 지식 스킬 열 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다 #14

Merged
donghyeon.kang merged 3 commits from donghyeon.kang/w3-experts-be AGit into main 2026-11-12 06:00:52 +00:00
Owner

선행 PR: #10(Gradle 루트 재배치)은 병합됐다(main 841a176f). force push 없이 이 PR을 갱신하려고 main을 이 브랜치로 merge했다(ea52d9d9). 플러그인 lead·new-expert·harness-eval은 claude-harness #3(0.3.0, 병합됨)에 있다.

무엇을, 왜

하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약·빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한, 동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그 문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게 합치는지도 정한 곳이 없다. 소유자 결정(2026-11-11 「W3 설계대로」)대로 분야 전문가를 넣는다.

  • 지식 스킬 be-* 10개(.claude/skills/): paths를 걸어 그 분야 파일을 만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 → 이 repo에서 정한 것.
  • 서브에이전트 reviewer(렌즈 = brief가 준 스킬 경로). arch-reviewer는 be-domain을 미리 싣는다.
  • .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의 「함정」·「검증」을 보게 하는 두 줄.
  • docs/work/experts.md: 명단, 경로 → 렌즈, 넘김 지도, 충돌 순서, 비용. 루트 AGENTS.md 한 줄, CLAUDE.md 두 줄 고침, README 3절과 delegate.md 4.3절에 가리키는 말.

고른 방법과 버린 대안

  • 분야마다 서브에이전트를 두지 않는다. Anthropic 2026-10-22 「When to fold subagents into your main agent loop」, 2026-01-23 「Building multi-agent systems」, 2026-04-07 「subagents in Claude Code」가 분야·역할별 서브에이전트를 반대하고, 설명은 모든 세션에 든다. 근거는 claude-harness docs/experts.md·docs/research/2026-11-11-harness-v2.md.
  • 스킬 초안은 이 repo 문서만 본 서브에이전트가 썼다(평가에 심은 결함을 모르게). 경로는 #10 배치로 바꿨고, 모든 paths glob이 추적 파일에 걸리는 것을 시험으로 고정했다.
  • 스킬 호출을 늘리려고 규칙 파일을 더했다(평가용 판에서 호출이 5번 중 2번이었다). 그래도 실제 세션에서 셋 중 하나만 불러서, 5feb5a1b에서 "처음 Edit·Write 전에 Skill 도구로, 문서를 읽었어도 부른다"와 고칠 것 → 스킬 짝을 적었다. 다시 재니 3/3이 첫 편집 전에 불렀다. 버린 대안: 모듈마다 leaf AGENTS.md에 한 줄(파일 수십 개), 강조어(과다 호출).

위험과 영향

  • 시작 비용: 실제 세션 첫 호출 47,689 → 48,088토큰(+0.8%). be-*는 시작 목록에 없다.
  • v2 세션은 더 넓게 확인해 구현 과제에서 호출 1.35배, 출력 1.5배를 썼다. 새 규칙 판은 분야 스킬을 세션마다 3~7개 부른다. 과제와 먼 분야(be-security·be-performance)도 섞인다. claude-harness 설계 9절 F7로 지켜본다.
  • 파생 서비스는 .claude/skills/be-*의 경로를 자기 배치에 맞춰야 한다(경로가 어긋나면 test_every_knowledge_skill_glob_matches_a_tracked_file가 실패한다).

검증

  • python3 -m unittest discover -s scripts/tests → 154건 통과(ea52d9d9에서 다시 돌림). 새 시험 6개는 조건을 깰 때마다 실패했다(낡은 glob, Agent 도구, 절 이름, paths 없음, 강조어, 미리 싣는 스킬).
  • scripts/verify.sh docs → rc=0(노트북).
  • desktop scripts/verify.sh pr(기준 main 841a176f, head ea52d9d9의 트리 ca967cff, 공유 잠금 아래): rc=0, 테스트 6,721개 실패 0·오류 0·건너뜀 28. 로그 desktop ~/w3-experts-be2-logs/pr.log. 첫 head c611b06f(기준 123fc0bf)도 같은 결과였다(~/w3-experts-be-logs/pr.log).
  • 평가(실제 세션, claude-harness 장부 harness-v2-eval-real): 구현 과제(우선순위 컬럼·인덱스·설정 키를 repo 규칙대로, 정규식 채점 8개)에서 기준(#10) 6/8 ×3, 이 브랜치 8/8 ×3. 동시 인덱스 규칙 0/3 → 3/3. 작은 diff 리뷰는 판과 상관없이 결함 12개를 모두 찾았다(변별력 없음). 규칙을 고친 판(5feb5a1b)은 8/8 ×3이고, 분야 스킬을 첫 편집 전에 부른 세션이 1/3에서 3/3이 됐다(claude-harness docs/experts.md 7.4절).

리뷰어가 볼 곳

  • .claude/skills/be-persistence/SKILL.md·be-security·be-api-contract의 「함정」(이 repo에서 실제로 난 실패).
  • docs/work/experts.md 3절 경로 → 렌즈 표.
  • scripts/tests/test_claude_setup.py의 새 시험.

관련

  • claude-harness docs/experts.md(설계·평가 7.1~7.3절), docs/research/2026-11-11-harness-v2.md(조사)
  • design-docs harness/01-harness-design.md 13절(결정 문장은 총괄이 반영)
> **선행 PR**: #10(Gradle 루트 재배치)은 병합됐다(main `841a176f`). force push 없이 이 PR을 갱신하려고 main을 이 브랜치로 merge했다(`ea52d9d9`). 플러그인 `lead`·`new-expert`·`harness-eval`은 claude-harness #3(0.3.0, 병합됨)에 있다. ## 무엇을, 왜 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약·빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한, 동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그 문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게 합치는지도 정한 곳이 없다. 소유자 결정(2026-11-11 「W3 설계대로」)대로 분야 전문가를 넣는다. - 지식 스킬 `be-*` 10개(`.claude/skills/`): `paths`를 걸어 그 분야 파일을 만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 → 이 repo에서 정한 것. - 서브에이전트 `reviewer`(렌즈 = brief가 준 스킬 경로). `arch-reviewer`는 `be-domain`을 미리 싣는다. - `.claude/rules/expert-skills.md`: 분야 파일을 고치기 전에 그 스킬의 「함정」·「검증」을 보게 하는 두 줄. - `docs/work/experts.md`: 명단, 경로 → 렌즈, 넘김 지도, 충돌 순서, 비용. 루트 `AGENTS.md` 한 줄, `CLAUDE.md` 두 줄 고침, README 3절과 delegate.md 4.3절에 가리키는 말. ## 고른 방법과 버린 대안 - 분야마다 서브에이전트를 두지 않는다. Anthropic 2026-10-22 「When to fold subagents into your main agent loop」, 2026-01-23 「Building multi-agent systems」, 2026-04-07 「subagents in Claude Code」가 분야·역할별 서브에이전트를 반대하고, 설명은 모든 세션에 든다. 근거는 claude-harness `docs/experts.md`·`docs/research/2026-11-11-harness-v2.md`. - 스킬 초안은 이 repo 문서만 본 서브에이전트가 썼다(평가에 심은 결함을 모르게). 경로는 #10 배치로 바꿨고, 모든 `paths` glob이 추적 파일에 걸리는 것을 시험으로 고정했다. - 스킬 호출을 늘리려고 규칙 파일을 더했다(평가용 판에서 호출이 5번 중 2번이었다). 그래도 실제 세션에서 셋 중 하나만 불러서, `5feb5a1b`에서 "처음 Edit·Write 전에 Skill 도구로, 문서를 읽었어도 부른다"와 고칠 것 → 스킬 짝을 적었다. 다시 재니 3/3이 첫 편집 전에 불렀다. 버린 대안: 모듈마다 leaf AGENTS.md에 한 줄(파일 수십 개), 강조어(과다 호출). ## 위험과 영향 - 시작 비용: 실제 세션 첫 호출 47,689 → 48,088토큰(+0.8%). `be-*`는 시작 목록에 없다. - v2 세션은 더 넓게 확인해 구현 과제에서 호출 1.35배, 출력 1.5배를 썼다. 새 규칙 판은 분야 스킬을 세션마다 3~7개 부른다. 과제와 먼 분야(`be-security`·`be-performance`)도 섞인다. claude-harness 설계 9절 F7로 지켜본다. - 파생 서비스는 `.claude/skills/be-*`의 경로를 자기 배치에 맞춰야 한다(경로가 어긋나면 `test_every_knowledge_skill_glob_matches_a_tracked_file`가 실패한다). ## 검증 - `python3 -m unittest discover -s scripts/tests` → 154건 통과(`ea52d9d9`에서 다시 돌림). 새 시험 6개는 조건을 깰 때마다 실패했다(낡은 glob, Agent 도구, 절 이름, paths 없음, 강조어, 미리 싣는 스킬). - `scripts/verify.sh docs` → rc=0(노트북). - desktop `scripts/verify.sh pr`(기준 main `841a176f`, head `ea52d9d9`의 트리 `ca967cff`, 공유 잠금 아래): **rc=0**, 테스트 6,721개 실패 0·오류 0·건너뜀 28. 로그 desktop `~/w3-experts-be2-logs/pr.log`. 첫 head `c611b06f`(기준 `123fc0bf`)도 같은 결과였다(`~/w3-experts-be-logs/pr.log`). - 평가(실제 세션, claude-harness 장부 `harness-v2-eval-real`): 구현 과제(우선순위 컬럼·인덱스·설정 키를 repo 규칙대로, 정규식 채점 8개)에서 기준(#10) 6/8 ×3, 이 브랜치 8/8 ×3. 동시 인덱스 규칙 0/3 → 3/3. 작은 diff 리뷰는 판과 상관없이 결함 12개를 모두 찾았다(변별력 없음). 규칙을 고친 판(`5feb5a1b`)은 8/8 ×3이고, 분야 스킬을 첫 편집 전에 부른 세션이 1/3에서 3/3이 됐다(claude-harness `docs/experts.md` 7.4절). ## 리뷰어가 볼 곳 - `.claude/skills/be-persistence/SKILL.md`·`be-security`·`be-api-contract`의 「함정」(이 repo에서 실제로 난 실패). - `docs/work/experts.md` 3절 경로 → 렌즈 표. - `scripts/tests/test_claude_setup.py`의 새 시험. ## 관련 - claude-harness `docs/experts.md`(설계·평가 7.1~7.3절), `docs/research/2026-11-11-harness-v2.md`(조사) - design-docs `harness/01-harness-design.md` 13절(결정 문장은 총괄이 반영)
donghyeon.kang added 1 commit 2026-11-11 16:19:42 +00:00
feat(claude): 분야 전문가를 지식 스킬 열 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
pr / vulnerabilities (pull_request) Canceled after 0s
pr / done (pull_request) Canceled after 0s
pr / gradle (pull_request) Canceled after 8m18s
c611b06f03
문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·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.
donghyeon.kang added 2 commits 2026-11-11 19:37:30 +00:00
문제: 실제 세션 평가(구현 과제 3번)에서 `be-persistence`는 세 번 모두 스킬 목록에
떴지만 부른 세션은 한 번뿐이었다. 나머지 둘은 관련 문서를 직접 읽고 스킬을 건너뛰었다.
규칙은 "어느 스킬인지는 experts.md 3절 표"라고만 해서 한 번 더 읽어야 짝을 알았다.

고른 방법: 규칙에 고칠 것 → 스킬 짝을 한 줄로 적고, 처음 Edit·Write하기 전에 Skill
도구로 부르며 문서를 읽었어도 부른다고 적었다. 버린 대안: 모듈마다 leaf AGENTS.md에
한 줄 더하기(파일 수십 개, 배치 검사와 겹침), 강조어(MUST 등, 과다 호출을 부른다).

위험: 규칙이 붙는 세션마다 약 300토큰이 는다. 여러 분야를 부르면 호출이 는다.

검증: python3 -m unittest discover -s scripts/tests 154건 통과, scripts/verify.sh docs rc=0.
Merge remote-tracking branch 'origin/main' into claude/w3-experts-be
pr / gradle (pull_request) Successful in 11m1s
pr / vulnerabilities (pull_request) Successful in 1m10s
pr / done (pull_request) Successful in 0s
ea52d9d900
donghyeon.kang merged commit 27a18b4f0c into main 2026-11-12 06:00:52 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#14