docs(work): 넘친 operate.md와 재배치 뒤 낡은 지침을 고친다 #16

Merged
donghyeon.kang merged 11 commits from claude/r9-docs-work into main 2026-11-12 18:58:54 +00:00
Owner

무엇을, 왜

백엔드 round9 전체 리뷰(main a7e38c10)의 문서·지침 발견을 고친다. main에서 이미 scripts/check-work-docs.py가 rc=1이라(docs/work/operate.md 151/150줄) scripts/verify.sh docs와 라운드 끝 묶음이 실패한다. 같은 묶음으로, 재배치 뒤 낡은 손 절차, 손으로 옮겨 갈라진 경로 표, 코드와 다른 결정 색인 행, desktop에 daemon을 남기는 verify-api 절차를 고친다.

발견 바꾼 것
진입 문서의 묶음 ID (W4 BE-OBS-A) 꼴을 검사가 못 잡음 검사가 이 꼴(W1~W6, BE-OBS-A·BE-CONFIG-001)을 잡게 함. operate.md 줄 수·ID 자체는 PR #15(caa71d32)가 고쳐서, 이 PR의 같은 수정은 revert 커밋 d82a534d로 되돌렸다
operate.md 4.1절이 cd ~/workspace/<작업>/src 다음 ./gradlew, 지식 스킬 넷(be-api-contract·be-domain·be-persistence·be-security)이 "명령은 src/에서" /src 삭제, 스킬은 "저장소 루트에서". 진입 문서에 옛 Gradle 루트 지시가 남으면 실패하는 시험 추가
related-repos.md "Gradle 루트가 src/", ../../messaging-library 저장소 루트 기준 ../messaging-library
experts.md 3절 표가 스킬 paths와 아홉 스킬에서 갈라짐 표를 paths와 같게, 대조 시험 추가
decisions.md 낡은 행 넷(docs-check, build-logic 잠금, cosign keyless, workflow cd) + docs/README.md docs-check 취소선·「→ 바꿈」, 새 행 둘
verify-api가 bootstrap-local.sh를 flock으로 직접(daemon 남음), 없는 「정리법」 scripts/verify.sh app --on here, 정리는 compose down과 worktree remove
CLAUDE.md "be-* 10개" 개수 복사 개수 삭제

고른 방법과 버린 대안

  • experts 표는 지우지 않고 맞춘 뒤 시험으로 고정했다. 지우면 리드가 렌즈 하나를 고르려고 스킬 열 개의 머리를 읽어야 하고 「이럴 때 더한다」 칸이 갈 곳이 없다.
  • operate.md는 다른 줄을 지우지 않고 바로 위 줄에 합쳤다. 정본은 docs/security/rate-limiting.md 「파생 서비스가 정할 것」이다.
  • verify-api는 bootstrap-local.sh에 --no-daemon을 붙이지 않았다. 노트북 첫 실행에서는 daemon이 이득이라, desktop 쪽 진입점 verify.sh가 끈다.

