pr / done (pull_request) Successful in 1m51s
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
8.6 KiB
8.6 KiB
작업 매뉴얼
이 폴더는 이 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.md2절이 정본이다. - 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 leaf(또는 문서 폴더) 하나 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다.
- brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다.
- brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
- 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다.
- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약
docs/web/http-contract.md, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 저장소 루트나src/최상위에 폴더를 새로 만들거나 옮기는 일, 보안 정책. - 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다(research-design.md). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다.
3. 모든 작업의 공통 단계
- 기준 커밋을 고정한다.
git rev-parse HEAD를 산출물과 보고에 적는다. - 이미 정한 것을 읽는다: reference/decisions.md,
docs/reviews/에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. - 소유 leaf를 찾는다. registry의
source_path로 정하고, 가장 가까운src/**/AGENTS.md를 읽는다. - 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은
.claude/skills/다(new-feature,desktop-gates, 분야 지식be-*). 여러 분야에 걸치면 experts.md의 명단·렌즈표로 고른다. 스킬이 서브에이전트에게 파일을 고치게 하라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. 결과만 받는 일은 서브에이전트에 맡겨도 된다(delegate.md 4.3절). - 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
- 무거운 실행(Gradle, Docker, 테스트, 게이트)은 operate.md 「실행 위치」대로 한다.
- 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
- 완료를 말하기 전에 검증한다(
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.md3절). 다른 세션이 맡긴 일이면 design-docsconventions/delegation-loop.md5절 양식을 쓴다.
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.md10줄, 폴더 지역 규칙(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다.