feat: 개념(CONCEPT) 문서 종류 — 편집기·공개 화면·탐색

Kubernetes 내부 동작처럼 처음부터 풀어 읽어야 하는 글을 쓸 자리를 만든다. Reference 는
판단 기준을 빨리 찾는 글이라 규칙·적용·예외로 나뉘고, 그 틀에 개념을 넣으면 두 글이 서로를
망친다 — 기준을 찾으러 온 사람은 배경을 지나야 하고, 개념을 배우러 온 사람은 규칙에서
시작한다.

편집기는 Case 의 본문 칸과 Asset Picker 를 그대로 쓴다. 아키텍처 도식은 같은
`:::evidence` 로 들어오고, `##` 소제목이 목차가 된다. 개념이 따로 갖는 것은 기준 버전
하나다 — 개념이 낡는 방식은 날짜가 아니라 버전이다.

공개 렌더는 Case 와 본문·목차를 공유하되 머리말이 다르다. 문제도 결론도 검증 환경도 없고,
프로젝트 마디는 값이 있을 때만 그린다 — 개념은 프로젝트 없이 서는 유일한 종류다.

픽스처가 실제 결함을 하나 드러냈다. 프로젝트 없는 기록이 처음 생기자 `?project=` 빈 값이
"프로젝트가 없는 기록 전부" 를 뜻하게 됐다 — 고르지 않은 것이 고른 것이 되어 버린다. 빈
필터는 아무것도 고르지 않도록 고쳤다. 예전에는 빈 값에 걸릴 기록이 없어 저절로 맞았다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
This commit is contained in:
DongHyeonka
2026-08-28 19:51:20 +09:00
co-authored by Claude Opus 5
parent 9ecc017f22
commit 048c1b2f68
27 changed files with 749 additions and 47 deletions
@@ -151,6 +151,9 @@ export function validateWorkingCopyInputStructure(input: WorkingCopyInput): Fiel
ordered(errors, "/options", input.options, [["title", 120, 1], ["description", 100_000, 0]]);
text(errors, "/nextValidation", input.nextValidation, 100_000);
if (input.resolution) { text(errors, "/resolution/summary", input.resolution.summary, 100_000); uuid(errors, "/resolution/evidenceTargetId", input.resolution.evidenceTargetId, true); text(errors, "/resolution/linkLabel", input.resolution.linkLabel, 120); }
} else if (input.kind === "CONCEPT") {
text(errors, "/bodyMarkdown", input.bodyMarkdown, 100_000);
text(errors, "/basisVersion", input.basisVersion, 120);
} else {
text(errors, "/statement", input.statement, 100_000);
text(errors, "/rationale", input.rationale, 100_000);
@@ -171,10 +174,15 @@ export function validateWorkingCopy(document: WorkingCopy, dependencies: Validat
if (blank(document.title)) error("TITLE_REQUIRED", "/title", "제목을 입력하세요.");
if (blank(document.slug)) error("SLUG_REQUIRED", "/slug", "slug를 입력하세요."); else if (dependencies.documents.some((item) => item.id !== document.id && item.slug === document.slug)) error("SLUG_DUPLICATE", "/slug", "중복 slug입니다.");
if (blank(document.summary)) warning("SUMMARY_REQUIRED", "/summary", "요약을 입력하세요.");
if (!has(document.topicId, "TOPIC")) warning("TOPIC_REQUIRED", "/topicId", "Topic을 선택하세요.");
if (!has(document.topicId, "TOPIC")) {
// 개념은 프로젝트 없이 설 수 있는 유일한 종류다. 주제가 유일한 집이므로 비면 막는다.
if (document.kind === "CONCEPT") error("TOPIC_REQUIRED", "/topicId", "개념에는 주제가 필요합니다.");
else warning("TOPIC_REQUIRED", "/topicId", "Topic을 선택하세요.");
}
if (!document.projectId) {
if (document.kind === "PROJECT_DECISION") warning("DECISION_PROJECT_REQUIRED", "/projectId", "Decision에는 Project가 필요합니다.");
else warning("PROJECT_MISSING", "/projectId", "Project 연결을 권장합니다.");
// 개념에 프로젝트가 없는 것은 결함이 아니라 정상이다 — 아는 것이지 프로젝트 산출물이 아니다.
else if (document.kind !== "CONCEPT") warning("PROJECT_MISSING", "/projectId", "Project 연결을 권장합니다.");
} else if (!has(document.projectId, "PROJECT")) error("PROJECT_NOT_FOUND", "/projectId", "Project를 찾을 수 없습니다.");
document.relations.forEach((relation, index) => { if (!has(relation.targetId, "RELATION")) error("RELATION_TARGET_NOT_FOUND", `/relations/${index}/targetId`, "관계 대상을 찾을 수 없습니다."); });
if (document.kind === "CASE") {
@@ -210,6 +218,9 @@ export function validateWorkingCopy(document: WorkingCopy, dependencies: Validat
if (document.questionStatus === "OPEN") { if (!document.unknowns.length) error("QUESTION_UNKNOWN_REQUIRED", "/unknowns", "미확인 사항이 필요합니다."); if (document.resolution) error("OPEN_QUESTION_RESOLUTION_FORBIDDEN", "/resolution", "열린 질문에는 결론을 둘 수 없습니다."); }
if (document.questionStatus === "RESOLVED") { if (!document.resolution) warning("QUESTION_RESOLUTION_REQUIRED", "/resolution", "해결 내용이 필요합니다."); else { if (blank(document.resolution.summary)) warning("RESOLUTION_SUMMARY_REQUIRED", "/resolution/summary", "요약이 필요합니다."); if (!has(document.resolution.evidenceTargetId, "EVIDENCE")) error("RESOLUTION_EVIDENCE_REQUIRED", "/resolution/evidenceTargetId", "근거가 필요합니다."); if (blank(document.resolution.linkLabel)) warning("RESOLUTION_LINK_LABEL_REQUIRED", "/resolution/linkLabel", "링크 문구가 필요합니다."); } }
if (document.options.length < 2) warning("QUESTION_OPTIONS_FEWER_THAN_TWO", "/options", "선택지 두 개를 권장합니다.");
} else if (document.kind === "CONCEPT") {
// 개념은 본문이 전부다. 비어 있으면 제목만 있는 글이 공개된다.
if (blank(document.bodyMarkdown)) warning("BODY_REQUIRED", "/bodyMarkdown", "본문을 입력하세요.");
} else {
if (!document.decisionStatus) warning("DECISION_STATUS_REQUIRED", "/decisionStatus", "결정 상태가 필요합니다.");
if (!document.decidedOn) warning("DECIDED_ON_REQUIRED", "/decidedOn", "결정일이 필요합니다.");
@@ -1,4 +1,4 @@
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION";
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
export type QuestionStatus =
| "OPEN"
| "INVESTIGATING"
@@ -96,7 +96,23 @@ export type QuestionRecord = PublicRecordBase & {
};
};
export type PublicRecord = CaseRecord | ReferenceRecord | QuestionRecord;
/**
* 개념. Reference 가 규칙·적용·예외로 나뉘는 것과 달리 본문 하나로 흐르고, 낡음은 검증일이
* 아니라 기준 버전이 말한다. 프로젝트가 없어도 되는 유일한 종류다.
*/
export type ConceptRecord = PublicRecordBase & {
kind: "CONCEPT";
basisVersion: string;
content: string;
bodyAssets: ReadonlyArray<PublicBodyAsset>;
sections: ReadonlyArray<RecordSection>;
};
export type PublicRecord =
| CaseRecord
| ReferenceRecord
| QuestionRecord
| ConceptRecord;
export type ProjectDecision = {
id: string;
@@ -167,6 +183,49 @@ export type HomeFocusItem = {
};
export const publicRecords: ReadonlyArray<PublicRecord> = [
{
kind: "CONCEPT",
slug: "kubernetes-scheduling",
title: "Kubernetes 스케줄링은 어떻게 결정되는가",
summary:
"Pod 가 Node 에 앉기까지 scheduler 가 거치는 단계를 따라가고, 예약과 실제 바인딩이 갈라지는 지점을 짚습니다.",
path: "/concepts/kubernetes-scheduling",
topic: "Kubernetes",
topicSlug: "kubernetes",
// 개념은 프로젝트 없이 선다 — 프로젝트 산출물이 아니라 아는 것이다.
projectSlug: "",
projectTitle: "",
publishedAt: "2026-08-20T10:00:00+09:00",
publishedLabel: "2026.08.20",
visibility: "PUBLIC",
basisVersion: "Kubernetes 1.31",
content: "",
bodyAssets: [],
sections: [
{
id: "what-the-scheduler-sees",
title: "스케줄러가 보는 것",
paragraphs: [
"스케줄러는 아직 노드가 정해지지 않은 Pod 를 감시한다. 그 목록은 API 서버가 주고, 결정의 근거는 노드의 여유 자원과 Pod 가 건 조건이다.",
],
},
{
id: "filtering-and-scoring",
title: "Filtering 과 Scoring",
paragraphs: [
"먼저 둘 수 없는 노드를 걸러 내고(Filtering), 남은 노드에 점수를 매긴다(Scoring). 거르는 단계에서 전부 탈락하면 Pod 는 Pending 으로 남는다.",
],
},
{
id: "reservation-and-binding",
title: "예약과 실제 바인딩의 간격",
paragraphs: [
"점수가 가장 높은 노드를 고른 뒤 스케줄러는 먼저 자기 캐시에 자리를 예약하고, 바인딩은 API 서버에 따로 보낸다. 그 사이에 노드 상태가 바뀌면 kubelet 이 거절할 수 있다.",
],
},
],
relations: [],
},
{
kind: "CASE",
slug: "collection-fetch-join-pagination",
@@ -42,8 +42,19 @@ function comparePublishedAt(
}
export function listRecords(filters: RecordFilters = {}): PublicRecord[] {
const hasTopicFilter = filters.topic !== undefined;
const hasProjectFilter = filters.project !== undefined;
/*
빈 필터는 아무것도 고르지 않는다.
예전에는 빈 값을 비교해도 걸리는 기록이 없어 저절로 빈 목록이 됐다. 개념이 프로젝트 없이
설 수 있게 되면서 `projectSlug` 가 빈 기록이 생겼고, 그때부터 `?project=` 는 "프로젝트가
없는 기록 전부" 를 뜻하게 됐다 — 고르지 않은 것이 고른 것이 되어 버린다.
*/
const hasTopicFilter = filters.topic !== undefined && filters.topic.trim() !== "";
const hasProjectFilter = filters.project !== undefined && filters.project.trim() !== "";
const filtersNothing =
(filters.topic !== undefined && filters.topic.trim() === "") ||
(filters.project !== undefined && filters.project.trim() === "");
if (filtersNothing) return [];
const requestedTopic = filters.topic?.trim().toLocaleLowerCase("ko-KR");
const requestedProject = filters.project
?.trim()