Confluence Page Workflow

스킬 경계: Confluence 페이지 생성·수정 전용. 연구 기록은 /confluence-research-record, 워크플로우 설계는 /workflow 사용.

자동 트리거 조건

• Confluence 페이지 생성/수정 요청
• mcp__claude_ai_Atlassian__updateConfluencePage / createConfluencePage 호출 전
• Confluence URL 또는 페이지 ID가 대화에 등장

실행 흐름

0. 프로젝트 양식 레지스트리 조회 (§0) — 등록 양식 있으면 §1 질문 생략 가능
1. 포맷 참고 페이지 확인 (§1 — §0 미등록 시)
2. 연구 페이지라면 연구 동기 확인 (§1-1) 2.5. 콘텐츠 범위 게이트 (§1-2) — 작업 경위 배제, 본문 작성 전 필수
3. 페이지 구조 표준 적용 (§2)
4. 수정 전 3단계 확인 (§3) 4.5. 게시 전 기계 게이트: 골격 대조(§0, 등록 양식 있을 때 confluence_skeleton_check.py 차단 0건)와 한국어 문체(§6-1, korean_style_check.py 차단 0건). 출력 원문 없이는 게시 금지
5. 업데이트 실행 (is_minor_edit, version_comment 적용)
6. 레이아웃 수동 설정 안내 (너비 최대, 밀도 압축)

§0. 프로젝트 양식 레지스트리 조회 (MANDATORY — §1보다 먼저, 2026-07-20)

~/.claude/doc-formats/<프로젝트>/ 존재를 확인한다 (존재=등록, 규약: rules-lazy/doc-format-registry.md):

• 등록됨 → 양식 인덱스(README) Read → 해당 페이지 유형 양식 적용. 양식이 기준 페이지 ID를 지정하므로 §1 참고 페이지 질문 생략 가능
• 골격 대조 게이트(MANDATORY, 예외 없음 — 2026-09-02 사용자 지시): 신설·절 구조 변경은 게시 전 python3 ~/.claude/scripts/confluence_skeleton_check.py <storage.html> --format <프로젝트>/<양식> 차단 0건이 조건. «양식을 읽었다»는 보고는 증거가 아니다 — 13차 총괄 페이지가 규칙이 있는데도 h1만 7개로 게시된 실사고(레지스트리 게이트 6)
• 미등록 → §1 진행 + 레지스트리 § 부트스트랩 제안 (어느 서버·어느 프로젝트든 동일)

§1. 포맷 참고 페이지 확인 (MANDATORY — 생성/수정 전)

포맷 참고할 페이지를 선택해주세요:
1. [이전 작업 페이지 제목] — [URL]
또는 직접 URL 제공

§1-1. 연구 페이지 콘텐츠 품질 기준 (연구 관련 페이지 시)

연구 동기 확인 (신규 연구 페이지 MANDATORY):

이 연구를 시작하게 된 계기나 문제 의식을 알려주세요.

수집한 동기를 Overview 첫 문단 + Motivation & Background 섹션에 반영.

포함 필수 항목: Research Motivation / Abstract·Overview / Motivation & Background / Method(수식·아키텍처) / Implementation Details / Experiment Design(설계 근거 포함) / Results / Related Work

§1-2. 콘텐츠 범위 — 작업 경위 배제 (MANDATORY, 2026-07-23 사용자 지시)

룰: 작성하는 컨플 또는 이미 작성된 컨플에 있는 내용 외에, 작업을 진행하며 있었던 내용은 기입하지 않는다. 하네스 흔적 금지(에이전트명·스킬명·/goal 등 슬래시 커맨드·mem0·subagent)와 동급의 MANDATORY 이며, 그 범위를 "AI 도구 이름"에서 **"작업 경위 전반"**으로 확장한 것이다.

Why: 페이지는 제품·시스템의 사실을 남기는 문서지, 그 사실에 도달하기까지의 경위를 남기는 작업 로그가 아니다. 경위가 섞이면 독자가 결과와 시행착오를 구분하지 못하고, 문서가 세션 기록처럼 읽힌다. (2026-07-23 실측: 두 DR 페이지에서 중간 오측정 정정·감시 스크립트 오판·작업 회고 절이 지적돼 일괄 삭제)

판정 기준 (작성 직전 각 블록에 적용)

배제 대상 (예시 — 전부 실측 삭제 사례)

