Files
DongHyeonka 9873fc06af
pr / done (pull_request) Successful in 1m51s
fix(verify): --on 단계가 worktree를 지우기 전에 lane별 시험 클래스 목록을 남긴다
verify.sh --on <호스트>는 단계를 돌린 뒤 새 worktree의 JUnit XML을
읽어 합계 한 줄만 로그에 쓰고, trap이 worktree와 XML을 지운다. Gradle
--console=plain 로그에는 성공한 시험의 수도 클래스도 없어, 표준
진입점으로 돌리면 「고친 시험이 그 lane에서 돌았다」를 남길 곳이 없다.
requires lane은 빌드가 단언하지만 tag lane과 기본 test는 비어 있고,
세션마다 XML을 손으로 복사해 왔다.

합계를 새 scripts/junit-summary.py로 옮기고, 같은 스크립트가 XML마다
leaf·태스크·클래스·숫자 한 줄을 ~/<로그 이름>-logs/<단계>-classes.tsv에
남긴다. 단계 전에 지난 목록을 지워, 단계가 합계 전에 끊겨도 옛 목록이
새 로그 옆에 남지 않는다. 합계 줄은 전 awk와 같은 꼴이고, 읽는 범위도
전 find와 같다(build/test-results/ 아래 TEST-*.xml). 다른 점: 루트
testsuite만 세서 시험이 찍은 "<testsuite " 글자를 더 세지 않고, 열지
못하거나 끝까지 읽지 못하거나 숫자가 아닌 XML은 stderr에 이름을 찍고
뺀다. rc는 전처럼 단계의 rc다. 버린 안: heredoc 안 셸로 목록 만들기
(이스케이프가 겹쳐 시험하기 어렵다), XML 폴더 통째 복사(pr 단계 약
1천 개가 실행마다 쌓인다). gates.md 4절·operate.md의 손 복사 절차는
--on here나 손으로 돌린 worktree일 때만으로 좁히고, 같은 절차를 말하던
docs/work/README.md와 스킬 셋(be-testing·be-build-ci·desktop-gates)의
한 줄도 맞춘다.

위험: 원격 worktree에 python3이 있어야 한다(desktop 3.12.3). 합계
스크립트가 죽어도 단계 rc는 바뀌지 않는다. 캐시에서 되살린 태스크의
XML도 목록에 줄이 되므로 「돌았다」의 증거는 --no-cache 실행의 목록만
쓴다고 gates.md에 적었다. 잠금·정리·트리 비교·rc 처리·workflow는
그대로다.

검증(트리 fb7606c4): scripts 시험 전체 332개 통과, 새 시험 9개는 base
트리에서 모두 실패(rc=1). 변이 9개를 모두 시험이 잡는다. desktop
scripts/verify.sh pr --no-cache rc=0(tests=7353, 목록 1059줄, TSV 합
7353), leaf :adapter:inbound:grpc rc=0(tests=85, TSV 합 85,
GrpcP1BoundaryWireTest 줄), docs rc=0.

Refs: CI-BE-0006
2026-11-22 06:23:40 +09:00
..

작업 매뉴얼

이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다. 읽는 순서는 하나다: 루트 AGENTS.md(지도) → 이 README → 맡은 일의 playbook 하나. Claude Code 세션에서는 루트 CLAUDE.md가 AGENTS.md를 가져온다. 규칙의 정본은 AGENTS.md와 registry(gradle/modules.json)다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다.

1. 어떤 playbook인가

맡은 일 playbook
새 업무 기능이나 새 capability 모듈을 만든다 new-feature.md
있는 코드를 리뷰·수정·리팩터링·최적화한다. 구조·테스트 구조를 바꾼다 improve.md
바꾸기 전에 대안을 비교하고 소유자 결정을 받는다 research-design.md
매뉴얼·안내 문서를 쓰거나 고친다 docs-writing.md
게이트를 돌린다, 릴리스한다, 파생 서비스에 템플릿 변경을 넘긴다 operate.md
큰 일을 나눠 다른 세션에 맡긴다 delegate.md

둘에 걸리면 이렇게 고른다. 결정이 먼저 필요하면 research-design이다. 동작이 바뀌는 코드가 있으면 new-feature나 improve다. 문서만 바뀌면 docs-writing이다.

2. 크기 정하기

  • 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs conventions/work-thinking-order.md 2절이 정본이다.
  • 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 leaf(또는 문서 폴더) 하나 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다.
  • brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다.
  • brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
  • 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다.
  • 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 docs/web/http-contract.md, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 저장소 루트나 src/ 최상위에 폴더를 새로 만들거나 옮기는 일, 보안 정책.
  • 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다(research-design.md). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다.

