Files
clean-architecture-frontend…/tasks/lanes/LANE-BRIEF.md
T
DongHyeonkaandClaude Opus 5.5 54ba358892 docs: hand off the maturity review fixes to another machine
tasks/handoff.md records merged and pending lanes, the remaining tasks
and follow-ups, and the integration procedure. tasks/lanes/ carries the
lane brief and a machine-independent worktree setup script. todo.md
marks the tasks already merged into this branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 01:11:04 +09:00

7.3 KiB

구현 레인 공통 지시서 (모든 레인 에이전트가 먼저 읽는다)

원본 repo: 이 저장소를 clone한 경로(아래 $REPO) 통합 브랜치: fix/maturity-review-2026-09-25 너의 작업 디렉터리(worktree)와 브랜치는 프롬프트에 적혀 있다. 그 디렉터리 밖의 파일은 읽기만 한다. 원본 repo의 워킹트리와 다른 레인 worktree는 절대 수정하지 않는다.

1. 먼저 읽을 것 (worktree 안의 파일)

  1. SPEC.md — 공통 완료 기준, 결정 표 D-1~D-19, 범위 밖 항목
  2. tasks/plan.md — 레인 구조, 파일 소유 표
  3. tasks/todo.md — 너의 레인 섹션(작업 목록과 순서)
  4. CLAUDE.md — repo 전제(템플릿, 배럴이 공개 경계, kernel 예외)
  5. docs/reviews/2026-09-25-maturity-review/<영역 문서> — 네 작업 ID 항목 전부. 근거·발생 조건·최소 개선 방향·완료 기준·검증 방법이 여기 있다.

완료 기준의 기준은 리뷰 항목의 "완료 기준" 칸이다. SPEC 결정 표가 다르게 정했으면 결정 표를 따른다.

2. 작업 하나의 순서

todo 순서대로 하나씩 한다.

  1. 리뷰 항목과 관련 코드를 읽는다. 근거 줄 번호는 리뷰 당시(4626b73) 기준이다. 코드가 바뀌었을 수 있으니 직접 확인한다.
  2. RED: 문제를 재현하는 테스트를 먼저 쓰고, 실패하는 것을 확인한다. 문서만 바꾸는 작업은 이 단계가 없다. 변이 생존이 문제였던 작업은 리뷰에 적힌 변이를 넣었을 때 새 테스트가 실패하는지도 확인한다.
  3. GREEN: 가장 작은 변경으로 통과시킨다. 주변 코드를 정리하지 않는다. 필요 없는 추상화를 만들지 않는다.
  4. 게이트: 아래를 모두 통과시킨다.
    corepack pnpm check:architecture && corepack pnpm check:types && corepack pnpm lint && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:contract && corepack pnpm test:runtime-schema
    
    adapter 파일을 추가·이동했으면 docs/reviews/adapters/INVENTORY.md를 고치고 corepack pnpm check:adapter-inventory도 돌린다.
  5. 커밋: 그 작업이 바꾼 파일만 git add <경로>로 스테이징한다(git add -A 금지). 메시지 형식은 기존 이력과 같다.
    fix(<area>): <무엇을 고쳤나, 영어 소문자 시작> (<발견 ID>)
    
    <왜, 1~3줄>
    
    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
    
    종류는 fix, test, docs, perf, refactor, build, ci 중 맞는 것을 쓴다.
  6. tasks/todo.md는 고치지 않는다. 체크는 오케스트레이터가 통합 때 한다.

