469 lines
21 KiB
Markdown
469 lines
21 KiB
Markdown
---
|
|
title:
|
|
source_type: project-note
|
|
status: draft
|
|
confidence: unknown
|
|
tags: [project-note]
|
|
related_projects: []
|
|
last_reviewed:
|
|
diagrams: []
|
|
architecture_review:
|
|
status_label: active
|
|
project_revision: 1
|
|
---
|
|
|
|
# {{title}}
|
|
|
|
> Layer: `raw/project-notes/` (primary, hub) → `/ingest` 후 검증된 사실은 `wiki/projects/` 로 추출.
|
|
> 본 문서는 **프로젝트의 최상위 hub**. 프로젝트 전체 컨텍스트 / 문제 정의 / 시스템 아키텍처 / 핵심 시퀀스가 여기에 집중. 모든 branch / errors / interviews / lectures / job-postings / blog-topics / sources 가 본 문서로 upward link.
|
|
> `status_label`: `active` | `paused` | `completed` | `archived`
|
|
> `project_revision`: project decision/work-item snapshot 의 양의 정수 revision. 레지스트리의 의미가 바뀌면 증가시킨다.
|
|
|
|
## 1. 프로젝트 개요
|
|
|
|
> 외부인이 1분 안에 "이게 뭐 하는 프로젝트인가" 이해할 수 있어야 함.
|
|
|
|
- **한 줄 요약**: <무엇을 / 왜 / 누구를 위해>
|
|
- **기간**: <시작 ~ 종료(또는 in-progress)>
|
|
- **현재 상태**: `active` | `paused` | `completed` | `archived`
|
|
- **나의 역할 / Role**: <구현자 / 설계자 / 학습자 / 컨설팅 / 팀원 등>
|
|
- **저장소 / Repo**:
|
|
- 메인: `<git url>`
|
|
- 부속:
|
|
|
|
## 2. 문제 정의
|
|
|
|
> 추상화 금지. 구체 시나리오·수치로.
|
|
|
|
### 2.1 현재 상태의 문제
|
|
|
|
- 문제 1: <구체적 통증>
|
|
- 문제 2:
|
|
- 문제 3:
|
|
|
|
### 2.2 왜 지금 해결해야 하는가
|
|
|
|
- 트리거 (왜 지금):
|
|
- 비용 (해결 안 했을 때 손실):
|
|
- 기회 (해결 시 가치):
|
|
|
|
### 2.3 성공 기준
|
|
|
|
> 측정 가능해야 함. "잘 동작한다" 같은 모호 표현 금지.
|
|
|
|
- 기준 1: <측정 가능한 결과>
|
|
- 기준 2:
|
|
- 기준 3:
|
|
|
|
## 3. 시스템 아키텍처
|
|
|
|
> **필수 섹션.** 아키텍처 다이어그램이 없는 project-note 는 hub 역할을 못 함.
|
|
|
|
### Diagram tool 선택 — 엄격한 분리
|
|
|
|
| 다이어그램 종류 | 도구 | 이유 |
|
|
|---|---|---|
|
|
| **시스템 아키텍처 / 컴포넌트 구성도 / 배포 토폴로지 / 데이터 흐름 (정적 구조)** | **draw.io XML (`.drawio` 또는 `.drawio.svg`)** | 자유 배치 / 시각적 그룹화 / 신뢰 경계 / 색상 코딩 / Obsidian draw.io 플러그인 native 편집 |
|
|
| **시퀀스 다이어그램** | **Mermaid `sequenceDiagram`** | 텍스트 기반·git diff 친화, 시간축 표현에 최적 |
|
|
| **ER 다이어그램 (데이터 모델, 선택)** | **Mermaid `erDiagram`** | 텍스트 기반·관계 카디널리티 표기 직관적 |
|
|
| 작은 결정 트리 / 짧은 플로우차트 | Mermaid `flowchart` 도 허용 (작은 규모 한정) | 시퀀스가 아닌 단순 분기 |
|
|
|
|
**금지**:
|
|
- 시스템 아키텍처를 Mermaid `graph TD`/`graph LR` 로 작성 — 시각 표현력 부족, draw.io 사용 의무
|
|
- 시퀀스 흐름을 draw.io 로 작성 — 시간축 표현 불편, Mermaid 사용 의무
|
|
|
|
### Diagram 컨퍼런스급 표준 (필수 정독)
|
|
|
|
> [[rules/diagram-standards]] 에서 **컨퍼런스급(Toss SLASH / Kakao if(dev) / Naver DEVIEW 수준) 다이어그램 표준 v2 (minimalist-first)** 를 정의한다. 본 template 본문에 별도 기준을 두지 않는다 — 항상 `rules/diagram-standards.md` 를 정독.
|
|
>
|
|
> **핵심 원칙: "적을수록 좋다" (Less is more)**. 정보를 다이어그램에 몰아넣으면 청중이 어디부터 봐야 할지 모른다.
|
|
>
|
|
> v2 의 요약 (전체는 rules 정독):
|
|
>
|
|
> - **요소 수 상한** (HARD): Vertex ≤ 10 / Edge ≤ 8 / Callout ≤ 1 / Boundary group ≤ 3 / Legend 항목 ≤ 6 / 색상 ≤ 4
|
|
> - **박스 라벨 ≤ 2줄**, **화살표 라벨 ≤ 5단어**
|
|
> - **80% 회색/흑백 + 강조색 ≤ 2** (color salad 금지)
|
|
> - **Boundary 는 정보 있을 때만** (장식용 boundary 금지)
|
|
> - **Legend 는 표준 컨벤션이면 생략** (점선=외부 / cylinder=DB / 실선=동기 / 점선=비동기 는 legend 불필요)
|
|
> - **Callout 1개** (있을 때만) — 비자명한 함정·결정에만
|
|
> - **출처 wikilink 는 본문/캡션에**, 다이어그램 안에 박지 말 것
|
|
> - **스케일 어노테이션 (QPS/latency)** 은 다이어그램의 질문이 *성능* 일 때만
|
|
> - **5초 룰 + 30초 룰** 통과
|
|
>
|
|
> **8항 self-check checklist** ([[rules/diagram-standards]] §14) 를 모두 ✓ 해야 컨퍼런스 발표 가능 수준. 1개라도 미달 → 분할 또는 단순화.
|
|
>
|
|
> `wiki-diagram-reviewer` agent 가 위 기준으로 `.drawio` XML 을 grep-카운트 후 0~100 점수 부여, ≥95 PASS.
|
|
|
|
### 3.1 아키텍처 다이어그램 (draw.io XML)
|
|
|
|
> 컴포넌트 구성도. **저장 경로**: `raw/diagrams/<project-slug>/` 하위에 `.drawio` 또는 `.drawio.svg` 형식으로 저장. Obsidian draw.io 플러그인으로 더블클릭 편집.
|
|
>
|
|
> **파일 명명 규약**: `architecture-{viewpoint}-YYYY-MM-DD.drawio.svg`
|
|
> 예: `architecture-overview-2026-05-25.drawio.svg`, `architecture-deployment-2026-05-25.drawio.svg`, `architecture-data-flow-2026-05-25.drawio.svg`
|
|
>
|
|
> **임베드 작성 방법**: 아래 code block 형식을 참고해 실제 파일명을 채워 wikilink 작성. **placeholder 그대로 두지 말 것** — Obsidian이 placeholder를 파일명으로 채택해 root에 orphan 파일을 생성함.
|
|
|
|
```markdown
|
|
실제 사용 예 (drawio 파일 생성 후 placeholder 부분을 실제 값으로 치환):
|
|
![[raw/diagrams/my-project/architecture-overview-2026-05-25.drawio.svg]]
|
|
```
|
|
|
|
<!-- 본 템플릿 사용자: 위 code block 안의 line을 일반 wikilink로 옮기되, my-project 와 날짜를 실제 값으로 치환한 뒤에만 사용. -->
|
|
|
|
|
|
**다이어그램 작성 요약 (v2 minimalist, 상세는 [[rules/diagram-standards]] 정독):**
|
|
|
|
- **컴포넌트 라벨**: 시스템 이름 (Bold 1줄) + 핵심 한 줄 (Stack OR 역할, 둘 중 하나만). 절대 ≥3 줄 금지.
|
|
예: `**User Service**` / `Spring Boot 3.4 · :8080` (2줄)
|
|
- **화살표 라벨**: `<step?> <verb/protocol> <object>` — 5단어 이내
|
|
예: `① GET /`, `proxy_pass :8080`, `Kafka publish user.signed-up`
|
|
- **외부 시스템**: 점선 (`#D0D7DE`) + fill `#F6F8FA`. Legend 불필요 (표준 컨벤션)
|
|
- **Boundary**: Trust / Network / External — **정보 있을 때만**. 모든 컴포넌트를 boundary 1개 안에 넣지 말 것 (정보 0)
|
|
- **색상 ≤ 4** — 80% 회색 + 강조 ≤ 2 (blue / orange 한 family씩) + (선택) warning red callout
|
|
- **Legend 생략 가능** — 점선=외부 / cylinder=DB / 실선=동기 같은 표준 컨벤션이면 legend 불필요. 비표준 색·기호 있을 때만 ≤6 항목 legend.
|
|
- **데이터 모델 카디널리티** 는 ER 다이어그램 (Mermaid `erDiagram`)에서만. 아키텍처 다이어그램의 화살표에 `1..N` 같은 cardinality 박지 말 것.
|
|
|
|
<!-- section-id: architecture-components -->
|
|
### 3.2 컴포넌트 책임 분담
|
|
|
|
> 다이어그램의 각 컴포넌트가 정확히 무엇을 책임지는지 표로.
|
|
|
|
| 컴포넌트 | 역할 | 기술 스택 | 의존하는 외부 |
|
|
|---|---|---|---|
|
|
| `<name>` | <한 줄 책임> | <stack> | <외부 시스템> |
|
|
| `<name>` | <한 줄 책임> | <stack> | <외부 시스템> |
|
|
|
|
### 3.3 외부 의존성
|
|
|
|
| 외부 시스템 | 용도 | 통신 방식 | 장애 시 영향 (degrade / fail / fallback) |
|
|
|---|---|---|---|
|
|
| `<name>` | <용도> | <REST/gRPC/...> | <영향> |
|
|
|
|
### 3.4 배포 다이어그램
|
|
|
|
> 운영 환경 토폴로지가 비자명하면 별도 draw.io.
|
|
|
|
```markdown
|
|
실제 사용 예 (placeholder 치환 후 사용):
|
|
![[raw/diagrams/my-project/architecture-deployment-2026-05-25.drawio.svg]]
|
|
```
|
|
|
|
|
|
<!-- section-id: runtime-flow -->
|
|
## 4. 핵심 시퀀스
|
|
|
|
> **필수 섹션.** 최소 1개의 주요 user flow 를 Mermaid sequence diagram 으로. happy path + 주요 error path 함께.
|
|
|
|
<!-- section-id: sequence -->
|
|
### 4.1 <Flow name 1> (예: 사용자 로그인)
|
|
|
|
**시나리오**: <어떤 상황의 흐름인지 1줄>
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
actor User
|
|
participant FE as Frontend
|
|
participant API as Backend API
|
|
participant Auth as Auth Service
|
|
participant DB as DB
|
|
|
|
User->>FE: 로그인 폼 입력
|
|
FE->>API: POST /api/v1/login {email, password}
|
|
API->>Auth: validateCredentials()
|
|
Auth->>DB: SELECT user
|
|
DB-->>Auth: user row
|
|
alt 자격 증명 유효
|
|
Auth-->>API: AuthToken
|
|
API-->>FE: 200 OK {token}
|
|
FE-->>User: 메인 페이지 리다이렉트
|
|
else 자격 증명 무효
|
|
Auth-->>API: AuthenticationFailed
|
|
API-->>FE: 401 Unauthorized {error_code: AUTH_INVALID}
|
|
FE-->>User: 에러 표시
|
|
end
|
|
```
|
|
|
|
**시퀀스 작성 표준 (필수 준수):**
|
|
|
|
- **`autonumber` 활성화** — 본문에서 "단계 3에서 ..." 처럼 참조 가능
|
|
- **`actor` vs `participant`**: 사람은 `actor`, 시스템은 `participant`
|
|
- **순서**: User → Frontend → Backend → External (좌→우)
|
|
- **화살표 라벨 명세**:
|
|
- HTTP: `METHOD /path {body 요약}` (예: `POST /api/v1/login {email, password}`)
|
|
- 메시징: `event-name {payload 요약}` (예: `user.signed-up {userId}`)
|
|
- 메서드 호출: `method()` (예: `validateCredentials()`)
|
|
- **응답**: `-->>` (점선 화살표)
|
|
- **alt / opt / loop**: 분기·옵션·반복은 명시적 블록
|
|
- **`Note over X,Y`**: 비자명한 동작은 노트로 명시
|
|
- **에러 경로 1개 이상 필수**: happy path 만 그리면 미완성
|
|
|
|
### 4.2 <Flow name 2> (필요 시)
|
|
|
|
(반복)
|
|
|
|
## 5. 데이터 모델
|
|
|
|
> 핵심 엔터티가 5~10개 이상이면 ER 다이어그램으로. 그 미만이면 글로만.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
USER ||--o{ ORDER : places
|
|
ORDER ||--|{ ORDER_ITEM : contains
|
|
PRODUCT ||--o{ ORDER_ITEM : "ordered as"
|
|
|
|
USER {
|
|
uuid id PK
|
|
string email
|
|
string name
|
|
}
|
|
ORDER {
|
|
uuid id PK
|
|
uuid user_id FK
|
|
timestamp created_at
|
|
decimal total
|
|
}
|
|
```
|
|
|
|
**ER 작성 표준:**
|
|
|
|
- **PK / FK 표시 필수**
|
|
- **관계 카디널리티 기호**:
|
|
- `||--||` (1:1)
|
|
- `||--o{` (1:N)
|
|
- `}o--o{` (M:N)
|
|
- `||..o{` (identifying vs non-identifying 표현)
|
|
- **관계 라벨**: 동사로 (예: `places`, `contains`, `ordered as`)
|
|
- 핵심 엔터티만 (5~10개 이내). 모든 테이블 그리지 말 것.
|
|
|
|
## 6. 기술 결정
|
|
|
|
> 주요 기술 선택과 이유. 트레이드오프 + 근거 자료 link 필수.
|
|
|
|
| 결정 영역 | 선택 | 검토한 대안 | 채택 이유 | 트레이드오프 | 근거 자료 |
|
|
|---|---|---|---|---|---|
|
|
| 백엔드 언어 | <e.g., Java 21> | <Kotlin / Go / Node> | <이유> | <단점> | `[[raw/official-docs/...]]` |
|
|
| 프레임워크 | <e.g., Spring Boot 3.4> | <Quarkus / Micronaut> | <이유> | <단점> | `[[raw/company-tech-blogs/...]]` |
|
|
| DB | <e.g., PostgreSQL 16> | <MySQL / MongoDB> | <이유> | <단점> | `[[raw/official-docs/...]]` |
|
|
| 메시징 | <e.g., Kafka / Redis Streams / X> | <대안> | <이유> | <단점> | |
|
|
| 캐시 | <e.g., Redis / Caffeine / X> | <대안> | <이유> | <단점> | |
|
|
| 아키텍처 패턴 | <e.g., Clean Architecture> | <Layered / Hexagonal / X> | <이유> | <단점> | |
|
|
| ... | | | | | |
|
|
|
|
<!-- section-id: project-decisions -->
|
|
## 6.1 안정 결정 레지스트리
|
|
|
|
> 프로젝트가 소유하는 결정의 SSOT. Decision ID 는 `DEC-<PROJECT>-<DOMAIN>-NNN`, revision 은 `1` 이상 정수다.
|
|
> `<PROJECT>` 와 `<DOMAIN>` 은 slug 를 uppercase kebab-case 로 정규화한다. 예: `DEC-CA-SKELETON-AUTH-001`.
|
|
> branch 는 결정 상세를 복제하지 않고 `DEC-CA-SKELETON-AUTH-001@2` 같은 **pinned reference + 1줄 요약**만 가진다.
|
|
> 결정 의미가 바뀌면 같은 ID 의 `Revision` 을 증가시키고 `project_revision` 도 증가시킨다. 단순 오탈자·링크 보정은 revision 증가 대상이 아니다.
|
|
|
|
| Decision ID | Revision | Domain | Decision Summary | Status | Owner | Evidence |
|
|
|---|---|---|---|---|---|---|
|
|
| `DEC-<PROJECT>-<DOMAIN>-001` | 1 | `<domain>` | <결정의 경계가 드러나는 1줄 요약> | `active` | `[[raw/project-notes/<project>]]` | `[[raw/official-docs/<...>]]` |
|
|
|
|
<!-- section-id: artifact-registry -->
|
|
## 6.2 Artifact Registry
|
|
|
|
| Artifact ID | Revision | Name | Schema Owner | Producer | Consumers | Schema Ref | Status |
|
|
|---|---:|---|---|---|---|---|---|
|
|
|
|
<!-- section-id: contract-gate-registry -->
|
|
## 6.3 Contract/Gate Registry
|
|
|
|
| Contract ID | Concern Key | Revision | Type | Owner | Trigger | Required Effect | Enforcement | Status |
|
|
|---|---|---:|---|---|---|---|---|---|
|
|
|
|
<!-- section-id: delegation-registry -->
|
|
## 6.4 Delegation Registry
|
|
|
|
| Delegation ID | Concern Key | Revision | Delegator | Delegate | Scope | Status |
|
|
|---|---|---:|---|---|---|---|
|
|
|
|
<!-- section-id: flow-stage-registry -->
|
|
## 6.5 Flow/Stage Registry
|
|
|
|
| Stage ID | Order | Owner | Input | Action | Output | Invariants | Revision |
|
|
|---|---:|---|---|---|---|---|---:|
|
|
|
|
<!-- section-id: implementation-boundaries -->
|
|
## 7. 비기능 요구사항
|
|
|
|
> 측정 가능한 비기능 목표. 없으면 명시적으로 "해당 없음".
|
|
|
|
- **성능**: <RPS, P99 latency 목표>
|
|
- **가용성**: <SLO 99.9% 등>
|
|
- **확장성**: <단일 인스턴스 / 다중 인스턴스 / HPA 정책>
|
|
- **보안**: <인증·인가 방식, 데이터 보호 정책, 컴플라이언스>
|
|
- **운영 / Observability**: <로깅·메트릭·트레이싱 정책>
|
|
- **재해 복구 / DR**: <RTO / RPO>
|
|
- **컴플라이언스**: <GDPR / PCI-DSS / 기타 / 해당 없음>
|
|
|
|
<!-- section-id: project-work-items -->
|
|
## 8.0 실행계획
|
|
|
|
> **`/project-spec` 가 채우는 핸드오프 SSOT.** Work Item ID 는 `WI-<PROJECT>-NNN` 이며 한 번 부여하면 재사용하지 않는다.
|
|
> 각 row 는 branch slug, 완료 조건, 적용할 project decision 의 pinned reference, 선행 Work Item, 상태를 묶는다.
|
|
> 결정 상세·메커니즘은 이 표나 branch 에 복제하지 않는다. project decision registry 를 owner 로 두고 pointer + 요약만 사용한다.
|
|
>
|
|
> 작성 규칙:
|
|
> - `Work Item ID` 의 `<PROJECT>` 는 project slug 의 uppercase kebab-case 형태다. 예: `WI-CA-SKELETON-001`.
|
|
> - `branch slug` 는 `rules/naming-conventions.md` §2.1 준수 (prefix 4종 `feature-`/`fix-`/`chore-`/`experiment-` 중 하나 + kebab-case, numbered hierarchy 금지).
|
|
> - `완료 조건` 은 **측정가능**해야 함 ("잘 된다" 금지). 그 branch 가 "끝났다"고 말할 수 있는 검증 가능한 결과.
|
|
> - `Applies Decisions` 는 쉼표로 구분한 `DEC-...@revision` 만 허용한다. unpinned ID 금지.
|
|
> - `Dependencies` 는 선행 `WI-...` ID 를 쉼표로 구분한다. 없으면 `-`.
|
|
> - `Status` 는 `planned` | `in-progress` | `blocked` | `done` | `cancelled` 중 하나다.
|
|
|
|
| Work Item ID | branch slug | 완료 조건 (측정가능) | Applies Decisions | Dependencies | Status |
|
|
|---|---|---|---|---|---|
|
|
| `WI-<PROJECT>-001` | `feature-<...>` | <이 branch 가 끝났다고 할 검증 가능한 결과> | `DEC-<PROJECT>-<DOMAIN>-001@1` | - | `planned` |
|
|
|
|
> 채운 뒤: `/branch-from-project <project> <WI-ID>` → `/branch-spec <slug> <근거 URL...>` → `/depth <slug>` 순으로 각 branch 를 깊게 작성.
|
|
|
|
## 8. 묶음 (이 프로젝트에 묶이는 모든 raw 자료)
|
|
|
|
> 본 project-note 는 cluster 의 entry point. 모든 branch / errors / interviews / lectures / job-postings / blog-topics / sources 가 여기로 upward link. hub 측에서도 카테고리별 명시.
|
|
|
|
### 8.1 브랜치 (project 의 직접 자식 branch — `parent_branch:` 비어있음)
|
|
|
|
> project-note 가 직접 가리키는 branch 들. 자식 branch 가 있는 branch 는 자기 Cluster 섹션에서 자식들을 참조하므로 여기에는 등재 안 함.
|
|
|
|
- `[[raw/branch-notes/<branch-1>]]` — <한 줄 요약>
|
|
- `[[raw/branch-notes/<branch-2>]]` — <한 줄 요약>
|
|
|
|
### 8.2 근거 자료 (프로젝트 전체 차원 foundational 조사)
|
|
|
|
> 특정 branch 에 묶이지 않는 전체 프로젝트 단위 근거 자료.
|
|
|
|
- `[[raw/official-docs/<...>]]`
|
|
- `[[raw/company-tech-blogs/<...>]]`
|
|
- `[[raw/lectures/<...>]]`
|
|
|
|
### 8.3 오류 기록 (branch 외 발생한 환경·운영 이슈)
|
|
|
|
- `[[raw/errors/<...>]]`
|
|
|
|
### 8.4 면접 준비 (프로젝트 전체 차원 면접 질문)
|
|
|
|
- `[[raw/interviews/<...>]]`
|
|
|
|
### 8.5 블로그·채용공고 연계 글감
|
|
|
|
- `[[raw/blog-topics/<...>]]` — 채용공고가 아닌 작업·학습·트러블슈팅 기반 글감 후보
|
|
- `[[raw/job-postings/<...>]]` — 채용공고에서 파생된 글감 후보
|
|
|
|
### 8.6 파생 wiki 문서
|
|
|
|
- canonical 검증 사실: `[[wiki/projects/<...>]]`
|
|
- 관련 일반 개념: `[[wiki/concepts/<...>]]`
|
|
- 포트폴리오: `[[wiki/portfolio/<...>]]`
|
|
- 블로그 글: `[[wiki/blog/<...>]]`
|
|
|
|
## 9. 검증 등급
|
|
|
|
> 본 project-note 의 각 부분이 어느 등급까지 검증되었는지. CLAUDE.md §15 lifecycle 참조.
|
|
|
|
| 영역 | 등급 | 근거 |
|
|
|---|---|---|
|
|
| 아키텍처 다이어그램 | `documented-only` \| `locally-verified` \| `prod-verified` | <근거 / 측정·로그·테스트> |
|
|
| 시퀀스 다이어그램 | 동일 | <근거> |
|
|
| 기술 결정 | 동일 | <근거> |
|
|
| 비기능 요구사항 | 동일 | <측정값 / SLO 모니터링 결과> |
|
|
|
|
### 9.1 실제 구현 내용 (`actually-implemented`)
|
|
|
|
> 코드에 존재하는 것만. 파일·함수 단위로 구체적으로. 면접에서 "구현했다"고 말해도 되는 부분.
|
|
|
|
### 9.2 로컬/dev 검증 (`locally-verified`)
|
|
|
|
> 로컬 또는 dev 환경에서 동작 확인한 부분. 어떻게 검증했는지(로그/테스트/측정값).
|
|
|
|
### 9.3 운영 검증 (`prod-verified`)
|
|
|
|
> 운영(prod) 환경에서 동작·성능을 확인한 부분. 근거(릴리즈 노트 / 운영 로그 / 모니터링 대시보드 / 인시던트 보고서)를 함께 명시.
|
|
|
|
### 9.4 문서/계획만 존재 (`documented-only`
|
|
|
|
> 설계 문서에만 있고 아직 구현 안 된 것. 면접에서 "구현했다"고 말하면 안 되는 부분.
|
|
|
|
## 10. 면접·외부 공개 답변 경계
|
|
|
|
### 10.1 자신 있게 답할 수 있는 범위
|
|
|
|
- <항목 1>
|
|
- <항목 2>
|
|
|
|
### 10.2 적당히 답할 수 있는 범위
|
|
|
|
- <항목>
|
|
|
|
### 10.3 답하면 안 되는 / "공식 문서 다시 확인" 해야 하는 범위
|
|
|
|
- <항목>
|
|
|
|
### 10.4 과장 금지 지점
|
|
|
|
> 외부에 설명할 때 사실보다 부풀려지기 쉬운 표현. 자기 검열용.
|
|
|
|
- <항목>
|
|
|
|
## 11. 아키텍처 검토 체크리스트 (작성·갱신 시 자체 점검)
|
|
|
|
> 본 project-note 가 hub 역할을 제대로 하려면 모두 ✓ 여야 함.
|
|
|
|
- [ ] 한 줄 요약 + 현재 상태 + 나의 역할 채워짐 (§1)
|
|
- [ ] 측정 가능한 성공 기준 1개 이상 (§2.3)
|
|
- [ ] **아키텍처 다이어그램 (`.drawio.svg`) 1개 이상 첨부** (§3.1)
|
|
- [ ] 다이어그램이 [[rules/diagram-standards]] v2 minimalist 통과 — `wiki-diagram-reviewer` 로 ≥95 점 (vertex ≤ 10 / edge ≤ 8 / callout ≤ 1 / 박스 라벨 ≤ 2줄 / 화살표 라벨 ≤ 5단어 / 80% 회색 + 강조 ≤ 2 / boundary 정보 있을 때만 / 5초 + 30초 룰)
|
|
- [ ] 외부 시스템이 점선 + 회색 fill 로 시각적 구분 (legend 불필요 — 표준 컨벤션)
|
|
- [ ] **시퀀스 다이어그램 1개 이상 (Mermaid)** — happy path + error path 함께 (§4)
|
|
- [ ] 데이터 모델은 5~10개 이상 엔터티 시에만 ER 그림 (§5)
|
|
- [ ] 주요 기술 결정 표에 트레이드오프 + 근거 자료 link 명시 (§6)
|
|
- [ ] 비기능 요구사항이 측정 가능한 수치 (§7)
|
|
- [ ] `project_revision` 이 양의 정수이고 Project Decision Registry 의 ID/revision 이 유효함 (§6.1)
|
|
- [ ] **Work Item Registry 채워짐** — 각 자식 branch 가 stable WI ID + naming-conventions slug + 측정가능 완료조건 + pinned decision refs 를 가짐 (§8.0)
|
|
- [ ] Cluster 섹션의 project 직접 자식 branch 목록 채워짐 (§8.1)
|
|
- [ ] 검증 등급이 각 영역별로 매겨짐 (§9)
|
|
- [ ] 면접 답변 경계 명시 (§10)
|
|
- [ ] 마지막 architecture review 날짜 frontmatter `architecture_review:` 에 기록
|
|
|
|
## 12. 다이어그램 파일 관리 가이드
|
|
|
|
> draw.io 파일과 Mermaid 코드 모두 본 project-note 와 함께 라이프사이클 관리.
|
|
|
|
### 12.1 draw.io (`.drawio.svg`)
|
|
|
|
- 저장 위치: `raw/diagrams/<project-slug>/`
|
|
- 명명: `architecture-{viewpoint}-{YYYY-MM-DD}.drawio.svg`
|
|
- viewpoint 예: `overview`, `deployment`, `data-flow`, `security`, `network`
|
|
- 갱신 시: 새 날짜로 파일 추가 + frontmatter `diagrams:` 에 모든 활성 다이어그램 나열
|
|
- 폐기 시: 파일 삭제하지 말고 `diagrams/<project>/archived/` 하위로 이동 + project-note 에서 link 제거
|
|
- Obsidian 임베딩 문법: `![[architecture-overview-2026-05-25.drawio.svg]]`
|
|
|
|
### 12.2 Mermaid
|
|
|
|
- 본 문서 본문에 직접. 외부 파일로 분리 안 함.
|
|
- 갱신 시: code block 그대로 수정 (git diff 친화적)
|
|
- 너무 커지면 (>50줄) 별도 sub-branch 의 branch-note 로 분리하고 본문에서는 요약만
|
|
|
|
### 12.3 그림 변경 시 의무
|
|
|
|
- 아키텍처가 변경되면 본 project-note 의 `architecture_review:` frontmatter 날짜 갱신
|
|
- 변경 사유는 §6 "기술 결정" 표에 한 줄 추가 (예: "2026-06-01: PostgreSQL → Aurora 변경 — 이유: 가용성 SLO 99.99%")
|
|
- 폐기된 결정도 표에서 지우지 말고 status 컬럼 추가로 표시 (`active` / `deprecated` / `superseded-by-<row>`)
|
|
|
|
## 13. 관련 개념
|
|
|
|
> §3~§6 표에 등장하지 않은 보조 개념·자료.
|
|
|
|
- `[[wiki/concepts/<...>]]`
|
|
- `[[wiki/projects/<...>]]`
|
|
- `[[raw/official-docs/<...>]]`
|
|
- `[[raw/company-tech-blogs/<...>]]`
|
|
|
|
## 14. 다음 단계
|
|
|
|
- [ ] <다음 마일스톤 / branch>
|
|
- [ ] <후속 학습 / 조사>
|
|
- [ ] <derived 산출물 후보>
|