171 lines
7.9 KiB
Markdown
171 lines
7.9 KiB
Markdown
# Tech Log 기록 작업 공간
|
|
|
|
이 저장소는 [Tech Log Studio](https://hyeonworks.com/studio)에 올릴 기록을 쓰고 보관하는
|
|
곳입니다. 작성 능력은 `.agents/skills/`의 Agent Skill이 담당하고, 완성된 글과 근거 자료는
|
|
`docs/` 아래에 프로젝트별로 보관합니다.
|
|
|
|
## 스킬
|
|
|
|
| 스킬 | 언제 |
|
|
|---|---|
|
|
| `running-tech-log-pipeline` | 코드베이스에서 Studio 저장까지 일곱 단계를 한 줄기로 돌릴 때. 단계마다 서브에이전트를 띄우고 런 원장에 남깁니다 |
|
|
| `publishing-tech-log-to-studio` | 다 쓴 기록을 Studio 에 넣고 저장할 때. Playwright MCP 를 쓰고 게시하지 않습니다 |
|
|
| `writing-tech-log-records` | Studio에 올릴 기록 한 건을 쓰거나 고칠 때. 종류 선택, 칸 채우기, 본문 작성, 게시 전 대조 |
|
|
| `rewriting-technical-prose-naturally` | 이미 쓴 문장이 AI가 쓴 것처럼 읽힐 때 |
|
|
| `writing-as-the-person-who-did-it` | 정확한데 아무도 쓰지 않은 보고서처럼 읽힐 때. 자료에 남은 사람의 흔적을 제자리에 놓습니다 |
|
|
| `technical-visualizer` | 다이어그램이 필요할 때. 손으로 SVG를 그리지 않습니다 |
|
|
|
|
`.claude/skills/`는 위 폴더를 가리키는 상대 경로 심링크입니다.
|
|
|
|
`technical-visualizer`는 스킬만 이 저장소에 있고 도구(`techviz` 파이썬 패키지)는
|
|
`ai-tool/technical-visualization-haness`에 있습니다. `scripts/techviz`가 래퍼이고, 경로가
|
|
다르면 `TECHVIZ_HOME`으로 알려 줍니다.
|
|
|
|
## 실행 순서
|
|
|
|
```text
|
|
원자료
|
|
→ 종류 선택 Case · Concept · Reference · Question · Decision
|
|
→ 칸 채우기
|
|
→ 본문 작성 Case · Concept
|
|
→ 다이어그램 technical-visualizer 스킬
|
|
→ 파서 검사 check_body.mjs
|
|
→ 문장 검사 check_prose.mjs (error 0) · style_profile.mjs
|
|
→ 게시 전 대조
|
|
→ Studio 저장 → 게시 → 공개 화면 확인
|
|
```
|
|
|
|
**코드·표·다이어그램·이미지는 본문에만 들어갑니다. 본문이 있는 종류는 Case와 Concept입니다.**
|
|
Reference·Question·Decision의 칸은 평문으로 렌더링됩니다. 그런 자료가 필요하면 Case나 Concept에
|
|
담고 `관계`로 가리킵니다.
|
|
|
|
작업 규칙과 보관 중인 문서 목록은 `CLAUDE.md`에 있습니다.
|
|
|
|
## 한 줄기로 실행할 때
|
|
|
|
`running-tech-log-pipeline` 이 일곱 단계(S1 SSOT → S2 분해 계약 → S3 기록 → S4 그림 →
|
|
S5 AI 티 → S6 목소리 → S7 Studio 저장)를 정의하고 단계마다 서브에이전트를 띄웁니다.
|
|
한 런은 `runs/<프로젝트>/<runId>/run.json` 에 원장을 남기고, 그 원장이 절차를 지켰는지는
|
|
따로 검사합니다.
|
|
|
|
```bash
|
|
python3 scripts/verify-pipeline-run.py runs/<프로젝트>/<runId>/run.json
|
|
```
|
|
|
|
단계가 빠졌는지, 그 단계가 자기 스킬을 실제로 열었는지(`skillEcho`), 관문이 통과했는지,
|
|
산출물이 디스크에 있는지를 봅니다.
|
|
|
|
## 보관 구조
|
|
|
|
`docs/` 아래를 프로젝트로 나눕니다. 프로젝트 문서는 그 폴더 밖에 두지 않습니다. 루트에는
|
|
`.agents`·`.claude`·`.codex`·`.playwright-mcp`·`runs/`와
|
|
`CLAUDE.md`·`README.md`·`LICENSE`·`scripts/`만 둡니다.
|
|
|
|
```text
|
|
docs/
|
|
├── ca-tmpl/ 실행 가능한 클린 아키텍처
|
|
├── clean-architecture-backend-template/
|
|
│ 분석 진행 중 (모듈 7편)
|
|
├── keycloak/ 인증 패턴 네 가지
|
|
├── keycloak-session-store/ 세션 저장소와 장애 주입 실험 26건
|
|
│ keycloak 의 열린 질문 네 개에 답한다
|
|
├── n+1liner/ 피드 조회 성능
|
|
└── TechLog/ 이 Studio를 만들며 만난 결함
|
|
```
|
|
|
|
프로젝트 하나는 이렇게 생겼습니다.
|
|
|
|
```text
|
|
docs/<프로젝트>/
|
|
├── source/ 밖에서 가져온 원본. 고치지 않습니다
|
|
├── final/ SSOT — 이 프로젝트에 대해 아는 것 전부
|
|
│ ├── document.md 상세한 글
|
|
│ ├── assets/ svg, drawio, 그림
|
|
│ ├── .techviz/ 그림의 정본 (context, spec, prompt)
|
|
│ └── evidence/ 터미널 기록, 실행계획, csv, 스크린샷
|
|
└── tech-log-studio/ Studio에 올릴 글만
|
|
├── tech-log-tree.json 글감 목록
|
|
└── <주제 slug>/
|
|
├── case/ concept/ reference/ question/ decision/
|
|
```
|
|
|
|
`final/`이 정본이고 `tech-log-studio/`는 거기서 뽑아낸 글입니다. 증거는 `final/evidence/`에만
|
|
두고 기록은 그 파일을 가리킵니다.
|
|
|
|
주제 폴더 이름은 Studio 주제의 slug입니다. Studio가 주제별로 다섯 종류를 나눠 보여 주므로
|
|
폴더도 같은 모양입니다. 지금은 `keycloak`에 `oauth-oidc-auth-boundary` 23건,
|
|
`n+1liner`에 `jpa-feed-query-performance` 24건이 있습니다.
|
|
`keycloak-session-store`는 SSOT 까지 들어왔고 기록은 아직 없습니다.
|
|
|
|
`tech-log-tree.json`은 그 주제 아래 어떤 글감이 있고 어디까지 썼는지를 한 파일에 모읍니다.
|
|
기록을 쓰거나 지운 뒤에는 다시 만듭니다.
|
|
|
|
```bash
|
|
python3 scripts/build-tech-log-tree.py # 전부
|
|
python3 scripts/build-tech-log-tree.py keycloak # 하나만
|
|
```
|
|
|
|
## 밖에서 문서를 가져올 때
|
|
|
|
1. 원본을 `docs/<프로젝트>/source/`에 그대로 복사합니다
|
|
2. 글·그림·증거를 `final/`로 옮깁니다 — 여기까지가 SSOT입니다
|
|
3. SSOT를 읽고 글감을 뽑아 `tech-log-tree.json`에 제목만 적습니다
|
|
4. 글감 하나를 골라 `<주제>/<종류>/`에 기록을 씁니다
|
|
5. 트리를 다시 만듭니다
|
|
6. Studio에 넣고 저장합니다
|
|
|
|
## 검사
|
|
|
|
게시 전에 둘 다 돌립니다. 하나는 파서를, 하나는 문장을 봅니다.
|
|
|
|
```bash
|
|
# 본문이 Studio 파서를 통과하는지. 같은 파서를 그대로 부릅니다
|
|
node --experimental-transform-types \
|
|
.agents/skills/writing-tech-log-records/scripts/check_body.mjs 초안.md
|
|
|
|
# 문장이 규범을 지키는지. error가 남아 있으면 덜 된 글입니다
|
|
S=.agents/skills/rewriting-technical-prose-naturally/scripts
|
|
node $S/check_prose.mjs --warn 초안.md
|
|
node $S/style_profile.mjs 초안.md
|
|
```
|
|
|
|
`check_body.mjs`는 `tech-log-frontend` 체크아웃을 읽습니다. 경로가 다르면 `--frontend` 또는
|
|
`TECH_LOG_FRONTEND`로 알려 줍니다.
|
|
|
|
기록이 수백 건이면 하나씩 읽어 확인할 수 없습니다. 구조는 기계가 셉니다.
|
|
|
|
```bash
|
|
python3 scripts/audit-records.py # 전부
|
|
python3 scripts/audit-records.py keycloak # 하나만
|
|
```
|
|
|
|
그림은 좌표까지 봅니다. lint는 관계만 보고 좌표를 안 봐서, 구역이 겹쳐 그려지거나 라벨이
|
|
상자에 먹혀도 통과합니다.
|
|
|
|
```bash
|
|
python3 scripts/check-figure-text.py <프로젝트> # <text>가 전부 이름인가
|
|
python3 scripts/check-figure-overlap.py <프로젝트> # 상자와 라벨이 겹치지 않는가
|
|
```
|
|
|
|
칸이 비었는지, `kind`와 폴더가 맞는지, `topic`이 폴더 slug인지, 본문 마커가 있는지,
|
|
`assets`·`evidence`가 가리키는 파일이 실제로 있는지, 본문이 부르는 자산이 frontmatter에
|
|
선언돼 있는지, 증거의 원문·메타·렌더가 짝을 이루는지를 봅니다. 문제가 있으면 종료 코드가
|
|
1입니다.
|
|
|
|
`style_profile.mjs`의 기준값은 우아한형제들 기술블로그 5편에서 잰 것입니다. 수치를 맞추려고
|
|
문장을 넣지 않습니다 — 두 검사기 모두 표면 패턴만 보고 뜻은 못 봅니다.
|
|
|
|
## 이력
|
|
|
|
이 저장소에는 ClariDoc 하네스(파이썬 패키지 `claridoc-harness` 0.2.0과 CLI)가 있었습니다.
|
|
2026-08-07에 제거했습니다. 제거 직전 상태는 `pre-harness-removal` 태그에 있습니다.
|
|
|
|
```bash
|
|
git show pre-harness-removal:src/claridoc/cli.py
|
|
git checkout pre-harness-removal -- <경로>
|
|
```
|
|
|
|
## 라이선스
|
|
|
|
MIT. `LICENSE` 참조.
|