3. 규칙

  • 파일 소유: tasks/plan.md 표에서 다른 레인이 소유한 파일은 바꾸지 않는다. 꼭 바꿔야 하면 바꾸지 말고 보고에 "다른 레인 요청"으로 적는다. config/ci/gates.json과 .gitea/workflows/quality-gates.yml은 레인 Z(Phase 0)와 K만 바꾼다.
  • 범위: 결정 표 밖의 설계 판단이 필요하면(공개 포트를 깨야 함, 리뷰 방향이 코드와 맞지 않음 등) 그 작업은 멈추고 "막힘"으로 보고한다. 그다음 독립적인 작업은 계속한다.
  • 무관한 테스트 실패: 다른 레인이 병렬로 돌아 호스트 부하가 높다. 네 변경과 무관해 보이는 실패가 나면 그 파일만 단독으로 다시 돌린다. 단독으로 통과하면 "부하 flaky"로 보고에 적고 진행한다. 단독으로도 실패하면 원인을 찾는다.
  • 실행: corepack pnpm <script>는 worktree 안에서 돌린다. 설치 명령(pnpm install, pnpm add)은 절대 실행하지 않는다. 새 의존성은 추가하지 않는다. 필요하면 "막힘"으로 보고한다.
  • git: push 금지. git config 변경 금지. 다른 브랜치를 checkout하지 않는다. rebase·reset·stash도 하지 않는다. 네 브랜치에 커밋만 쌓는다.
  • Playwright: 리뷰가 브라우저 검증을 요구한 작업만 spec 하나를 추가하고 그 spec만 돌린다. 브라우저 설치 명령은 실행하지 않는다.
  • 코드 스타일: 주변 코드의 주석 밀도, 이름, 관용구를 따른다. 코드 주석은 영어로 쓴다(기존 코드와 같게).
  • 문서: 문서는 한국어 평범한 문장으로 쓴다. 기존 문서가 영어면 영어로 쓴다. 주장마다 코드 위치를 붙인다.

4. 레인 끝

모든 작업을 끝낸 뒤 다음을 한 번 돌린다.

corepack pnpm check:architecture && corepack pnpm check:types && corepack pnpm lint && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:contract && corepack pnpm test:runtime-schema && corepack pnpm check:ci && corepack pnpm check:adapter-inventory && corepack pnpm verify:documentation && corepack pnpm build

corepack pnpm test:sample-removal은 시간이 들지만 레인 끝에 한 번 돌린다.

5. 오케스트레이터에게 돌려줄 최종 메시지 (50줄 이하)

레인: <X> · 브랜치: lane/<X> · 커밋 <N>개
작업:
- <ID> | 완료/막힘/부분 | <커밋 short sha> | <추가·바꾼 테스트 파일> | <한 줄 요약>
막힘·부분: <ID와 이유, 필요한 결정>
다른 레인 요청: <파일과 바꿀 내용>
부하 flaky: <테스트 파일>
레인 끝 게이트: <명령별 결과>

6. 2차 레인 추가 규칙 (1차 통합 뒤, 기준 커밋 4d17259)

  • 레시피 번들 예산: corepack pnpm build 뒤 corepack pnpm check:optional-recipes를 돌린다. 네 수정으로 config/recipes/frontend-capability-recipes.json의 bundleBudgetGzipBytes를 넘으면 예산을 고치지 말고 측정값(artifacts/quality/optional-recipes.json)을 보고에 적는다. 오케스트레이터가 통합 때 "측정값을 100바이트 단위로 올림" 규칙으로 한 번에 올린다. 현재 여유: realtime 39,903/40,000, service-worker-pwa 9,623/10,000, file-transfer 55,517/55,600, offline-indexeddb 36,822/36,900.
  • 초기 JS 예산: check:bundle이 초과하면 역시 고치지 말고 보고한다(현재 약 196.5KB/204.8KB).
  • config/ci/gates.json: 2차 레인은 필요할 때만 바꾼다. 바꾸면 CI_CONTRACT_BASELINE_OWNER=<담당> CI_CONTRACT_BASELINE_REASON=<이유·ID> corepack pnpm update:ci-contract-baseline → corepack pnpm generate:ci-workflow → tests/unit/ci-workflow-generation.test.ts 개수 갱신 → check:ci. 여러 레인이 바꾸면 오케스트레이터가 통합 때 기준선을 다시 만든다.
  • Playwright 포트: 여러 레인이 동시에 브라우저 테스트를 돌린다. 프롬프트에 적힌 네 포트를 쓰는 임시 설정 파일을 .tmp/에 만들어(커밋하지 않음) 그 설정으로 spec을 돌린다. 기존 설정 파일을 복사해 webServer.port/url/baseURL만 바꾸면 된다.
  • 1차 레인이 바꾼 것: 결과 불명 쓰기의 같은 키 재전송(C), 폼 실패 상태(C), needs 검사와 기능 선택 생성기(I), 부트 오류 경로 boot.tsx·boot-messages.ts(I, BootErrorShell은 i18n catalog를 import하면 안 된다), 그래프 규칙과 위반 메시지(K), drill·hosting 판정 UNVERIFIED(K). 이 위에서 작업한다.
  • 레인 끝 게이트에 corepack pnpm check:optional-recipes(build 뒤)를 더한다.