모듈 작업자 브리프 — 체크리스트와 템플릿

오케스트레이터가 병렬 모듈 작업자(Agent Teams teammate, Orca 워커, 서브에이전트)에게 줄 지시문을 쓸 때 쓰는 점검표다. 작업자는 지시문에 없는 규칙을 스스로 찾지 않는다 — 지시문에 빠진 규칙은 모든 모듈에서 같은 방식으로 어겨진다.

한 신규 풀스택 앱에서 오케스트레이터가 쓴 공통 브리프는 읽을 문서·소유 영역·품질 기준·포트 격리·보고 형식을 잘 갖췄지만, 아래 7가지가 빠져 있었다. 결과로 모든 모듈이 같은 결함을 갖고 합쳐졌다.

브리프가 참조한 규칙 문서 목록(coui-flutter-rules, responsive-available-width, flutter-patterns)에 위 규칙의 정본이 없었던 것도 원인이다. 이제 정본은 flutter-app-baseline 한 장이다.

• 반드시 먼저 읽기에 저장소 CLAUDE.md·README, 공통 계약 문서, 자기 모듈 수용 기준이 있다

• 소유 영역(수정 가능한 경로)과 "영역 밖 수정 금지 → 계약 변경 요청으로 보고" 가 있다

• 런타임 격리(포트·DB·시뮬레이터 슬롯)가 작업자마다 다르게 정해져 있다

• 커밋 규약(언어·형식·트레일러)과 최종 보고 형식(줄 수, 테스트 숫자, 계약 변경 요청)이 있다

• 커밋·PR 리듬 — 의미 단위로 자주 커밋·push, 공유 파일(루트 workspace 목록·lock·공용 DI) 변경 금지(필요하면 오케스트레이터에게 요청), 충돌이 없으면 rebase 하지 않는다

• 배포 경로 소유 — 배포·CI 파이프라인(워크플로·Pages 활성화·게이트)은 한 작업자가 첫 PR 로 먼저 연다

• git 의존 ref — 사내 패키지 ref 를 작업자가 따로 올리지 않는다(워크스페이스 일괄 상향, check_git_dep_refs.py 게이트)

• Jev 판단 지점 — 오케스트레이터·작업자별 입력, 세트, reflex 채택/위임 폴백, evidence 기록법이 지시문에 있다

• "반드시 먼저 읽기"에 cc-flutter:flutter-app-baseline 이 있다
• 사내 패키지 먼저 — cc-dev:internal-package-registry 표를 보고, 쓰지 않으면 이유를 보고에 남기라고 적었다. 이 모듈에 해당하는 패키지를 이름으로 짚었다(예: 차트 주석 → open_board)
• HookWidget + signals_hooks: ^7.1.0, StatefulWidget 금지(예외는 baseline §1 목록 + 주석)
• 한 파일 한 공개 타입(UseCase·State·enum 도 분리) + 게이트 명령 check_one_public_class.py --check-name
• 라우트는 @TypedGoRoute, 문자열 context.go('/…') 금지. 새 경로는 링크로도 열리는지(웹 path URL)
• 골든 — 화면마다 co_golden 매트릭스 시나리오(상태별), CO_GOLDEN_MODE=capture 통과를 완료 조건에
• BDD — 기능마다 co_bdd .feature(정상·검증 실패·권한/빈 상태), 생성 테스트 통과를 완료 조건에
• 목·픽스처 데이터 — co_faker(seed·기준 시각 고정), 앱에 이름·전화·주소 목록 하드코딩 금지, 실존 개인정보처럼 보이는 값 금지
• 사내 패키지 확장 소유자 — co_faker(및 이번 작업에서 확장할 다른 사내 패키지)의 변경을 한 작업자에게만 소유시켰고, 나머지 작업자에게는 "필요한 생성기·API 는 <소유자>에게 요청, 받기 전엔 얇은 어댑터 + 이관 대상 목록" 을 적었다
• 엔티티 × co_faker API — 모듈 착수 전 엔티티와 필드를 실제 API 선언·문서 후보에 대조했다. 후보마다 upstream-coverage 를 묻고, 누락은 단일 소유자가 먼저 확장한다
• 데모 모드 — localOnly 리포지토리는 공용 데모 세계만 읽고 쓰고, 변경 신호는 쓰기에서만(읽기에서 내면 무한 루프), 서버 없으면 조용히 폴백하지 않는다(baseline §7)
• 시계 주입 — 실시계를 읽는 화면·나이 계산은 기준 시각을 주입받는다(골든·데모 결정성)
• 웹 — flutter build web 은 --no-wasm-dry-run, 한글 폰트 번들(baseline §8)
• coui — 공통 핀을 쓰고 작업자가 따로 올리지 않는다(버전 상향은 오케스트레이터가 별도 작업으로). 핀이 최신 태그보다 낡았으면 착수 전에 오케스트레이터가 먼저 올렸다

• 서버·클라이언트 경로가 backend/<project>_server·backend/<project>_client 로 적혀 있다(중립 이름 경로를 지시문에 복사하지 않는다)
• 오프라인 동기화·소셜 로그인이 필요하면 co-serverpod 패키지를 쓰라고 적었다
• 모델 변경 시 마이그레이션 생성 규칙(작업자 로컬 vs 통합 시 단일화)이 있다

