문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.
고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.
위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).
검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
rc=0(3건)
6.6 KiB
6.6 KiB
작업 매뉴얼
이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다.
읽는 순서는 하나다: 루트 CLAUDE.md(지도) → 이 README → 맡은 일의 playbook 하나.
규칙의 정본은 AGENTS.md와 registry(src/config/architecture/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, 보안 정책. - 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다(research-design.md).
3. 모든 작업의 공통 단계
- 기준 커밋을 고정한다.
git rev-parse HEAD를 산출물과 보고에 적는다. - 이미 정한 것을 읽는다: reference/decisions.md,
docs/reviews/에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. - 소유 leaf를 찾는다. registry의
source_path로 정하고, 가장 가까운src/**/CLAUDE.md를 읽는다. - 스킬을 고른다. 정본은
AGENTS.md「Superpowers Workflow」다. playbook에 작업별 스킬이 있다. - 자기 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, 채우지 않은 칸)를 넣지 않는다.
5. 막혔을 때
- 소유자만 정할 수 있는 것(공개 계약, 파생 서비스 동작, 보안 정책, 새 leaf, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다.
- brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다.
- 묻는 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람.
6. 보고
- 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다.
- 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
- 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다.
- 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다.
- 사고 순서 흔적 칸을 둔다(
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 | 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법 |
| evidence.md | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID |
8. 이 폴더를 고칠 때
- 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄.
reference/는 상한이 없다. - 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 evidence.md로 옮긴다. 새 세션이 처음 읽는
AGENTS.md와src/**/CLAUDE.md도 같다. 모듈 README·설계 문서·docs/reviews/**는 ID를 둔다. - 이 폴더, 루트
CLAUDE.md,AGENTS.md,src/**/CLAUDE.md를 고친 뒤python3 scripts/check-work-docs.py가 통과해야 한다. 절차는 docs-writing.md다.