원전 조사 — 도구 병행 절차 (Source Investigation with Tools)
서사는 사람이 남긴 것이고, 계측은 도구가 남긴 것이며, 커밋은 시점이 남긴 것이다. 셋이 어긋나는 자리가 글감이다.
이 문서는 [[manuscript-architect]] 가 Type 1(Drafted-First) 초안 단계에서 다른 저장소·다른 정원을 원전으로 삼을 때 따르는 조사 절차다.
20편 「톡브릿지, 데밍의 PDSA 루프를 품다」 구성초안(2026-09-04)에서 처음 적용했다 — draft/20-현장조사-pdsa-cli.md.
1. 왜 로그만으로 부족한가
하네스 로그는 한 회차에 무엇을 왜 했는지를 남긴다. 그러나 로그는 쓰는 사람이 그 시점에 본 것만 담는다. 20편 조사에서 로그와 실물이 어긋난 자리 셋:
| 로그가 말한 것 | 실물이 말한 것 | 어떻게 알았나 |
|---|---|---|
| 34 사이클 · 60% (09-03 로그) | 35 사이클 · 19/31 61% | pdsa status (09-04 조회) |
| CLI 0.0.8 기준 문서 | CLI 는 이미 0.0.9, 신규 명령 2개가 래퍼 주입 목록에 없음 | pdsa update --check · --help · 래퍼 소스 |
| "재오픈 2건" | 같은 화면이 세 번, 재발 유형이 서로 달랐음 | pdsa recall "재오픈" → 커밋 본문 복원 |
로그가 틀렸다는 뜻이 아니다 — 로그는 서사이고, 글은 서사 위에 계측과 시점을 얹어야 한다.
2. 순서 — 로그 → 그래프 → 커밋
① 로그(서사) harness/logs/{agent}/ 가설을 세운다 — "무슨 이야기인가"
↓
② 계측(도구) CLI 조회 (읽기 전용) 숫자를 확인한다 — "정말 그런가, 얼마나"
↓
③ 커밋(시점) git log / show 시점·인과를 복원한다 — "언제, 무엇과 함께"
↓
④ 어긋남 목록 ①②③ 이 다른 자리 → 통찰 후보, 팩트체크 메모
순서를 바꾸지 않는다. 계측부터 보면 숫자에 서사를 끼워 맞추고, 커밋부터 보면 이야기 없이 목록만 남는다.
3. 규칙
3-1. 읽기 전용 — 남의 그래프에 우리 회차를 섞지 않는다
- 계측 도구의 조회 명령만 쓴다(예: pdsa
status·history·show·eval·recall·project list/show·--help·update --check). - 기록을 만드는 명령(pdsa
plan/do/study/act·init·project set)은 글쓰기 세션에서 쓰지 않는다. 원전 정원의 계측이 오염된다. - 블로킹 명령(
view등 서버 기동)은 에이전트 세션에서 돌리지 않는다. - 원전 저장소에 래퍼가 있으면 래퍼로 호출한다(인코딩·프로젝트 고정·가드). 래퍼가 못 붙이는 인자(예: 신규 명령의
--project)는 수동으로 붙인다 — 붙이지 않으면 조용히 다른 그래프를 읽는다.
3-2. 조회 시점을 적는다
그래프는 계속 자란다. 본문·초안의 모든 수치에 조회 날짜를 붙인다("09-04 조회 기준 35 사이클"). 게시 시점에 갱신하지 않는다 — 글은 스냅샷이다.
3-3. 원본은 스크래치패드, 요약만 컨텍스트에
--json/--full 덤프는 스크래치패드에 저장하고, 세션 컨텍스트에는 스크립트로 요약한 표만 올린다(20편: 880KB 덤프 → 사이클 35행 표). 큰 출력을 통째로 읽으면 컨텍스트가 무너진다.
3-4. 식별자 치환
원전이 사내 저장소면 티켓 번호·담당자 닉·호스트명·리소스명·🔒 보호정보(원가·마진·단가)는 본문 전 치환한다 — "한 티켓", "QA 팀", "dev 환경". 동반 조사 문서(draft/NN-현장조사-*.md)에는 추적용으로 남기되 게시 대상이 아님을 상단에 명시한다. 계측 순번(사이클 #n)은 식별자가 아니므로 써도 된다.
3-5. 도구 자체를 먼저 대조한다
계측 도구의 버전·명령 표면을 문서와 대조하고 시작한다(update --check, --help). 20편에서 문서(0.0.8)와 실물(0.0.9)이 달랐고, 그 표류 자체가 7절의 글감이 됐다. 측정 도구도 시스템의 일부다(씨앗 글 교훈 ⑤).
3-6. 공개 원전이 API 로 안 읽히면 브라우저 렌더링
Notion 공개 페이지는 통합 봇에 공유되지 않으면 API 404 다. 공개 글이면 Playwright 로 렌더링해 텍스트를 뜬다(캐시된 Chromium 사용, 스크립트는 스크래치패드) — 20편 씨앗 글이 이 경로였다. 비공개 글은 소유자에게 공유를 요청한다.
4. 산출물
| 파일 | 내용 |
|---|---|
draft/NN-현장조사-<도구>.md | 도구 학습 요약 · 조회 명령 · 실측표 · 커밋 대조 · 본문 반영 계획(절별 조사 전/후) · 도구 발견 |
draft/NN-<제목>.md 의 "현장조사 보강" 절 | 브리프 수치 정정 + 동반 문서 포인터 |
harness/logs/manuscript-architect/…-field-study.md | 로그 + 평가 |
원전 저장소에서 발견한 결함(래퍼 누락 등)은 그 저장소의 회차로 처리한다 — 이 정원의 커밋에 섞지 않는다.
5. 관련
- [[manuscript-architect]] §1B 초안 → 원고 변환의 2단계("필요 시 외부 자료 조사로 보강")의 구체 절차
- [[manuscript-conventions]] — 자리표시자
[[REF]]로 미확보 원전을 표시하고 조사 후 해소 - 씨앗 글: 「데밍의 PDSA, 루프엔지니어링이 되다」 — "그래프 메모리를 깃 로그와 대조해 쓴 개발기". 이 절차는 그 방법의 계승이다