사내 매체 연동 가이드 (internal-doc-tools)

정원 바깥의 사내 매체와 manuscript 사이에 놓인 다리. 이 다리를 건너는 규칙을 적는다.

무엇이 들어왔는가

internal-doc-tools 스킬(영입판 v1.3.0)이 사내 문서 작업용 외부 시스템 4종을 의존성 0(Node.js 18+ 내장 fetch) 단일 파일 스크립트로 묶어 들여왔다.

능력	방향	스크립트	시크릿	이 정원에서의 쓰임
Notion API	읽기·쓰기	notion.mjs	.secret/notion.json	주력 — 게시 원고 미러(쓰기) + 사내 문서 영입(읽기)
Confluence	읽기·쓰기	confluence.mjs	.secret/confluence.json	보조 — 영입 소스로 가능, 미러는 열어둠(주력 아님)
Jira (read-only)	읽기	jira.mjs	.secret/confluence.json 재사용	보조 — 글의 소재·근거 조회(사례/통계)
이미지 생성 (gpt-image-2)	생성	image-gen.mjs	.secret/openai.json	기존 image-gen 스킬과 중복 — 보조 경로

스크립트 경로 접두사: .claude/skills/internal-doc-tools/scripts/. 능력별 상세는 각 스킬의 references/{confluence,notion,jira,image-generation}.md.

활성화 게이트 (가장 먼저 확인)

이 스킬은 현재 세션에서 /internal-doc-tools 슬래시 명령이 한 번이라도 실행된 경우에만 동작한다.

• 게이트가 닫힌 세션에서는 "노션에 올려", "컨플런스 미러링" 같은 입력이 들어와도 스킬이 발동하지 않는다 — 다른 Notion MCP와의 충돌 방지용 명시적 게이트.
• 연락관([[internal-liaison]])이 미러/영입을 수행하기 전, 게이트 상태가 모호하면 먼저 묻는다: "/internal-doc-tools 로 활성화하신 상태인가요?"

시크릿 보관 규칙

모든 시크릿은 .secret/ 디렉터리에서 읽는다. 종류별 한 파일.

능력	실키 (비커밋)	템플릿 (커밋)
Notion	.secret/notion.json (워크스페이스별 notion-<slug>.json 가능)	.secret/notion.json.tmp
Confluence / Jira	.secret/confluence.json (Jira는 같은 파일 재사용)	.secret/confluence.json.tmp
이미지	.secret/openai.json	.secret/openai.json.tmp

