Files
tech-log-frontend/docs/superpowers/specs/2026-08-27-concept-record-kind-design.md
T
DongHyeonkaandClaude Opus 5 05df030530 docs: 개념(CONCEPT) 문서 종류 설계
Reference 는 판단 기준을 빨리 찾는 글이고, Kubernetes 내부 동작처럼 처음부터 풀어 읽어야
하는 글은 그 틀에 들어가지 않는다. 종류를 하나 더하고 Reference 구조는 그대로 둔다.

개념 글은 프로젝트 없이 게시될 수 있는 유일한 종류이므로 주제를 게시 조건으로 둔다 —
집 없는 글이 생기지 않게.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
2026-08-28 19:19:02 +09:00

9.0 KiB

개념(CONCEPT) 문서 종류 추가

작성일 2026-08-27 · 대상 저장소 tech-log-design-package · tech-log-backend · tech-log-frontend

왜

Reference 는 "이렇게 판단한다"를 빨리 찾는 글이다. 규칙·적용 범위·예외·예시라는 칸을 갖고 있고, 읽는 사람이 대상을 이미 안다고 가정한다.

Kubernetes 의 내부 동작과 아키텍처처럼 처음부터 풀어 읽어야 하는 글은 그 틀에 들어가지 않는다. 규칙이 아니라 설명이고, 결론이 아니라 경로다. Reference 에 억지로 넣으면 두 글이 서로를 망친다 — 기준을 찾으러 온 사람은 배경 설명을 지나야 하고, 개념을 배우러 온 사람은 규칙 목록에서 시작한다.

그래서 종류를 하나 더한다. Reference 의 구조는 그대로 둔다.

무엇이 아닌가

  • Reference 를 바꾸지 않는다. 규칙·적용·예외·예시 구조는 그대로다.
  • 시리즈·묶음 컨테이너를 만들지 않는다. 순서와 이유는 이미 관계(relations)가 갖고 있다. 묶음을 따로 두면 "관계에도 있고 묶음에도 있는" 두 진실이 생긴다.
  • 주제 페이지를 만들지 않는다. 개념이 쌓이면 주제가 자연스러운 묶음이 되어 그 페이지를 만들 이유가 생기지만, 지금은 주제 1개에 개념 0개다. 쌓인 뒤에 별건으로 본다.
  • 마지막 검증일·신선도를 두지 않는다. 개념이 낡는 방식은 날짜가 아니라 버전이다.

문서의 모양

WorkingCopyInputBase 가 이미 주는 것을 그대로 쓰고 두 칸만 더한다.

base (모든 종류 공유)
  kind · title · slug · summary · topicId · projectId · relations

CONCEPT 이 더하는 것
  bodyMarkdown : 자유 마크다운. Case 와 같은 파서를 쓴다 —
                 `##` 소제목이 목차가 되고 `:::evidence key="…"` 로 도식을 끼운다
  basisVersion : "Kubernetes 1.31" 같은 한 줄. 비우면 화면에 그리지 않는다

bodyMarkdown 의 규칙은 Case 와 같다: 마크다운 원문만 저장하고 object storage URL 을 원문에 넣지 않는다. Asset 은 assetKey 로만 참조한다.

붙는 자리

붙는 곳 개념 글에게 규칙
주제 집. 여기서 서로를 찾는다 게시 시 필수 — 없으면 오류
프로젝트 선택. 그 프로젝트에서 썼다면 붙인다 없어도 됨(경고도 띄우지 않는다)
관계 읽는 순서와 이유 자유

주제를 오류로 두는 이유는 CONCEPT 이 프로젝트 없이 게시될 수 있는 유일한 종류이기 때문이다. 다른 종류는 프로젝트라도 있으니 집이 하나는 있지만, 개념 글은 주제까지 비우면 탐색 목록과 최근 기록에서만 보이다가 사실상 사라진다. PROJECT_DECISION 이 프로젝트를 요구하는 것과 같은 규칙을 주제 쪽으로 쓴 셈이다.

프로젝트가 없는 것은 결함이 아니라 이 종류의 정상 상태이므로, PROJECT_MISSING 경고를 CONCEPT 에는 띄우지 않는다.

여러 문서를 잇는 법

Kubernetes 스케줄링은 어떻게 결정되는가
  관계 1  → 컨트롤 플레인은 무엇을 하는가       "먼저 읽기"
  관계 2  → 네트워킹은 어떻게 연결되는가         "이어서"
  관계 3  → Forward-Auth 에서 Identity Header…  "이 개념을 쓴 기록"

RelationInput 은 { targetId, reason, order } 다. 순서가 있고 이유가 자유 문구이므로 개념끼리도, 개념 ↔ Case/Reference 로도 같은 방식으로 이어진다.

계약 변경

studio-v1.yaml (작성)

  • RecordKind enum 에 CONCEPT 추가
  • ConceptInput 신설 — WorkingCopyInputBase + { kind, bodyMarkdown, basisVersion }
  • ConceptWorkingCopy (응답형) 신설 — 같은 모양에 id · version · updatedAt
  • 작업본 union(WorkingCopyInput / WorkingCopy)에 분기 추가

