Files

T

DongHyeonka 6c53ded9cb init: llm-wiki-haness 하네스 설계

2026-07-24 14:21:35 +09:00

18 KiB

Raw Blame History

title, source_type, status, id, kind, project, work_item, inherits, refines, overrides, depends_on, imports, delegates, accepts_delegations, contract_packet, branch, parent_branch, related_projects, tags, created, target_merge, status_label

title

source_type

status

kind

project

work_item

inherits

refines

overrides

depends_on

imports

delegates

accepts_delegations

contract_packet

branch

parent_branch

related_projects

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 필수.

부모 (필수)

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

브랜치 계약 패킷

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
완료 조건: <실행계획의 완료 조건을 그대로 연결>

상속한 프로젝트 결정

Decision Ref	Project Summary	Branch Application	Source
`DEC-<PROJECT>-<DOMAIN>-001@1`	<project registry 의 1줄 요약>	<이 branch 가 consume 하는 경계>	`[[raw/project-notes/<project>]]`

브랜치 지역 결정

상세 근거와 선택 조건은 아래 ## 결정-근거 매핑의 동일 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`

선언한 예외

inherited project decision 과 다른 동작이 필요할 때만 작성한다. frontmatter overrides 와 동일한 pinned ref 를 사용하며 이유·승인·상태를 남긴다.

Override ID	Overrides	Reason	Approval	Status
O1	`DEC-<PROJECT>-<DOMAIN>-001@1`	<project 기본값을 적용할 수 없는 조건>	`needs-approval`	`proposed`

가져온 artifact 계약

Artifact Ref	Owner	Producer	Schema Ref

가져온 프로젝트 계약

Ref	Owner	요약	Branch 적용

수신한 위임

Delegation Ref	From	Concern	Status

가져온 흐름 단계

Stage Ref	Order	Owner	Input	Action	Output

목표

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

이슈:
PR:

범위

포함 범위

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

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

진행 중 메모

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

결정 사항

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

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

결정-근거 매핑

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

구현 가이드

결정 (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. ... (필요 시 추가)

엣지·실패·의존

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

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

검증해야 할 주장

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

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
<관심사>	delegated	feature-	OK/Should-fix	§Audit 위임 링크
<관심사>	missing	(없음)	🔴 Blocking	governing doc § 요구, 결정 없음

마주친 문제

짧은 메모만. 깊이 있는 트러블슈팅은 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 후보

완료 후 정리

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

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

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

부모 (필수)

브랜치 계약 패킷

생성 시 프로젝트 개정: {{project_revision}}
패킷 스키마: contract_packet: 1
완료 조건: {{completion}}

상속한 프로젝트 결정

Decision Ref	Project Summary	Branch Application	Source
{{inherited_rows}}

브랜치 지역 결정

Decision ID	Decision	Relation	Supporting Claims	Status

선언한 예외

Override ID	Overrides	Reason	Approval	Status

가져온 artifact 계약

Artifact Ref	Owner	Producer	Schema Ref

가져온 프로젝트 계약

Ref	Owner	요약	Branch 적용

수신한 위임

Delegation Ref	From	Concern	Status

가져온 흐름 단계

Stage Ref	Order	Owner	Input	Action	Output

목표

{{work_item}}의 완료 조건을 구현한다: {{completion}}

범위

포함 범위

Work Item 완료 조건

제외 범위

project decision registry 변경

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

외부 근거 미등록. /branch-spec {{branch_slug}} 단계에서 source claim을 연결한다.

TODO

{{completion}} — 등급: planned

진행 중 메모

아직 없음.

결정 사항

project 결정 외 branch-local 결정은 아직 없음.

결정-근거 매핑

Decision ID	Decision	선택 조건 (언제 이 결정 / 언제 대안)	Supporting Claims	Evidence Strength	Open Risk

구현 가이드

/branch-spec 단계에서 source claim 기반으로 작성한다.

엣지·실패·의존

실패·엣지 경로: /branch-spec 단계에서 구체화한다.
다른 계약 의존: {{dependency_display}}

검증해야 할 주장

Claim	Why uncertain	How to verify	Status

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

/coverage 실행 전.

마주친 문제

아직 없음.

묶음 (이 branch에서 파생된 자료)

완료 후 정리

PR 링크:
리뷰 메모:

18 KiB Raw Blame History

branch: {{branch-name}}

부모 (필수)

브랜치 계약 패킷

상속한 프로젝트 결정

브랜치 지역 결정

선언한 예외

가져온 artifact 계약

가져온 프로젝트 계약

수신한 위임

가져온 흐름 단계

목표

범위

포함 범위

제외 범위

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

TODO

진행 중 메모

결정 사항

결정-근거 매핑

구현 가이드

1. <sub-section 제목 — 본 branch 의 결정 영역 안에서만>

2. ... (필요 시 추가)

엣지·실패·의존

검증해야 할 주장

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

마주친 문제

묶음 (이 branch에서 파생된 자료)

Sub-branches (세부 작업)

오류 기록 (이 branch 작업 중 발생)

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

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

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

관련 일일 노트

완료 후 정리

branch: {{branch_slug}}

부모 (필수)

브랜치 계약 패킷

상속한 프로젝트 결정

브랜치 지역 결정

선언한 예외

가져온 artifact 계약

가져온 프로젝트 계약

수신한 위임

가져온 흐름 단계

목표

범위

포함 범위

제외 범위

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

TODO

진행 중 메모

결정 사항

결정-근거 매핑

구현 가이드

엣지·실패·의존

검증해야 할 주장

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

마주친 문제

묶음 (이 branch에서 파생된 자료)

관련 일일 노트

완료 후 정리

18 KiB

Raw Blame History