3장 결정 기록과 근거
결정은 기억이 아니라 기록으로 남깁니다. 기록에는 결정만이 아니라 이유, 검토한 다른 선택지, 근거를 얼마나 확실히 확인했는지를 함께 적습니다.
왜 필요한가
규칙만 남고 이유가 사라지면 같은 질문이 다시 나옵니다. 새 구성원이나 에이전트는 이미 검토하고 버린 안을 다시 제안합니다. 근거가 기억이나 추정이면 더 위험합니다. 나중에 틀린 것으로 드러났을 때는 이미 그 근거 위에 파일과 커밋과 문서가 쌓여 있어 되돌리는 비용이 큽니다. 처음 인용할 때 확실성을 표시하는 편이 나중에 번복하는 것보다 훨씬 쌉니다.
원칙
결정 기록
결정 기록(ADR, architecture decision record)은 하나의 결정과 그 이유를 적은 문서입니다. leysys-designdocs/decisions/에는 2026-10-04 KST 기준 632건이 있고, 그중 621건은 SIZE-SCALE-SYMMETRIC-AXIOM-2026-05-25.md처럼 주제와 날짜로 이름을 짓습니다. 최근 기록이 대체로 갖는 요소는 다음과 같습니다.
| 요소 | 담는 것 |
|---|---|
| 상태·날짜·범위 | 확정·대체 여부, 결정일, 영향을 받는 패키지와 저장소 |
| 배경 | 문제와 실측한 결함 |
| 결정과 근거 | 무엇을 하기로 했고 무엇을 근거로 삼았는지 |
| 검토한 다른 선택지 | 채택하지 않은 안과 그 이유 |
| 백지 기준과 이행 비용 | 백지에서의 정답과 지금부터의 비용을 나눈 판단(2장) |
| 검증과 상태 | 실행한 검사, 게시·채택이 어디까지 되었는지 |
기록은 지우지 않습니다. 새 결정이 옛 결정을 대체하면 옛 기록에 「Superseded → 새 문서」를 달고 역사로 남깁니다. 바꾸지 않기로 한 결정도 남깁니다. KEEP-AS-IS.md는 검토한 뒤 의도적으로 현행을 유지하기로 한 항목을 모은 문서입니다. 게시하지 않기로 한 버전도 결정 기록으로 남깁니다(4장).
오너 결정과 버린 선택지
결정은 사람이 합니다. 큰 결정에는 오너가 정한 내용과 함께 검토한 다른 선택지를 적습니다. 나중에 같은 질문을 다시 하지 않기 위해서입니다. 접근 역할 체계의 결정 기록에는 「오너 결정」 여덟 건이 있고, 건마다 버린 안과 이유가 있습니다. 업무 데이터를 다루는 등급의 이름은 editor(편집자)로 정했고, 다음 안을 버렸습니다.
- 라벨 「실무자」 — 대상(audience) 어휘와 겹칩니다.
manager(매니저) — 이행 비용은 가장 적지만 사내에서 세 가지 뜻으로 쓰입니다.member(구성원) — 제품의 멤버·명부 레코드와 겹칩니다.
약점도 숫자로 남깁니다. 컬러 모델 rev 4를 다시 검증한 기록은 500 단계에서 흰 글자와의 대비가 WCAG AA(4.5:1)를 넘는 색이 채택한 17개 중 4개뿐이라고 적고, 이를 차단이 아닌 알림으로 관리한다고 정했습니다. 함께 검토한 대안 둘은 채택하지 않되 재검토 자료로 남겼습니다(9장).
근거의 확실성 등급
벤치마크나 외부 자료를 근거로 쓸 때는 얼마나 확실히 확인했는지 등급을 붙입니다. 태그가 없으면 독자는 실측으로 읽기 때문입니다.
| 등급 | 태그 | 뜻 | 결정 근거로 |
|---|---|---|---|
| T1 실측 | [실측] | 이번 작업에서 직접 열어 보거나 파일을 읽거나 측정함 | 쓸 수 있음 |
| T2 문서 재인용 | [문서 재인용: 출처] | 작성 당시 실측했던 내부 문서를 인용함 | 출처를 밝히면 쓸 수 있음 |
| T3 추정 | [추정] | 기억이나 일반 지식 | 쓸 수 없음. 초안과 선택지 나열에만 |
| T4 미확인 | [확인 필요] | 인용 자체가 불확실함 | 경고 표시. 진행 여부를 사람에게 물음 |
CSS 선택자가 실제로 참조하는 값, 외부 디자인 시스템의 어휘와 수치, 렌더링과 specificity 판단은 반드시 T1이어야 합니다. 결정에 쓰는 숫자는 T1이나 T2만 쓰고 T3로는 결정하지 않습니다. Switch의 손잡이 부품 이름을 정할 때 「토큰 이름이 thumb이니 thumb」이라는 근거만으로 정할 뻔했습니다. 사람의 지적을 받고 Nuxt UI·shadcn/ui·Material Design 3의 공식 문서를 직접 열어 세 곳 모두 thumb을 쓰는 것을 확인한 뒤 확정했습니다.
공식 출처와 공식 API
외부 참조는 공식 출처만 근거로 셉니다. shadcn/ui는 ui.shadcn.com, Nuxt UI는 ui.nuxt.com입니다. 포크나 커뮤니티 판(예: shadcn-vue.com)은 보조 참고일 뿐 근거로 세지 않습니다.
외부 라이브러리는 공식 문서에 공개된 API만 씁니다. 내부 자식 요소 선택자, 문서에 없는 이벤트, 소스 코드를 읽고 짐작한 lifecycle, 공개되지 않은 내부 token이나 CSS 변수에는 기대지 않습니다. 메이저 업그레이드에서 예고 없이 깨지기 때문입니다. 스타일이 맞지 않으면 공식 테마와 문서화된 props·slots 안에서 비슷하게만 맞추고, 자체 토큰을 억지로 밀어 넣지 않습니다.
허용되는 예도 분명합니다. Combobox 목록의 폭을 입력란 폭에 맞출 때 Reka UI가 공식으로 내보내는 CSS 변수 --reka-combobox-trigger-width를 썼습니다. Radix의 data-state="open"처럼 공식 문서가 공개한 data 속성도 쓸 수 있습니다. 회사 공통 기준도 같은 규칙을 둡니다(웹 라이브러리 선택 기준).
정직성
실행하지 않은 것을 했다고 말하지 않고, 확인하지 않은 것을 확인했다고 말하지 않습니다. 「빌드 PASS」, 「전수 검사 완료」는 실제로 실행했을 때만 씁니다. 모르면 「확인 필요」라고 씁니다. 사람이 다시 검토해 달라고 하면 바로 다시 검토하고, 틀렸으면 바로 정정합니다.
실제 예 — 정정도 기록입니다
접근 역할 체계를 정한 뒤 오너의 질문을 받고 원본을 다시 확인하다가, 독립된 두 설계안이 함께 낸 주장 하나가 틀렸음을 발견했습니다. 결정 문서 본문은 그 주장을 쓰지 않았지만 검토 기록에 정정 내용과 발견 경위를 적었고, 두 설계안의 원문은 기록이므로 고치지 않았습니다. 개인정보 열람 기록의 위치를 정할 때는 법령 조항 원문을 확인하지 못해 조항을 적지 않았다고 밝혔습니다.
초안이 틀린 것으로 드러났을 때의 절차도 정해 두었습니다. 즉시 멈추고, 어디서 무엇을 확인했는지 보고하고, 그 초안을 근거로 만든 문서·커밋·파일을 모두 찾아 정정합니다. 정정할 때는 원래 판단을 지우지 않고 이유와 함께 남기며, 혼자 고치지 않고 사람에게 알립니다. 번복 기록이 사라지면 다음 작업에서 같은 오판을 반복하기 때문입니다.
경계와 예외
- 결정 기록은 결정을 남기는 문서입니다. 해설과 교육은 이 책 같은 해설판이 맡고, 값이 다르면 정본이 맞습니다.
- 외부 벤치마크는 근거이지 정답이 아닙니다. 모델의 값은 공리에서 도출하고, 외부 수치로 보정하지 않습니다.
- 라이브러리 소스 코드를 읽는 일은 플러그인 같은 기능이 있는지 확인하는 데까지만 씁니다. 결정 근거에는 문서화된 공식 API만 인용합니다.
- 이 책도 같은 규칙을 따릅니다. 외부 디자인 시스템 비교는 정본 문서에 공식 출처와 함께 적힌 것만 옮깁니다.
정리
- 결정은 이유·버린 선택지·검증 상태와 함께 기록하고, 대체된 기록도 지우지 않습니다.
- 결정은 사람이 하고, 기록은 오너 결정과 함께 검토한 다른 선택지를 남깁니다.
- 근거에는 T1 실측부터 T4 미확인까지 확실성 등급을 붙이고, 추정은 결정 근거로 쓰지 않습니다.
- 외부 자료는 공식 출처만, 외부 라이브러리는 공식 API만 씁니다.
- 실행하지 않은 것을 했다고 말하지 않고, 정정도 기록으로 남깁니다.
정본
leysys-designdocs/decisions/— 결정 기록 전체(2026-10-04 KST 기준 632건)leysys-designdocs/process/BENCHMARK-CITATION-CONVENTION.md— T1–T4 인용 등급과 정정 절차leysys-designdocs/decisions/KEEP-AS-IS.md— 검토 후 현행을 유지한 결정leysys-designdocs/decisions/COLOR-MODEL-REV4-CONTRAST-ALERT-ONLY-2026-09-28.md— 대안과 약점을 함께 남긴 예leysys-designdocs/decisions/COMBOBOX-TRIGGER-WIDTH-SYNC-2026-05-07.md— 공식 CSS 변수를 쓴 예leysys-designdocs/reviews/ACCESS-ROLE-SYSTEM-DESIGN-REVIEW-2026-10-03.md— 정정과 원문 보존의 예leysys-designAGENTS.md— 정직성, 외부 참조, 외부 라이브러리 공식 API 규칙- 웹 라이브러리 선택 기준 — 회사 공통 라이브러리 도입 규칙