Files
clean-architecture-backend-…/docs/work/research-design.md
T
DongHyeonka 73d39212f5 docs(work): cold-read 시험 1회차의 빈틈과 모순을 매뉴얼에 반영한다
문제: 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을
시켰다. 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 세션마다
1~9건 나왔고, 세 곳은 문서끼리 다르게 말했다.
- 리뷰 README를 누가 쓰나: delegate.md는 총괄, improve.md는 리뷰어
- push: README 4절·decisions.md는 "커밋을 허용하면 push도", 정본
  delegation-loop.md 11절은 brief가 push를 따로 허용해야 한다
- evidence.md 머리말은 "RR-는 1차 재리뷰"라는데 round2도 RR-를 썼다

고른 방법:
- 리뷰어는 README에 자기 라운드 색인 절 하나만 쓰고, 처리 표·결정의
  답·게이트 기록은 총괄이 쓴다(improve.md 4.1, delegate.md 4.2,
  decisions.md 2.1)
- 커밋과 push는 brief 7절이 따로 허용한다. 커밋만 허용되면 push하지
  않는다. push 없이도 패치와 트리 해시로 desktop에서 검증한다
  (operate.md 4.1 「push 전에 검증하기」). 이 방법은 커밋 본문에
  desktop 결과를 넣으려는 세션의 빈틈도 닫는다
- evidence.md 머리말을 접두어별 문서로 고친다
- 나머지 빈틈은 그 일을 하는 playbook의 절차 단계나 자주 하는 실수,
  reference에 한 줄씩 넣는다. 36행 처리 표는 evidence.md 9절이다
  (고침 35, 고치지 않음 1: 새 매뉴얼에 이미 답이 있던 것)
버린 대안: push를 "커밋 허용이면 push도"로 읽기. 정본 11절과 실제
brief(백엔드는 push, design-docs는 push 안 함)가 push를 따로 다룬다.
버린 대안: 빈틈을 모두 자주 하는 실수에 넣기. 10줄 상한을 넘고, 절차의
한 단계인 것은 그 단계에 있어야 읽힌다.

위험·한계:
- 리뷰 README 분담, push를 따로 읽는 것, 하위 세션 Slack은 기본값이다.
  소유자가 뒤집을 수 있게 decisions.md에 기본값으로 적었다
- AGENTS.md의 커밋 예외 문장은 이번 범위 밖이라 그대로다. 세부는 이
  README 4절을 가리키므로 README가 정한다
- 고친 매뉴얼은 2회차 cold-read 시험 전이다

검증:
- python3 scripts/check-work-docs.py rc=0. 지도 73/120, README 76/80,
  improve.md 134/150, 진입 경로 최대 283/350, 본문 이력 0줄
- python3 scripts/check-work-docs.py --links docs CLAUDE.md 결과 링크
  432개, 깨진 것 0
- desktop: 바꾼 것을 패치로 기준 커밋 2c8a359d 위에 얹어 노트북과 같은
  트리 3d0e5900을 만들고 flock 아래
  :app-bootstrap:documentContractTest --rerun rc=0, 66건 실패 0
  건너뜀 0, 13초, 직전 1분 부하 3.13
  (desktop ~/manual-gap-fix-1-logs/documentContractTest.log)
2026-11-06 23:18:47 +09:00

7.3 KiB

조사·설계 — 바꾸기 전에 대안을 비교하고 결정을 받는다

코드를 바꾸기 전에 무엇을 할지 정하는 일이다. 사고 순서(목적 → 선행 사례 → 방법 → 필요한 정보 → 격차 → 만들고 시험)의 정본은 design-docs conventions/work-thinking-order.md다. 이 playbook은 순서를 다시 쓰지 않고, 이 repo에서 어디를 보고 결과를 어디에 두는지만 정한다.

1. 언제 쓰나

  • 고치거나 만들기 전에 소유자 결정이 필요하다(공개 계약, 파생 서비스 동작, 보안 정책, 새 leaf, 되돌리기 비싼 선택).
  • 리뷰가 "판단하지 않음"으로 남긴 항목을 어떻게 닫을지 정해야 한다.
  • 큰 일의 1~5단계와 대안 비교를 소유자 검토용으로 만든다.
  • 설계 메모 하나를 쓴다(예: 레지스트리의 칸 하나를 규범으로 둘지).
  • 결정이 이미 reference/decisions.md에 있으면 이 playbook이 아니다. 그 결정대로 improve.md나 new-feature.md로 간다.

2. 받아야 할 것

  • 정할 질문 한 문장과 누가 왜 묻는가(요청 원문).
  • 크기와 결정할 사람. 큼이면 소유자 검토가 만들기 전에 있어야 한다.
  • 산출물 위치(4절 6단계 기준과 다르면 brief를 따른다).
  • 코드를 바꿔도 되는지. 기본은 바꾸지 않는다.