• 중간 오측정과 그 정정 ("초기 재측정치 15:47 은 사실 warm 하이브리드였다", "중간에 본 83.00% 는 100건 표본 값")
• 내 도구·스크립트의 결함과 수습 (감시 스크립트 오판, 구동 절차의 발췌 미첨부, 자동화의 승인 게이트 통과)
• 작업 회고·교훈 절 ("이번 작업의 핵심 요소", "X 가 Y 보다 낫다" 류 방법론 반성) — 단, 그 방법론 자체가 페이지의 선언된 주제이면 본문이다
• 재작업 판단 ("재계측 불요", "따라서 다시 재지 않았다"), 세션 진행 서사("지적을 받아", "확인 결과", "정직한 기록")

경계 (과잉 삭제 금지)

• 제품이 실제로 낸 실패·회귀와 그 근본 수정은 남긴다 — 시스템의 속성이다. 다만 서술은 "작업 중 터진 사고"가 아니라 "시스템의 결함 → 보강" 으로 쓴다.
• 문서의 배경·동기는 남기되, 대화 경위가 아니라 기준·문제 정의로 진술한다 ("~라는 지적을 받았다" ✗ → "기준은 ~이다" ✓).
• 수치의 해석에 필요한 주석은 남기되 원인이 작업 경위면 중립화한다 ("내가 정책을 고치느라 7분" ✗ → "파이프라인 외부 대기 7분 제외" ✓).
• 연구 기록의 실험 서사는 배제 대상이 아니다: /confluence-research-record의 동기→결과→해석→후속 서사는 연구 자체의 경위(=페이지의 선언된 주제)라 본문이다 — 이 룰이 배제하는 것은 세션 작업의 경위다.

§1-3. 최소 기록: 기본은 «없음» (MANDATORY, 2026-09-09 사용자 지시)

룰: 각 파트의 글머리 내용은 기본이 없음이다. 결론·판단 근거·부연을 파트마다 채우지 않는다. 그 파트를 읽는 사람이 모르면 판단·재현을 못 하는 것만 적는다.

Why: 글머리 전용 규칙은 형식(문단 대신 글머리)이지 분량 지시가 아닌데, 파트마다 결론과 판단 근거를 채우는 쪽으로 읽혔다. 페이지가 길어지면 훑기가 막혀 글머리를 쓰는 목적 자체가 사라진다. 2026-09-09 사용자 지적.

판정 (각 항목 쓰기 직전)

적용

• 파트에 필수 내용이 없으면 글머리를 만들지 않는다. 등록 양식의 필수 h1 은 골격 게이트 대상이라 제목만 남기고 아래를 억지로 채우지 않는다.
• 결론·판정의 근거 서술은 한 곳에서 한 번만 적는다(절 끝 panel 또는 판정 접기). 표의 판정 열 · 상태 로제 · 제목의 «(미승격)» 표기는 요약이라 중복이 아니다.
• 수치는 표가 정본이다. 표에 있는 값을 글머리로 다시 쓰지 않는다.
• 판단 근거는 페이지가 그것을 주제로 선언한 경우에만 본문이다. 그 밖에는 결과와 기준만 남긴다.
• 본문에는 판정·재현에 필수인 것만 남기고, 개념·정의 변경 설명 · 부속 표 · 발사 기록 · 해석 · 표 읽는 법 · 미승격 상세는 <details> 접기로 내린다.

자가 점검 (게시 직전 MANDATORY)

• 각 파트에서 줄을 하나씩 지워 보고, 지워도 독자가 같은 판단에 도달하는 줄은 지운 채로 게시한다.
• 남긴 줄마다 «이 줄이 없으면 무엇을 못 하는가»에 한 마디로 답할 수 있어야 한다.

고정 요소 (MANDATORY, 2026-09-09 사용자 지시)

• 최상단: 목차 매크로(data-extension-key="toc") → 📖 단어장 접기(<details><summary>📖 단어장 …</summary>) 순서를 반드시 둔다. 그 뒤에 첫 <h1> 이 온다.
• 최하단: 「출처」 접기(<details><summary>출처</summary>)를 본문 바로 뒤 최하단에 둔다(«관련 링크» 접기가 있으면 그것이 출처 아래 마지막 블록이다). 재현에 필요한 것만 글머리로 적는다(로그 · 체크포인트 · 데이터셋 경로 · 스크립트 · 설정 키 · 측정 도구 · 표본 · 비교 기준선. 경로는 <code>).
• 목차 · 단어장 · 출처 셋은 분량 최소화의 예외가 아니라 고정 자리다. 내용이 적어도 자리를 비우지 않는다.
• 실험 기록의 h1 은 배경 · 목적 및 가설 · 데이터 · 방법 · 결과 · 향후 및 리스크 여섯 개를 번호 없이 쓴다. 측정 보고는 번호 h1 을 쓴다.

