feat: 질문의 인식 상태, 개념의 흐름, 프로젝트 목록의 조사 상태

열린 질문의 네 구역이 같은 제목+본문 모양이라, 긴 글을 훑을 때 「확인한 사실」과
「가정」이 눈으로 구분되지 않았다. 이 기록의 값어치가 바로 그 구분에 있는데 화면에서
사라져 있었다. 색을 다섯 개 칠하지 않고 표식 하나와 왼쪽 선만 다르게 둔다.

다음 검증은 「무엇을 확인할 것인가」만 있었다. 이 질문이 열려 있는 이유는 남은
미지수이므로 그것을 여기 다시 세워 둘을 잇는다 — 작성자가 따로 적지 않아도 사슬이 보인다.

개념은 여느 긴 글과 똑같이 제목 다음에 첫 문단이 왔다. 어느 계층을 지나는 이야기인지
알려면 끝까지 읽어야 했다. 본문의 소제목이 곧 그 계층이므로 손으로 적지 않고 거기서
흐름을 만든다 — 손으로 적게 하면 본문을 고칠 때 그 줄만 낡는다.

편집기 목차는 구역만 읽어서 Question 에서는 「판단과 다음 검증」 한 줄이었다. 확인한
사실·가정·남은 미지수·제약이 전부 그 한 구역 안의 묶음이기 때문이다. 묶음도 함께 읽어
7,540px 짜리 폼에서 목차가 제 일을 하게 한다.

