Files

T

DongHyeonkaandClaude Opus 5 ab59130196 chore: 이전 세션이 남긴 변경을 커밋한다

이번 파이프라인 작업과 무관하게 작업 트리에 남아 있던 것을 그대로 올린다.
사용자가 「전부 커밋」으로 정했고, 이번 작업과 섞이지 않게 커밋만 나눴다.

대부분은 clean-architecture-backend-template 의 그림 정본 재배치다 —
final/assets/diagrams/<이름>/ 에 있던 것이 CLAUDE.md 가 적은 배치인
final/assets/<이름>/ 로 옮겨졌고 .techviz/<이름>/ 이 함께 들어왔다.
삽입 줄의 대부분(3.15M)이 그 .techviz context.json 이다.

그 밖에 ca-tmpl·document-haness 의 정리, .claude/agents/ 열한 개,
writing-practitioner-guides 스킬, .playwright-mcp 세션 산출물,
scripts/check-ssot-facts.py 와 그 시험이 들어 있다.

이 커밋의 내용은 내가 만든 것이 아니라 이전 세션이 남긴 것이고 검증하지 않았다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-17 11:02:02 +09:00

6.3 KiB

Raw Blame History

기록 `.md` 의 어디가 Studio 의 어느 칸인가

세 자리

기록 `.md`	Studio
frontmatter	메타데이터. 화면 칸이 아니다
제목 바로 아래 첫 문단	`요약` 칸
`## <이름>`	같은 이름의 칸

## 요약 이라는 절을 만들지 않는다 — Studio 에 그런 칸이 없어 통째로 사라진다. ## 출처 도 칸이 아니다. 원본 경로는 frontmatter 의 source 에 있다.

종류마다의 칸

종류	기록 `.md` 의 `##` 이름	본문
Case	`관계` · `문제` · `결론` · `검증 환경` · `재현 조건` · `본문`	있음
Concept	`관계` · `본문`	있음
Setup	`관계` · `본문` — 본문 안의 `##` 는 칸이 아니다	있음
Reference	`관계` · `목적` · `규칙` · `적용 조건` · `예외` · `예시`	없음
Question	`관계` · `사실` · `가정` · `미지수` · `제약` · `선택지` · `다음 검증`	없음
Decision	`근거` · `결정문` · `판단 이유` · `영향`	없음

Decision 만 관계 절 이름이 근거 다. 그리고 근거가 1개 이상 없으면 게시가 거절된다.

환경 구성은 `##` 를 칸으로 세지 않는다

다른 다섯은 ## <이름> 하나가 칸 하나다. 환경 구성은 화면 칸이 고정한 버전 과 절차 Markdown 둘뿐이고, ## 실행 절차 · ## 구성 값 · ## 확인 방법 은 그 절차 Markdown 안의 소제목이다. 계약이 bodyMarkdown 설명에 「절 이름을 강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다」고 적는다.

그래서 넣는 법이 다르다. 기록의 ## 본문 아래 전체가 bodyMarkdown 한 칸으로 들어가고, 화면 칸에 따로 옮길 값은 고정한 버전 하나뿐이다.

기록 `.md`	어디로
frontmatter `pinnedVersions[]`	`고정한 버전` — 줄마다 `이름`·`버전` 입력 둘
`## 본문` 의 `<!-- body:start -->`~`<!-- body:end -->`	`절차 Markdown` 통째로
`## 관계`	`관계`

작업본을 만들면 절차 Markdown 이 비어 있지 않다. Studio 가 위의 절 셋을 미리 넣어 두므로, 본문을 넣기 전에 그 내용을 지운다.

화면의 라벨은 기록의 절 이름과 다르다

이것이 이 문서에서 가장 자주 틀리는 자리다. 위 표는 기록 .md 가 쓰는 이름이고, 편집 화면의 라벨은 다른 말을 쓴다. 그리고 /studio/documents/new 의 종류 카드에 적힌 요약 (목적 · 규칙 · 적용 조건 · 예외 · 예시)은 카드 문구이지 편집 화면의 라벨이 아니다.

Reference 에서 실제로 확인한 대응이다.