§2. 페이지 구조 표준 (MANDATORY)

[목차 매크로]          ← 최상단 고정
[📖 단어장 접기]       ← 최상단 고정 (목차 바로 아래, §1-3)
[본문 내용]
[펼치기: 출처]         ← 최하단 고정
[펼치기: 관련 링크]    ← 최하단 고정 (출처 아래, 있을 때만)

아래 <ac:structured-macro> 는 storage 형식 표기다. contentFormat=html 로 쓰는 페이지는 같은 요소를 <details><summary>출처</summary>…</details> 로 넣는다.

목차 (TOC) — Atlassian 네이티브 /목차 기능 사용:

<ac:structured-macro ac:name="toc"/>

출처 펼치기:

<ac:structured-macro ac:name="expand">
  <ac:parameter ac:name="title">출처</ac:parameter>
  <ac:rich-text-body><ul><li>[컨텍스트]: [소스명] / [URL]</li></ul></ac:rich-text-body>
</ac:structured-macro>

관련 링크 펼치기 (출처 아래):

<ac:structured-macro ac:name="expand">
  <ac:parameter ac:name="title">관련 페이지 / 이슈</ac:parameter>
  <ac:rich-text-body><ul>
    <li>[Confluence 페이지 제목] — [URL]</li>
    <li>[Jira 이슈 키] [이슈 제목] — [URL]</li>
  </ul></ac:rich-text-body>
</ac:structured-macro>

§3. 페이지 수정 전 3단계 확인 (MANDATORY)

사전 확인 없이 Confluence 페이지를 수정하지 않는다.

① 업데이트 여부 확인:

업데이트할까요?
  내용: [변경 요약 1~2줄]
  대상: [페이지 제목] (ID: XXXXXXXXXX)

대상이 2페이지+ 또는 계층 수정이면 '내용' 대신 수정 계획 트리(배지 [수정]/[신규]/[삭제] + 10~20자 동사형 요약, 유지 항목 생략)로 보고 — 형식 정본: rules-lazy/answer-detail.md § 수정 계획 트리 보고.

② 관찰자 알림:

A) 알림 발송 (is_minor_edit=false)
B) 조용히 업데이트 (is_minor_edit=true)

③ 버전 설명:

버전 기록에 남길 설명을 입력해 주세요. (예: "실험 결과 3종 추가")

응답 수령 후 ④ 의 승인 질문을 거쳐 is_minor_edit과 version_comment 적용하여 업데이트 실행. ①②③ 을 사용자가 채팅으로 먼저 답한 경우에도 그 값으로 ④ 의 승인 줄을 만들어 AskUserQuestion 으로 다시 확인한다. 채팅 답은 승인 증거가 아니다.

④ 게시 승인 질문 (MANDATORY, 2026-10-06 사용자 결정, 2026-10-07 개정 1): 게시 직전에 main 은 AskUserQuestion 으로 승인 질문을 띄운다. 세 질문(업데이트 여부·알림·버전 설명)을 이 질문 하나에 담고, 질문 문자열에 아래 승인 줄을 정확히 한 줄 넣는다. 승인 줄은 아래 명령이 출력하며 그대로 붙여 쓴다. 보기에는 게시 승인 과 취소 를 둔다. 사용자가 게시 승인 을 고른 기록이 없으면 MCP 게시(skeleton-gate.sh)와 confluence_patch_page.py --apply 둘 다 막힌다. 2026-10-05 페이지 두 개가 «바꿔» 한 마디로 확인 없이 게시된 사고의 대책이며, 발화 인용 방식은 요청 발화로 세 질문을 건너뛸 수 있어 질문·답 기록으로 바꿨다.

# 승인 줄과 권장 보기를 출력만 한다(쓰기 없음). 기존 페이지는 --page 를 여러 번 쓸 수 있다
python3 ~/.claude/scripts/confluence_publish_approve.py question --page <ID> [--page <ID> ...] \
    --notify quiet|notify --message "<버전 설명>"
