# 조사·설계 — 바꾸기 전에 대안을 비교하고 결정을 받는다 코드를 바꾸기 전에 무엇을 할지 정하는 일이다. 사고 순서(목적 → 선행 사례 → 방법 → 필요한 정보 → 격차 → 만들고 시험)의 정본은 design-docs `conventions/work-thinking-order.md`다. 이 playbook은 순서를 다시 쓰지 않고, 이 repo에서 어디를 보고 결과를 어디에 두는지만 정한다. ## 1. 언제 쓰나 - 고치거나 만들기 전에 소유자 결정이 필요하다(공개 계약, 파생 서비스 동작, 보안 정책, 새 leaf, 되돌리기 비싼 선택). - 리뷰가 "판단하지 않음"으로 남긴 항목을 어떻게 닫을지 정해야 한다. - 큰 일의 1~5단계와 대안 비교를 소유자 검토용으로 만든다. - 설계 메모 하나를 쓴다(예: 레지스트리의 칸 하나를 규범으로 둘지). - 결정이 이미 [reference/decisions.md](reference/decisions.md)에 있으면 이 playbook이 아니다. 그 결정대로 [improve.md](improve.md)나 [new-feature.md](new-feature.md)로 간다. ## 2. 받아야 할 것 - 정할 질문 한 문장과 누가 왜 묻는가(요청 원문). - 크기와 결정할 사람. 큼이면 소유자 검토가 만들기 전에 있어야 한다. - 산출물 위치(4절 6단계 기준과 다르면 brief를 따른다). - 코드를 바꿔도 되는지. 기본은 바꾸지 않는다. ## 3. 크기와 사고 순서 - 설계 메모 하나는 보통 중간이다: 선행 사례 2~3곳(내부 선례 포함), 대안 2~3개. 다루는 대상이 [README](README.md) 2절의 "파일 하나여도 큼" 표면(오류 코드 레지스트리 등)이어도 메모만 쓰고 바꾸지 않으면 중간이다. 큼은 그 메모를 적용하는 일이다(design-docs `conventions/work-thinking-order.md` 2.1절). - 새 체계·아키텍처·공개 계약은 큼이다: 선행 사례 10~15곳, 대안 3~5개. 1~5단계 결과와 대안 비교를 소유자가 먼저 본다. - 이 repo의 내부 선례를 찾는 곳: - [reference/decisions.md](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/-<주제>-design.md`, 되돌리기 비싼 선택이면 `docs/adr/ADR-<영역>-<번호>-<제목>.md`(기존 번호를 잇는다). - 여러 repo나 소유자 운영에 걸침: design-docs. 템플릿 `docs/`는 파생 서비스로 복사되므로 로드맵·운영 설계는 여기에 두지 않는다. - 짧은 설계 메모는 보고 본문으로 충분하다(brief가 파일을 요구하지 않으면). 8. 소유자 결정 목록을 쓴다: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람. 한 번에 묻는다. 9. 멈추고 검토를 받는다. 승인을 받으면 승인 시각을 적는다. 10. 결정을 기록한다([reference/decisions.md](reference/decisions.md) 3절). 만들기는 [new-feature.md](new-feature.md)나 [improve.md](improve.md)로 넘긴다. ## 5. 완료 기준 - 보고에 사고 순서 흔적이 있다. 크기에 맞는 단계가 있고, 생략한 단계는 이유가 한 줄 있다. - 사실마다 출처(`file:line`, 커밋, 명령 결과)가 있다. 추정은 추정이라고 적었다. - 대안 비교 표, 권하는 안, 반증할 수 있는 가정이 있다. - 소유자 결정 목록이 있고, 질문을 보냈거나 승인 시각이 있다. - brief가 허용하지 않았으면 코드가 바뀌지 않았다(`git diff --stat`에 문서만). ## 6. 하지 말 것 - 소유자 검토 전에 만들지 않는다. 큰 일은 1~5단계와 대안 비교까지만 하고 멈춘다. - 크기를 스스로 내리지 않는다. - 이미 정한 결정을 다시 묻지 않는다. 다시 열 조건은 [reference/decisions.md](reference/decisions.md) 1절이다. - "업계 표준이다", "추상화가 많다" 같은 말을 근거로 쓰지 않는다. 이 repo의 어느 계약·비용에 닿는지로 쓴다. - 대안을 하나만 놓고 권하지 않는다. - 탐침 코드를 제품 코드에 남기지 않는다. ## 7. 막혔을 때 - 필요한 정보가 이 repo와 공개 자료에 없으면(운영 수치, 소유자의 계획) 그 칸을 "모름"으로 두고 질문 목록에 넣는다. - 질문은 한 번에 모아 보낸다. 형식은 [README](README.md) 5절이다. 답이 올 때까지 그 결정에 기대는 단계만 멈춘다. ## 8. 보고 형식 [README](README.md) 6절에 더해 적는다. ```markdown ## 결론 (권하는 안 한 문장) ## 사고 순서 흔적 (크기: 중간) 1. 목적: 2. 선행 사례: 3. 방법: 4. 필요한 정보: 5. 격차: 6. 만들고 시험: ## 대안 비교 | 대안 | 효과 | 비용 | 되돌리기 | 기존 결정과 충돌 | ## 반증할 수 있는 가정 / 반론과 답 ## 소유자가 정할 것 | 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 | ``` ## 9. 자주 하는 실수 - 정리한 글(2차)을 원문처럼 인용한다. 원문을 찾아 확인하고 1차/2차를 표시한다. - 지난 리뷰의 결정을 찾지 않아 같은 질문을 다시 한다. 결정 색인과 리뷰 README 「결정」 절부터 본다. - 조사하다 바로 고친다. 고치는 일은 결정 뒤에 다른 playbook으로 한다.