Files
clean-architecture-frontend…/src/adapters/AGENTS.md
T
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

1.9 KiB

AGENTS.md — src/adapters (재사용 capability runtime)

application 포트를 구현하는 HTTP, 인증, 저장소, query cache, telemetry, worker 등이다. 그룹마다 src/adapters/<그룹>/index.ts(배럴)가 공개 경계다.

지킬 것

  • 그룹 밖에서는 배럴로만 들어온다. 2단계 index.ts는 공개 배럴이 아니다(예외 storage/indexeddb, storage/opfs).
  • 다른 adapter 그룹을 import하지 않는다(adapters-do-not-know-other-concrete-adapters). 예외는 kernel 셋(src/adapters/platform/ 폴더 전체, browser-file-storage/result.ts, cross-context-invalidation/index.ts)뿐이고 새 파일 단위 예외를 만들지 않는다. 새 공유 프리미티브는 src/adapters/platform/에 둔다.
  • presentation·bootstrap을 import하지 않는다(adapters-do-not-know-presentation). 일반 worker는 네트워크·자격 증명 adapter를 모른다. Service Worker 입구는 페이지 코드가 아니다.
  • 실패 분류는 status와 code를 함께 본다. 짝 백엔드 쓰기 응답 판정은 src/adapters/http/backend-envelope.ts의 REFUSED_BEFORE_WRITE 하나다.
  • 모든 src/ 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 src/contracts/zod.ts로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 AGENTS.md 꼭 지킬 것과 docs/architecture/layers.md다.

검사

  • 판정은 check:architecture(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
  • check:adapter-inventory(FE-GATE-010 안): 파일을 더하거나 옮기면 docs/reviews/adapters/INVENTORY.md를 같은 커밋에서 고친다(이 파일도 거기 행이 있다)
  • check:browser-file-storage-boundaries·check:realtime-boundaries(FE-GATE-010 안)
  • 돌리는 곳은 desktop이다(scripts/verify.sh). 테스트는 tests/integration, tests/contract에 둔다(.claude/rules/tests.md).