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

3.3 KiB

AGENTS.md — 프론트 템플릿의 정본

도메인 로직을 뺀 공통 기능을 갖춘 React + Vite 프론트 출발점이다(PRODUCT.md). 브라우저 SPA + 정적 호스팅 + Service Worker이고 SSR은 없다. 서비스는 복사해 기능 폴더를 채운다. 개발 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를 같은 커밋에서 고친다.
  • 폴더를 가로지르는 규칙(테스트·문서·설정)은 .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로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다.
  • 문서·지침을 고쳤으면 scripts/verify.sh docs(노트북).

일하는 방식

  • 커밋·push는 brief가 허용한 것만 자기 브랜치에 한다. main 병합·force push·PR 병합은 소유자가 한다.
  • 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
  • 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. pnpm·게이트·브라우저는 누가 돌려도 desktop에서다(docs/work/delegate.md).