python3 ~/.claude/scripts/confluence_publish_approve.py question --new --space <spaceId> --parent <parentId> --title "<제목>"

승인 줄 형식은 아래와 같다.

게시 승인 요청 · page=<ID>[,<ID>...] · 알림=<notify|quiet> · 버전 설명=«<버전 설명>»
게시 승인 요청 · new · space=<spaceId> · parent=<parentId 또는 없음> · 제목=«<제목>»

• 승인으로 인정하는 것은 사용자가 보기 게시 승인 을 고른 답뿐이다. 취소 등 다른 보기, 자유 입력, subagent 기록, 질문과 결박되지 않은 답은 인정하지 않는다. 한 번에 질문 여러 개를 띄우면 질문마다 따로 판정한다.
• 승인 뒤 사용자가 같은 대화에 새 메시지를 보내면 그 승인은 무효가 된다(채팅으로 보류·변경을 말했을 수 있어서다). 그래서 답을 받은 그 턴에 게시한다. 도구 결과·알림·피어 메시지는 무효 사유가 아니다.
• 자유 입력란에 «게시 승인» 을 직접 쳐도 승인으로 본다(사용자 본인의 의사표시이기 때문이다).
• 대상·알림·버전 설명은 승인 줄에서 읽으며 게시 호출 값과 정확히 같아야 한다. 호출의 알림 선택(--minor 여부)과 버전 설명(MCP는 versionMessage)이 다르면 막힌다. 승인 줄과 다르게 게시하려면 새 승인 질문을 띄운다.
• 페이지 ID 는 숫자만 받는다. tiny link·URL 은 거부되므로 숫자 페이지 ID 로 다시 지정한다.
• 실제 유효 시간은 «사용자가 답한 시각부터 1시간»이다. 승인은 그 안에 한 번만 쓸 수 있고, 게시가 네트워크 오류로 실패해도 승인은 소모되어 새 승인 질문이 필요하다. 한 질문으로 여러 페이지를 승인할 수 있고 소모는 페이지마다 따로 한다.
• MCP updateConfluencePage 는 조용한 수정을 지정할 수 없어 알림 발송(notify) 승인만 통과한다. 조용한 수정은 confluence_patch_page.py --minor 로 한다.
• 승인은 세션 기록(~/.claude/projects/<프로젝트>/<세션id>.jsonl)에서 읽는다. 기록 형식이 바뀌면 승인을 찾지 못해 게시가 막힌다(막히는 쪽으로만 틀린다).

§4. 수식 표기 기준 (MANDATORY)

금지: $$...$$, \(...\), \[...\] 등 raw LaTeX — Confluence에서 렌더링 불가.

권장 방식 (우선순위):

1순위 — Atlassian LaTeX 매크로 (Math/LaTeX 플러그인 설치 시):

<ac:structured-macro ac:name="latex">
  <ac:plain-text-body><![CDATA[\Delta W = \sum_i g_i \cdot B_i A_i]]></ac:plain-text-body>
</ac:structured-macro>

2순위 — Unicode 수학 기호: ΔW = Σᵢ gᵢ(x, rᵢ) · Bᵢ·Aᵢ

3순위 — 코드 블록(monospace): 복잡 수식, 플러그인 없을 때

수식 삽입 전 Math/LaTeX 매크로 설치 여부 사용자 확인 필수.

§5. 페이지 너비 (MANDATORY)

모든 페이지 너비는 항상 최대:

<ac:layout>
  <ac:layout-section ac:type="full-width">
    <ac:layout-cell>[본문]</ac:layout-cell>
  </ac:layout-section>
</ac:layout>

테이블: <table style="width: 100%;"> 적용. 업데이트 후 안내: "페이지 우상단 ⋯ → 페이지 너비 → 최대 설정 필요"

§6. 페이지 밀도 (MANDATORY)

모든 페이지 밀도는 압축 밀도(Compact) — UI 수동 설정 필요. 업데이트 후 안내: "페이지 우상단 ⋯ → 밀도 → 압축 밀도 설정 필요"

3대 레이아웃 기준:

§6-1. 한국어 문체 점검 (게시 전 MANDATORY — 2026-08-05 제정 · 2026-08-10 자동화)

게시 직전 본문을 점검기로 돌리고 히트를 재작성한 뒤 게시한다. 눈으로 훑는 방식은 2026-08-10에 4개 페이지 83건 미검출로 실패했으므로 기계 판정이 정본이다.

