Files
clean-architecture-frontend…/AGENTS.md
T
DongHyeonka b5e7f54bd1
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
feat(claude): 분야 전문가를 지식 스킬 아홉 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
문제: 하네스에 분야 지식이 없다. 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

37 lines
3.8 KiB
Markdown

# AGENTS.md — 프론트 템플릿의 정본
도메인 로직을 뺀 공통 기능을 갖춘 React + Vite 프론트 출발점이다(`PRODUCT.md`). 브라우저 SPA + 정적 호스팅 + Service Worker이고 SSR은 없다. 서비스는 복사해 기능 폴더를 채운다. 방향과 문제 정의는 `docs/vision.md`·`docs/problem-statement.md`(소유자가 채우는 빈 양식)다. 개발 compose는 짝 백엔드의 `compose.yaml`을 쓴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이고, 갈라진 중복 복사본은 결함이다.
## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다
1. adapter 그룹 밖에서는 배럴(`src/adapters/*/index.ts`)로만 들어간다. 배럴이 공개 경계다.
2. adapter끼리 import하는 예외는 `.dependency-cruiser.json`의 kernel 셋(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이다. 새 파일 단위 예외를 만들지 않는다. 공용 로직은 `src/adapters/platform/`이나 `src/contracts/`에 둔다.
3. import 규칙의 정본은 `.dependency-cruiser.json`, 판정은 `check:architecture`다. dependency-cruiser CLI는 TypeScript 7을 못 읽어 쓰지 않는다.
4. 게이트 기준(문턱, 예산, 기준선, skip·only)을 낮춰 통과시키지 않는다.
5. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말하지 않는다.
## 지도
- 계층·import 방향과 최상위 `src/` 폴더의 역할은 `docs/architecture/layers.md`다.
- 새 기능은 `corepack pnpm create:feature <id>`로 만들고 `docs/manual/` 순서로 채운다.
- 게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다(설명 `docs/operations/ci-quality-gates.md`).
- adapter 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다.
- 지역 규칙은 작업 파일과 가장 가까운 `src/<계층>/AGENTS.md`다. 폴더를 가로지르는 규칙(테스트·문서·게이트 기준)은 `.claude/rules/`, 문서 위치 규칙은 `docs/README.md`다.
## 맡은 일
먼저 `docs/work/README.md`, 그다음 playbook 하나를 끝까지 읽는다(모두 `docs/work/`): 새 기능 `new-feature.md` · 리뷰·수정·리팩터링·성능 `improve.md` · 대안 비교와 소유자 결정 `research-design.md` · 문서 `docs-writing.md` · 게이트·릴리스·파생 프로젝트 `operate.md` · 일 나누기 `delegate.md`. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.
## 검증
- 진입점은 `scripts/verify.sh <단계>`다. 단계는 `config/ci/gates.json`의 stage id(`merge` 등), 게이트 하나는 `scripts/verify.sh gate FE-GATE-005`(안에서 `corepack pnpm ci:gate FE-GATE-005`). pnpm 단계는 desktop으로 옮겨 돈다.
- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. desktop의 FE-GATE-013은 `docs/work/reference/gates.md` 3절 문구로 적는다.
- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북).
## 일하는 방식
- 커밋·push는 brief가 허용한 것만 자기 브랜치에 한다. main 병합·force push·PR 병합은 소유자가 한다.
- 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. pnpm·게이트·브라우저는 누가 돌려도 desktop에서다(`docs/work/delegate.md`).
- 여러 분야에 걸친 일은 리드(메인 세션)가 분야 지식을 골라 새 눈 리뷰어에게 맡기고 합친다. 명단·경로표·넘김·충돌 규칙은 `docs/work/experts.md`다.