3. 모든 작업의 공통 단계

  1. 기준 커밋을 고정한다. git rev-parse HEAD를 산출물과 보고에 적는다.
  2. 이미 정한 것을 읽는다: reference/decisions.md, docs/reviews/에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
  3. 소유 leaf를 찾는다. registry의 source_path로 정하고, 가장 가까운 src/**/AGENTS.md를 읽는다.
  4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은 .claude/skills/다(new-feature, desktop-gates, 분야 지식 be-*). 여러 분야에 걸치면 experts.md의 명단·렌즈표로 고른다. 스킬이 서브에이전트에게 파일을 고치게 하라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. 결과만 받는 일은 서브에이전트에 맡겨도 된다(delegate.md 4.3절).
  5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
  6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 operate.md 「실행 위치」대로 한다.
  7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
  8. 완료를 말하기 전에 검증한다(superpowers:verification-before-completion). 돌리지 못한 검증은 못 돌렸다고, 이유와 함께 쓴다(HARD-STOP 6).

4. 커밋

  • 기본 정책은 human-only다(AGENTS.md). 에이전트는 stage·commit·amend·push하지 않는다.
  • 예외는 하나다. brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은 operate.md 4.1절 「push 전에 검증하기」).
  • 그때도 main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자가 한다.
  • 메시지 형식은 design-docs conventions/commit-and-pr.md를 따른다. AI 꼬리말과 자리표시자(TBD, TODO, 채우지 않은 칸)를 넣지 않는다.
  • 커밋 하나에 논리 변경 하나다(같은 문서 3.1절). 수정 묶음도 결함(또는 같은 원인 하나)마다 커밋을 나누고, 동작 변경을 위한 리팩터링(규칙을 상수로 빼기 등)은 앞 커밋으로 나눈다. 나눈 커밋마다 그 커밋이 바꾼 것의 검사가 통과해야 한다(operate.md 4.1절 「push 전에 검증하기」).

5. 막혔을 때

  • 소유자만 정할 수 있는 것(공개 계약, 파생 서비스 동작, 보안 정책, 새 leaf, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다.
  • brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다.
  • 묻는 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람.

6. 보고

  • 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다.
  • 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
  • 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다.
  • 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다. 테스트 수는 성공한 Gradle 로그에 없다. scripts/verify.sh로 보낸 단계는 로그 끝 합계 줄과 <단계>-classes.tsv에서, 손으로 돌린 worktree는 결과 XML 사본에서 센다(reference/gates.md 4절).
  • 착수할 때 예측(p30·p50·p80과 근거)을, 끝 보고 직전에 실측을 docs/ledger/estimates.jsonl에 한 줄씩 더한다(형식 docs/ledger/README.md).
  • 사고 순서 흔적 칸을 둔다(conventions/work-thinking-order.md 3절). 다른 세션이 맡긴 일이면 design-docs conventions/delegation-loop.md 5절 양식을 쓴다.

7. 필요할 때만 읽는 문서

문서 내용
reference/gates.md 게이트 목록, 바꾼 것에 맞는 게이트, 결과 기록 형식, 거짓 통과 막기
reference/review-criteria.md 결함 정의, 심각도, 증거·통제 수준, 점검 항목, 리뷰 문서 양식
reference/defect-patterns.md 반복해서 나온 결함의 모양과 막는 기준
reference/decisions.md 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법
reference/terms.md 영어 그대로 쓰는 말과 정한 표기의 뜻
reference/related-repos.md 템플릿 밖 라이브러리 repo 목록, 같이 고치기와 버전 올리기
evidence.md 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID

8. 이 폴더를 고칠 때

  • 분량 상한: 지도(루트 AGENTS.md) 40줄, 루트 CLAUDE.md 10줄, 폴더 지역 규칙(src/**/AGENTS.md) 200줄(넘으면 표·근거를 그 leaf README로), 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 CLAUDE.md + README + playbook 하나) 350줄. reference/는 상한이 없다.
  • 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 evidence.md로 옮긴다. 새 세션이 처음 읽는 루트 AGENTS.md·CLAUDE.md, src/**/AGENTS.md, .claude/ 아래 규칙·스킬·서브에이전트 문서도 같다. 모듈 README·설계 문서·docs/reviews/**는 ID를 둔다.
  • 이 폴더, 루트 AGENTS.md·CLAUDE.md, src/**/AGENTS.md, .claude/ 아래 문서를 고친 뒤 python3 scripts/check-work-docs.py가 통과해야 한다. 절차는 docs-writing.md다.