python3 ~/.claude/scripts/korean_style_check.py <저장형식 파일>   # 차단 0건이어야 게시

검사 3종 — ① 산문 문장 안 삽입 대시(차단) ② 쉼표 2개 이상 문장(경고) ③ 영문 토큰 뒤 조사(경고). 제목·캡션·범례의 구분 대시는 콜론으로 바꾼다(차단 대상).

두 게시 경로 모두 자동 차단이 걸려 있어 우회되지 않는다 — MCP updateConfluencePage·createConfluencePage는 PreToolUse hook(scripts/korean-style-gate.sh), 스크립트 경로는 confluence_patch_page.py 내부 게이트(치환 전후 비교)다. 규칙 정본: rules-lazy/answer-detail.md § 한국어 문체 (적용 경계·대체 규칙·조사 판정 포함 — 표 셀·**라벨** — 설명 불릿은 예외).

§7. Storage Format 무결성 검증 (MANDATORY — 기존 페이지 수정 시)

MCP getConfluencePage(claude_ai_Atlassian)로 가져온 storage HTML이 JSON 다중 직렬화로 매크로 속성 따옴표가 깨지는 현상 (2026-03-03, 3,625건)

증상: 모든 매크로(toc, expand 등) "확장 기능 로드 오류" 원인: ac:name="toc" → ac:name='\"toc\"' 이중 변환 수정: ~/.claude/scripts/fix_confluence_html.py — fix_corrupt_macro_attrs() 사용

예방 (MANDATORY): 기존 storage HTML 가져와 수정 후 올리는 경우:

1. ='\" 패턴 존재 확인 → 발견 시 fix_corrupt_macro_attrs() 적용 후 업로드
2. 신규 HTML 직접 작성 시는 해당 없음

§8. ADF Math Block 백슬래시 무결성 검증 (MANDATORY — 기존 페이지 수정 시)

storage HTML의 ADF 수식 블록 body에서 \command → \\command 이중 변환 현상 (2026-03-03, 42건)

증상: 수식 블록이 \\mathcal{L} 등 raw 텍스트 표시 적용 대상: Atlassian Marketplace "LaTex Math Block" (Forge 앱) 수정: fix_confluence_html.py — fix_adf_formula_backslash() 사용

§9. ADF Math Block 리터럴 \n 무결성 검증 (MANDATORY — 기존 페이지 수정 시)

body 파라미터에 리터럴 \n (0x5C+0x6E) 두 문자 포함 현상 (2026-03-03, 10건)

증상: 수식 블록 앞뒤 불필요한 빈 줄 렌더링 원인: JSON 직렬화 시 실제 개행(0x0A)이 아닌 두 문자로 저장 → strip() 무효 수정: fix_confluence_html.py — fix_adf_formula_literal_newlines() 사용

적용 순서 (MANDATORY): fix_corrupt_macro_attrs() → fix_adf_formula_backslash() → fix_adf_formula_literal_newlines() — 또는 fix_all() 일괄 호출

§10. 기존 페이지 수정 = 최소 치환 (media·매크로 보존) (MANDATORY — 2026-07-22)

신규 작성이 아닌 "수정"일 때는 본문을 재생성하지 않는다. 이미지·첨부(media 노드)와 매크로는 본문 HTML에 불투명 ID(data-id·data-collection·data-media-id·data-local-id)로만 참조된다. 본문을 손으로 다시 쓰거나 markdown ↔ html 왕복 변환하면 이 ID가 유실돼 이미지가 통째로 사라지고 매크로가 깨진다. ★근거 이식(2026-07 실측): 본문 재생성 시 첨부 이미지 전멸, 큰 본문 수기 이관 중 표 셀 누락·행 소실이 수 차례 발생. 반대로 원문 verbatim + 목표 셀만 리터럴 치환하면 media ID가 그대로 되돌아가 기존 이미지가 보존된다.

수정 프로토콜 (MANDATORY):

