---
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 -->