Commit Graph
4 Commits
Author SHA1 Message Date
DongHyeonka b5e7f54bd1 feat(claude): 분야 전문가를 지식 스킬 아홉 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
frontend-quality-gates / merge / static checks (pull_request) Successful in 3m3s
frontend-quality-gates / merge / tests (pull_request) Failing after 13m34s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 9m26s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
문제: 하네스에 분야 지식이 없다. QA·디자인/UX·디자인 시스템·React·폴더
구조·시험 환경·접근성·성능·보안의 이 repo 규칙(배럴 경계, 토큰 밖 색 금지,
axe 태그 범위, 예산, FE-GATE 실행법 등)은 문서와 검사기에 흩어져 있고,
여러 분야에 걸친 일을 누가 보고 어떻게 합치는지 정한 곳이 없다.

고른 방법(소유자 결정 2026-11-11 「W3 설계대로」, 백엔드와 같은 모양):
- 지식 스킬 fe-* 9개(.claude/skills/). paths를 걸어 그 분야 파일을 만질 때만
  목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 →
  이 repo에서 정한 것 순서. 초안은 이 repo 문서만 본 서브에이전트가 썼고
  glob 75개가 모두 파일에 걸리는 것을 확인했다.
- 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는
  fe-structure를, verify-app은 fe-qa를 미리 싣는다(QA 탐색 차터).
- .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의
  「함정」·「검증」을 보게 하는 두 줄.
- docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도(백엔드 repo로 가는 API
  계약 차이는 총괄을 거침)·충돌·비용. 루트 AGENTS.md·CLAUDE.md 한 줄씩,
  README 3절 4단계와 delegate.md 4.3절에 가리키는 말.
- 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 미리 싣는 스킬,
  지식 스킬의 paths·설명 300자·금지어·절 순서·150줄·glob이 파일에 걸림,
  명단이 모든 전문가를 담음, 규칙 목록에 expert-skills.
- 문서 PR #15와 겹치지 않게 docs/는 docs/work/만 건드렸다.
버린 대안: 분야마다 서브에이전트(QA·디자인·접근성 …). Anthropic
2026-10-22·2026-01-23·2026-04-07 글이 반대하고, 설명이 모든 세션에 든다.

위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이
병합돼야 받는다. fe-ux·fe-a11y의 paths는 템플릿에 기능 화면이 없어
src/presentation/**까지만 건다(기능이 생기면 넓힌다).

검증: scripts/verify.sh docs → rc=0, scripts/verify.sh hooks → 68건 통과.
새 시험은 조건을 깰 때마다 실패했다. desktop merge 단계는 이 커밋 뒤에 돈다.
2026-11-11 23:55:59 +09:00
DongHyeonka f117a5af41 docs(src): 계층 폴더마다 지역 규칙 AGENTS.md를 두고 CLAUDE.md가 가져온다
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.

src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).

- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
  본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
  아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
  양식을 가리킨다.

버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).

위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).

검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
2026-11-08 22:57:03 +09:00
DongHyeonka 18ea5e939b docs(work): cold-read 시험에서 막힌 곳과 사실과 다른 곳을 고친다
이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능
만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가
나왔다. 고친 것:

- new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로
  받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거
  드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는
  중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면
  묻는다. 초기 JS 기록의 파일을 적는다.
- gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구,
  PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과
  ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개
  (package script)"로.
- review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4·
  증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다.
- README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절
  이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의
  정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외,
  스킬의 새 명령 모양.

고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에
시작했다).

검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
2026-11-08 17:53:36 +09:00
DongHyeonka 6e8cc963ec docs(agents): 루트 AGENTS.md를 정본으로 두고 CLAUDE.md가 가져온다
루트에는 리뷰 기준만 담은 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
2026-11-08 17:27:39 +09:00