• cc-deeplink:deeplink-bootstrap 체크리스트(웹 path URL·SPA 폴백·AASA·assetlinks·entitlements·intent-filter)를 그 작업자 한 명에게 소유시켰다
• 골든 갤러리 GitHub Pages 워크플로를 그 작업자(또는 오케스트레이터)가 소유한다 — 모듈 작업자는 시나리오만 추가

• cob doctor와 수동 preflight에서 SDK·인증/push·secret·Pages/Actions·패키지 ref 상태를 확인했다 (cob doctor --preflight 는 도구에 머지된 뒤 사용)
• cob fullstack --name <name> --demo 산출물을 검증하고, 첫 Pages 워크플로·저장소 설정의 단일 소유자를 지정했다 (--pages·--console 은 머지 전 사용 금지)
• Pages 실제 URL의 등록 surface build.json이 같은 source SHA 를 가리키고, 데모 화면 이동·새로고침이 된다
• Seed spec 은 /cc-spec:verify PASS·LOCKED, 일반 분석 문서는 사용 가능한 문서 평가 결과와 근거가 있다
• 분석 문서 엔티티 × co_faker 실제 API 심볼/필드 표에 부족분이 없고, 부족분은 단일 소유자가 패키지 확장·태그를 선행했다
• 첫 PR CI 필수 잡이 녹색이고 잡별·전체 시간을 기록했다. 병렬 샤드 템플릿이 없으면 예정 상태와 수동 분할 계획을 브리프에 적었다

복붙 명령(값은 임시 JSON 파일에 넣어 셸 인용 문제를 피한다):

JR="${CLAUDE_PLUGIN_ROOT:-$PWD/plugins/cc-dev}/skills/jev-reflex/scripts/jev_reflex.py"
python3 "$JR" ask --set upstream-coverage --state @/tmp/upstream-candidate.json
python3 "$JR" ask --set ci-failure --state @/tmp/ci-failure.json
python3 "$JR" ask --set same-failure --state @/tmp/failure-pair.json
python3 "$JR" ask --set rebase-needed --state @/tmp/merge-evidence.json

각 JSON 의 필수 필드: requirement+api(실제 API 후보 한 개), failure, previous+current, merge_evidence. reflex 만 사용한다. 불확실하거나 호출 불가면 기존 규칙으로 진행하고 판단: <지점> | set=<세트> | state=<후보/로그 식별자> | route=<경로> | value=<채택값 또는 -> | fallback=<기준> | source=<file:line/URL> 를 작업 보고에 남긴다. 숫자 세기·API 존재·CI 통과·merge 가능 여부는 원천으로 검증한다. rebase-needed 가 unknown 이면 Jev 가 reflex 라도 GitHub 상태와 보호 규칙을 다시 확인한다.

## 새 앱 기준선 (flutter-app-baseline — 어기면 반려)
- 라이브러리급 기능은 먼저 사내 패키지 표(internal-package-registry)를 본다. 이 모듈 해당: <패키지 또는 "없음">.
  쓰지 않으면 최종 보고에 이유 한 줄.
- 화면·위젯: HookWidget + signals_hooks ^7.1.0. StatefulWidget 금지(baseline §1 예외만, 주석 필수).
- 한 파일 = 공개 타입 하나(UseCase·State·enum 포함). `python3 tool/gates/check_one_public_class.py <내 패키지> --check-name` exit 0.
- 라우트: @TypedGoRoute 선언, 이동은 생성된 라우트 클래스로. 문자열 경로 금지.
- 골든: 화면마다 co_golden 매트릭스(로딩·빈·에러·데이터). `CO_GOLDEN_MODE=capture flutter test --tags co_golden` 통과.
- BDD: 기능마다 co_bdd .feature(정상·검증 실패·권한/빈 상태). build_runner 후 생성 테스트 통과.
- 서버 경로는 backend/<project>_server · backend/<project>_client.
- 목·픽스처·골든·위젯북 데이터는 co_faker(seed·now 고정). 없는 생성기는 <co_faker 소유 작업자>에게 요청하고,
  받기 전까지 얇은 어댑터 + "co_faker 이관 대상" 목록에 기록. 사내 패키지가 부족하면 우회 구현 전에 업스트림 확장.
- coui 핀은 공통 값을 쓴다. 올려야 하면 "계약 변경 요청"으로 보고.
- 데모(localOnly) 리포지토리는 공용 데모 세계만 사용, 변경 신호는 쓰기에서만. 실시계 대신 주입된 시계.
- 의미 단위로 자주 커밋·push. 공유 파일(루트 workspace 목록·lock) 수정 금지, 충돌 없으면 rebase 금지.
- 사내 패키지 git ref 는 따로 올리지 않는다(워크스페이스 일괄).
- Day 0 근거: <preflight 결과> · <Pages run URL/source SHA> · <Seed spec 판정> · <엔티티×co_faker API 표> · <CI 잡별 시간>.

최종 보고 형식에 다음 줄을 더한다: 기준선: StatefulWidget n · 파일 게이트 위반 n · 문자열 라우트 n · 골든 시나리오 n · BDD 시나리오 n · 사내 패키지 사용/미사용(이유).