fix: 하네스 제거 및 keycloak 문서 보강
This commit is contained in:
DongHyeonka
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/blog-template.md
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
title:
|
||||
source_type: blog
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: [blog]
|
||||
related_projects: []
|
||||
last_reviewed:
|
||||
canonical_sources: []
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: outline
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/blog/` — **외부 공개용 블로그 글 초안·완성본**. canonical (`wiki/concepts/` + `wiki/projects/`) 에서 파생된 산출물.
|
||||
> 상태: draft → reviewed → verified → **published-ready** (외부 게시 가능)
|
||||
> `status_label`: `outline` | `drafting` | `review` | `ready` | `published` | `retired`
|
||||
> `audience`: `backend-engineer` | `senior-engineer` | `tech-lead` | `general` — 깊이·전문용어 사용량이 달라짐.
|
||||
|
||||
## 부모 (필수)
|
||||
|
||||
> wiki/blog/ 는 derived layer. **반드시 canonical wiki/concepts/ 또는 wiki/projects/ 에서 파생.** raw 또는 branch에서 직접 파생 금지.
|
||||
|
||||
- 핵심 canonical (최소 1개+):
|
||||
- `[[wiki/concepts/<...>]]` — <어떤 개념을 다루는지>
|
||||
- `[[wiki/projects/<...>]]` — <어떤 프로젝트 사실을 다루는지>
|
||||
- 영감 출처 (선택):
|
||||
- `[[raw/blog-topics/<...>]]` — <어떤 raw 글감이 출발점이었나>
|
||||
- `[[raw/job-postings/<...>]]` — <어떤 공고가 글감을 자극했나>
|
||||
- `[[raw/interviews/<...>]]` — <어떤 면접 질문에서 파생>
|
||||
|
||||
## 타깃 독자
|
||||
|
||||
> 이 글을 누가 읽을 것인지. 톤·전문용어·깊이가 결정됨.
|
||||
|
||||
- 독자 profile:
|
||||
- 독자가 이미 알고 있을 것이라 가정하는 것:
|
||||
- 독자가 처음 듣는다고 가정하는 것:
|
||||
|
||||
## 도입
|
||||
|
||||
> 왜 이 글을 쓰는가. 독자에게 이 글의 가치를 1~2문장으로.
|
||||
|
||||
- 문제 / 궁금증:
|
||||
- 이 글이 답하는 것:
|
||||
- 이 글이 답하지 않는 것 (스코프):
|
||||
|
||||
## 본문 outline
|
||||
|
||||
> 글의 흐름. 초안 단계에서는 outline 만, drafting 단계부터 본문.
|
||||
|
||||
1. <섹션 1 제목> — <핵심 메시지 한 줄>
|
||||
2. <섹션 2 제목> — <핵심 메시지 한 줄>
|
||||
3. <섹션 3 제목> — <핵심 메시지 한 줄>
|
||||
|
||||
## 본문
|
||||
|
||||
> drafting 단계에서 채움. 모든 사실 주장은 canonical 인용으로 뒷받침.
|
||||
|
||||
(여기에 글 본문)
|
||||
|
||||
## 코드 예제
|
||||
|
||||
> 가능한 실제 프로젝트 코드 인용. 가짜 예제 금지. 추출 시 출처 PR·커밋 명시.
|
||||
|
||||
```<lang>
|
||||
// 출처: [[wiki/projects/<...>]] — <commit-sha>
|
||||
<code>
|
||||
```
|
||||
|
||||
## 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
> 모든 사실 주장은 canonical 또는 raw 인용으로 뒷받침. 자기 추론은 명시적으로 "내 해석" 으로 분리.
|
||||
|
||||
- `[[wiki/concepts/<...>]]` — <어떤 사실의 출처>
|
||||
- `[[wiki/projects/<...>]]` — <어떤 결정의 출처>
|
||||
- `[[raw/official-docs/<...>]]` — <인용한 공식 자료>
|
||||
- `[[raw/company-tech-blogs/<...>]]` — <인용한 사례>
|
||||
|
||||
## 사실 vs 의견
|
||||
|
||||
> 독자가 자신 있게 인용할 수 있도록.
|
||||
|
||||
- **사실 (검증됨)**:
|
||||
- <항목> — 근거: `[[wiki/...]]` 또는 `[[raw/...]]`
|
||||
- **내 해석·의견 (검증 안 된 추론)**:
|
||||
- <항목> — "내 경험상" / "내 해석으로는" 같은 표현으로 명시
|
||||
- **알지 못하는 것**:
|
||||
- <항목> — "이 부분은 다음 글에서 다루겠다" 또는 솔직히 표기
|
||||
|
||||
## 답할 수 있는 범위
|
||||
|
||||
> 이 글을 읽은 사람에게 후속 질문을 받았을 때 자신 있게 답할 수 있는 범위.
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- "그건 다음 글에서 다루겠다" 라고 해야 하는 부분:
|
||||
|
||||
## 게시 체크리스트
|
||||
|
||||
`ready` → `published` 로 올리기 전 확인.
|
||||
|
||||
- [ ] 모든 사실 주장에 canonical 링크 있음
|
||||
- [ ] 사실 vs 의견 분리 명시됨
|
||||
- [ ] 과장 단어 (`완벽`, `극한`, `100%`, `최고`, `역사상 가장`) 없음
|
||||
- [ ] 코드 예제 출처 명시
|
||||
- [ ] 타깃 독자 가정과 톤 일치
|
||||
- [ ] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## 관련
|
||||
|
||||
- 후속 글 후보: `[[wiki/blog/<...>]]`
|
||||
- 관련 포트폴리오 항목: `[[wiki/portfolio/<...>]]`
|
||||
- 영감을 받은 raw 자료: `[[raw/blog-topics/<...>]]`, `[[raw/job-postings/<...>]]`, `[[raw/lectures/<...>]]`
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/blog-topic-template.md
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: blog-topic / {{short-topic-slug}}
|
||||
source_type: blog-topic
|
||||
status: raw
|
||||
related_branches: []
|
||||
related_projects: []
|
||||
tags: [blog-topic, {{project-slug}}] # L2 프로젝트 슬러그 필수 (tag-taxonomy.md §2). L3~L5 는 주제별 추가.
|
||||
created: YYYY-MM-DD
|
||||
status_label: captured
|
||||
target_audience: backend-engineer
|
||||
inspiration_url: # 외부 자료에서 영감 받았으면 원본 URL. 없으면 빈 채로.
|
||||
archive_url: # inspiration_url 의 Wayback Machine 등 archive snapshot. CLAUDE.md §7.
|
||||
---
|
||||
|
||||
# blog-topic: {{short-topic-slug}}
|
||||
|
||||
> Layer: `raw/blog-topics/` — 채용공고가 아닌 작업·학습·트러블슈팅에서 나온 **블로그 글감 원석**. 다듬어진 블로그 초안은 canonical (`wiki/concepts/` 또는 `wiki/projects/`) 정제 후 `/blogify` 또는 수동 작성으로 `wiki/blog/`에 별도 작성한다. 원본은 raw에 영구 보관.
|
||||
> `status_label`: `captured` | `expanded` | `ready-for-canonical` | `derived-to-blog` | `parked`
|
||||
|
||||
> **Citation discipline (필수)**:
|
||||
>
|
||||
> - `## 핵심 주장 후보` 의 각 사실/경험 후보는 단순 `[[branch-note]]` 링크만으로는 부족하다. 다음 셋 중 하나를 동반한다:
|
||||
> 1. branch-note 의 **Decision ID** (예: "근거: `feature-X.md` D3").
|
||||
> 2. 외부 source 의 **claim ID** (예: `AT-TX-C5`, `UNIL-TX-C1`) — 가능하면 raw source 파일의 anchor 인용 (`<path>.md#AT-TX-C5`).
|
||||
> 3. branch-note 의 **section + line ref** (예: `feature-X.md §결정 사항`, `feature-X.md:104`).
|
||||
> - 외부 자료에 다수파 vs 소수파 trade-off 가 있다면 명시 (`다수파: @Transactional 직접 부착`, `소수파: TransactionPort 추상화` 등).
|
||||
> - `## Outline seed` 의 각 섹션 후보는 `→ 핵심 메시지 한 줄` 으로 다음 글의 단락 핵심을 미리 적는다. 단순 섹션 제목만 두지 않는다.
|
||||
> - `## Canonical 전환 후보` 는 추상 후보가 아니라 **구체 파일명** 까지 명시 (`wiki/projects/ca-tmpl/<topic>.md`).
|
||||
> - `## 미해결 / Unknown` 의 "과장하면 안 되는 부분" 은 반드시 한 줄 이상 채운다 — local-verified / prod-verified / documented-only 의 등급을 흐리지 말 것.
|
||||
|
||||
## 부모
|
||||
|
||||
> 이 글감이 어느 작업·프로젝트에서 나왔는지 명시. **최소 1개 필수.** 일반 주제면 `[[raw/project-notes/<project>]]` 로 연결.
|
||||
|
||||
- `[[raw/branch-notes/{{branch-name}}]]` — <왜 이 branch에서 이 글감이 나왔는지 한 줄>
|
||||
- (또는) `[[raw/project-notes/{{project-name}}]]`
|
||||
|
||||
## 트리거
|
||||
|
||||
> 어떤 사건에서 이 글감이 나왔는지 구조적으로 기록. `/lint` / `/query` 에서 trigger 유형별 필터링 가능.
|
||||
|
||||
- 트리거 유형: `branch-work` | `error` | `interview` | `lecture` | `conversation` | `other`
|
||||
- 트리거 날짜: YYYY-MM-DD
|
||||
- 트리거 연결 노트: `[[raw/branch-notes/...]]` 또는 `[[raw/errors/...]]` 또는 `[[raw/lectures/...]]` 또는 `[[raw/interviews/...]]`
|
||||
|
||||
## 글감
|
||||
|
||||
- 한 문장 요지:
|
||||
- 예상 제목 후보:
|
||||
- <제목 후보 1>
|
||||
- <제목 후보 2>
|
||||
|
||||
> 타깃 독자는 frontmatter `target_audience:` 필드를 SSOT 로 사용 (중복 방지).
|
||||
|
||||
## 핵심 주장 후보
|
||||
|
||||
> 아직 canonical이 아니다. 사실/경험/의견 후보를 분리한다.
|
||||
|
||||
- 사실 후보:
|
||||
- <검증 가능한 사실> — 근거 후보: `[[raw/branch-notes/<...>]]`
|
||||
- 경험 후보:
|
||||
- <내가 직접 한 작업/검증> — 근거 후보: `[[raw/branch-notes/<...>]]`
|
||||
- 의견/해석 후보:
|
||||
- <내 해석 또는 글의 관점>
|
||||
|
||||
## Outline seed
|
||||
|
||||
1. <섹션 후보 1> — <핵심 메시지>
|
||||
2. <섹션 후보 2> — <핵심 메시지>
|
||||
3. <섹션 후보 3> — <핵심 메시지>
|
||||
|
||||
## Canonical 전환 후보 / Canonical extraction candidates
|
||||
|
||||
> `wiki/blog/`로 바로 가지 않는다. 먼저 어떤 canonical 문서로 정제할지 기록한다.
|
||||
|
||||
- `wiki/projects/<project>/<topic>.md` 후보:
|
||||
- <프로젝트 적용 사실로 승격할 항목>
|
||||
- `wiki/concepts/<concept>.md` 후보:
|
||||
- <일반 개념으로 승격할 항목>
|
||||
- 필요한 추가 검증:
|
||||
- <테스트 / 공식문서 확인 / 코드 링크 / 리뷰>
|
||||
|
||||
## 근거 후보
|
||||
|
||||
> 글감 단계의 후보 링크다. 최종 blog의 사실 근거는 canonical 문서에서 다시 검증한다.
|
||||
|
||||
- `[[raw/branch-notes/<...>]]` — <어떤 경험/결정의 근거인지>
|
||||
- `[[raw/errors/<...>]]` — <관련 트러블슈팅이 있다면>
|
||||
- `[[raw/interviews/<...>]]` — <관련 예상 질문이 있다면>
|
||||
- `[[raw/official-docs/<...>]]` — <공식 근거 후보>
|
||||
- `[[raw/company-tech-blogs/<...>]]` — <사례 근거 후보>
|
||||
|
||||
## 미해결
|
||||
|
||||
- 아직 확인해야 할 사실:
|
||||
- 과장하면 안 되는 부분:
|
||||
- 블로그로 쓰기 전에 필요한 canonical 정제:
|
||||
|
||||
## 처리 결정
|
||||
|
||||
- 액션: `keep-as-topic` | `expand` | `promote-to-canonical` | `derive-to-blog` | `park`
|
||||
- 이유:
|
||||
- 다음 단계:
|
||||
|
||||
## 관련
|
||||
|
||||
- 관련 branch: `[[raw/branch-notes/{{branch-name}}]]`
|
||||
- 관련 error: `[[raw/errors/<...>]]` (있다면)
|
||||
- 관련 interview prep: `[[raw/interviews/<...>]]` (있다면)
|
||||
- derived blog: 생성 전. 생성 시 `wiki/blog/<slug>-YYYY-MM-DD.md` 후보
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/branch-note-template.md
|
||||
@@ -0,0 +1,473 @@
|
||||
---
|
||||
title: branch / {{branch-name}}
|
||||
source_type: branch-note
|
||||
status: raw
|
||||
id: {{branch-id}}
|
||||
kind: {{project-work-item|branch-child|standalone}}
|
||||
project: {{project-name}}
|
||||
work_item: {{WI-PROJECT-NNN}}
|
||||
inherits: [{{DEC-PROJECT-DOMAIN-NNN@revision}}]
|
||||
refines: []
|
||||
overrides: []
|
||||
depends_on: []
|
||||
imports: []
|
||||
delegates: []
|
||||
accepts_delegations: []
|
||||
contract_packet: 1
|
||||
branch: {{branch-name}}
|
||||
parent_branch:
|
||||
related_projects: []
|
||||
tags: [branch]
|
||||
created: YYYY-MM-DD
|
||||
target_merge:
|
||||
status_label: in-progress
|
||||
---
|
||||
|
||||
# branch: {{branch-name}}
|
||||
|
||||
> Layer: `raw/branch-notes/` — 단일 브랜치의 **TODO·결정·진행 기록**. 머지/종료 후 verified 결과는 `/ingest`로 `wiki/projects/`에 추출. 원본은 raw에 영구 보관.
|
||||
> `status_label`: `in-progress` | `review` | `merged` | `abandoned`
|
||||
> `id`: project 직접 자식은 `WI-`를 `BR-`로 치환한 stable ID, child는 결정론적으로 생성한 `BR-<PROJECT>-CHILD-<HASH>`를 사용한다. 파일명 slug를 ID로 재사용하지 않는다.
|
||||
> `contract_packet`: branch contract packet schema revision. 현재 v2 작성값은 양의 정수 `1`.
|
||||
> **계층 표기**: "root branch" 라는 별도 개념은 없음. project 의 직접 자식 branch 는 `parent_branch:` 를 **비워두고** `related_projects` 만 채움. 다른 branch 의 자식이면 `parent_branch: <부모 branch 이름>` 명시 + `## Parent` 섹션의 부모 wikilink 필수.
|
||||
|
||||
<!-- section-id: branch-parent -->
|
||||
## 부모 (필수)
|
||||
|
||||
> 이 branch 가 어느 작업 묶음에 속하는지. 모든 branch 는 예외 없이 upward link 보유.
|
||||
|
||||
다음 중 정확히 하나:
|
||||
|
||||
- **Project 의 직접 자식 branch** (`parent_branch:` 비어있음): `[[raw/project-notes/{{project-name}}]]` 만 명시
|
||||
- **다른 branch 의 자식** (`parent_branch:` 채워짐): `[[raw/branch-notes/{{parent-branch}}]]` 명시 + `frontmatter.parent_branch` 와 일치
|
||||
|
||||
선택 (있을 때):
|
||||
|
||||
- 형제 branch (같은 부모의 다른 자식):
|
||||
- `[[raw/branch-notes/{{sibling-1}}]]`
|
||||
- `[[raw/branch-notes/{{sibling-2}}]]`
|
||||
|
||||
<!-- section-id: branch-contract-packet -->
|
||||
## 브랜치 계약 패킷
|
||||
|
||||
> project Work Item 에서 내려온 실행 계약의 snapshot. `project`·`work_item`·`inherits`·`depends_on` 은 project registry row 와 일치해야 한다.
|
||||
> project 결정의 owner 는 project-note 다. 여기에는 **pinned pointer + 1줄 요약 + branch 적용점**만 쓰고 임계값·메커니즘·예외 목록 같은 상세를 복제하지 않는다.
|
||||
|
||||
- **생성 시 프로젝트 개정**: `{{positive-project-revision}}`
|
||||
- **패킷 스키마**: `contract_packet: 1`
|
||||
- **완료 조건**: <실행계획의 완료 조건을 그대로 연결>
|
||||
|
||||
<!-- section-id: inherited-project-decisions -->
|
||||
### 상속한 프로젝트 결정
|
||||
|
||||
| Decision Ref | Project Summary | Branch Application | Source |
|
||||
|---|---|---|---|
|
||||
| `DEC-<PROJECT>-<DOMAIN>-001@1` | <project registry 의 1줄 요약> | <이 branch 가 consume 하는 경계> | `[[raw/project-notes/<project>]]` |
|
||||
|
||||
<!-- section-id: branch-local-decisions -->
|
||||
### 브랜치 지역 결정
|
||||
|
||||
> 상세 근거와 선택 조건은 아래 `## 결정-근거 매핑`의 동일 D-row가 소유한다. `Relation` 은 `local` 또는 `refines DEC-...@revision`.
|
||||
|
||||
| Decision ID | Decision | Relation | Supporting Claims | Status |
|
||||
|---|---|---|---|---|
|
||||
| D1 | <branch-local 결정 1줄 요약> | `local` | `raw/official-docs/<slug>.md#C1` | `proposed` |
|
||||
|
||||
<!-- section-id: declared-overrides -->
|
||||
### 선언한 예외
|
||||
|
||||
> inherited project decision 과 다른 동작이 필요할 때만 작성한다. frontmatter `overrides` 와 동일한 pinned ref 를 사용하며 이유·승인·상태를 남긴다.
|
||||
|
||||
| Override ID | Overrides | Reason | Approval | Status |
|
||||
|---|---|---|---|---|
|
||||
| O1 | `DEC-<PROJECT>-<DOMAIN>-001@1` | <project 기본값을 적용할 수 없는 조건> | `needs-approval` | `proposed` |
|
||||
|
||||
<!-- GENERATED: artifact-imports:start -->
|
||||
### 가져온 artifact 계약
|
||||
|
||||
| Artifact Ref | Owner | Producer | Schema Ref |
|
||||
|---|---|---|---|
|
||||
<!-- GENERATED: artifact-imports:end -->
|
||||
|
||||
<!-- GENERATED: project-contract-imports:start -->
|
||||
## 가져온 프로젝트 계약
|
||||
|
||||
| Ref | Owner | 요약 | Branch 적용 |
|
||||
|---|---|---|---|
|
||||
<!-- GENERATED: project-contract-imports:end -->
|
||||
|
||||
<!-- GENERATED: received-delegations:start -->
|
||||
### 수신한 위임
|
||||
|
||||
| Delegation Ref | From | Concern | Status |
|
||||
|---|---|---|---|
|
||||
<!-- GENERATED: received-delegations:end -->
|
||||
|
||||
<!-- GENERATED: flow:start -->
|
||||
### 가져온 흐름 단계
|
||||
|
||||
| Stage Ref | Order | Owner | Input | Action | Output |
|
||||
|---|---:|---|---|---|---|
|
||||
<!-- GENERATED: flow:end -->
|
||||
|
||||
<!-- section-id: branch-goal -->
|
||||
## 목표
|
||||
|
||||
이 브랜치에서 해결하려는 문제. 관련 이슈 / PR 링크.
|
||||
|
||||
- 이슈:
|
||||
- PR:
|
||||
|
||||
<!-- section-id: branch-scope -->
|
||||
## 범위
|
||||
|
||||
### 포함 범위
|
||||
|
||||
- 항목 1
|
||||
- 항목 2
|
||||
|
||||
### 제외 범위
|
||||
|
||||
> 의도적으로 제외한 것. 면접 등에서 "이건 범위에 없었습니다"라고 답할 근거.
|
||||
|
||||
- 항목 1
|
||||
|
||||
## 근거 (필수, 최소 1개+)
|
||||
|
||||
> 이 branch의 구현·설계 결정의 **근거가 되는 외부 자료**. 공식 문서·대기업 기술 블로그·강의 등 raw 자료를 인용. 같은 자료가 여러 결정의 근거면 결정 표시와 함께 여러 번 등장 가능.
|
||||
|
||||
| Source | 정당화하는 결정 |
|
||||
|---|---|
|
||||
| `[[raw/official-docs/<...>]]` | <어떤 결정의 근거인지 한 줄> |
|
||||
| `[[raw/company-tech-blogs/<...>]]` | <한 줄> |
|
||||
| `[[raw/lectures/<...>]]` | <한 줄> |
|
||||
|
||||
근거 자료가 raw에 아직 없다면 먼저 `raw-source-template` 또는 `lecture-note-template` 으로 raw에 등록한 뒤 여기서 링크.
|
||||
|
||||
## TODO
|
||||
|
||||
각 항목 옆에 증거 등급 표기: `actually-implemented` | `locally-verified` | `prod-verified` | `documented-only` | `planned` | `needs-confirmation`
|
||||
|
||||
- [ ] 작업 1 — 등급: `planned`
|
||||
- [ ] 작업 2 — 등급: `planned`
|
||||
- [x] 작업 3 — 등급: `actually-implemented`
|
||||
|
||||
## 진행 중 메모
|
||||
|
||||
작업하며 떠오른 메모. 자유 형식.
|
||||
|
||||
## 결정 사항
|
||||
|
||||
> 추후 면접/회고에서 "왜 이렇게 했나" 답할 근거. 대안과 함께 기록. 각 결정의 근거는 위 Sources 또는 새로 추가된 raw 자료를 가리킬 것.
|
||||
|
||||
- YYYY-MM-DD: <결정 내용> / 이유: <왜> / 검토한 대안: <대안> / 근거: `[[raw/official-docs/<...>]]`
|
||||
|
||||
<!-- section-id: decision-evidence -->
|
||||
## 결정-근거 매핑
|
||||
|
||||
> 각 결정이 어떤 raw source claim 으로 뒷받침되는지 명시한다.
|
||||
> `Decision ID` 는 이 branch-note 안에서 안정적으로 유지한다. 예: `D1`, `D2`.
|
||||
> `Supporting Claims` 는 `raw/<category>/<slug>.md#C1` 형식으로 연결한다.
|
||||
|
||||
> `선택 조건` 열(R2): "이 조건일 때 이 결정, 다른 조건이면 어떤 대안". 분기 없으면 `N/A`.
|
||||
|
||||
| Decision ID | Decision | 선택 조건 (언제 이 결정 / 언제 대안) | Supporting Claims | Evidence Strength | Open Risk |
|
||||
|---|---|---|---|---|---|
|
||||
| D1 | <결정 내용> | <이 조건일 때 이 결정, 다른 조건이면 어떤 대안> | `raw/official-docs/<slug>.md#C1`, `raw/company-tech-blogs/<slug>.md#C2` | `official-vendor-doc + company-case-study` | <아직 검증해야 할 위험> |
|
||||
| D2 | <결정 내용> | <선택 조건 또는 N/A> | `raw/official-docs/<slug>.md#C3` | `official-standard` | <위험 또는 N/A> |
|
||||
|
||||
<!-- section-id: implementation -->
|
||||
## 구현 가이드
|
||||
|
||||
> *결정 (Decisions)* 이 "*무엇* 을 할 것인가" 라면, 본 §는 "*어디에 어떻게* 구현될 것인가" 의 사전 명세 — *문서가 모호해서 구현자가 임의로 정해야 했던 결정* 카탈로그. 작성 목표는 다음 구현자가 *되묻지 않아도 코드를 작성할 수 있는 수준*.
|
||||
>
|
||||
> **본 §는 일률적 anchor list 를 강제하지 않는다.** branch 마다 구현 내용·범위가 다르므로 sub-section 은 *이 branch 의 결정과 근거에서 도출되는 것만* 작성. 어떤 branch 는 error mapping 표 + 정적 강제 카탈로그, 어떤 branch 는 migration 단계 + wiring, 어떤 branch 는 sequence + state machine. 형식 예시는 `[[raw/branch-notes/feature-boundary-validation-mapping-contract]]` 의 §구현 가이드 참조.
|
||||
>
|
||||
> **3-rule meta principle (필수 준수)**:
|
||||
>
|
||||
> 1. **R1. Reference 필수** — 각 sub-section / row / cell 은 본 branch 의 `Decision ID` (예: D1, D2) + 그 결정의 `Supporting Claim ID` (예: `RAW-SLUG-C1`) 를 reference. *근거 없는 결정 금지* — 모든 구현 detail 은 결정 + 근거의 *도출* 이어야 함.
|
||||
> 2. **R2. UNSUPPORTED_IMPL_DECISION 명시** — 근거 raw 가 *원칙* 만 권고하고 *detail* (메커니즘 선택 / 클래스/rule 명명 / glob 패턴 / algorithm / factory API 모양 등) 은 권고하지 않는 cell 은 `UNSUPPORTED_IMPL_DECISION` 라벨 + 사용자 trade-off 근거 한 줄. 이게 *근거 있는 결정 vs 사용자 임의 trade-off* 의 경계.
|
||||
> 3. **R3. OUT_OF_BRANCH_SCOPE 정제** — 본 branch 결정 범위 밖 cell 은 §구현 가이드에 *남기지 않음*. 별도 branch 또는 canonical SSOT 로 이관 (이관 history 는 별도 § "Audit & Findings" 등에 보존). 도메인 특화 detail (ca-tmpl skeleton 범위 밖) 도 동일하게 정제.
|
||||
>
|
||||
> **각 sub-section 의 권장 헤더 패턴**:
|
||||
>
|
||||
> ```markdown
|
||||
> ### N. <sub-section 제목>
|
||||
>
|
||||
> > **Trace**: <In-scope row 들 + Decision ID + Supporting Claim ID 의 매핑 (한 줄/한 단락)>
|
||||
> >
|
||||
> > - **UNSUPPORTED_IMPL_DECISION**: <근거 없는 사용자 임의 결정 항목들 + 각각의 trade-off 근거 한 줄>
|
||||
>
|
||||
> <표 또는 명확한 구조 — 자유 텍스트 = 모호함 = 되묻기 원인>
|
||||
> ```
|
||||
|
||||
### 1. <sub-section 제목 — 본 branch 의 결정 영역 안에서만>
|
||||
|
||||
> **Trace**: <Decision ID + Supporting Claim ID 매핑>
|
||||
>
|
||||
> - **UNSUPPORTED_IMPL_DECISION**: <임의 결정 항목 + trade-off 한 줄>
|
||||
|
||||
(표 / 명세 / 카탈로그 / 절차 — 본 branch 의 결정 도출 detail)
|
||||
|
||||
### 2. ... (필요 시 추가)
|
||||
|
||||
<!-- section-id: edge-failure-dependency -->
|
||||
## 엣지·실패·의존
|
||||
|
||||
> R4(깊이 게이트) 캡처용. 정상 경로 외에 *구현 중 부딪힐* 실패/엣지/다른 계약 의존을 미리 열거. 없으면 "해당 없음" 명시(공란 금지).
|
||||
|
||||
- **실패·엣지 경로**: <입력 경계 / 타임아웃 / 부분 실패 / 동시성 등 — 각 경로의 기대 동작>
|
||||
- **다른 계약 의존**: `[[raw/branch-notes/<other-branch>]]` 의 `D<n>` 에 의존 — <무엇을 consume 하는지, 그 계약이 바뀌면 본 브랜치 영향>
|
||||
|
||||
<!-- section-id: claims-to-verify -->
|
||||
## 검증해야 할 주장
|
||||
|
||||
> 공식 문서나 사례는 근거지만, 내 프로젝트에서의 동작을 자동으로 보장하지 않는다.
|
||||
> 구현 전/중/후에 실제로 검증해야 하는 주장을 분리한다.
|
||||
|
||||
| Claim | Why uncertain | How to verify | Status |
|
||||
|---|---|---|---|
|
||||
| <검증할 주장> | <불확실한 이유> | <테스트/grep/실행 검증 방법> | `needs-confirmation` |
|
||||
| <검증할 주장> | <이유> | <방법> | `planned` |
|
||||
|
||||
|
||||
## 관심사 커버리지 (coverage-auditor 자동 생성 — 있을 때)
|
||||
|
||||
> `/coverage` 가 채우는 **생성물** — 손으로 유지하지 않는다. governing 문서(frontmatter `governing_docs`)가 요구하는 관심사를 이 브랜치가 빠짐없이 덮는지의 결과. 기준: `rules/coverage-gate.md`.
|
||||
> 상태: `covered-here`(이 브랜치 결정) / `delegated`(다른 owner 브랜치) / `missing`(아무도 안 맡음 → Blocking).
|
||||
|
||||
| 관심사 | 상태 | owner | 심각도 | 근거 |
|
||||
|--------|------|-------|--------|------|
|
||||
| <governing doc 의 관심사> | covered-here | — | — | D<n> |
|
||||
| <관심사> | delegated | feature-<owner> | OK/Should-fix | §Audit 위임 링크 |
|
||||
| <관심사> | missing | (없음) | 🔴 Blocking | governing doc §<x> 요구, 결정 없음 |
|
||||
|
||||
## 마주친 문제
|
||||
|
||||
> 짧은 메모만. 깊이 있는 트러블슈팅은 `raw/errors/` 로 분리하고 아래 Cluster에 연결.
|
||||
|
||||
- 이슈 1
|
||||
- 원인:
|
||||
- 시도:
|
||||
- 해결: (또는 미해결이면 `needs-confirmation`)
|
||||
- 별도 에러 노트로 분리됨: `[[raw/errors/<...>]]` (생성 시)
|
||||
|
||||
## 묶음 (이 branch에서 파생된 자료)
|
||||
|
||||
> 이 branch는 단일 노트가 아니라 **작업 묶음의 entry point**. 이 branch에서 파생된 모든 raw 노트를 카테고리별로 명시. 자식 노트가 forward link만 박아도 Obsidian backlink로 자동 발견되지만, 읽기 흐름과 분류를 위해 hub가 명시적으로 그룹화한다.
|
||||
|
||||
### Sub-branches (세부 작업)
|
||||
|
||||
- `[[raw/branch-notes/<sub-branch-1>]]` — <한 줄 요약>
|
||||
- `[[raw/branch-notes/<sub-branch-2>]]` — <한 줄 요약>
|
||||
|
||||
### 오류 기록 (이 branch 작업 중 발생)
|
||||
|
||||
- `[[raw/errors/<...>]]` — <한 줄 요약>
|
||||
|
||||
### 면접 준비 (이 작업에서 나올 수 있는 면접 질문)
|
||||
|
||||
- `[[raw/interviews/<...>]]` — <한 줄 요약>
|
||||
|
||||
### 강의 (이 작업을 위해 학습한 강의)
|
||||
|
||||
- `[[raw/lectures/<...>]]` — <한 줄 요약>
|
||||
|
||||
### job-posting tie-ins (이 작업에서 파생된 글감)
|
||||
|
||||
- `[[raw/blog-topics/<...>]]` — <채용공고가 아닌 작업·학습·트러블슈팅 기반 글감 후보>
|
||||
- `[[raw/job-postings/<...>]]` — <채용공고에서 파생된 글감 후보>
|
||||
- derived blog: 생성 전. 생성 시 `wiki/blog/<slug>-YYYY-MM-DD.md` 후보
|
||||
|
||||
## 관련 일일 노트
|
||||
|
||||
> 이 브랜치를 작업한 날짜들. 양방향 nav 유지.
|
||||
|
||||
- `[[raw/daily-notes/YYYY-MM-DD]]`
|
||||
- `[[raw/daily-notes/YYYY-MM-DD]]`
|
||||
|
||||
## 완료 후 정리
|
||||
|
||||
> 머지/종료 시점에 채움. `/ingest`가 이 섹션을 기준으로 wiki/projects/에 추출.
|
||||
|
||||
- PR 링크:
|
||||
- 리뷰 메모:
|
||||
- 머지 결과 / 배포 환경: (로컬/dev/staging/prod 어디까지 검증됐는지)
|
||||
- **wiki 추출 대상** (verified만, `wiki/projects/`로만 추출):
|
||||
- `actually-implemented` 항목:
|
||||
- `locally-verified` 항목:
|
||||
- `prod-verified` 항목:
|
||||
- **추출하지 않을 항목** (planned / documented-only / abandoned):
|
||||
|
||||
<!--
|
||||
아래 region은 `branch_from_project.py`의 결정론 renderer가 소비한다.
|
||||
사람이 복사하는 위 안내 template과 달리, 모든 값은 Work Item registry에서 주입되며
|
||||
`branch-contract` generated region은 runtime 외 작성자가 수정할 수 없다.
|
||||
-->
|
||||
<!-- RUNTIME-TEMPLATE: branch-from-project:start -->
|
||||
---
|
||||
title: branch / {{branch_slug}}
|
||||
source_type: branch-note
|
||||
status: raw
|
||||
id: {{branch_id}}
|
||||
kind: project-work-item
|
||||
project: {{project}}
|
||||
work_item: {{work_item}}
|
||||
inherits: {{inherits_yaml}}
|
||||
refines: []
|
||||
overrides: []
|
||||
depends_on: {{depends_on_yaml}}
|
||||
imports: []
|
||||
delegates: []
|
||||
accepts_delegations: []
|
||||
contract_packet: 1
|
||||
contract_packet_sha256: {{contract_packet_sha256}}
|
||||
branch: {{branch_slug}}
|
||||
parent_branch:
|
||||
related_projects: [{{project}}]
|
||||
tags: [branch]
|
||||
created: {{created}}
|
||||
target_merge:
|
||||
status_label: in-progress
|
||||
---
|
||||
|
||||
# branch: {{branch_slug}}
|
||||
|
||||
<!-- section-id: branch-parent -->
|
||||
## 부모 (필수)
|
||||
|
||||
{{project_parent_link}}
|
||||
|
||||
<!-- GENERATED: branch-contract:start -->
|
||||
<!-- section-id: branch-contract-packet -->
|
||||
## 브랜치 계약 패킷
|
||||
|
||||
- **생성 시 프로젝트 개정**: `{{project_revision}}`
|
||||
- **패킷 스키마**: `contract_packet: 1`
|
||||
- **완료 조건**: {{completion}}
|
||||
|
||||
<!-- section-id: inherited-project-decisions -->
|
||||
### 상속한 프로젝트 결정
|
||||
|
||||
| Decision Ref | Project Summary | Branch Application | Source |
|
||||
|---|---|---|---|
|
||||
{{inherited_rows}}
|
||||
|
||||
<!-- section-id: branch-local-decisions -->
|
||||
### 브랜치 지역 결정
|
||||
|
||||
| Decision ID | Decision | Relation | Supporting Claims | Status |
|
||||
|---|---|---|---|---|
|
||||
|
||||
<!-- section-id: declared-overrides -->
|
||||
### 선언한 예외
|
||||
|
||||
| Override ID | Overrides | Reason | Approval | Status |
|
||||
|---|---|---|---|---|
|
||||
<!-- GENERATED: branch-contract:end -->
|
||||
|
||||
<!-- GENERATED: artifact-imports:start -->
|
||||
### 가져온 artifact 계약
|
||||
|
||||
| Artifact Ref | Owner | Producer | Schema Ref |
|
||||
|---|---|---|---|
|
||||
<!-- GENERATED: artifact-imports:end -->
|
||||
|
||||
<!-- GENERATED: project-contract-imports:start -->
|
||||
## 가져온 프로젝트 계약
|
||||
|
||||
| Ref | Owner | 요약 | Branch 적용 |
|
||||
|---|---|---|---|
|
||||
<!-- GENERATED: project-contract-imports:end -->
|
||||
|
||||
<!-- GENERATED: received-delegations:start -->
|
||||
### 수신한 위임
|
||||
|
||||
| Delegation Ref | From | Concern | Status |
|
||||
|---|---|---|---|
|
||||
<!-- GENERATED: received-delegations:end -->
|
||||
|
||||
<!-- GENERATED: flow:start -->
|
||||
### 가져온 흐름 단계
|
||||
|
||||
| Stage Ref | Order | Owner | Input | Action | Output |
|
||||
|---|---:|---|---|---|---|
|
||||
<!-- GENERATED: flow:end -->
|
||||
|
||||
<!-- section-id: branch-goal -->
|
||||
## 목표
|
||||
|
||||
- `{{work_item}}`의 완료 조건을 구현한다: {{completion}}
|
||||
|
||||
<!-- section-id: branch-scope -->
|
||||
## 범위
|
||||
|
||||
### 포함 범위
|
||||
|
||||
- Work Item 완료 조건
|
||||
|
||||
### 제외 범위
|
||||
|
||||
- project decision registry 변경
|
||||
|
||||
## 근거 (필수, 최소 1개+)
|
||||
|
||||
외부 근거 미등록. `/branch-spec {{branch_slug}}` 단계에서 source claim을 연결한다.
|
||||
|
||||
## TODO
|
||||
|
||||
- [ ] {{completion}} — 등급: `planned`
|
||||
|
||||
## 진행 중 메모
|
||||
|
||||
아직 없음.
|
||||
|
||||
## 결정 사항
|
||||
|
||||
project 결정 외 branch-local 결정은 아직 없음.
|
||||
|
||||
<!-- section-id: decision-evidence -->
|
||||
## 결정-근거 매핑
|
||||
|
||||
| Decision ID | Decision | 선택 조건 (언제 이 결정 / 언제 대안) | Supporting Claims | Evidence Strength | Open Risk |
|
||||
|---|---|---|---|---|---|
|
||||
|
||||
<!-- section-id: implementation -->
|
||||
## 구현 가이드
|
||||
|
||||
`/branch-spec` 단계에서 source claim 기반으로 작성한다.
|
||||
|
||||
<!-- section-id: edge-failure-dependency -->
|
||||
## 엣지·실패·의존
|
||||
|
||||
- **실패·엣지 경로**: `/branch-spec` 단계에서 구체화한다.
|
||||
- **다른 계약 의존**: {{dependency_display}}
|
||||
|
||||
<!-- section-id: claims-to-verify -->
|
||||
## 검증해야 할 주장
|
||||
|
||||
| Claim | Why uncertain | How to verify | Status |
|
||||
|---|---|---|---|
|
||||
|
||||
## 관심사 커버리지 (coverage-auditor 자동 생성 — 있을 때)
|
||||
|
||||
`/coverage` 실행 전.
|
||||
|
||||
## 마주친 문제
|
||||
|
||||
아직 없음.
|
||||
|
||||
## 묶음 (이 branch에서 파생된 자료)
|
||||
|
||||
<!-- GENERATED: branches:start -->
|
||||
<!-- GENERATED: branches:end -->
|
||||
|
||||
## 관련 일일 노트
|
||||
|
||||
해당 없음.
|
||||
|
||||
## 완료 후 정리
|
||||
|
||||
- PR 링크:
|
||||
- 리뷰 메모:
|
||||
<!-- RUNTIME-TEMPLATE: branch-from-project:end -->
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/branch-report-template.md
|
||||
@@ -0,0 +1,387 @@
|
||||
---
|
||||
title: ""
|
||||
source_type: "report"
|
||||
status: "draft"
|
||||
confidence: "unknown"
|
||||
derived_from:
|
||||
- "raw/branch-notes/<branch-name>"
|
||||
- "wiki/projects/<canonical-doc>"
|
||||
related_projects:
|
||||
- "ca-tmpl"
|
||||
target_branch: ""
|
||||
target_module: ""
|
||||
audience: "self"
|
||||
purpose: "branch-implementation-understanding"
|
||||
last_reviewed: ""
|
||||
status_label: "draft"
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> 이 문서는 이해를 위한 derived report입니다.
|
||||
> SSOT는 `raw/branch-notes/`와 `wiki/projects/`의 canonical 문서입니다.
|
||||
> 이 문서는 branch-note의 모든 내용을 보존하지 않고, 사람이 읽고 설명할 수 있도록 재구성합니다.
|
||||
|
||||
---
|
||||
|
||||
## 0. Executive Summary
|
||||
|
||||
### 한 문장 요약
|
||||
|
||||
> 이 기능은 `<무엇>`이 `<어떤 문제>`를 일으키지 않도록, `<어느 계층>`에서 `<어떤 계약>`으로 통제하는 기능이다.
|
||||
|
||||
### 이 보고서를 읽고 답할 수 있어야 하는 질문
|
||||
|
||||
- 이 기능은 왜 필요한가?
|
||||
- 이 기능이 없으면 어떤 실패가 발생하는가?
|
||||
- Clean Architecture 구조에서 어디에 위치하는가?
|
||||
- 어떤 모듈이 무엇을 책임지고 무엇을 몰라야 하는가?
|
||||
- 실제 구현은 어떤 원리로 동작하는가?
|
||||
- 무엇을 테스트로 증명해야 하는가?
|
||||
|
||||
### 관련 문서
|
||||
|
||||
- Branch note:
|
||||
- `raw/branch-notes/<branch-name>`
|
||||
- Canonical project:
|
||||
- `wiki/projects/<canonical-doc>`
|
||||
- 관련 코드:
|
||||
- `<module>/<path>`
|
||||
- 관련 테스트:
|
||||
- `<module>/<test-path>`
|
||||
|
||||
---
|
||||
|
||||
## 1. 이 기능은 어떤 문제를 해결하는가?
|
||||
|
||||
### 문제 정의
|
||||
|
||||
`<문제 설명>`
|
||||
|
||||
### 이 문제가 중요한 이유
|
||||
|
||||
- `<이유 1>`
|
||||
- `<이유 2>`
|
||||
- `<이유 3>`
|
||||
|
||||
### 이 기능이 없을 때 생기는 구조적 문제
|
||||
|
||||
- `<레이어 침투>`
|
||||
- `<기술 누출>`
|
||||
- `<실패 분류 불일치>`
|
||||
- `<테스트로 감지 불가>`
|
||||
|
||||
---
|
||||
|
||||
## 2. 실제 실패 시나리오
|
||||
|
||||
### 시나리오 A. `<실패 이름>`
|
||||
|
||||
**상황**
|
||||
|
||||
`<현실적인 상황 설명>`
|
||||
|
||||
**실패 흐름**
|
||||
|
||||
```text
|
||||
<입력/요청>
|
||||
→ <잘못된 처리>
|
||||
→ <장애/버그>
|
||||
→ <운영 영향>
|
||||
```
|
||||
|
||||
**이 기능이 막는 방식**
|
||||
|
||||
`<어떤 계약/테스트/모듈 경계가 이 실패를 막는지>`
|
||||
|
||||
---
|
||||
|
||||
### 시나리오 B. `<실패 이름>`
|
||||
|
||||
**상황**
|
||||
|
||||
`<현실적인 상황 설명>`
|
||||
|
||||
**실패 흐름**
|
||||
|
||||
```text
|
||||
<입력/요청>
|
||||
→ <잘못된 처리>
|
||||
→ <장애/버그>
|
||||
→ <운영 영향>
|
||||
```
|
||||
|
||||
**이 기능이 막는 방식**
|
||||
|
||||
`<어떤 계약/테스트/모듈 경계가 이 실패를 막는지>`
|
||||
|
||||
---
|
||||
|
||||
## 3. Clean Architecture 안에서의 위치
|
||||
|
||||
### 관련 모듈
|
||||
|
||||
| 모듈 | 이 기능과의 관계 |
|
||||
| ------------------- | ---------------- |
|
||||
| domain-core | |
|
||||
| application-core | |
|
||||
| adapter-web | |
|
||||
| adapter-persistence | |
|
||||
| adapter-outbound | |
|
||||
| shared-contract | |
|
||||
| app-bootstrap | |
|
||||
| sample-portfolio | |
|
||||
|
||||
### 의존 방향
|
||||
|
||||
```text
|
||||
<허용되는 의존 방향>
|
||||
```
|
||||
|
||||
### 이 기능의 소유 계층
|
||||
|
||||
- 주 소유 계층:
|
||||
- 보조 계층:
|
||||
- 소비 계층:
|
||||
|
||||
---
|
||||
|
||||
## 4. 각 모듈은 무엇을 책임지고 무엇을 몰라야 하는가?
|
||||
|
||||
| 모듈 | 책임 | 몰라야 하는 것 | 위반 예시 |
|
||||
| ------------------- | ---- | -------------- | --------- |
|
||||
| domain-core | | | |
|
||||
| application-core | | | |
|
||||
| adapter-web | | | |
|
||||
| adapter-persistence | | | |
|
||||
| adapter-outbound | | | |
|
||||
| shared-contract | | | |
|
||||
| app-bootstrap | | | |
|
||||
| sample-portfolio | | | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 핵심 설계 결정
|
||||
|
||||
| ID | 결정 | 이유 | 대안 | 선택하지 않은 이유 | 상태 |
|
||||
| --- | ---- | ---- | ---- | ------------------ | ---- |
|
||||
| D1 | | | | | |
|
||||
| D2 | | | | | |
|
||||
| D3 | | | | | |
|
||||
|
||||
### 가장 중요한 결정 1개
|
||||
|
||||
`<이 branch에서 가장 중요한 결정>`
|
||||
|
||||
### 이 결정이 중요한 이유
|
||||
|
||||
`<왜 이 결정이 전체 구조를 좌우하는지>`
|
||||
|
||||
---
|
||||
|
||||
## 6. 핵심 구현 원리
|
||||
|
||||
### 구현 원리 요약
|
||||
|
||||
`<핵심 구현 원리 설명>`
|
||||
|
||||
### 처리 흐름
|
||||
|
||||
```text
|
||||
<입력>
|
||||
→ <경계>
|
||||
→ <변환>
|
||||
→ <핵심 처리>
|
||||
→ <외부 어댑터>
|
||||
→ <응답/로그/테스트>
|
||||
```
|
||||
|
||||
### 구현 위치
|
||||
|
||||
| 코드 위치 | 역할 | 관련 결정 |
|
||||
| --------- | ---- | --------- |
|
||||
| `<path>` | | D1 |
|
||||
| `<path>` | | D2 |
|
||||
| `<path>` | | D3 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 상태나 데이터 모델은 어떻게 생기는가?
|
||||
|
||||
### 주요 타입
|
||||
|
||||
| 타입 | 위치 | 역할 | 노출 가능 여부 |
|
||||
| ------------------- | ---- | ---- | -------------- |
|
||||
| Request DTO | | | |
|
||||
| Command/Query | | | |
|
||||
| Domain Model | | | |
|
||||
| Persistence Entity | | | |
|
||||
| Response DTO | | | |
|
||||
| Error/Envelope Type | | | |
|
||||
|
||||
### 변환 흐름
|
||||
|
||||
```text
|
||||
HTTP JSON
|
||||
→ Request DTO
|
||||
→ Command / Query
|
||||
→ Domain Model
|
||||
→ Persistence Entity
|
||||
→ Response DTO
|
||||
→ Envelope
|
||||
```
|
||||
|
||||
### 주의할 점
|
||||
|
||||
- DTO와 Domain을 섞지 않는다.
|
||||
- Domain과 Persistence Entity를 동일시하지 않는다.
|
||||
- 내부 진단 정보와 외부 응답 payload를 섞지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## 8. 동시성/장애 상황에서 어떻게 동작하는가?
|
||||
|
||||
### 장애 분류
|
||||
|
||||
| 장애 상황 | 감지 위치 | 변환 결과 | client 노출 | log/trace |
|
||||
| --------------------- | --------- | --------- | ----------- | --------- |
|
||||
| validation failure | | | | |
|
||||
| persistence failure | | | | |
|
||||
| dependency timeout | | | | |
|
||||
| authorization failure | | | | |
|
||||
| concurrency conflict | | | | |
|
||||
|
||||
### 동시성 관련 동작
|
||||
|
||||
- transaction boundary:
|
||||
- lock/retry/idempotency 관련 여부:
|
||||
- 중복 실행 시 기대 동작:
|
||||
- multi-instance 관련 제약:
|
||||
|
||||
---
|
||||
|
||||
## 9. 이 구현이 보장하는 것과 보장하지 못하는 것
|
||||
|
||||
### 보장하는 것
|
||||
|
||||
- `<자동 테스트나 컴파일 규칙으로 검증 가능한 것>`
|
||||
- `<계약상 반드시 유지되는 것>`
|
||||
|
||||
### 보장하지 못하는 것
|
||||
|
||||
- `<정적 분석으로 잡기 어려운 것>`
|
||||
- `<운영 환경에서 추가 검증이 필요한 것>`
|
||||
- `<비즈니스 요구사항 자체의 정합성>`
|
||||
|
||||
### 표현 주의
|
||||
|
||||
아래 표현은 사용하지 않는다.
|
||||
|
||||
- 완벽히 보장한다
|
||||
- 100% 방지한다
|
||||
- 완전무결하다
|
||||
- 모든 상황에서 안전하다
|
||||
|
||||
대신 아래처럼 쓴다.
|
||||
|
||||
- 빌드 시점에 감지한다
|
||||
- 정적 import 위반을 차단한다
|
||||
- 계약 위반을 테스트로 드러낸다
|
||||
- 런타임 동적 우회는 코드 리뷰와 추가 테스트가 필요하다
|
||||
|
||||
---
|
||||
|
||||
## 10. 테스트는 무엇으로 증명해야 하는가?
|
||||
|
||||
| 테스트 종류 | 증명하는 것 | 실패해야 하는 조건 | 실행 명령 |
|
||||
| ----------------- | ----------- | ------------------ | --------- |
|
||||
| unit test | | | |
|
||||
| contract test | | | |
|
||||
| architecture test | | | |
|
||||
| integration test | | | |
|
||||
| smoke test | | | |
|
||||
|
||||
### 핵심 테스트
|
||||
|
||||
```bash
|
||||
<명령어>
|
||||
```
|
||||
|
||||
### 이 테스트가 깨졌을 때 의미
|
||||
|
||||
`<어떤 계약이 깨졌다는 뜻인지>`
|
||||
|
||||
---
|
||||
|
||||
## 11. Implementation Status
|
||||
|
||||
| 항목 | 상태 | 근거 | 비고 |
|
||||
| -------- | ------------------------------------------------------------------------ | -------------------- | ---- |
|
||||
| `<항목>` | `<decision-only / documented-only / local-verified / pending / unknown>` | `<문서/코드/테스트>` | |
|
||||
|
||||
### 상태 값 정의
|
||||
|
||||
| 상태 | 의미 |
|
||||
| --------------- | ----------------------------------- |
|
||||
| decision-only | 결정은 있으나 구현/검증은 아직 없음 |
|
||||
| documented-only | 문서상 계약만 있음 |
|
||||
| local-verified | 로컬 코드/테스트로 검증됨 |
|
||||
| pending | 아직 착수 전 또는 잔여 작업 존재 |
|
||||
| unknown | 근거 부족으로 판단 불가 |
|
||||
|
||||
---
|
||||
|
||||
## 12. Fact / Interpretation / Unknown
|
||||
|
||||
### 검증된 사실
|
||||
|
||||
- `<검증된 사실>` — 근거: `[[...]]`
|
||||
|
||||
### 내 해석
|
||||
|
||||
- `<내 해석>` — 이유: `<왜 그렇게 해석했는지>`
|
||||
|
||||
### 아직 모르는 것
|
||||
|
||||
- `<확인 필요 항목>`
|
||||
|
||||
---
|
||||
|
||||
## 13. 설명용 문장
|
||||
|
||||
### 30초 설명
|
||||
|
||||
`<짧은 설명>`
|
||||
|
||||
### 2분 설명
|
||||
|
||||
`<면접/리뷰에서 말할 수 있는 설명>`
|
||||
|
||||
### 깊게 질문받았을 때 답변
|
||||
|
||||
**Q. 왜 이렇게 나누었나?**
|
||||
A. `<답변>`
|
||||
|
||||
**Q. 이 구조의 한계는 무엇인가?**
|
||||
A. `<답변>`
|
||||
|
||||
**Q. 이게 실제 장애를 어떻게 막나?**
|
||||
A. `<답변>`
|
||||
|
||||
---
|
||||
|
||||
## 14. 남은 리스크와 후속 작업
|
||||
|
||||
| 리스크 | 영향 | 확인 방법 | 후속 문서/branch |
|
||||
| ------ | ---- | --------- | ---------------- |
|
||||
| | | | |
|
||||
|
||||
---
|
||||
|
||||
## 15. Closure
|
||||
|
||||
- 이 보고서를 작성한 기준일:
|
||||
- 반영한 branch-note:
|
||||
- 반영한 코드 버전/커밋:
|
||||
- 아직 반영하지 않은 자료:
|
||||
- 다음에 읽을 문서:
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/concept-template.md
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title:
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: []
|
||||
related_projects: []
|
||||
last_reviewed:
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실(`wiki/projects/`)은 `wiki-project-template` 사용 (raw 프로젝트 hub는 `project-template`).
|
||||
|
||||
## Summary
|
||||
|
||||
한두 문장으로 핵심 정의.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
공식 문서 기준의 정의. 출처는 본문 끝 Sources 섹션에 명시.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
이 개념의 적용 한계, 흔한 오해, 트레이드오프. 공식 문서가 명시한 부분만 사실로, 그 외는 `needs-confirmation`으로 표기.
|
||||
|
||||
## Project Application
|
||||
|
||||
내 프로젝트에서 이 개념과 관련된 문서로 **링크**. 실제 구현 여부·검증 등급은 해당 project 문서에서 판정 (concept 문서는 등급을 직접 매기지 않음).
|
||||
|
||||
- `[[{{관련-project-문서}}]]`
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 이 개념 문서의 핵심 설명은 raw source claim 으로 뒷받침되어야 한다.
|
||||
> 공식 문서 claim, 회사 사례 claim, 내 프로젝트 decision 을 분리한다.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| <개념 설명> | `raw/official-docs/<slug>.md#C1` | `high` | <공식 문서 기준> |
|
||||
| <실무 적용 사례> | `raw/company-tech-blogs/<slug>.md#C2` | `medium` | <특정 회사 사례이므로 일반화 주의> |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- 이 개념의 공식 정의는 무엇인가?
|
||||
- 어떤 문제를 해결하는가?
|
||||
- 어떤 상황에서는 쓰면 안 되는가?
|
||||
- 공식 문서가 말하지 않는 부분은 무엇인가?
|
||||
- 회사 기술 블로그 사례를 일반 법칙처럼 말하면 안 되는 지점은 무엇인가?
|
||||
- 내 프로젝트에서는 어떤 branch decision 으로 연결됐는가?
|
||||
- 이 개념을 코드나 운영 환경에서 검증하려면 무엇을 확인해야 하는가?
|
||||
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- 면접에서 나올 법한 질문 1
|
||||
- 면접에서 나올 법한 질문 2
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
이 개념을 면접/이력서에서 말할 때 **과장하면 안 되는 지점**.
|
||||
|
||||
## 근거 자료
|
||||
|
||||
- [공식 문서 제목](https://example.com/...) — 핵심 출처
|
||||
- `[[raw/{{원본-경로}}]]` — raw에 보존한 원본
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/daily-note-template.md
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: YYYY-MM-DD 일일 노트
|
||||
source_type: daily-note
|
||||
status: raw
|
||||
tags: [daily]
|
||||
date: YYYY-MM-DD
|
||||
branches: []
|
||||
---
|
||||
|
||||
# YYYY-MM-DD
|
||||
|
||||
> Layer: `raw/daily-notes/` — 그날의 **혼합 일일 기록**. 그 자체는 wiki로 옮기지 않으며, `/ingest`가 promotable 항목만 추출해 다른 wiki 영역으로 보냅니다. 원본은 raw에 영구 보관.
|
||||
|
||||
## 활성 브랜치
|
||||
|
||||
오늘 작업한 브랜치 목록과 진행 상태. 브랜치 노트로 양방향 링크.
|
||||
|
||||
- `[branch-name]` (in-progress | review | merged) — `[[raw/branch-notes/{{branch-name}}]]`
|
||||
|
||||
## 오늘의 계획
|
||||
|
||||
브랜치별 항목은 `[branch-name]` 프리픽스. 브랜치 무관 항목은 프리픽스 없음.
|
||||
|
||||
- [ ] [branch-name] 항목 1
|
||||
- [ ] [branch-name] 항목 2
|
||||
- [ ] (no branch) 일반 항목
|
||||
|
||||
## 한 일
|
||||
|
||||
- [branch-name] 작업 1
|
||||
- [branch-name] 작업 2
|
||||
- (no branch) 일반 작업
|
||||
|
||||
## 배운 점
|
||||
|
||||
> wiki/concepts/로 promotable 후보
|
||||
|
||||
- 개념/사실 1
|
||||
- 개념/사실 2
|
||||
|
||||
## 트러블슈팅
|
||||
|
||||
> raw/errors/ 또는 wiki/projects/ 또는 관련 branch-note의 "마주친 문제" 섹션으로 promotable 후보
|
||||
|
||||
- [branch-name] 이슈 1: 원인 / 해결
|
||||
- 이슈 2
|
||||
|
||||
## 면접·포트폴리오로 옮길 만한 것
|
||||
|
||||
> **후보 표기만.** daily-note에서 `wiki/interview/` 또는 `wiki/portfolio/`를 직접 만들지 않습니다. 먼저 `/ingest`로 `wiki/projects/` 또는 `wiki/concepts/`에 canonical 추출 → 그 문서가 `reviewed | verified | published-ready`로 승급 → 그 후 `/interviewize` 또는 수동 작성.
|
||||
|
||||
- 항목 1 (→ 어떤 canonical 문서로 추출되어야 하는지)
|
||||
- 항목 2
|
||||
|
||||
## 내일로 넘긴 것
|
||||
|
||||
- [branch-name] 항목 1
|
||||
- 항목 2
|
||||
|
||||
## 잡담 / 회의 / 기타
|
||||
|
||||
> wiki로 promote할 가치가 낮은 일상 기록. 검색 archive로만 사용.
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/daily-task-develop-template.md
|
||||
@@ -0,0 +1,191 @@
|
||||
---
|
||||
title: daily-task / develop / {{slug}}
|
||||
source_type: daily-task
|
||||
track: develop
|
||||
status: raw
|
||||
status_label: not-started
|
||||
difficulty: intermediate
|
||||
duration_estimate: 120
|
||||
prerequisites: []
|
||||
parent_project: ca-skeleton-operational-contract
|
||||
parent_branch:
|
||||
target_date: YYYY-MM-DD
|
||||
created: YYYY-MM-DD
|
||||
tags: [daily-task]
|
||||
# 트랙 구분은 폴더 경로 + frontmatter `track:` 가 SSOT. tag 에 develop/infra 중복 금지.
|
||||
# 추가 tag 는 도메인별 (예: `validation`, `testing`, `archunit`) 1~2개 권장.
|
||||
---
|
||||
|
||||
# daily-task / develop / {{slug}}
|
||||
|
||||
> Layer: `raw/daily-tasks/develop/` — **개발 트랙 일일 실습 과제**. 사수가 신입에게 주는 형식의 자율 학습 과제. 매일 아침 1개 수행.
|
||||
> `status_label`: `not-started` | `in-progress` | `done` | `abandoned`
|
||||
> `difficulty`: `starter` (오늘이 처음) | `intermediate` (기본 흐름 익숙) | `advanced` (실패 모드 / 트레이드오프 탐구)
|
||||
> `duration_estimate`: 분 단위. 기본 120분 (Pomodoro 4-5개). 단순 일정이 아니라 *완료 신호가 뜰 때까지* 의 자기 추정치.
|
||||
>
|
||||
> **체계 근거**: 본 template 구조는 두 raw 자료로 정당화된다 — 9-section anchor 는 vendor-normative 가이드 (`[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]`), 단계 분할·자기평가·회고 원리는 deliberate-practice 개인 블로그 (`[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]`) 기반. 두 자료 모두 *공식 best practice 가 아니다* — 본 template 도 best practice 가 아닌 **운영 가능한 학습 구조**로만 인용할 것.
|
||||
|
||||
## 부모 (필수)
|
||||
|
||||
- **Parent project**: `[[raw/project-notes/ca-skeleton-operational-contract]]` (또는 해당하는 다른 project-note)
|
||||
- **연관 branch** (선택, 있을 때만): `[[raw/branch-notes/{{branch-slug}}]]`
|
||||
|
||||
> 본 과제가 어느 작업 묶음에 속하는지 명시. parent 없는 과제는 금지 (raw 영구 보관 정책 + ingest 시 추적 불가).
|
||||
|
||||
## 1. 학습 목표
|
||||
|
||||
> 3-5개 측정 가능 목표. "이 과제 끝났을 때 다음을 *할 수 있어야* 한다" 형식.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C1` — Learning Objectives 는 hands-on lab 의 7 functional spec 중 첫 anchor.
|
||||
|
||||
- [ ] L1: <할 수 있어야 하는 것 — 동사로 시작 (예: "ArchUnit rule 로 controller→domain 직접 의존을 빌드 실패로 검출할 수 있다")>
|
||||
- [ ] L2: <...>
|
||||
- [ ] L3: <...>
|
||||
|
||||
## 2. 스토리라인
|
||||
|
||||
> *왜* 이 과제가 필요한가. 실무 시나리오 1-2 문단. 단순한 코드 따라치기를 막는 anchor.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C2` — storyline 이 없으면 lab 은 "clicking things" 가 되고 학습자는 skill 향상 없이 끝난다.
|
||||
|
||||
(예시: "ca-tmpl 의 `feature-boundary-validation-mapping-contract` branch D7 결정 — controller 가 domain object 를 직접 반환하지 않는다 — 을 ArchUnit 으로 강제하려 한다. 다음 신입이 그 결정을 모르고 controller method 의 return type 에 domain entity 를 넣어도 build 가 통과되면 boundary contract 가 사실상 무력화된다. 오늘은 그 단 한 가지 시나리오만 막는 rule 을 작성하고 의도적인 위반으로 빌드를 깬다.")
|
||||
|
||||
## 3. 환경
|
||||
|
||||
> 사용 도구·버전·사전 셋업.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C1` — Prospective environment + Technologies used.
|
||||
|
||||
**개발 도구**:
|
||||
|
||||
- Java: <버전, e.g., 21 LTS>
|
||||
- Build: <Gradle 8.x / Maven 3.9>
|
||||
- IDE 권장: <IntelliJ IDEA 2025.x>
|
||||
- 추가 라이브러리: <ArchUnit / MapStruct / RestAssured 등 — 버전 명시>
|
||||
|
||||
**사전 셋업**:
|
||||
|
||||
```bash
|
||||
# repo clone / branch 전환
|
||||
cd ~/workspace/ca-tmpl
|
||||
git checkout -b daily-task/develop/{{slug}}
|
||||
|
||||
# 빌드 확인
|
||||
./gradlew clean build
|
||||
```
|
||||
|
||||
**예상 디렉토리 변경**:
|
||||
|
||||
- 추가/수정될 파일 경로 미리 명시 (예: `adapter-web/src/test/java/.../CleanArchitectureTest.java`)
|
||||
|
||||
## 4. 사전 지식
|
||||
|
||||
> 알아야 할 개념·결정. 모르면 wikilink 먼저 정독한 뒤 진행.
|
||||
|
||||
- `[[wiki/concepts/<concept-slug>]]` — <왜 필요한지 한 줄>
|
||||
- `[[raw/branch-notes/<related-branch>]]` — <관련 결정>
|
||||
- `[[raw/official-docs/<source-slug>]]` — <인용할 claim>
|
||||
|
||||
## 5. 단계별 과제
|
||||
|
||||
> Pomodoro (~25분) 단위로 분할. 각 단계는 *현재 능력보다 약간 높은* 도전이어야 한다 — 너무 쉬우면 학습 0, 너무 어려우면 좌절.
|
||||
> 근거: `[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]#DP-RGC-C2` (slightly higher than current ability — Ericsson 연구의 *개인 블로그 2차 인용*. 공식 best practice 표현 금지), `#DP-RGC-C5` (25-min Pomodoro 는 권고 시작점일 뿐 규범 아님).
|
||||
|
||||
### Step 1: <단계 제목> (~25min)
|
||||
|
||||
- **무엇을 (What)**: <구현해야 할 단위. 단일 commit 이 떠올라야 함>
|
||||
- **어떻게 (How — hint, *spoiler 아님*)**: <어떤 클래스를 만져야 하는지 / 어떤 패턴을 찾아야 하는지. 코드 정답 X>
|
||||
- **합격 신호 (Done when)**: <이 단계가 끝났음을 어떻게 알 수 있는가 — 명령어 / 로그 / 빨강↔초록 전환 / test name>
|
||||
|
||||
### Step 2: <단계 제목> (~25min)
|
||||
|
||||
- **What**:
|
||||
- **How (hint)**:
|
||||
- **Done when**:
|
||||
|
||||
### Step 3: <단계 제목> (~25min)
|
||||
|
||||
- **What**:
|
||||
- **How (hint)**:
|
||||
- **Done when**:
|
||||
|
||||
### 실패 모드 탐구> (~25min)
|
||||
|
||||
- **What**:
|
||||
- **How (hint)**:
|
||||
- **Done when**:
|
||||
|
||||
> *단계 갯수는 difficulty 에 따라*: starter=2, intermediate=3-4, advanced=4-5. 총 시간은 frontmatter `duration_estimate` 와 일치.
|
||||
|
||||
## 6. 검증
|
||||
|
||||
> 객관적 합격 기준. 단계 통과 = 측정 가능한 contract. *느낌* 으로 끝내지 않는다.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C4` (assessment = immediate feedback for success / additional help), `[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]#DP-RGC-C3` (objective standard 로 평가 — 단 "objective standard" 의 구체 정의는 본 template 작성자가 합격 명령어로 조작적 정의해야 함).
|
||||
|
||||
**자동 검증**:
|
||||
|
||||
```bash
|
||||
# 1) 빌드 + 단위 테스트
|
||||
./gradlew clean build test
|
||||
# 합격 기준: exit code 0
|
||||
|
||||
# 2) ArchUnit / contract test (해당 시)
|
||||
./gradlew :adapter-web:test --tests '*CleanArchitectureTest'
|
||||
# 합격 기준: PASS 로그
|
||||
|
||||
# 3) 의도적 위반 빌드 깨기 (해당 시 — rule 검증)
|
||||
# 임시로 위반 코드 추가 → 빌드 → 실패 확인 → 위반 코드 제거
|
||||
```
|
||||
|
||||
**수동 self-check**:
|
||||
|
||||
- [ ] 위 자동 명령 모두 exit 0
|
||||
- [ ] 의도적 위반 시 *정확히* 의도된 rule 이름이 실패 메시지에 포함됨
|
||||
- [ ] L1~L3 학습 목표가 실제로 *할 수 있다* 상태인지 (1줄로 설명 가능)
|
||||
- [ ] commit 메시지가 "왜" 를 답함 ("Add X" 가 아니라 "Enforce X to prevent Y")
|
||||
|
||||
## 7. 결과물
|
||||
|
||||
> 과제가 끝났을 때 남는 산출물. 휘발성 학습이 아니라 *재사용 가능한 흔적* 을 남긴다.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C1` — Outcomes 는 7-component spec 의 마지막 anchor.
|
||||
|
||||
- **commit / PR**:
|
||||
- 브랜치: `daily-task/develop/{{slug}}`
|
||||
- commits: <해시 + 1줄 메시지>
|
||||
- PR URL (있다면):
|
||||
- **신규/변경 파일**:
|
||||
- `<path/to/file>` — <역할 한 줄>
|
||||
- **학습한 개념** (wiki/concepts 로 ingest 후보):
|
||||
- <개념 1> — `/ingest` 시점에 `wiki/concepts/<slug>` 로 추출 가능 여부 메모
|
||||
- **다음 과제 thread** (실수·궁금증·심화 주제):
|
||||
- <오늘 막혔던 지점에서 자연스럽게 파생되는 과제 후보 — 내일 또는 다음 주 daily-task 시드>
|
||||
|
||||
## 8. 회고
|
||||
|
||||
> 과제 끝난 직후 5분 회고. 빈칸으로 두지 말 것. 빈 회고 = 학습 손실.
|
||||
> 근거: `[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]#DP-RGC-C4` — "After you finish each problem, ask yourself if you can improve any aspect of your problem-solving process based on your experience with that problem."
|
||||
|
||||
- **막혔던 곳** (몇 분 / 어디서):
|
||||
- **예상과 다른 점** (가정이 깨진 부분):
|
||||
- **다음 반복에서 개선할 점** (방법론 / 도구 / 정보 수집 순서):
|
||||
- **부수 효과로 발견한 것** (의도 외 학습):
|
||||
- **이 과제의 난이도가 적정했는가** (`너무 쉬움` / `적정` / `너무 어려움` — frontmatter `difficulty` 조정 신호):
|
||||
|
||||
## 9. 출처
|
||||
|
||||
> 본 과제의 구조 근거 + 도메인 근거.
|
||||
|
||||
| Source | 정당화 영역 |
|
||||
|---|---|
|
||||
| `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]` | template 9-section 구조 자체 (§1, §2, §3, §6, §7) |
|
||||
| `[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]` | §5 단계 분할 + §6 objective 평가 + §8 reflection 원리 |
|
||||
| `[[raw/official-docs/<...>]]` | 도메인 결정 근거 (Spring Boot / Java spec / Jackson 등) |
|
||||
| `[[raw/branch-notes/<...>]]` | 본 과제가 검증하려는 branch 결정 |
|
||||
|
||||
## 10. 완료 후 정리
|
||||
|
||||
> done 으로 바뀌는 순간 채움. `/ingest` 가 이 섹션을 기준으로 wiki 영역으로 promotable 항목 추출.
|
||||
|
||||
- **최종 status_label**: `done` | `abandoned`
|
||||
- **소요 시간 실측**: <분> (vs frontmatter `duration_estimate` <분>) — 차이 분석은 §8 회고에
|
||||
- **promotable 후보**:
|
||||
- `actually-implemented` → 어느 branch-note 의 어느 결정과 연결되는지
|
||||
- `locally-verified` → 어떤 명령으로 검증됐는지
|
||||
- **추출하지 않을 항목** (단순 학습 / 폐기):
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/daily-task-infra-template.md
|
||||
@@ -0,0 +1,238 @@
|
||||
---
|
||||
title: daily-task / infra / {{slug}}
|
||||
source_type: daily-task
|
||||
track: infra
|
||||
status: raw
|
||||
status_label: not-started
|
||||
difficulty: intermediate
|
||||
duration_estimate: 120
|
||||
prerequisites: []
|
||||
parent_project: ca-skeleton-operational-contract
|
||||
parent_branch:
|
||||
target_date: YYYY-MM-DD
|
||||
created: YYYY-MM-DD
|
||||
tags: [daily-task, infra]
|
||||
# 트랙 구분은 폴더 경로 + frontmatter `track:` 가 SSOT.
|
||||
# `infra` 는 L3 Domain 태그 (운영/인프라 영역 검색용). 추가 tag 는 도메인별 (예: `observability`, `kubernetes`) 0~2개.
|
||||
---
|
||||
|
||||
# daily-task / infra / {{slug}}
|
||||
|
||||
> Layer: `raw/daily-tasks/infra/` — **인프라 / 운영 트랙 일일 실습 과제**. 사수가 신입에게 주는 형식의 자율 운영 과제. 매일 아침 1개 수행.
|
||||
> `status_label`: `not-started` | `in-progress` | `done` | `abandoned`
|
||||
> `difficulty`: `starter` (도구 처음) | `intermediate` (기본 흐름 익숙) | `advanced` (장애 / 트레이드오프 / SLO 탐구)
|
||||
> `duration_estimate`: 분 단위. 기본 120분. develop 트랙과 달리 *대기 시간 (apply / probe / metric 수렴)* 이 포함됨에 유의.
|
||||
>
|
||||
> **체계 근거**: 본 template 구조는 두 raw 자료로 정당화된다 — 9-section anchor 는 vendor-normative 가이드 (`[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]`), 단계 분할·자기평가·회고 원리는 deliberate-practice 개인 블로그 (`[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]`) 기반. 두 자료 모두 *공식 best practice 가 아니다*.
|
||||
>
|
||||
> **develop 트랙과의 차이**: §3 환경은 *작업 host + target cluster + kubeconfig context*, §5 단계는 *manifest 작성 → apply → 관측 → 롤백 drill* 흐름, §6 검증은 *kubectl / promql / log query / smoke test*, §7 결과물은 *applied manifest + dashboard URL + alert rule + runbook stub*, §11 운영 회복력 anchor 추가.
|
||||
|
||||
## 부모 (필수)
|
||||
|
||||
- **Parent project**: `[[raw/project-notes/ca-skeleton-operational-contract]]` (또는 해당하는 다른 project-note — 예: 사용자 인프라 개요)
|
||||
- **연관 branch** (선택, 있을 때만): `[[raw/branch-notes/{{branch-slug}}]]`
|
||||
|
||||
> 본 과제가 어느 작업 묶음에 속하는지 명시. parent 없는 과제는 금지.
|
||||
|
||||
## 1. 학습 목표
|
||||
|
||||
> 3-5개 측정 가능 목표. "이 과제 끝났을 때 다음을 *할 수 있어야* 한다" 형식. 인프라 트랙은 *관측 / 진단 / 롤백* 동사를 의식적으로 섞을 것.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C1`.
|
||||
|
||||
- [ ] L1: <동사로 시작 (예: "Spring Boot actuator `/actuator/health/readiness` 를 k8s readinessProbe 로 연결하고 의도적 DB 단절 시 not-ready 가 30초 안에 노출됨을 prometheus 로 확인할 수 있다")>
|
||||
- [ ] L2: <...>
|
||||
- [ ] L3: <...>
|
||||
|
||||
## 2. 스토리라인
|
||||
|
||||
> *왜* 이 인프라 작업이 필요한가. 실무 운영 시나리오 1-2 문단. SLO / 장애 / 비용 anchor 가 자연스럽다.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C2` (storyline 없으면 "clicking things").
|
||||
|
||||
(예시: "현재 ca-tmpl staging cluster 의 readiness probe 는 항상 200 을 반환하는 `/health` 를 본다. 즉 DB unavailable 이어도 pod 가 ready 로 표시돼 트래픽이 흘러 5xx 가 양산된다. 오늘은 readiness 를 `health/readiness` 로 분리하고 DB connection failure 시 *unhealthy* 가 30초 내에 표면화되는지, kube-state-metrics + prometheus 로 확인한다.")
|
||||
|
||||
## 3. 환경
|
||||
|
||||
> 작업 호스트 · 대상 시스템 · 도구 버전 · context.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C1` (Prospective environment + Technologies used).
|
||||
|
||||
**작업 호스트**:
|
||||
|
||||
- 로컬 macOS / Linux / WSL2 — <명시>
|
||||
|
||||
**대상 환경**:
|
||||
|
||||
- Cluster: <local kind / k3s / minikube / staging cluster name>
|
||||
- Namespace: <e.g., `ca-tmpl-staging`>
|
||||
- Kubeconfig context: <명시>
|
||||
|
||||
**도구 버전**:
|
||||
|
||||
- `kubectl`: <e.g., 1.30>
|
||||
- `helm`: <3.15>
|
||||
- `docker` / `podman`: <24.x>
|
||||
- (Optional) `terraform`, `kustomize`, `k9s`, `stern`, `kubectx`: <버전>
|
||||
- 관측: Prometheus <v2.50>, Grafana <11.x>, Loki / OpenTelemetry collector <버전>
|
||||
|
||||
**사전 셋업**:
|
||||
|
||||
```bash
|
||||
# context 전환 확인
|
||||
kubectl config current-context
|
||||
kubectl get ns <namespace>
|
||||
|
||||
# 작업 디렉토리
|
||||
cd ~/workspace/ca-tmpl-infra
|
||||
git checkout -b daily-task/infra/{{slug}}
|
||||
|
||||
# 현재 상태 스냅샷 (롤백 reference)
|
||||
kubectl get all -n <namespace> -o yaml > /tmp/snapshot-pre-{{slug}}.yaml
|
||||
```
|
||||
|
||||
**변경 예정 리소스**:
|
||||
|
||||
- `<manifest path or k8s resource>` — <어떤 변경>
|
||||
|
||||
## 4. 사전 지식
|
||||
|
||||
> 알아야 할 개념·결정·운영 규약.
|
||||
|
||||
- `[[wiki/concepts/<concept-slug>]]` — <왜 필요한지>
|
||||
- `[[raw/project-notes/ca-skeleton-operational-contract]]` — <§N (e.g., §15 runtime/lifecycle) 인용>
|
||||
- `[[raw/official-docs/<source-slug>]]` — <인용할 claim>
|
||||
|
||||
## 5. 단계별 과제
|
||||
|
||||
> *Manifest 작성 → apply → 관측 → 롤백 drill* 의 자연스러운 흐름. 각 단계 25분 ± 대기시간. infra 는 *apply 후 metric 수렴* 같은 비-CPU 대기가 있으니 시간 추정에 포함.
|
||||
> 근거: `[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]#DP-RGC-C2` (slightly higher than current), `#DP-RGC-C5` (25-min Pomodoro 권고 시작점).
|
||||
|
||||
### 베이스라인 측정 (~20min)
|
||||
|
||||
- **What**: 변경 전 상태를 *수치* 로 기록. metric / log / probe 응답.
|
||||
- **How (hint)**: `kubectl get` / `kubectl describe` / promql query / log grep
|
||||
- **Done when**: 베이스라인 수치 3개 이상이 본 노트 §7 에 기록됨
|
||||
|
||||
### 설정 작성 (~30min)
|
||||
|
||||
- **What**: <변경할 manifest / Dockerfile / helm values / actuator config>
|
||||
- **How (hint)**: 어떤 field 가 핵심인가, 어떤 default 를 override 해야 하는가
|
||||
- **Done when**: 로컬 lint 통과 (`kubectl apply --dry-run=server -f ...`), diff 검토 완료
|
||||
|
||||
### Step 3: Apply + 관측 (~25min, 대기 포함)
|
||||
|
||||
- **What**: 실제 apply 후 *수렴 시간* 측정 + 의도된 동작 확인
|
||||
- **How (hint)**: `kubectl rollout status`, prometheus `up{job=...}`, alert 발화 여부, `kubectl logs --previous`
|
||||
- **Done when**: 의도된 metric / probe 변화가 promQL 로 확인 가능
|
||||
|
||||
### 롤백 drill (~25min)
|
||||
|
||||
- **What**: 본 변경의 *실패 모드* 를 의도적으로 발생 → 자동 복구 또는 수동 롤백 검증
|
||||
- **How (hint)**: chaos (e.g., DB 단절, pod kill, network delay), 또는 rollback 명령 직접 실행
|
||||
- **Done when**: 시스템이 알려진 상태로 복귀 + 사후 metric / log 정상
|
||||
|
||||
### 대시보드 작성 (~20min)
|
||||
|
||||
- **What**: 본 변경을 관측하는 alert rule + grafana panel
|
||||
- **How (hint)**: PromQL recording rule, alert threshold, runbook link
|
||||
- **Done when**: alert rule lint 통과, dashboard JSON commit
|
||||
|
||||
> *단계 갯수 권고*: starter=3, intermediate=4-5, advanced=5+chaos. 총 시간은 frontmatter `duration_estimate` 와 일치.
|
||||
|
||||
## 6. 검증
|
||||
|
||||
> 인프라 검증 = *명령 + metric + log + probe* 4가지 채널 중 ≥2개 교차 확인. 단일 채널만 의존 금지.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C4` (immediate feedback), `[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]#DP-RGC-C3` (objective standard).
|
||||
|
||||
**자동 검증** (각 명령 + 합격 기준):
|
||||
|
||||
```bash
|
||||
# 1) Probe / health
|
||||
curl -fsS http://<host>:<port>/actuator/health/readiness
|
||||
# 합격 기준: HTTP 200 + status: UP
|
||||
|
||||
# 2) k8s 리소스 상태
|
||||
kubectl rollout status deployment/<name> -n <namespace> --timeout=60s
|
||||
# 합격 기준: deployment 가 successfully rolled out
|
||||
|
||||
# 3) PromQL — 의도된 metric 수렴
|
||||
# 예: 1분 평균 readiness probe success rate
|
||||
# promql: avg_over_time(probe_success{job="kubernetes-pods"}[1m])
|
||||
# 합격 기준: 변화 시점이 기대 시간 ± 10초 내
|
||||
|
||||
# 4) Log 검증
|
||||
kubectl logs deployment/<name> -n <namespace> --tail=200 | grep -E '<expected log line>'
|
||||
# 합격 기준: 의도된 log entry 발견 (또는 *없어야 할* line 부재)
|
||||
|
||||
# 5) Smoke test (해당 시)
|
||||
./scripts/smoke-test.sh <env>
|
||||
# 합격 기준: exit code 0
|
||||
```
|
||||
|
||||
**수동 self-check**:
|
||||
|
||||
- [ ] 위 4-5개 명령 중 ≥2 채널이 교차 확인됨
|
||||
- [ ] 의도적 실패 시 정확히 의도된 alert 가 발화 (Step 4 결과)
|
||||
- [ ] 롤백 명령으로 *완전히* 베이스라인으로 복귀 가능 (Step 1 수치와 일치)
|
||||
- [ ] L1~L3 학습 목표가 실제로 수행 가능한 상태
|
||||
- [ ] manifest commit 메시지가 "왜" 를 답함
|
||||
|
||||
## 7. 결과물
|
||||
|
||||
> 인프라 트랙 산출물 = *applied manifest + 측정값 + dashboard / alert + runbook stub*.
|
||||
> 근거: `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]#SKILL-LAB-C1`.
|
||||
|
||||
- **commit / PR**:
|
||||
- 브랜치: `daily-task/infra/{{slug}}`
|
||||
- commits: <해시 + 1줄>
|
||||
- PR URL (있다면):
|
||||
- **변경된 manifest / 설정**:
|
||||
- `<path>` — <역할 한 줄>
|
||||
- **측정값** (§5 Step 1 베이스라인 vs Step 3 적용 후):
|
||||
- <metric / probe / log line>: before=<값> → after=<값>
|
||||
- **Dashboard / Alert**:
|
||||
- Grafana panel URL: <또는 JSON path>
|
||||
- Alert rule: <name, threshold, runbook link>
|
||||
- **Runbook stub** (이 변경으로 새 alert 가 생겼다면):
|
||||
- 알람 발생 시 1차 확인: <명령 1-2줄>
|
||||
- 즉시 fail-fast / degrade 가능 분류: <명시>
|
||||
- **학습한 개념** (wiki/concepts 로 ingest 후보):
|
||||
- **다음 과제 thread**:
|
||||
|
||||
## 8. 회고
|
||||
|
||||
> 빈 회고 = 학습 손실. 인프라 트랙은 *측정값 vs 예상* 의 괴리를 특히 기록.
|
||||
> 근거: `[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]#DP-RGC-C4`.
|
||||
|
||||
- **막혔던 곳** (몇 분 / 어디서 — apply 대기 / probe timing / metric label mismatch 등):
|
||||
- **예상과 다른 점** (가정이 깨진 부분 — 수렴 시간 / probe 동작 / cluster 자동 동작):
|
||||
- **다음 반복에서 개선할 점**:
|
||||
- **부수 효과로 발견한 것** (의도 외 metric / log / 이벤트):
|
||||
- **이 과제의 난이도가 적정했는가** (frontmatter `difficulty` 조정 신호):
|
||||
|
||||
## 9. 출처
|
||||
|
||||
| Source | 정당화 영역 |
|
||||
|---|---|
|
||||
| `[[raw/company-tech-blogs/skillable-hands-on-lab-structure]]` | template 9-section 구조 자체 |
|
||||
| `[[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]` | §5 단계 분할 + §6 objective 평가 + §8 reflection |
|
||||
| `[[raw/official-docs/<...>]]` | 도메인 근거 (Spring actuator / k8s probe / Prometheus / Grafana 등) |
|
||||
| `[[raw/project-notes/ca-skeleton-operational-contract]]` | 본 과제가 검증하려는 운영 계약 §N |
|
||||
|
||||
## 10. 완료 후 정리
|
||||
|
||||
- **최종 status_label**: `done` | `abandoned`
|
||||
- **소요 시간 실측**: <분> (vs frontmatter `duration_estimate`) — 차이는 §8 회고에
|
||||
- **promotable 후보**:
|
||||
- `actually-implemented` → 어느 운영 계약 §N 과 연결되는지
|
||||
- `locally-verified` → 어떤 명령으로 검증됐는지
|
||||
- `prod-verified` → (해당 시) 운영 환경 검증 시점 + 로그/측정값 reference
|
||||
- **추출하지 않을 항목** (단순 학습 / 실험 / 폐기):
|
||||
|
||||
## 11. 운영 회복력
|
||||
|
||||
> develop 트랙에 *없는* infra 트랙 전용 anchor. 본 과제가 시스템 회복력에 어떤 영향을 주는지 명시.
|
||||
|
||||
- **본 변경이 도입하는 새 실패 모드**:
|
||||
- **새 실패 모드의 fail-fast vs degrade 분류**:
|
||||
- **모니터링 누락 위험** (이 변경 후 *못 보게 되는* metric/log):
|
||||
- **롤백 트리거 조건** (어떤 측정값이 어떤 임계치 초과 시 롤백):
|
||||
- **연관 alert / runbook** (`[[raw/project-notes/ca-skeleton-operational-contract]]#28` Operational Runbook 와의 정합):
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/error-note-template.md
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: error / {{short-error-slug}}
|
||||
source_type: error-note
|
||||
status: raw
|
||||
related_branches: []
|
||||
related_projects: []
|
||||
tags: [error]
|
||||
created: YYYY-MM-DD
|
||||
status_label: open
|
||||
---
|
||||
|
||||
# error: {{short-error-slug}}
|
||||
|
||||
> Layer: `raw/errors/` — 작업 중 마주친 **단일 실패·트러블슈팅 기록**. 해결되면 wiki/concepts(공통 패턴) 또는 wiki/projects(프로젝트 특화)로 `/ingest` 시 일부 추출 가능. 원본은 raw에 영구 보관.
|
||||
> `status_label`: `open` | `investigating` | `resolved` | `workaround` | `wontfix` | `needs-confirmation`
|
||||
|
||||
> **Citation / honesty discipline (필수)**:
|
||||
>
|
||||
> - `## 증상` 의 에러 메시지는 **원문 그대로** (paraphrase 금지). stack trace 핵심 부분만 발췌해도 verbatim 유지.
|
||||
> - `## 재현 절차` 는 _타인이 그대로 재현할 수 있는지_ 기준으로 명령·파일 변경·기대값/실제값을 적는다. 빈 상태로 두지 말 것.
|
||||
> - `## 조사 단계` 는 시간순으로 시도와 결과를 모두 기록한다 (막다른 길 포함). 사후에 "원인은 X였다" 만 적으면 재발 시 패턴 인식 불가능.
|
||||
> - `## 근본 원인` 의 "직접 원인 / 근본 원인 / 트리거 조건" 셋을 분리. "직접 원인" 만 적으면 다음 비슷한 상황을 인지 못 함.
|
||||
> - `## 회고` 의 "빨리 감지하는 신호" 는 _다음에 같은 에러를 더 빨리 잡기 위한_ 키워드 (예: "메시지에 `Read-only file system` 이 나오면 sandbox 권한 의심"). 추상적인 교훈만 적지 않는다.
|
||||
|
||||
## 부모
|
||||
|
||||
> 이 에러가 어느 작업 묶음에 속하는지 명시. **최소 1개 필수.** 작업 외 발생 시(예: 환경 셋업 중) `[[raw/project-notes/<project>]]` 로 연결.
|
||||
|
||||
- `[[raw/branch-notes/{{branch-name}}]]`
|
||||
- (또는) `[[raw/project-notes/{{project-name}}]]`
|
||||
|
||||
## 증상
|
||||
|
||||
> 무슨 일이 일어났는가. 에러 메시지 원문, stack trace 핵심 부분, 발생 화면/명령 등.
|
||||
|
||||
- 에러 메시지 (원문 그대로):
|
||||
```text
|
||||
<verbatim message>
|
||||
```
|
||||
- 발생 컨텍스트: <어떤 명령·요청·UI 동작에서 발생>
|
||||
- 발생 시점: YYYY-MM-DD HH:MM
|
||||
- 발생 환경: <local / dev / staging / prod / CI>
|
||||
- 재현 가능 여부: `always` | `sometimes` | `once`
|
||||
|
||||
## 재현 절차
|
||||
|
||||
> "타인이 이걸 보고 재현할 수 있는가" 기준. 명령 한 줄 또는 step-by-step.
|
||||
|
||||
1. <단계 1>
|
||||
2. <단계 2>
|
||||
3. <기대 결과> vs <실제 결과>
|
||||
|
||||
## 조사 단계
|
||||
|
||||
> 시도한 것 + 결과를 시간 순으로. 막다른 길도 기록 (다음에 같은 길로 안 가기 위함).
|
||||
|
||||
- YYYY-MM-DD HH:MM — <시도한 것> → <결과·관측>
|
||||
- YYYY-MM-DD HH:MM — <시도한 것> → <결과·관측>
|
||||
|
||||
## 근본 원인
|
||||
|
||||
> 사실에 입각해 결론. 추측이라면 `needs-confirmation` 으로 표시.
|
||||
|
||||
- 직접 원인:
|
||||
- 근본 원인:
|
||||
- 트리거 조건:
|
||||
|
||||
## 근거 (해결 근거가 된 자료, 최소 1개+ 권장)
|
||||
|
||||
> 공식 문서·기술 블로그·이슈 트래커 링크. raw에 보관한 원문 발췌가 있다면 `[[raw/official-docs/...]]` 또는 `[[raw/company-tech-blogs/...]]` 로 연결.
|
||||
|
||||
- `[[raw/official-docs/<...>]]` — <어떤 부분이 근거인지 한 줄>
|
||||
- `[[raw/company-tech-blogs/<...>]]` — <어떤 부분이 근거인지 한 줄>
|
||||
- 외부 URL (raw에 안 넣은 즉석 참조): <url> — <한 줄 메모>
|
||||
|
||||
## 해결
|
||||
|
||||
> 어떻게 막았는가. 코드/설정/명령 변경 사항을 구체적으로.
|
||||
|
||||
- 적용한 조치:
|
||||
- 검증 방법: <테스트·로그·재현 명령으로 확인>
|
||||
- 잔여 위험 / 후속 작업: <있다면>
|
||||
|
||||
## 회고
|
||||
|
||||
> 다음번에 같은 에러를 더 빨리 잡으려면 무엇을 기억할지.
|
||||
|
||||
- 빨리 감지하는 신호:
|
||||
- 예방 체크리스트 항목 후보:
|
||||
- wiki로 끌어올릴 가치가 있는 일반화된 교훈: <있다면 wiki/concepts 추출 후보로 메모>
|
||||
|
||||
## 관련
|
||||
|
||||
> 같은 작업 묶음 내 다른 raw 문서.
|
||||
|
||||
- 트리거된 daily note: `[[raw/daily-notes/YYYY-MM-DD]]`
|
||||
- 관련 에러 (선행/후속/유사): `[[raw/errors/<...>]]`
|
||||
- 관련 wiki 개념: `[[wiki/concepts/<...>]]` (이미 검증된 요약 있을 시)
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/explainer-template.md
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
title: (강사 설명) {{무엇을, 한 줄로}}
|
||||
source_type: explainer
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: []
|
||||
related_projects: []
|
||||
last_reviewed:
|
||||
---
|
||||
|
||||
# (강사 설명) {{제목 — 정의가 아니라 "무엇을 할 수 있게 되는가" 로}}
|
||||
|
||||
> Layer: `wiki/explainer/` — **derived(파생) 교육 문서.** "나의 진짜 이해" 를 위한 1타강사 칠판이다.
|
||||
> 정확한 사실·근거·검증 등급은 여기서 만들지 않는다. 전부 canonical 에서 가져온다:
|
||||
> - 개념·대안·근거: `[[wiki/concepts/{{concept-slug}}]]`
|
||||
> - 내 프로젝트 실제 구현·검증 범위: `[[wiki/projects/{{project}}/{{slug}}]]` (있을 때만)
|
||||
>
|
||||
> 이 문서의 **비유는 의도적으로 부정확**하다 (이해를 위한 단순화). 비유를 사실로 인용하지 마라. 면접에서 말할 땐 canonical 의 표현을 써라.
|
||||
|
||||
<!--
|
||||
작성 원칙 (HARD RULE — 지우지 말고 작성 후 검토):
|
||||
1. derived 다. 새 claim 을 만들지 않는다. 전부 canonical 의 재구성이다. (코드 인용은 ground-truth repo 에서, file:line 캡션과 함께.)
|
||||
2. **학습 계약 먼저(§0).** "무엇을 알고 와서(선행지식), 끝나면 무엇을 어디까지 설명할 수 있나(수료역량)"를 표로 못박는다. 이게 이 템플릿의 1급 시민이다 — 학습자가 진입↔도달을 스스로 측정하게 한다.
|
||||
3. 정의로 시작하지 않는다. §1 은 고통/문제 장면.
|
||||
4. **하나의 관통 줄기(through-line).** 처음부터 끝까지 한 예시("요청 1건의 생애" 등)를 따라간다. 큰 그림(§3)에서 정상 경로를 깔고, §4 에서 그 1건이 각 안전장치를 *통과 순서대로* 만나게 한다.
|
||||
5. **난이도 레인.** 각 본문 모듈 제목 끝에 `[신입 필수]` / `[심화]` / `[참조]` 라벨. §0 에 "신입 최소 완주 경로"를 명시(어디까지 읽으면 수료역량 달성).
|
||||
6. **just-in-time 용어.** 용어는 *처음 쓰는 모듈 시작*에 "새 용어" 미니 박스로 정의한다. 전체 용어집(§참조)은 *복습 치트시트*이지 처음 배우는 곳이 아니다.
|
||||
7. **모듈마다 형성 평가.** 각 본문 모듈 끝에 `<details>` 자가 점검 1~3문항(정답은 본문 위치/메서드명을 가리킴). 끝에 몰지 말 것.
|
||||
8. 톤: 존댓말 아님. 크리스프 평서문 + 직접 호명. 단정 과장 금지(canonical 의 과장 금지 준수). 비유가 사실을 왜곡할 지점은 "강사의 한마디"로 명시 보정.
|
||||
9. **## 백बोन 헤딩(§0~§3 · 정의 · 자가 점검 · Sources)은 글자 그대로 유지**한다. structure-lint(`wiki_structure_lint.py`)가 헤딩을 거의-정확매칭하므로, 백본 헤딩을 바꾸거나 인스턴스값(프로젝트명/주제)을 백본 헤딩에 끼우면 MISSING_SECTION 오탐이 난다. **인스턴스값·난이도 라벨은 백본 헤딩이 아니라 그 아래 첫 줄(부제, bold)에 쓴다.** 본문 모듈은 `###` 으로 자유롭게(린트는 `##` 만 검사).
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## §0. 학습 계약 — 시작 전에 꼭 읽기
|
||||
|
||||
> 이 수업이 가르치는 것을 한 문장으로. 그 다음 네 블록을 *표로* 채운다.
|
||||
|
||||
**이 수업을 마치면 — 수료 역량** (이 질문들에 *이 깊이로* 답하게 된다):
|
||||
|
||||
| # | 질문 | 답에 반드시 들어가야 할 키워드 |
|
||||
|---|---|---|
|
||||
| E1 | {{핵심 질문 1}} | {{기대 답변 깊이}} |
|
||||
| E2 | {{...}} | {{...}} |
|
||||
|
||||
**시작 전 알아야 할 것 — 선행 지식** (self-check 통과하면 OK):
|
||||
|
||||
| 알아야 할 것 | self-check (한 줄로 답되면 통과) | 모르면 |
|
||||
|---|---|---|
|
||||
| {{선행 1}} | "{{스스로 던질 질문}}" | {{보충 링크/섹션}} |
|
||||
|
||||
**난이도 레인 & 최소 완주 경로:** 본문 제목의 `[신입 필수]` / `[심화]` / `[참조]` 를 읽는 법. "신입은 {{§N}} 까지만 읽어도 E1~E{{k}} 달성. [심화]는 1회독 후."
|
||||
|
||||
**관통 줄기 🧵:** 이 수업은 처음부터 끝까지 **"{{예시 1건}}의 생애"** 를 따라간다. ({{가상/실제}} 여부 명시.)
|
||||
|
||||
---
|
||||
|
||||
## §1. 한 장면 — 5초 만에 고통 느끼기
|
||||
|
||||
> 정의 금지. 이 주제가 없으면 무엇이 *터지는지* 구체적 장면. 코드/숫자/실패가 보이게.
|
||||
> 마지막은 "그래서 진짜 고민은 이 한 줄" 로 §2 에 넘긴다.
|
||||
|
||||
---
|
||||
|
||||
## §2. 단 하나의 축
|
||||
|
||||
> **부제(첫 줄, bold)에 인스턴스 축 이름**: 예) "정합성 ↔ 가용성". (백본 헤딩엔 넣지 말 것 — 원칙 9.)
|
||||
> 모든 선택이 답하려는 *공통 질문* 을 한 축(axis)으로 압축. 양 끝 신념을 ASCII 한 줄로 대비.
|
||||
> 메시지: "누가 맞고 틀린 게 아니라, 무엇을 더 두려워하는지가 다르다."
|
||||
|
||||
```text
|
||||
{{왼쪽 끝 신념}} ◄───────────────────────────────► {{오른쪽 끝 신념}}
|
||||
{{선택지 위치들}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §3. 큰 그림
|
||||
|
||||
> **부제(첫 줄, bold)에 인스턴스 제목**: 예) "{{요청 1건}}의 정상 항해".
|
||||
> 관통 줄기의 *정상 경로* 1회를 깐다. 레이어 경계(누가 누구를 부르나) + 입·출력(구체 값/JSON) 을 보인다.
|
||||
> 아직 안 본 영역은 🌫️(미지의 영역)로 표시하되, 경계를 *넘는 값* 은 보여준다. 마스터 시퀀스 다이어그램 1장은 여기.
|
||||
|
||||
<!--
|
||||
─────────────────────────────────────────────────────────────────────
|
||||
본문 (코드로 따라가기) — 백본 아니라 ### 모듈로 자유롭게. 주제별 가변.
|
||||
관통 줄기의 1건이 *통과하는 순서대로* 안전장치/메커니즘을 한 모듈씩.
|
||||
각 모듈은 아래 패턴을 반복한다 (### 이므로 structure-lint 가 강제하지 않음):
|
||||
|
||||
### {{모듈 제목}} [신입 필수|심화|참조]
|
||||
> **새 용어:** {{이 모듈에서 처음 쓰는 용어 2~3개 just-in-time 정의}}
|
||||
{{실제 코드 블록 + 📄 file:line 캡션 + 한 줄씩 풀이}}
|
||||
{{필요시 mermaid: sequence/state/class diagram}}
|
||||
<details><summary>✅ 이해 점검</summary>
|
||||
1. {{질문}} (정답: {{본문 위치/메서드명}})
|
||||
</details>
|
||||
─────────────────────────────────────────────────────────────────────
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## 그래서 어떤 문제로 "정의" 했나
|
||||
|
||||
> **부제(첫 줄, bold)에 인스턴스**: "{{프로젝트}} 가 {{이 조합}}을 고른 이유". (백본 헤딩엔 넣지 말 것.)
|
||||
> 메시지: "그게 우월해서" 가 아니라 "내가 문제를 그렇게 정의했기 때문". 내가 세운 규칙/제약이 답을 결정했음을 보인다.
|
||||
> 그 다음 *검증된 사실만* (project 문서에서) 간략히. 검증 범위(로컬/dev/prod) 와 "말하면 안 되는 범위" 를 분명히.
|
||||
|
||||
- 내가 세운 규칙 / 문제 정의: {{...}} → 이 규칙이 답을 어떻게 좁혔는가
|
||||
- 실제로 한 것 (`actually-implemented` / `locally-verified` 등급만): {{...}} — 자세히는 `[[wiki/projects/{{project}}/{{slug}}]]`
|
||||
- 검증은 어디까지 / 무엇을 말하면 안 되는가: {{...}}
|
||||
|
||||
---
|
||||
|
||||
## 자가 점검 — 다시 처음 장면으로
|
||||
|
||||
> §1 장면으로 복귀. 답을 *외운 게 아니라 재구성할 수 있는지* 확인하는 질문 5~6개.
|
||||
> 최소 1개는 "문제 정의를 바꾸면 답이 어떻게 바뀌는가", 1개는 "흔한 과장을 반박하라", 1개는 "한 단계 더 깊은 메커니즘".
|
||||
> (모듈별 형성 평가와 별개로, 전체를 관통 줄기로 다시 엮는 종합 점검.)
|
||||
|
||||
1. {{문제 정의를 바꾸면?}}
|
||||
2. {{흔한 단정/과장을 반박하라}}
|
||||
3. {{한 단계 더 깊은 메커니즘/비용}}
|
||||
|
||||
---
|
||||
|
||||
## 근거 자료 (이 설명의 출처 — 모두 canonical)
|
||||
|
||||
- `[[wiki/concepts/{{concept-slug}}]]` — 개념 정의 / Claim-backed 근거 / 과장 금지 (사실의 금고)
|
||||
- `[[wiki/projects/{{project}}/{{slug}}]]` — 내 프로젝트 실제 구현 · 검증 범위 (있을 때만)
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/interview-prep-template.md
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: interview-prep / {{short-question-slug}}
|
||||
source_type: interview-prep
|
||||
status: raw
|
||||
related_branches: []
|
||||
related_projects: []
|
||||
tags: [interview-prep]
|
||||
created: YYYY-MM-DD
|
||||
status_label: collecting
|
||||
---
|
||||
|
||||
# interview-prep: {{short-question-slug}}
|
||||
|
||||
> Layer: `raw/interviews/` — 면접 질문 **원본 수집·연구 노트**. 다듬어진 답변은 `/interviewize` 후 `wiki/interview/`에 별도 작성. 원본은 raw에 영구 보관.
|
||||
> `status_label`: `collecting` | `drafting` | `ready-for-derive` | `derived` | `needs-confirmation`
|
||||
|
||||
> **Citation discipline (필수)**:
|
||||
>
|
||||
> - `## 답변 재료` 의 각 "사실" 항목은 다음 셋 중 하나로 근거를 같이 적는다:
|
||||
> 1. branch-note 의 **Decision ID** (예: "근거: `feature-X.md` D3, D9").
|
||||
> 2. 외부 source 의 **claim ID** (예: `AT-TX-C5`, `SPRING-TX-MGR-C6`) — anchor 인용 가능하면 `<path>.md#<claim-id>`.
|
||||
> 3. branch-note 의 **section** 인용 (예: `feature-X.md §결정 사항`).
|
||||
> - "경험" 은 _내가 직접 한_ 것만. 추론은 "의견 / 해석" 으로 분리.
|
||||
> - "트레이드오프" 는 majority vs minority position 을 명시 (다수파 / 소수파 / 표준 / 비표준). 한쪽만 적으면 답변이 단편적이 된다.
|
||||
> - `## 답변 경계 / Answer boundary` 의 "절대 과장하지 말 것" 은 반드시 채운다 — local-verified 를 prod-verified 처럼 말하지 않기 위한 self-check.
|
||||
> - `## 미해결 / Unknown` 의 "확인 방법" 도 비워두지 말 것 — "공식 문서 다시 보기" / "실 실험" / "후속 branch" 등 구체 방법 명시.
|
||||
|
||||
## 부모
|
||||
|
||||
> 이 질문이 어느 작업·프로젝트에서 나올 수 있는지 명시. **최소 1개 필수.** 특정 작업과 무관한 일반 CS 질문이면 `[[raw/project-notes/<project>]]` (전체 프로젝트 차원) 또는 미연결도 허용 (단, frontmatter `related_projects` 는 채울 것).
|
||||
|
||||
- `[[raw/branch-notes/{{branch-name}}]]` — <왜 이 branch에서 이 질문이 나올 수 있는지 한 줄>
|
||||
- (또는) `[[raw/project-notes/{{project-name}}]]`
|
||||
|
||||
## 질문
|
||||
|
||||
> 면접에서 받을 수 있는 질문 원형. 받았다면 받은 형태 그대로.
|
||||
|
||||
- 질문 원문:
|
||||
- 출처: <실제 받은 질문 / 예상 질문 / 책·블로그에서 발견 / JD에서 유추>
|
||||
- 받은 날짜·맥락 (실제 받은 경우):
|
||||
|
||||
## 질문 의도 추론
|
||||
|
||||
> 면접관이 이 질문으로 무엇을 평가하려 하는지.
|
||||
|
||||
- 핵심 평가 대상: <개념 이해 / 운영 경험 / 트레이드오프 인식 / 의사결정 경험 / 한계 인식>
|
||||
- 함정 / 흔히 빠지는 답변 패턴:
|
||||
- 따라올 만한 후속 질문:
|
||||
|
||||
## 답변 재료
|
||||
|
||||
> 이 단계는 raw. 정리된 답변이 아님. 떠오르는 사실·일화·트레이드오프를 자유롭게 모음.
|
||||
|
||||
- 사실 1 (근거: `[[raw/branch-notes/...]]` 또는 `[[raw/official-docs/...]]`):
|
||||
- 사실 2:
|
||||
- 내가 직접 한 경험 (있다면): `[[raw/branch-notes/...]]`
|
||||
- 트레이드오프:
|
||||
- 한계 / "이건 안 해봤다":
|
||||
|
||||
## 근거 (답변의 사실 근거)
|
||||
|
||||
> 면접에서 자신 있게 말하려면 사실 근거가 있어야 함. raw 또는 wiki canonical 링크.
|
||||
|
||||
- `[[raw/official-docs/<...>]]` — <인용할 만한 핵심 사실>
|
||||
- `[[raw/company-tech-blogs/<...>]]` — <인용할 만한 사례>
|
||||
- `[[wiki/concepts/<...>]]` — (검증된 요약이 있다면)
|
||||
- `[[wiki/projects/<...>]]` — (내 프로젝트 사실, 있다면)
|
||||
|
||||
## 미해결
|
||||
|
||||
> 이 질문에 답하기 위해 더 학습하거나 확인이 필요한 것.
|
||||
|
||||
- 모르는 것 1:
|
||||
- 모르는 것 2:
|
||||
- 확인 방법: <official-doc 다시 읽기 / 실 실험 / 멘토에게 질문>
|
||||
|
||||
## 답변 경계
|
||||
|
||||
> 어디까지 자신 있게 말할 수 있고, 어디부터는 "확인이 필요하다"라고 말해야 하는지.
|
||||
|
||||
- 자신 있게 말할 수 있는 범위:
|
||||
- "이 부분은 공식 문서를 다시 보고 답변드리겠습니다" 라고 해야 하는 부분:
|
||||
- **절대 과장하지 말 것** (예: 검증 안 된 prod 경험을 말하지 말 것):
|
||||
|
||||
## 관련
|
||||
|
||||
> 같은 작업 묶음 내 다른 raw 문서, 또는 같은 주제의 다른 면접 질문.
|
||||
|
||||
- 관련 면접 질문 (선행/후속): `[[raw/interviews/<...>]]`
|
||||
- 영감을 받은 채용공고: `[[raw/job-postings/<...>]]`
|
||||
- 관련 블로그 글감: `[[raw/blog-topics/<...>]]`
|
||||
- 답변 derive 후 위치: `[[wiki/interview/<...>]]` (생성되면)
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/interview-template.md
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title:
|
||||
source_type: interview
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: []
|
||||
related_projects: []
|
||||
last_reviewed:
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/interview/` — 면접 답변용. 말로 했을 때 자연스럽게.
|
||||
|
||||
## 질문
|
||||
|
||||
면접에서 받을 가능성이 있는 질문 원형.
|
||||
|
||||
## 질문 의도
|
||||
|
||||
면접관이 이 질문으로 무엇을 평가하려는가.
|
||||
|
||||
## 짧은 답변 (30초)
|
||||
|
||||
핵심만 1–2문장.
|
||||
|
||||
## 상세 답변 (1–2분)
|
||||
|
||||
배경 → 핵심 개념 → 내 프로젝트 적용 → 결과/한계 순.
|
||||
|
||||
## 사실 / 추론 / 확인 필요
|
||||
|
||||
상세 답변에 들어간 진술을 3분류로 명시.
|
||||
|
||||
- **사실 (verified)** — canonical 문서에 `status: reviewed | verified | published-ready`이고 Sources가 있는 진술
|
||||
- **추론 (inferred)** — canonical 내용을 조합한 결론. 면접 시 추론임을 드러내며 말할 것
|
||||
- **확인 필요 (needs-confirmation)** — wiki에 없거나 stale, 또는 원천 status가 `draft` 이하. **면접 전에 raw 확인 또는 모른다고 답할 준비**
|
||||
|
||||
## 면접에서 말해도 되는 범위
|
||||
|
||||
- **자신 있게 답할 수 있는 부분** (`actually-implemented` / `locally-verified` / `prod-verified` 만):
|
||||
- **모른다고 답해야 하는 부분** (`documented-only` / `planned` / `needs-confirmation`):
|
||||
|
||||
## 꼬리 질문
|
||||
|
||||
- 가능한 후속 질문 1 → 어떻게 답할지
|
||||
- 가능한 후속 질문 2 → 어떻게 답할지
|
||||
|
||||
## 약한 답변 예시 (피해야 할 답)
|
||||
|
||||
- 답변 1: 왜 약한가
|
||||
- 답변 2: 왜 약한가
|
||||
|
||||
## 과장 금지 지점
|
||||
|
||||
이 질문에 답할 때 **사실보다 부풀리기 쉬운 표현**.
|
||||
|
||||
## 근거 자료 (canonical 필수)
|
||||
|
||||
답변의 근거가 된 canonical wiki 문서. `wiki/concepts/` 또는 `wiki/projects/` **반드시 1개 이상**. status, confidence 함께 표기.
|
||||
|
||||
- `[[wiki/concepts/{{...}}]]` — status / confidence
|
||||
- `[[wiki/projects/{{...}}]]` — status / confidence
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- `[[{{관련-concept}}]]`
|
||||
- `[[{{관련-project}}]]`
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/invest-concept-template.md
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title:
|
||||
source_type: invest-concept
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: [invest-concept, personal-invest, finance]
|
||||
last_reviewed: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/invest-concepts/` — 검증된 투자 개념(ETF·금리·환율·분산 등). 내 전략 규칙은 `wiki/invest-strategy/`, 활성 계획은 `wiki/invest-plan/`.
|
||||
|
||||
## Parent
|
||||
|
||||
- `[[wiki/invest/invest-hub]]`
|
||||
|
||||
## Summary
|
||||
|
||||
한두 문장 핵심 정의.
|
||||
|
||||
## Standard (기준)
|
||||
|
||||
공식/학술 기준의 정의. 출처는 Sources 섹션.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
적용 한계·흔한 오해·트레이드오프. 검증된 것만 사실로, 그 외 `needs-confirmation`.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 핵심 설명은 raw 증거 claim으로 뒷받침.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| <설명> | `raw/invest-research/<slug>.md#C1` | `high`/`medium`/`low` | |
|
||||
|
||||
## Strategy 연결
|
||||
|
||||
> 이 개념이 어떤 전략 규칙으로 연결되는지 링크.
|
||||
|
||||
- `[[wiki/invest-strategy/strategy]]` — <어느 규칙>
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
이 개념을 말할 때 과장 금지 지점.
|
||||
|
||||
## 근거 자료
|
||||
|
||||
- [출처 제목](https://...) — 핵심
|
||||
- `[[raw/invest-research/<...>]]` — 보존 원본
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/invest-daily-template.md
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: YYYY-MM-DD 투자 일일 조사
|
||||
source_type: invest-daily
|
||||
status: raw
|
||||
confidence: unknown
|
||||
tags: [invest-daily, personal-invest, macro]
|
||||
date: YYYY-MM-DD
|
||||
last_reviewed: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# YYYY-MM-DD 투자 일일 조사
|
||||
|
||||
> Layer: `raw/invest-daily/` — 그날의 거시 자금흐름 조사. **수치마다 출처 링크 + 조사 시점 필수**(실시간 아님). `/invest-ingest`가 검증 가능한 항목만 `wiki/invest-concepts/`로 추출. 원본은 raw에 영구 보관.
|
||||
|
||||
## Parent
|
||||
|
||||
> 이 노트가 속한 cluster 루트로 upward link (linking-rules).
|
||||
|
||||
- `[[wiki/invest/invest-hub]]`
|
||||
|
||||
## 고정 체크리스트 (매일 동일)
|
||||
|
||||
> 각 항목은 **수치 + 방향(↑/↓) + 출처 + 조사시점**. 모르면 비우되 추측 금지.
|
||||
|
||||
| 자산군 | 핵심 지표 | 값 / 방향 | 출처 | 조사시점 |
|
||||
|---|---|---|---|---|
|
||||
| 금리 | 미 10Y / 한 기준금리 | | | |
|
||||
| 환율 | USD/KRW | | | |
|
||||
| 원자재 | WTI / 금 | | | |
|
||||
| 주요지수 | S&P500 / KOSPI / 나스닥 | | | |
|
||||
| 코인 | BTC / ETH | | | |
|
||||
|
||||
## 오늘의 이슈 (가변)
|
||||
|
||||
> 그날 가장 큰 움직임·뉴스. 각 항목 출처 링크 필수.
|
||||
|
||||
- 이슈 1 — <한 줄> ([출처](https://...), 조사 YYYY-MM-DD)
|
||||
|
||||
## 관찰·가설 (미검증)
|
||||
|
||||
> 내 해석. **검증 전이므로 사실 아님.** canonical로 옮기기 전 `/invest-research`로 확인 대상.
|
||||
|
||||
- 가설 1:
|
||||
|
||||
## Promotable 후보
|
||||
|
||||
> `/invest-ingest`로 `wiki/invest-concepts/` 또는 `invest-strategy/`에 올릴 만한 것만 표기.
|
||||
|
||||
- 후보 1 (→ 어떤 canonical 문서로?)
|
||||
|
||||
## 분야 관찰
|
||||
|
||||
> 오늘 움직인 분야 카드와, 그 카드가 예측한 연결이 실측과 맞았는지 대조. 루프의 엔진 — 맞으면 `[가설]`→`[검증]` 승격 후보, 틀리면 새 학습거리. 카드 허브는 `[[wiki/invest-concepts/field-map]]`.
|
||||
|
||||
| 오늘 움직인 카드 | 방향 | 그 카드 예측 연결이 맞았나?(확인/반증) | 새 가설/메모 |
|
||||
|---|---|---|---|
|
||||
| `[[wiki/invest-concepts/field-dollar]]` | | | |
|
||||
|
||||
## 출처
|
||||
|
||||
> deep-research 가 조사한 **전(全) 출처**를 여기 남긴다 — "어디서 뭘 확인했나" 추적용. 각 줄에 `[primary/secondary/blog/unreliable]` 등급 + URL. 교차검증 실패(claims:0)·`[unreliable]` 출처도 *조사는 했으나 미채택* 기록으로 남겨 투명성 확보. 조사 통계(N각도·M출처·검증 confirmed/killed)도 1줄.
|
||||
|
||||
- (deep-research 채움 — 각도별/등급별로 전 출처 나열)
|
||||
|
||||
## Related
|
||||
|
||||
- 어제 노트: `[[raw/invest-daily/{{어제}}]]`
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/invest-field-card-template.md
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title:
|
||||
source_type: invest-concept
|
||||
status: draft
|
||||
confidence: low
|
||||
tags: [invest-concept, field-card, macro-asset]
|
||||
last_reviewed: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/invest-concepts/` — 분야(자산군·섹터) 지식 카드. 노드 1장 = 분야 1개, 관계는 wikilink 엣지. **모든 관계 행에 `[검증]/[가설]` 라벨 필수.** `[가설]`은 외부 산출물 사용 금지(파생 규칙). 세무·투자 자문 아님 — `[[wiki/invest-strategy/strategy]]` §고지.
|
||||
|
||||
## Parent
|
||||
|
||||
- `[[wiki/invest-concepts/field-map]]`
|
||||
|
||||
## 한 줄 정의
|
||||
|
||||
> 이 분야가 뭔지 한 문장.
|
||||
|
||||
## 무엇이 이걸 움직이나
|
||||
|
||||
> 이 분야를 위/아래로 미는 입력 요인. 각 행에 `[검증]/[가설]` + 근거.
|
||||
|
||||
| 요인 | 방향 | 메커니즘 | 검증/가설 | 근거 |
|
||||
|---|---|---|---|---|
|
||||
|
||||
## 연결
|
||||
|
||||
> ★ 엣지 — 이게 움직이면 *따라오는* 것. 다른 카드로 wikilink 연결.
|
||||
|
||||
| 이게 ↑하면 | → 따라 | 메커니즘 | 검증/가설 | 근거 |
|
||||
|---|---|---|---|---|
|
||||
|
||||
## 대장주 / 추종주 (Leaders & Followers)
|
||||
|
||||
> (산업 섹터 카드에만 — 자산군 카드는 생략 가능) 대장주(선행·시총/거래 주도)와 따라 움직이는 추종주. 대장주가 움직이면 추종주를 본다. **종목 선정·동조 관계는 전부 `[가설]`** — `/invest-research`로 검증.
|
||||
|
||||
| 종목(티커) | 역할 | 왜(동조 근거) | 검증/가설 |
|
||||
|---|---|---|---|
|
||||
|
||||
## 관찰 지표
|
||||
|
||||
> 이 분야 상태를 매일 보는 구체 지표·티커(invest-daily가 잡을 것).
|
||||
|
||||
-
|
||||
|
||||
## 경기 사이클 위치
|
||||
|
||||
- 회복/확장/둔화/침체 중 언제 강·약
|
||||
|
||||
## 검증 상태
|
||||
|
||||
- `[검증]` N개 · `[가설]` M개 (관찰 누적 → `/invest-research`로 승격)
|
||||
|
||||
## 근거 자료
|
||||
|
||||
- `[[wiki/invest-strategy/strategy]]`
|
||||
|
||||
## Related
|
||||
|
||||
> 연결된 카드(= 그래프 엣지).
|
||||
|
||||
-
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/invest-ledger-template.md
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: 매매 원장 / Trade Ledger
|
||||
source_type: invest-ledger
|
||||
status: raw
|
||||
confidence: unknown
|
||||
tags: [invest-ledger, personal-invest, finance]
|
||||
created: YYYY-MM-DD
|
||||
last_reviewed: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# 매매 원장
|
||||
|
||||
> Layer: `raw/invest-ledger/` — 실제 매수/매도의 **사실 기록**. 단일 원장 파일에 모든 거래를 누적(설계 §8-3). `/invest-decide`가 행을 추가하며 `wiki/invest-strategy/`의 규칙 위반을 체크. wiki로 옮기지 않음.
|
||||
|
||||
## Parent
|
||||
|
||||
- `[[wiki/invest/invest-hub]]`
|
||||
|
||||
## 현재 포지션
|
||||
|
||||
| 종목/티커 | 분류(코어/베팅) | 보유수량 | 평균단가 | 현재 비중% | 메모 |
|
||||
|---|---|---|---|---|---|
|
||||
|
||||
## 거래 내역
|
||||
|
||||
> 시간 역순(최신 위). 모든 행은 근거 문서 링크 필수.
|
||||
> ⚠️ **실손익 = (단가×수량) − 수수료 ± 환차손익 − 세금.** 해외상장 ETF는 **양도세(연 250만 공제 후 22%, 손익통산)** + **체결 환율** 이 손익에 실질적 영향 → 아래 컬럼에 기록. 국내상장 ETF/주식은 세제가 다름(증권거래세·배당소득세).
|
||||
|
||||
| 날짜 | 매수/매도 | 종목 | 수량 | 단가 | 수수료 | 체결환율 | 금액(원) | 계좌 | 근거(링크) | 규칙체크 |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|
|
||||
|
||||
## 규칙 위반 이력
|
||||
|
||||
> `/invest-decide`가 빨간 플래그를 낸 건 기록. 무시하고 진행했다면 그 사유도.
|
||||
|
||||
| 날짜 | 위반 규칙 | 내용 | 사용자 처리 |
|
||||
|---|---|---|---|
|
||||
|
||||
## 손익 요약
|
||||
|
||||
> `/invest-review` 실행 시 갱신.
|
||||
|
||||
- 총 투입원금:
|
||||
- 평가금액:
|
||||
- 실현손익:
|
||||
- 목표 대비:
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/invest-plan-template.md
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title:
|
||||
source_type: invest-plan
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: [invest-plan, personal-invest, finance]
|
||||
last_reviewed: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/invest-plan/` — 현재 활성 투자 계획. `wiki/invest-strategy/` 규칙 + 최근 `raw/invest-research/`·`raw/invest-daily/` 조사에서 도출. **모든 항목은 canonical/증거 근거 링크 필수.**
|
||||
> ⚠️ 면허 자문 아님 — `[[wiki/invest-strategy/strategy]]` §고지 참조.
|
||||
> 📐 **이 템플릿의 목적 = 구체성 강제.** "광범위 ETF를 산다" 수준이 아니라 *어떤 종목을·얼마를·언제·어느 계좌에서·자본이 커지면 어떻게 바꾸는가*까지 박는다. 비어 있으면 `NEEDS_DECISION` 라벨.
|
||||
|
||||
## Parent
|
||||
|
||||
- `[[wiki/invest/invest-hub]]`
|
||||
|
||||
## 현재 자본·목표·계좌
|
||||
|
||||
> strategy 프로필에서 끌어온 기준점. 한 줄씩 *구체 숫자*로.
|
||||
|
||||
- 가용 자본: **{{원금}}** ({{여유자금 여부·출처}})
|
||||
- **현재 자본 구간**: {{strategy ① 구간 매핑 — 예: ~200만 이하}} → 기본 전략 {{예: 광범위 ETF 1~2개}}
|
||||
- MDD 수용 / 주식 비중: **{{예: ~-40% / 주식 90~100%}}** (`[[wiki/invest-strategy/strategy]]` 프로필)
|
||||
- 계좌: **{{예: 일반 위탁계좌}}** ({{근거 링크}})
|
||||
- 매수 방식: **{{일시매수 | 분할(DCA) N회}}** ({{근거 — strategy ⑤}})
|
||||
- 이번 분기 목표: {{고정 목표금액 없음이면 그렇게 — 분기는 "정산" 아니라 "점검"}}
|
||||
|
||||
## 목표 자산 배분
|
||||
|
||||
| 자산 | 분류(코어/완충/베팅) | 목표 비중% | 근거(링크) |
|
||||
|---|---|---|---|
|
||||
| {{광범위 주식 ETF}} | 코어 | {{%}} | {{strategy ① / invest-research}} |
|
||||
| {{현금 완충}} | 완충 | {{%}} | {{심리·리밸런스 — UNSUPPORTED_IMPL_DECISION이면 표기}} |
|
||||
|
||||
## 보유 종목
|
||||
|
||||
> 실제 보유 현황. `[[raw/invest-ledger/ledger]]`와 동기화(원장이 사실 SSOT, 여기는 목표 대비 현황). 매수 전이면 "없음".
|
||||
|
||||
| 종목/티커 | 분류 | 보유수량 | 평단 | 현재 비중% | 목표 비중% | 근거(링크) |
|
||||
|---|---|---|---|---|---|---|
|
||||
| {{미정이면 — 4단계서 확정}} | | | | | | |
|
||||
|
||||
## 매수 실행
|
||||
|
||||
> **무엇을·얼마를·언제·어느 계좌에서.** 이 § 가 비면 "내일 뭘 누를지" 답이 없는 것.
|
||||
|
||||
- **무엇을 (종목)**: {{구체 티커 1개 — 미정이면 `NEEDS_DECISION` + 좁히는 invest-research 링크}}
|
||||
- **얼마를 (금액)**: {{예: 100만 일시 / 25만×4회}}
|
||||
- **언제·어떻게 (스케줄)**: {{일시매수면 "1회" / 분할이면 주기·간격 표}}
|
||||
- **다음 매수 트리거**: {{추가납입 시점 — 소득 발생 / 정기 / 자본 구간 전환}}
|
||||
- **매수 후**: `/invest-decide`로 `[[raw/invest-ledger/ledger]]`에 기록(규칙 위반 자동 체크).
|
||||
|
||||
## 자본 성장 로드맵
|
||||
|
||||
> "100만으로 시작해 키운다"의 *체계*. strategy ① 자본 구간 규칙 + ④ 절세계좌 조건을 단계로 펼침. **각 단계 전환은 자본 임계치 / 소득 발생 같은 명시적 트리거로.**
|
||||
|
||||
| 단계 | 자본 구간 | 전략 (strategy ① 매핑) | 계좌·절세 (strategy ④) | 전환 트리거 |
|
||||
|---|---|---|---|---|
|
||||
| **현재** {{▶ 표시}} | {{~200만}} | {{광범위 ETF 1~2개}} | {{일반계좌, 절세계좌 보류}} | — |
|
||||
| 다음 | {{200~1,000만}} | {{ETF 코어 + 위성 1~2}} | {{소득 발생 시 ISA/연금 재검토}} | {{자본 200만 돌파 OR 소득 발생}} |
|
||||
| 그다음 | {{1,000만~}} | {{자산군 배분 본격화}} | {{}} | {{자본 1,000만 돌파}} |
|
||||
|
||||
- **소득 발생 시 (별도 트리거)**: ① 월 추가납입 시작 → 매수 실행 § 갱신, ② **절세계좌 재검토** — 결정세액 생기면 ISA 손익통산·연금 세액공제 가치 발생(`[[raw/invest-research/2026-06-08-isa-vs-general-account-no-income]]` 무소득 시 실익 없음 결론이 뒤집힘), ③ MDD·목표 재설정 가능.
|
||||
|
||||
## 리밸런싱·점검 규칙
|
||||
|
||||
> 언제·무엇을 점검하나. `/invest-review`가 이 규칙으로 돈다.
|
||||
|
||||
- **점검 주기**: {{예: 분기 1회}}. 분기말 하락장이어도 강제매도 ❌ (strategy ②).
|
||||
- **리밸런싱 밴드**: 목표 배분 **±5%p** 이탈 시 검토 (strategy ①, 재량 — 잦은 매매 경계).
|
||||
- **점검 체크리스트**: ① 비중 drift ② stale 조사(90일+) ③ 규칙 위반 매매 ④ 자본 구간 전환 도달 여부.
|
||||
|
||||
## 워치리스트
|
||||
|
||||
| 종목/티커(유형) | 왜 후보인가 | 검증 상태(invest-research 링크) | 진입 조건 |
|
||||
|---|---|---|---|
|
||||
|
||||
## 리스크·한계
|
||||
|
||||
- 이 계획이 틀릴 수 있는 지점: {{단일 최대 전제부터}}
|
||||
- 말하면 안 되는 범위(검증 안 된 것): {{미검증·기각 claim}}
|
||||
|
||||
## 규칙 사전 점검 (Rule Pre-check)
|
||||
|
||||
> 계획이 strategy ①~⑤를 위반하지 않는지. 위반 시 플래그.
|
||||
|
||||
- ① 포지션 크기: {{}} → 준수/위반
|
||||
- ② 손절/익절: {{}} → 준수/위반
|
||||
- ③ 행동 가드레일: {{}} → 준수/위반
|
||||
- ④ 절세계좌: {{}} → 준수/위반
|
||||
- 위반: {{없음 / 목록}}
|
||||
|
||||
## 근거 자료
|
||||
|
||||
- `[[wiki/invest-strategy/strategy]]`
|
||||
- `[[raw/invest-research/<...>]]`
|
||||
- `[[raw/invest-daily/<...>]]`
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/invest-research-template.md
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title:
|
||||
source_type: invest-research
|
||||
status: raw
|
||||
confidence: unknown
|
||||
url:
|
||||
archive_url:
|
||||
tags: [invest-research, personal-invest, finance]
|
||||
created: YYYY-MM-DD
|
||||
last_reviewed: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `raw/invest-research/` — 특정 분야/자산/주장에 대한 심층 조사. **외부 출처의 verbatim 인용 보존**(evidence-first-research). 검증된 결론만 `/invest-ingest`로 `wiki/invest-concepts/` 또는 `invest-strategy/`로 추출.
|
||||
|
||||
## Parent
|
||||
|
||||
- `[[wiki/invest/invest-hub]]`
|
||||
|
||||
## 조사 질문
|
||||
|
||||
> 무엇을 확인하려고 조사했는가 1~2줄.
|
||||
|
||||
## 출처
|
||||
|
||||
| # | 제목 | 출처 등급 | URL | 발행/조사일 |
|
||||
|---|---|---|---|---|
|
||||
| S1 | | official / vendor-research / academic / media / blog(약함) | | |
|
||||
|
||||
## 핵심 인용
|
||||
|
||||
> 원문 그대로. 출처 # 표기. 의역 금지.
|
||||
|
||||
> [S1] "원문 발췌 1."
|
||||
|
||||
## 추출된 주장
|
||||
|
||||
> 출처가 **직접 말하는 것만**. 내 적용 결론은 여기 쓰지 않음. Claim ID는 문서 내 안정 유지.
|
||||
|
||||
| Claim ID | Claim | Evidence quote | Strength | 적용 조건 | 증명 못 하는 것 |
|
||||
|---|---|---|---|---|---|
|
||||
| C1 | | [S1] "<인용>" | academic / official / vendor-research / media / needs-confirmation | | |
|
||||
|
||||
## 판정
|
||||
|
||||
> 각 Claim에 대한 KEEP / CORRECT / REJECT + 한 줄 사유.
|
||||
|
||||
- C1: KEEP — <사유>
|
||||
|
||||
## 적용 경계
|
||||
|
||||
- 직접 증명하는 것:
|
||||
- 증명하지 않는 것:
|
||||
- 내 상황(소액·국내 거주)에 적용하려면 추가 확인할 것:
|
||||
|
||||
## Related
|
||||
|
||||
- 같은 주제 다른 조사: `[[raw/invest-research/<...>]]`
|
||||
- 이 조사를 인용한 canonical: `[[wiki/invest-strategy/strategy]]` (생성 시)
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/invest-strategy-template.md
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title:
|
||||
source_type: invest-strategy
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: [invest-strategy, personal-invest, finance]
|
||||
last_reviewed: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/invest-strategy/` — 내 투자 전략 규칙. `/invest-decide`가 이 문서의 고정 규칙과 매매를 대조한다.
|
||||
|
||||
## ⚠️ 고지 (Disclaimer)
|
||||
|
||||
> **면허 있는 투자자문이 아님.** Claude는 환각으로 틀릴 수 있고 손실에 책임지지 않는다. 모든 수치는 조사 시점 기준이며 본인이 출처로 교차검증한다. 이 시스템은 "규율 강제 + 리서치 보조"이지 자산관리사가 아니다.
|
||||
|
||||
## Parent
|
||||
|
||||
- `[[wiki/invest/invest-hub]]`
|
||||
|
||||
## 내 프로필 (규칙 기준점)
|
||||
|
||||
- 시작 자본:
|
||||
- 목표 금액 / 기간:
|
||||
- 월 추가납입:
|
||||
- 최대 감내손실(MDD):
|
||||
- **현재 과세소득(결정세액) 유무:** <있음/없음/미확인 — 절세계좌 규칙이 의존. 미확인 시 연금계좌 권고 보류>
|
||||
|
||||
## ① 포지션 크기 규칙 (자본 구간별)
|
||||
|
||||
| 자본 구간 | 기본 전략 | 근거 |
|
||||
|---|---|---|
|
||||
|
||||
## 익절 규칙
|
||||
|
||||
- 코어(광범위 ETF):
|
||||
- 개별 베팅: <두면 `UNSUPPORTED_DECISION` 라벨 + "근거 아닌 재량" 명시>
|
||||
|
||||
## ③ 행동 가드레일
|
||||
|
||||
- 패닉셀 쿨다운:
|
||||
- FOMO 가드:
|
||||
- 거래 빈도 상한:
|
||||
- 선근거 원칙:
|
||||
|
||||
## ④ 절세계좌 우선순위 (조건부)
|
||||
|
||||
- 사전 체크:
|
||||
- 계좌별 한도(연도 명시):
|
||||
|
||||
## ⑤ 목표·금액
|
||||
|
||||
- (위 프로필과 연결)
|
||||
|
||||
## 규칙 근거
|
||||
|
||||
> 각 규칙이 어느 증거에서 도출됐는지. 근거 없는 규칙은 `UNSUPPORTED_DECISION` 라벨.
|
||||
|
||||
| 규칙 | Supporting Claim | 판정 |
|
||||
|---|---|---|
|
||||
|
||||
## 근거 자료
|
||||
|
||||
- `[[raw/invest-research/<...>]]`
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/job-posting-template.md
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: job-posting / {{company}}-{{role-slug}}
|
||||
source_type: job-posting
|
||||
status: raw
|
||||
related_branches: []
|
||||
related_projects: []
|
||||
tags: [job-posting]
|
||||
created: YYYY-MM-DD
|
||||
posting_url:
|
||||
archive_url:
|
||||
status_label: collected
|
||||
---
|
||||
|
||||
# job-posting: {{company}} — {{role}}
|
||||
|
||||
> Layer: `raw/job-postings/` — 채용공고 **원본 수집·블로그 글감 추출**. 다듬어진 블로그 초안은 `/blogify` 후 `wiki/blog/`에 별도 작성. 원본은 raw에 영구 보관.
|
||||
> `status_label`: `collected` | `analyzed` | `topics-extracted` | `derived-to-blog` | `passed-on`
|
||||
|
||||
## 부모
|
||||
|
||||
> 이 채용공고가 어느 작업·프로젝트와 연결되는지. **최소 1개 필수.** 특정 작업과 무관한 일반 시장 조사면 `[[raw/project-notes/<project>]]` (커리어 메인 프로젝트) 로 연결.
|
||||
|
||||
- `[[raw/branch-notes/{{branch-name}}]]` — <어떤 작업과 연관된 채용 요건인지>
|
||||
- (또는) `[[raw/project-notes/{{project-name}}]]`
|
||||
|
||||
## 채용공고 출처
|
||||
|
||||
- 회사: {{company}}
|
||||
- 역할: {{role}}
|
||||
- 공고 URL: <원본 URL>
|
||||
- 아카이브 URL:
|
||||
- 수집 날짜: YYYY-MM-DD
|
||||
- 마감 (있다면):
|
||||
|
||||
## 요구 사항
|
||||
|
||||
> 공고에서 직접 인용. 자기 해석 추가하지 말 것. 해석은 §분석에 별도.
|
||||
|
||||
- 필수 (Required):
|
||||
- <원문 인용 1>
|
||||
- <원문 인용 2>
|
||||
- 우대 (Preferred):
|
||||
- <원문 인용 1>
|
||||
- <원문 인용 2>
|
||||
|
||||
## 분석
|
||||
|
||||
> 위 원문에 대한 내 해석. 사실과 분리.
|
||||
|
||||
### 내가 이미 갖춘 것
|
||||
|
||||
- <항목> — 근거: `[[raw/branch-notes/<...>]]` 또는 `[[wiki/projects/<...>]]`
|
||||
|
||||
### 부족한 것
|
||||
|
||||
- <항목> — 학습 계획: <어떻게 보강할지>
|
||||
|
||||
### 흥미로운 신호
|
||||
|
||||
- <기술 스택이나 키워드 중 처음 보는 것 / 트렌드 신호>
|
||||
|
||||
## 블로그 글감
|
||||
|
||||
> 이 공고가 자극한 글감. wiki/blog/ 초안 후보가 됨.
|
||||
|
||||
- 글감 1: <한 문장 요지>
|
||||
- 타깃 독자:
|
||||
- 인용할 raw 자료: `[[raw/official-docs/<...>]]`, `[[raw/branch-notes/<...>]]`
|
||||
- 예상 derived 위치: `[[wiki/blog/<slug>]]`
|
||||
- 글감 2: ...
|
||||
|
||||
## 면접 글감
|
||||
|
||||
> 이 공고가 자극한 면접 질문 후보. raw/interviews/로 분리해 별도 노트 만들지 결정.
|
||||
|
||||
- 예상 질문 1 — 후속 raw 노트: `[[raw/interviews/<...>]]` (생성 시)
|
||||
- 예상 질문 2: ...
|
||||
|
||||
## 근거 자료
|
||||
|
||||
> 공고 평가 또는 글감 작성에 인용된 자료.
|
||||
|
||||
- `[[raw/official-docs/<...>]]`
|
||||
- `[[raw/company-tech-blogs/<...>]]`
|
||||
|
||||
## 결정
|
||||
|
||||
> 이 공고에 대한 액션. 면접 준비 / 블로그 초안 작성 / 패스 / 보관만.
|
||||
|
||||
- 액션: `apply` | `prep-only` | `blog-only` | `pass-but-archive`
|
||||
- 이유 (1~2줄):
|
||||
|
||||
## 관련
|
||||
|
||||
- 같은 회사 다른 공고: `[[raw/job-postings/<...>]]`
|
||||
- 유사 역할 다른 공고: `[[raw/job-postings/<...>]]`
|
||||
- 파생된 블로그: `[[wiki/blog/<...>]]`
|
||||
- 파생된 면접 노트: `[[raw/interviews/<...>]]`
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/lecture-note-template.md
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: lecture / {{course-slug}}-{{episode-or-topic}}
|
||||
source_type: lecture
|
||||
status: raw
|
||||
related_branches: []
|
||||
related_projects: []
|
||||
tags: [lecture]
|
||||
created: YYYY-MM-DD
|
||||
course:
|
||||
instructor:
|
||||
episode:
|
||||
duration:
|
||||
url:
|
||||
archive_url:
|
||||
status_label: in-progress
|
||||
---
|
||||
|
||||
# lecture: {{course}} — {{episode-or-topic}}
|
||||
|
||||
> Layer: `raw/lectures/` — 강의·강연·컨퍼런스 발표의 **원본 발췌 + 학습 메모**. 검증된 개념 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.
|
||||
> `status_label`: `in-progress` | `done` | `reviewed` | `concepts-extracted` | `needs-confirmation`
|
||||
|
||||
## 부모
|
||||
|
||||
> 이 강의를 들은 동기. **최소 1개 필수.** 특정 작업을 위한 학습이면 branch, 프로젝트 차원 일반 학습이면 project.
|
||||
|
||||
- `[[raw/branch-notes/{{branch-name}}]]` — <어떤 작업을 위해 이 강의를 학습>
|
||||
- (또는) `[[raw/project-notes/{{project-name}}]]` — <전체 프로젝트 차원 학습>
|
||||
|
||||
## 강의 출처
|
||||
|
||||
- 코스 / 강연: {{course}}
|
||||
- 강사 / 발표자: {{instructor}}
|
||||
- 에피소드 / 챕터: {{episode}}
|
||||
- 길이: {{duration}}
|
||||
- URL: <강의 URL>
|
||||
- 아카이브 URL:
|
||||
- 시청 날짜: YYYY-MM-DD
|
||||
|
||||
## 왜 들었는지
|
||||
|
||||
> 이 강의를 본 이유. 어떤 문제·궁금증·작업과 연결되는가.
|
||||
|
||||
<1~2줄>
|
||||
|
||||
## 핵심 인용
|
||||
|
||||
> 강사의 발언을 그대로. 자기 해석 추가하지 말 것 (별도 § 학습 메모).
|
||||
|
||||
- [HH:MM:SS] "<verbatim 발췌 1>"
|
||||
- [HH:MM:SS] "<verbatim 발췌 2>"
|
||||
- [HH:MM:SS] "<verbatim 발췌 3>"
|
||||
|
||||
## 핵심 개념
|
||||
|
||||
> 강의에서 다룬 개념의 raw 정리. 이 단계는 자기 이해 수준의 메모. 검증된 정의는 wiki/concepts로 옮길 때 만듦.
|
||||
|
||||
- 개념 1:
|
||||
- 강사의 설명 (요약):
|
||||
- 내 이해 (자신 없으면 `needs-confirmation`):
|
||||
- 인접 개념:
|
||||
- 개념 2: ...
|
||||
|
||||
## 학습 메모
|
||||
|
||||
> 강의를 들으며 떠오른 생각·연결·반론. 강사의 사실과 분리.
|
||||
|
||||
- 내 프로젝트와의 연결: `[[raw/branch-notes/<...>]]`
|
||||
- 강사 의견과 다른 점이 있다면:
|
||||
- 추가 확인이 필요한 것:
|
||||
|
||||
## 보강 자료
|
||||
|
||||
> 강의 외에 같이 본 공식 문서·블로그.
|
||||
|
||||
- `[[raw/official-docs/<...>]]` — <어떤 부분을 보강하는지>
|
||||
- `[[raw/company-tech-blogs/<...>]]`
|
||||
|
||||
## 작업 항목
|
||||
|
||||
> 이 강의 결과 해야 할 일.
|
||||
|
||||
- [ ] 관련 branch에서 실험 해보기 — `[[raw/branch-notes/<...>]]`
|
||||
- [ ] wiki/concepts/ 로 추출할 개념: <개념 슬러그>
|
||||
- [ ] 후속 강의·문서: <다음에 볼 자료>
|
||||
|
||||
## 관련
|
||||
|
||||
- 같은 코스 다른 에피소드: `[[raw/lectures/<...>]]`
|
||||
- 유사 주제 다른 강의: `[[raw/lectures/<...>]]`
|
||||
- 파생된 wiki 개념: `[[wiki/concepts/<...>]]` (생성 시)
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/portfolio-template.md
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
title:
|
||||
source_type: portfolio
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: [portfolio]
|
||||
related_projects: []
|
||||
last_reviewed:
|
||||
canonical_sources: []
|
||||
audience: recruiter
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/portfolio/` — **외부 공개용 프로젝트 요약**. canonical (`wiki/projects/`) 에서 파생된 산출물. 면접관·이력서 reader·포트폴리오 사이트 대상.
|
||||
> 상태: draft → reviewed → verified → **published-ready** (이력서·README·외부 게시 가능)
|
||||
> `audience`: `recruiter` | `tech-lead` | `cs-interviewer` | `general` — 톤·깊이가 달라짐.
|
||||
|
||||
## 부모 (필수)
|
||||
|
||||
> wiki/portfolio/ 는 derived layer. **반드시 canonical wiki/projects/ 에서 파생.** raw 또는 branch에서 직접 파생 금지.
|
||||
|
||||
- `[[wiki/projects/{{project-slug}}]]` (필수, 최소 1개)
|
||||
- 추가 wiki/projects 인용:
|
||||
- `[[wiki/projects/<...>]]`
|
||||
- 보조 wiki/concepts:
|
||||
- `[[wiki/concepts/<...>]]`
|
||||
|
||||
## 한 줄 요약
|
||||
|
||||
> 30초 자기소개 한 줄. 무엇을 했고 왜 그 가치가 있는지.
|
||||
|
||||
<한 줄>
|
||||
|
||||
## 문제
|
||||
|
||||
> 이 프로젝트가 해결한 문제. 추상적 표현 금지 — 구체 수치·시나리오로.
|
||||
|
||||
- 직면한 문제:
|
||||
- 영향 범위:
|
||||
- 측정 가능한 손실 (있다면 — latency / 비용 / 사고 빈도):
|
||||
|
||||
## 해결
|
||||
|
||||
> 이 프로젝트에서 한 핵심 결정 3~5개. 트레이드오프와 함께.
|
||||
|
||||
- 결정 1: <무엇을> — 이유: <왜> — 트레이드오프: <대안 대비 손해 본 것>
|
||||
- 결정 2: ...
|
||||
- 결정 3: ...
|
||||
|
||||
## 결과
|
||||
|
||||
> 측정 가능한 결과만. 짐작·과장 금지. 측정 안 한 것은 "측정 X"로 명시.
|
||||
|
||||
- 측정 1 (자동화·테스트·로그): <before → after>
|
||||
- 측정 2 (운영 기록·인시던트 빈도): <before → after>
|
||||
- 측정 안 한 것: <항목>
|
||||
|
||||
## 기술 스택
|
||||
|
||||
> 실제 사용한 것만. "쓸 줄 안다" 와 "이 프로젝트에 썼다" 를 구분.
|
||||
|
||||
- 핵심: <Java 21, Spring Boot 3.4, ...>
|
||||
- 보조: <...>
|
||||
- 의식적으로 안 쓴 것 (있으면 면접 차별화): <...>
|
||||
|
||||
## 익혀야 할 것
|
||||
|
||||
> 면접관·리뷰어가 이 포트폴리오를 읽고 "이 분야를 안다"고 판단할 수 있는 항목. 자기 학습 가이드 역할도 함.
|
||||
|
||||
- 익혀서 자신 있게 답할 수 있어야 할 개념: `[[wiki/concepts/<...>]]`
|
||||
- 실제 구현 결정에 대해 변호할 수 있어야 함: `[[wiki/projects/<...>]]`
|
||||
- 인용한 출처를 자신 있게 인용 가능해야 함: `[[raw/official-docs/<...>]]`, `[[raw/company-tech-blogs/<...>]]`
|
||||
|
||||
## 답할 수 있는 범위
|
||||
|
||||
> 면접에서 자신 있게 답할 수 있는 부분 / "확인이 필요하다"라고 말해야 하는 부분 명시.
|
||||
|
||||
- 자신 있게 답할 수 있는 범위:
|
||||
- "공식 문서를 다시 확인하고 답변드리겠습니다" 라고 해야 하는 부분:
|
||||
- 절대 과장하지 말 것 (예: 검증 안 된 prod 경험을 prod-verified로 말하지 말 것):
|
||||
|
||||
## 한계
|
||||
|
||||
> 이 프로젝트가 못 한 것. 솔직하게.
|
||||
|
||||
- 검증 안 한 영역:
|
||||
- 시간 부족으로 미룬 것:
|
||||
- 알면서 안 한 결정 (트레이드오프):
|
||||
|
||||
## 근거 (canonical 인용 필수)
|
||||
|
||||
> derived 산출물의 모든 사실 주장은 canonical 인용으로 뒷받침.
|
||||
|
||||
- `[[wiki/projects/<...>]]` — <어떤 결정의 출처>
|
||||
- `[[wiki/concepts/<...>]]` — <어떤 개념의 출처>
|
||||
|
||||
## 외부 링크
|
||||
|
||||
- GitHub 저장소:
|
||||
- 데모:
|
||||
- 관련 블로그 글: `[[wiki/blog/<...>]]`
|
||||
|
||||
## 관련
|
||||
|
||||
- 다른 포트폴리오 항목: `[[wiki/portfolio/<...>]]`
|
||||
- 관련 면접 답변: `[[wiki/interview/<...>]]`
|
||||
- 관련 블로그 글: `[[wiki/blog/<...>]]`
|
||||
|
||||
## 게시 체크리스트
|
||||
|
||||
`published-ready` 로 올리기 전 확인.
|
||||
|
||||
- [ ] 모든 측정값이 실측이거나 "측정 X" 로 명시됨
|
||||
- [ ] 과장 단어 (`완벽`, `극한`, `100%`, `최고`) 없음
|
||||
- [ ] 모든 사실 주장에 canonical 링크 있음
|
||||
- [ ] 답할 수 있는 범위 / 한계 섹션 채움
|
||||
- [ ] `/lint` 통과
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/project-report-template.md
|
||||
@@ -0,0 +1,279 @@
|
||||
---
|
||||
title: ""
|
||||
source_type: "report"
|
||||
status: "draft"
|
||||
confidence: "unknown"
|
||||
derived_from:
|
||||
- "wiki/projects/<canonical-project-doc>"
|
||||
- "raw/branch-notes/<optional-branch-note>"
|
||||
related_projects:
|
||||
- "ca-tmpl"
|
||||
audience: "self"
|
||||
purpose: "big-picture-understanding"
|
||||
last_reviewed: ""
|
||||
status_label: "draft"
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> 이 문서는 이해를 위한 derived report입니다.
|
||||
> SSOT는 `raw/branch-notes/`와 `wiki/projects/`의 canonical 문서입니다.
|
||||
> 이 문서는 ca-tmpl 전체 구조를 사람이 읽고 설명할 수 있도록 재구성합니다.
|
||||
|
||||
---
|
||||
|
||||
## 0. Reading Guide
|
||||
|
||||
### 이 문서는 무엇을 설명하는가
|
||||
|
||||
`<ca-tmpl 전체 구조, 목표, 핵심 계약, 구현 상태를 설명한다.>`
|
||||
|
||||
### 먼저 읽어야 할 사람
|
||||
|
||||
- `<ca-tmpl의 큰 그림이 아직 안 잡힌 사람>`
|
||||
- `<branch-note를 읽기 전에 전체 지도가 필요한 사람>`
|
||||
- `<Clean Architecture skeleton의 운영 계약이 왜 필요한지 이해하려는 사람>`
|
||||
|
||||
### 이 문서를 읽고 답할 수 있어야 하는 질문
|
||||
|
||||
- ca-tmpl은 무엇인가?
|
||||
- 왜 도메인 기능을 제거했는가?
|
||||
- 왜 운영 계약이 skeleton의 중심인가?
|
||||
- 왜 branch-note가 많은가?
|
||||
- 각 branch-note는 전체 skeleton의 어느 영역을 책임지는가?
|
||||
- 현재 구현된 것과 아직 문서만 있는 것은 무엇인가?
|
||||
|
||||
### SSOT
|
||||
|
||||
- Canonical:
|
||||
- `wiki/projects/<canonical-project-doc>`
|
||||
- Raw / branch notes:
|
||||
- `raw/branch-notes/<optional-branch-note>`
|
||||
|
||||
### 이 문서의 한계
|
||||
|
||||
- 이 문서는 SSOT가 아니다.
|
||||
- 구현 상태는 작성일 기준이다.
|
||||
- 세부 결정은 각 branch-note와 canonical 문서를 확인해야 한다.
|
||||
|
||||
---
|
||||
|
||||
## 1. 이 프로젝트는 무엇인가
|
||||
|
||||
### 한 문장 정의
|
||||
|
||||
> ca-tmpl은 `<새 백엔드 프로젝트를 시작할 때 반복적으로 필요한 운영 계약>`을 Clean Architecture 구조로 미리 고정해두는 skeleton이다.
|
||||
|
||||
### 하지 않는 것
|
||||
|
||||
- 특정 비즈니스 도메인을 제공하지 않는다.
|
||||
- 특정 adapter를 무겁게 기본 탑재하지 않는다.
|
||||
- raw branch-note에서 곧바로 blog/interview/portfolio로 파생하지 않는다.
|
||||
- 운영 실패, 로그, trace, API envelope, module boundary를 프로젝트마다 임의로 재결정하지 않는다.
|
||||
|
||||
### 제공하는 것
|
||||
|
||||
- module/package boundary
|
||||
- structured API response
|
||||
- operational error category
|
||||
- exception ownership
|
||||
- boundary validation / mapper contract
|
||||
- structured logging / tracing
|
||||
- env-driven runtime configuration
|
||||
- repository capability contract
|
||||
- adapter failure mapping
|
||||
- architecture test / contract test
|
||||
- sample domain fixture
|
||||
|
||||
### 왜 skeleton인가
|
||||
|
||||
`<도메인 기능 자체보다, 도메인을 얹었을 때 동일한 운영 계약과 아키텍처 경계를 유지하는 구조가 목적이기 때문이다.>`
|
||||
|
||||
---
|
||||
|
||||
## 2. 이 프로젝트가 해결하는 핵심 문제
|
||||
|
||||
### 문제 1. 프로젝트마다 실패 처리 방식이 달라지는 문제
|
||||
|
||||
- 어떤 프로젝트는 validation 실패를 400으로 반환한다.
|
||||
- 어떤 프로젝트는 같은 실패를 500으로 반환한다.
|
||||
- 어떤 프로젝트는 raw exception message를 client에게 노출한다.
|
||||
- 결과적으로 운영, 디버깅, API contract가 흔들린다.
|
||||
|
||||
### 문제 2. Clean Architecture 경계가 문서에만 남고 코드에서 무너지는 문제
|
||||
|
||||
- controller가 JPA entity를 직접 반환한다.
|
||||
- application layer가 Spring/JPA 구현체를 직접 import한다.
|
||||
- domain이 framework annotation을 알게 된다.
|
||||
- adapter끼리 직접 참조하면서 순환 결합이 생긴다.
|
||||
|
||||
### 문제 3. 관측성 정보가 일관되지 않은 문제
|
||||
|
||||
- requestId가 없는 로그가 남는다.
|
||||
- traceId와 correlationId 의미가 branch마다 다르다.
|
||||
- 장애 발생 시 어떤 요청에서 어떤 dependency 실패가 났는지 추적하기 어렵다.
|
||||
|
||||
### 문제 4. 테스트가 구현 세부만 검증하고 계약 위반을 잡지 못하는 문제
|
||||
|
||||
- unit test는 통과하지만 architecture boundary가 깨진다.
|
||||
- API response schema drift가 생겨도 release 전에 감지하지 못한다.
|
||||
- contract violation이 warning-only로 남는다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 전체 구조 요약
|
||||
|
||||
| 영역 | 역할 | 왜 필요한가 |
|
||||
| ------------------- | --------------------------------------------------- | --------------------------------------------------- |
|
||||
| domain-core | 순수 domain model, value object, domain rule | framework와 adapter로부터 business invariant를 보호 |
|
||||
| application-core | use case, command/query, port, policy validation | business flow와 외부 구현체 사이의 경계 유지 |
|
||||
| adapter-web | HTTP DTO, controller, validation, response mapper | 외부 HTTP 요청을 application contract로 변환 |
|
||||
| adapter-persistence | JPA/RDBMS 저장소 구현, entity, mapper | persistence 기술을 application port 뒤로 숨김 |
|
||||
| adapter-outbound | HTTP client, messaging, cache, notification adapter | 외부 dependency 세부 구현을 격리 |
|
||||
| shared-contract | envelope, error code, header/log/metric registry | skeleton-wide operational contract 공유 |
|
||||
| app-bootstrap | Spring Boot entrypoint, DI wiring, runtime config | composition root로 runtime module을 조립 |
|
||||
| sample-portfolio | skeleton contract 검증용 fixture | 실제 domain 없이 contract를 검증 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 핵심 흐름
|
||||
|
||||
### 4.1 Request 처리 흐름
|
||||
|
||||
```text
|
||||
HTTP Request
|
||||
→ adapter-web Request DTO
|
||||
→ request validation
|
||||
→ mapper
|
||||
→ application Command/Query
|
||||
→ use case
|
||||
→ domain model / domain rule
|
||||
→ output port
|
||||
→ adapter-persistence or adapter-outbound
|
||||
→ response mapper
|
||||
→ structured envelope
|
||||
```
|
||||
|
||||
### 4.2 Error 처리 흐름
|
||||
|
||||
```text
|
||||
Exception or failure
|
||||
→ layer-specific exception ownership
|
||||
→ operational error mapping
|
||||
→ error.code / error.category / retryable
|
||||
→ structured envelope
|
||||
→ structured log
|
||||
→ trace correlation
|
||||
```
|
||||
|
||||
### 4.3 Domain Feature 추가 흐름
|
||||
|
||||
```text
|
||||
presentation request/response DTO
|
||||
→ request mapper
|
||||
→ application command/query
|
||||
→ use case
|
||||
→ input port / output port
|
||||
→ domain model / value object / domain rule
|
||||
→ persistence model / repository adapter
|
||||
→ response mapper
|
||||
→ contract test
|
||||
→ architecture rule
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 주요 계약 묶음
|
||||
|
||||
| 계약 영역 | 담당 branch | 설명 | 현재 상태 |
|
||||
| ---------------------------- | -------------------------- | ---------------------------------------------- | ---------- |
|
||||
| error / observability | `raw/branch-notes/<...>` | error category, envelope, log/trace 기반 | `<status>` |
|
||||
| API contract | `raw/branch-notes/<...>` | versioning, pagination, headers, idempotency | `<status>` |
|
||||
| boundary validation / mapper | `raw/branch-notes/<...>` | DTO → command/query → domain 변환 경계 | `<status>` |
|
||||
| module/package blueprint | `raw/branch-notes/<...>` | Gradle multi-module, package responsibility | `<status>` |
|
||||
| transaction / concurrency | `raw/branch-notes/<...>` | transaction boundary, lock, retry, idempotency | `<status>` |
|
||||
| sample fixture | `raw/branch-notes/<...>` | skeleton contract 검증용 sample domain | `<status>` |
|
||||
| architecture enforcement | `raw/branch-notes/<...>` | ArchUnit / Gradle dependency guardrail | `<status>` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 현재 구현 상태
|
||||
|
||||
| 영역 | 상태 | 근거 | 남은 위험 |
|
||||
| -------- | ------------------------------------------------------------------------ | -------------------- | --------- |
|
||||
| `<영역>` | `<decision-only / documented-only / local-verified / pending / unknown>` | `<문서/코드/테스트>` | `<위험>` |
|
||||
|
||||
### 상태 값 정의
|
||||
|
||||
| 상태 | 의미 |
|
||||
| --------------- | ----------------------------------- |
|
||||
| decision-only | 결정은 있으나 구현/검증은 아직 없음 |
|
||||
| documented-only | 문서상 계약만 있음 |
|
||||
| local-verified | 로컬 코드/테스트로 검증됨 |
|
||||
| pending | 아직 착수 전 또는 잔여 작업 존재 |
|
||||
| unknown | 근거 부족으로 판단 불가 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 큰 그림에서 가장 중요한 설계 판단
|
||||
|
||||
### 판단 1. `<판단 이름>`
|
||||
|
||||
- 결정:
|
||||
- 이유:
|
||||
- 대안:
|
||||
- 선택하지 않은 이유:
|
||||
- 근거:
|
||||
- 남은 리스크:
|
||||
|
||||
### 판단 2. `<판단 이름>`
|
||||
|
||||
- 결정:
|
||||
- 이유:
|
||||
- 대안:
|
||||
- 선택하지 않은 이유:
|
||||
- 근거:
|
||||
- 남은 리스크:
|
||||
|
||||
---
|
||||
|
||||
## 8. 내가 설명할 수 있어야 하는 문장
|
||||
|
||||
### 30초 설명
|
||||
|
||||
`<ca-tmpl을 30초 안에 설명하는 문장>`
|
||||
|
||||
### 2분 설명
|
||||
|
||||
`<면접/리뷰/동료 설명에서 말할 수 있는 설명>`
|
||||
|
||||
### 깊게 질문받았을 때
|
||||
|
||||
**Q. 왜 도메인 기능을 제거했나?**
|
||||
A. `<답변>`
|
||||
|
||||
**Q. 왜 sample-portfolio가 필요한가?**
|
||||
A. `<답변>`
|
||||
|
||||
**Q. 왜 shared-contract가 필요한가?**
|
||||
A. `<답변>`
|
||||
|
||||
**Q. 왜 architecture test가 필요한가?**
|
||||
A. `<답변>`
|
||||
|
||||
---
|
||||
|
||||
## 9. 아직 이해가 부족한 부분
|
||||
|
||||
| 질문 | 왜 헷갈리는가 | 확인할 문서 | 확인할 코드 |
|
||||
| ---- | ------------- | ----------- | ----------- |
|
||||
| | | | |
|
||||
|
||||
---
|
||||
|
||||
## 10. 다음에 읽을 문서
|
||||
|
||||
- `wiki/reports/ca-tmpl/01-module-boundary-report`
|
||||
- `wiki/reports/ca-tmpl/02-operational-error-observability-report`
|
||||
- `wiki/reports/ca-tmpl/03-api-contract-report`
|
||||
- `wiki/reports/ca-tmpl/04-boundary-validation-mapper-report`
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/project-template.md
|
||||
@@ -0,0 +1,468 @@
|
||||
---
|
||||
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 산출물 후보>
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/raw-source-template.md
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title:
|
||||
source_type: official-doc | company-tech-blog | personal-blog
|
||||
url:
|
||||
archive_url:
|
||||
related_branches: []
|
||||
related_projects: []
|
||||
tags: []
|
||||
created: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `raw/` — 외부 자료(공식 문서 / 대기업 기술 블로그)의 **원문 발췌·출처 기록**.
|
||||
> 본 템플릿은 `raw/official-docs/` 와 `raw/company-tech-blogs/` 두 폴더가 공유.
|
||||
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.
|
||||
|
||||
## source_type 허용값
|
||||
|
||||
frontmatter `source_type:` 에는 다음 중 하나만 사용:
|
||||
|
||||
- `official-doc` — 공식 레퍼런스 / 표준 / 사양 (예: Spring Boot reference, RFC, AWS docs)
|
||||
- `company-tech-blog` — 대기업 엔지니어링 블로그 / 컨퍼런스 발표 글 (예: Stripe, Netflix, Toss, 카카오)
|
||||
|
||||
해당하지 않는 자료는 별도 카테고리 검토 (강의는 `raw/lectures/`, 채용공고는 `raw/job-postings/`, 일반 블로그 글감은 `raw/blog-topics/`).
|
||||
|
||||
## 활용 branch (필수, 최소 1개+)
|
||||
|
||||
> 이 자료는 **혼자 존재하지 않는다.** 어느 branch(또는 project)의 구현 결정의 **근거**로서 보관됨. 어느 작업의 어떤 결정을 정당화하는지 명시. 같은 자료가 여러 branch에서 인용될 수 있으면 frontmatter `related_branches` 에 모두 나열 + 아래 표에 추가.
|
||||
|
||||
| Branch | 이 자료가 정당화하는 결정 |
|
||||
|---|---|
|
||||
| `[[raw/branch-notes/{{branch-name-1}}]]` | <한 줄: 어떤 결정의 근거인지> |
|
||||
| `[[raw/branch-notes/{{branch-name-2}}]]` | <한 줄> |
|
||||
|
||||
특정 branch 없이 foundational 조사로 수집한 경우:
|
||||
|
||||
- `[[raw/project-notes/{{project-name}}]]` — <어떤 프로젝트의 초기 조사인지>
|
||||
|
||||
## 출처
|
||||
|
||||
- 원본 URL:
|
||||
- 아카이브 URL:
|
||||
- 저자 / 조직:
|
||||
- 발행일:
|
||||
- 마지막 확인일: YYYY-MM-DD
|
||||
|
||||
## 왜 저장했는지
|
||||
|
||||
> 이 자료를 보관하는 이유 1~2줄. 어떤 개념·문제·결정과 연결되는가. Parent 표의 "정당화하는 결정"과 일관되어야 함.
|
||||
|
||||
<이유>
|
||||
|
||||
## 핵심 인용
|
||||
|
||||
> 원문 그대로. 따옴표·줄바꿈 보존. 페이지·섹션 번호 있으면 같이.
|
||||
|
||||
> [§<section>] "원문 발췌 1."
|
||||
|
||||
> [§<section>] "원문 발췌 2."
|
||||
|
||||
> [§<section>] "원문 발췌 3."
|
||||
|
||||
## 추출된 주장
|
||||
|
||||
> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.
|
||||
> `Claim ID` 는 같은 raw 문서 안에서 안정적으로 유지한다. 예: `C1`, `C2`, `C3`.
|
||||
|
||||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||||
|---|---|---|---|---|---|
|
||||
| C1 | <원문이 직접 지지하는 주장> | [§<section>] "<짧은 원문 인용>" | `official-strong` | <적용 가능한 조건> | <이 claim 으로 증명할 수 없는 것> |
|
||||
| C2 | <주장> | [§<section>] "<짧은 원문 인용>" | `case-study` | <조건> | <한계> |
|
||||
|
||||
### Strength 허용값
|
||||
|
||||
- `official-standard` — RFC, 표준 사양, 언어/프로토콜 표준
|
||||
- `official-vendor-doc` — Spring, Keycloak, AWS, Google 등 공식 벤더 문서
|
||||
- `official-reference` — 공식 reference/API 문서
|
||||
- `company-case-study` — 대기업/실무 기술 블로그의 특정 사례
|
||||
- `engineering-blog` — 개인/팀 블로그의 엔지니어링 해설
|
||||
- `tutorial` — 튜토리얼/가이드. 일반화 금지
|
||||
- `needs-confirmation` — 원문만으로는 적용 판단 불가
|
||||
|
||||
## 적용 경계
|
||||
|
||||
- 이 자료가 직접 증명하는 것:
|
||||
- `C1`: <직접 증명 범위>
|
||||
- 이 자료가 증명하지 않는 것:
|
||||
- <예: 특정 설정이 모든 런타임에서 기본 활성화된다는 뜻은 아님>
|
||||
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
||||
- <예: ca-tmpl 의 실제 Spring Security 설정에서 동작 검증 필요>
|
||||
|
||||
|
||||
## 메모
|
||||
|
||||
> 나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것 (그것은 wiki/concepts의 source-summary 또는 wiki/projects 본문에서만 작성).
|
||||
|
||||
- 인용 1 해석 후보 (미검증):
|
||||
- 추가로 봐야 할 동일 출처 페이지:
|
||||
|
||||
## 관련
|
||||
|
||||
> 같은 주제의 다른 raw 자료, 또는 이 자료를 인용한 wiki 문서.
|
||||
|
||||
- 같은 주제 다른 official-doc / company-tech-blog: `[[raw/<...>]]`
|
||||
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/<...>]]` (생성 시)
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/source-summary-template.md
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title:
|
||||
source_type: source-summary
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: []
|
||||
related_projects: []
|
||||
last_reviewed:
|
||||
url:
|
||||
archive_url:
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/concepts/` — 외부 자료의 **검증된 요약 문서**. 원문 발췌와 출처 기록 자체는 `raw-source-template`을 사용해 `raw/`에 보관하고, 본 문서는 그 raw를 참조해 작성합니다.
|
||||
|
||||
## 출처
|
||||
|
||||
- 원본 URL:
|
||||
- 아카이브:
|
||||
- 저자/조직:
|
||||
- 발행일:
|
||||
|
||||
## 핵심 인용 (3–5문장)
|
||||
|
||||
> 원문 발췌 1.
|
||||
|
||||
> 원문 발췌 2.
|
||||
|
||||
## 요약
|
||||
|
||||
자료의 핵심 주장 2–4줄.
|
||||
|
||||
## 내 해석
|
||||
|
||||
원문이 말한 것과 내가 추론한 것을 **분리**해서 작성.
|
||||
|
||||
- **원문이 말한 것**:
|
||||
- **내 해석/추론**:
|
||||
|
||||
## Claim Map
|
||||
|
||||
> raw source 의 `Claims Extracted` 를 wiki 요약으로 승격할 때, 원문 claim 과 내 해석을 분리해 보존한다.
|
||||
|
||||
| Claim ID | Source claim | Wiki interpretation | Confidence | Linked decisions |
|
||||
|---|---|---|---|---|
|
||||
| `raw/<category>/<slug>.md#C1` | <원문 claim 요약> | <내 해석> | `high` | `raw/branch-notes/<branch>.md#D1` |
|
||||
| `raw/<category>/<slug>.md#C2` | <원문 claim 요약> | <내 해석> | `medium` | <없으면 N/A> |
|
||||
|
||||
## 적용 경계
|
||||
|
||||
- 이 자료를 근거로 말할 수 있는 것:
|
||||
- 이 자료만으로 말하면 안 되는 것:
|
||||
- 내 프로젝트에서 추가 검증이 필요한 것:
|
||||
|
||||
|
||||
## 평가
|
||||
|
||||
- 이 자료가 공식 기준인가, 사례인가? (`source_type` 따라 다름)
|
||||
- 어떤 한계가 있는가?
|
||||
|
||||
## 관련 개념
|
||||
|
||||
- `[[{{related-concept}}]]`
|
||||
@@ -1 +0,0 @@
|
||||
../vault/00-system/templates/wiki-project-template.md
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title:
|
||||
source_type: project
|
||||
status: draft
|
||||
confidence: unknown
|
||||
tags: []
|
||||
related_projects: []
|
||||
last_reviewed:
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
> Layer: `wiki/projects/` — canonical 실무 적용 문서(내 프로젝트 사실). 일반 개념은 `wiki/concepts/`, raw 프로젝트 hub는 `raw/project-notes/`(`project-template.md`) 사용.
|
||||
> 본 문서는 **하나의 토픽/결정 영역** 슬라이스다. 프로젝트 전체 hub(아키텍처·시퀀스·Cluster)는 `wiki/projects/<project>.md` named-hub(MOC)와 그 SSOT인 `raw/project-notes/` 가 담당한다.
|
||||
> 증거 등급(`actually-implemented`/`locally-verified`/`prod-verified`/`documented-only`/`planned`)을 섹션별로 분리해 외부 공개 가능 범위를 명확히 한다 (CLAUDE.md §6/§15).
|
||||
|
||||
## 프로젝트 컨텍스트
|
||||
|
||||
> 이 슬라이스가 다루는 결정/토픽의 배경. 문제 배경 + 검토한 선택지 + 결정 이유를 여기에 접어 서술(별도 필수 섹션 아님). 외부인이 "무엇을 왜 이렇게 했는가"를 1분에 이해할 수 있어야 함.
|
||||
|
||||
## 실제 구현 내용 (`actually-implemented`)
|
||||
|
||||
> 코드에 실제 존재하는 것만. 파일·클래스·task 단위로 구체적으로. 면접에서 "구현했다"고 말해도 되는 부분. 가능하면 ground-truth(레포 경로/커밋) 대조 근거를 함께.
|
||||
|
||||
## 로컬/dev 검증 (`locally-verified`)
|
||||
|
||||
> 로컬 또는 dev 환경에서 동작 확인한 부분. 어떻게 검증했는지(테스트 명령/로그/측정값)를 명시.
|
||||
|
||||
## 운영 검증 (`prod-verified`)
|
||||
|
||||
> 운영(prod) 환경에서 검증된 부분. 릴리즈 노트/운영 로그/모니터링/인시던트 근거. 없으면 "없음"이라고 명시.
|
||||
|
||||
## 문서/계획만 존재 (`documented-only`
|
||||
|
||||
> 설계/문서에만 있고 아직 구현 안 된 것. 면접·외부 공개에서 "구현했다"고 말하면 안 되는 부분. 후속 branch로 위임되는 항목은 링크.
|
||||
|
||||
## 면접에서 말할 수 있는 범위
|
||||
|
||||
> 자신 있게 / 적당히 / 답하면 안 되는 범위로 구분. 증거 등급과 일치해야 함.
|
||||
|
||||
## 과장 금지 지점
|
||||
|
||||
> 외부 설명 시 사실보다 부풀려지기 쉬운 표현. 자기 검열용.
|
||||
|
||||
## 관련 개념
|
||||
|
||||
> `[[wiki/concepts/...]]` 양방향 링크. 일반 개념과 본 프로젝트 사실을 연결.
|
||||
|
||||
## 근거 자료
|
||||
|
||||
> 근거. 추출 출처 branch-note/raw, 그리고 ground-truth 레포. `[[raw/branch-notes/...]]`, `[[raw/project-notes/...]]` 등.
|
||||
Reference in New Issue
Block a user