qwreey
298dac2510
전 세션이 "재시작해야만 확인 가능"으로 남긴 3건을 전부 닫음: - @import 3개(conventions/project-context/todos) 실제 로드 확인 - quad-doc-auditor 레지스트리 등록 확인(전 세션 전멸은 .claude/agents/가 세션 도중 생긴 디렉토리였던 탓) - frontmatter model: sonnet 반영 확인(트랜스크립트에 claude-sonnet-5 기록, 워크플로에 opts.model 명시 불필요) 정의 파일은 세션 시작 시점 스냅샷으로 고정된다는 것을 1차 증거로 확정 — quad-handover-audit이 실제 실행한 스크립트가 세션 시작 시점 상태와 바이트 단위로 동일했고 같은 세션의 편집은 반영 0. 에이전트 정의도 동일. 정의를 고쳤으면 재시작 뒤에 감사를 돌릴 것(안 그러면 거짓 초록불). 전 세션 감사가 남긴 긴 가설 배너(80줄)를 검증된 것만 남겨 압축. quad-handover-audit 첫 실동: 에이전트 67개/6라운드, 수렴 실패 (새 발견 28→15→16→7→11→6, 라운드5에서 되레 증가). MAX_ROUNDS와 "연속 dry 2회" 조건 재검토 필요 — 결과 자체는 위 스냅샷 문제로 옛 스크립트가 돈 것이라 재시작 후 재실동 대상. 감사가 잡은 것 반영: slot-plan.md 정정 배너가 그 뒤 재역전(retract=언마운트)을 놓치고 있던 것, "spikes 44개"(실제 48개) 류 하드코딩 개수의 단일 소스화, doc-check.py docstring이 검사 심각도를 실제 코드와 다르게 서술하던 것 등. 인용 출처 3건 재분류 — 2건은 인용 대상만 틀린 것이라 실제 소스로 재조준 (v1-compat-plan.md→component-composition-plan.md+store-plan.md, pre-implementation-audit.md→ROADMAP.md). 진짜 출처가 없는 1건 (modifier-plan.md:536)만 question.md 3번으로 올려 사용자 판단 대기. 워크플로 개선: 반환값에 findings 추가(커밋 전 diff 리뷰 근거), totalFindingsFixed→findingsSentToFix 개명(과대계상), 반영 에이전트 sonnet 명시. .claude/agent-memory/는 의도적으로 커밋 제외(추적 여부는 사용자 판단). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
118 lines
7.2 KiB
Markdown
118 lines
7.2 KiB
Markdown
# 문서 stale 감소용 include 도구 — `doc-include.py` (가칭)
|
|
|
|
**상태**: research — 2026-08-14 세션에 아이디어 확정, **[2026-08-16 갱신]**
|
|
CLAUDE.md 분할로 파일럿 설계가 **단방향 생성으로 단순화**됨(아래 "파일럿
|
|
범위" 참고). 구현 착수 전.
|
|
|
|
> **[2026-08-16] 이 문서의 원 설계에서 절반이 불필요해졌음.** 원래는 원본에
|
|
> `<!--#summary-->`, 인용처에 `<!--#include-->` 두 종류 마커를 두는 **양방향**
|
|
> 설계였는데, 같은 날 CLAUDE.md를 분할하면서 세션 히스토리가 독립 파일
|
|
> (`.claude/session-summary.md`)이 됐음 — 목적지가 "손으로 쓴 파일 속 구간"이
|
|
> 아니라 **통째로 생성되는 파일**이 되면서 목적지 마커가 필요 없어졌다. 남는
|
|
> 건 원본 쪽 마커 + 단방향 생성기뿐. 아래 본문은 이 정정을 반영해 갱신했다.
|
|
|
|
## 배경
|
|
|
|
같은 날 진행된 코퍼스 전체 사실관계 감사(서브에이전트 4개 병렬)에서 실제
|
|
오류 20건을 찾아 고쳤는데, 대부분이 "같은 사실이 두 곳 이상에 적혀있다가
|
|
한쪽만 갱신됨" 패턴이었음(`bind-system-plan.md` 3단계 분할 후 다른 문서가
|
|
옛 줄번호를 가리키던 것 11곳 등). 이 프로젝트는 이미 `doc-check.py`(기계
|
|
검증기, ERROR/WARN 리포트)로 이 문제를 **사후 탐지**하고 있는데, 사용자가
|
|
**사전 차단**(애초에 중복 서술이 안 생기게)이 더 근본적이지 않겠냐고 제안 —
|
|
"summary" 같은 블록을 원본 파일에 마커로 표시해두고, 인용하는 쪽은 그 마커
|
|
구간을 기계적으로 추출해 붙여넣는 도구를 만들면 정보의 관리 주체가 자연히
|
|
한 파일로 모인다는 아이디어.
|
|
|
|
## 선례 (재발명 아님을 확인)
|
|
|
|
- **AsciiDoc tagged region include** — `// tag::x[]` ... `// end::x[]`로
|
|
구간 표시, `include::file.adoc[tag=x]`로 다른 문서가 그 구간만 당겨옴.
|
|
사용자가 제안한 `--#summary-start`/`--#summary-end` 아이디어의 원조 격.
|
|
- **markdown-magic**(JS) — HTML 주석 마커(`<!-- AUTO-GENERATED-CONTENT:START -->`)로
|
|
README 등에 다른 파일 내용을 주입, 재실행하면 갱신. Markdown 생태계에서
|
|
가장 가까운 기존 도구.
|
|
- **Obsidian/Roam/Logseq의 block transclusion**(`![[file#^blockid]]`) —
|
|
빌드 스텝 없이 렌더 시점에 라이브로 당겨옴. stale이 구조적으로 원천 차단되는
|
|
더 강한 버전이지만 이 프로젝트는 정적 `.md` 파일이 소스라 뷰어 종속적인
|
|
이 방식은 안 맞음.
|
|
|
|
## Build vs Buy 판단 — 직접 제작 채택
|
|
|
|
- 필요한 기능이 좁음: 마커 사이 텍스트를 원본에서 읽어 대상에 갱신 삽입 +
|
|
재실행해도 안정적(idempotent) + `--check` 모드로 어긋나면 실패. 정규식
|
|
몇 개 + 파일 I/O가 전부라 100줄 내외로 충분.
|
|
- 기존 도구(markdown-magic 등)를 쓰면 이 레포에 없던 Node/npm 툴체인이
|
|
새로 들어옴 — 지금 유일한 도구인 `doc-check.py`가 Python 표준 라이브러리만
|
|
쓰는 의존성 0 스크립트라는 관례와 어긋남. 프로젝트가 얻는 이득(TOC 생성,
|
|
배지 삽입 등 우리가 안 쓸 기능들)에 비해 대가가 큼.
|
|
- 마커 문법을 이 코퍼스 관례(한국어, `doc-check.py`의 ERROR/WARN 리포팅
|
|
스타일)에 맞춰 직접 정하고 싶으므로, 외부 도구 설정 파일로 끼워 맞추는
|
|
것보다 직접 짜는 쪽이 코드도 적고 통제도 쉬움.
|
|
|
|
**결론**: `.claude/tools/doc-check.py`와 짝을 이루는 `doc-include.py`를
|
|
Python 표준 라이브러리만으로 신설. `--write`(갱신 삽입)/`--check`(어긋나면
|
|
ERROR, `doc-check.py` 파이프라인에 편입) 두 모드.
|
|
|
|
## 파일럿 범위 — `.claude/session-summary.md` 전체 생성
|
|
|
|
사용자가 지목한 이유: 세션 히스토리 항목은 서로 독립적(과거 기록이라
|
|
다른 문서가 그 문장을 인용하는 경우가 거의 없음)이라 이 도구가 버그가
|
|
있어도 **부작용이 다른 곳으로 안 번짐** — 첫 적용 대상으로 가장 안전.
|
|
|
|
- **[2026-08-16 기준] 지금 구조**: `.claude/session/YYYY-MM-DD-NN-slug.md`에
|
|
세션 원문 전체가 있고, `.claude/session-summary.md`(CLAUDE.md 분할 전엔
|
|
`CLAUDE.md`의 "세션 히스토리" 절이었음)에 사람이 손으로 압축한 2~4줄
|
|
요약 + 링크가 **별도 텍스트로** 적혀있음 — 한쪽만 갱신되면 어긋날 수
|
|
있는 구조.
|
|
- **적용 후**: 각 세션 파일 안에 "이게 이 세션의 정본 요약"이라고 표시하는
|
|
마커 블록을 신설(**새로 요약을 쓸 필요 없음** — 지금 `session-summary.md`에
|
|
이미 있는 압축 요약을 그대로 그 블록 안으로 옮기면 됨). 생성기가 세션
|
|
파일들을 파일명 순으로 훑어 마커 블록을 모아 `session-summary.md`를
|
|
**통째로 다시 씀**. 그 시점부터 `session-summary.md`는 직접 편집 금지
|
|
대상이 되고(파일 상단에 그렇게 명시), 요약을 고치려면 세션 파일을 고침.
|
|
|
|
### 왜 목적지 마커가 필요 없어졌나
|
|
|
|
원안은 목적지(`CLAUDE.md`)가 손으로 관리되는 파일이라, 그 안의 특정
|
|
구간만 골라 갱신하려고 `<!--#include-->` 마커가 필요했음. 분할 후엔
|
|
목적지가 **파일 통째로 파생 데이터**라 "어디를 갱신할지"를 표시할 이유가
|
|
없음 — 파일 전체를 덮어쓰면 됨. 부품이 절반으로 줄고, "목적지 마커가
|
|
손실되면?" 같은 실패 모드도 같이 사라짐.
|
|
|
|
## 마커 문법 (초안 — 사용자가 확정할 것)
|
|
|
|
```
|
|
# 세션 파일(.claude/session/2026-08-14-14-....md) 안:
|
|
<!--#summary-->
|
|
**2026-08-14 열네 번째 세션 — ...** (`session/2026-08-14-14-....md`)
|
|
... 2~4줄 압축 요약 ...
|
|
<!--#/summary-->
|
|
```
|
|
|
|
`session-summary.md` 쪽엔 마커가 없음 — 생성기가 헤더 + 각 세션 블록을
|
|
파일명 순으로 이어 붙여 전체를 씀. id도 불필요해짐(파일명이 곧 순서이자
|
|
식별자).
|
|
|
|
## 열린 질문 (사용자가 다듬을 것)
|
|
|
|
1. 마커 문법 자체(위 초안 확정 여부, id 네이밍 규칙 — 날짜+세션번호로
|
|
충분한지).
|
|
2. 기존 세션 항목 전부(`.claude/session/` 폴더에 지금까지 쌓인 파일
|
|
전부 — 개수는 여기 안 적음, 폴더가 소스)에 마커를 소급 삽입할지, 아니면 다음
|
|
세션부터 신규 항목에만 적용하고 과거분은 그대로 둘지.
|
|
3. `--write` 실행 시점 — 수동(세션 마무리 시 사람이 실행) vs 커밋 훅.
|
|
이 레포는 지금 CI가 없고 사람이 `doc-check.py`도 수동으로 돌리는
|
|
관례라 같은 패턴(수동 + 커밋 전 확인)이 자연스러워 보이지만 확정은
|
|
사용자 몫.
|
|
4. `--check` 실패를 `doc-check.py`의 ERROR로 편입할지 별도 스크립트로
|
|
둘지.
|
|
5. 파일럿이 성공하면 다음 확대 후보 — `.claude/README.md` 표의 "상태"
|
|
요약을 각 `base/`/`research/` 문서 맨 위 `**상태**: ...` 줄에서
|
|
추출해오는 것(단, `luau-test/STATUS.md`처럼 이미 "폴더 구조 자체가
|
|
상태"인 곳은 include로 바꿀 필요 없음 — 그쪽은 이미 소스가 하나로
|
|
수렴된 상태라 적용 대상 아님).
|
|
|
|
## 우선순위
|
|
|
|
하 — M0/설계 게이트와 무관한 메타 도구. 사용자가 플랜을 다듬은 뒤 착수
|
|
시점 결정.
|