문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와 리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이 "이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는 없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지), 커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음). 고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs delegation-loop/02-design.md 4~6·10절): - CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본 AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는 곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던 내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은 reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절. - docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개 (new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns, decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고 review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에 나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고, improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다. - improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과 수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난 수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25, +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다. - 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를 README 4절과 AGENTS.md에 같은 말로 적었다. - 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인 (reference/decisions.md, reference/defect-patterns.md)에만 둔다. - 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md, docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운 CLAUDE.md 「Layer workflow」를 가리키던 줄). 위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라 초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어 docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/ 본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의 성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다. 검증 - python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80, playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄 - python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0 - CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest .guidanceNamesTheArchitectureSourceSetTask가 기대하는 "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는 이 커밋을 push한 뒤 desktop에서 돌린다
91 lines
6.6 KiB
Markdown
91 lines
6.6 KiB
Markdown
# 조사·설계 — 바꾸기 전에 대안을 비교하고 결정을 받는다
|
|
|
|
코드를 바꾸기 전에 무엇을 할지 정하는 일이다. 사고 순서(목적 → 선행 사례 → 방법 → 필요한 정보 → 격차 → 만들고 시험)의 정본은 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개.
|
|
- 새 체계·아키텍처·공개 계약은 큼이다: 선행 사례 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개(크기에 맞게), 기준(효과, 비용, 되돌리기, 파생 서비스 영향, 기존 결정과 충돌), 권하는 안과 이유. 의존 순서가 있는 변경은 의존 그래프 순서로 따진다.
|
|
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](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으로 한다.
|