init: 클린 기반 auth 서버 설계

2026-07-24 14:30:18 +09:00
parent 471db0203d
commit 8a1ac1e769
3642 changed files with 275893 additions and 1 deletions
@@ -0,0 +1,17 @@
+# Documentation Templates
+
+새 문서를 시작할 때 기본 골격으로 사용한다. 이 repo 는 *ADR* 과 *트러블슈팅 / 런북* 두 축 + 토픽 README + 아키텍처 설명만 다루므로 템플릿도 5 개로 압축되어 있다.
+
+| 템플릿 | 용도 |
+|--------|------|
+| [topic-readme-template.md](./topic-readme-template.md) | `docs/topics/<n>-<topic>/` 폴더의 시작 README |
+| [architecture-template.md](./architecture-template.md) | 구조와 내부 동작 설명 |
+| [adr-template.md](./adr-template.md) | 기술 선택 근거 기록 |
+| [runbook-template.md](./runbook-template.md) | 운영 절차 |
+| [troubleshooting-template.md](./troubleshooting-template.md) | 문제 해결 기록 |
+
+## 사용 규칙
+
+- 템플릿은 그대로 두고, 새 문서를 만들 때 복사해서 사용한다.
+- 문서를 추가하면 관련 `README.md` 에 링크를 함께 넣는다.
+- 템플릿을 쓰더라도 *대안 비교* 와 *트레이드오프* 는 생략하지 않는다.
@@ -0,0 +1,50 @@
+# ADR-00X: [결정 제목]
+
+## Status
+
+Proposed | Accepted | Superseded | Deprecated
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+결정이 필요했던 배경과 요구사항을 적습니다.
+
+## Decision Drivers
+
+- 
+- 
+
+## Considered Options
+
+### Option 1: [선택지 이름]
+
+- 장점:
+- 단점:
+- 트레이드오프:
+
+### Option 2: [선택지 이름]
+
+- 장점:
+- 단점:
+- 트레이드오프:
+
+## Decision
+
+최종적으로 무엇을 선택했는지 한 문장으로 적습니다.
+
+## Consequences
+
+### 긍정적 결과
+
+- 
+
+### 부정적 결과
+
+- 
+
+### 위험 완화
+
+- 
@@ -0,0 +1,91 @@
+# [주제명] 아키텍처
+
+## 1. Context & Scope
+
+### 목적
+
+이 문서가 설명하려는 범위를 적습니다.
+
+### Scope
+
+- 포함:
+- 제외:
+
+## 2. Why
+
+- 이 구조가 해결하려는 문제는 무엇인가?
+- 대안 구조는 무엇이었는가?
+- 왜 이 구조를 선택했는가?
+
+## 3. Goals & Non-Goals
+
+### Goals
+
+- 
+
+### Non-Goals
+
+- 
+
+## 4. Architecture Overview
+
+### 4.1 전체 구조
+
+```mermaid
+flowchart LR
+  A[Client] --> B[System]
+```
+
+### 4.2 핵심 컴포넌트
+
+- 컴포넌트 A:
+- 컴포넌트 B:
+
+## 5. How It Works
+
+### 5.1 요청/데이터 흐름
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant System
+  Client->>System: Request
+  System-->>Client: Response
+```
+
+### 5.2 상세 설계
+
+- 단계 1:
+- 단계 2:
+
+## 6. Alternatives Considered
+
+### 대안 1
+
+- 장점:
+- 단점:
+- 왜 선택하지 않았는가:
+
+### 대안 2
+
+- 장점:
+- 단점:
+- 왜 선택하지 않았는가:
+
+## 7. Cross-cutting Concerns
+
+- 성능:
+- 보안:
+- 테스트:
+- 운영:
+
+## 8. Result / Trade-offs
+
+- 얻은 이점:
+- 감수한 비용:
+- 남은 리스크:
+
+## 9. References
+
+- 관련 코드:
+- 관련 문서:
@@ -0,0 +1,52 @@
+# Runbook: [절차명]
+
+## 1. 목적
+
+이 절차가 해결하는 운영 문제를 적습니다.
+
+## 2. 사용 시점
+
+- 언제 이 문서를 실행하는가?
+- 누가 사용하는가?
+
+## 3. Preconditions
+
+- 필요한 권한:
+- 필요한 환경 변수/도구:
+- 사전 확인 사항:
+
+## 4. Procedure
+
+### Step 1
+
+```bash
+# command
+```
+
+예상 결과:
+
+### Step 2
+
+```bash
+# command
+```
+
+예상 결과:
+
+## 5. Verification
+
+- 성공 여부를 어떻게 확인하는가?
+
+## 6. Rollback / Recovery
+
+- 실패 시 되돌리는 방법
+
+## 7. Failure Modes
+
+- 자주 발생하는 실수:
+- 위험한 포인트:
+
+## 8. References
+
+- 관련 대시보드:
+- 관련 문서:
@@ -0,0 +1,32 @@
+# [기술명] 문서
+
+## 개요
+
+[기술명]의 핵심 개념, 실제 적용 경험, 문제 해결 사례를 정리한 문서입니다.
+
+## 학습 배경
+
+- 왜 이 기술을 다루게 되었는가?
+- 어떤 프로젝트 맥락에서 필요했는가?
+
+## 문서 구조
+
+| 문서 | 내용 |
+|------|------|
+| [01-architecture.md](./01-architecture.md) | 구조와 핵심 개념 |
+| [02-flow.md](./02-flow.md) | 요청/데이터 흐름 |
+| [03-practice.md](./03-practice.md) | 실제 적용과 설정 이유 |
+| [04-troubleshooting.md](./04-troubleshooting.md) | 문제 해결 기록 |
+| [05-adr-why-[topic].md](./05-adr-why-[topic].md) | 기술 선택 근거 |
+
+## 핵심 키워드
+
+`keyword-1` · `keyword-2` · `keyword-3`
+
+## 읽는 순서
+
+1. 아키텍처
+2. 흐름
+3. 적용
+4. 트러블슈팅
+5. ADR
@@ -0,0 +1,51 @@
+# [문제 제목]
+
+## 한 줄 요약
+
+문제와 해결을 한두 문장으로 요약합니다.
+
+## 배경
+
+- 어떤 맥락에서 발생했는가?
+- 어떤 변경 이후 문제가 나타났는가?
+
+## 증상
+
+- 사용자/시스템 관점에서 어떤 문제가 보였는가?
+- 에러 로그, HTTP 상태, 재현 조건은 무엇이었는가?
+
+## 원인 분석
+
+### 가설 1
+
+- 시도:
+- 결과:
+
+### 가설 2
+
+- 시도:
+- 결과:
+
+### Root Cause
+
+최종 원인을 구조적으로 설명합니다.
+
+## 해결
+
+```text
+수정한 설정, 코드, 운영 조치를 적습니다.
+```
+
+## 검증
+
+- 어떻게 해결 여부를 확인했는가?
+
+## 교훈
+
+- 무엇을 배웠는가?
+- 다음에는 무엇을 먼저 확인할 것인가?
+
+## 교훈 / 향후 액션
+
+- 다음에 같은 증상이 보이면 가장 먼저 확인할 것:
+- 재발 방지를 위해 코드 / 매니페스트 / 알람에서 바뀌어야 할 것: