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
parent 2109f726fe
commit ab59130196
1524 changed files with 3160026 additions and 8369 deletions
@@ -90,8 +90,14 @@ python3 scripts/studio-body.py <기록.md> --key <저장소 key>=<서버가 준
 줄이 모자란 채로 채우면 뒤엣것이 조용히 버려진다. 셀렉터와 배치 실행 방법은
 [references/playwright-recipes.md](references/playwright-recipes.md).

-**본문이 없는 세 종류(Reference·Question·Decision)의 칸은 평문으로 렌더링된다.** 백틱과
-파이프가 글자 그대로 보이고, 줄바꿈은 `<br>` 로만 살아난다.
+**본문이 없는 세 종류(Reference·Question·Decision)의 칸은 마크다운 블록 파서를 안 거친다.**
+그래도 전부 글자로 나오지는 않는다 — 렌더러(`tech-log-frontend` 의
+`presentation/shared/public-render/prose-text.tsx`)가 **백틱 쌍은 인라인 `<code>` 로** 살리고,
+빈 줄은 문단으로, 한 줄 바꿈은 `<br>` 로 남긴다. **글자 그대로 나오는 것은 별표·파이프·`#`·
+코드펜스·인용 표지 `>` 다.** 백틱을 빼지 않는다 — 빼면 식별자가 민무늬로 나온다.
+
+**환경 구성에도 되풀이 칸이 하나 있다.** `고정한 버전` 은 줄마다 `이름`·`버전` 입력 둘이고
+「버전 추가」 버튼으로 늘린다. 여기도 줄 수를 먼저 맞추고 값을 넣는다.

 ### 4. 저장한다

@@ -128,16 +134,26 @@ python3 scripts/verify-tech-log-tree.py <프로젝트>

 ## 시험용 초안을 남기지 않는다

-확인하려고 만든 작업본은 지운다. **다섯 종류 전부 삭제 경로가 있다** —
-`tech-log-backend` @ `a000f87` 의 `ManagementDocumentController` 에서 센 것이다.
+확인하려고 만든 작업본은 지운다. **여섯 종류 전부 삭제 경로가 있다.** 앞의 다섯은
+`tech-log-backend` @ `a000f87` 의 `ManagementDocumentController` 에서 셌고, 환경 구성은
+`tech-log-frontend` @ `9e5642c` 의 `management-api.openapi.yaml:606-628`(`deleteSetupDraft`)
+에서 읽었다. 경로 앞머리가 줄마다 다른 것은 두 문서가 각자 적는 대로 옮겼기 때문이다.

-| 종류 | 경로 |
-|---|---|
-| Case | `DELETE /v1/studio/cases/{id}` (`:72`) |
-| Reference | `DELETE /v1/studio/references/{id}` (`:81`) |
-| Concept | `DELETE /v1/studio/concepts/{id}` (`:95`) |
-| Question | `DELETE /v1/studio/questions/{id}` (`:114`) |
-| Decision | `DELETE /v1/studio/projects/{id}/decisions/{decisionId}` (`:123`) |
+| 종류 | 경로 | 본문 |
+|---|---|---|
+| Case | `DELETE /v1/studio/cases/{id}` (`:72`) | `{"expectedVersion": <저장 버전>}` |
+| Reference | `DELETE /v1/studio/references/{id}` (`:81`) | `{"expectedVersion": <저장 버전>}` |
+| Concept | `DELETE /v1/studio/concepts/{id}` (`:95`) | `{"expectedVersion": <저장 버전>}` |
+| Setup | `DELETE /api/v1/studio/setups/{id}` | `{"expectedVersion": <저장 버전>}` |
+| Question | `DELETE /v1/studio/questions/{id}` (`:114`) | `{"expectedVersion": <저장 버전>}` |
+| Decision | `DELETE /v1/studio/projects/{id}/decisions/{decisionId}` (`:123`) | `{"expectedVersion": <저장 버전>}` |
+
+**본문 없이 부르면 204 가 아니라 422 다.** `ExpectedVersionRequest` 가 없으면
+`REQUEST_VALIDATION_FAILED` / `Request body is malformed` 로 거절된다. 헤더에는
+`X-CSRF-TOKEN` 이 있어야 한다. 여섯 줄 다 같고, 전에 이 표는 경로만 적고 본문을 적지 않았다.
+
+환경 구성 줄은 2026-09-12 에 시험 작업본 하나를 만들고 이 경로로 지워 204 를 받아 확인했다
+(계약 `9e5642c`).

 **전에 이 자리에 「Decision 은 계약에 삭제 경로가 없다」고 적혀 있었고 그것은 틀렸다.**
 확인 없이 적힌 문장이 옮겨 다녔다 — 이 배치에서 그 문장을 코드 주석과 보고서로 다시 옮긴
@@ -17,19 +17,23 @@

 종류를 라디오로 고르고 `작업본 만들기` 를 누른다. 라디오의 이름은 화면에 보이는 그대로다.

-| 종류 | 라디오 이름 | 화면이 적어 놓은 칸 |
+| 계약 `kind` | 라디오 이름 | 화면이 적어 놓은 칸 |
 |---|---|---|
