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>
7.3 KiB
7.3 KiB
구현 레인 공통 지시서 (모든 레인 에이전트가 먼저 읽는다)
원본 repo: 이 저장소를 clone한 경로(아래 $REPO)
통합 브랜치: fix/maturity-review-2026-09-25
너의 작업 디렉터리(worktree)와 브랜치는 프롬프트에 적혀 있다. 그 디렉터리 밖의 파일은 읽기만 한다. 원본 repo의 워킹트리와 다른 레인 worktree는 절대 수정하지 않는다.
1. 먼저 읽을 것 (worktree 안의 파일)
SPEC.md— 공통 완료 기준, 결정 표 D-1~D-19, 범위 밖 항목tasks/plan.md— 레인 구조, 파일 소유 표tasks/todo.md— 너의 레인 섹션(작업 목록과 순서)CLAUDE.md— repo 전제(템플릿, 배럴이 공개 경계, kernel 예외)docs/reviews/2026-09-25-maturity-review/<영역 문서>— 네 작업 ID 항목 전부. 근거·발생 조건·최소 개선 방향·완료 기준·검증 방법이 여기 있다.
완료 기준의 기준은 리뷰 항목의 "완료 기준" 칸이다. SPEC 결정 표가 다르게 정했으면 결정 표를 따른다.
2. 작업 하나의 순서
todo 순서대로 하나씩 한다.
- 리뷰 항목과 관련 코드를 읽는다. 근거 줄 번호는 리뷰 당시(
4626b73) 기준이다. 코드가 바뀌었을 수 있으니 직접 확인한다. - RED: 문제를 재현하는 테스트를 먼저 쓰고, 실패하는 것을 확인한다. 문서만 바꾸는 작업은 이 단계가 없다. 변이 생존이 문제였던 작업은 리뷰에 적힌 변이를 넣었을 때 새 테스트가 실패하는지도 확인한다.
- GREEN: 가장 작은 변경으로 통과시킨다. 주변 코드를 정리하지 않는다. 필요 없는 추상화를 만들지 않는다.
- 게이트: 아래를 모두 통과시킨다.
adapter 파일을 추가·이동했으면
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-schemadocs/reviews/adapters/INVENTORY.md를 고치고corepack pnpm check:adapter-inventory도 돌린다. - 커밋: 그 작업이 바꾼 파일만
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중 맞는 것을 쓴다. 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 뒤)를 더한다.