프로젝트 목록은 이름과 단계만 있어 한 줄이 차지하는 높이에 비해 말하는 것이 적었다.
기록·열린 질문·결정 수를 실어, 그 프로젝트가 지금 모으는 중인지 정리된 상태인지가
목록에서 보이게 한다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
This commit is contained in:
DongHyeonka
2026-09-16 01:29:42 +09:00
co-authored by Claude Opus 5
parent a66316e22d
commit 5399e19429
7 changed files with 260 additions and 12 deletions
@@ -8,10 +8,34 @@ export function ProjectsPage() {
const entries = (await queries.searchPublicContent("")).filter(
(item) => item.contentType === "PROJECT",
);
const slugs = entries.map((item) => item.path.replace("/projects/", ""));
/*
목록에도 조사의 상태를 싣는다. 이름과 단계만 있던 동안 한 줄이 차지하는 높이에 비해
말하는 것이 너무 적었다 — 넓은 여백이 남고, 읽는 사람은 그 프로젝트가 지금 어디쯤인지
들어가 봐야 알았다. 기록과 결정은 각 프로젝트에서 읽어 와 세고, 열린 질문도 거기서 센다.
*/
const resolved = await Promise.all(
entries.map((item) => queries.getProject(item.path.replace("/projects/", ""))),
slugs.map(async (slug) => {
const project = await queries.getProject(slug);
if (!project) return undefined;
const [records, decisions] = await Promise.all([
queries.getProjectRecords(slug),
queries.getProjectDecisions(slug),
]);
return {
project,
records: records.length,
decisions: decisions.length,
open: records.filter(
(record) =>
record.kind === "QUESTION" &&
record.questionStatus !== "RESOLVED" &&
record.questionStatus !== "ARCHIVED",
).length,
};
}),
);
return { projects: resolved.filter((project) => project !== undefined) };
return { projects: resolved.filter((entry) => entry !== undefined) };
});
// Header first: it is fixed copy and owes the network nothing.
@@ -34,7 +58,7 @@ export function ProjectsPage() {
<p className="public-empty-note">아직 공개된 프로젝트가 없습니다.</p>
) : (
<ol className="project-index-list">
{view.data.projects.map((project, index) => (
{view.data.projects.map(({ project, records, decisions, open }, index) => (
<li key={project.slug}>
<Link to={`/projects/${project.slug}`}>
<span>{String(index + 1).padStart(2, "0")}</span>
@@ -66,6 +90,13 @@ export function ProjectsPage() {
) : null}
</dl>
) : null}
{/*
세 숫자가 이 프로젝트가 지금 어디쯤인지를 말한다. 기록만 많고 결정이 0이면
아직 모으는 중이고, 열린 질문이 0이면 더 볼 것이 남지 않은 상태다.
*/}
<p className="project-index-state">
{`기록 ${records} · 열린 질문 ${open} · 결정 ${decisions}`}
</p>
</div>
<span aria-hidden="true">↗</span>
</Link>
@@ -0,0 +1,32 @@
type Step = Readonly<{ id: string; label: string }>;
/**
* 동작 원리가 지나가는 자리들을 한눈에.
*
* <p>개념 기록의 목적은 "작동 원리를 나중에 빠르게 되살리는 것"이다. 그런데 화면은 여느 긴 글과
* 똑같이 제목 다음에 바로 첫 문단이 왔다 — 어느 계층을 지나는 이야기인지 알려면 끝까지 읽거나
* 오른쪽 목차를 따로 읽어야 했다.
*
* <p>본문의 소제목이 곧 그 계층들이므로, 그것을 가로로 이어 첫 화면에 세운다. 작성자가 따로
* 적을 것이 없다는 점이 중요하다 — 손으로 적게 하면 본문을 고칠 때 이 줄만 낡는다.
*
* <p>누르면 그 자리로 간다. 목차와 같은 일을 하지만 모양이 다르다: 목차는 "무엇이 있나"의
* 목록이고, 이것은 "어디를 지나는가"의 흐름이다.
*/
export function MechanismMap({ steps }: { steps: ReadonlyArray<Step> }) {
/* 한 자리짜리 흐름은 흐름이 아니다. 둘 이상일 때만 그린다. */
if (steps.length < 2) return null;
return (
<nav className="shell mechanism-map" aria-label="지나가는 자리">
<p className="section-kicker">Mechanism</p>
<ol>
{steps.map((step) => (
<li key={step.id}>
<a href={`#${step.id}`}>{step.label}</a>
</li>
))}
</ol>
</nav>
);
}
@@ -10,6 +10,7 @@ import type {
import { CaseBodyRenderer } from "./case-body-renderer.tsx";
import { ContextNavigator } from "./context-navigator.tsx";
import { DocumentToc } from "./document-toc.tsx";
import { MechanismMap } from "./mechanism-map.tsx";
import { RailContext } from "./rail-context.tsx";
import {
PublicDocumentRelations,
@@ -313,6 +314,12 @@ function ConceptDocument({
<ContextNavigator model={model} />
{/*
개념은 여느 긴 글과 달리 "어디를 지나는가"가 먼저 보여야 한다. 본문의 소제목이 곧 그
계층이므로 손으로 적지 않고 거기서 만든다 — 손으로 적게 하면 본문을 고칠 때 이 줄만 낡는다.
*/}
<MechanismMap steps={headings} />
<DocumentToc headings={headings} variant="mobile" />
<div className="shell document-layout">
@@ -573,26 +580,34 @@ function QuestionDocument({
)}
</aside>
) : null}
{/*
네 구역이 같은 제목+본문 모양이라, 긴 글을 훑을 때 「확인한 사실」과 「가정」이 눈으로
구분되지 않았다. 이 기록의 값어치는 무엇이 검증됐고 무엇이 아직 아닌지를 갈라 적는
데 있는데, 그 구분이 화면에서 사라져 있었다.
색을 다섯 개 칠하지 않는다. 표식 하나와 왼쪽 선만 다르게 둔다 — 나머지 화면이 카드도
채도 높은 색도 쓰지 않는다.
*/}
<article className="public-document-body question-body">
<section aria-labelledby="facts-title">
<section aria-labelledby="facts-title" data-epistemic="fact">
<h2 id="facts-title">확인한 사실</h2>
<OrderedItems items={model.facts} />
</section>
<section aria-labelledby="assumptions-title">
<section aria-labelledby="assumptions-title" data-epistemic="assumption">
<h2 id="assumptions-title">가정</h2>
<OrderedItems
items={model.assumptions}
empty="현재 기록된 가정이 없습니다."
/>
</section>
<section aria-labelledby="unknowns-title">
<section aria-labelledby="unknowns-title" data-epistemic="unknown">
<h2 id="unknowns-title">남은 미지수</h2>
<OrderedItems
items={model.unknowns}
empty="해결 과정에서 남은 미지수가 없습니다."
/>
</section>
<section aria-labelledby="constraints-title">
<section aria-labelledby="constraints-title" data-epistemic="constraint">
<h2 id="constraints-title">제약</h2>
<OrderedItems items={model.constraints} />
</section>
@@ -615,7 +630,30 @@ function QuestionDocument({
>
<p className="section-kicker">Next</p>
<h2 id="next-validation-title">다음 검증</h2>
<ProseText text={model.nextValidation} />
{/*
「무엇을 확인할 것인가」는 있었지만 「왜 그것이 다음인가」가 없었다. 이 기록이 열려
있는 이유는 남은 미지수이므로, 그 미지수를 여기 다시 세워 둘을 잇는다 — 작성자가
따로 적지 않아도 사슬이 보인다.
*/}
{model.unknowns.length > 0 ? (
<div className="next-validation-why">
<p>왜 다음인가</p>
<ul>
{[...model.unknowns]
.sort((left, right) => left.order - right.order)
.slice(0, 2)
.map((item) => (
<li key={item.id}>
<ProseText text={item.text} />
</li>
))}
</ul>
</div>
) : null}
<div className="next-validation-how">
<p>어떻게 확인하나</p>
<ProseText text={model.nextValidation} />
</div>
</section>
</article>
<PublicDocumentRelations relations={publicRelations(model.relations)} />
@@ -21,8 +21,26 @@ export function EditorSectionToc({ containerId }: { containerId: string }) {
const read = () => {
const found: Array<{ id: string; label: string }> = [];
for (const section of container.querySelectorAll("section[aria-labelledby]")) {
const labelId = section.getAttribute("aria-labelledby");
/*
구역과 항목 묶음을 함께 읽는다.
구역만 읽던 동안 Question 편집기의 목차에는 「판단과 다음 검증」 한 줄만 있었다 — 확인한
사실·가정·남은 미지수·제약·검토한 선택지가 전부 그 한 구역 안의 fieldset 이기 때문이다.
7,540px 짜리 폼에서 목차가 한 줄이면 없는 것과 같다.
문서 순서대로 모으려고 한 번의 질의로 훑는다. 둘을 따로 모으면 구역이 먼저 오고 묶음이
뒤에 몰려, 목차 순서가 화면 순서와 달라진다.
*/
for (const node of container.querySelectorAll(
"section[aria-labelledby], fieldset[id] > legend",
)) {
if (node.tagName === "LEGEND") {
const fieldset = node.parentElement;
const label = node.textContent?.replace(/접기$|펼치기 \(\d+\)$/u, "").trim();
if (fieldset?.id && label) found.push({ id: fieldset.id, label });
continue;
}
const labelId = node.getAttribute("aria-labelledby");
const heading = labelId ? document.getElementById(labelId) : null;
const label = heading?.textContent?.trim();
if (labelId && label) found.push({ id: labelId, label });
@@ -3943,3 +3943,130 @@ summary {
summary {
cursor: pointer;
}
/* 열린 질문 — 무엇이 검증됐고 무엇이 아직 아닌지를 표식으로 가른다 */
/*
네 구역이 같은 제목+본문 모양이라 긴 글을 훑을 때 「확인한 사실」과 「가정」이 눈으로
구분되지 않았다. 이 기록의 값어치가 바로 그 구분에 있는데 화면에서 사라져 있었다.
색을 다섯 개 칠하지 않는다. 표식 하나와 왼쪽 선만 다르게 둔다.
*/
.question-body > section[data-epistemic] {
padding-left: 19px;
border-left: 2px solid var(--line);
}
.question-body > section[data-epistemic] > h2::before {
display: inline-block;
width: 20px;
margin-left: -20px;
color: var(--faint);
font-family: "IBM Plex Mono", monospace;
font-weight: 600;
}
/* 검증된 근거 — 채워진 표식. */
.question-body > section[data-epistemic="fact"] {
border-left-color: var(--evidence);
}
.question-body > section[data-epistemic="fact"] > h2::before {
content: "●";
color: var(--evidence);
}
/* 아직 검증하지 않은 전제 — 비운 표식. */
.question-body > section[data-epistemic="assumption"] > h2::before {
content: "○";
}
/* 이 질문이 열려 있는 이유. */
.question-body > section[data-epistemic="unknown"] {
border-left-color: var(--warning);
}
.question-body > section[data-epistemic="unknown"] > h2::before {
content: "?";
color: var(--warning);
}
/* 이번 판단에서 바꿀 수 없는 조건. */
.question-body > section[data-epistemic="constraint"] > h2::before {
content: "│";
}
.next-validation-why,
.next-validation-how {
margin-top: 22px;
}
.next-validation-why > p,
.next-validation-how > p {
margin: 0 0 8px;
color: var(--faint);
font-size: 12px;
font-weight: 650;
letter-spacing: 0.06em;
}
.next-validation-why ul {
margin: 0;
padding-left: 18px;
color: var(--ink-soft);
}
.next-validation-why li {
padding-block: 3px;
}
/* 동작 원리가 지나가는 자리들 */
.mechanism-map {
padding-bottom: 10px;
}
.mechanism-map > ol {
display: flex;
flex-wrap: wrap;
gap: 7px 0;
margin: 13px 0 0;
padding: 0;
list-style: none;
}
.mechanism-map > ol > li {
display: flex;
align-items: center;
}
/* 사이의 화살표. 마지막 뒤에는 붙이지 않는다 — 더 갈 곳이 있다는 거짓말이 된다. */
.mechanism-map > ol > li:not(:last-child)::after {
content: "→";
padding-inline: 11px;
color: var(--line-strong);
font-size: 13px;
}
.mechanism-map a {
padding: 5px 11px;
border: 1px solid var(--line);
border-radius: 999px;
color: var(--ink-soft);
font-size: 13px;
line-height: 1.4;
}
.mechanism-map a:hover {
border-color: var(--signal);
color: var(--signal);
}
/* 프로젝트 목록의 조사 상태 */
.project-index-state {
margin: 13px 0 0;
color: var(--faint);
font-family: "IBM Plex Mono", monospace;
font-size: 12px;
}
@@ -131,11 +131,11 @@ describe("TechLog project screens", () => {
).toEqual([
{
href: "/projects/backend-skeleton",
text: "01Backend Skeleton설계저장소·Redis·JPA·MongoDB 같은 기술을 붙일 때 애플리케이션 경계를 다시 만들지 않도록 공통 계약을 정리하는 프로젝트입니다.현재 목표Filesystem과 Object Storage를 하나의 StoragePort로 통합다음 작업MinIO Adapter와 공통 계약 테스트 연결↗",
text: "01Backend Skeleton설계저장소·Redis·JPA·MongoDB 같은 기술을 붙일 때 애플리케이션 경계를 다시 만들지 않도록 공통 계약을 정리하는 프로젝트입니다.현재 목표Filesystem과 Object Storage를 하나의 StoragePort로 통합다음 작업MinIO Adapter와 공통 계약 테스트 연결기록 4 · 열린 질문 0 · 결정 2↗",
},
{
href: "/projects/auth-lab",
text: "02Auth Lab검증브라우저·Edge·Spring 사이에서 Token과 Session의 책임을 나누고 인증 경계를 검증하는 프로젝트입니다.현재 목표oauth2-proxy 뒤의 Spring 신뢰 경계 결정다음 작업JWT 재검증안과 신뢰 헤더안의 위협 모델 비교↗",
text: "02Auth Lab검증브라우저·Edge·Spring 사이에서 Token과 Session의 책임을 나누고 인증 경계를 검증하는 프로젝트입니다.현재 목표oauth2-proxy 뒤의 Spring 신뢰 경계 결정다음 작업JWT 재검증안과 신뢰 헤더안의 위협 모델 비교기록 2 · 열린 질문 1 · 결정 1↗",
},
]);
});
@@ -41,6 +41,8 @@ const SETTLED = new Set([
".home-path-trail li",
".home-path-records li",
".investigation-records li",
// 흐름의 마디는 한 모양뿐이다 — 각 li 안에 링크 하나.
".mechanism-map a",
".studio-warning-check span",
]);