feat: 문서 구조 변경 및 tech-visual 스킬 추가
This commit is contained in:
DongHyeonka
@@ -1,20 +1,43 @@
|
||||
# CLAUDE.md
|
||||
|
||||
이 저장소는 한국어 기술 블로그를 쓰고 보관하는 작업 공간이다. 글을 쓰거나 고칠 때는
|
||||
`.claude/skills/`의 스킬 세 개를 아래 순서로 사용한다.
|
||||
이 저장소는 Tech Log Studio에 올릴 기록을 쓰고 보관하는 작업 공간이다. 기록을 쓰거나 고칠 때는
|
||||
`.claude/skills/writing-tech-log-records`를 사용한다. 문장이 AI가 쓴 것처럼 읽히면
|
||||
`.claude/skills/rewriting-technical-prose-naturally`로 다시 쓴다. 다이어그램은
|
||||
`.claude/skills/technical-visualizer`로 만든다.
|
||||
|
||||
## 실행 순서
|
||||
|
||||
```text
|
||||
원자료·초안
|
||||
→ writing-korean-technical-blogs 문제·제약·선택·구현·결과·한계로 구조화
|
||||
→ reducing-ai-like-korean-writing 상투성·추상화·반복·과잉 구조화 제거
|
||||
→ editing-korean-grammar-and-expression 맞춤법·띄어쓰기·문법·호응 검수
|
||||
→ 사실·수치·코드·인용 최종 대조
|
||||
원자료
|
||||
→ 종류 선택 Case · Concept · Reference · Question · Decision
|
||||
→ 칸 채우기 종류마다 칸이 다르다
|
||||
→ 본문 작성 Case · Concept. 코드·표·다이어그램·이미지
|
||||
→ 다이어그램 technical-visualizer 스킬. 손으로 SVG 를 그리지 않는다
|
||||
→ 파서 검사 check_body.mjs
|
||||
→ 문장 검사 check_prose.mjs (error 0) · style_profile.mjs
|
||||
→ 게시 전 대조 references/review-checklist.md
|
||||
→ Studio 저장 → 게시 → 공개 화면 확인
|
||||
```
|
||||
|
||||
문법만 고치거나 문체만 다듬을 때는 해당 스킬을 직접 쓴다. 조사, 실행 검증, 이미지 제작,
|
||||
게시까지 묶어서 관리하는 절차는 이 저장소에 없다.
|
||||
**코드·표·다이어그램·이미지는 본문에만 들어간다. 본문이 있는 종류는 Case와 Concept이다.**
|
||||
Reference·Question·Decision의 칸은 평문으로 렌더링된다. 그런 자료가 필요하면 Case나 Concept에
|
||||
담고 `관계`로 가리킨다.
|
||||
|
||||
조사와 실행 검증을 묶어서 관리하는 절차는 이 저장소에 없다.
|
||||
|
||||
## 다이어그램
|
||||
|
||||
`technical-visualizer` 스킬로 만든다. 도구(`techviz`)는 `ai-tool/technical-visualization-haness`에
|
||||
있고 이 저장소에는 스킬만 들어와 있다. `./scripts/techviz`가 래퍼이고, 경로가 다르면 `TECHVIZ_HOME`으로
|
||||
알려 준다.
|
||||
|
||||
```bash
|
||||
./scripts/techviz doctor
|
||||
```
|
||||
|
||||
문서를 읽어 context를 만들고, 구성 문법(profile)을 고르고, VizSpec 1.1을 쓰고, lint를 통과한 뒤
|
||||
SVG로 컴파일한다. 손으로 SVG를 그리지 않는다. **그림 안에는 이름만 넣고 문장은 `<desc>`와 옆 문단에
|
||||
둔다.**
|
||||
|
||||
## 작업 규칙
|
||||
|
||||
@@ -32,19 +55,95 @@
|
||||
|
||||
## 문서 위치
|
||||
|
||||
문서는 `.run/<slug>/final/document.md`에 둔다. 다이어그램은 같은 런의 `assets/`,
|
||||
측정 자료는 `evidence/`에 둔다.
|
||||
프로젝트 하나가 폴더 하나다. 프로젝트 문서는 그 폴더 밖에 두지 않는다.
|
||||
|
||||
| 런 | 문서 |
|
||||
|---|---|
|
||||
| `executable-clean-architecture` | 실행 가능한 클린 아키텍처 — 선언이 아니라 빌드가 지키는 경계 |
|
||||
| `keycloak-four-patterns` | 브라우저 토큰에서 엣지 세션까지: Keycloak 인증 패턴 네 가지의 경계 설계 |
|
||||
| `n+1liner` | 하이라이트 피드 조회 성능 — N+1 진단과 조회 전략의 진화 |
|
||||
|
||||
## 스킬 검증
|
||||
|
||||
```bash
|
||||
for d in .agents/skills/*/; do ( cd "$d" && python3 scripts/validate_skill.py ); done
|
||||
```text
|
||||
docs/<프로젝트>/
|
||||
├── source/ 밖에서 가져온 원본. 고치지 않는다
|
||||
├── final/ SSOT — 이 프로젝트에 대해 아는 것 전부
|
||||
│ ├── document.md 상세한 글
|
||||
│ ├── assets/ svg, drawio, 그림
|
||||
│ ├── .techviz/ 그림의 정본 (context, spec, prompt)
|
||||
│ └── evidence/ 증거. 아래 셋으로만 나눈다
|
||||
│ ├── terminal/ 명령을 돌려 얻은 출력 (테스트·빌드·EXPLAIN·curl·가드)
|
||||
│ ├── metrics/ 잰 값 (csv)
|
||||
│ └── screens/ 캡처 (Playwright MCP 스크린샷 포함)
|
||||
└── tech-log-studio/ Studio 에 올릴 글만
|
||||
├── tech-log-tree.json 글감 목록. 항상 최신으로 둔다
|
||||
└── <주제 slug>/
|
||||
├── case/ concept/ reference/ question/ decision/
|
||||
```
|
||||
|
||||
세 스킬 모두 PASS여야 한다. 이 스크립트는 PyYAML을 요구한다.
|
||||
`final/` 이 정본이고 `tech-log-studio/` 는 거기서 뽑아낸 글이다. 증거는 `final/evidence/` 에만
|
||||
두고 기록에서는 그 파일을 가리킨다. 같은 파일을 양쪽에 두지 않는다.
|
||||
|
||||
증거 폴더는 프로젝트마다 같다. `terminal/` 아래에는 하위 폴더를 자유롭게 둔다
|
||||
(`terminal/explain/`, `terminal/guards/`). 캡처와 출력에는 무엇을 담았는지 한 줄을 같은 폴더의
|
||||
`README.txt` 에 적는다 — 파일 이름만으로는 6개월 뒤에 못 읽는다.
|
||||
|
||||
기록은 frontmatter 로 잇는다. `assets` 는 Studio 에 올릴 그림이고 `evidence` 는 인용한 측정
|
||||
자료다. Studio 에 넣을 때 `assets` 를 보고 Asset 을 올린 뒤 본문의 `:::evidence key` 를 서버가
|
||||
준 키로 바꾼다.
|
||||
|
||||
```yaml
|
||||
assets:
|
||||
- key: eager-lazy-query-sequence
|
||||
file: ../../../final/assets/tech-log-studio/eager-lazy-query-sequence.svg
|
||||
evidence:
|
||||
- ../../../final/evidence/explain/highlights-child-plan-A.txt
|
||||
```
|
||||
|
||||
주제 폴더 이름은 Studio 주제의 slug 를 쓴다 — `jpa-feed-query-performance`,
|
||||
`oauth-oidc-auth-boundary`. Studio 가 주제별로 다섯 종류를 나눠 보여 주므로 폴더도 같은 모양이다.
|
||||
|
||||
Redis 20편은 한 글을 나눠 쓴 것이라 `docs/clean-architecture-backend-template/final/document.md`
|
||||
하나로 합쳐 두었다. SSOT 는 프로젝트마다 `final/document.md` 하나다.
|
||||
|
||||
## 밖에서 문서를 가져올 때
|
||||
|
||||
다른 프로젝트에서 쓴 문서를 이 저장소로 옮길 때 따르는 순서다.
|
||||
|
||||
1. 원본을 `docs/<프로젝트>/source/` 에 그대로 복사한다. 손대지 않는다 — 대조할 것이 필요하다
|
||||
2. 원본과 증거를 `final/` 로 옮긴다. 글은 `final/document.md`, 그림은 `assets/`,
|
||||
터미널 기록·스크린샷·실행계획은 `evidence/`. **여기까지가 SSOT 다**
|
||||
3. SSOT 를 읽고 글감을 뽑아 `tech-log-tree.json` 에 적는다. 종류(case·concept·reference·
|
||||
question·decision)와 주제를 먼저 정하고 제목만 적는다. 아직 글은 쓰지 않는다
|
||||
4. 트리의 글감 하나를 골라 `<주제>/<종류>/` 아래에 기록을 쓴다. 증거는 `final/evidence/` 의
|
||||
파일을 가리킨다
|
||||
5. 기록을 쓰거나 지웠으면 트리를 다시 만든다 — `python3 scripts/build-tech-log-tree.py`
|
||||
6. Studio 에 넣고 저장한다
|
||||
|
||||
`tech-log-tree.json` 은 손으로 고쳐도 되고 스크립트로 다시 만들어도 된다. 스크립트는 기록
|
||||
파일에서 제목·slug·상태를 읽어 채우고, 파일이 아직 없는 글감은 지우지 않고 남긴다.
|
||||
|
||||
| 런 또는 파일 | 문서 |
|
||||
|---|---|
|
||||
| `ca-tmpl` | 실행 가능한 클린 아키텍처 — 선언이 아니라 빌드가 지키는 경계 |
|
||||
| `keycloak` | 브라우저 토큰에서 엣지 세션까지: Keycloak 인증 패턴 네 가지의 경계 설계 |
|
||||
| `n+1liner` | 하이라이트 피드 조회 성능 — N+1 진단과 조회 전략의 진화 |
|
||||
| `TechLog` | 계약이 먼저인 시스템에서 값이 사라지는 자리들 — TechLog를 만들며 만난 결함의 전수 기록 |
|
||||
| `clean-architecture-backend-template` | Redis를 정책 경계로 다루는 코드 (20편을 합침) |
|
||||
|
||||
## 검사
|
||||
|
||||
게시 전에 둘 다 돌린다. 하나는 파서를, 하나는 문장을 본다.
|
||||
|
||||
**본문이 Studio 파서를 통과하는지.** Studio가 쓰는 파서를 그대로 부르므로 통과하면 저장도 통과한다.
|
||||
|
||||
```bash
|
||||
node --experimental-transform-types \
|
||||
.agents/skills/writing-tech-log-records/scripts/check_body.mjs 초안.md
|
||||
```
|
||||
|
||||
`tech-log-frontend` 체크아웃 경로가 다르면 `--frontend` 또는 `TECH_LOG_FRONTEND`로 알려 준다.
|
||||
|
||||
**문장이 규범을 지키는지.** `error` 가 남아 있으면 덜 된 글이다. 칸 하나나 한 절만 고쳤으면
|
||||
`--doc` 을 빼고 부른다.
|
||||
|
||||
```bash
|
||||
S=.agents/skills/rewriting-technical-prose-naturally/scripts
|
||||
node $S/check_prose.mjs --warn 초안.md # error 0 까지 고친다
|
||||
node $S/style_profile.mjs 초안.md # 문체 수치. 기준은 우아한형제들 5편
|
||||
```
|
||||
|
||||
수치를 맞추려고 문장을 넣지 않는다. 검사기는 표면 패턴만 보고 뜻은 못 본다.
|
||||
|
||||
Reference in New Issue
Block a user