• .gitignore 규칙: /.secret/*.json 차단, .tmp는 추적 가능. 실키는 절대 커밋되지 않는다.
• 시크릿이 없으면 각 스크립트가 "템플릿 복사 후 채우라" 안내를 띄우고 종료 — 그 안내를 그대로 사용자에게 전달한다.
• Notion 권한: Internal Integration은 워크스페이스 단위 발급 + 페이지마다 별도 공유(... → + Add connections)가 필요하다. 이게 빠지면 404.

두 방향의 원칙

이 다리는 한 방향이 아니다. 영입(읽기) 과 미러(쓰기) 는 흐름도 책임도 다르다.

        영입 (Ingest, 읽기)
사내 매체  ───────────────▶  draft/ → manuscript/   (Type 3 진입)
(Notion/Confluence)            └ 사람·편집장이 정식 원고로 다듬음

        미러 (Syndicate, 쓰기)
manuscript/ (published)  ───────────────▶  Notion 페이지/DB
   └ 단일 출처(canonical)        └ 파생본(derivative), 읽기 전용 사본

단일 출처 규칙 (canonical source)

manuscript/ 가 진실의 단일 출처다. 사내 매체의 사본은 파생본이다.

• 미러는 단방향: manuscript → Notion. 미러된 Notion 페이지를 사람이 수정해도 그 변경은 manuscript로 되돌아오지 않는다. 원고 수정은 항상 manuscript에서, [[publication-pipeline]] Type 4(이슈 기반 리비전)로.
• 미러는 멱등: 같은 글을 두 번 미러하면 새 페이지가 생기지 않고 기존 페이지가 갱신되어야 한다(upsert). Notion은 제목/식별자 기준으로 기존 페이지를 찾아 덮어쓴다.
• 미러 표식: 미러된 페이지 상단에 "이 문서는 자동 미러본입니다 — 원본은 <사이트 URL>" 콜아웃을 남겨, 사내 독자가 사본을 원본으로 오인하지 않게 한다.
• published 만 미러: draft/review 상태 원고는 미러하지 않는다. 사이트 게시(MANUSCRIPT_STATUS_FILTER=published)와 같은 기준.

영입 시 주의

• 영입은 소재 수집이지 자동 게시가 아니다. fetch한 사내 문서는 draft/<slug>.md 자리에 떨어뜨리고, 거기서부터 [[manuscript-architect]] 가 Type 1 흐름(Stage 1~)으로 정식 원고화한다.
• 사내 고유 식별자(내부 URL, 사번, 비공개 프로젝트명)는 영입 단계에서 걸러낸다 — 발행물은 Pages로 공개될 수 있다.
• Notion 읽기 폴백: 영입판 notion.mjs get이 권한 미공유로 404면, MCP notion-fetch로 폴백하고 "MCP 폴백으로 읽음"을 한 줄 보고한다. 쓰기(미러)는 폴백하지 않는다 — 통합 봇 명의의 멱등 동작 보장.

Notion 명령 빠른 참조

작업	명령 (node .../notion.mjs ...)
인증 점검	check [--config <path>]
검색	search "<query>"
페이지 조회	get <id> (실패 시 MCP 폴백)
페이지 생성	create-page ... (폴백 금지)
블록 추가	append ...
DB 쿼리	query-db <dbId>
행 생성	create-row <dbId> --props <json>
DB 생성	create-db --parent <pageId> --schema <json> [--inline]
대량 행 적재	bulk-create-rows --db <dbId> --rows-file <p> (429 재시도 내장)

지원 변환: MD 제목/단락/볼드·이탤릭·코드/펜스 코드블록(언어 매핑)/리스트/인용/수평선/링크/[[wiki]] 평문화. callout/toggle 등 복잡 블록은 blocks JSON 직접 작성.

정형 다이어그램 정책 (이미지 생성과 공유)

internal-doc-tools의 이미지 생성도 [[doc-clarity-principles]] 의 원칙을 따른다: 시퀀스/관계/플로우 같은 정형 다이어그램은 이미지로 만들지 않고 mermaid로 작성한다(도메인 사실 왜곡 위험). 이미지는 타이틀 카드·일러스트·배너 같은 보조 시각자료에만. 기존 image-gen 스킬과 능력이 겹치므로, 원고용 이미지는 [[publication-pipeline]] Stage 2의 기존 경로를 우선한다.

트러블슈팅

증상	진단	조치
스킬이 트리거에 반응 안 함	활성화 게이트 닫힘	/internal-doc-tools 선행 실행 안내
Notion 404 (읽기)	페이지 미공유	+ Add connections 안내 → 그래도 안 되면 MCP 폴백
Notion 404 (쓰기)	통합 권한 미공유	권한 안내만. MCP 폴백 금지
미러 시 중복 페이지 생성	upsert 키 미스매치	제목/식별자 기준 기존 페이지 탐색 로직 확인
시크릿 없음 안내 후 멈춤	.secret/*.json 미생성	템플릿 복사 + 토큰 채움 안내 그대로 전달

채택 의사결정 기록

결정	이유
주력 매체 = Notion (양방향)	블룸AI 내부 문서 운영 매체. 영입·미러 모두 Notion 중심
Confluence/Jira 쓰기는 열어두되 비주력	능력은 있으나 사용 사례 미발생. 두 번째 사례 누적 시 연락관 모드 추가
manuscript 단일 출처 고정	사내 사본이 원본을 덮어쓰면 진실이 둘이 된다. 미러는 단방향 파생본
미러는 published 만	사이트 게시 기준과 일치. 미완성 원고가 사내에 새는 것 방지