3. 크기와 사고 순서

  • 설계 메모 하나는 보통 중간이다: 선행 사례 23곳(내부 선례 포함), 대안 23개. 다루는 대상이 README 2절의 "파일 하나여도 큼" 표면(오류 코드 레지스트리 등)이어도 메모만 쓰고 바꾸지 않으면 중간이다. 큼은 그 메모를 적용하는 일이다(design-docs conventions/work-thinking-order.md 2.1절).
  • 새 체계·아키텍처·공개 계약은 큼이다: 선행 사례 1015곳, 대안 35개. 1~5단계 결과와 대안 비교를 소유자가 먼저 본다.
  • 이 repo의 내부 선례를 찾는 곳:
    • reference/decisions.md와 그 출처 문서
    • docs/reviews/의 리뷰 README 「결정」 절과 영역 문서의 「Declined to judge」
    • docs/adr/(되돌리기 비싼 선택), docs/superpowers/specs/(설계서), docs/superpowers/plans/(계획서)
    • git log --oneline -- <경로>와 커밋 본문의 "고른 방법과 버린 대안"
    • 가장 가까운 src/**/CLAUDE.md와 모듈 README
  • 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(Spring Boot, Flyway, Hibernate 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다.
  • 스킬: superpowers:brainstorming, 결정 기록은 documentation-and-adrs, 공식 문서 확인은 source-driven-development. 큰 판단은 doubt-driven-development로 반론을 세운다.

4. 절차

  1. 목적을 한 문장으로 적고 성공 기준을 정한다. 요청 원문이 있으면 인용한다.
  2. 이미 정한 것을 찾는다(3절의 내부 선례). 이미 정해져 있으면 멈추고 그 결정을 보고한다.
  3. 현황을 확인한다. 주장마다 출처를 단다: file:line, 커밋, 명령 결과. 코드 읽기로 동작이 하나로 정해지지 않으면(분기, 동시성, 설정·외부 시스템에 따라 다름) 별도 worktree에서 탐침 테스트를 desktop으로 돌리고, 탐침 코드는 남기지 않는다. 분기 없는 경로이고 기존 테스트가 그 동작을 고정하면 탐침을 생략하고, 그 테스트 이름을 출처로 적는다.
  4. 선행 사례 표를 만든다: 출처 · 1차/2차 · 그들이 한 것 · 실패와 비판 · 가져올 것.
  5. 대안을 비교한다. 실제로 다른 대안 2~5개(크기에 맞게), 기준(효과, 비용, 되돌리기, 파생 서비스 영향, 기존 결정과 충돌), 권하는 안과 이유. 의존 순서가 있는 변경은 의존 그래프 순서로 따진다. 파생 서비스 영향은 파생 서비스 repo에서 바꿀 이름(키, 칸, 타입)을 git grep해 쓰는 곳을 센다. 소유자 환경의 파생 서비스 위치는 design-docs conventions/delegation-loop.md 11절이다.
  6. 반증할 수 있는 가정을 적는다: "이 안이 틀렸다면 어디서 드러나나". 반론과 답도 적는다.
  7. 산출물을 둔다.
    • 이 repo에만 해당: 설계서 docs/superpowers/specs/<YYYY-MM-DD>-<주제>-design.md, 되돌리기 비싼 선택이면 docs/adr/ADR-<영역>-<번호>-<제목>.md(기존 번호를 잇는다).
    • 여러 repo나 소유자 운영에 걸침: design-docs. 템플릿 docs/는 파생 서비스로 복사되므로 로드맵·운영 설계는 여기에 두지 않는다.
    • 짧은 설계 메모는 보고 본문으로 충분하다(brief가 파일을 요구하지 않으면).
  8. 소유자 결정 목록을 쓴다: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람. 한 번에 묻는다.
  9. 멈추고 검토를 받는다. 승인을 받으면 승인 시각을 적는다.
  10. 결정을 기록한다(reference/decisions.md 3절). 만들기는 new-feature.md나 improve.md로 넘긴다.

5. 완료 기준

  • 보고에 사고 순서 흔적이 있다. 크기에 맞는 단계가 있고, 생략한 단계는 이유가 한 줄 있다.
  • 사실마다 출처(file:line, 커밋, 명령 결과)가 있다. 추정은 추정이라고 적었다.
  • 대안 비교 표, 권하는 안, 반증할 수 있는 가정이 있다.
  • 소유자 결정 목록이 있고, 질문을 보냈거나 승인 시각이 있다.
  • brief가 허용하지 않았으면 코드가 바뀌지 않았다(git diff --stat에 문서만).

6. 하지 말 것

  • 소유자 검토 전에 만들지 않는다. 큰 일은 1~5단계와 대안 비교까지만 하고 멈춘다.
  • 크기를 스스로 내리지 않는다.
  • 이미 정한 결정을 다시 묻지 않는다. 다시 열 조건은 reference/decisions.md 1절이다.
  • "업계 표준이다", "추상화가 많다" 같은 말을 근거로 쓰지 않는다. 이 repo의 어느 계약·비용에 닿는지로 쓴다.
  • 대안을 하나만 놓고 권하지 않는다.
  • 탐침 코드를 제품 코드에 남기지 않는다.

7. 막혔을 때

  • 필요한 정보가 이 repo와 공개 자료에 없으면(운영 수치, 소유자의 계획) 그 칸을 "모름"으로 두고 질문 목록에 넣는다.
  • 질문은 한 번에 모아 보낸다. 형식은 README 5절이다. 답이 올 때까지 그 결정에 기대는 단계만 멈춘다.

8. 보고 형식

README 6절에 더해 적는다.

## 결론 (권하는 안 한 문장)
## 사고 순서 흔적 (크기: 중간)
1. 목적: 2. 선행 사례: 3. 방법: 4. 필요한 정보: 5. 격차: 6. 만들고 시험:
## 대안 비교
| 대안 | 효과 | 비용 | 되돌리기 | 기존 결정과 충돌 |
## 반증할 수 있는 가정 / 반론과 답
## 소유자가 정할 것
| 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 |

9. 자주 하는 실수

  • 정리한 글(2차)을 원문처럼 인용한다. 원문을 찾아 확인하고 1차/2차를 표시한다.
  • 지난 리뷰의 결정을 찾지 않아 같은 질문을 다시 한다. 결정 색인과 리뷰 README 「결정」 절부터 본다.
  • 조사하다 바로 고친다. 고치는 일은 결정 뒤에 다른 playbook으로 한다.