Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 KiB

Raw Blame History

title, source_type, status, branch, parent_branch, related_projects, tags, created, target_merge, status_label, archive_reason

title

source_type

status

branch

parent_branch

related_projects

branch: feature-template-instantiation-contract

Layer: raw/branch-notes/ — 단일 브랜치의 TODO·결정·진행 기록. 머지/종료 후 verified 결과는 /ingest로 wiki/projects/에 추출. 원본은 raw에 영구 보관. status_label: in-progress | review | merged | abandoned 계층 표기: "root branch" 라는 별도 개념은 없음. project 의 직접 자식 branch 는 parent_branch: 를 비워두고 related_projects 만 채움. 다른 branch 의 자식이면 parent_branch: <부모 branch 이름> 명시 + ## Parent 섹션의 부모 wikilink 필수.

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

목표 / WHY

이 브랜치에서 해결하려는 문제. 관련 이슈 / PR 링크.

이슈:
PR:

범위

In scope

항목 1
항목 2

Out of scope

의도적으로 제외한 것. 면접 등에서 "이건 범위에 없었습니다"라고 답할 근거.

항목 1

Sources / 근거 (필수, 최소 1개+)

이 branch의 구현·설계 결정의 근거가 되는 외부 자료. 공식 문서·대기업 기술 블로그·강의 등 raw 자료를 인용. 같은 자료가 여러 결정의 근거면 결정 표시와 함께 여러 번 등장 가능.

Source	정당화하는 결정
`[[raw/official-docs/<...>]]`	<어떤 결정의 근거인지 한 줄>
`[[raw/company-tech-blogs/<...>]]`	<한 줄>
`[[raw/lectures/<...>]]`	<한 줄>

근거 자료가 raw에 아직 없다면 먼저 raw-source-template 또는 lecture-note-template 으로 raw에 등록한 뒤 여기서 링크.

TODO

작업 1 — 등급: planned
작업 2 — 등급: planned
작업 3 — 등급: actually-implemented

진행 중 메모

작업하며 떠오른 메모. 자유 형식.

결정 사항 / Decisions

추후 면접/회고에서 "왜 이렇게 했나" 답할 근거. 대안과 함께 기록. 각 결정의 근거는 위 Sources 또는 새로 추가된 raw 자료를 가리킬 것.

YYYY-MM-DD: <결정 내용> / 이유: <왜> / 검토한 대안: <대안> / 근거: [[raw/official-docs/<...>]]

Decision Evidence Map / 결정-근거 매핑

각 결정이 어떤 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>

구현 가이드 / Implementation Specification

결정 (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 (필수 준수):

R1. Reference 필수 — 각 sub-section / row / cell 은 본 branch 의 Decision ID (예: D1, D2) + 그 결정의 Supporting Claim ID (예: RAW-SLUG-C1) 를 reference. 근거 없는 결정 금지 — 모든 구현 detail 은 결정 + 근거의 도출 이어야 함.

R2. UNSUPPORTED_IMPL_DECISION 명시 — 근거 raw 가 원칙 만 권고하고 detail (메커니즘 선택 / 클래스/rule 명명 / glob 패턴 / algorithm / factory API 모양 등) 은 권고하지 않는 cell 은 UNSUPPORTED_IMPL_DECISION 라벨 + 사용자 trade-off 근거 한 줄. 이게 근거 있는 결정 vs 사용자 임의 trade-off 의 경계.

R3. OUT_OF_BRANCH_SCOPE 정제 — 본 branch 결정 범위 밖 cell 은 §구현 가이드에 남기지 않음. 별도 branch 또는 canonical SSOT 로 이관 (이관 history 는 별도 § "Audit & Findings" 등에 보존). 도메인 특화 detail (ca-tmpl skeleton 범위 밖) 도 동일하게 정제.

각 sub-section 의 권장 헤더 패턴:
### 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. ... (필요 시 추가)

엣지·실패·의존 / Edge · Failure · Dependency

R4(깊이 게이트) 캡처용. 정상 경로 외에 구현 중 부딪힐 실패/엣지/다른 계약 의존을 미리 열거. 없으면 "해당 없음" 명시(공란 금지).

실패·엣지 경로: <입력 경계 / 타임아웃 / 부분 실패 / 동시성 등 — 각 경로의 기대 동작>
다른 계약 의존: [[raw/branch-notes/<other-branch>]] 의 D<n> 에 의존 — <무엇을 consume 하는지, 그 계약이 바뀌면 본 브랜치 영향>

검증해야 할 주장 / Claims To Verify

공식 문서나 사례는 근거지만, 내 프로젝트에서의 동작을 자동으로 보장하지 않는다. 구현 전/중/후에 실제로 검증해야 하는 주장을 분리한다.

Claim	Why uncertain	How to verify	Status
<검증할 주장>	<불확실한 이유>	<테스트/grep/실행 검증 방법>	`needs-confirmation`
<검증할 주장>	<이유>	<방법>	`planned`

Coverage / 관심사 커버리지 (coverage-auditor 자동 생성 — 있을 때)

/coverage 가 채우는 생성물 — 손으로 유지하지 않는다. governing 문서(frontmatter governing_docs)가 요구하는 관심사를 이 브랜치가 빠짐없이 덮는지의 결과. 기준: rules/coverage-gate.md. 상태: covered-here(이 브랜치 결정) / delegated(다른 owner 브랜치) / missing(아무도 안 맡음 → Blocking).

관심사	상태	owner	심각도	근거
<governing doc 의 관심사>	covered-here	—	—	D
<관심사>	delegated	feature-	OK/Should-fix	§Audit 위임 링크
<관심사>	missing	(없음)	🔴 Blocking	governing doc § 요구, 결정 없음

마주친 문제

짧은 메모만. 깊이 있는 트러블슈팅은 raw/errors/ 로 분리하고 아래 Cluster에 연결.

이슈 1
- 원인:
- 시도:
- 해결: (또는 미해결이면 needs-confirmation)
- 별도 에러 노트로 분리됨: [[raw/errors/<...>]] (생성 시)

Cluster / 묶음 (이 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>]] — <한 줄 요약>

Errors (이 branch 작업 중 발생)

[[raw/errors/<...>]] — <한 줄 요약>

Interview prep (이 작업에서 나올 수 있는 면접 질문)

[[raw/interviews/<...>]] — <한 줄 요약>

Lectures (이 작업을 위해 학습한 강의)

[[raw/lectures/<...>]] — <한 줄 요약>

Blog topics / job-posting tie-ins (이 작업에서 파생된 글감)

[[raw/blog-topics/<...>]] — <채용공고가 아닌 작업·학습·트러블슈팅 기반 글감 후보>
[[raw/job-postings/<...>]] — <채용공고에서 파생된 글감 후보>
derived blog: 생성 전. 생성 시 wiki/blog/<slug>-YYYY-MM-DD.md 후보

완료 후 정리 / Closure

머지/종료 시점에 채움. /ingest가 이 섹션을 기준으로 wiki/projects/에 추출.

PR 링크:
리뷰 메모:
머지 결과 / 배포 환경: (로컬/dev/staging/prod 어디까지 검증됐는지)
wiki 추출 대상 (verified만, wiki/projects/로만 추출):
- actually-implemented 항목:
- locally-verified 항목:
- prod-verified 항목:
추출하지 않을 항목 (planned / documented-only / abandoned):

10 KiB Raw Blame History