위험과 영향

  • 문서·검사 스크립트·.claude/ 정의만 바꾼다. 운영 코드·공개 계약·빌드는 바뀌지 않는다.
  • check-work-docs.py가 PR 단계에서 돌지 않아 operate.md 초과가 병합됐다. 그 검사를 prCheck에 넣는 일은 workflow·build.gradle을 맡은 CI 세션(PR #15 쪽)에 넘겼다.
  • decisions.md 「build-logic 의존성 잠금」은 언제 누가 잠그기로 바꿨는지 기록이 없어 "기록 없음"으로 적었다. 소유자 확인 대상이다.

검증

  • 기준 a7e38c10에서 check-work-docs.py rc=1(151 lines) — PR #15가 고친다. 이 PR만 병합된 main에서도 #15 전까지 rc=1이다(새 ID 꼴 검사가 operate.md의 W4를 잡음). 새 시험 셋을 기준 파일에 얹으면 실패: ID 꼴 3건, experts 표 9개 스킬, verify-api 1건, 옛 src/ 지시 6곳(스킬 넷, operate.md 두 줄).
  • GREEN(노트북, Gradle 없음): scripts/verify.sh docs rc=0(check-work-docs·check-docs·scripts/tests 158건·check-repo-layout).
  • 이 문서들을 읽는 Java 시험은 없다: git grep -n -e experts.md -e decisions.md -e operate.md -e related-repos -e verify-api -- 'src/*.java' 'build-logic/*.java' → 걸림 없음(알림 증거 검사의 주석 한 줄만 docs/README.md를 말함). 그래서 desktop lane은 돌리지 않았다. PR 단계(:prCheck 안 documentCheck)는 runner가 돈다.

리뷰어가 볼 곳

  • scripts/tests/test_claude_setup.py experts_lens_paths: 표를 읽는 방식(1열 백틱 glob, 중괄호 펼침, 2열의 be-* 이름).
  • scripts/check-work-docs.py 새 패턴 둘의 경계(W3C·HTTP-W1-x는 통과).

관련

  • 리뷰 기록: docs/reviews/2026-11-12-round9-review/(리뷰 PR에서 커밋).
## 무엇을, 왜 백엔드 round9 전체 리뷰(main `a7e38c10`)의 문서·지침 발견을 고친다. main에서 이미 `scripts/check-work-docs.py`가 rc=1이라(`docs/work/operate.md` 151/150줄) `scripts/verify.sh docs`와 라운드 끝 묶음이 실패한다. 같은 묶음으로, 재배치 뒤 낡은 손 절차, 손으로 옮겨 갈라진 경로 표, 코드와 다른 결정 색인 행, desktop에 daemon을 남기는 verify-api 절차를 고친다. | 발견 | 바꾼 것 | |---|---| | 진입 문서의 묶음 ID `(W4 BE-OBS-A)` 꼴을 검사가 못 잡음 | 검사가 이 꼴(W1~W6, BE-OBS-A·BE-CONFIG-001)을 잡게 함. operate.md 줄 수·ID 자체는 PR #15(caa71d32)가 고쳐서, 이 PR의 같은 수정은 revert 커밋 d82a534d로 되돌렸다 | | operate.md 4.1절이 `cd ~/workspace/<작업>/src` 다음 `./gradlew`, 지식 스킬 넷(be-api-contract·be-domain·be-persistence·be-security)이 "명령은 `src/`에서" | `/src` 삭제, 스킬은 "저장소 루트에서". 진입 문서에 옛 Gradle 루트 지시가 남으면 실패하는 시험 추가 | | related-repos.md "Gradle 루트가 src/", `../../messaging-library` | 저장소 루트 기준 `../messaging-library` | | experts.md 3절 표가 스킬 `paths`와 아홉 스킬에서 갈라짐 | 표를 `paths`와 같게, 대조 시험 추가 | | decisions.md 낡은 행 넷(docs-check, build-logic 잠금, cosign keyless, workflow cd) + docs/README.md docs-check | 취소선·「→ 바꿈」, 새 행 둘 | | verify-api가 bootstrap-local.sh를 flock으로 직접(daemon 남음), 없는 「정리법」 | `scripts/verify.sh app --on here`, 정리는 compose down과 worktree remove | | CLAUDE.md "be-* 10개" 개수 복사 | 개수 삭제 | ## 고른 방법과 버린 대안 - experts 표는 지우지 않고 맞춘 뒤 시험으로 고정했다. 지우면 리드가 렌즈 하나를 고르려고 스킬 열 개의 머리를 읽어야 하고 「이럴 때 더한다」 칸이 갈 곳이 없다. - operate.md는 다른 줄을 지우지 않고 바로 위 줄에 합쳤다. 정본은 `docs/security/rate-limiting.md` 「파생 서비스가 정할 것」이다. - verify-api는 bootstrap-local.sh에 `--no-daemon`을 붙이지 않았다. 노트북 첫 실행에서는 daemon이 이득이라, desktop 쪽 진입점 `verify.sh`가 끈다. ## 위험과 영향 - 문서·검사 스크립트·`.claude/` 정의만 바꾼다. 운영 코드·공개 계약·빌드는 바뀌지 않는다. - `check-work-docs.py`가 PR 단계에서 돌지 않아 operate.md 초과가 병합됐다. 그 검사를 `prCheck`에 넣는 일은 workflow·`build.gradle`을 맡은 CI 세션(PR #15 쪽)에 넘겼다. - decisions.md 「build-logic 의존성 잠금」은 언제 누가 잠그기로 바꿨는지 기록이 없어 "기록 없음"으로 적었다. 소유자 확인 대상이다. ## 검증 - 기준 `a7e38c10`에서 `check-work-docs.py` rc=1(151 lines) — PR #15가 고친다. 이 PR만 병합된 main에서도 #15 전까지 rc=1이다(새 ID 꼴 검사가 operate.md의 `W4`를 잡음). 새 시험 셋을 기준 파일에 얹으면 실패: ID 꼴 3건, experts 표 9개 스킬, verify-api 1건, 옛 `src/` 지시 6곳(스킬 넷, operate.md 두 줄). - GREEN(노트북, Gradle 없음): `scripts/verify.sh docs` rc=0(check-work-docs·check-docs·`scripts/tests` 158건·check-repo-layout). - 이 문서들을 읽는 Java 시험은 없다: `git grep -n -e experts.md -e decisions.md -e operate.md -e related-repos -e verify-api -- 'src/*.java' 'build-logic/*.java'` → 걸림 없음(알림 증거 검사의 주석 한 줄만 `docs/README.md`를 말함). 그래서 desktop lane은 돌리지 않았다. PR 단계(`:prCheck` 안 `documentCheck`)는 runner가 돈다. ## 리뷰어가 볼 곳 - `scripts/tests/test_claude_setup.py` `experts_lens_paths`: 표를 읽는 방식(1열 백틱 glob, 중괄호 펼침, 2열의 `be-*` 이름). - `scripts/check-work-docs.py` 새 패턴 둘의 경계(W3C·HTTP-W1-x는 통과). ## 관련 - 리뷰 기록: `docs/reviews/2026-11-12-round9-review/`(리뷰 PR에서 커밋).
donghyeon.kang added 7 commits 2026-11-12 12:41:20 +00:00
문제: red team 수정이 operate.md 4.3절에 요청률 제한 한 줄을 더해
151줄이 됐다(playbook 상한 150). main에서 check-work-docs.py가 rc=1이라
scripts/verify.sh docs와 라운드 끝 묶음이 실패한다. 같은 줄 끝의
"(W4 BE-OBS-A)"는 그 주 노트를 읽은 사람만 따라갈 수 있는 묶음 ID다.
진입 문서에는 ID를 쓰지 않는다(.claude/rules/docs.md).

고른 방법: 바로 위 「파생 서비스가 유지할 게이트」 줄에 한 문장으로
합치고 ID를 뺀다. 자세와 켜는 법의 정본은 docs/security/rate-limiting.md
「파생 서비스가 정할 것」이라 operate.md에는 가리키는 말만 남긴다.
버린 대안: 다른 줄을 지워 자리를 만드는 것 — 지울 만큼 낡은 줄이 없다.

위험·한계: check-work-docs.py가 PR 단계에서 돌지 않아 이 초과가 병합됐다.
그 검사를 PR 단계에 넣는 일은 workflow·build.gradle을 맡은 CI 세션에 넘겼다.

검증: python3 scripts/check-work-docs.py rc=0(operate.md 150/150).
기준 a7e38c10에서는 rc=1(151 lines, limit 150).
문제: 진입 문서의 이력 ID 검사(HISTORY_PATTERNS)는 리뷰 라운드·묶음
이름의 아는 꼴만 잡는다. 2026-11 프로그램의 작업 흐름 이름(W1~W6)과 red
team 발견 ID(BE-OBS-A, BE-CONFIG-001)는 꼴이 없어, operate.md에 들어간
"(W4 BE-OBS-A)"를 --history도 기본 검사도 잡지 못했다.

고른 방법: 두 꼴을 패턴에 더한다. W 뒤 숫자 하나가 단어로 서 있을 때
(W3C, HTTP-W1-x는 아님), BE·FE 뒤 대문자 분야와 세 자리 번호나 글자
하나. 지금 검사 대상 문서에는 걸리는 줄이 없다.

위험·한계: 새 이름 꼴(다른 프로그램의 흐름 이름 등)은 또 패턴을 더해야
잡힌다. 검사는 아는 꼴만 본다는 한계는 그대로다(be-docs 함정 2).

검증: 새 시험 둘(걸리는 세 줄, 걸리면 안 되는 W3C) — 기준
check-work-docs.py에 얹으면 세 줄 모두 통과해 3건 실패, 이 커밋에서
test_check_work_docs 17건 통과. check-work-docs.py rc=0.
문제: Gradle 루트를 저장소 루트로 옮긴 뒤(refactor(layout)!) src/에는
gradlew가 없다. 그런데 operate.md 4.1절 손 절차 두 곳은 아직
`cd ~/workspace/<작업 이름>/src` 다음 ./gradlew를 돌리라고 한다.
desktop-gates 스킬 6단계가 단계 밖 명령(lane 하나, spotlessApply, 탐침)을
이 절차로 보내므로 그대로 따르면 명령이 없다고 실패한다.
related-repos.md도 "Gradle 루트가 src/라 경로는 두 단계 위"라며
--include-build ../../messaging-library를 적는다. 지금은 workspace 밖을
가리킨다.

고른 방법: /src를 지우고, 라이브러리 경로를 한 단계 위(../messaging-library)로
고친다. 다른 살아 있는 문서에 같은 꼴(cd src, src/gradlew)이 남았는지
git grep으로 봤다. 시험 fixture(broken-readme.md)만 걸린다.

검증: python3 scripts/check-work-docs.py rc=0, check-docs.py rc=0.
문제: experts.md 3절 「경로 → 전문가」는 리드가 바뀐 경로로 렌즈를
고르는 표이고 "지식 스킬의 paths와 맞춘다"고 적는다. 그런데 손으로 옮긴
표가 열 스킬 중 아홉에서 이미 갈라졌다. 예: be-build-ci의 settings.gradle·
gradle.properties·Dockerfile·renovate.json, be-api-contract의 .env.example·
docs/upgrade/**, be-observability의 docs/runbooks/**, be-docs의
**/CLAUDE.md가 표에 없다. 표로 렌즈를 고르면 그 파일을 바꾼 변경에서
렌즈가 빠진다. 이름만 보는 시험(test_the_experts_manual_names_every_expert)은
이 차이를 못 잡는다.

고른 방법: 표 1열을 1차 렌즈 스킬의 paths와 똑같이 고치고, 시험이
표를 읽어(중괄호 펼침) 스킬마다 "1차 렌즈로 이름 댄 행의 glob 합집합 ==
그 스킬의 paths"를 본다. 표 위 문장에 대조 시험이 있다고 적는다.
버린 대안: 표를 지우고 각 스킬 paths를 읽으라고만 쓰기 — 리드가 렌즈
하나를 고르려고 스킬 열 개의 머리를 읽어야 하고, 「이럴 때 더한다」 칸이
갈 곳이 없다.

위험·한계: 「이럴 때 더한다」 칸은 기계로 대조하지 않는다.

검증: 새 시험 test_the_experts_path_table_lists_exactly_each_skill_paths —
기준 표에서 9개 스킬 실패(be-domain만 통과), 고친 표에서 통과.
test_claude_setup 16건 통과, check-work-docs.py·check-docs.py rc=0.
문제: verify-api 서브에이전트는 desktop worktree에서
`flock /tmp/claude-gates/heavy.lock scripts/bootstrap-local.sh`를 직접 돌린다.
bootstrap-local.sh의 ./gradlew에는 --no-daemon이 없어 desktop에 Gradle
daemon이 남는다(여러 worktree를 받은 daemon이 compiler worker를 쌓아
메모리를 채운 일이 있다). 5단계가 따르라는 "4.1절의 정리법"은 operate.md에
없다.

고른 방법: `scripts/verify.sh app --on here`로 부른다. verify.sh가 공유
잠금을 잡고 GRADLE_OPTS로 daemon을 끈 채 같은 스크립트를 부른다. 앱은
compose로 떠 있으니 4단계 호출은 그대로다. 정리는 compose down과
git worktree remove만 적고, 못 지우면 보고에 남기게 한다.
버린 대안: bootstrap-local.sh의 ./gradlew에 --no-daemon을 붙이기 — 사람이
노트북에서 처음 돌릴 때는 daemon이 이득이라 스크립트 기본값은 두고,
desktop 쪽 진입점(verify.sh)이 끈다.

검증: test_verify_api_runs_the_app_on_the_desktop_under_the_shared_lock을
새 절차로 바꿨다(verify.sh app --on here와 git worktree remove를 요구하고,
잠금만 두른 직접 호출과 "정리법"을 거절). 기준 verify-api.md에서 실패,
고친 파일에서 통과. test_claude_setup 16건 통과.
문제: 결정 색인의 네 행이 지금 코드와 다른데 바뀌었다는 표시가 없다.
색인 1절 6번은 리뷰어가 정한 결정을 결함으로 올리지 않게 하므로, 낡은
행대로 읽은 리뷰어는 맞는 코드를 결함으로 올린다.

- 「문서 검사」: workflow `docs-check`는 2026-11-08 workflow를 셋으로 접으며
  없어졌다. 지금은 pr.yml done → :prCheck → documentCheck다.
- 「build-logic 의존성 잠금」: "잠그지 않음(보류)"인데 build-logic/build.gradle은
  2026-09-25 커밋부터 STRICT로 잠근다.
- 「릴리스 이미지 서명」: "cosign keyless"인데 2026-11-07 소유자가 키 쌍으로
  바꿨다(Gitea Actions가 OIDC 토큰을 주지 않음, operate.md 4.3절).
- 「workflow 명령의 빌드 판정」: "cd도 따라간다"인데 2026-11-08 셸을 해석하지
  않는 고정 형식 검사로 바꿨다(소유자가 고른 B안, StrictLaneStagesPlugin).

docs/README.md 「문서 검사」도 같은 `docs-check`를 가리켜 함께 고친다.

고른 방법: 1절 5번대로 원문을 지우지 않고 취소선과 "→ 바꿈"으로 새 위치를
가리키고, 서명 키와 job 모양은 새 행을 더한다.

위험·한계: build-logic 잠금을 언제 누가 바꾸기로 했는지 기록이 없다. 행에
"바꾼 결정의 기록은 없다"고 적었다. 소유자 확인이 필요하다.

검증: check-work-docs.py rc=0, check-docs.py rc=0.
스킬 수를 복사해 두면 스킬을 더하거나 뺄 때 낡는다(be-docs 함정 6). 목록의 정본은 .claude/skills/와 docs/work/experts.md 명단이다. 검증: check-work-docs.py rc=0(CLAUDE.md 10/10).
donghyeon.kang added 1 commit 2026-11-12 12:42:59 +00:00
문제: be-api-contract·be-domain·be-persistence·be-security의 「검증」 절이
"명령은 `src/`에서다"라고 한다. 분야 스킬은 Gradle 루트를 저장소 루트로
옮긴 뒤에 들어왔는데 옛 위치를 적었다. 그대로 따르면 gradlew가 없는
폴더에서 명령을 돌린다. operate.md 4.1절의 같은 꼴은 앞 커밋이 고쳤다.

고른 방법: 네 줄을 "저장소 루트에서다"로 고치고, 진입 문서(AGENTS.md·
CLAUDE.md·docs/work/·.claude/)에 "명령은 `src/`에서"나 `cd …/src`가 남으면
실패하는 시험을 둔다.

검증: 새 시험 test_no_instruction_runs_gradle_from_the_old_src_root —
기준 스킬 넷에서 4건, 기준 operate.md에서 2건(57·87줄)을 잡고, 이
커밋에서 통과. scripts/tests 158건 통과, check-work-docs.py rc=0.
donghyeon.kang added 1 commit 2026-11-12 13:28:02 +00:00
revert: operate.md 줄 줄이기를 PR #15에 맡긴다
pr / done (pull_request) Successful in 11m58s
d82a534d23
이 브랜치의 c0d7ad8f("operate.md를 150줄 안으로 줄이고 묶음 ID를
뺀다")를 되돌린다. 백엔드 CI 세션이 같은 줄을 PR #15(caa71d32)에서
다르게 고쳤고(4.4절 두 줄을 합쳐 150줄, ID 삭제), check-work-docs.py를
prCheck에 넣었다(13ed3a1d). 두 PR이 같은 줄을 고치면 병합 충돌이
난다.

위험·한계: PR #15가 병합되기 전에는 main의 operate.md가 151줄이고
"(W4 BE-OBS-A)"가 남아, 이 브랜치가 더한 ID 꼴 검사와 줄 수 검사로
check-work-docs.py가 rc=1이다. 지금 prCheck는 그 검사를 돌리지 않으므로
PR 단계는 막히지 않는다. #15가 병합되면 둘 다 풀린다.

검증: git diff origin/main -- docs/work/operate.md가 57·87줄의 /src
절차만 남는다. scripts/tests 158건 통과.
donghyeon.kang added 1 commit 2026-11-12 16:45:47 +00:00
Merge branch 'main' into claude/r9-docs-work
pr / done (pull_request) Canceled after 0s
04eb82139f
donghyeon.kang added 1 commit 2026-11-12 17:00:28 +00:00
Merge branch 'main' into claude/r9-docs-work
pr / done (pull_request) Successful in 11m55s
b7029ce7ce
donghyeon.kang merged commit d3a90479c5 into main 2026-11-12 18:58:54 +00:00
donghyeon.kang deleted branch claude/r9-docs-work 2026-11-12 18:58:54 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#16