기록의 `##`	편집 화면의 라벨
`목적`	`이 기준을 쓰는 이유`
`규칙`	`판단 기준` — 제목과 본문 두 칸이 한 줄이다
`적용 조건`	`적용할 때`
`예외`	`예외와 주의`
`예시`	`예시`
`관계`	`관계`

종류 이름도 화면마다 달랐다. 상태 레일이 Reference 를 적용 기준 이라고 부르는 동안 새 문서 화면의 라디오는 Reference 였다. 2026-09-12 에는 새 문서 쪽도 여섯 다 한글이다 — 검증 기록 · 적용 기준 · 동작 원리 · 환경 구성 · 열린 질문 · 설계 결정.

화면을 먼저 스냅샷으로 읽고 그 라벨을 쓴다. 이 표를 외워서 넣지 않는다 — 화면이 바뀌면 표가 먼저 낡는다.

기록에 없는데 화면에 있는 칸

칸	무엇
`축`	주제 안의 변이(SPA · Mediator · BFF · Forward-Auth). 주제를 고른 뒤에 나타난다. 안 고르면 주제 공통 기록이 된다
`마지막 검증일`	기록의 `verifiedOn` 이다. 없으면 비워 둔다

근거가 없으면 비워 둔다. verifiedOn 이 없는 채로 저장하면 미리보기에 「마지막 검증」 절이 값 없이 뜬다. 그것은 날짜를 지어내는 것보다 낫다 — 게시 전에 사람이 채울지 정한다.

frontmatter 에서 화면으로 가는 값

frontmatter	어디로
`id`	편집 주소 `/studio/documents/<id>/edit`
`kind`	새 문서를 만들 때 고르는 종류
`slug` · `title`	화면 위쪽의 슬러그·제목 칸
`topic` · `topicName` · `project`	주제·프로젝트 선택
`basisVersion` (Concept)	기준 버전 칸
`pinnedVersions` (Setup)	고정한 버전 칸. `name` · `version` 이 한 줄
`questionStatus` (Question) · `decisionStatus` (Decision)	상태 선택
`assets[].file`	올릴 Asset 파일
`assets[].key`	본문 `:::evidence key` 의 저장소 쪽 이름. 올리면 서버 키로 바뀐다

계약이 화면에 주는 상태와 도메인이 들고 있는 상태가 다르다. QuestionStatus 는 화면에서 OPEN·RESOLVED 둘인데 도메인은 OPEN·INVESTIGATING·PAUSED·RESOLVED 넷이고, Decision 의 도메인 ACCEPTED 가 화면에서는 ADOPTED 로 보인다. 화면에서 고른 값이 도메인 상태를 덮어쓰지는 않는다.

본문이 없는 세 종류

Reference·Question·Decision 의 칸은 평문으로 렌더링된다.

백틱과 파이프가 글자 그대로 보인다. 코드·표를 넣지 않는다
줄바꿈은 <br> 로만 살아난다
나열은 쉼표로 잇지 말고 이름 : 값 으로 줄을 나눈다

코드·표·그림이 필요하면 짝이 되는 Case·Concept·Setup 에 담고 관계 로 가리킨다.

본문을 넣기 전에

저장소의 .md 는 그림을 마크다운 이미지로 싣는다. Studio 는 :::evidence 를 쓴다. 바꾸는 것은 스크립트가 한다.

python3 scripts/studio-body.py <기록.md> --body-only                    # 저장소 key 그대로
python3 scripts/studio-body.py <기록.md> --key a=a-1a2b3c4d --body-only # 서버가 준 key 로

저장소 파일 자체는 고치지 않는다.

되돌아오는 값

저장이 끝나면 Studio 가 id 를 준다. 새로 만든 기록이면 frontmatter 의 id 와 studio: 를 채운다. 그 두 칸이 차면 색인이 publication 을 게시됨 으로 적는데, 그것은 「Studio 에 있다」는 뜻이고 공개됐다는 뜻이 아니다. 공개 여부는 status 와 public: 이 말한다.

6.3 KiB Raw Blame History

기록 .md 의 어디가 Studio 의 어느 칸인가