Files
clean-architecture-frontend…/docs/work/research-design.md
T
DongHyeonka 3524d6b00b docs(work): 작업 매뉴얼 docs/work/를 두고 개선 매뉴얼 초안을 흡수한다
프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 CLAUDE.md의
리뷰 기준만 읽고 시작했고, 개선 작업 기준은 main에 들어가지 않은 초안
(브랜치 docs/improvement-manual의 docs/improvement 11개)에만 있었다.

백엔드 docs/work/와 같은 모양으로 README(크기·공통 단계·커밋·보고),
playbook 여섯(new-feature, improve, research-design, docs-writing,
operate, delegate, 모두 같은 9절 뼈대), reference 일곱(gates,
review-criteria, structure, testing, performance, defect-patterns,
decisions)과 evidence.md를 둔다. 초안의 장을 나눠 옮긴 표는
evidence.md 1.1절이다. SPEC.md의 공통 완료 기준 9개는 improve.md 5절로
옮겨, 문서 체계 정리가 SPEC.md를 이력으로 옮길 수 있게 한다.

진입 문서에는 지난 리뷰 ID를 쓰지 않고 내용과 날짜로 쓴다. ID는
evidence.md와 결정·결함 패턴 색인에만 둔다. 결함 패턴 번호 P-NN은
결정 번호 꼴과 겹쳐 영역 글자+번호(G·T·C·S·W·B)로 다시 매기고 옛
번호 대응을 evidence.md 4절에 남겼다. 열린 결정 대기는 2026-11-06
리뷰 기준으로 갱신했다.

버린 대안: 초안처럼 docs/improvement/ 장 번호 체계를 유지하기. 백엔드와
진입 경로·검사기가 갈라진다.

위험·한계: 이 커밋만으로는 문서 검사 범위 밖이다. docs/README.md가 이
폴더를 링크하는 커밋부터 verify:documentation이 경로를 본다. cold-read
시험은 하지 않았다.

검증: python3 scripts/check-work-docs.py rc=0(뒤 커밋에서 더함).

Refs: design-docs harness/01-harness-design.md 13절, PR #6
2026-11-08 17:27:39 +09:00

7.4 KiB

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

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

1. 언제 쓰나

  • 고치거나 만들기 전에 소유자 결정이 필요하다: import 규칙, adapter 배럴의 공개 표면, 게이트 단계·기준, 짝 백엔드 계약, 런타임 설정 키, 파생 프로젝트 동작, 보안 정책, 되돌리기 비싼 선택.
  • 리뷰가 「결정이 필요한 것」으로 남긴 항목을 어떻게 닫을지 정해야 한다.
  • 큰 일의 1~5단계와 대안 비교를 소유자 검토용으로 만든다. 설계 메모 하나를 쓴다.
  • 결정이 이미 reference/decisions.md에 있으면 이 playbook이 아니다. 그 결정대로 improve.md나 new-feature.md로 간다.

2. 받아야 할 것

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

3. 크기와 사고 순서

  • 설계 메모 하나는 보통 중간이다: 선행 사례 23곳(내부 선례 포함), 대안 23개. 다루는 대상이 README 2절의 "파일 하나여도 큼" 표면이어도 메모만 쓰고 바꾸지 않으면 중간이다. 큼은 그 메모를 적용하는 일이다.
  • 새 체계·아키텍처·공개 계약은 큼이다: 선행 사례 1015곳, 대안 35개. 1~5단계 결과와 대안 비교를 소유자가 먼저 본다.
  • 이 repo의 내부 선례를 찾는 곳:
    • reference/decisions.md와 그 출처 문서
    • docs/reviews/의 리뷰 README 「결정이 필요한 것」「조치」 절
    • docs/architecture/decisions/(오래 가는 구조·기술 선택), docs/architecture/의 설계 문서(현재 계약인지 목표 설계인지는 docs/README.md 묶음으로 본다)
    • git log --oneline -- <경로>와 커밋 본문의 "고른 방법과 버린 대안"
    • 규칙 예외의 이유·담당·재검토 조건: 그 규칙의 comment(.dependency-cruiser.json)
  • 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(React, Vite, TanStack Query, Playwright 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다.
  • 스킬: superpowers:brainstorming, 결정 기록은 documentation-and-adrs, 공식 문서 확인은 source-driven-development. 큰 판단은 doubt-driven-development로 반론을 세운다.

4. 절차

  1. 목적을 한 문장으로 적고 성공 기준을 정한다. 요청 원문이 있으면 인용한다.
  2. 이미 정한 것을 찾는다(3절의 내부 선례). 이미 정해져 있으면 멈추고 그 결정을 보고한다.
  3. 현황을 확인한다. 주장마다 출처를 단다: file:line, 커밋, 명령 결과. 확인한 사실 / 기록된 의도 / 추론을 나눈다(리뷰 가이드 41.3절). 코드 읽기로 동작이 하나로 정해지지 않으면 별도 worktree에서 탐침 테스트를 desktop으로 돌리고(scripts/verify.sh script), 탐침 코드는 남기지 않는다.
  4. 선행 사례 표를 만든다: 출처 · 1차/2차 · 그들이 한 것 · 실패와 비판 · 가져올 것.
  5. 대안을 비교한다. 실제로 다른 대안 2~5개(크기에 맞게), 기준(효과, 비용, 되돌리기, 파생 프로젝트 영향, 기존 결정과 충돌, 초기 JS·예산 영향), 권하는 안과 이유. 파생 프로젝트 영향은 그 repo에서 바꿀 이름(파일, 키, 타입)을 git grep해 쓰는 곳을 센다.
  6. 반증할 수 있는 가정을 적는다: "이 안이 틀렸다면 어디서 드러나나". 재검토 조건(어떤 규모·버전·계약 변화가 결론을 바꾸나)과 반론·답도 적는다.
  7. 산출물을 둔다.
    • 이 repo에만 해당하고 오래 가는 선택: docs/architecture/decisions/의 결정 기록(기존 번호를 잇는다, 머리 블록은 docs/README.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 「결정」 절부터 본다.
  • 짝 백엔드 사실을 계약 문서 문장만으로 정한다. 백엔드 코드와 이 repo의 pin(config/contracts/backend-contract-pin.json)까지 따라간다.
  • 조사하다 바로 고친다. 고치는 일은 결정 뒤에 다른 playbook으로 한다.