Files
clean-architecture-frontend…/.claude/rules/tests.md
T
DongHyeonka 9f8596280c feat(claude): 경로별 규칙·스킬·결과만 돌려주는 서브에이전트를 둔다
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
2026-11-08 17:27:39 +09:00

2.4 KiB

paths
paths
tests/**
**/*.spec.ts
vitest.config.ts
playwright*.config.ts

테스트를 쓰거나 고칠 때

정본은 docs/testing/taxonomy.md(층·명령·실행 환경)와 docs/work/reference/testing.md(결함을 막는지 확인하는 법)다.

  1. 층은 프레임워크가 아니라 필요한 실행 환경으로 정한다: Node만 tests/unit, React·hook tests/component, HTTP/MSW·IndexedDB·조립된 경계 tests/integration, 실제 브라우저 tests/e2e 등, 한 기능의 테스트 tests/features/<id>/.
  2. 동작을 바꾸면 재현 테스트가 먼저 실패하고(RED) 고친 뒤 통과한다(GREEN). 검출력이 문제였으면 보호 규칙을 지우는 변이를 넣어 새 테스트가 실패하는지 본다.
  3. 템플릿 원래 상태 밖에서도 돈다: 기능을 더한 상태, 확장 지점을 채운 상태, 입력·객체가 셋 이상.
  4. 단언이 대상에 닿는지 본다: fixture가 비어 첫 줄에서 return하지 않는가, 로딩·오류 화면이나 fixture 자신을 검사하지 않는가.
  5. .only를 두지 않는다. .skip·fixme는 Playwright spec에만, owner·defect·route·만료일이 있는 quarantine으로만 둔다(scripts/check-test-evidence.ts). 빠른 계층에는 quarantine이 없다. 편집 훅이 마지막 커밋보다 늘어난 skip·only·fixme·todo를 알린다.
  6. 가끔 떨어지는 테스트를 재시도·timeout 늘리기·worker 줄이기·force 클릭으로 덮지 않는다. 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 원인을 찾는다.
  7. 환경에 기대지 않는다: gitignore된 생성물, 작성자 PC의 글꼴·CPU, 바깥 env(CI=true, 빌드 식별값). 테스트가 띄우는 빌드·서버의 env는 테스트가 정한다.
  8. 플랫폼 테스트를 기능·스타터 화면에 묶지 않는다(테스트 전용 라우트, tests/mocks/). 테스트가 지워도 되는 문서(docs/reviews/ 등)를 읽지 않는다.
  9. 자식 프로세스를 띄우는 suite는 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다.

돌리는 법

  • 노트북에서는 돌리지 않는다. 한 파일도 desktop에서: scripts/verify.sh script test:unit, 또는 ssh desktop으로 node scripts/run-vitest.ts run <file>(이 runner가 생성물을 먼저 만든다. pnpm exec vitest run <file>은 import 오류로 실패한다).