Files

T

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

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

21 KiB

Raw Blame History

title, source_type, status, confidence, tags, related_projects, last_reviewed, diagrams, architecture_review, status_label, project_revision

title

source_type

status

confidence

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 파일을 생성함.

실제 사용 예 (drawio 파일 생성 후 placeholder 부분을 실제 값으로 치환):
![[raw/diagrams/my-project/architecture-overview-2026-05-25.drawio.svg]]

다이어그램 작성 요약 (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 박지 말 것.

3.2 컴포넌트 책임 분담

다이어그램의 각 컴포넌트가 정확히 무엇을 책임지는지 표로.

컴포넌트	역할	기술 스택	의존하는 외부
`<name>`	<한 줄 책임>		<외부 시스템>
`<name>`	<한 줄 책임>		<외부 시스템>

3.3 외부 의존성

외부 시스템	용도	통신 방식	장애 시 영향 (degrade / fail / fallback)
`<name>`	<용도>	<REST/gRPC/...>	<영향>

3.4 배포 다이어그램

운영 환경 토폴로지가 비자명하면 별도 draw.io.

실제 사용 예 (placeholder 치환 후 사용):
![[raw/diagrams/my-project/architecture-deployment-2026-05-25.drawio.svg]]

4. 핵심 시퀀스

필수 섹션. 최소 1개의 주요 user flow 를 Mermaid sequence diagram 으로. happy path + 주요 error path 함께.

4.1 <Flow name 1> (예: 사용자 로그인)

시나리오: <어떤 상황의 흐름인지 1줄>

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 다이어그램으로. 그 미만이면 글로만.

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>	<이유>	<단점>
...

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/<...>]]`

6.2 Artifact Registry

Artifact ID	Revision	Name	Schema Owner	Producer	Consumers	Schema Ref	Status

6.3 Contract/Gate Registry

Contract ID	Concern Key	Revision	Type	Owner	Trigger	Required Effect	Enforcement	Status

6.4 Delegation Registry

Delegation ID	Concern Key	Revision	Delegator	Delegate	Scope	Status

6.5 Flow/Stage Registry

Stage ID	Order	Owner	Input	Action	Output	Invariants	Revision

7. 비기능 요구사항

측정 가능한 비기능 목표. 없으면 명시적으로 "해당 없음".

성능: <RPS, P99 latency 목표>
가용성: <SLO 99.9% 등>
확장성: <단일 인스턴스 / 다중 인스턴스 / HPA 정책>
보안: <인증·인가 방식, 데이터 보호 정책, 컴플라이언스>
운영 / Observability: <로깅·메트릭·트레이싱 정책>
재해 복구 / DR: <RTO / RPO>
컴플라이언스: <GDPR / PCI-DSS / 기타 / 해당 없음>

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 산출물 후보>

21 KiB Raw Blame History

{{title}}