public-v1.yaml (공개)

  • ConceptDetailResponse 신설
    • concept: { title, summary, basisVersion?, content, contentFormat, contentFormatVersion, bodyAssets, primaryTopic, primaryProject?, tags, publishedAt, updatedAt }
    • relations: { derivedConcepts[], relatedRecords[], primaryProject? }
  • KnowledgeListItem.type 에 CONCEPT 추가
  • LatestEntry.entryType 에 CONCEPT 추가
  • exploreKnowledge 의 type 질의 파라미터에 CONCEPT 추가
  • GET /concepts/{slug} 경로 추가

검색(SearchResultItem.contentType)은 자유 문자열이라 건드리지 않는다.

백엔드

마이그레이션 V11

concept_working_copy   -- working_copy_id, body_markdown, basis_version
concept_detail         -- publication_id, body_markdown, basis_version, content_format…

record_kind 를 제약으로 검사하는 자리에 'CONCEPT' 를 더한다 — working_copy, publication, public_resource_projection.

코드

파일 할 일
RecordKind enum 에 CONCEPT
PublicPaths CONCEPT → /concepts/{slug}
StudioDocumentValidator CONCEPT: topicId 없으면 error, bodyMarkdown 비면 error, PROJECT_MISSING 경고 제외
JdbcWorkingCopyRepositoryAdapter + ConceptWorkingCopyStore 작업본 읽기·쓰기
JdbcPublicationWriterAdapter concept_detail 기록 + projection upsert
JdbcPublicDocumentQueryAdapter /concepts/{slug} 상세 조회
PublicSql.LATEST_ENTRY_TYPES 'CONCEPT' 추가 (홈·주제가 함께 쓴다)
JdbcCatalogQueryAdapter RELATION/EVIDENCE 후보에 개념 포함
PublicRenderModelFactory 즉시 미리보기를 Case 와 같은 파서로
StudioRequestMapper / StudioResponseMapper CONCEPT 분기

공개 조회의 유형 필터

exploreKnowledge 는 CASE/REFERENCE 만 담고 있다. CONCEPT 을 더한다 — 지식 목록의 의미가 "기록과 기준"에서 "기록과 기준과 개념"으로 넓어진다.

프론트엔드

파일 할 일
계약 codegen generate:tech-log-contract 재실행
public-content-queries.ts RecordKind 에 CONCEPT, ConceptRecord 타입, LatestRecordEntry.entryType
concept-fields.tsx (신규) 편집기 — 본문 마크다운 + 기준 버전. Case 의 Asset Picker 재사용
document-editor.tsx CONCEPT 분기와 CONCEPT_FIELD_PATHS
public-record-renderer.tsx 개념 렌더 — 제목·요약·기준 버전·본문·목차·관계
concept-document-page.tsx (신규) 공개 상세
라우트 TECH_LOG_CONCEPT = /concepts/:slug, explore-kind-page 에 concepts
explore-filter-form.tsx 유형 선택지에 개념
public-document-header.tsx kindLabels 에 CONCEPT, 프로젝트 없을 때 그 마디와 dl 행을 뺀다
home-page.tsx latestTypeLabels 에 CONCEPT: "개념"
정적/모의 어댑터 픽스처에 개념 문서 추가

프로젝트 없는 문서 — 이번에 처음 생기는 상황

머리말은 지금 유형 / 주제 / 프로젝트 세 마디와 프로젝트 dl 행을 무조건 그린다. 프로젝트가 없으면 빈 링크와 빈 값이 남는다. 값이 없을 때 그 마디와 행을 빼도록 고친다. Case·Reference·Question 은 값이 늘 있으므로 화면이 달라지지 않는다.

테스트

  • 계약: design-package 검증기 3종(check-openapi / check-consistency / check-contract-parity)
  • 백엔드:
    • PublicSitePersistenceIntegrationTest — 개념 게시본이 홈·주제 최근 기록에 나온다
    • 공개 상세 통합 테스트 — /concepts/{slug} 가 본문·기준 버전·관계를 돌려준다
    • 검증기 단위 테스트 — 주제 없는 CONCEPT 은 게시가 막힌다(오류), 프로젝트 없음은 조용하다
    • ArchUnit D20(단일 생성자)은 새 어댑터에 그대로 적용된다
  • 프론트엔드:
    • public-question-mapping.test.ts 와 같은 방식으로 public-concept-mapping.test.ts — 계약 모양 그대로의 응답을 진짜 게이트웨이에 넣어 본문·기준 버전·관계가 채워지는지 본다
    • 화면 테스트 — 개념 상세가 목차와 본문을 그리고, 프로젝트 없는 머리말이 두 마디만 그린다
    • 탐색 필터 테스트 — type=CONCEPT 로 걸러진다
    • route-contract.test.ts — 새 라우트 등록

반영 순서

  1. design-package 계약 → 검증기 → 커밋
  2. 백엔드: vendored 계약 + MANIFEST.sha256, 마이그레이션, 코드, 테스트 → 커밋
  3. 프론트: codegen, 편집기·렌더러·라우트, 테스트 → 커밋
  4. 백엔드 이미지 → 임포트 → 롤아웃 (마이그레이션이 먼저 적용되어야 한다)
  5. 프론트 이미지 → 롤아웃
  6. 운영에서 개념 문서를 하나 써서 게시 → 홈·탐색·주제·상세를 눈으로 확인

백엔드를 먼저 올린다. 프론트가 먼저 올라가면 /concepts/{slug} 를 부르는 화면이 404 를 받는다. 반대 순서는 안전하다 — 백엔드에 새 경로가 생겨도 부르는 화면이 아직 없을 뿐이다.