1. getConfluencePage(contentFormat="html")로 원문을 받아 파일에 verbatim 저장 — 엔티티(<·&·")·태그 순서·공백·이모지 불변, 저장 길이를 원문과 대조(다르면 중단). 저장 위치는 임시 폴더 규약(code-execution.md). 1.5. §7~§9 손상 패턴 선점검 (2026-07-22 보완): 저장본에서 ='\"(따옴표 깨짐, §7)·\\command(이중 백슬래시, §8)·리터럴 \n(§9) 패턴을 점검 — 발견 시 fix_confluence_html.py fix_all() 적용본을 이후 단계의 baseline으로 삼는다(길이 대조 기준도 fix본으로 갱신). 손상은 조건부 발생(2026-03 3,625건 vs 2026-07 무손상 왕복)이라 점검이 싸고 생략이 위험하다 — 손상 원문을 verbatim 재업로드하면 손상이 그대로 재기록된다.
2. 리터럴 문자열 치환만 수행. 바꿀 각 앵커가 원문에서 정확히 1건(count==1) 인지 assert — 0건/2건 이상이면 중단하고 앵커를 앞뒤 문맥까지 확장해 유일화. 정규식보다 리터럴 우선. (Edit 도구로 저장 파일을 고치면 old_string 유일성 요구가 count==1을 자연 집행한다.)
3. 치환 전후 <table>/<tr>/<td>·media 노드 개수를 대조 — 목표 외 증감 시 중단(아무것도 쓰지 않음). 부분 적용된 페이지가 가장 위험.
4. 통과 시에만 updateConfluencePage에 전체 본문 그대로(치환분만 반영) 전송 → 재조회로 반영·인접 문단 무손상 확인.

금지: 수정 시 본문 전체 재작성 / markdown으로 받아 편집 후 html 재삽입 / media·매크로 노드 ID 임의 생성·삭제 / 큰 본문을 손으로 옮겨 담기(전사 오류·매크로 유실 원인).

경계: 이 규칙은 수정(update) 전용. 신규 페이지 생성(§1~§6)에는 적용 안 됨. 또 이미지 blob 자체 교체는 MCP 불가 → 그림 내용이 바뀌면 참조 보존까지만 되고 사용자 수동 drag-drop이 필요하다(값만 바뀐 표와 옛 그림이 공존할 수 있으니 교체 안내 필수).

§10-1. 대형 페이지 수정 = REST 직접 패치 (본문을 모델에 통과시키지 않는다) (MANDATORY — 2026-08-05)

§10을 지키려 해도 본문이 크면 MCP로는 물리적으로 불가능하다. Confluence는 부분 수정 API가 없어 본문 전체를 되보내야 하는데(빈 body는 페이지를 백지로 만든다 — confluence-update-empty-body-wipes), 모델이 그 본문을 출력해야 하므로 본문 크기 = 출력 토큰이 된다. 실측(2026-08-05): 저장 형식 본문 56,363자 = 약 4.8만 토큰 → 1턴 전송 한도 초과. 잘린 채 전송되면 잘린 본문이 그대로 저장된다.

트리거: 본문 3만 자 이상, 또는 MCP getConfluencePage가 토큰 초과로 파일 저장으로 떨어질 때.

도구: ~/.claude/scripts/confluence_patch_page.py (Confluence REST v2 직접). 본문은 서버↔스크립트만 오가고 모델은 치환 규칙만 만든다 — 왕복 약 10만 토큰이 0이 되고, 잘림에 의한 손상이 구조적으로 불가능해진다.

자격증명: ~/.atlassian_token (chmod 600, 1줄=이메일 / 2줄=토큰). Atlassian 계정 API 토큰이어야 한다(id.atlassian.com) — Bitbucket 전용 토큰·구 app password는 Confluence에서 거부된다. 토큰을 명령줄·대화에 쓰지 않는 이유: 셸 히스토리·ps 출력·대화 로그에 남는다.

절차

1. --probe "문구" — 저장 형식 원문을 눈으로 확인(읽기 전용, 원본 자동 백업). 앵커를 추정으로 짓지 않는다.
2. 치환 목록 JSON 작성 [{"label","anchor","new"}] — 새 내용도 저장 형식으로 쓴다.
3. --patches (플래그 없음) = dry-run — 앵커 count==1 전수 검사, 하나라도 어긋나면 아무것도 쓰지 않음.
4. --apply — 적용. 적용 전 본문이 outputs/confluence_backup_{id}_v{n}_{시각}.storage.html로 저장된다.
5. 적용 후 검증(MANDATORY): 백업본과 <table>·<tr>·ac:structured-macro·expand·adf panel·ac:link·ri:attachment 개수를 기계 대조 — 하나라도 줄면 소실이므로 백업 복구.

★저장 형식 ≠ MCP가 보여 주는 HTML (실측 차이 — 이걸 모르면 앵커가 전부 빗나간다)

함정: ckpt·본문 대조 시 학습으로 변하는 값을 섞지 말 것 — 같은 원리의 사고를 이 날 실측했다(사영층 동일성 비교에 BatchNorm num_batches_tracked가 섞여 "최대 절대차 1792"가 나왔고, 그 1792는 에폭당 배치 수였다). 비교 대상에서 통계 버퍼를 빼자 36개 텐서 전부 완전 일치.

★골격 스탬프는 «살아 있는 본문 + 이번 치환» 에 찍는다 (MANDATORY — 2026-09-09 실측, 두 번 막힘)

--apply 는 게시할 본문의 sha256 으로 골격 대조 스탬프를 찾는다. 그런데 Confluence 는 저장할 때 storage 를 조금 정규화한다(실측: 내가 만든 54,351자 → 서버 보관본 54,374자). 그래서 «직전에 내가 만든 로컬 본문» 에 스탬프를 찍으면 해시가 어긋나 게시가 막힌다. 같은 페이지를 연속으로 두 번 고칠 때 반드시 걸린다.

1. 매 치환 직전에 --backup-dir 만 주고 한 번 돌려 살아 있는 본문을 새로 받는다(치환 목록 없이 = 읽기 전용).
2. 그 본문에 치환을 로컬로 적용해 «게시될 본문» 파일을 만든다.
3. 그 파일에 confluence_skeleton_check.py 를 돌려 스탬프를 찍는다.
4. --apply 로 게시한다.

헤딩(h1·h2) 구조를 바꾸지 않는 리터럴 치환이면 --base <방금 받은 원본> 을 붙여 골격 검사를 건너뛰고 스탬프만 받을 수 있다. 같은 파일을 --base 로 주는 자기선언은 스크립트가 막는다.

★중첩 목록 앵커는 비탐욕 정규식으로 못 잡는다 (2026-09-09 실측)

<ul>.*?</ul> 는 중첩된 목록에서 안쪽 </ul> 에서 멈춘다. 그래서 41개 항목짜리 블록을 앵커로 잡으려다 6개짜리 안쪽 목록만 잡혔다. 여는 태그를 세어 짝을 맞춰야 한다.

def balanced_ul(text, frm):
    s = text.find('<ul>', frm); depth = 0
    for t in re.finditer(r'<ul>|</ul>', text[s:]):
        depth += 1 if t.group(0) == '<ul>' else -1
        if depth == 0:
            return text[s:s + t.end()]

같은 이유로 바깥 <li> 를 앵커로 쓸 때도 <li>(?:(?!<li).)*?</li> 처럼 중첩을 배제하는 형태를 쓰거나 짝맞춤을 해야 한다.

§11. 그림에서 읽은 주장은 수치로 바꾼 뒤 게시한다 (MANDATORY — 2026-08-12 실측 사고)

Confluence에 "그림을 보니 A가 B와 다르다"는 관찰을 실을 때, 그림을 눈으로 본 것만으로 문장을 쓰지 않는다. 같은 관찰을 재는 수치를 먼저 만들고 그 수치를 본문에 넣는다.

왜 (판단 근거 이식)

• 이미지 Read 결과는 다음 턴에 남지 않는다. 검증하려고 PNG를 Read해도 그 내용은 대화에 보존되지 않아, 여러 턴에 걸친 작업에서는 "봤다"는 사실만 남고 근거가 사라진다. 게시 문장을 뒷받침할 것이 없어진다.
• 기존 지표가 그 현상에 눈이 멀어 있을 수 있다. 예: 진단이 무게중심만 쓰면, 무게중심은 1차 모멘트라 "한 곳이 밝다"와 "양쪽이 밝고 평균이 가운데다"를 구분하지 못한다. 그림에 보이는 양측성이 표에는 잡히지 않고, 지표를 바꾸면(따뜻한 색 비중의 좌우 분배) 갈린다.
• 즉 "표에 안 잡혔다"가 "현상이 없다"가 아니다. 그림이 지표보다 앞설 때가 있고, 그때 할 일은 그림을 인용하는 것이 아니라 그 현상을 재는 새 지표를 만드는 것이다.

절차

1. 그림에서 관찰을 말로 적는다 (예: "어텐션을 켜면 등급과 무관하게 양쪽 구획이 모두 밝다").
2. 그 관찰을 가르는 스칼라를 정의한다 (예: 약한 쪽 절반의 열 비중 = 양측성).
3. 렌더된 그림에서 재야 한다면 색 규약을 감안한다 — jet/turbo 계열은 차가운 영역까지 전부 칠하므로 채도로 재면 배경 색칠이 섞인다. 따뜻한 색만(예: R − B > 0.25) 세야 상위 활성이 잡힌다.
4. 수치가 관찰과 같은 방향이면 수치를 본문에 쓰고 그림은 근거로 첨부한다. 어긋나면 게시하지 않고 왜 어긋나는지 먼저 가른다.
5. 표본이 적으면(예: 판당 3장) 본문에 표본 수와 대리 지표임을 함께 적는다.

이미지 첨부

MCP로 실첨부는 불가하다. 본문에는 자리(캡션 + 자리표시 문단)만 만들고 파일 경로를 적어 수동 drag-drop 하게 한다 (README § figure 보존과 동일).

Jira 작업 참조

Jira 커밋 연결, 이슈 댓글, 이슈 완료 처리 → /commit 스킬 참조 (댓글 작성·수정은 REST: /commit § Jira 댓글 쓰기·고치기 = REST)

§ QMD (.qmd) 입력 지원

상세: agents/docs.md § Quarto Markdown (.qmd) 처리 참조

트리거

사용자가 .md 대신 .qmd 파일 경로 제공 시:

1. docs 에이전트로 위임 — quarto render 변환 흐름 진입
2. 변환 결과(.confluence 또는 HTML)를 본 스킬의 페이지 생성/수정 흐름에 입력
3. 페이지 footer에 .qmd 원본 경로 명시 (재현성)

일반 .md vs .qmd 분기

• .md: 본 스킬 기존 흐름 (직접 페이지 생성)
• .qmd: docs 에이전트 quarto render 경유 → 본 스킬에 결과 전달

의존성

quarto CLI 필요 — docs 에이전트가 사전 점검 + 안내

§12. 전수 감사 시 커버리지 근거 (MANDATORY — 2026-08-21)

• 커버리지 근거는 대상 페이지 전문 grep이다. CQL 히트 수는 보조 발견 수단일 뿐 커버리지 증거가 아니다. 한국어 조사 결합 때문에 실제 해당 문구를 담은 페이지가 text ~ "..." 결과에서 누락된다(실측 2026-08-21).
• 절차: ① 대상 집합을 인덱스 링크·하위 트리·CQL로 모은 뒤 ② 전 페이지 storage 본문을 내려받아 태그 제거 텍스트에 패턴을 돌리고 ③ 보고서 커버리지 절 첫 줄에 "커버리지 근거 = N페이지 전문 grep, CQL은 발견 보조"를 명시한다.
• 치환 적용 시: 평문 before는 storage에서 강조 태그·엔티티(··×·—)로 갈라져 매칭이 빗나간다 — storage 원문 조각을 먼저 확인해 storage 정확 문자열로 치환하고, 같은 문장이 패널·본문에 중복되면 페이지 1회 업데이트 안에서 전체 치환(first-match 금지)한다.
• 전수 열거를 기준선으로 먼저 만든 뒤 제안을 쓴다 (MANDATORY). "고칠 문장"부터 찾으면 같은 숫자·같은 문구의 다른 등장을 놓친다(2026-08-21 실측 2회: 1차 §1 99.4~99.7% 누락, 2차 24/24 2곳·1페이지 누락). 절차: 대상 토큰(숫자·문구)을 전 페이지 본문에서 전부 열거한 표를 먼저 만들고, 각 행에 수정/OK 판정을 붙인 것이 제안서다. 적용 후 잔존 검색도 같은 전수 표로 한다.
• 제목 변경이 포함되면 제목 링크(ri:content-title)를 전 페이지 storage에서 찾아 같은 배치에서 직접 치환한다. 렌더된 pageId URL은 storage 구조의 근거가 아니다(제목 링크도 URL로 렌더됨). 적용은 제목 변경 → 각 페이지 PUT 직전 fresh fetch → 치환 순서로 하고, 구 제목 속성이 이미 0건이면 자동 갱신된 것이므로 그 실측을 보고에 남긴다(rename 이전 스냅샷으로 PUT하면 자동 갱신분까지 덮어쓴다).