-| Case | `Case` | 문제 · 결론 · 환경 · 재현 · 본문 |
-| Reference | `Reference` | 목적 · 규칙 · 적용 조건 · 예외 · 예시 |
-| Concept | **`개념`** | 기준 버전 · 본문 |
-| Question | `Question` | 상태 · 사실 · 가정 · 미지수 · 선택지 |
-| Decision | `Decision` | 상태 · 결정일 · 결정문 · 판단 이유 · 영향 · 근거 |
+| `CASE` | `검증 기록` | 문제 · 결론 · 환경 · 재현 · 본문 |
+| `REFERENCE` | `적용 기준` | 목적 · 규칙 · 적용 조건 · 예외 · 예시 |
+| `CONCEPT` | `동작 원리` | 기준 버전 · 본문 |
+| `SETUP` | `환경 구성` | 버전 · 본문 |
+| `QUESTION` | `열린 질문` | 상태 · 사실 · 가정 · 미지수 · 선택지 |
+| `PROJECT_DECISION` | `설계 결정` | 상태 · 결정일 · 결정문 · 판단 이유 · 영향 · 근거 |

-**Concept 만 라디오 이름이 한글(`개념`)이다.** 나머지 넷은 영어다.
+**여섯 다 한글이다.** 이 표는 전에 「Concept 만 라디오 이름이 한글(`개념`)이다. 나머지 넷은
+영어다」라고 적고 있었고 그것은 낡았다 — 2026-09-12 에 `/studio/documents/new` 를 열어 여섯
+라디오의 이름을 그대로 읽었다. **화면 문구는 이렇게 조용히 바뀐다.** 표를 외워서 넣지 말고
+스냅샷으로 읽은 이름을 쓴다.

 ```js
 await page.goto('https://hyeonworks.com/studio/documents/new');
-await page.getByRole('radio', { name: /^Reference/ }).check();
+await page.getByRole('radio', { name: /^환경 구성/ }).check();
 await page.getByRole('button', { name: '작업본 만들기' }).click();
 // 주소가 /studio/documents/<uuid>/edit 로 바뀐다. 그 uuid 를 기록 frontmatter 에 적는다
 ```
@@ -17,12 +17,32 @@
 |---|---|---|
 | **Case** | `관계` · `문제` · `결론` · `검증 환경` · `재현 조건` · `본문` | 있음 |
 | **Concept** | `관계` · `본문` | 있음 |
+| **Setup** | `관계` · `본문` — 본문 안의 `##` 는 칸이 아니다 | 있음 |
 | **Reference** | `관계` · `목적` · `규칙` · `적용 조건` · `예외` · `예시` | 없음 |
 | **Question** | `관계` · `사실` · `가정` · `미지수` · `제약` · `선택지` · `다음 검증` | 없음 |
 | **Decision** | **`근거`** · `결정문` · `판단 이유` · `영향` | 없음 |

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

+## 환경 구성은 `##` 를 칸으로 세지 않는다
+
+다른 다섯은 `## <이름>` 하나가 칸 하나다. 환경 구성은 화면 칸이 `고정한 버전` 과
+`절차 Markdown` 둘뿐이고, **`## 실행 절차` · `## 구성 값` · `## 확인 방법` 은 그 `절차 Markdown`
+안의 소제목**이다. 계약이 `bodyMarkdown` 설명에 「절 이름을 강제하지 않는다 — 프로젝트마다
+셋업의 모양이 다르다」고 적는다.
+
+그래서 넣는 법이 다르다. 기록의 `## 본문` 아래 전체가 `bodyMarkdown` 한 칸으로 들어가고, 화면
+칸에 따로 옮길 값은 `고정한 버전` 하나뿐이다.
+
+| 기록 `.md` | 어디로 |
+|---|---|
+| frontmatter `pinnedVersions[]` | `고정한 버전` — 줄마다 `이름`·`버전` 입력 둘 |
+| `## 본문` 의 `<!-- body:start -->`~`<!-- body:end -->` | `절차 Markdown` 통째로 |
+| `## 관계` | `관계` |
+
+작업본을 만들면 `절차 Markdown` 이 비어 있지 않다. Studio 가 위의 절 셋을 미리 넣어 두므로,
+본문을 넣기 전에 그 내용을 지운다.
+
 ## 화면의 라벨은 기록의 절 이름과 다르다

 **이것이 이 문서에서 가장 자주 틀리는 자리다.** 위 표는 기록 `.md` 가 쓰는 이름이고,
@@ -40,8 +60,9 @@ Reference 에서 실제로 확인한 대응이다.
 | `예시` | `예시` |
 | `관계` | `관계` |

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

 **화면을 먼저 스냅샷으로 읽고 그 라벨을 쓴다.** 이 표를 외워서 넣지 않는다 — 화면이 바뀌면
 표가 먼저 낡는다.
@@ -65,6 +86,7 @@ Reference 에서 실제로 확인한 대응이다.
 | `slug` · `title` | 화면 위쪽의 슬러그·제목 칸 |
 | `topic` · `topicName` · `project` | 주제·프로젝트 선택 |
 | `basisVersion` (Concept) | 기준 버전 칸 |
+| `pinnedVersions` (Setup) | 고정한 버전 칸. `name` · `version` 이 한 줄 |
 | `questionStatus` (Question) · `decisionStatus` (Decision) | 상태 선택 |
 | `assets[].file` | 올릴 Asset 파일 |
 | `assets[].key` | 본문 `:::evidence key` 의 저장소 쪽 이름. 올리면 서버 키로 바뀐다 |
@@ -82,7 +104,7 @@ Decision 의 도메인 `ACCEPTED` 가 화면에서는 `ADOPTED` 로 보인다.
 - 줄바꿈은 `<br>` 로만 살아난다
 - 나열은 쉼표로 잇지 말고 `이름 : 값` 으로 줄을 나눈다

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

 ## 본문을 넣기 전에