1인 사업가 생산성 키트 — 직원 없이 58개를 자동화했고, 그중 바로 쓸 수 있는 AI 에이전트 스킬 38개

version
1.1.0
GitHub stars
448

Install

/plugin install solo-skills@bam-bam-2

Run it inside Claude Code after adding the marketplace with /plugin marketplace add bam-bam-2/solo-skills.

Contents

Discovered from source

Skills 26

마크다운 → 진짜 책 PDF/EPUB

일반 page.pdf() + 마크다운→HTML 변환만으로는 "리포트를 인쇄한 것"처럼 보인다. 실제 책이려면 최소 이 6가지가 있어야 한다: 표지(풀블리드) · 타이틀 페이지 · 판권 페이지 · 실제 쪽번호가 달린 목차 · 장 시작마다 새 페이지 · 쪽마다 러닝헤더/쪽번호.

이 스킬은 Paged.js(MIT, https://unpkg.com/pagedjs/dist/paged.polyfill.js)를 브라우저에 스크립트 태그로 로드해 CSS Paged Media 기능(러닝헤더, 목차 쪽번호 자동생성)을 구현한다. Chromium이 네이티브로 지원 안 하는 기능이라 이 폴리필이 필요하다.

이 환경(Aside REPL)의 알려진 함정

  1. page.pdf({width, height}) 파라미터가 무시된다. 항상 US Letter로 나온다. 반드시 preferCSSPageSize: true를 주고 CSS @page { size: 148mm 210mm; }로 크기를 지정할 것. format: 'A5' 같은 심볼릭 사이즈도 마찬가지로 무시되니 쓰지 말 것.
  2. page.setViewportSize()가 없다. 뷰포트 크기를 못 바꾸므로 표지 등 개별 이미지를 만들 때 page.screenshot({fullPage:true})로 큰 캔버스를 찍으면 타일링 버그가 난다. 대신 page.pdf() + pdftoppm으로 원하는 크기를 렌더링할 것.
  3. page.addScriptTag()가 없다. 외부 스크립트(Paged.js 등)는 document.write()로 쓰는 HTML 문자열 안에 <script src="https://unpkg.com/..."> 태그를 직접 넣어야 로드된다.
  4. 구글 폰트 @import/<link>가 document.write() 직후엔 타이밍 문제로 반영 안 될 때가 있다. 커스텀 세리프 폰트를 꼭 써야 하면 woff2를 직접 fetch해서 base64로 인라인 @font-face에 박아넣을 것. 급하면 시스템 폰트(-apple-system, 'Apple SD Gothic Neo')로 타협.
  5. target-counter()로 목차 쪽번호를 만들 때 한글 슬러그 id가 깨질 수 있다. pandoc이 자동 생성하는 id="1장-시작과-실패" 같은 한글 id 대신 ch-01, part-1, app-a 같은 ASCII id로 바꿔서 앵커를 걸 것.
  6. CSS page: (named page) 속성을 제목 요소에만 주고 바로 다음 형제 요소에는 안 주면, 그 둘 사이에 강제 페이지베이크가 생긴다. 단순히 break-before: page로 장/부 시작만 제어하고 싶을 때는 page: main; 같은 명명 페이지 지정을 쓰지 말거나, 쓴다면 본문 전체에 동일하게 적용해야 한다 — 이건 "장 제목 바로 뒤에 이미지를 넣었는데 이미지가 다음 페이지로 밀리며 압도적인 빈 공백 페이지가 생기는" 증상으로 나타난다. 페이지 구성이 이상하면 가장 먼저 이 속성부터 의심할 것.
  7. 트림 사이즈로 A5(148x210mm)를 쓰지 말 것. A5와 A4는 비율이 동일해(1:1.414, ISO 시리즈) 화면에서 보면 "작은 A4 문서"처럼 보인다. 한국 단행본 표준판형인 **신국판(152x225mm, 비율 1:1.48)**을 쓰면 "진짜 책" 느낌이 명확하게 산다.
  8. Paged.js 렌더링은 비동기라 완료 시점을 폴링해야 한다. document.querySelectorAll('.pagedjs_page').length가 N초 연속 안 바뀔 때까지 기다린 다음 page.pdf()를 호출할 것. 문서가 크면(80150쪽) 완료까지 30초1분 걸릴 수 있다.
  9. page.pdf()는 가로 flexbox를 통째로 날려버린다. display:flex로 카드 3장을 나란히 놓으면 화면(스크린샷)에서는 멀쩡한데 PDF 출력에서는 그 영역이 통째로 빈칸으로 나온다. 세로 방향(flex-direction:column)은 정상. <table>로 바꿔도 안 되니, 가로 배치가 필요하면 **display:inline-block + vertical-align:middle**로 짤 것. 이건 Paged.js와 무관하게 일반 page.pdf()에서도 발생한다.
  10. page.screenshot({clip})은 뷰포트(1440x900)를 넘는 영역을 못 찍는다. 세로 1600px짜리 썸네일을 clip으로 찍으면 900px 아래는 잘리고, 여러 번 찍으면 같은 이미지가 반복되거나 내용이 누락된다. setViewportSize()도 없으므로(함정 2), 큰 이미지는 무조건 page.pdf() + pdftoppm 경유로 만든다.
  11. document.write()를 반복 호출하면 이전 문서가 남아 중복 렌더링된다. 한 탭에서 여러 이미지를 연속으로 뽑을 때 결과물이 세로로 두 번 반복되거나 MD5가 전부 동일하게 나오면 이 증상이다. HTML을 파일로 쓰고 page.goto('file://<절대경로>')로 여는 방식이 안전하다 — file://은 이 환경에서 정상 동작하고, 매번 완전히 새 문서가 로드된다.
  12. document.write()로 넣은 스크립트에서 top-level const로 선언한 값이 나중 스크립트에서 안 보일 때가 있다. 렌더 함수를 window.render처럼 전역에 붙여도 데이터가 undefined로 잡히면, 스크립트를 쪼개지 말고 변형별로 완성된 HTML을 통째로 만들어 각각 파일로 저장할 것.

절차

  1. 원고를 pandoc으로 HTML 변환: pandoc manuscript.md -f markdown -t html5 --wrap=none -o body_raw.html. \newpage 같은 LaTeX 지시자는 HTML에서 무시되니 CSS break-before로 대체한다.
  2. 제목(h1/h2)에 ASCII id를 다시 부여하면서 장/부 디바이더 구조로 감싼다 (예: <h1> → <div class="part-divider" data-run="PART 1. ...">). 이때 원본 문서에 등장하는 순서를 한 번의 스캔으로 그대로 따라가는 배열을 만들어 목차 데이터로 쓴다 — h1 전체를 먼저 훑고 h2 전체를 나중에 훑는 식으로 두 번 나눠 처리하면 목차 순서가 깨진다(장이 전부 나온 뒤 부가 나오는 식).
  3. 목차 HTML은 <a class="toc-entry" href="#ch-01">...</a> 형태로, CSS에서 .toc-entry::after { content: target-counter(attr(href url), page); }로 쪽번호를 자동 채운다.
  4. 러닝헤더: 장/부 요소에 string-set: runninghead attr(data-run);, @page의 @top-center { content: string(runninghead); }로 받는다.
  5. 표지는 별도 @page cover { margin:0; } + page: cover;로 풀블리드, 그 외 프론트매터(타이틀/판권/목차)는 쪽번호·러닝헤더를 끈 @page front로 분리한다.
  6. Paged.js 로드 + 렌더 대기 + PDF 출력:
    const html = `<!DOCTYPE html><html><head>
      <script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
      <style>${css}</style></head><body>${frontMatter}${bodyContent}</body></html>`;
    await page.evaluate((h) => { document.open(); document.write(h); document.close(); }, html);
    // 안정화 폴링
    let last = -1, stable = 0;
    for (let i = 0; i < 60; i++) {
      await sleep(1000);
      const n = await page.evaluate(() => document.querySelectorAll('.pagedjs_page').length);
      if (n === last) { if (++stable >= 3) break; } else stable = 0;
      last = n;
    }
    const pdf = await page.pdf({ printBackground: true, preferCSSPageSize: true });
    
  7. 검수는 aside.pdf.renderPages()로 표지/타이틀/판권/목차/본문 몇 쪽을 실제로 렌더링해서 눈으로 확인한다. pdfinfo로 최종 Page size가 의도한 트림 사이즈(A5 등)인지 꼭 재확인한다 (함정 1번 재발 여부 체크).
  8. EPUB은 별도로 pandoc이 이미 잘 만든다: pandoc manuscript.md -t epub3 --css=epub.css --epub-cover-image=cover.jpg --toc --toc-depth=2 -o book.epub. EPUB은 리플로우 포맷이라 쪽번호/러닝헤더 개념이 없고 nav.xhtml 목차만 있으면 충분하다.

어색한 쪽 분리(내용이 잘려서 다음 페이지로 넘어가는 현상) 방지

표/인용문/코드블록이 문장 중간에서 맥려서 다음 페이지로 이어지는 건 CSS에 깨짐 방지 규칙이 없어서다. 다음을 기본값으로 넣을 것:

p { orphans: 3; widows: 3; }
table, blockquote, pre, img, figure { break-inside: avoid; page-break-inside: avoid; }
h2, h3 { break-after: avoid; page-break-after: avoid; } /* 소제목이 페이지 맨아래 혼자 남지 않게 */

이렇게 하면 문단/표/인용문이 한 페이지에 다 안 들어갈 때 그 블록 전체가 다음 페이지로 밀린다(사용자가 "앞 단락을 뒤로 밀어버려라"라고 표현하는 바로 그 동작). 부작용으로 강제 페이지보맜(장 시작 직전) 앞에 짧은 내용만 단독으로 낙은 거의-빈 페이지가 가끔 생기는데, 이건 실제 책에서도 흔한 자연스러운 현상이라 문제가 아니다. 적용 후반드시 처음부터 끝까지 순차적으로 모든 페이지를 렌더링해서 육안으로 확인할 것 — 하나만 집어서 보고 넘어가면 높은 확률로 놓친다.

flexbox를 부/장 오프너에 쓰지 말 것

제목+삽화를 한 덩어리로 묶어서 같은 페이지에 있게 하려고 display:flex를 쓨다면, Paged.js가 flex 컨테이너 내부 높이 계산을 제대로 못 해서 예상과 달리 자식 요소가 다음 페이지로 통째로 밀려나간다 (제목만 남고 삽화는 혼자 다음 장으로 가는 식). 한 페이지에 여러 요소를 묶을 때는 평범한 블록 흐름(margin/padding)만으로 레이아웃하고 flexbox/grid는 피할 것. 또한 제목과 그 바로 뒤에 오는 이미지 문단을 따로 처리하지 말고, 한 번의 정규식으로 단락(제목 헤딩 + 바로 뒤 이미지 단락)을 함께 매칭해서 하나의 div로 합쳐넣으면 둘이 한 덩어리로 취급되어 분리될 확률이 줄어든다.

스타일 참고

색은 절제된 포인트 컬러 1개(골드/앰버 등)만 쓰고, 여백을 넉넉히 준다. 장 오프너는 "CH.01" 같은 뱃지 + 큰 제목, 인용구는 왼쪽 세로선 + 이탤릭으로 처리하면 무난하게 "책스럽다".


표지 · 판매 플랫폼 이미지

밤밤 이름으로 나가는 책·강의 상품이면 표지와 스토어 이미지를 겟백 브랜드 시스템으로 만든다. 임의로 예쁜 스타일을 지어내지 말 것.

브랜드 규격 (정본: ~/Projects/getback/마케팅/insane-design/get100/design.md)

작업 전에 위 문서를 먼저 읽고, 실제 홈페이지(get100.co.kr)도 한 번 열어본다.

  • 배경은 순백이 아니라 오프화이트 #f5f5f0
  • 색은 검정 #0d0d0d, 라임 #D4F000, 퍼플 #7B2FFF 세 개만. 퍼플이 주인공, 라임이 강조
  • 네오브루탈리즘: 테두리 검정 4~6px, 하드 오프셋 그림자 Npx Npx 0 0 #0d0d0d(블러 0), 모서리 둥글림 0
  • 폰트 Pretendard, 헤딩 weight 800, letter-spacing:-.03em~-.04em
  • 제목 강조는 <span>에 background:#D4F000; box-shadow:0 0 0 5px #D4F000(형광펜 효과)

밤밤이 싫어한 것 (실측)

  • 텍스트만 얹은 표지: "텍스트만 얹은 것 같다"고 반려됨. 그래픽 장치가 최소 하나는 있어야 한다
  • 썸네일 가운데 스펙 카드: 작은 목록에서 지저분해 보임. "그냥 밑에 띠지만 있는게 딱 낫다"
  • 상세페이지 본문에 블록 이미지 나열(와디즈식): "너무 구려". 본문은 글로 두고 시각 정보는 커버/썸네일에 넣는다

확정된 형태: 썸네일 = 책 표지 그대로 + 하단 색 띠 하나, 커버 = 왼쪽 제목 + 오른쪽 구성 카드.

만년필(10000yearspen.com) 실측 규격

저장 규격과 실제 노출 규격이 다르다. 반드시 실제 크롭·표시 크기로 검증하고 올릴 것.

자리업로드 규격실제 노출안전영역
커버2100x900 (21:9)세로 중앙 382px만 보임 (5.49:1)y 259~641 안에 모든 요소
썸네일1200x1600 (3:4)목록에서 102x138px글자 최소 42px 이상(1200 기준)

검증 명령:

magick cover.jpg -gravity center -crop 2100x382+0+0 +repage -resize 760x check_cover.jpg
magick thumb.jpg -resize 102x138! -resize 380% check_thumb.png

둘 다 눈으로 읽히는지 확인한 뒤 업로드한다.

렌더링 절차 (함정 9~12 반영)

// 1) 변형마다 완성된 HTML을 파일로 저장
const css = `<style>@page{size:1200px 1600px;margin:0}
  .wrap{width:1200px;height:1600px;position:relative;overflow:hidden;background:#f5f5f0}
  .row .ic{display:inline-block;vertical-align:middle}   /* flex 금지 */
  .row .k{display:inline-block;vertical-align:middle}
</style>`;
await fs.writeFile(tmp+'t_book.html', head+css+body+'</body></html>');

// 2) file://로 열고 PDF로 뽑는다 (screenshot 아님)
await page.goto('file://'+tmp+'t_book.html', {waitUntil:'load'});
await sleep(2400);
await fs.writeFile(tmp+'t_book.pdf',
  await page.pdf({printBackground:true, preferCSSPageSize:true, pageRanges:'1'}));
# 3) PNG/JPG로 변환
pdftoppm -r 96 -png -singlefile t_book.pdf r_book
magick r_book.png -resize 1200x1600! -quality 93 thumb_book.jpg

서로 다른 변형인데 결과 MD5가 같으면 함정 11이 재발한 것이다. md5 -q로 매번 확인할 것.

만년필 업로드 자동화

상품 수정 화면의 input[type=file] 순서가 고정이다.

nth용도accept
0본문 삽입 이미지image/*
1커버(21:9)image/*
2썸네일(3:4)image/*
3첨부 파일.pdf,.zip,.epub
// 내 크리에이터 프로필 → 프리미엄 탭 → 수정하기(목록은 최신순)
await page.locator('input[type=file]').nth(1).setInputFiles(tmp+'cover.jpg'); await sleep(4500);
await page.locator('input[type=file]').nth(2).setInputFiles(tmp+'thumb.jpg'); await sleep(4500);
// 저장 버튼 클릭

주의할 점

  • 발행 후 가격은 못 바꾼다. 이미지·본문은 계속 수정 가능
  • 파일 첨부는 input[type=file]을 다시 쓰면 교체가 아니라 추가된다. 그래서 같은 PDF가 여러 장 쌓이기 쉽다. 다만 본문의 "첨부 삭제" 버튼은 정상 동작한다 — 카드를 지우고 「저장」하면 반영된다 (2026-09-12 실측: 중복 3장 → 1장 정리 성공).
  • ⚠️ 정정 (2026-09-12). 이 문서에 2026-09-08자로 "첨부 삭제가 안 되고 서버가 원래 개수로 되살린다"고 적혀 있었는데 틀렸다. 캐시된 옛 화면을 보고 내린 오진이었다. 만년필은 SPA라 저장 직후 같은 URL을 열면 저장 전 상태를 그대로 돌려준다. 반드시 쿼리스트링(?t=<timestamp>)을 붙이거나 page.reload()로 강제 새로고침한 뒤에 판단할 것. 본문 innerText 기반 개수 세기도 하이드레이션 중에는 중복해서 나오니 충분히 기다렸다 재셑할 것.
  • ⚠️ 저장 직후 편집기에 다시 들어가면 저장 전 본문이 뜬다. 그 상태에서 편집해 저장하면 방금 넣은 내용이 통째로 날아간다. 편집기 재진입 시에는 page.reload() → 의도한 변경이 화면에 보이는지 확인 → 그다음에 손댈 것.
  • 영상 임베드가 저장 과정에서 날아갈 수 있다. 2026-09-08 발행한 합본 상품은 유튜브 iframe이 사라지고 그 자리에 PDF 카드가 들어가 있었다(2026-09-12 만년필 개발자 제보로 발견). 발행 후에는 반드시 공개 페이지를 캐시 우회로 열어 iframe[src*="youtube"] 개수와 첨부 카드 개수를 세어볼 것.
  • 본문 편집기(tiptap)에서 이미지를 지울 때는 한 번에 여러 개가 안 지워진다. img를 가진 자식 노드를 찾아 setStartBefore/setEndAfter로 하나씩 선택 후 Delete를 반복할 것
  • 유료 경계(.node-paywallBlock)를 기준으로 무료 공개 비율이 자동 계산된다. 편집 후 여기부터 유료 / 공개 N% 문구로 확인
  • 영상은 유튜브 링크를 본문에 붙이면 임베드된다. 별도 이동 없이 결제 후 바로 재생됨

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • claude와 codex CLI를 로컬에서 실행합니다. 둘 다 설치돼 있어야 합니다.
  • OAuth 토큰을 ~/.config/llm/claude-oauth-token에서 읽기만 합니다. 출력하거나 전송하지 않습니다.
  • 프롬프트는 임시파일(mktemp, mode 600)에 두고 종료 시 삭제합니다.
  • 네트워크 호출은 각 CLI가 하는 것뿐이고, 이 스크립트가 따로 하는 외부 통신은 없습니다.

Claude 우선, Codex 조건부 폴백

  1. 같은 프롬프트를 안전한 임시파일에 저장한다.
  2. Claude Code를 먼저 실행한다. 자동화에 필요한 모델, 권한, 턴 상한을 기존 작업과 동일하게 유지한다.
  3. Claude가 실패했을 때 stdout과 stderr에서 실제 사용량 한도 문구만 판별한다.
    • 예: weekly limit, usage limit, hit your limit, limit ... resets
    • 일반 네트워크 오류, 인증 오류, 파싱 오류, 단순 rate limit은 자동 모델 전환 근거로 쓰지 않는다.
  4. 사용량 한도가 확정된 경우에만 같은 프롬프트를 Codex CLI로 한 번 재실행한다.
  5. Codex도 실패하면 원래 오류와 폴백 오류를 함께 기록하고 정상 산출물처럼 발송하지 않는다.
  6. 인증 토큰 값은 로그나 응답에 출력하지 않는다. Claude OAuth와 Codex ChatGPT 인증은 각 CLI의 기존 저장소를 사용한다.
  7. 배포 전에 세 경로를 각각 검증한다.
    • Claude 정상 성공: Codex 미호출
    • Claude 사용량 한도: Codex 호출 및 성공
    • Claude 일반 오류: Codex 미호출
  8. 실제 운영 환경에서 무발송 또는 읽기 전용 프롬프트로 한도 감지와 폴백 성공 로그를 확인한다.

커뮤니티 개설 에이전트 조직

에이전트 구조

오케스트레이터 (이 파일)
├── [사전 참고] 시행착오 로그  → references/00-lessons-learned.md
├── 기획 에이전트              → references/01-planning-agent.md
├── 카피라이팅 에이전트         → references/02-copywriting-agent.md
├── 노션 에이전트              → references/03-notion-agent.md
└── SOP 에이전트               → references/04-sop-agent.md

Phase 0. 오케스트레이터 — 인터뷰

스킬이 실행되면 먼저 references/00-lessons-learned.md를 읽는다. 기록된 시행착오를 파악한 뒤, 아래 질문을 순서대로 진행한다. 한 번에 2~3개씩 묻는다.

1라운드 질문 (필수)

안녕하세요! 커뮤니티 개설을 도와드릴게요.
몇 가지 여쭤볼게요.

1. 커뮤니티 이름 (아직 없으면 가칭 OK)
2. 한 줄로 설명하면? (어떤 사람들이, 무엇을 하는 곳인지)
3. 운영 호스트 이름 또는 닉네임

2라운드 질문 (필수)

4. 타겟: 어떤 사람을 위한 커뮤니티인가요?
   (직업, 상황, 고민 등 구체적으로)
5. 가격: 월정액 / 기수제 / 연간 중 어떤 구조로 생각하세요?
   그리고 예상 가격은요?
6. 운영 플랫폼: 카카오오픈채팅 / 디스코드 / 슬랙 / 기타?

3라운드 질문 (선택, 답하기 어려우면 넘어가도 됨)

7. 커뮤니티에서 정기적으로 할 활동이 있다면요?
   (예: 주 1회 줌 세션, 주간 과제, 챌린지 등)
8. 비슷한 커뮤니티와 차별화되는 점이 있다면요?
9. 1기 모집 목표 인원과 오픈 예정일은요?

모든 답변이 수집되면 → Phase 1부터 순서대로 실행.


Phase 1. 기획 에이전트 실행

references/01-planning-agent.md를 읽고 커뮤니티 기획서를 작성한다.

완성 후 호스트에게 확인: "기획서 확인하셨나요? 수정할 부분 있으면 말씀해주세요. 없으면 다음 단계로 넘어갑니다."


Phase 2. 카피라이팅 에이전트 실행

references/02-copywriting-agent.md를 읽고 채널별 모집 카피를 작성한다.

기본 출력: 스레드 모집 글 + 카카오 단톡방 공지 운영 플랫폼이 디스코드/인스타 등이면 해당 채널 카피 추가.

완성 후 호스트에게 확인 후 다음 단계 진행.


Phase 3. 노션 에이전트 실행

references/03-notion-agent.md를 읽는다.

노션 MCP가 연결된 경우: DB 자동 생성 진행 노션 MCP가 없는 경우: DB 스키마를 텍스트로 출력하고 "노션에서 직접 만드실 때 이렇게 세팅하시면 됩니다" 안내


Phase 4. SOP 에이전트 실행

references/04-sop-agent.md를 읽고 운영 SOP 전체를 작성한다.


Phase 5. 마무리 요약

모든 산출물 완성 후 아래 요약 출력:

✅ 커뮤니티 개설 패키지 완성

📋 기획서: [커뮤니티 이름] 기획서
✍️ 모집 카피: 스레드 글 + 단톡 공지
🗂️ 노션 DB: 멤버 / 콘텐츠 / 세션 DB
📌 SOP: 온보딩 / 주간 루틴 / 위기대응 / 기수 전환

다음 액션:
1. 결제 페이지 만들기 (래피드 권장)
2. 모집 글 발행
3. 노션 DB 세팅 확인

시행착오 로그 기록 방법

운영 중 새로운 인사이트가 생기면 호스트에게 물어본다:

"이번에 [상황]이 있었는데, 시행착오 로그에 기록해둘까요?"

동의하면 references/00-lessons-learned.md에 아래 형식으로 추가:

### [커뮤니티명 또는 기수] — [날짜]

**상황**: ...
**시도한 것**: ...
**결과**: ...
**배운 것**: ...
**적용 범위**: 기획 / 모집카피 / 운영 / 노션 / SOP

운영 원칙

  • 스킬 시작 시 반드시 00-lessons-learned.md를 먼저 읽어 과거 시행착오 반영
  • 인터뷰 중 호스트가 답변하기 어려워하면 예시를 제시하고 선택하게 한다
  • 각 Phase 완료 후 반드시 확인을 받고 다음으로 넘어간다
  • 모든 산출물은 호스트의 말투와 컨셉을 반영해 작성한다
  • 수정 요청이 들어오면 해당 Phase만 재실행한다
  • 새로운 시행착오 발견 시 로그 기록을 제안한다

Computer Use

This file is a discovery stub, not the usage guide. The full, version-matched computer-use reference is served by the orca binary itself — kept out of this file on purpose so it can never drift from the binary that will actually run your commands.

Engage Orca's computer-use surface whenever you must inspect or operate a local desktop app window — reading its accessibility tree, taking screenshots, or performing safe UI actions (click controls, type, press keys, scroll, drag, set values). It also covers browser windows, webviews, and Orca's own UI. Triggers include "computer use", "orca computer", "read Spotify", "read Slack", "control/click/read in a desktop app", and "get app state".

Resolve the CLI for this session

Choose the executable once and reuse it for every later command:

  • If the ORCA_CLI_COMMAND environment variable is set, use its value. Orca exports this for managed WSL sessions.
  • Otherwise, in a dev checkout whose session exposes ORCA_DEV_REPO_ROOT, use orca-dev.
  • Otherwise, on Linux outside an Orca-managed terminal, use orca-ide. Never run bare orca there — outside Orca's terminals it normally resolves to the GNOME Orca screen reader (/usr/bin/orca) and starts speech on the user's machine.
  • Otherwise, use orca.

Below, ORCA is a placeholder for the executable you resolved. Substitute it before running anything; do not create a shell variable or run ORCA literally. This works the same way in POSIX shells, PowerShell, and cmd.exe.

If the selected executable cannot run, report its exact error and stop. Do not fall through to another executable, which could silently target a different Orca build.

Load the full guide before running Orca commands

ORCA skills get computer-use

That prints the complete, version-matched guide for the exact binary that will handle your next commands — listing apps/windows, reading UI, and driving clicks, typing, and other accessibility actions. Read it first, then run the specific command you need.

Don't guess subcommands or flags from memory or from a cached copy of this stub. They change between Orca releases, and this file deliberately no longer lists them. Confirm the app is up with ORCA status --json (start it with ORCA open --json if needed), and prefer --json for agent-driven calls.

If an older Orca does not recognize skills get

Use this fallback only when the selected binary explicitly reports that skills get is an unknown command. Another failure is not proof of an older binary; report it rather than guessing or changing executables. For a confirmed pre-guide binary, use only this bounded, read-only bootstrap to orient. Do not dead-end and do not invent commands:

ORCA status --json
ORCA computer capabilities --json
ORCA computer list-apps --json

Then tell the user that updating Orca restores the full, version-matched guide via ORCA skills get computer-use. Beyond these commands, ask the user rather than guessing a command surface this older binary may not support.

당근마켓 광역 검색

당근 웹(www.daangn.com)의 중고거래 검색은 선택된 행정동 하나의 매물만 보여준다. "전국 검색" 기능이 없다. 넓게 찾으려면 지역코드를 바꿔가며 순회해야 한다.

URL 구조

https://www.daangn.com/kr/buy-sell/?in=x-<지역ID>&search=<검색어>&only_on_sale=true
  • in 파라미터의 이름 부분은 무시되고 숫자 ID만 유효하다. x-448처럼 아무 이름이나 써도 된다
  • only_on_sale=true 를 붙이면 거래완료 매물이 빠진다. 안 붙이면 결과 대부분이 이미 팔린 것
  • 응답은 서버사이드 렌더링이라 fetch만으로 매물이 다 들어온다 (브라우저 불필요)

지역 ID 지도 (2026-08 실측)

시도 순서로 연속 배치돼 있다. 서울은 구 단위로 아래와 같다.

구ID구ID
종로3~19양천239~260
중구20~35강서261~280
용산36~52구로281~296
성동53~70금천297~306
광진71~86영등포307~325
동대문87~110동작326~340
중랑111~127관악341~361
성북128~144서초362~380
강북145~157강남381~403
도봉158~172송파404~431
노원173~185강동432~450
은평186~206
서대문207~220마포221~238

서울 밖: 부산 451~, 대구 680830, 인천 831960, 광주 961, 대전 1051, 울산 1151, 세종·경기 12511800, 강원 ~1900, 충북 ~2100, 충남 ~2400, 전북 ~2700, 전남 ~3000.

경계는 정확하지 않다. 확인이 필요하면 아래로 지역명을 읽어 검증한다.

const m = html.match(/data-gtm="search_filter">([^<]+)</);  // "서울시 강동구 둔촌동"

매물 파싱

function parseL(html){
  const re=/<a data-gtm="search_article"[^>]*href="(\/kr\/buy-sell\/[^"]+)"[\s\S]*?<\/a>/g;
  const res=[]; let m;
  while((m=re.exec(html))){
    const seg=m[0];
    const txt=seg.replace(/<img[^>]*>/g,'').replace(/<svg[\s\S]*?<\/svg>/g,'')
                 .replace(/<[^>]+>/g,'\u0001').split('\u0001').map(s=>s.trim()).filter(Boolean);
    res.push({href:'https://www.daangn.com'+m[1], t:txt.join(' | ')});  // "제목 | 가격 | 동네 | 시간"
  }
  return res;
}

상세 페이지는 fetch 후 매너온도 다음 20줄 정도를 읽으면 본문·채팅수·관심수가 나온다.

속도와 차단

CloudFront가 앞단에 있어 너무 빠르면 403이 뜬다. 한 번 막히면 1~2분 쉬어야 풀린다.

  • 안전 구간: 23개 병렬 + 250450ms 간격 (초당 약 2.5~5건). 이 속도로 900개 동을 돌았고 차단 0회
  • 위험 구간: 10병렬 연속. 약 120건에서 막혔다
  • 403이 연속 8건 넘게 나오면 15~20초 쉬고 재개하는 가드를 넣는다
  • page.goto()(브라우저)는 동당 2.4초로 fetch보다 3~4배 느리다. fetch를 쓴다
  • REPL 툴콜은 120초에서 끊긴다. 한 콜에 250~300개 동이 한계이니 나눠 돌린다
  • 에이전트 탭이 중간에 닫혀 page가 null이 되는 일이 있다. fetch 방식이면 영향 없다

검색어 전략

당근 검색은 토큰 기반이라 한 단어로는 다 못 잡는다. 2~3개를 돌린다.

  • 예: 세탁건조기 → 콤보(워시콤보·AI콤보 잡힘) + 세탁건조기 + 워시타워
  • 콤보 같은 일반어는 영화 팝콘 쿠폰 같은 노이즈가 압도적이다. 수집 후 /세탁|건조/ 등으로 거른다
  • 결과는 Map(href → 제목)에 모아 자동 중복 제거한다. 같은 판매자가 여러 동네에 중복 게시하는 일이 잦다

결과 정리

제목 문자열에서 가격·세대를 뽑아 정렬하면 시세 분포가 바로 보인다.

const price = t => { const m=t.match(/([\d,]+)원/); return m?+m[1].replace(/,/g,''):null; };

주의

  • 대형가전은 지방 매물을 넣지 말 것. 용달비 40~50만원이면 가격 이점이 사라진다. 수도권까지가 실용 범위
  • 중고 시세가 신품가에 근접하면 신품·구독과 나란히 비교해서 보고한다. 중고만 훑고 "이게 최저가"라고 하면 반쪽짜리다

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • 정해진 시각에 자동 실행되는 상주 작업(launchd/cron)을 등록합니다.
  • 외부 사이트를 주기적으로 읽습니다. 대상 사이트의 이용약관을 먼저 확인하세요.
  • 결과를 메신저로 발송합니다. 봇 토큰이 필요합니다.

데일리 브리핑 봇

밤밤은 매일 아침 10시에 디스코드 DM으로 데일리 브리핑 봇 아티클을 받는다. 대상 커뮤니티(사이트는 설정에서 지정) 신규 글을 전부 읽고, 밤밤의 제2두뇌 볼트·에이사이드 스킬/메모리와 대조해 밤밤이 지금 붙들고 있는 고민에 닿는 3건을 골라 편지 형식으로 보낸다. 각 항목에 번호(1~3)와 원문 링크가 붙어 있다.

"여백"은 이 봇이 후보를 고르는 내부 판정 기준을 부르는 말이다(볼트에 한 번도 안 나온 것). 밤밤에게 말할 때는 봇 이름인 데일리 브리핑 봇으로 부른다.

트리거

  • "데일리 브리핑 봇 고치자" — 톤·길이·건수·시간 등 편집. 아래 편집 표 참고
  • "데일리 브리핑 봇 2번 해보자" / "8/13 2번 해보자" / "어제 그거 해보자" — 실행
  • "오늘 데일리 브리핑 봇 뭐 왔어" — 읽어주기만
  • "이거 볼트에 넣어" — 볼트 승격
  • 옛 호칭 "여백 브리핑"으로 불러도 같은 것을 가리킨다

인프라 위치 (전부 맥미니, ssh mac-mini)

~/Projects/daily-brief/
  prompt-template.md  ★ 톤·형식·길이·몇 건을 결정하는 유일한 파일. 편집은 거의 여기만 고친다
  collect.mjs   대상 커뮤니티 신규 글 수집 (Bettermode GraphQL, 게스트 토큰 · 로그인 불필요)
  brief.mjs     볼트·스킬·메모리 대조 → 후보 22건 추린 뒤 템플릿에 끼워 프롬프트 생성
  verify.mjs    브리핑 링크가 실제 수집분인지 대조·정정
  dm.py         디스코드 DM 발송 (stdin → 밤밤 DM, 1900자씩 분할)
  capture.py    밤밤의 DM 답장 회수 (10분마다)
  run.sh        매일 10:00 전체 실행 (launchd com.bambam.daily-brief)
  .env          DISCORD_TOKEN / BAMBAM_USER_ID / CLAUDE_CODE_OAUTH_TOKEN (600)
  ctx/          맥북에서 동기화한 에이사이드 skills/ · memory/ ("이미 하고 있는 것" 판정용)
  state/
    posts-YYYY-MM-DD.json   그날 수집한 글 전문
    brief-YYYY-MM-DD.md     그날 보낸 아티클
    marks.jsonl             밤밤이 DM에서 표시한 관심 항목
    done.jsonl              실제로 실현한 항목 (재제안 금지 목록)

밤밤 볼트: ~/Library/Mobile Documents/com~apple~CloudDocs/제2두뇌 (맥미니에서도 접근됨)

현재 확정된 형식 (2026-08-13 밤밤 승인)

  • 아티클이다. 목록이나 알림이 아니다. 링크를 하나도 안 눌러도 내용을 다 알 수 있어야 한다.
  • 문체는 "밤밤님" + 해요체의 편지. 관찰 보고서 금지.
  • 첫 문단은 반드시 "요즘 ~에 걸려 계신 것 같아요" 로 시작해 고민을 한 가지로 짚는다. 노트 제목 나열 금지. 틀려도 좋으니 구체적으로 짚는다.
  • 3건, 전체 1만자 안팛. 앞 2건은 짚은 고민에 바로 닿는 것, 마지막 1건은 안 해본 것.
  • 각 항목: 그 사람 상황 → 무엇을 어떻게 했는지(도구·프롬프트·숫자 그대로) → 결과 → 밤밤님 쪽이랑 겹치는 데(볼트·스킬 근거) → "이거 한번 시도해보시면 어때요?" → 오늘 30분 → 원문 링크

편집 요청 처리

밤밤이 "데일리 브리핑 봇 고치자" 계열로 말하면 아래에서 해당하는 파일만 고친다.

요청고칠 곳
톤, 문체, 형식, 길이, 몇 건, 어떤 순서로, 금지 표현prompt-template.md ← 거의 전부 여기
어떤 글을 후보로 올릴지 (점수 기준, 후보 개수, 활동 판정 기간 7일)brief.mjs
어떤 카테고리를 수집할지, 몇 건 가져올지collect.mjs
보내는 시각~/Library/LaunchAgents/com.bambam.daily-brief.plist → 수정 후 unload/load
모델 (클로드 → 코덱스 폴백)run.sh

고친 뒤에는 반드시 한 번 돌려보고 결과를 보여준 다음 발송한다.

ssh mac-mini 'cd ~/Projects/daily-brief && node brief.mjs && set -a && . ./.env && set +a && claude -p < state/prompt-<날짜>.txt'

맥북 스킬/메모리가 바뀜으면 판정 근거도 갱신해야 한다.

rsync -az --delete ~/.aside/u/0/skills/ mac-mini:~/Projects/daily-brief/ctx/skills/
rsync -az --exclude='.history.jsonl' --exclude='memory-index.json' --exclude='.moss-cache' --exclude='.git' ~/.aside/u/0/memory/ mac-mini:~/Projects/daily-brief/ctx/memory/

"데일리 브리핑 봇 N번 해보자" 처리 절차

  1. 원문 전문부터 읽는다. 브리핑 요약만 보고 시작하지 마라.

    ssh mac-mini 'cat ~/Projects/daily-brief/state/brief-<날짜>.md'
    

    해당 항목의 링크에서 post ID를 뽑아 posts-<날짜>.json에서 body를 꺼낸다.

  2. 밤밤 볼트의 관련 노트를 읽는다. 브리핑의 "밤밤 쪽 연결" 줄에 적힌 노트를 실제로 열어본다. 남이 쓴 방법을 그대로 옮기지 말고, 밤밤이 이미 가진 것과 겹치는 부분을 먼저 확인한다.

  3. 밤밤 환경 기준으로 다시 짠 실행안을 제시하고 승인받는다.

    • 원문에서 그대로 쓸 것 / 밤밤 환경에 맞게 바꿀 것 / 안 쓸 것을 구분해서 보여준다
    • 되돌리기 어려운 작업(배포, 결제, 삭제)은 승인 전에 절대 실행하지 않는다
  4. 실행한다. 무거운 작업이면 맥미니로 넘긴다(macmini-offload 스킬).

  5. 끝나면 기록한다.

    • 볼트: 새 노트를 만들지 말고 기존 노트에 한 줄 덧붙인다. [[위키링크]] 문법 지킬 것. 예) 참고: 정본노트를 채널별 브리프로 분리하는 OSMU 방식 — https://... 새 개념 노트가 필요할 정도면 밤밤에게 먼저 묻는다.
    • done.jsonl에 한 줄 추가:
      ssh mac-mini 'echo "{\"date\":\"2026-08-13\",\"no\":2,\"post\":\"<postId>\",\"title\":\"...\",\"result\":\"...\"}" >> ~/Projects/daily-brief/state/done.jsonl'
      
      이게 있으면 같은 주제를 다시 제안하지 않는다.

설계 원칙 (밤밤이 직접 정한 것)

  • 여백 = 밤밤이 지금 하는 일과 인접한데, 볼트 761개 노트에 한 번도 기록된 적 없는 것. 미결 목록은 고민이 아니다. 밤밤이 선택을 안 한 건 그냥 넘긴 것일 수 있다.
  • "지금 하는 일"은 밤밤에게 묻지 말고 볼트에서 최근 7일 수정된 노트로 판단한다.
  • 읽지 않은 것은 볼트에 넣지 않는다. 브리핑 원본은 맥미니에 30일만 두고 자동 삭제된다. 볼트로 올라가는 건 밤밤이 표시했거나 실제로 해봤을 때뿐이다.
  • 억지로 4개를 채우지 않는다. 그날 걸리는 게 없으면 비운다.
  • 볼트가 커질수록 "이미 아는 것"이 두꺼워져 여백이 좁아진다. 그게 정상이다.

톤

  • 이모지 쓰지 않는다.
  • 금지 표현: "~이 아니라" 대조 구문, "굴러가다", "여정", "진짜 기준", 안심시키려는 문장.
  • 볼트에 없는 걸 있다고 말하지 않는다. 근거는 실제 노트 경로로 댄다.

아바타 교체

후보 4종이 맥미니 ~/Projects/daily-brief/assets/ 에 있다 (b_bot 적용 중 / a_owl / c_book / d_cat). 밤밤이 로봇을 골랐다. 40px 원형으로 잘려도 눈 두 개와 안테나 라임 점이 살아남는다. 겟백 브랜드 컬러 기준: 배경 #0d0d0d, 강조 #d4f000. 디스코드는 작은 원으로 잘리니 여백을 넉넉히 둔 단순한 형태만 쓴다.

ssh mac-mini 'cd ~/Projects/daily-brief && set -a && . ./.env && set +a && python3 -c "
import os,json,base64,urllib.request
img=base64.b64encode(open(\"assets/b_bot.png\",\"rb\").read()).decode()
H={\"Authorization\":\"Bot \"+os.environ[\"DISCORD_TOKEN\"],\"User-Agent\":\"DiscordBot (https://github.com, 1.0)\",\"Content-Type\":\"application/json\"}
r=urllib.request.Request(\"https://discord.com/api/v10/users/@me\",data=json.dumps({\"avatar\":\"data:image/png;base64,\"+img}).encode(),headers=H,method=\"PATCH\")
print(json.load(urllib.request.urlopen(r))[\"username\"])"'

어휘 수준 (2026-08-13 교정)

밤밤은 개발자가 아니다. 읽다가 모르는 단어가 하나라도 나오면 실패다. 전문용어는 처음 나올 때 괄호로 풀고, 영어 약어는 우리말로 바꾸고, 명령어·코드는 역할 설명이 붙을 때만 쓴다. 단 숫자와 구체적 사실은 그대로 살린다. 쉽게 쓰라는 게 내용을 빼라는 뜻이 아니다. 자세한 규칙은 prompt-template.md 의 "말투와 어휘" 절에 있다.

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • 상주 작업(launchd)을 등록하고 프로세스를 죽였다 살립니다.
  • 봇 토큰이 필요합니다. 환경변수·.env에서만 읽습니다.
  • 저전력 모드에서 상주 작업이 조용히 죽는 문제를 다룹니다. 전원 설정을 바꾸는 단계가 포함됩니다.

맥미니 에이전트 무리

밤밤의 맥미니(ssh mac-mini)에 대화형 디스코드 봇이 셋 상주한다. 전부 같은 뼈대를 쓴다.

봇폴더아는 것launchd
지식봇A~/Projects/knowledge-bot-a/커뮤니티A 8기수 기록 + 원자료 55개com.bambam.knowledge-bot-a
스터디봇B~/Projects/daily-brief-agent/대상 커뮤니티 글 2,000건 + 지난 아티클 + 밤밤 스킬·메모리com.bambam.daily-brief-agent
밤냥이~/Projects/getback/discord_bot/겟백 커뮤니티 운영(길드·슬래시명령 등)com.getback.bamnyangi

파이썬은 셋 다 ~/Projects/getback/.venv/bin/python 를 공유한다. 서버는 ai공작실(<DISCORD_ID>) 하나. 허용 계정은 밤밤 <DISCORD_ID>, GET100 <DISCORD_ID>.

공통 뼈대

  • bot.py — 디스코드 게이트웨이. DM은 전체 지식, 공개 채널은 멘션받을 때만
  • answer.py — 인격+기억+자료를 조립해 LLM 호출
  • store.py — 단기 대화를 SQLite 에 영구 저장 (재시작·재부팅에도 유지)
  • persona.md — 인격·말투. 매 응답마다 읽으므로 고치면 재시작 없이 반영
  • memory.md — 장기기억. 응답에 MEMORY: 줄을 쓰면 자동 적립

기억이 두 층이라는 게 핵심이다. 단기(대명사 받기) + 장기(세션 끊어도 남는 사실). 초기화는 단기만 끊고 장기는 남긴다.

⚠️ 이 기기의 함정 세 가지

1. 저전력 모드가 KeepAlive 자동 재시작을 막는다

맥미니에 lowpowermode = 1 이 켜져 있으면, 프로세스가 죽어도 launchd 가 되살리지 않는다.

state = not running
pended nondemand spawn = inefficient

"요청 없이 스스로 재기동하는 건 비효율적"이라며 무기한 보류한다. plist 에 KeepAlive 가 제대로 있어도 소용없고 ProcessType 을 바꿔도 안 통한다. 40초를 기다려도 안 풀리는 걸 실측했다.

  • 배포·재시작할 때는 항상 launchctl kickstart -k 를 명시적으로 쓴다. bootstrap 만으로는 프로세스가 안 뜬다. kickstart 는 명시적 요청이라 보류 정책을 우회한다.
  • 근본 해결은 sudo pmset -a lowpowermode 0 인데 비번 없는 sudo 가 안 걸려 있어 SSH 로는 못 한다. 밤밤이 직접 쳐야 한다.
  • 이건 지식봇A만의 문제가 아니라 이 기기의 모든 launchd 상주 작업에 적용된다.

2. CLAUDE.md 가 모든 CLI 호출에 자동으로 딸려간다

claude CLI 는 실행 디렉터리에 CLAUDE.md 가 없으면 상위 폴더로 거슬러 올라가며 찾아서 프롬프트에 넣는다.

밤냥이가 호출당 14만 토큰을 쓰던 원인이 이거였다. 밤집사가 실제로 만드는 프롬프트는 4,766자인데, discord_bot/ 한 칸 위의 ~/Projects/getback/CLAUDE.md(당시 170KB)가 매번 통째로 붙고 있었다. 2026-08-16 에 밤알바생·옛 작업이력을 docs/CLAUDE-archive-*.md 로 옮겨 1만 4천 자(92% 감소) 로 줄였다.

  • 새 봇을 만들 때는 subprocess 에 cwd 를 그 봇 폴더로 고정하고, 그 폴더에 큰 CLAUDE.md 를 두지 않는다
  • 토큰이 예상보다 크면 프롬프트 코드부터 의심하지 말고 상위 폴더의 CLAUDE.md 크기를 먼저 재라
  • ~/.claude/CLAUDE.md(전역, 약 5KB)는 항상 붙는다. 이건 어쩔 수 없다

3. launchd PATH 에는 homebrew 가 없다 — 절대경로만으론 부족하다

launchd 는 PATH 를 /usr/bin:/bin:/usr/sbin:/sbin 으로만 준다. 그래서 CLI 를 절대경로로 불러도, 그 CLI 자체가 node 스크립트면 죽는다.

Codex rc=127: env: node: No such file or directory

codex 는 /opt/homebrew/lib/node_modules/@openai/codex/bin/codex.js 로 가는 심링크이고 셔뱅이 #!/usr/bin/env node 다. PATH 에 /opt/homebrew/bin 이 없으면 node 를 못 찾는다. claude 는 네이티브 Mach-O 바이너리라 이 문제가 없다 — 그래서 claude 는 멀쩡한데 codex 폴백만 조용히 죽어 있는 상태가 만들어진다. 2026-08-16 TWC 조사봇이 주간 한도에 걸렸을 때 폴백도 같이 실패해 15시간 리포트가 끊긴 원인이 이거였다.

두 겹으로 막는다.

  1. plist 에 PATH 를 박는다 (근본)
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
    
  2. 스크립트에서도 env 를 보강한다 (수동 실행 대비). subprocess.run(..., env=_tool_env()) 로 /opt/homebrew/bin 을 PATH 앞에 끼운다.

진단 코드도 같이 봐라. subprocess.run 은 셔뱅 실패(rc=127)에 예외를 안 던진다. try/except 만으로 점검하면 죽은 CLI 를 OK 로 찍는다. TWC 조사봇 --check 가 정확히 이 버그였고, 그래서 폴백이 몇 달 고장난 걸 아무도 몰랐다. 반드시 returncode 를 확인할 것.

검증은 launchd 환경을 재현해서 한다.

ssh mac-mini 'cd ~/ops/<봇> && env -i HOME=$HOME PATH=/usr/bin:/bin:/usr/sbin:/sbin /opt/homebrew/bin/python3 followup.py --check'

LLM 호출은 구독으로만

API 키(ANTHROPIC_API_KEY)를 쓰지 않는다. 밤밤이 명시적으로 금지했다. ~/Projects/getback/agents/llm_cli.py 가 공용 호출 모듈이다. claude -p --output-format text 를 stdin 으로 부르고, CLAUDE_CODE_OAUTH_TOKEN 을 넘긴다. PATH 가 없는 launchd 환경 대비로 /opt/homebrew/bin/claude 하드코딩 폴백이 있다.

사용량 한도(weekly limit) 문구가 나올 때만 Codex 로 한 번 재실행한다. 일반 오류로는 넘어가지 않는다. 자세한 규칙은 claude-codex-fallback 스킬.

모델은 --model 을 안 줘서 CLI 기본값(2026-08 기준 claude-sonnet-5)을 쓴다. 고정하려면 --model sonnet|opus|fable.

자주 하는 일

# 상태
ssh mac-mini 'for S in com.bambam.knowledge-bot-a com.bambam.daily-brief-agent com.getback.bamnyangi; do echo "=== $S ==="; launchctl print gui/$(id -u)/$S 2>/dev/null | grep -iE "^\s+(state|pid) "; done'

# 재시작 (kickstart 필수)
ssh mac-mini 'launchctl kickstart -k gui/$(id -u)/com.bambam.knowledge-bot-a'

# 로그 — 실제 로그는 bot.error.log 에 쌓인다 (bot.log 는 비어있는 경우가 많다)
ssh mac-mini 'tail -30 ~/Projects/knowledge-bot-a/bot.error.log'

# 디스코드 안 거치고 답변 엔진만 시험
ssh mac-mini 'cd ~/Projects/knowledge-bot-a && set -a && . ./.env && set +a && ~/Projects/getback/.venv/bin/python answer.py "질문"'

코드는 로컬에서 쓰고 scp 로 보낸다. 히어독으로 원격에 파이썬을 직접 쓰면 따옴표·한글 이스케이프가 깨진다(실제로 깨졌다).

새 봇을 만들 때

knowledge-bot-a 를 통째로 복사하고 answer.py 의 지식 소스만 바꾸는 게 가장 빠르다. store.py·bot.py·persona.md 는 거의 그대로 간다.

만들기 전에 확인할 것:

  • 어느 계정으로 DM 하는가 — 봇은 자기와 같은 서버에 있는 사람하고만 DM 이 열린다
  • 공개 채널에도 둘 것인가 — 그렇다면 지식 범위를 나눈다. 지식봇A은 DM 에선 밤밤판(대외비 포함), 채널에선 커뮤니티A판(내부 데이터 없음)을 쓴다. 규칙으로 막지 말고 자료를 안 주는 방식으로 분리한다
  • 봇끼리 무한루프 — 사람이 안 끼어든 연속 봇 응답이 3회 넘으면 침묵하게 한다
  • 응답에 식별 접두어를 붙인다(📓 [지식봇A] 등)
  • allowed_mentions=discord.AllowedMentions.none() 로 멘션 사고를 막는다

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • 사용자 홈에 실행 스크립트 하나(~/Projects/<프로젝트>/<slug>.sh, mode 700)를 만듭니다.
  • macOS launchd 항목 하나(~/Library/LaunchAgents/com.bambam.reminder-<slug>.plist)를 등록합니다.
  • 일회성 리마인더는 발송 직후 스스로 launchd에서 내려가고 plist를 지웁니다. 상주하지 않습니다.
  • 반복 리마인더는 사용자가 지운 시점까지 유지됩니다. 목록은 launchctl list | grep reminder로 확인합니다.
  • 디스코드 토큰은 실행 시점에 .env에서만 읽고 출력하지 않습니다.

보안 스캐너는 이 동작을 service_persistence(영구 서비스 설치)로 분류합니다. 맞습니다. 다만 일회성 항목은 스스로 제거되고, 만드는 파일은 위 두 개뿐입니다.

Mac-mini Discord reminder

Use the mac-mini instead of Aside routine slots for scheduled reminders.

  1. Resolve relative dates in Asia/Seoul and choose a concrete KST time. If the user gives no time, use 10:00 KST and state it.
  2. Store the executable script at ~/Projects/reminders/<slug>.sh on mac-mini with mode 700.
  3. Load Discord credentials only at runtime from ~/Projects/getback/discord_bot/.env. Never print or copy token values.
  4. Send the DM through Discord API v10 to BAMBAM_USER_ID. Include a non-empty User-Agent header to avoid Cloudflare blocking.
  5. Store the LaunchAgent at ~/Library/LaunchAgents/com.bambam.reminder-<slug>.plist.
    • One-time reminder: use StartCalendarInterval with Year, Month, Day, Hour, and Minute.
    • Recurring reminder: use only the requested recurring calendar fields.
    • Never use StartInterval on this mac-mini. Verified 2026-08-16: every StartInterval LaunchAgent in the gui/501 domain sits at pended nondemand spawn = interval and does not fire, including one that had previously run 2,429 times. StartCalendarInterval jobs fire normally. For an every-N-minutes job, list the minutes explicitly, e.g. [{Minute: 0}, {Minute: 5}, ... {Minute: 55}] for a 5-minute cadence.
  6. Write stdout and stderr to ~/Projects/reminders/<slug>.log.
  7. Validate and load without firing the reminder immediately:
    • plutil -lint <plist>
    • launchctl bootout gui/$(id -u)/<label> if an old copy exists
    • launchctl bootstrap gui/$(id -u) <plist>
    • launchctl print gui/$(id -u)/<label>
    • plutil -p <plist> to verify the exact schedule
  8. Confirm it actually fires. launchctl print showing the job loaded is not proof — watch runs increment across two scheduled ticks, or check the job's own log for two consecutive scheduled entries. A job can load cleanly and never spawn.
  9. Do not test-send a real DM unless the user asks. Report the resolved date, time, timezone, delivery channel, and loaded label.

Use concise reminder text that says what happened, what the user should do next, and any account or product distinction needed to avoid a wrong action.


커뮤니티 행사 판매 멘트 생성기

실전 사례(행사 2026, 완판+대기자 29명)에서 추출한 7단계 프레임워크를 기반으로, 입력받은 행사 정보에 맞춘 채널별 판매 멘트 세트를 생성한다.

전략 원칙과 원문 사례는 references/framework.md 참고 — 채널 톤, 구성 공식, 실전 발화 예시 포함.

1단계: 행사 정보 수집

멘트 생성 전, 아래 정보를 묻는다. 사용자가 일부만 제공하면 나머지는 합리적으로 채워서 진행한다.

필수
- 행사명
- 날짜/장소
- 대상 (커뮤니티 이름 or "멤버들")
- 가격 구조 (단계가 있으면 전부: 슈퍼얼리버드 → 얼리버드 → 일반)
- 한정 수량
- 신청 방법 (계좌이체/링크/구글폼)

선택
- 행사 핵심 가치 한 줄 (없으면 행사명에서 추론)
- 주최자/운영자 이름 또는 페르소나
- 특별 혜택 (점심 포함, 굿즈, 책 패키지 등)

2단계: 멘트 세트 생성

정보 수집 후 아래 7단계를 카카오톡 단톡방과 스레드 버전으로 나눠 출력한다.

출력 형식

각 단계마다 다음 구조로 출력:

## STEP N. [단계명]
📍 발송 시점: [언제 보낼지]

### 카카오톡 단톡방
[실제 복사해서 쓸 수 있는 멘트]

### 스레드
[실제 복사해서 쓸 수 있는 멘트]

7단계 구성

단계이름발송 시점
STEP 1선공개 공지판매 시작 당일
STEP 2개별 DM (주도자용)공지 직후 30분 내
STEP 3리스트 공개 + 업데이트 유도첫 구매자 나온 직후
STEP 4카운트다운마감 D-1 또는 D-0 아침
STEP 5중간 업데이트판매 1~2주차
STEP 6설문 + 경품 안내행사 D-14~D-7
STEP 7완판 공지완판 직후

작성 원칙

  • 카카오톡 단톡방: 친근 + 공식 혼합. 이체 안내, 리스트, 멘션 포함 가능. 이모티콘 자연스럽게.
  • 스레드: 홍보처럼 안 보이게. 개인 이야기/소감 형식. 짧고 끊기는 문장. 해시태그 끝에 배치.
  • 압박 뒤에는 반드시 감사/다짐으로 마무리 — 차갑지 않게.
  • 가격 인상 경고는 매 단계 자연스럽게 포함.
  • 수치는 구체적으로 (예: "87장" not "많은 장").

추가 요청 처리

생성 후 사용자가 다음을 요청할 수 있다:

  • "STEP 4만 다시 써줘" → 해당 단계만 재생성
  • "좀 더 따뜻하게" / "좀 더 긴박하게" → 톤 조정
  • "스레드 버전만" → 채널 필터링
  • "실제 수량 넣어서" → 수치 반영 재생성

Harness — Agent Team & Skill Architect

도메인/프로젝트에 맞는 하네스를 구성하고, 각 에이전트의 역할을 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬.

핵심 원칙:

  1. 에이전트 정의(.claude/agents/)와 스킬(.claude/skills/)을 생성한다.
  2. 에이전트 팀을 기본 실행 모드로 사용한다.
  3. CLAUDE.md에 하네스 포인터를 등록한다. — 새 세션에서 오케스트레이터 스킬이 트리거되도록 최소한의 포인터(트리거 규칙 + 변경 이력)만 기록한다.
  4. 하네스는 고정물이 아니라 진화하는 시스템이다. — 매 실행 후 피드백을 반영하고, 에이전트·스킬·CLAUDE.md를 지속 갱신한다.

워크플로우

Phase 0: 현황 감사

하네스 스킬이 트리거되면 가장 먼저 기존 하네스 현황을 확인한다.

  1. 프로젝트/.claude/agents/, 프로젝트/.claude/skills/, 프로젝트/CLAUDE.md를 읽는다

  2. 현황에 따라 실행 모드를 분기한다:

    • 신규 구축: 에이전트/스킬 디렉토리가 없거나 비어있음 → Phase 1부터 전체 실행
    • 기존 확장: 기존 하네스가 있고 새 에이전트/스킬 추가 요청 → 아래 Phase 선택 매트릭스에 따라 필요한 Phase만 실행
    • 운영/유지보수: 기존 하네스의 감사·수정·동기화 요청 → Phase 7-5 운영/유지보수 워크플로우로 이동

    기존 확장 시 Phase 선택 매트릭스:

    변경 유형Phase 1Phase 2Phase 3Phase 4Phase 5Phase 6
    에이전트 추가건너뜀 (Phase 0 결과 활용)배치 결정만필수전용 스킬 필요 시오케스트레이터 수정필수
    스킬 추가/수정건너뜀건너뜀건너뜀필수연결 변경 시필수
    아키텍처 변경건너뜀필수영향받는 에이전트만영향받는 스킬만필수필수
  3. 기존 에이전트/스킬 목록과 CLAUDE.md 기록을 대조하여 불일치(drift)를 감지한다

  4. 감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다

Phase 1: 도메인 분석

  1. 사용자 요청에서 도메인/프로젝트 파악
  2. 핵심 작업 유형 식별 (생성, 검증, 편집, 분석 등)
  3. Phase 0 감사 결과를 기반으로 기존 에이전트/스킬과의 충돌/중복 분석
  4. 프로젝트 코드베이스 탐색 — 기술 스택, 데이터 모델, 주요 모듈 파악
  5. 사용자 숙련도 감지 — 대화의 맥락 단서(사용 용어, 질문 수준)로 기술 수준을 파악하고, 이후 커뮤니케이션 톤을 조절한다. 코딩 경험이 적은 사용자에게는 "assertion", "JSON schema" 같은 용어를 설명 없이 쓰지 않는다.

Phase 2: 팀 아키텍처 설계

2-1. 실행 모드 선택

에이전트 팀이 최우선 기본값이다. 2개 이상의 에이전트가 협업할 때는 반드시 에이전트 팀을 먼저 검토한다. 팀원 간 직접 통신(SendMessage)과 공유 작업 목록(TaskCreate)으로 자체 조율하며, 발견 공유·상충 토론·누락 보완이 결과 품질을 높인다.

모드언제 사용특성
에이전트 팀 (기본)2명 이상 협업, 실시간 조율·피드백 교환이 필요, 중간 산출물 상호 참조TeamCreate + SendMessage + TaskCreate로 자체 조율
서브 에이전트 (대안)단일 에이전트 작업, 결과만 메인에 반환하면 충분, 팀 통신 오버헤드가 과할 때Agent 도구 직접 호출, run_in_background로 병렬
하이브리드Phase마다 특성이 다를 때 — 예: 병렬 수집(서브) → 합의 기반 통합(팀)Phase 단위로 팀/서브를 섞어 구성

의사결정 순서:

  1. 먼저 에이전트 팀으로 설계 가능한지 검토한다 — 2명 이상이면 기본값
  2. 팀 통신이 구조적으로 불필요하고(결과 전달만), 팀 오버헤드가 이득보다 클 때만 서브 에이전트 선택
  3. Phase별 특성이 확연히 다르면 하이브리드 고려 — 각 Phase의 실행 모드를 오케스트레이터에 명시

상세 비교표와 패턴별 의사결정 트리는 references/agent-design-patterns.md의 "실행 모드" 참조.

2-2. 아키텍처 패턴 선택
  1. 작업을 전문 영역으로 분해
  2. 에이전트 팀 구조 결정 (아키텍처 패턴은 references/agent-design-patterns.md 참조)
    • 파이프라인: 순차 의존 작업
    • 팬아웃/팬인: 병렬 독립 작업
    • 전문가 풀: 상황별 선택 호출
    • 생성-검증: 생성 후 품질 검수
    • 감독자: 중앙 에이전트가 상태 관리 및 동적 분배
    • 계층적 위임: 상위 에이전트가 하위에 재귀적 위임
2-3. 에이전트 분리 기준

전문성·병렬성·컨텍스트·재사용성 4축으로 판단한다. 상세 기준표는 references/agent-design-patterns.md의 "에이전트 분리 기준" 참조.

Phase 3: 에이전트 정의 생성

모든 에이전트는 반드시 프로젝트/.claude/agents/{name}.md 파일로 정의한다. 에이전트 정의 파일 없이 Agent 도구의 prompt에 역할을 직접 넣는 것은 금지한다. 이유:

  • 에이전트 정의가 파일로 존재해야 다음 세션에서 재사용 가능
  • 팀 통신 프로토콜이 명시되어야 에이전트 간 협업 품질 보장
  • 하네스의 핵심 가치는 에이전트(누가)와 스킬(어떻게)의 분리

빌트인 타입(general-purpose, Explore, Plan)을 사용하더라도 에이전트 정의 파일은 생성한다. 빌트인 타입은 Agent 도구의 subagent_type 파라미터로 지정하고, 에이전트 정의 파일에는 역할·원칙·프로토콜을 담는다.

모델 설정: 모든 에이전트는 model: "opus"를 사용한다. Agent 도구 호출 시 반드시 model: "opus" 파라미터를 명시한다. 하네스의 품질은 에이전트의 추론 능력에 직결되며, opus가 최고 품질을 보장한다.

팀 재구성: 에이전트 팀은 세션당 한 팀만 활성화할 수 있지만, Phase 간에 팀을 해체하고 새 팀을 구성할 수 있다. 파이프라인 패턴처럼 Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 파일로 저장한 뒤 팀을 정리하고 새 팀을 생성한다.

각 에이전트를 프로젝트/.claude/agents/{name}.md에 정의한다. 필수 섹션: 핵심 역할, 작업 원칙, 입력/출력 프로토콜, 에러 핸들링, 협업. 에이전트 팀 모드에서는 ## 팀 통신 프로토콜 섹션을 추가하여 메시지 수신/발신 대상과 작업 요청 범위를 명시한다.

정의 템플릿과 실제 파일 전문은 references/agent-design-patterns.md의 "에이전트 정의 구조" + references/team-examples.md 참조.

QA 에이전트 포함 시 필수 사항:

  • QA 에이전트는 general-purpose 타입을 사용하라 (Explore는 읽기 전용이므로 검증 스크립트 실행 불가)
  • QA의 핵심은 "존재 확인"이 아니라 "경계면 교차 비교" — API 응답과 프론트 훅을 동시에 읽고 shape을 비교
  • QA는 전체 완성 후 1회가 아니라, 각 모듈 완성 직후 점진적으로 실행 (incremental QA)
  • 상세 가이드: references/qa-agent-guide.md 참조

Phase 4: 스킬 생성

각 에이전트가 사용할 스킬을 프로젝트/.claude/skills/{name}/SKILL.md에 생성한다. 상세 작성 가이드는 references/skill-writing-guide.md 참조.

4-1. 스킬 구조
skill-name/
├── SKILL.md (필수)
│   ├── YAML frontmatter (name, description 필수)
│   └── Markdown 본문
└── Bundled Resources (선택)
    ├── scripts/    - 반복/결정적 작업용 실행 코드
    ├── references/ - 조건부 로딩하는 참조 문서
    └── assets/     - 출력에 사용되는 파일 (템플릿, 이미지 등)
4-2. Description 작성 — 적극적 트리거 유도

description은 스킬의 유일한 트리거 메커니즘이다. Claude는 트리거를 보수적으로 판단하는 경향이 있으므로, description을 **적극적("pushy")**으로 작성한다.

나쁜 예: "PDF 문서를 처리하는 스킬" 좋은 예: "PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크, 암호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나 PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것."

핵심: 스킬이 하는 일 + 구체적 트리거 상황을 모두 기술하고, 유사하지만 트리거하면 안 되는 경우와 구분되도록 작성.

4-3. 본문 작성 원칙
원칙설명
Why를 설명하라"ALWAYS/NEVER" 같은 강압적 지시 대신, 왜 그렇게 해야 하는지 이유를 전달한다. LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다.
Lean하게 유지컨텍스트 윈도우는 공공재다. SKILL.md 본문은 500줄 이내를 목표로, 무게를 벌지 않는 내용은 삭제하거나 references/로 이동한다.
일반화하라특정 예시에만 맞는 좁은 규칙보다, 원리를 설명하여 다양한 입력에 대응할 수 있게 한다. 오버피팅 금지.
반복 코드는 번들링테스트 실행에서 에이전트들이 공통으로 작성하는 스크립트가 발견되면 scripts/에 미리 번들링한다.
명령형으로 작성"~한다", "~하라" 형태의 명령형/지시형 어조를 사용한다.
4-4. Progressive Disclosure (단계적 정보 공개)

스킬은 3단계 로딩 시스템으로 컨텍스트를 관리한다:

단계로딩 시점크기 목표
Metadata (name + description)항상 컨텍스트에 존재~100단어
SKILL.md 본문스킬 트리거 시<500줄
references/필요할 때만무제한 (스크립트는 로딩 없이 실행 가능)

크기 관리 규칙:

  • SKILL.md가 500줄에 근접하면 세부 내용을 references/로 분리하고, 본문에 "언제 이 파일을 읽으라"는 포인터를 남긴다
  • 300줄 이상의 reference 파일에는 상단에 **목차(ToC)**를 포함한다
  • 도메인/프레임워크별 변형이 있으면 references/ 하위에 도메인별로 분리하여, 관련 파일만 로드한다
cloud-deploy/
├── SKILL.md (워크플로우 + 선택 가이드)
└── references/
    ├── aws.md    ← AWS 선택 시만 로드
    ├── gcp.md
    └── azure.md
4-5. 스킬-에이전트 연결 원칙
  • 에이전트 1개 ↔ 스킬 1~N개 (1:1 또는 1:다)
  • 여러 에이전트가 공유하는 스킬도 가능
  • 스킬은 "어떻게 하는가"를 담고, 에이전트는 "누가 하는가"를 담는다

상세 작성 패턴, 예시, 데이터 스키마 표준은 references/skill-writing-guide.md 참조.

Phase 5: 통합 및 오케스트레이션

오케스트레이터는 스킬의 특수한 형태로, 개별 에이전트와 스킬을 하나의 워크플로우로 엮어 팀 전체를 조율한다. Phase 4에서 생성한 개별 스킬이 "각 에이전트가 무엇을 어떻게 하는가"를 정의한다면, 오케스트레이터는 "누가 언제 어떤 순서로 협업하는가"를 정의한다. 구체적 템플릿은 references/orchestrator-template.md 참조.

기존 확장 시 오케스트레이터 수정: 신규 구축이 아닌 기존 확장일 때는 오케스트레이터를 새로 생성하지 않고 기존 오케스트레이터를 수정한다. 에이전트 추가 시 팀 구성·작업 할당·데이터 흐름에 새 에이전트를 반영하고, description에 새 에이전트 관련 트리거 키워드를 추가한다.

Phase 2-1에서 선택한 실행 모드에 따라 오케스트레이터 패턴이 달라진다:

5-0. 오케스트레이터 패턴 (모드별)

에이전트 팀 패턴 (기본): 오케스트레이터가 TeamCreate로 팀을 구성하고, TaskCreate로 작업을 할당한다. 팀원들은 SendMessage로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다.

[오케스트레이터/리더]
    ├── TeamCreate(team_name, members)
    ├── TaskCreate(tasks with dependencies)
    ├── 팀원들이 자체 조율 (SendMessage)
    ├── 결과 수집 및 종합
    └── 팀 정리

서브 에이전트 패턴 (대안): 오케스트레이터가 Agent 도구로 서브 에이전트를 직접 호출한다. 병렬 실행은 run_in_background: true, 결과는 메인에게만 반환된다. 팀 통신이 불필요하고 오버헤드를 줄이고 싶을 때 사용.

[오케스트레이터]
    ├── Agent(agent-1, run_in_background=true)
    ├── Agent(agent-2, run_in_background=true)
    ├── 결과 대기 및 수집
    └── 통합 산출물 생성

하이브리드 패턴: Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:

  • 병렬 수집(서브) → 합의 통합(팀): Phase 2에서 서브 에이전트로 독립 자료를 병렬 수집 → Phase 3에서 팀을 만들어 토론·합의 기반 통합
  • 팀 생성(팀) → 검증(서브): Phase 2에서 팀이 초안 생성 → Phase 3에서 단일 서브 에이전트가 독립 검증
  • Phase 간 팀 재구성: 각 Phase마다 TeamDelete 후 새 TeamCreate, 사이에 서브 에이전트 호출 삽입

하이브리드 선택 시 오케스트레이터의 각 Phase 섹션 상단에 해당 Phase의 실행 모드를 명시한다 (예: **실행 모드:** 에이전트 팀).

5-1. 데이터 전달 프로토콜

오케스트레이터 내에 에이전트 간 데이터 전달 방식을 명시한다:

전략방식적용 모드적합한 경우
메시지 기반SendMessage로 팀원 간 직접 통신팀실시간 조율, 피드백 교환, 가벼운 상태 전달
태스크 기반TaskCreate/TaskUpdate로 작업 상태 공유팀진행상황 추적, 의존 관계 관리, 작업 자체 요청
파일 기반약속된 경로에 파일을 쓰고 읽음팀 + 서브대용량 데이터, 구조화된 산출물, 감사 추적 필요
반환값 기반Agent 도구의 반환 메시지서브서브 에이전트 결과를 메인이 직접 수집

권장 조합 (팀 모드): 태스크 기반(조율) + 파일 기반(산출물) + 메시지 기반(실시간 소통) 권장 조합 (서브 모드): 반환값 기반(결과 수집) + 파일 기반(대용량 산출물) 하이브리드: 각 Phase의 실행 모드에 맞춰 해당 조합 적용

파일 기반 전달 시 규칙:

  • 작업 디렉토리 하위에 _workspace/ 폴더를 만들어 중간 산출물 저장
  • 파일명 컨벤션: {phase}_{agent}_{artifact}.{ext} (예: 01_analyst_requirements.md)
  • 최종 산출물만 사용자 지정 경로에 출력, 중간 파일(_workspace/)은 보존 (사후 검증·감사 추적용)
5-2. 에러 핸들링

오케스트레이터 내에 에러 처리 방침을 포함한다. 핵심 원칙: 1회 재시도 후 재실패 시 해당 결과 없이 진행(보고서에 누락 명시), 상충 데이터는 삭제하지 않고 출처 병기.

에러 유형별 전략표와 구현 상세는 references/orchestrator-template.md의 "에러 핸들링" 참조.

5-3. 팀 크기 가이드라인
작업 규모권장 팀원 수팀원당 작업 수
소규모 (5~10개 작업)2~3명3~5개
중규모 (10~20개 작업)3~5명4~6개
대규모 (20개+ 작업)5~7명4~5개

팀원이 많을수록 조율 오버헤드가 커진다. 3명의 집중된 팀원이 5명의 산만한 팀원보다 낫다.

5-4. CLAUDE.md 하네스 포인터 등록

하네스 구성 완료 후, 프로젝트의 CLAUDE.md에 최소한의 포인터를 등록한다. CLAUDE.md는 새 세션마다 로딩되므로, 하네스 존재와 트리거 규칙만 기록하면 오케스트레이터 스킬이 나머지를 처리한다.

CLAUDE.md 템플릿:

## 하네스: {도메인명}

**목표:** {하네스의 핵심 목표 한 줄}

**트리거:** {도메인} 관련 작업 요청 시 `{orchestrator-skill-name}` 스킬을 사용하라. 단순 질문은 직접 응답 가능.

**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| {YYYY-MM-DD} | 초기 구성 | 전체 | - |

CLAUDE.md에 넣지 않는 것: 에이전트 목록, 스킬 목록, 디렉토리 구조, 실행 규칙 상세. 이유: 에이전트/스킬 목록은 오케스트레이터 스킬과 .claude/agents/, .claude/skills/에서 관리하므로 중복이다. 디렉토리 구조는 파일 시스템에서 직접 확인 가능하다. CLAUDE.md는 포인터(트리거 규칙) + 변경 이력만 담는다.

5-5. 후속 작업 지원

오케스트레이터는 초기 실행뿐 아니라 후속 작업도 처리해야 한다. 다음 세 가지를 보장하라:

1. 오케스트레이터 description에 후속 키워드 포함: 초기 생성 키워드만으로는 후속 요청이 트리거되지 않는다. description에 반드시 포함할 후속 표현:

  • "다시 실행", "재실행", "업데이트", "수정", "보완"
  • "{도메인}의 {부분작업}만 다시"
  • "이전 결과 기반으로", "결과 개선"

2. 오케스트레이터 Phase 1에 컨텍스트 확인 단계 추가: 워크플로우 시작 시 기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다:

  • _workspace/ 존재 + 사용자가 부분 수정 요청 → 부분 재실행 (해당 에이전트만 재호출)
  • _workspace/ 존재 + 사용자가 새 입력 제공 → 새 실행 (기존 _workspace를 _workspace_prev/로 이동)
  • _workspace/ 미존재 → 초기 실행

3. 에이전트 정의에 재호출 지침 포함: 각 에이전트 .md 파일에 "이전 산출물이 있을 때의 행동"을 명시한다:

  • 이전 결과 파일이 존재하면 읽고 개선점을 반영
  • 사용자 피드백이 주어지면 해당 부분만 수정

오케스트레이터 템플릿의 "Phase 0: 컨텍스트 확인" 섹션 참조: references/orchestrator-template.md

5-6. 알토스(Atlas) 등록 — 필수, 건너뛰기 금지

하네스 구성이 워크플로우나 launchd 자동화를 포함하면 반드시 알토스 대시보드(~/Projects/atlas/)에 등록한다. 등록 3종 세트:

  1. 도식: ~/Projects/atlas/flows/{slug}.mmd — 헤더 4줄(title/project/code/trigger) + click X call atlasInfo("...") 주석. 검증: 헤더 떼고 npx -y @mermaid-js/mermaid-cli -i <파일> -o /tmp/check.svg (mermaid 10 함정은 알토스 CLAUDE.md 참조)
  2. 자동화 한글 라벨: 새 launchd 잡마다 ~/Projects/atlas/scan.py의 AUTOMATION_LABELS에 "라벨": ("한글이름","설명","카테고리") 추가
  3. 상태 배지: scan.py의 FLOW_LAUNCHD에 'slug': 'launchd라벨' 매핑 (+ skill_categories.py 카테고리 배치)

등록 후 python3 ~/Projects/atlas/scan.py 1회 실행으로 즉시 반영 확인. 스킬 카드는 자동 스캔이라 등록 불필요. 백스톱: scan.py에 미등록 감지기가 하드코딩되어 있어(2026-07-07) 등록을 빼먹은 launchd 잡은 대시보드에 "⚠️ 미등록 자동화" 경고로 뜨고 scan.log에 기록된다 — 경고가 보이면 이 섹션대로 등록하라.

Phase 6: 검증 및 테스트

생성된 하네스를 검증한다. 상세 테스트 방법론은 references/skill-testing-guide.md 참조.

6-1. 구조 검증
  • 모든 에이전트 파일이 올바른 위치에 있는지 확인
  • 스킬의 frontmatter(name, description) 검증
  • 에이전트 간 참조 일관성 확인
  • 커맨드가 생성되지 않았는지 확인
6-2. 실행 모드별 검증
  • 에이전트 팀: 팀원 간 통신 경로, 작업 의존성, 팀 크기 적정성 확인
  • 서브 에이전트: 각 에이전트의 입출력 연결, run_in_background 설정, 반환값 수집 로직 확인
  • 하이브리드: 각 Phase의 실행 모드가 오케스트레이터에 명시되었는지, Phase 경계에서 데이터 전달이 끊기지 않는지 확인 (팀 → 서브 전환 시 팀의 산출물이 서브의 입력으로 연결되는지)
6-3. 스킬 실행 테스트

생성된 각 스킬에 대해 실제 실행 테스트를 수행한다:

  1. 테스트 프롬프트 작성 — 각 스킬에 대해 2~3개의 현실적인 테스트 프롬프트를 작성한다. 실제 사용자가 입력할 법한 구체적이고 자연스러운 문장으로 작성한다.

  2. With-skill vs Without-skill 비교 실행 — 가능하면 스킬 있는 실행과 없는 실행을 병렬로 수행하여 스킬의 부가가치를 확인한다. 에이전트를 두 개씩 스폰한다:

    • With-skill: 스킬을 읽고 작업 수행
    • Without-skill (baseline): 같은 프롬프트를 스킬 없이 수행
  3. 결과 평가 — 산출물의 품질을 정성적(사용자 리뷰) + 정량적(assertion 기반) 으로 평가한다. 산출물이 객관적으로 검증 가능한 경우(파일 생성, 데이터 추출 등) assertion을 정의하고, 주관적인 경우(문체, 디자인) 사용자 피드백에 의존한다.

  4. 반복 개선 루프 — 테스트 결과에서 문제가 발견되면:

    • 피드백을 일반화하여 스킬을 수정한다 (특정 예시에만 맞는 좁은 수정 금지)
    • 수정 후 재테스트한다
    • 사용자가 만족하거나 의미 있는 개선이 더 이상 없을 때까지 반복한다
  5. 반복 패턴 번들링 — 테스트 실행에서 에이전트들이 공통으로 작성하는 코드(예: 모든 테스트에서 동일한 헬퍼 스크립트를 생성)가 발견되면, 해당 코드를 scripts/에 미리 번들링한다.

6-4. 트리거 검증

각 스킬의 description이 올바르게 트리거되는지 검증한다:

  1. Should-trigger 쿼리 (8~10개) — 스킬을 트리거해야 하는 다양한 표현 (공식적/캐주얼, 명시적/암시적)
  2. Should-NOT-trigger 쿼리 (8~10개) — 키워드가 유사하지만 이 스킬이 아닌 다른 도구/스킬이 적합한 "near-miss" 쿼리

near-miss 작성 핵심: "피보나치 함수 작성" 같이 명백히 무관한 쿼리는 테스트 가치가 없다. "이 엑셀 파일의 차트를 PNG로 추출해줘" (xlsx 스킬 vs 이미지 변환)처럼 경계가 모호한 쿼리가 좋은 테스트 케이스다.

기존 스킬과의 트리거 충돌도 이 단계에서 확인한다.

6-5. 드라이런 테스트
  • 오케스트레이터 스킬의 Phase 순서가 논리적인지 검토
  • 데이터 전달 경로에 빈 구간(dead link)이 없는지 확인
  • 모든 에이전트의 입력이 이전 Phase의 출력과 매칭되는지 확인
  • 에러 시나리오별 폴백 경로가 실행 가능한지 확인
6-6. 테스트 시나리오 작성
  • 오케스트레이터 스킬에 ## 테스트 시나리오 섹션 추가
  • 정상 흐름 1개 + 에러 흐름 1개 이상 기술

Phase 7: 하네스 진화

하네스는 한 번 만들고 끝나는 정적 산출물이 아니다. 사용자 피드백에 따라 계속 진화하는 시스템이다.

7-1. 실행 후 피드백 수집

매 하네스 실행 완료 후, 사용자에게 피드백을 요청한다:

  • "결과에서 개선할 부분이 있나요?"
  • "에이전트 팀 구성이나 워크플로우에 바꾸고 싶은 점이 있나요?"

피드백이 없으면 넘어간다. 강요하지 않되, 반드시 기회를 제공한다.

7-2. 피드백 반영 경로

피드백 유형에 따라 수정 대상이 다르다:

피드백 유형수정 대상예시
결과물 품질해당 에이전트의 스킬"분석이 너무 피상적" → 스킬에 깊이 기준 추가
에이전트 역할에이전트 정의 .md"보안 검토도 필요" → 새 에이전트 추가
워크플로우 순서오케스트레이터 스킬"검증을 먼저 해야" → Phase 순서 변경
팀 구성오케스트레이터 + 에이전트"이 둘은 합쳐도 될 듯" → 에이전트 병합
트리거 누락스킬 description"이 표현으로 하면 작동 안 함" → description 확장
7-3. 변경 이력

모든 변경은 CLAUDE.md의 변경 이력 테이블에 기록한다 (Phase 5-4 템플릿의 "변경 이력" 섹션과 동일 테이블):

**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| 2026-04-05 | 초기 구성 | 전체 | - |
| 2026-04-07 | QA 에이전트 추가 | agents/qa.md | 산출물 품질 검증 부족 피드백 |
| 2026-04-10 | 톤 가이드 추가 | skills/content-creator | "너무 딱딱하다" 피드백 |

이 이력을 통해 하네스가 어떤 방향으로 진화했는지 추적하고, 퇴행(regression)을 방지한다.

7-4. 진화 트리거

사용자가 명시적으로 "하네스 수정해줘"라고 할 때만이 아니라, 다음 상황에서도 진화를 제안한다:

  • 같은 유형의 피드백이 2회 이상 반복될 때
  • 에이전트가 반복적으로 실패하는 패턴이 발견될 때
  • 사용자가 오케스트레이터를 우회하여 수동으로 작업하는 것이 관찰될 때
7-5. 운영/유지보수 워크플로우

기존 하네스의 점검·수정·동기화를 체계적으로 수행한다. Phase 0에서 "운영/유지보수" 분기로 진입했을 때 이 워크플로우를 따른다.

Step 1: 현황 감사

  • .claude/agents/ 파일 목록과 오케스트레이터 스킬의 에이전트 구성 비교 → 불일치 목록 생성
  • .claude/skills/ 디렉토리 목록과 오케스트레이터 스킬의 스킬 구성 비교 → 불일치 목록 생성
  • 감사 결과를 사용자에게 보고한다

Step 2: 점진적 추가/수정

  • 사용자 요청에 따라 에이전트 추가/수정/삭제, 스킬 추가/수정/삭제를 수행한다
  • 변경은 한 번에 하나씩, 각 변경 후 즉시 Step 3(동기화)을 실행한다

Step 3: CLAUDE.md 변경 이력 갱신

  • 변경 이력 테이블에 날짜, 변경 내용, 대상, 사유를 기록한다

Step 4: 변경 검증

  • 수정된 에이전트/스킬의 구조 검증 (Phase 6-1 기준)
  • 수정 범위가 트리거에 영향을 주면 트리거 검증 (Phase 6-4 기준)
  • 대규모 변경(아키텍처 변경, 에이전트 3개 이상 추가/삭제) 시 Phase 6-3(실행 테스트), 6-5(드라이런)까지 수행
  • CLAUDE.md와 실제 파일의 일치 여부 최종 확인

산출물 체크리스트

생성 완료 후 확인:

  • 프로젝트/.claude/agents/ — 에이전트 정의 파일 필수 생성 (빌트인 타입이라도 파일 생성 필수)
  • 프로젝트/.claude/skills/ — 스킬 파일들 (SKILL.md + references/)
  • 오케스트레이터 스킬 1개 (데이터 흐름 + 에러 핸들링 + 테스트 시나리오 포함)
  • 실행 모드 명시 (에이전트 팀 / 서브 에이전트 / 하이브리드 중 선택, 하이브리드면 Phase별 모드 기재)
  • 모든 Agent 호출에 model: "opus" 파라미터 명시
  • .claude/commands/ — 아무것도 생성하지 않음
  • 기존 에이전트/스킬과 충돌 없음
  • 스킬 description이 적극적("pushy")으로 작성됨 — 후속 작업 키워드 포함
  • SKILL.md 본문이 500줄 이내, 초과 시 references/ 분리
  • 테스트 프롬프트 2~3개로 실행 검증 완료
  • 트리거 검증 (should-trigger + should-NOT-trigger) 완료
  • CLAUDE.md에 하네스 포인터 등록 (트리거 규칙 + 변경 이력)
  • CLAUDE.md 변경 이력에 에이전트/스킬 추가/삭제/수정 기록
  • 오케스트레이터 Phase 1에 컨텍스트 확인 단계 (초기/후속/부분 재실행 판별)
  • 알토스 등록 3종 세트 (Phase 5-6) — 워크플로우/launchd 포함 하네스면 필수: flows/*.mmd 도식 + AUTOMATION_LABELS + FLOW_LAUNCHD, python3 scan.py로 반영 확인

참고

  • 하네스 패턴: references/agent-design-patterns.md
  • 기존 하네스 예시 (실제 파일 전문 포함): references/team-examples.md
  • 오케스트레이터 템플릿: references/orchestrator-template.md
  • 스킬 작성 가이드: references/skill-writing-guide.md — 작성 패턴, 예시, 데이터 스키마 표준
  • 스킬 테스트 가이드: references/skill-testing-guide.md — 테스트/평가/반복 개선 방법론
  • QA 에이전트 가이드: references/qa-agent-guide.md — 빌드 하네스에 QA 에이전트를 포함할 때 참조. 통합 정합성 검증 방법론, 경계면 버그 패턴, QA 에이전트 정의 템플릿 포함. 실제 프로젝트에서 발견된 7개 버그 사례 기반.

Humanize Korean — AI 한글 티 제거 오케스트레이터 (v1.5)

v1.5 변경 고지 (2026-04-26) — v1.1 베이스라인 + Monolith Fast Path v1.2(voice profile)·v1.3(candidate pool)·v1.4(역할별 모델 분산)는 모두 핫패스 비용을 잡지 못해 5,000자 입력에 25분이 걸렸습니다. v1.5는 v1.1 단순 구조로 롤백한 뒤 단일 호출 monolith 에이전트만 추가한 설계입니다.

  • Fast 모드(디폴트) — humanize-monolith 에이전트가 한 콜에서 탐지·윤문·자체검증 일괄 처리. 도구 호출 45회. 5,000자 이하 wall-clock 23분 목표.
  • Strict 모드(--strict) — v1.1 5인 파이프라인 그대로(detector·rewriter·auditor·reviewer + taxonomist 분류 자산 유지). 정밀 검증·장문(8,000자+) 처리·etc.
  • 삭제됨: voice profile·candidate pool·promotion-checklist·sample-collection·권한 위계 §1~§6.
  • 유지됨: 분류 체계 본진(C-9·C-10·D-7·H-3·I-3·I-4 등 v1.2~v1.3.1 신규 패턴)·rewriting-playbook·5인 에이전트 정의(strict 모드 백본).

Phase 0: 컨텍스트 확인 및 모드 결정

작업 시작 시 가장 먼저 다음 한 줄을 사용자에게 출력한다.

humanize-korean v1.5 — {fast|strict} 모드 / run_id: {YYYY-MM-DD-NNN}

모드 결정

  • 사용자가 --strict·"정밀 모드"·"5인 파이프라인" 명시 → strict
  • 입력 8,000자 초과 → strict (자동 승급 + 사용자에 1줄 고지)
  • 그 외 모두 → fast (디폴트)

run_id 결정

  • 모든 경로는 cwd 기준. 새 폴더 생성도 cwd 기준 _workspace/{YYYY-MM-DD-NNN}/에 만든다.
  • 기존 시퀀스 확인은 Glob 도구로 표지 파일을 매칭해 간접 조회. 올바른 사용법: Glob(pattern="_workspace/YYYY-MM-DD-*/01_input.txt") → 결과에서 폴더명 추출 후 NNN 최댓값 + 1. 주의: Glob은 디렉토리 자체는 매칭하지 못한다. 반드시 그 안의 표지 파일(01_input.txt)을 매칭할 것. Bash ls는 OS·셸 환경에 따라 경로 해석이 달라지므로 사용 금지.
  • 당일 폴더가 없으면 NNN = 001. 있으면 마지막 NNN + 1.
  • 부분 재실행 신호("이 카테고리만 다시"·"2차 윤문")일 경우 기존 run_id 재사용 + strict 모드로 자동 승급.

Fast 모드 (디폴트)

Phase 1: 입력 저장

  1. cwd 기준 _workspace/{run_id}/ 생성
  2. 입력 텍스트를 01_input.txt에 저장
  3. 첫 300자로 장르 자동 추정 (사용자 명시 시 우선)

Phase 2: Monolith 호출

humanize-monolith 에이전트를 Agent 도구로 1회 호출.

입력:

input_path: <abs path>/_workspace/{run_id}/01_input.txt
quick_rules_path: ${CLAUDE_SKILL_DIR}/references/quick-rules.md
genre_hint: 칼럼 | 리포트 | 블로그 | 공적 | null

출력 (에이전트가 직접 작성):

  • _workspace/{run_id}/final.md — 윤문본
  • _workspace/{run_id}/summary.md — 메트릭·자체검증·하이라이트

monolith는 단일 호출 안에서 다음을 모두 수행 (자세히는 에이전트 정의 참조):

  1. quick-rules 룰북 로드 → 메모리에서 패턴 탐지 + 윤문 + 자체검증 6항 점검
  2. 변경률 50% 초과 시 자동 롤백
  3. 자체검증 위반 시 1회 부분 재실행
  4. final.md + summary.md 작성

Phase 3: 결과 전달

사용자에게 다음 4개를 반환:

  1. 한 줄 상태: 완료. 변경률 X% / 등급 Y / 자체검증 N/6 통과
  2. 윤문본 본문 (마크다운 블록)
  3. summary.md의 핵심 표 (메트릭 + 카테고리 탐지 + 자체검증)
  4. 등급 B 이하면 "정밀 검증이 필요하면 --strict로 5인 파이프라인" 안내

디폴트 wall-clock 목표: 5,000자 이하 23분, 8,000자 57분.

Strict 모드 (--strict 또는 자동 승급)

v1.1 5인 파이프라인 그대로. 검증 분리·재윤문 루프가 의미 있을 때만 사용.

Phase A: 탐지

ai-tell-detector 호출 → 02_detection.json

Phase B: 윤문 (최대 3회 루프)

korean-style-rewriter 호출 → 03_rewrite.md + 03_rewrite_diff.json

Phase C: 병렬 검증 (에이전트 팀)

TeamCreate로 humanize-review-team 구성:

  • content-fidelity-auditor → 04_fidelity_audit.json (의미 동등성)
  • naturalness-reviewer → 05_naturalness_review.json (잔존·과윤문)

TeamDelete 후 종합 판정 매트릭스에 따라 분기:

fidelitynaturalness종합후속
full_passaccept / accept_with_note최종 승인Phase D
full_passrewrite_round_22차 윤문Phase B 재호출 (target finding)
full_passrollback_and_rewrite롤백 후 재윤문윤문가에 edit 롤백 지시
conditional_pass-롤백된 edit만 재시도Phase B 재호출
fail-전면 재작업Phase B 전면 재호출

2차/3차 윤문 진입 시 03_rewrite_v2.md·v3.md로 버전 분리. **최대 3회 후 미해결이면 hold_and_report**로 사람 개입.

Phase D: 최종 출력

  1. final.md에 최종 윤문본 복사
  2. summary.md 생성 (fast 모드와 동일 포맷)
  3. 사용자에게 결과 + 등급 + 안내

부분 재실행 / 후속 명령

사용자 신호처리
"특정 카테고리만 다시"strict 모드로 자동 전환, 해당 카테고리 finding만 Phase B 재실행
"이 문단만"strict 모드, 해당 문단만 입력으로 새 run_id 생성
"2차 윤문"·"/humanize-redo"기존 run_id의 final.md를 새 입력으로 strict Phase B 재실행
"윤문 강도 조정"strict 모드, min_severity 옵션 변경 후 Phase A부터 재실행
"장르 바꿔서"genre_hint 변경 후 Phase A부터 재실행

옵션 (인자 끝에 자연어로)

  • 장르: 칼럼|리포트|블로그|공적 — 장르 명시 (생략 시 자동 추정)
  • 강도: 보수|기본|적극 — 윤문 강도 (기본값: 기본)
  • 최소심각도: S1|S2|S3 — 탐지 임계값 (기본값: S2)
  • --strict — 5인 파이프라인 강제 사용

데이터 흐름 요약

Fast 모드 (디폴트)

01_input.txt
    ↓ [humanize-monolith — 단일 호출]
    ├ 메모리: quick-rules 로드 → 탐지 → 윤문 → 자체검증
    └→ final.md + summary.md

Strict 모드

01_input.txt
    ↓ [ai-tell-detector]
02_detection.json
    ↓ [korean-style-rewriter]
03_rewrite.md + 03_rewrite_diff.json
    ↓ [병렬 팀]
    ├→ [content-fidelity-auditor] → 04_fidelity_audit.json
    └→ [naturalness-reviewer]      → 05_naturalness_review.json
    ↓ [오케스트레이터 종합]
    ├→ (재작업) Phase B로 복귀 (최대 3회)
    └→ (승인) final.md + summary.md

에이전트 호출 규칙

모델: 모두 model: opus 통일 (v1.1 베이스라인). 모델 다운그레이드는 v1.4에서 시도했으나 도구 호출 chain이 진짜 병목이라 효과 미미했음.

에이전트 정의 위치: 저장소 루트 agents/에 12종 정의(플러그인 컨벤션). Claude Code 탐색 경로:

  1. 플러그인 설치 시 — humanize-korean 플러그인이 agents/를 번들로 제공(전역).
  2. 스크립트 설치 시 — install.sh가 agents/*.md를 ~/.claude/agents/에 심링크(전역).

필요 에이전트 6종:

  • humanize-monolith (v1.5 신규, fast 전용)
  • ai-tell-detector · korean-style-rewriter · content-fidelity-auditor · naturalness-reviewer (strict 5인 중 4명)
  • korean-ai-tell-taxonomist (분류 체계 유지·확장 — 본 스킬 실행 중에는 호출 안 됨, 별도 명령으로만 트리거)

테스트 시나리오

Fast 정상 흐름

  • 입력: ChatGPT가 생성한 AI 칼럼 초안 (2,000~5,000자, 번역투·결말 공식·hype 어휘 풍부)
  • 기대: monolith 1콜로 변경률 1525%, 등급 A/B, wall-clock 23분, 자체검증 5~6/6

Strict 정밀 검증 흐름

  • 사용자 명시 --strict 또는 8,000자+ 입력
  • 5인 파이프라인 끝까지 실행, 변경률 18~22%, 검증팀 full_pass

엣지 케이스 — 이미 사람이 쓴 글

  • monolith 자체 탐지에서 매치 거의 없음 → 변경률 5% 미만 + summary.md에 "윤문 불필요 가능성" 메모
  • 사용자가 --strict로 강제 검증 가능

주의 사항

  • 의미 불변이 최상위 불문율. monolith·strict 모두에서 위반 즉시 롤백.
  • 수치·고유명사·직접 인용은 탐지/윤문 대상 아님. Do-NOT list 엄수.
  • 장르 이탈 금지. 칼럼이 에세이로, 에세이가 문학으로 옮겨가지 않는다.
  • register 보존. 격식체 입력 → 격식체 출력. AI 티는 문법·수사이지 격식 자체가 아님.
  • 변경률 30% 초과 → 경고, 50% 초과 → 강제 중단.
  • 자동 로드 금지. 프로젝트 CLAUDE.md 등 다른 파일을 자동 파싱해 옵션을 추론하지 않는다.

참고 자료

출처

이 스킬의 분류 체계는 내가 만든 것이 아니다. 외부 연구를 가져와 세운 것이다.

  • 한국 번역학계 번역투 연구 — 8대 번역투 유형이 분류 체계의 뼈대다. 이영옥(2001) 「무생물 주어 타동사구문의 영한번역」 번역학연구 2(1): 53-76 을 비롯해 윤미선·김택민·임진주·홍승연(2018), 이상빈(2017·2018a·2018b), 마승혜(2018), 김혜림(2022), 김혜영(2019) 등.
  • KatFish 정량 보고서 — 인간/AI 텍스트의 어절 수, POS 다양성, 한자어 명사화 밀도 같은 수치 임계값은 이 보고서에서 가져왔다. (예: 에세이 평균 어절 인간 4.35 vs AI 8.56)
  • arXiv 계열 AI 텍스트 탐지 연구 — 일부 지표 정의를 참고했다.

학자 이름·연도·저널·페이지는 references/scholarship.md에 원문 그대로 보존돼 있다. 자체 추정이나 확장 없이 옮겼다.

내가 더한 부분은 이것뿐이다 — 한국어 실무에서 반복적으로 지적받은 표현 (~가 아니라 대조 구문, 여정, 굴러가다, 방어적 안심 문장 등)을 금지어로 추가하고, 윤문 강도를 Fast/Strict로 나눠 실제 원고에 돌 수 있게 절차화한 것.

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • macOS 전용입니다. 접근성(Accessibility) 권한이 필요합니다.
  • 외부 도구 kmsg/kakaocli를 통해 카카오톡 앱을 조작하고 로컬 메시지 DB를 읽습니다.
  • 메시지 내용을 외부로 전송하지 않습니다. 전부 로컬에서 처리됩니다.
  • 접근성 권한은 화면의 다른 앱도 조작할 수 있는 강한 권한입니다. 부여 전에 이해하고 결정하세요.

카카오톡 보내기·읽기

정본 도구는 kmsg다. kakaocli send는 쓰지 않는다 — 화면에 렌더링된 채팅 목록만 훑어서 아래로 밀린 방을 못 찾고, DB 키를 받는 옵션도 없다.

왜 SSH를 거치나

Aside 샌드박스는 GUI 실행·AX(손쉬운 사용)·타 프로세스 조회가 전부 막혀 있다. 그래서 모든 명령은 SSH 루프백으로 샌드박스 밖에서 실행한다.

ssh -o BatchMode=yes localhost 'export PATH=/opt/homebrew/bin:$PATH; kmsg ...'

kakaocli status가 "App state: notRunning"이라고 해도 믿지 말 것. 샌드박스가 프로세스를 못 볼 뿐 카톡은 대개 켜져 있다.

선행 조건(2026-08-15 부여 완료): /usr/libexec/sshd-keygen-wrapper에 시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용 권한. 없으면 모든 AX 호출이 -25211로 막힌다.

절차

# 1. 상태와 열린 창 확인 — 이 단계를 건너뛰지 말 것
kmsg status --verbose

# 2. (메인 창 외에 채팅 창이 열려 있으면 닫는다)

# 3. 보낼 내용을 파일로 빼서 따옴표 문제를 피한다
kmsg send "<방이름>" "$(cat /path/msg.txt)"

# 4. 실제로 나갔는지 읽어서 확인
kmsg read "<방이름>" --limit 1 --json
  • kmsg send는 성공 후 방 창을 닫는다. 그래서 직후 kmsg read는 창이 없다며 실패한다. 발송 검증은 kakaocli messages --chat-id ... --key로 DB를 보거나, 창을 다시 열고 읽는다.
  • 방은 이름 substring 또는 --chat-id로 지정한다. kmsg chats --json로 목록.
  • 보내기 전 --dry-run으로 수신자를 한 번 확인한다.
  • 나와의 채팅은 나와의 채팅이 아니라 프로필명 태현-밤밤으로 지정한다.
  • 처음 보내는 상대이거나 내용이 길면 먼저 태현-밤밤으로 연습 발송해 서식을 확인한다.

AI가 보냈다는 표시 (필수)

카톡은 밤밤 본인 명의로 나가므로, 대신 보내는 전달·공지·안내성 메시지에는 본문 맨 끝에 서명 한 줄을 붙인다.

— 이 메시지는 밤밤을 대신해 AI가 정리해서 보냈습니다

밤밤이 2026-08-15에 직접 요청했다("디스코드 봇은 그렇게 해주잖아"). 디스코드는 밤냥이 봇 계정이라 이미 드러나지만 카톡은 안 드러난다는 게 이유. 개인 브랜드 콘텐츠(블로그·스레드·링크드인)는 예외.

단톡방에 보낼 때

  • 진짜 @멘션은 걸 수 없다. 카톡 멘션은 @ 입력 시 뜨는 멤버 선택 팝업에서 골라야 생기고, 자동 입력은 그 팝업 때문에 문장이 깨질 위험이 있다. 이름을 본문에 나열하는 방식으로 쓰고, 하이라이트가 필요하면 밤밤이 직접 단다.
  • 여러 명이 읽는 메시지는 먼저 태현-밤밤으로 연습 발송해 서식을 확인하고, 밤밤 승인을 받은 뒤 보낸다.

실패하면

증상원인과 조치
[SEARCH_MISS] Search field not found다른 채팅 창이 열려 있다. 닫고 --refresh-cache
같은 오류인데 창이 메인 하나뿐방 창이 막 열리는 중이라 AX 캐시가 어긋난 것. 그대로 --refresh-cache로 한 번만 재시도하면 나간다(2026-08-16 실측). 첫 실패로 발송이 안 된 것이 맞는지 kakaocli messages로 먼저 확인할 것
[WINDOW_NOT_READY]같은 원인. open -a KakaoTalk 후 재시도
[BACKGROUND_SAFE_BLOCKED]--background-safe는 이미 열린 창만 읽는다. 정상 동작
방을 못 찾음kmsg chats --limit 200 --json로 이름 확인

하지 말 것

  • kmsg harvest류의 메타데이터 재수집을 실행하지 말 것. kakaocli harvest가 ~/.kakaocli/metadata.json의 방 이름을 전부 (unknown)으로 덮어쓴 사고가 있었다. 백업: ~/.kakaocli/backups/
  • AppleScript keystroke로 한글을 치지 말 것 — ㅁㅁㅁ으로 깨진다. SSH pbcopy도 GUI 페이스트보드에 닿지 않는다.
  • 대량 발송·무인 자동응답 봇으로 확장하지 말 것. 카카오 운영정책에 자동화 프로그램 이용 제한이 있고 계정 제재 가능성이 있다. 밤밤이 2026-08-15에 무인 자동응답은 돌리지 않겠다고 명시했다.

참고

  • 읽기 전용 대량 조회·검색이 필요하면 kakaocli(DB 직접 복호화)를 쓴다. 키는 맥미니 ~/Projects/seocho-ai-festa/dashboard/.env의 KAKAOCLI_KEY이며 --key로 넘긴다(환경변수는 읽지 않는다). 절대 출력하지 말 것.
  • 전체 배경·폴백(수동 AX 주입)·AppleScript 함정: ~/.aside/u/0/memory/agent/kakaotalk-send-procedure.md
  • 무인 상시 운영이 필요해지면: ~/.aside/u/0/memory/agent/unattended-mac-agent-xpair.md

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • 화면 캡처 이미지를 읽고 가공한 이미지를 새로 만듭니다. 원본은 수정하지 않습니다.
  • 개인정보 영역을 모자이크·블러 처리하는 단계가 포함됩니다. 최종 확인은 사람이 하세요.

측정 기반 실물 화면 콜아웃

실제 화면을 장식용 이미지로 재제작하지 말고, 원본 화면을 증거 자료로 유지한다.

작업 순서

  1. 원본 화면에서 강조 대상과 개인정보 영역을 먼저 구분한다.
  2. 실제 DOM 화면이면 대상 요소의 getBoundingClientRect()를 측정한다. 눈대중 좌표를 사용하지 않는다.
  3. DOM이 없는 캡처 이미지면 원본 픽셀에서 셀 경계와 텍스트 영역을 측정한 뒤, 렌더링 배율·이동값으로 변환한다.
  4. 개인정보는 원래 셀 경계를 유지한 채 해당 영역만 모자이크 또는 블러 처리한다. 회색 박스로 넓게 덮어 원본 구조를 가리지 않는다.
  5. 강조 박스는 설명하는 대상 하나만 감싼다. 주변 빈 영역, 다른 행, 버튼을 함께 감싸지 않는다.
  6. 제목·설명·브랜드 라벨과 실제 화면 카드 사이에 충분한 여백을 둔다. 카드가 제목 글자의 하단을 덮지 않도록 제목의 실제 bounding box보다 아래에 배치한다.
  7. 최종 캔버스 전체를 캡처하고 제목, 카드, 하단 설명, 콜아웃이 모두 캔버스 안에 들어오는지 확인한다. 부분 clip으로 잘린 결과를 완성본으로 쓰지 않는다.
  8. GIF는 첫 프레임만 보지 않는다. 모든 대표 프레임에서 강조 위치, 개인정보 가림, 제목 잘림 여부를 확인한다.

필수 검수

  • 원본 화면의 작업 내용은 변경하지 않았는가
  • 실명, 주소, 전화번호, 특허고객번호, 전체 출원번호, 접수번호, 결제·인증 정보가 남지 않았는가
  • 강조 박스가 실제 설명 대상과 정확히 일치하는가
  • 제목과 설명이 상단 카드에 가려지거나 캔버스 밖으로 잘리지 않았는가
  • 정적 이미지와 GIF의 캔버스 비율·표시 크기가 일관적인가
  • 공개 발행 전 브라우저에서 실제 표시 크기로 다시 확인했는가

프로젝트 회의록 발행

디스코드 음성 회의 → 전사본 수신 → 회의록 작성 → 노션 등록 → 디스코드 공지까지의 정본 절차.

프로젝트 개요·인물·일정은 볼트 프로젝트/프로젝트.md 참조. 작업 폴더: ~/Projects/<프로젝트>/이벤트/버추얼 프로젝트

1. 전사본 받기

프로젝트 조사봇이 회의 종료 후 사용자 DM으로 transcript.md를 보낸다.

cd "~/Projects/<프로젝트>/이벤트/버추얼 프로젝트"
TOKEN=$(grep '^프로젝트_DISCORD_BOT_TOKEN=' .env | cut -d= -f2-)
CH=$(curl -s -X POST -H "Authorization: Bot $TOKEN" -H "Content-Type: application/json" \
  -H "User-Agent: DiscordBot (https://github.com/bambam/twc-pm, 1.0)" \
  -d '{"recipient_id":"<DISCORD_ID>"}' \
  "https://discord.com/api/v10/users/@me/channels" \
  | python3 -c "import json,sys;print(json.load(sys.stdin)['id'])")
bash scripts/twc-dm-download-transcripts.sh "$CH" "회의록 전사/_dm받은전사" 5

원본은 원격 머신 ~/Projects/<프로젝트>/recordings/<ISO시각>_1515265088167346317/ 에도 있다. 저장되는 건 발화자별 음성(.ogg/.pcm)과 transcript.md뿐 — 화면 영상은 없다.

받자마자 유실 여부를 확인한다 (2026-08-18 사고 후)

전사본을 열어 "(전사된 발언이 없습니다)"이거나 발화수가 비정상으로 적으면 보령을 본다.

ssh remote-host 'grep -E "녹음 시작|디코더 오류|전사 완료" ~/Projects/<프로젝트>/logs/bot.log | tail -20'

디코더 오류 <userId> The compressed data passed is corrupted 가 보이면 그 사람은 그 시점 이후 녹음이 안 된 것이다. 녹음 시작 직후(수 ms 내)에 뜨면 그 참석자 발언은 회의 전체가 없다. 봇이 들어올 때 이미 말하고 있던 사람이 걸린다.

  • 원인이던 봇 버그(디코딩 실패 후 재구독 안 함)는 2026-08-19에 수정했고, 이제 발화 0건이거나 음성 0바이트인 참석자가 있으면 DM 상단에 경고 배너가 붙는다.
  • 그래도 유실이 생기면 지어내지 말고, 회의록 상단 콜아웃에 "전사 유실 · 무엇을 근거로 썼는지"를 명시하고 참석자에게 DM으로 보완을 요청한다. 사례: 회차 18(8/18).

⚠️ 유실이면 발행보다 사본 요청이 먼저다

봇 녹음이 없다고 기록이 없는 게 아니다. 참석자가 개인 녹취를 갖고 있을 수 있다. 회의 주변 텍스트(디스코드 후속 대화)로 재구성한 문서를 먼저 발행하지 말고, 참석자에게 녹취 유무를 먼저 물어볼 것.

8/18 건은 디스코드 기록만으로 발행했다가 나중에 녹취를 받았는데, 회의 본론이 통째로 빠져 있었다. 주변 텍스트에 남는 건 회의 직후 후속 논의지 회의 그 자체가 아니다. 재구성본을 굳이 내야 한다면 "회의에서 나온 것"과 "회의 후에 오간 것"을 별도 절로 분리해야 나중에 원본이 나왔을 때 무엇이 빠졌는지 바로 보인다.

외부 녹취(mp3)를 받았을 때 전사하는 법

봇과 같은 파이프라인을 손으로 태운다. 무거우니 원격 머신에서 돌린다.

ssh remote-host 'mkdir -p ~/tmp/<이름>'
scp "<mp3>" remote-host:~/tmp/<이름>/raw.mp3
ssh remote-host 'cd ~/tmp/<이름> && /opt/homebrew/bin/ffmpeg -hide_banner -loglevel error -y \
  -i raw.mp3 -ac 1 -ar 16000 -c:a libopus -b:a 24k meeting.ogg'
# 42MB mp3 → 5MB ogg. Groq 25MB 제한을 안 넘긴다.

ssh remote-host 'cd ~/tmp/<이름> && KEY=$(grep -h "^GROQ_API_KEY=" ~/.config/watch/.env | cut -d= -f2- | tr -d "\"") && \
  curl -s -X POST "https://api.groq.com/openai/v1/audio/transcriptions" \
  -H "Authorization: Bearer $KEY" -F "file=@meeting.ogg" -F "model=whisper-large-v3" \
  -F "language=ko" -F "response_format=verbose_json" \
  -F "prompt=<고유명사 나열>" -o result.json'
  • prompt에 고유명사를 넣으면 정확도가 크게 오른다. 공간명·캡틴 이름·콜라이더·베이킹 같은 도메인 용어.
  • segments의 start에 녹음 시작 시각을 더해 절대 시각으로 바꿔 적으면 회의록 쓸 때 대조하기 쉽다.
  • 개인 녹취는 화자 분리가 없다. 역할(피드백을 주는 쪽 / 구현 가능 여부를 답하는 쪽)로 판별하고, 그렇게 판별했다고 회의록 ⚠️참고에 밝힌다.
  • 녹음 시작 시각이 회의 시작보다 늦으면 앞부분이 빠졌다고 명시하고 참석자에게 물어볼 것.
  • 전사에서 숫자(폴리곤 상한·금액·비율)가 흔들리면 적지 말고 재확인을 요청한다. 지어내면 사고로 이어진다.

2. 읽기

60분 회의가 500줄/70KB 정도 된다. sed -n 으로 150~170줄씩 끊어 전부 읽는다. 요약본만 보고 쓰지 않는다. 발화자별 발화수를 먼저 세면 누가 주도했는지 잡힌다.

grep -o '^\[[0-9:]*\] [^:]*:' FILE | sed 's/^\[[0-9:]*\] //' | sort | uniq -c | sort -rn

직전 회의 회의록과 이전 체크포인트 전사를 함께 확인한다. 이번 회의의 "저번에 말한 거"가 무엇인지 모르면 액션아이템의 담당·기한을 틀리게 적는다.

3. 문서 2개를 만든다

작업 폴더 회의록 전사/ 아래에.

a. 공유본 <날짜>_<회의명>_회의록초안.md

구성 순서(기존 회의록과 동일하게 유지):

  1. > 🗓 콜아웃 — 날짜·시각·길이·참석자·회차 맥락
  2. ## 🎯 이 회의 한 줄 — 결론 한 문단
  3. ## 📅 일정
  4. ## 🧩 무슨 얘기를 했나 — 안건별 소제목, 발언 인용 포함
  5. ## ✅ 결정사항 — 번호 목록
  6. ## 📌 다음 할 일 (액션아이템) — 담당·할 일·기한 3열 표
  7. ## ⚠️ 참고

a-2. 이전 회차 미결 항목 대조 (5.4 때문에 필수)

공유본을 쓰기 전에 워치리스트의 진행중 항목을 뽑아 이번 전사와 대조한다. 노션 🔭 프로젝트 워치리스트(YOUR_NOTION_DB_ID)에서 상태=진행중을 조회.

각 항목을 셋 중 하나로 분류해 "무슨 얘기를 했나"에 근거가 남게 쓴다.

  • 확인됨 — 회의에서 실물로 시연·확인됨. 그 사실을 문장으로 남긴다. 예: "지하 녹음실은 특정 위치를 누르면 계단이 열리고, 방음 온오프 버튼도 작동하는 것을 확인했습니다."
  • 언급만 됨 — 하겠다고 말만 나옴. 완료로 읽히지 않게 쓴다. 예: "해치 손잡이는 추가하겠다고 했으나 이번 회의에서 실물 확인은 없었습니다."
  • 언급 없음 — 이번 회의에 안 나옴. ⚠️ 참고 절에 한 줄로 명시한다. 예: "창문 격자·스케일 1.2배는 이번 회의에서 언급되지 않아 진행 상황이 확인되지 않았습니다."

세 번째를 빠뜨리면 봇이 "언급이 없다"를 스스로 해석해야 해서 판정이 흔들린다. 명시해두면 red 로 정확히 유지된다.

b. PM전용메모 <날짜>_<회의명>_PM전용메모(대외비).md

공유본에서 뺀 것 + PM만의 액션. 뺄 것의 기준:

  • 클라이언트(하이브·3Y) 비판·변덕에 대한 언급
  • 미확정 계약·페이·정산 이야기
  • 팀원 개인 사정·컨디션·리소스 문제
  • 회식 등 비공식 논의

4. 노션 등록

DB: collection://YOUR_NOTION_DB_ID (📋 회의록)

회차는 직전 회의 +1. 먼저 확인:

notion-query-data-sources: SELECT "회차","제목","date:날짜:start" FROM "collection://YOUR_DATA_SOURCE_ID…" ORDER BY "회차" DESC LIMIT 5

참석자 relation은 인물 DB(collection://YOUR_NOTION_DB_ID) 페이지 URL로 넣는다.

사람페이지 ID
사용자NOTION_DB_ID
참석자NOTION_DB_ID
참석자NOTION_DB_ID
참석자NOTION_DB_ID
참석자NOTION_DB_ID
참석자NOTION_DB_ID
참석자NOTION_DB_ID

⚠️ 알려진 버그: 노션 MCP로 숫자 속성을 못 넣는다. 회차(number)와 date:날짜:is_datetime(0/1)을 넘기면 문자열로 직렬화돼 Number values must be JavaScript numbers 로 실패한다. → 두 필드를 빼고 페이지를 만든 뒤, 브라우저로 열어 회차만 직접 입력한다. is_datetime은 생략하면 기본 0이라 문제없다.

5. 디스코드 공지

채널 📃회의-안건및기록 <DISCORD_ID>. 형식은 고정이다.

📋 **회의록 업데이트했습니다!**

· **<날짜> <회의명>** — <핵심 3개를 · 로 연결>
<노션 링크>

-# 사용자(PM)이 작성한 회의록을 봇으로 공유드립니다.
bash scripts/twc-discord-post.sh <DISCORD_ID> /tmp/msg.txt

리마인드·담당별 할 일 같은 팀 대상 공지는 파트 채널로 간다: 🗺️맵·트리거-회의 <DISCORD_ID> / 🖼️디자인-회의 1516891... / 💻영상-회의 <DISCORD_ID>

5.4 회의록 본문이 조사봇 판정 근거로 쓰인다 (2026-08-17부터)

전에는 조사봇(followup.py)이 최근 24시간 디스코드 텍스트만 보고 미결 항목을 판정했다. 그래서 음성 회의에서 시연·확인되고 끝나는 일(맵팀 작업이 대표적)은 증거가 어디에도 남지 않아, 실제로는 끝났는데 계속 "마감 지났는데 완료 안 됐어요"로 알림이 갔다.

이제 봇이 판정할 때 노션 회의록 본문을 함께 읽는다. 최근 14일 이내·최대 2건·건당 4000자. 환경변수 FOLLOWUP_MINUTES_DAYS / FOLLOWUP_MINUTES_COUNT / FOLLOWUP_MINUTES_CHARS 로 조절.

그래서 회의록 본문 서술이 그대로 봇의 판정 근거다.

  • 무언가 작동하는 것을 확인했으면 그 사실을 본문에 적어라. "지하 녹음실: 특정 위치를 누르면 계단이 열리는 구조. 방음 온오프 버튼도 있고" 같은 서술 한 줄이 그 항목을 green 으로 닫는다.
  • 반대로 아직 안 된 것도 본문에 적어야 red·yellow 로 잡힌다. 회의에서 확인 안 된 항목을 확인된 것처럼 쓰면 봇이 잘못 닫는다.
  • 결정사항·액션아이템만 적고 "무슨 얘기를 했나"를 부실하게 쓰면 이 기능이 작동하지 않는다. 실물 확인·시연 내용을 구체적으로 남기는 게 봇 정확도로 직결된다.

⚠️ 이 기능 때문에 생긴 새 책임

회의록 문장 하나가 워치리스트 항목을 자동으로 닫는다(green 3회 연속 → 상태=완료). 그래서 아래 두 가지가 실제 사고로 이어진다.

잘못 쓰면결과
확인 안 된 걸 확인된 것처럼 서술봇이 green → 잘못된 "순조롭다" 보고 (자동완료는 가드가 막는다)
"무슨 얘기를 했나"를 부실하게 씀근거가 없어 계속 red → 끝난 일로 계속 알림이 감

자동완료 가드 (2026-08-17 오판 사고 후 추가)

회의록 서술만으로는 워치리스트 항목이 자동으로 닫히지 않는다. 상태를 실제로 바꾸려면 두 조건을 모두 넘어야 한다.

  1. 디스코드에 실물 근거 — 항목 제목의 특징 낱말이 최근 대화에 실제로 등장해야 한다 (_discord_corroborated). 모델 판단이 아니라 원문 대조다.
  2. 마감일이 지났을 것 — 봇의 green 은 "완료"가 아니라 "진전 보임"이라, 아직 안 온 마감 건이 닫히는 걸 막는다 (_due_passed).

둘 중 하나라도 실패하면 로그에 자동완료 보류(디스코드 근거 없음) 을 남기고 열어둔다. green 으로 보고는 되니 알림 소음은 사라지고, 닫는 건 사용자가 DM 한 줄로 한다.

자동완료될 때는 DM 에 근거 문장이 함께 표시된다(_close_line). 잘못 닫혔으면 그 자리에서 알아볼 수 있다.

왜 이 가드가 필요했나 — 회의록 ⚠️참고에 "스케일 1.2배는 이번 회의에서 확인하지 못했다"고 명시했는데도, 모델이 실물 투어 서술을 보고 green 으로 올렸다. 판정의 ev(근거 줄번호) 필드도 전 항목이 31 로 동일하게 채워져 신뢰할 수 없었다. 문서로 지시하는 것만으로는 모델의 과잉 추론을 못 막는다는 게 실측으로 확인된 사례다.

추측으로 완료를 적지 마라. 전사에 없으면 없다고 쓴다. 회의에서 화면으로 보여준 것과 말로만 언급된 것을 구분해서 적는다("시연으로 확인" vs "하겠다고 말함").

실측 예 — 8/12 회의에서 스꿀에게 8/15 마감으로 6건이 배정됐고, 8/17 클라이언트 리뷰에서 그중 녹음실 문·2층 동선 차단이 실물로 시연됐다. 회의록에 그 서술이 있어서 봇이 두 건을 green(근거: 8/17 회의록)으로 닫고, 전사에 언급이 없던 해치·창문·천장조명·스케일 4건은 red 로 유지했다. 사람이 전사본을 손으로 대조한 결과와 판정이 일치했다.

5.5 워치리스트 자동 연동 (2026-08-13부터)

노션에 올리면 끝이다. 액션아이템을 워치리스트에 샬다 집을 필요 없다.

맥밌니 ~/ops/twc-watchlist-sync/sync.py (launchd com.bambam.twc-watchlist-sync, 매일 07:50·11:50·18:50)가 회의록 DB를 훑어 새 회의록의 "📌 다음 할 일 (액션아이템)" 섹션을 파싱해 🔭 프로젝트 워치리스트에 상태=진행중 / 원처=회의록으로 넣는다. 그럼 조사봇(twc-followup)이 그걸 무는다. LLM을 쓰지 앨는다(토큰 0).

그래서 이제 액션아이템 서식이 곳 그대로 봇의 입력값이다:

  • 표 3열 담당 | 할 일 | 기한 또는 불릿 [담당] 할 일 — 둘 다 인식한다.
  • 기한은 8/15, 8/15 전, 이번 주, 내일은 날짜로 자동 변환된다. 미정·수시·최우선은 마감일 반입 없이 제목에 (기한: …)로 붙는다. → 추상적인 기한을 쓸수록 봇이 못 침다. 되면 날짜로 적어라.
  • 제목이 거의 같은 건은 자동 중봐스플된다. 진행된 건을 다음 회의록에 또 적지 말것(새 항목으로 들어간다).

직전 회의가 덮어썰는 구회차 항목은 수동으로 처리한다. 백필 범위 지정: python3 sync.py --dry-run --backfill 16,15 → 확인 후 --backfill 단독 실행. 로그는 ~/ops/twc-watchlist-sync/watchlist_sync.log.

봇 리포트는 한 번에 최대 6건으로 자른다(FOLLOWUP_MAX_TODO). 넘치면 "같은 성겼의 N건은 다음 회차에"로 뮸리고 다음 회차에 이어 알린다.

6. 마지막에 확인할 것

  • 본문에만 있고 액션아이템 표에 안 들어간 약속이 없는지 훑는다. 자주 빠진다.
  • 액션아이템이 실제로 실행 가능한지. 회의에서 나온 말이라도 산출물이 없으면 그대로 적지 않는다(예: "회의 영상 추출" — 봇은 음성만 녹음한다).
  • 담당이 지정된 발화가 전사에 실제로 있는지. 없으면 "담당 미지정"으로 적는다.
  • 공유본에 PM전용메모 항목이 섞이지 않았는지.
  • 완료로 읽힐 수 있는 서술이 전부 실제 근거가 있는지. 이 문장들이 봇의 자동완료 근거가 된다. 추측·희망 섞인 표현("됐을 것", "정리됐습니다")이 없는지 훑는다.
  • 이번 회의에서 언급되지 않은 이전 미결 항목을 ⚠️ 참고에 명시했는지.

발행 후 누락을 발견하면 채팅으로 알리지 말고 노션 발행본을 바로 고친다.


이 스킬은 GET100 운영하면서 실제로 쓰는 절차입니다. 막히는 부분이 있으면 스레드로 물어보셔도 됩니다.


회의록 요약

출력 형식

아래 형식을 반드시 준수한다:

## 📋 회의 개요
- 일시: (언급된 경우)
- 참석자: (언급된 경우)
- 주제: (한 줄)

## ✅ 핵심 결정사항
1. [결정 내용] — (결정 근거나 맥락이 있으면 괄호 안에 간략히)
2. ...

## 📌 액션아이템
| 담당자 | 할 일 | 기한 |
|--------|--------|------|
| 홍길동 | 보고서 초안 작성 | 2/28 |
| 미정 | 벤더 견적 취합 | 다음 주 금요일 |

## 💬 추가 논의 필요 사항 (선택)
- (결론 없이 끝난 안건이 있을 때만 포함)

작성 규칙

  • 결정사항: 회의에서 확정된 사항만 포함. "검토하기로 했다", "논의했다"는 제외.
  • 액션아이템: 담당자 + 할 일 + 기한을 최대한 명시. 담당자/기한 불명확 시 "미정"으로 표기.
  • 간결하게: 원문을 그대로 옮기지 말고 핵심만 요약. 항목당 한두 줄 이내.
  • 없으면 생략: 결정사항이나 액션아이템이 없는 섹션은 "없음"으로 표기하지 말고 해당 섹션 자체를 생략.
  • 언어: 회의록 언어(한국어/영어 등)에 맞춰 동일 언어로 출력.

사용 예시

사용자가 회의록 텍스트를 붙여넣거나 파일을 제공하면 즉시 위 형식으로 요약을 출력한다. 추가 질문 없이 바로 요약 결과를 제공하는 것이 원칙이며, 내용이 불충분할 때만 간단히 안내한다.

이미지 총동원 제작

목표: "총동원"이라는 말이 나오면 한 가지 방법으로 하나만 뽑아서 끝내지 않는다. 가진 무기를 다 꺼내서 후보를 여러 개 만들고, 비교해서, 근거를 대고 추천한다.

가용한 이미지 소스 (환경별로 있는 만큼 사용)

  1. 코덱스 이미지 생성: codex exec --skip-git-repo-check "<프롬프트>". 결과물은 ~/.codex/generated_images/<session-id>/<파일>.png에 저장됨 (codex의 sandbox가 read-only인 경우가 많아 원하는 경로로 직접 저장 못할 수 있음 — 출력 메시지에서 실제 생성 경로를 확인해 별도로 복사할 것).
  2. 제미나이 이미지 생성: 파이썬 google-genai SDK로 직접 호출. API 키는 다른 프로젝트(~/geuljam-bot/.env, ~/zoom-booking-bot/.env 등)의 GEMINI_API_KEY를 재사용 가능. 모델명은 이미지 생성 지원 모델(예: gemini-2.5-flash-image)을 쓴다.
  3. HTML/CSS 렌더링 + 스크린샷: 브랜드 컬러·타이포를 정확한 코드값으로 통제하고 싶을 때 (통계 카드, 표, 간단한 인포그래픽 등). 브라우저 탭에 document.open()/write()/close()로 렌더링 후 스크린샷. 뷰포트 높이를 넘는 clip을 잡으면 렌더링이 중복되는 버그가 있으니 캔버스 크기를 뷰포트 안으로 맞출 것.
  4. 사용자 사진 라이브러리: iCloud 동기화된 아이폰 사진 원본 (naver-travel-post 스킬의 방법 참고). 실제 인물/장소 사진이 필요할 때.
  5. 홈페이지/기존 자산의 이미지: get100.co.kr, litt.ly 등 이미 만들어둔 브랜드 이미지를 재활용.
  6. 웹 이미지 검색: 사용자 소유가 아닌 참고/스톡 이미지가 필요할 때만.

절차

  1. 요청받은 이미지의 용도를 먼저 파악한다 (단독 노출용 vs 텍스트를 얹을 배너용 vs 데이터 시각화 vs 실제 인물/장소 사진 필요).
  2. 용도에 맞을 만한 방법 2개 이상을 골라 각각 실제로 생성/수집해서 후보를 만든다. 코덱스와 제미나이는 프롬프트를 동일한 브랜드 톤(색상 코드, 절제된 구도, 로고/텍스트 없음 등)으로 맞춰서 비교 가능하게 만든다.
  3. 후보들을 나란히 display()로 보여준다.
  4. 각 후보의 장단점을 용도 기준으로 짧게 비교하고 하나를 추천한다 (예: "화면을 꽉 채우는 A는 단독 노출에 낫고, 여백이 넓은 B는 텍스트 얹는 배너에 낫다").
  5. 사용자 확인 후 최종본을 실제 콘텐츠(블로그, 페이지 등)에 반영한다.

주의

  • 코덱스/제미나이로 만든 이미지도 브랜드 컬러(겟백: #0d0d0d 블랙 / #d4f000 라임 / #7b2fff 퍼플)를 프롬프트에 명시해서 브랜드 무드를 유지한다.
  • 사용자는 "브랜드 컬러를 넣었다고 다가 아니라, 색을 넣어도 촌스럽게/노골적으로 쓰면 싫어한다" — 절제된 구도, 강조색은 소수 포인트에만, 과한 대칭·장식 지양.
  • API 키를 다른 프로젝트에서 재사용할 때는 평문으로 채팅에 노출하지 않는다.

naver-blog-post는 세 개로 나뉘었습니다

글 종류마다 제목·분량·톤의 기준이 서로 충돌해서, 하나의 스킬로는 어느 쪽에도 맞지 않는 글이 나왔습니다. 정보성 글에 후기 톤을 쓰면 검색에서 밀리고, 후기에 정보성 구조를 쓰면 사람이 읽지 않습니다.

그래서 목적별로 쪼갰습니다. 아래에서 목적에 맞는 것을 고르세요.

쓰려는 글쓸 스킬
도구 사용법, 문제 해결, 기능 안내 — 검색 유입이 목적naver-howto-post
기획 노트, 워크숍·강연 후기, 개인 서사 — "이 사람 뭐 하는 사람인지"를 남기는 게 목적naver-branding-post
여행·숙소·카페·맛집 후기, 서포터즈·기자단 원고naver-travel-post

기존 references/naver-search-facts.md(네이버 검색 반영 실측 자료)는 naver-howto-post/references/로 옮겼습니다.

이 폴더는 기존 링크가 깨지지 않도록 남겨둔 안내문입니다. 절차 내용은 없습니다.

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • 네이버 IMAP/SMTP 서버에 접속해 메일을 읽고 보냅니다.
  • 계정 정보는 .env에서만 읽습니다. 코드에 값을 넣지 말고, 애플리케이션 비밀번호를 발급해 쓰세요.
  • 자격증명을 출력하거나 다른 파일로 복사하지 않습니다.

네이버 메일 IMAP 읽기

네이버 웹메일은 세션이 자주 만료되고, 만료되면 저장된 비밀번호가 없어 로그인 화면에서 막힌다. 앱 비밀번호가 이미 .env에 있으므로 IMAP으로 바로 붙는 게 빠르다.

자격증명 위치

~/Projects/getback/운영/.env
~/Projects/getback/운영/서초aict-웰커밍데이/.env

키 이름: NAVER_MAIL_USER, NAVER_MAIL_APP_PASSWORD (GET100 레터 발송용으로 세팅된 것)

⚠️ 값을 출력하거나 다른 파일로 복사하지 말 것. 스크립트 안에서만 읽어 쓴다.

접속

imap.naver.com:993 SSL. 표준 imaplib이면 충분하다.

import imaplib, email
from email.header import decode_header
from pathlib import Path

env = {}
for p in [Path('.env'), Path('서초aict-웰커밍데이/.env')]:
    if p.exists():
        for line in p.read_text().splitlines():
            if '=' in line and not line.strip().startswith('#'):
                k, v = line.split('=', 1)
                env.setdefault(k.strip(), v.strip().strip('"').strip("'"))

M = imaplib.IMAP4_SSL('imap.naver.com', 993)
M.login(env['NAVER_MAIL_USER'], env['NAVER_MAIL_APP_PASSWORD'])
M.select('INBOX')

자주 쓰는 조회

# 발신자로 검색 (한글 검색어는 인코딩 이슈가 있으니 이메일 주소로 찾는 게 안전)
typ, data = M.search(None, 'FROM', '"someone@example.com"')
ids = data[0].split()

# 헤더만 빠르게 (읽음 처리 안 되게 BODY.PEEK)
typ, d = M.fetch(ids[-1], '(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE)])')

# 전문 + 첨부
typ, d = M.fetch(ids[-1], '(RFC822)')
msg = email.message_from_bytes(d[0][1])

제목·파일명은 반드시 decode_header로 디코드한다(MIME 인코딩).

첨부파일

일반 첨부는 part.get_filename() + part.get_payload(decode=True)로 바로 저장된다.

대용량 첨부(네이버 "대용량 첨부")는 본문에 안 들어 있다. HTML 파트에서 링크를 뽑아 따로 받아야 한다.

import re
fids = re.findall(r'bigfile\.mail\.naver\.com/download\?fid=([^"\'&<>\s]+)', html)
# 중복 제거 후 각각:
# https://bigfile.mail.naver.com/download?fid=<urlencode한 fid>

이 링크는 REPL 전역 fetch(사용자 쿠키 사용)로 받으면 200으로 그냥 떨어진다. fid 값에 +, /, = 가 들어가므로 반드시 encodeURIComponent로 감싼다. 파일 개수가 안 맞으면 HTML에서 fid를 다시 전부 뽑아 중복 제거할 것(같은 파일이 mybox 링크로도 중복 등장한다).

첨부파일 달아 답장 보내기 (SMTP)

브라우저 없이 바로 보낼 수 있다. 스레드로 묶으려면 원본의 Message-ID를 IMAP으로 먼저 가져와 In-Reply-To·References에 넣는다. 이걸 빼면 상대 메일함에서 별도 메일로 떨어진다.

import smtplib, ssl, mimetypes, imaplib, email
from email.message import EmailMessage
from email.utils import formataddr, make_msgid

# 1) 원본 Message-ID 확보
M.select('INBOX', readonly=True)
typ, d = M.fetch(uid, '(BODY.PEEK[HEADER.FIELDS (MESSAGE-ID)])')
orig_id = email.message_from_bytes(d[0][1]).get('Message-ID')

# 2) 메일 조립
msg = EmailMessage()
msg['From'] = formataddr(('밤밤', USER))
msg['To'] = '상대@example.com'
msg['Subject'] = '...'
msg['Message-ID'] = make_msgid(domain='naver.com')
msg['In-Reply-To'] = orig_id
msg['References'] = orig_id
msg.set_content(body)

data = att.read_bytes()
maintype, subtype = (mimetypes.guess_type(att.name)[0] or 'application/octet-stream').split('/', 1)
msg.add_attachment(data, maintype=maintype, subtype=subtype, filename=att.name)

# 3) 발송 — 네이버는 465(SSL)로 떨어진다
s = smtplib.SMTP_SSL('smtp.naver.com', 465, context=ssl.create_default_context(), timeout=30)
s.login(USER, PW); s.send_message(msg); s.quit()

보낸 뒤 보낸메일함("Sent Messages")을 열어 파트 구조를 확인한다. BODYSTRUCTURE 정규식은 한글 파일명을 놓치는 경우가 있으니, RFC822로 받아 msg.walk() 로 돌면서 get_filename() 과 바이트 수를 직접 본다. (2026-08-28 양주시 강의계획서 발송 시 실측)

주의

  • 읽기 전용으로 쓴다. 삭제·이동은 하지 않는다.
  • 큰 메일을 연속으로 RFC822 페치하면 socket error: EOF로 연결이 끊긴다. 목록은 BODY.PEEK[HEADER.FIELDS ...]로 훑고, 전문은 필요한 건만 받는다.
  • 글자수를 셀 때 wc -m을 쓰지 않는다. 비대화형 SSH엔 로케일이 없어 한글이 바이트로 세져 약 1.9배로 부풀린다. 파이썬 len()으로 쟴 것.
  • 웹 로그인이 필요한 작업(메일 쓰기 UI, 설정 변경)은 여전히 밤밤이 직접 로그인해야 한다.

노션 페이지 삭제 스킬

노션 MCP에 삭제 도구가 없어서 Notion API를 직접 호출하는 방식으로 구현. 페이지 ID 또는 URL을 받아 즉시 아카이브(휴지통으로 이동)한다.

실행 방법

python3 ~/.claude/skills/notion-delete/notion_archive.py "<page_id_or_url>"

여러 페이지 한번에:

python3 ~/.claude/skills/notion-delete/notion_archive.py "page_id_1" "page_id_2" "page_id_3"

토큰 탐색 순서

  1. NOTION_TOKEN 환경변수
  2. ~/Projects/getback/운영/pipeline/.env
  3. ~/Projects/getback/운영/discord_bot/.env
  4. ~/.env

트리거 예시

  • "스레드 #5 노션에서 삭제해줘"
  • "이 페이지 지워: https://www.notion.so/..."
  • "콘텐츠 DB에서 초안대기 빈 페이지들 다 삭제해줘"
  • /notion-delete

주의사항

  • 삭제 = 아카이브 (노션 휴지통으로 이동, 30일 내 복구 가능)
  • 완전 영구삭제는 노션 앱에서 휴지통 비우기 필요
  • DB 페이지 삭제 시 해당 DB 접근 권한 있어야 함

Orca Orchestration

This file is a discovery stub, not the usage guide. The full, version-matched Orca orchestration reference is served by the orca binary itself — kept out of this file on purpose so it can never drift from the binary that will actually run your commands.

Engage Orca orchestration whenever you need structured multi-agent coordination: threaded messages, blocking ask/reply flows, task dispatch, worker_done/escalation waits, task DAGs, decision gates, coordinator loops, or decomposing work across agents. Use the orca-cli skill instead for full ownership handoffs ("hand off", "handoff", "handover", "give this to another agent", "another worktree") when the user did not ask to supervise, monitor, wait for results, or coordinate a DAG — and for ordinary terminal control, shell commands, worktree management, and the built-in browser. Coordination requires real Orca runtime state; never substitute a non-Orca subagent tool.

Resolve the CLI for this session

Choose the executable once and reuse it for every later command:

  • If the ORCA_CLI_COMMAND environment variable is set, use its value. Orca exports this for managed WSL sessions.
  • Otherwise, in a dev checkout whose session exposes ORCA_DEV_REPO_ROOT, use orca-dev.
  • Otherwise, on Linux outside an Orca-managed terminal, use orca-ide. Never run bare orca there — outside Orca's terminals it normally resolves to the GNOME Orca screen reader (/usr/bin/orca) and starts speech on the user's machine.
  • Otherwise, use orca.

Below, ORCA is a placeholder for the executable you resolved. Substitute it before running anything; do not create a shell variable or run ORCA literally. This works the same way in POSIX shells, PowerShell, and cmd.exe.

If the selected executable cannot run, report its exact error and stop. Do not fall through to another executable, which could silently target a different Orca build.

Load the full guide before running Orca commands

ORCA skills get orchestration

That prints the complete, version-matched guide for the exact binary that will handle your next commands — task creation and dispatch, injected lifecycle preambles, worker_done authority, decision gates, and coordinator loops. Read it first, then run the specific command you need.

Don't guess subcommands or flags from memory or from a cached copy of this stub. They change between Orca releases, and this file deliberately no longer lists them. Confirm the app is up with ORCA status --json (start it with ORCA open --json if needed), and prefer --json for agent-driven calls.

If an older Orca does not recognize skills get

Use this fallback only when the selected binary explicitly reports that skills get is an unknown command. Another failure is not proof of an older binary; report it rather than guessing or changing executables. For a confirmed pre-guide binary, use only this bounded, read-only bootstrap to orient. Do not dead-end and do not invent commands:

ORCA status --json
ORCA orchestration task-list --json
ORCA terminal list --json

Then tell the user that updating Orca restores the full, version-matched guide via ORCA skills get orchestration. Beyond these commands, ask the user rather than guessing a command surface this older binary may not support.

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • ~/.ssh/config에 등록된 원격 호스트로 SSH 접속해 명령을 실행합니다.
  • 원격이 응답하지 않으면 로컬로 대체 실행하지 않고 중단합니다. 의도된 동작입니다.
  • 새 파일이나 상주 프로세스를 만들지 않습니다. --bg 사용 시 원격에 로그 파일(/tmp/offload-*.log) 하나가 남습니다.

맥미니 오프로딩

왜

Aside 돌아가는 기기오프로딩 대상
기기MacBook Air, Apple M1Mac mini, Apple M4
램8 GB (상시 부족, 압축 2.6GB / 여유 70MB 수준)16 GB
절전사용자가 덮으면 멈춤pmset sleep 0 — 안 잠듦
디스크 여유200 GB54 GB

맥북에어는 램이 모자라 크로미움이 백그라운드 탭을 강제 종료한다. 로컬에서 무거운 걸 돌리면 사용자의 탭이 죽는다. 무거운 건 맥미니로 넘기는 게 기본값이다.

접속

ssh mac-mini          # Tailscale (100.75.197.6) — 기본으로 이걸 쓴다
ssh mac-mini-lan      # 같은 LAN일 때 (mac-mini.local)

비대화형에서는 -o BatchMode=yes -o ConnectTimeout=10을 붙인다. PATH가 필요한 명령(brew 설치물 등)은 ssh mac-mini 'bash -lc "..."'로 로그인 셸을 태운다.

작업공간 규약

~/Projects/ops/offload/
├── run.sh          러너 (아래 참조)
├── jobs/           실행할 스크립트를 여기로 scp
├── out/            산출물 (이미지, csv, json 등)
├── logs/           <JOB_ID>.log / .pid / .cmd.sh
└── node_modules/   playwright 설치됨

기존 프로젝트 작업은 ~/Projects/<repo>에서 그대로 하고, 일회성 오프로딩만 여기를 쓴다.

판단 기준

넘긴다

  • 헤드리스 스크래핑, 특히 여러 페이지 순회 (로그인 불필요한 공개 페이지)
  • ffmpeg 인코딩, GIF 생성, 이미지 대량 변환
  • npm install, next build, 대형 저장소 clone
  • 대량 API 수집 (수백~수천 건 페이지네이션)
  • 수십 MB 이상 파일 파싱/집계
  • 30초 넘게 걸릴 것 같은 CPU 작업 전부
  • 긴 문서/영상 스크립트 읽고 요약 (아래 claude -p 레시피)

안 넘긴다

  • 사용자의 로그인 세션·쿠키가 필요한 브라우징 → Aside 브라우저에서 해야 함
  • 사용자가 화면으로 확인해야 하는 UI 조작
  • 몇 초 안에 끝나는 단순 조회 (ssh 왕복이 더 느림)
  • 사용자 개인 파일이 맥북에어에만 있는 경우 (전송 비용 판단 후 결정)

표준 패턴: 스크립트를 보내서 실행

ssh + bash -lc + heredoc을 중첩하면 따옴표가 반드시 깨진다. 로컬에 파일로 쓰고 scp로 보낸 뒤 실행한다.

TMP=<세션 tmp 디렉토리>
cat > "$TMP/job.js" <<'EOF'
... 스크립트 ...
EOF
scp -q "$TMP/job.js" mac-mini:~/Projects/ops/offload/jobs/job.js
ssh mac-mini 'cd ~/Projects/ops/offload && node jobs/job.js'

긴 작업: run.sh

ssh 세션이 끊겨도 살아남아야 하는 작업은 러너로 띄운다.

R=~/Projects/ops/offload/run.sh
ssh mac-mini "$R start 'node jobs/scrape.js' scrape"   # -> JOB_ID=scrape-20260811-124757
ssh mac-mini "$R status scrape-20260811-124757"        # running (pid=...) 또는 ### EXIT=0
ssh mac-mini "$R tail   scrape-20260811-124757"        # 마지막 40줄
ssh mac-mini "$R log    scrape-20260811-124757"        # 전체 로그
ssh mac-mini "$R list"                                 # 최근 20개 작업

작업이 오래 걸리면 붙잡고 기다리지 말고, 그동안 로컬에서 다른 일을 하다가 status로 확인한다.

산출물 회수

scp mac-mini:~/Projects/ops/offload/out/result.csv <세션 artifacts 디렉토리>/
scp -r mac-mini:~/Projects/ops/offload/out/frames  <세션 tmp 디렉토리>/

사용자에게 보여줄 결과물은 artifacts 디렉토리로, 중간 확인용은 tmp로 가져온다.

레시피

헤드리스 브라우징 (playwright)

const { chromium } = require('playwright');   // ~/Projects/ops/offload 에서 실행
(async () => {
  const b = await chromium.launch({ headless: true });
  const p = await b.newPage();
  await p.goto(url, { waitUntil: 'domcontentloaded' });
  // ...
  await p.screenshot({ path: 'out/shot.png' });
  await b.close();
})();

워밍업 후 페이지 로드 0.3초 수준. 전역에 puppeteer도 있지만 playwright를 기본으로 쓴다.

미디어

ffmpeg는 /opt/homebrew/bin/ffmpeg. 인코딩·GIF 변환은 전부 맥미니에서 한다. web-demo-video 스킬의 프레임 합성 단계도 여기로 넘길 수 있다.

긴 문서 읽기를 CLI로 위임

메인 컨텍스트에 원문을 쌓지 않으면서 긴 자료를 요약할 때:

ssh mac-mini 'bash -lc "cat ~/Projects/ops/offload/jobs/doc.txt | claude -p --model claude-sonnet-4-5"'

사용량 한도가 걸리면 claude-codex-fallback 스킬의 판별 규칙을 따른다. Codex CLI(codex)도 설치되어 있다.

설치된 도구

node v26 / npm 11 / python3.9 / uv / brew 6 / ffmpeg / rg / jq / git / gh 2.92 / vercel / claude CLI 2.1 / codex CLI 0.147 / playwright(offload 로컬) / puppeteer(전역) / Google Chrome

없는 게 필요하면 ssh mac-mini 'bash -lc "brew install <pkg>"'로 설치하고 이 목록을 갱신한다.

주의

  • 맥미니는 이미 launchd 상주 작업이 여러 개 돈다 (atlas-server, atlas-kakao-poll, threads-fetch, voicememoimporter, 디스코드 채널 봇, 각종 리마인더). 코어를 다 쓰는 작업을 걸기 전에 run.sh list와 launchctl list | grep bambam을 확인한다.
  • 예약 실행(리마인더/크론)은 이 스킬이 아니라 macmini-discord-reminder 스킬을 따른다.
  • 자격증명은 맥미니에 있는 기존 .env에서 런타임에만 읽고, 값을 출력하지 않는다.
  • 디스크 여유가 54GB뿐이다. 대용량 임시 파일은 작업 후 out/에서 정리한다.
  • 파괴적 작업(대량 삭제 등)은 AGENTS.md의 안전 규칙을 그대로 적용한다.

Style Skill Creator

Create style skills that teach Claude your writing style.

Critical: Audience is AI

This creates AI instructions (for Claude to read), NOT human documentation (for authors to read).

AI InstructionsHuman Documentation
"When writing X, do Y""The story uses X because Y"
Directive commandsExplanatory descriptions
Pattern + examplesAnalysis + reasoning

Step 1: Ask About Input

Always ask first:

다음 중 어떤 방식으로 스타일 스킬을 만들까요?

1. 기존 글 샘플 제공
   - 1~5장 같은 실제 쓰신 글을 분석해서 패턴 추출

2. 스타일 직접 설명
   - "나는 이렇게 쓴다"를 말로 설명

어느 쪽으로 하시겠어요?

Step 2: Gather Input

From existing prose (preferred):

  • Read 2-3 chapters/sections if provided
  • Identify consistent patterns: sentence length, paragraph structure, emotional tone, vocabulary, personal anecdotes, transitions

From description:

  • Ask specific questions about voice, rhythm, what feels "off" vs "right"

Writing Style: Directive and Technical

Use imperative/command form:

✅ "Use short sentences during emotional moments" ✅ "Avoid transition words like '또한', '그리고'" ✅ "Show vulnerability through specific episodes, not declarations" ❌ "The author tends to use short sentences" (analysis, not instruction)

Always include examples:

**Personal anecdotes:**
- Always anchor insight to a specific moment/episode
- Example: "일요일 저녁이었습니다. 정산을 하니 새벽이었습니다." not "모임이 힘들었습니다."

Pattern + Example format:

**[Pattern name]:**
- [Instruction about the pattern]
- Example: [Concrete example from the author's writing]
- Avoid: [What NOT to do]

Output Format

Create a SKILL.md file with these sections:

---
name: [author]-writing-style
description: Style guide for writing in [author]'s voice. Load this when writing content for [author].
---

# [Author] Writing Style

## Core Voice
[2-3 sentences capturing the essential feel]

## Sentence & Paragraph Structure
[Directives about length, rhythm, structure]

## Emotional Tone
[Directives about vulnerability, directness, energy level]

## Opening Patterns
[How chapters/sections typically start]

## Closing Patterns
[How sections end - with what kind of beat]

## Vocabulary & Phrases
[Signature expressions, words to use, words to avoid]

## Anecdote Style
[How personal stories are structured and used]

## What to Avoid
[Explicit list of things that feel wrong for this voice]

Common Style Skill Types

Master Prose: Overall writing voice, sentence structure, tone Personal Essay: Anecdote usage, vulnerability, insight delivery Social Content: Platform-specific patterns (Threads, LinkedIn) Chapter Structure: Long-form flow, section openings/closings

Integration

The ideal workflow for ebooks:

  1. Load cw-style-skill-creator → analyze 1~5장
  2. Generate bambam-writing-style skill
  3. When rewriting 6~9장, load bambam-writing-style + humanize-writing
  4. Result: Consistent voice across all chapters

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • Threads에 답글을 실제로 발행할 수 있습니다. 동봉 스크립트는 기본 dry-run이고 --go에서만 발행합니다.
  • 문체를 역산하려고 본인 계정의 과거 답글을 대량으로 읽습니다.
  • 액세스 토큰이 필요합니다. 환경변수에서만 읽습니다.

개인 스레드 답글 보이스 (@bam.bam_2)

밤밤 개인 계정에 온 댓글에 답글을 다는 작업 전용.

  • 브랜드 계정(@get100.official)이 남의 글에 콜드로 댓글 다는 기준은 ~/Projects/getback/마케팅/threads-1000/ENGAGE-VOICE.md(2026-07-10 밤밤 확정)다. 그쪽 철칙 3개(한 줄·미러링 금지·존대 유지)는 여기서도 유효하지만, 거기 적힌 말투 마커(ㅇ_ㅇ? ~넹 ~당 ~욤)는 밤밤의 게시물 에서 뽑은 것이라 답글에서는 거의 안 쓰인다(실측 ㅇ_ㅇ 0.0%, ~ 2.5%). 답글은 이 문서를 정본으로 본다.
  • 계정 성과 분석은 threads-analytics 스킬.

근거

Threads Graph API GET /me/replies 전량 22,560건(2024-04-26 ~ 2026-08-08) 실측.

0. ⚠️ 초안은 코덱스가 쓴다 (2026-08-15 밤밤 확정)

"다음부터 이거 코덱스로 하기로 하자"

답글 초안 생성은 클로드가 직접 하지 말고 코덱스에 넘긴다. 2026-08-15 배치에서 클로드 초안이 두 번 연속 반려됐고("내말투 들어간거냐", "코덱스는 내말투 잘 따라하던데"), 같은 재료를 물린 코덱스 출력이 채택됐다. 클로드는 재료 준비 · 검증 · 발행 · 예외 판단을 맡는다.

왜 클로드 초안이 실패했나 (반복 금지)

  • 통계 표를 보고 새로 지어냈다. 문체표(길이·이모티콘 비율)만 맞추면 리듬은 비슷해지지만 반응 방식은 못 배운다. 결과물이 지나치게 깔끔하고 훈수형(~하셔도 됩니다, ~반응 다릅니다)이 됐다.
  • 댓글↔답글 짝(pair)을 한 번도 안 봤다. 답글만 따로 보면 "어떤 말에 어떻게 받아치는지"가 안 보인다. 밤밤은 드립을 치고(천재라기엔 계란값이 많이 들었습니다 ㅋㅋ), 어미를 갖고 놀고(~게여 ~할게욤 'ㅁ' 워우...;;), 상대를 자기 판으로 끌어당긴다(6기 재참여하시죠!? 이제 맥스의 세계로 가보시죠!).

실행 절차

  1. 짝 코퍼스 수집 — reply-logs/ 의 pairs 수집 스크립트로 최근 2개월치 내 글 conversation을 훑어 {남의 댓글 → 밤밤 답글} 짝을 뽑는다(2026-08-15 기준 430건). 한 줄·90자 이하만 남기고 최신순 220건을 예시로 쓴다.
  2. 프롬프트 조립 — build_codex_prompt.py가 짝 220건 원문 + 계량 기준표(아래 1장) + 절대규칙 + 대상 댓글 전체를 묶는다. 출력은 번호|답글 한 줄씩만. 2026-09-13에 밤밤 지시로 세 가지가 빌더에 박혔다(1-2장 참조). ⓐ 이미지 글 하드게이트 ⓑ 같은 글 기존 답글 주입 ⓒ 수량 할당을 건수로 지시.
  3. 실행 — 코덱스 CLI는 맥북 샌드박스에서 env: node: No such file or directory로 죽는다. 맥미니에서 돌린다: scp /tmp/codex_prompt.txt mac-mini:/tmp/ → ssh mac-mini 'codex exec --skip-git-repo-check - < /tmp/codex_prompt.txt'. (맥미니엔 timeout 명령이 없으니 붙이지 말 것.)
  4. 클로드가 검수 — ⚠️ 눈으로 읽지 말고 먼저 숫자로 잰다(2026-08-23 추가). 초안 전체를 1장 실측표와 대조해 20자 이하 비율 / 중앙 길이 / 느낌표 / 감상·요약 종결(~네요·~군요·~같아요) 4개를 계산하고, 실측에서 크게 벗어나면 밤밤에게 보여주기 전에 다시 뽑는다.
    • 2026-08-23 실패: 눈으로만 훑고 212건을 그대로 올렸다가 "왤케 말투가 별로지"로 반려. 재보니 20자 이하 19%(실측 66%) / 느낌표 21%(실측 32%) / 감상 종결 18%(실측 9%) 였다. 프롬프트를 고쳐 다시 뽑으니 94% / 32% / 3%로 잡혔다.
    • 코덱스 출력에서 아래도 잡아낸다. 실제로 나온 결함들이다.
    • ㅋㅋㅋ 3개 이상 → ㅋㅋ로 자동 보정(2장 5번 절대규칙)
    • 훈수·교훈 종결(~하시면 됩니다, A는 이렇게 B는 이렇게가 맞겠네요)
    • ㅋㅋ 과다 — 코덱스는 31%까지 올린다(실측 13%)
    • 맥락상 기회를 날리는 답글 — 예: 공간 홍보 댓글에 웃고 넘기기(밤밤은 8/30 70명 행사 공간을 찾는 중이었다). 이런 건 클로드 안으로 갈아끼운다. 2026-08-15에 실제로 12번만 클로드 안이 채택됐다.
  5. 밤밤에게 코덱스안/클로드안을 나란히 보여주고 번호로 고르게 한다(7장).

1. 계량 기준표 — 초안이 이 범위를 벗어나면 다시 쓴다

⚠️ 2026-08-15 갱신. 아래 표는 2026-08 한 달치 한 줄 답글 492건 실측이다. 이전 판(2026-05 이후 836건 기준)은 느낌표 11% / 물음표 22%로 적혀 있었는데 8월 실측은 거의 정반대였다(느낌표 31% / 물음표 7.5%). 그 낡은 표를 믿고 쓴 초안이 밤밤에게 반려됐다. 문체표는 배치 시작할 때마다 다시 재본다.

항목실측값(2026-08)지킬 것
글자수 중앙값17자20자 안팎. 36자 넘으면 이유가 있어야 함
줄 수1줄줄바꿈은 예외
느낌표(!) 포함31.1%3건에 1건. 이게 밤밤 톤의 핵심이다. 없으면 딱딱해진다
ㅎㅎ16.3%6건에 1건
ㅋㅋ13.4%7~8건에 1건. 코덱스가 남발하니 깎을 것
물음표로 끝7.5%13건에 1건. 되묻기를 남발하지 말 것
님 호칭7.1%이름 아는 사람에게만
~하시죠 / ~실래요 청유3.0%상대를 자기 판으로 끌어당길 때
ㅠ ㅠ_ㅠ8%공감·엄살에만
이모지1%사실상 안 쓴다
반말 종결3%존대가 기본. 상대가 반말로 걸어와도 존대
상대 단어 되받기(미러링)2%사실상 안 한다

1-2. 빌더에 박힌 세 가지 (2026-09-13 밤밤 지시로 개정)

밤밤: "댓글노가다 규칙 먼저 뜯어보고 하자" → 코덱스가 맥락을 어떻게 짚는지를 점검하다 구멍 두 개를 찾았다. 프롬프트의 본체는 통계표가 아니라 짝 220건 원문인데, 대상 쪽에 붙는 맥락이 얇았다.

ⓐ 이미지/영상 글은 설명이 없으면 빌더가 죽는다 (exit 2)

예전엔 IMAGE_NOTES={}가 빈 dict 기본값이라, 설명을 안 채우면 아무 경고 없이 캡션만 보고 초안이 나왔다. 2026-09-08 대상 33건 중 16건이 IMAGE였다. 스킬 4장에 "이미지 글은 반드시 열어서 확인"이라고 적혀 있었지만 스크립트가 강제하지 않아 지켜지지 않던 지점이다.

  • 이제 post_media가 IMAGE/VIDEO/CAROUSEL_ALBUM인데 설명이 없으면 permalink와 이미지 URL을 찍고 exit 2로 죽는다.
  • 설명은 reply-logs/image_notes.json에 {post_id: "설명"}으로 누적 저장된다. 같은 글이 다음 배치에 또 나와도 재사용된다.
  • extract.py가 media_url + children{media_url}을 같이 뽑으므로, 그 URL을 받아 실제로 열어보고 채운다.

ⓑ 같은 글에 내가 이미 단 답글을 프롬프트에 넣는다

extract.py가 원글 conversation에서 밤밤 답글 전체를 모아 existing_my_replies로 저장하고, 빌더가 원글 블록 아래에 (이 글에 내가 이미 단 답글 — 표현·소재가 겹치지 않게 쓸 것: "…")로 넣는다. 사후 difflib 차단이 아니라 생성 단계에서 막는 방식이다(밤밤의 generation-over-gate 원칙).

ⓒ 수량은 비율이 아니라 건수로 박는다

⚠️ 코덱스는 백분율 지시를 못 지키고 한쪽으로 몰린다. 2026-09-13에 3차까지 돌려서 잡았다.

항목1차2차3차(채택)실측
20자 이하100%13%74%66%
중앙 길이17자24자18자17자
느낌표18.5%42.6%42.6%31%
물음표로 끝25.9%9.3%13%7.5%
  • 1차("3분의 2는 20자 이하")→ 전부 20자 이하로 만들고 느낌표는 모자라고 물음표는 3.5배 남발.
  • 2차(건수 하한만 지시)→ 반대로 21~35자를 47/54건까지 밀어버림. 하한만 주면 그쪽으로 몰린다.
  • 3차(하한+상한 동시)에서 잡혔다. 그래서 빌더의 QUOTA는 short_min / mid_min / mid_max / excl_min / qmark_max / hh_min을 전부 대상 건수 N에 비례해 계산해 "총 N건 중 최소 X건 / 최대 Y건" 문장으로 찍는다.

1-1. 코덱스 프롬프트에 반드시 넣을 것 (2026-08-23 확정)

계량 기준만 주면 코덱스는 "대화를 닫는 감상평"을 쓴다. 프롬프트에 답글의 목적을 먼저 박는다.

밤밤은 커뮤니티 기획자다. 답글의 목적은 '좋은 말로 마무리'가 아니라 그 사람과 관계를 여는 것이다. 모든 답글은 셋 중 하나여야 한다. (A) 상대에게 초점을 돌린다 — 그 사람 이야기를 묻는다 (B) 드립으로 받아친다 — 짧게 웃기고 끝낸다 (C) 내 판으로 끌어당긴다 — 만나자/오라/해보자 A 40% / B 40% / C 20% 정도로 섞어라.

금지 항목은 실제로 걸린 문장을 예시로 붙여야 먹힌다(추상적으로 "미러링 금지"만 쓰면 또 한다). 길이는 "중앙 18자"가 아니라 **"3분의 2는 20자 이하"**로 지시해야 실측에 맞는다.

⚠️ 유형에 맞는 응답을 해라 — (A)를 전면 적용하지 말 것

감사합니다 잘 쓰겠습니다 좋은정보 얻어갑니다 같은 인사·감사 댓글에 "어떤 일 하시는 분인가요?"를 붙이면 안 된다. 2026-08-23 밤밤 지적: "감사합니다에 뭔 어떤일 하시는 분인가요냐;;; 뭐 줬다는말에 감사합니다 같은걸로 해줘"

  • 감사 → 감사로. 뭘 줬다(별·스하리) → 고맙다고. 잘 쓰겠다 → 잘 쓰시라고.
  • 대신 11건이 전부 "감사합니다"면 대행 티가 나므로 감탄사·엄살·짧은 드립으로 매번 변주한다.
  • 캐묻는 질문은 실제로 물어볼 게 있는 댓글(자기 상황을 말한 사람, 질문한 사람, 검증성 지적을 한 사람)에만.

⚠️ 같은 질문 5개 금지

2026-08-23에 17건 중 5건이 "어떤 일 하세요 / 무슨 업무 하세요 / 뭘 자동화하고 싶으세요"로 겹쳤다. 초안을 받으면 질문 유형이 겹치는지 정규식으로 세어보고 3건 이상 겹치면 분산시킨다.

2. 절대 규칙 7개

  1. 같은 문구를 두 번 쓰지 않는다. 최근 836건에 완전히 겹치는 답글이 0건이다. 밤밤은 매번 다르게 쓴다.
    • ⚠️ 2026-08-08 실패: 76건 대행하면서 감사합니다 ㅎㅎ를 7번 썼다. 고유 문구 70/76. 이게 대행 티가 나는 1순위 지점이다.
  2. 미러링 금지. 상대 말을 요약해 되돌려주지 않는다("17번이면 세계관도 17번 바뀌신 거네요" ❌). 실측 미러링 2%.
  3. 훈수 금지, 존대 유지. 교훈으로 끝맺지 않는다. 상대가 반말이어도 존대로 답한다.
  4. ㅎㅎ/ㅋㅋ를 기본값으로 붙이지 않는다. 10건 중 8건은 이런 것 없이 끝난다.
  5. ㅋㅋㅋ(세 번 이상)는 쓰지 않는다. 비웃는 느낌으로 읽힐 수 있다는 밤밤 지적(2026-08-08). 대신 ㅋㅋ(두 번) 또는 :)를 쓴다. :)는 실측 데이터에도 실제로 등장하는 표현.
  6. 재답글(내 답글에 달린 대댓글)은 답글 대상이 아니다. 남이 나에게 새로 단 최상위 댓글에만 답한다. 내가 이미 답한 스레드 안에서 이어지는 대화(재답글)는 대량 발행 대상에서 제외한다(2026-08-08 밤밤 지시).
  7. 초대·모집성 답글에 뭉뚱그린 템플릿 문구를 쓰지 않는다. ~가능해요 편하게 오세요 류의 일반화된 초대 문구는 다단계·리딩방·투자 스캠 계정의 전형적 홍보 템플릿과 표면 패턴이 겹쳐 Threads의 "금융 사기 및 스캠" 자동 필터에 오탐될 수 있다. 행사명·날짜·장소 등 구체적 디테일을 최소 1개 이상 넣어서 일반 템플릿과 표면적으로 구분되게 쓴다.
    • ⚠️ 2026-08-10 실제 사례: 누구나 참여 가능해요 편하게 오세요!(70명 네트워킹 행사 문의 답글)가 "경제적 이익에 관한 현실성 없는 주장/약속"으로 자동 삭제 후 5분 만에 재검토로 복원됨. 오탐이었지만 재발 방지 대상.
    • 예: 누구나 참여 가능해요 편하게 오세요! ❌ → 이번 강남 모임은 신청만 하면 누구나 오실 수 있어요! ✅ (구체적 장소/행사 정보 포함)

3. 댓글 유형별 대응 (실측 패턴)

① 짧은 공감·인사 (12자 이하) — 내 답글 중앙 16자 감사로 끝내지 말고 상대에게 관심을 돌린다. 프로필을 보고 그 사람 이야기를 꺼내는 게 이 계정의 핵심 동작이다.

  • 친해지고 싶어요 😅 → 우와 캐나다에서 크리에이터로 도전하고 계시네요~?!
  • 뚫어주세요~~~~~ → 뭐가 고민이예요!!
  • 피드 발견 → 온제님은 어떤일을 하시나요?!
  • 오잉 → 또잉?!
  • 감사만 할 거면 짧게 변주: ㅋㅋㅋ공감감사합니다 / 100% 감사합니다. / ㅎㅎ반갑습니다!

② 보통 (13~45자) — 내 답글 중앙 22자 한 조각 얹거나 되묻는다.

  • 경험의 기회는 내가 만드는 거지..! → 맞아요 내 인생의 주인공도 나 잖아요!? ㅎㅎ
  • 1인 사업가 디자이너 보여요!! → 헉 5년차 디자이너~! 손목 괜찮으세요?
  • 교육커뮤니티 만들고싶은데 시작을 모르겠어요 → 으아 어떤 교육 커뮤니티를 운영하시는데요..? 먼저 만들어보시죠!

③ 긴 글 (46자+) — 내 답글 중앙 27자 길이를 따라가지 않는다. 한 지점만 집어서 짧게.

  • 긴 경험담 → 랜덤뽑기 하듯이 모임을 참여하는 것과 잘 검증된 사람들과 만나는건 체력소비가 달라요.
  • 긴 공감글 → 벗어나셨나요?!

④ 60자 넘게 쓰는 경우는 이 셋뿐 (전체의 13%) 자기 경험/수치를 나눌 때, 링크·제품을 안내할 때, 상대를 구체적으로 띄워줄 때. 그 외에는 길게 쓰지 않는다.

⑤ 답하지 않는 것

  • 논쟁 걸어오는 계정 — 밤밤이 지정하면 그 계정 전체를 무시한다.
  • 정치 사안(집회·참정권 등) — 본계정으로 안 엮인다.
  • 남들끼리 주고받는 대댓글 — 부모가 밤밤 글/답글이 아니면 대상 아님.
  • 재답글(부모가 내 답글인 대댓글) — 최상위 댓글만 대상으로 한다(2026-08-08 밤밤 지시).
  • 맥락이 불분명한 댓글은 밤밤에게 확인하고 보류(원글 속 표현을 짧게 묻는 댓글이 그 예다 — 원글 본문에 있는 단어·표현을 물어보는 거면 원글 전문을 먼저 대조해볼 것).

4. 첫 어절로 자주 쓰는 것

오 와 그 크으으으 아 헉 근데 이거 저랑 — 감탄사로 열고 바로 짧게 끝내는 리듬.

⚠️ 오프너 반복 금지(2026-08-14 밤밤 지적): 같은 배치 안에서 여러 건을 쓸 때 오만 계속 쓰면 대행 티가 확 난다(절대 규칙 1번 "같은 문구 두 번 안 씀"의 연장). 위 목록에서 매 건마다 다른 첫 어절을 고르고, 감탄사 없이 바로 본론으로 시작하는 것도 정상적인 선택지로 섞는다.

⚠️ 이미지·영상 있는 게시물은 반드시 실제로 열어서 확인(2026-08-14 밤밤 지적): 게시물에 사진/동영상이 있으면 텍스트 캡션만 읽고 댓글을 쓰지 않는다. 스크린샷으로 이미지 내용을 직접 확인한 뒤, 캡션과 이미지 중 실제로 반응할 지점(구체적 사물·장면·비교컷 등)을 잡아서 쓴다. 캡션이 짧거나 이미지가 핵심인 게시물(예: 사진 위주 게시물, before/after 비교컷)일수록 이미지를 안 보면 완전히 엉뚱한 댓글이 나온다 — 텍스트만 보고 썼다가 실제와 다른 내용으로 지적받은 사례 있음.

5. 대량 발행 절차

스크립트 세트 (전부 ~/Projects/ops/threads-tool/reply-logs/, 2026-08-15 정비)

파일역할
extract.py미답변 최상위 댓글 추출(컷오프+스킵리스트 적용) → pending_YYYY-MM-DD.json
build_pairs.py{남의 댓글 → 밤밤 답글} 짝 코퍼스 수집 → /tmp/pairs.json
build_codex_prompt.py짝 220건 + 기준 + 대상을 묶어 코덱스 프롬프트 생성. 이미지 설명 없으면 exit 2로 죽는다. 원글 단위로 묶어 seq를 매기고 target_YYYY-MM-DD.json으로 저장(표시번호=데이터키)
image_notes.json{post_id: "이미지/영상 내용 설명"} 누적 저장소. 빌더가 여기를 본다
publish.pypython3 reply-logs/publish.py YYYY-MM-DD — final_YYYY-MM-DD.json을 30~45초 간격으로 발행하고 batch_YYYY-MM-DD.jsonl에 기록. 발행 직전 username 검증, 재실행해도 중복 발행 안 됨. 날짜는 인자로 받는다(2026-08-23 파라미터화). 한 날짜에 여러 배치를 돌릴 땐 final_ 파일만 갈아끼우면 로그가 중복을 걸러준다

(구버전 postreplies.py는 맥미니에만 있다)

# 대상 추출 — 내 답글이 자식으로 없는 남의 댓글만
GET /v1.0/{post_id}/conversation?fields=id,text,username,timestamp,replied_to&limit=100
# 발행 (2단계)
POST /v1.0/{uid}/threads  {media_type:TEXT, text, reply_to_id:<댓글id>}
POST /v1.0/{uid}/threads_publish  {creation_id}

토큰: 맥미니 ~/Projects/ops/threads-tool/.env 또는 ~/Projects/getback/discord_bot/.env (둘 다 @bam.bam_2). uid <DISCORD_ID>.

반드시 지킬 것

  • 발행 직전 대상 댓글 작성자가 초안에 적힌 계정과 같은지 대조하고, 다르면 SKIP + 기록. 리다이렉트·순서 밀림으로 엉뚱한 사람에게 달리는 걸 막는다.

  • 성공분을 JSONL에 남겨 재실행해도 중복 발행되지 않게 한다.

  • 30~45초 간격. 계정이 도달 제한을 받은 적이 있다면 속도 자체가 위험하다. 76건에 약 55분.

  • 발행 뒤 conversation을 재조회해 누락 0을 확인하고, 그 사이 새로 들어온 댓글은 따로 센다.

  • 답글 발행 후 상대 프로필의 최신 원글 최대 5개에 좋아요를 누르고, 가장 최신 원글 1개에 맞춤 댓글을 단다(2026-08-09 밤밤 지시). 게시물이 5개 미만이면 가능한 만큼만, 이미 좋아요된 글은 중복 클릭하지 않는다. 각 좋아요 사이 38초·계정 사이 2040초 간격을 둔다. 성공/스킵/실패 수를 발행 로그에 함께 남긴다.

  • 원글 판정 필수: 프로필 기본 탭에는 상대가 남긴 답글·인용글이 원글처럼 섞여 보일 수 있다. 댓글 버튼을 누르기 직전, 현재 스레드의 원 작성자가 상대 username인지와 본문이 프로필에서 읽은 최신 원글 본문과 일치하는지 대조한다. 밤밤 글에 상대가 단 답글 페이지로 이동했으면 취소하고 프로필로 돌아간다(2026-08-09 중복 댓글 직전 발견 사례).

  • 정치 프로필/정치 최신글은 좋아요·선제 댓글에서 제외한다. 자동 좋아요 중 정치 글을 발견하면 해당 좋아요를 즉시 취소하고 맞춤 댓글도 달지 않는다.

  • 맞춤댓글은 최근 3일 이내 원글에만 단다(2026-08-10 밤밤 지시). 상대 프로필의 가장 최신 원글이 3일보다 오래됐으면 그 계정은 맞춤댓글을 생략하고 좋아요만 진행한다.

  • 답변하기 애매한 글은 댓글을 스킵하고 좋아요만 진행한다(2026-08-15 밤밤 확정). 아래 4가지 중 하나라도 해당하면 댓글 후보에서 제외 — 무리하게 초안을 짜내지 말고 좋아요만 하고 넘어간다.

    1. 너무 추상적/철학적인 성찰글 — 걸 수 있는 구체적 소재가 없어 질문이 범용화된다(그 글이 아니라 "시작/성장/도전" 같은 주제어가 들어간 아무 글에나 붙여도 말이 되는 질문이 나오면 이 케이스).
    2. 광고/마케팅/홍보 목적 게시물 — 사장님 홍보, 상세페이지·마케팅 서비스 판매, 창업 컨설팅 등. 댓글이 진짜 반응이 아니라 고객 문의처럼 읽힌다.
    3. 원문에 없는 걸 프로필 정보로 추론해서 연결한 질문이 되는 경우 — 예: 프로필 태그가 "bass"라서 "이 채널도 보시나봐요?"처럼 원문이 확인해주지 않은 전제를 까는 질문. 확인 안 된 연결은 만들지 않는다.
    4. 원문 자체가 모호하거나(뜻이 불확실), 콘텐츠가 템플릿/AI풍이라 진짜 개인 경험인지 불확실한 경우 — 일러스트/AI 생성 이미지·영상에 감성 문구가 반복되는 계정, 문장 뜻이 여러 갈래로 읽히는 짧은 글 등. 뜻을 잘못 짚어 엉뚱한 댓글이 나올 위험이 크다.
  • 이미 어떤 방향으로든 팔로우 관계가 있는 계정은 좋아요·맞춤댓글 대상에서 전부 제외한다(2026-08-11 밤밤 지시 "이미 팔로우하는 사람한테는 뭔 글쓰지 말라고", 2026-08-13 재확인 "나랑 팔로우인사람도 왜 포함하냐"). 이 단계의 목적은 아직 연결되지 않은 사람과의 새 관계 형성이다.

    팔로우 버튼 판정표 (프로필 상단 버튼 텍스트를 그대로 읽는다)

    버튼 텍스트의미처리
    팔로우서로 아무 관계 없음유일한 대상. 좋아요 + 맞춤댓글
    팔로잉밤밤이 이미 상대를 팔로우 중전진 제외(좋아요도 안 누름)
    맞팔로우상대가 밤밤을 팔로우 중전진 제외

    2026-08-13 사고: 서브에이전트에 "맞팔로우면 팔로워(스킵), 그외(팔로우/팔로잉)면 비팔로워"라고 지시해서 "팔로잉"(이미 내가 팔로우 중)이 대상으로 섞였고 hayan_sool에 좋아요 1건이 잘못 나갔다(즉시 취소). 서브에이전트에게는 버튼 텍스트를 있는 그대로 보고하라고만 시키고, 팔로워/비팔로워 같은 해석을 시키지 않는다.

    ⚠️ 밤밤이 특정 글을 콕어 "이 글에 댓글 단 사람은 다 팔로우하고 좋아요해라"고 지시하면 이 제외 규칙은 그 배치에 한해 무효다(2026-09-13 실제 지시). 이미 팔로잉인 사람은 팔로우가 no-op이니 좋아요만 진행하고, 결과 보고에 새 팔로우/기존 팔로잉을 나눈다. 정치 스크리닝은 지시와 무관하게 유지한다.

5-1. 속도 최적화 (2026-08-10 밤밤 지시, 반복 요청되는 작업이라 기본값으로 박아둠)

안전 페이싱(발행 3045초, 좋아요 38초·계정 20~40초)은 절대 줄이지 않는다 — 이건 속도가 아니라 계정 안전이 목적이다. 줄일 수 있는 건 이 페이싱 안에서 에이전트가 쓰는 조사·확인 오버헤드다.

  • 팔로워/정치/3일규칙 조사는 서브에이전트 병렬이 기본값이다. 대상 계정을 58개씩 묶어 45개 그룹으로 나누고, 각 그룹을 default 프로필·fast 카테고리 서브에이전트에게 병렬 위임한다. 지시문에 다음을 명시: (1) 계정별 프로필 방문 후 "적용된 조치" 다이얼로그가 뜨면 좌상단 로고 근처 클릭으로 닫기, (2) 팔로우 버튼 텍스트를 있는 그대로(팔로우 / 팔로잉 / 맞팔로우) 보고 — 해석하지 말 것, (3) 버튼이 "팔로우"인 경우에만 고정글 제외한 최신 원글 최대 5개의 본문 앞부분과 게시시각, (4) bio·고정글·최근글 정치성 여부, (5) 가장 최신 원글이 3일 이내인지. 서브에이전트는 조사만 하고 좋아요·댓글은 직접 달지 않는다 — ref가 서브에이전트 자체 탭에서만 유효해서 본 세션이 발행을 다시 만들어야 한다. 2026-08-10 실측: 38계정 수동 조사 대비 5개 병렬 조사가 훨씬 빠르고, 다이얼로그 오탐지로 팔로워 5명을 비팔로워로 오분류할 뻔했던 수동 조사 버그도 재검증으로 잡았다.
  • 조사 결과를 바탕으로 실행 대상(계정·좋아요 대상 게시물·댓글 여부)을 미리 확정해 명단으로 만든 뒤 실제 방문을 시작한다. 방문하면서 매번 좋아요 대상을 고르지 않고, 댓글도 방문해서 바로 쓴다.
  • 검증 회도를 줄인다: 좋아요는 5개 다 누른 뒤 한 번만 상태를 확인한다(매 클릭마다 재스냅샷 금지). 댓글은 게시 후 2~3초 대기하고 본문 포함 여부를 1회 확인하면 된다. "확인 안됨"이면 바로 최신순 재정렬로 넘어가지 말고 5초 더 기다렸다가 같은 방식으로 1회만 재확인한다(인기순 정렬 때문에 새 댓글이 안 보일 수 있다). 이유 없이 같은 게시물을 두 번 이상 재제출하지 않는다 — 2026-08-10 miji74000 중복 게시 사고(게시 확인 지연을 재제출 신호로 오해해 발생) 이후 이 규칙 추가.

⚠️ 스레드 프로필은 가상 스크롤이다 — 스크롤 뒤에 좋아요 누르면 엉뚱한 글을 누른다 (2026-09-13 실제 발생)

프로필 게시물은 [data-pressable-container="true"]로 잡히는데, 아래로 스크롤하면 위쪽 게시물이 DOM에서 통째로 사라진다. "5개 로드될 때까지 스크롤 → 그때 수집"으로 짜면 최신 5개가 아니라 스크롤 끝에 남은 오래된 글에 좋아요가 나간다. 실제로 한 계정에 1~2일 전 글 5개를 눌렀고, 정작 최신 3개(50분·11시간·1일)는 빠졌다.

올바른 순서:

  1. window.scrollTo(0,0) 으로 맨 위로 간다.
  2. 보이는 대로 수집 → 조금 스크롤 → 다시 수집을 반복해 url 기준으로 누적한다(문서 순서=최신순 유지). 새 게시물이 2회 연속 안 늘면 중단(원글이 5개 미만인 계정).
  3. 누를 때는 url로 다시 찾아 없으면 위부터 다시 훑어서 찾은 뒤 scrollIntoView 후 클릭한다.

원글 판정은 스냅샷 파싱 대신 컨테이너 안 첫 번째 a[href^="/@"]의 아이디가 프로필 주인과 같은지로 본다(남의 글에 단 답글은 부모 작성자가 먼저 나온다). 고정글은 고정됨 텍스트로 걱러낸다. 팔로우 버튼은 메시지 보내기 버튼의 형제로 잡는다(게시물마다 달린 작은 팔로우 버튼과 이름이 같아서 역할/이름으로는 구분이 안 된다).

  • 프로필 미리보기 팝업이나 태그 링크를 클릭해 다른 계정으로 튀는 오작동이 가끔 생긴다(좋아요가 누락된 적이 있다). 좋아요·댓글 진행 후 페이지 타이틀이 의도한 계정과 다르면 즉시 원래 계정으로 돌아가 좋아요 상태를 전체 재확인한다.

6. "답글 노가다 하자" 실행 순서

  1. 지난 회차에 넘어간 댓글은 두 번 다시 초안에 올리지 않는다(2026-08-13 밤밤 지시 "내가 댓글 노가다 할때 넘어간거 왜또 자꾸 들고오냐"). 미답변으로 남아 있어도 그건 실수가 아니라 밤밤의 판단이다.
    • 컷오프 규칙: 직전 발행 로그(~/Projects/ops/threads-tool/reply-logs/batch_*.jsonl)의 마지막 timestamp보다 오래된 미답변 댓글은 전부 제외한다. 그 시각 이후에 새로 들어온 댓글만 대상이다.
    • 영구 스킵리스트: ~/Projects/ops/threads-tool/reply-logs/skiplist.json. 추출 직후 이 파일의 comment_id를 무조건 뺀다. 새로 넘어간 건이 생기면 매 회차 끝에 여기에 추가한다.
    • 애매해서 밤밤에게 물어봤던 건도 답을 못 받았으면 스킵리스트로 보낸다. 같은 댓글을 두 번 물어보지 않는다.
    • ⚠️ "이미 답한 것"은 사람 단위로도 본다(2026-08-23 밤밤 지적 "내가 이미 답글쓴거에도 답글을 쓸려고해?"). 추출기는 그 댓글의 직접 자식에 내 답글이 있는지만 보는데, 그러면 같은 글 안에서 그 사람과 이미 주고받은 경우를 놓친다. 실제 사례: 어떤 계정의 최상위 댓글에는 내 답글이 없었지만, 같은 글 다른 갈래에서 이미 언쟁을 한 상태였다. 거기에 순한 답글을 새로 달면 딴사람처럼 보인다. → 추출 후 각 원글 conversation에서 부모가 나(bam.bam_2)인 항목의 작성자 집합을 만들고, 그 집합에 든 사람의 댓글은 후보에서 뺀다.
    • 기존 답글과 문구가 겹치는지도 본다. 같은 글에 이미 단 내 답글들과 초안을 difflib 유사도 0.5 이상으로 비교해 걸러낸다(2026-08-23에 "이제 당당해지실 차례입니다!"가 같은 글의 "이미 잘하고 계시니 이제 당당해지시면 됩니다!"와 중복될 뻔했다).
  2. @bam.bam_2 내 글의 미답변 최상위 댓글을 라이브 API로 찾는다.
  3. 정치 관련 글을 쓰는 계정, 밤밤에게 부정적·논쟁성 댓글을 쓴 계정, 홍보·스팸, 재답글은 제외한다.
  4. 초안은 코덱스가 만든다(0장). 클로드가 직접 쓰지 않는다. 남은 전체 대상의 답글 초안을 한 번에 만든다. 모든 항목에 연속 번호를 붙여 밤밤이 1~10 발행, 12번 수정처럼 한 번에 오더할 수 있게 한다. 임의로 10개씩 끊지 않는다.
  5. 프로필은 정치 스크리닝과 맥락 파악에 쓰는 배경 자료다. 모든 답글에 상대 직업·최근 글을 억지로 끌어오지 않는다. 댓글 맥락에 먼저 반응하고, 프로필 언급은 자연스럽게 연결될 때만 쓴다.
  6. 밤밤 승인 뒤 답글을 30~45초 간격으로 발행한다. 각 대상의 username·댓글 id·부모 글 id·기존 밤밤 답글 유무를 발행 직전 재검증한다.
  7. 발행 뒤 댓글 작성자 전원을 5~8명씩 묶어 서브에이전트 병렬로 팔로워·정치·3일규칙 조사한다(5-1장). 팔로워·정치계정·계정없음은 제외하고, 남은 비팔로워 명단(계정별 좋아요 대상·댓글 여부)을 미리 확정한다.
  8. 확정된 명단을 순서대로 방문해 최신 원글 최대 5개에 좋아요를 누르고, 3일 이내 최신 원글 1개에 맞춤 댓글을 단다(3일 초과면 좋아요만). 검증은 5-1장 기준으로 최소화한다.

7. 사람 확인은 받고 간다

초안 전체를 밤밤에게 먼저 보여주고 승인받는다. 승인 없이 발행하지 않는다.

⚠️ 번호는 화면에 보이는 순서대로 1부터 연번(2026-08-23 밤밤 지적 "내가 하나씩 답변할 수 있게 번호를 메겨줘야지").

  • 원글별로 묶어서 보여주면서 번호는 추출 순서(시간순)를 쓰면 1,2,5,8,3,4...처럼 튄다. 밤밤이 1~10 발행으로 지시할 수 없다.
  • 표시 번호와 데이터 키를 반드시 같은 값으로 둔다. 2026-08-23에 화면 표시 번호로 제외 대상을 골랐는데 파일은 다른 순번을 쓰고 있어서 엉뚱한 5건이 제외되고 스팸 5건이 초안에 남았다. 제외·수정 지시를 받으면 그 번호로 파일을 조회해 대상 본문을 한 번 출력해 대조한다.
  • 표시할 땐 번호 | @계정 | 댓글 앞부분 | 답글 한 줄로. 클로드안으로 갈아낀 건 코덱스안을 같이 보여준다.

8. Threads 자동 제재(적용된 조치) 대응

어떤 답글이 Threads의 자동 모니터링(금융 사기/스캠 등)에 걸려 "적용된 조치" 알림을 받으면 — 나중에 자동 복원되었더라도 — 그 댓글은 삭제만 한다. 에이전트가 현장에서 다른 문구로 임의로 재작성해 재발행하지 않는다 — 이건 7번 규칙(사람 확인 받고 간다)을 우회하는 것이다. 대체 문구가 필요하면 새 초안으로 밤밤에게 다시 승인받는다.

  • 근본 대책은 2장 7번(초대·모집성 답글 템플릿 금지) 규칙처럼 초안 생성 단계에서 미리 막는 것이지, 발행 후 사고 대응 단계에서 임의로 고치는 것이 아니다.

Voice DNA Creator

Analyze writing samples to extract and codify a unique voice profile that AI can use to replicate your authentic writing style.

When to Use This Skill

  • Setting up a new writing system
  • Creating voice profiles for clients (ghostwriting)
  • Updating voice profiles after style evolution
  • Onboarding into content creation workflow

Requirements

The user must provide:

  • Minimum: 3 writing samples (500+ words each)
  • Ideal: 5-10 samples across different content types
  • Best: Mix of casual (social posts) and formal (articles) content

Analysis Process

Step 1: Collect Samples

Ask: "Please share 3-10 writing samples that represent your authentic voice. These can be:

  • Newsletter issues
  • Blog posts
  • Social media posts
  • Emails you've written
  • Any content where you feel 'this sounds like me'

Paste them here or point me to files."

Step 2: Analyze Core Elements

For each sample, analyze:

Personality Markers

  • What personality traits come through?
  • What's the energy level?
  • How does the writer relate to the reader?

Emotional Range

  • What emotions are expressed?
  • How intense are they?
  • What's the dominant emotional tone?

Communication Style

  • Formality level (casual to professional)
  • Sentence length patterns
  • Paragraph structure
  • Use of questions, commands, statements

Language Patterns

  • Signature phrases that repeat
  • Power words used frequently
  • Transition phrases
  • Opening and closing patterns

What They Avoid

  • Words or phrases never used
  • Tones never taken
  • Approaches avoided

Formatting Habits

  • Emoji usage
  • List usage
  • Header styles
  • Bold/italic patterns

Step 3: Synthesize Findings

Combine analysis across all samples to identify:

  • Consistent patterns (appear in most samples)
  • Contextual variations (change based on content type)
  • Core voice elements (never change)

Step 4: Generate Voice DNA

Create the profile following this structure:

{
  "voice_dna": {
    "version": "1.0",
    "last_updated": "YYYY-MM-DD",
    "core_essence": {
      "identity": "",
      "primary_role": "",
      "unique_angle": ""
    },
    "personality_traits": {
      "primary": [],
      "how_it_shows": {}
    },
    "emotional_palette": {
      "dominant_emotions": [],
      "emotional_range": {},
      "energy_level": ""
    },
    "communication_style": {
      "formality": "",
      "complexity": "",
      "sentence_structure": {},
      "paragraph_style": ""
    },
    "language_patterns": {
      "signature_phrases": [],
      "power_words": [],
      "words_to_avoid": [],
      "transitions": []
    },
    "never_say": {
      "phrases": [],
      "tones": [],
      "approaches": []
    },
    "formatting_preferences": {},
    "content_philosophy": {},
    "voice_examples": {
      "opening_lines": [],
      "closing_lines": [],
      "transitional_phrases": []
    }
  }
}

Output Instructions

  1. After analysis, present key findings in a summary
  2. Generate the complete JSON voice profile
  3. Save to /context/voice-dna.json (or suggest saving location)
  4. Provide 3 example sentences written in the captured voice for validation
  5. Ask: "Does this capture your voice? What would you adjust?"

Best Practices

  • Focus on TONE and PERSONALITY, not just word choice
  • Avoid creating a profile that just repeats phrases
  • Capture the "feeling" of the writing, not just patterns
  • Include what NOT to do (equally important)
  • Make the profile actionable for content generation

Validation Test

After creating the profile, write a short paragraph on any topic using ONLY the voice DNA as guidance. Ask the user: "Does this sound like you?"

If not, iterate on the profile based on feedback.

Common Pitfalls to Avoid

  • Don't just list frequently used words
  • Don't create a parody of the voice (too exaggerated)
  • Don't ignore context (social posts ≠ articles)
  • Don't miss the underlying personality
  • Don't forget emotional elements

웹 데모 영상 만들기

밤밤의 웹 프로젝트(모자이크, 겟백앱, 카공메이트 등) 소개 영상을 만들 때 쓰는 절차. 목업 이미지를 이어붙이는 게 아니라 실제 사이트를 실제로 조작한 화면을 찍는 게 핵심이다.

먼저 물어볼 것

영상은 어디 쓰느냐로 비율·길이가 갈린다. 만들기 전에 반드시 확인한다.

용도비율길이
스레드·릴스·쇼츠9:16 (1080x1920)15~25초
블로그·유튜브 임베드·랜딩16:9 (1920x1080)30~40초
인스타 피드·카톡 공유1:1 (1080x1080)~20초

밤밤은 시각 산출물의 형식에 구체적인 기대가 있다. 레퍼런스가 있으면 먼저 달라고 한다.

절차

1. 로컬 서버로 대상 사이트를 띄운다

cd <프로젝트> && python3 -m http.server 8899

무대(stage) 페이지와 대상 사이트는 반드시 같은 오리진이어야 한다. 포트가 다르면 iframe.contentDocument 접근이 막혀서 조작이 불가능하다. → 무대 파일을 프로젝트 폴더 안에 임시로 두고, 작업이 끝나면 반드시 빼낸다(안 그러면 다음 배포에 딸려 올라간다).

2. 무대 페이지를 만든다

assets/stage-template.html를 복사해서 고친다. 구조:

  • #stage — 출력 비율 그대로의 고정 크기 div (1:1이면 540x540, dpr 2로 캡처하면 1080x1080)
  • #cap / #foot — 큰 자막(상단) / 보조 문구(하단)
  • #win — 맥 브라우저 창 목업(신호등 3개 + URL) 안에 <iframe>을 transform: scale()로 축소해 넣음
  • #cursor — 가짜 마우스 커서 SVG. 이게 있어야 조작 영상처럼 보인다
  • #ring — 클릭·브러시 크기를 보여주는 하이라이트 원
  • #end — 엔딩 카드(제품명 / 한줄 설명 / 셀링포인트 3개 / URL)
  • window.__tick(frameIndex) — 프레임 번호 하나를 받아 그 시점의 화면 상태를 만드는 결정론적 함수

3. 타임라인을 결정론적으로 짠다

__tick(frame) 안에서 t = frame / FPS로 시간을 계산하고, 모든 상태를 t로부터 다시 계산한다. 실시간 setTimeout을 쓰면 캡처 속도와 어긋나서 망가진다.

  • 1회성 동작(이미지 로드, 모드 전환)은 once(key, fn) 으로 중복 실행을 막는다
  • 드래그는 drag(t, 시작초, 끝초, ptFn) — 시작 프레임에 mousedown, 매 프레임 mousemove, 끝나면 mouseup
  • 이벤트는 iframe의 W.MouseEvent로 만들어 clientX/clientY(iframe 기준 좌표)로 dispatch한다. mousedown은 대상 요소에, mousemove/mouseup은 보통 window에 붙어 있으니 확인하고 각각 맞는 타깃에 쏜다
  • 좌표는 하드코딩하지 말고 요소의 getBoundingClientRect() 또는 그려넣은 목업의 rect 비율로 계산한다. 창 크기를 바꿔도 안 깨진다
  • iframe 안에서 영상에 불필요한 요소(헤더, SEO 본문, 푸터, 광고 배너, 상태줄)는 iframe load 시점에 <style> 주입으로 숨긴다

4. 프레임을 캡처한다

for (let i = from; i <= to; i++) {
  await page.evaluate(f => __tick(f), i);
  const buf = await page.screenshot({ clip: { x:0, y:0, width:540, height:540 } });
  await fs.writeFile(`${DIR}/f${String(i).padStart(4,'0')}.png`, buf);
}
  • clip은 CSS 픽셀 단위다. devicePixelRatio를 곱하면 안 된다. dpr 2면 540 클립이 1080px 이미지로 나온다
  • 프레임 한 장에 약 0.09초. 400장이면 40초 → REPL 120초 제한 때문에 100~150장씩 나눠 호출한다
  • 캡처 시작 전에 페이지를 새로 로드해 상태를 초기화하고, __tick(0) 후 이미지 로드가 끝날 시간을 준다

5. ffmpeg로 합성한다

ffmpeg는 PATH에 없다. export PATH="$PATH:/opt/homebrew/bin" 를 붙인다.

ffmpeg -y -framerate 20 -i frames/f%04d.png \
  -vf "scale=1080:1080:flags=lanczos,fps=30" \
  -c:v libx264 -profile:v high -pix_fmt yuv420p -crf 20 -movflags +faststart out.mp4
  • -pix_fmt yuv420p는 SNS 호환 필수
  • 채팅에 붙여 보여줄 미리보기 GIF는 palettegen/paletteuse 2패스로: fps=10,scale=420:-1:flags=lanczos,palettegen=stats_mode=diff → paletteuse=dither=bayer:bayer_scale=3
  • 콘티 확인용 컨택트시트: select='eq(n\,20)+...',scale=340:340,tile=3x3

6. 뒷정리

  • 무대 파일을 프로젝트 폴더 밖으로 옮긴다 (배포에 섞이면 안 됨)
  • 로컬 서버 종료: lsof -ti:8899 | xargs kill -9
  • 캡처 탭 닫기

주의

  • 영상에 쓰는 예시 데이터(대화 내용, 이름, 계좌번호, 전화번호, 주소)는 전부 지어낸 가짜로 만들고, 보고할 때 가짜라고 명시한다. 밤밤의 실제 개인정보(전세금 등)나 제3자 정보는 절대 넣지 않는다
  • 무음이 기본. 음악이 필요하면 밤밤에게 확인받는다
  • 완성본은 세션 artifacts에 두되, 다시 뽑을 수 있도록 무대 파일을 영구 경로에 보관한다

부록 · 블로그 본문용 GIF (브라우저 목업 없이)

SNS 영상과 목적이 다르다. 블로그 독자는 **"이 도구가 뭘 하는지"**를 3초 안에 봐야 하므로, 맥 브라우저 창 목업·엔딩 카드 없이 작업 대상만 크게 보여주는 편이 낫다. 무대(stage) 페이지도 로컬 서버도 필요 없다. 배포된 사이트를 직접 조작하고 캔버스를 그대로 뜬다.

절차

  1. 배포 사이트를 열고 예시 이미지를 붙여넣기 이벤트로 주입한다(파일 선택 UI를 거치지 않아도 된다).
    await page.evaluate(async (b64) => {
      const blob = await (await fetch('data:image/png;base64,'+b64)).blob();
      const dt = new DataTransfer(); dt.items.add(new File([blob],'s.png',{type:'image/png'}));
      document.dispatchEvent(new ClipboardEvent('paste',{clipboardData:dt,bubbles:true}));
    }, b64);
    
  2. 영상에 불필요한 요소는 캡처 전에 숨긴다 (adInCanvas 같은 광고 영역).
  3. 좌표는 반드시 픽셀로 탐지한다. 눈대중 금지. 이번에 눈대중으로 잡았다가 펜·채우기가 엉뚱한 데 찍혀서 세 번 다시 찍었다. 캔버스 픽셀을 직접 훑어 대상 글자의 bbox를 구한다.
    const bbox = (x0,x1,y0,y1) => { /* 어두운 픽셀(r,g,b<110)의 min/max */ };
    
    노란 말풍선 같은 색 블록은 해당 색 범위로 같은 방식으로 찾는다.
  4. 프레임은 캔버스를 새 캔버스에 다시 그려서 만든다. page.screenshot({clip})은 스크롤/DPR 때문에 좌표가 어긋나기 쉽다. 자막·커서·선택 박스·브러시 원도 이 합성 단계에서 그려 넣는다.
    • 상단에 라벨 띠(무슨 모드를 쓰는지)를 넣으면 GIF 하나로 기능 여러 개를 설명할 수 있다
    • 드래그 중에는 파란 점선 선택 박스를, 펜 모드에서는 브러시 크기 원을 그린다
  5. 실제 마우스 이벤트로 조작하면서 매 스텝 프레임을 저장한다. 동작 전후로 정지 프레임 6~8장을 넣어야 눈이 따라간다.
  6. ffmpeg 2패스로 GIF 합성 (본문용은 폭 620~640px, 12fps, 70KB 안팎이면 충분).

효과 선택 주의

  • 단색 영역에 블러를 걸면 화면상 아무 변화가 없다. 평면 아바타를 블러 처리하는 컷을 넣었다가 차이가 안 보여서 뺐다. 블러는 디테일이 있는 대상에만 쓴다.
  • 펜은 모자이크보다 블러가 깔끔하다. 펜+모자이크는 블록이 흩뿌려진 것처럼 지저분하게 나온다.
  • 가리기 결과를 보여줄 땐 가린 영역 위로 원본이 삐져나오지 않았는지 마지막 프레임에서 확인한다. 살짝 비치면 여백을 더 줘서 한 번 더 덮고 뒤쪽 정지 프레임만 다시 찍으면 된다.

어디에 쓰나

  • 네이버 블로그: 사진 업로드와 동일하게 사진 버튼 → 파일 선택으로 올린다 (GIF도 그대로 애니메이션된다)
  • 티스토리: 첨부 → 사진. 업로드하면 [##_Image|...|_##] 문법이 본문에 들어가므로, 그걸 읽어서 전체 HTML을 조립한 뒤 setContent() 하면 이미지 위치를 원하는 곳에 둘 수 있다
  • 사이트 자체: <figure> + loading="lazy" + 캡션에 "예시 데이터는 전부 가짜"를 명시

Workshop Prep

Claude Code 바이브코딩 워크샵 사전 준비 퍼실리테이터.

Core Principles

  • 참석자는 뭘 자동화해야 하는지, 뭐가 가능한지 모름
  • 질문으로 생각을 이끌어내고, 예시로 가능성을 보여줌
  • 한 번에 한 질문만, 수다 떠는 느낌으로

Workflow

Phase 0: Context7 설정 확인 (필수)

⚠️ Context7 API 키가 없으면 인터뷰를 시작할 수 없습니다.

스킬 시작 전 Context7 MCP 설정 여부 확인:

  1. mcp_context7_resolve-library-id 호출 시도
  2. 실패 시 (API 키 미설정):
    • 안내: "Context7 API 키가 필요해요! 제가 대신 설정해드릴게요 😊"
    • API 키 발급 안내:
      1. https://context7.com/dashboard 접속
      2. GitHub 또는 Google로 로그인
      3. API Key 복사
      4. 여기에 붙여넣기 해주세요!
      
    • 사용자가 API 키를 붙여넣으면: a. ~/.mcp.json 파일 읽기 (없으면 생성) b. mcpServers.context7 설정 추가:
      "context7": {
        "command": "npx",
        "args": ["-y", "@upstash/context7-mcp", "--api-key", "{사용자가_입력한_키}"]
      }
      
      c. 파일 저장 d. "설정 완료! Claude Code를 재시작해주세요. 재시작 후 다시 '워크샵 준비해줘'라고 말씀해주세요!"
    • Claude Code 재시작 필요 안내 (MCP 설정은 재시작해야 적용됨)
  3. 성공 시: Phase 1로 진행

진행 불가 안내:

  • "외부 서비스 연동 가이드를 만들려면 Context7이 꼭 필요해요!"
  • "API 키만 붙여넣어 주시면 제가 알아서 설정해드릴게요 👍"

Phase 1: Warmup

역할 파악. "지금 회사에서 어떤 일을 맡고 계세요?"로 시작.

  • 꼬리질문: 하루가 어떻게 흘러가는지, 어떤 툴을 많이 쓰는지

Phase 2: Find Repetitive Tasks

구체적 예시와 함께 반복 업무 탐색. See examples.md for role-specific categories.

  • 얼마나 자주? 한 번에 시간이 얼마나?
  • 어디서 시작해서 어디서 끝나는지?

Phase 3: Map the Process

시작점 → 과정 → 결과물 순서로 파악.

  1. 시작점: 이 일이 시작되는 계기
  2. 과정: 그 다음 뭘 하는지, 어디서 뭘 여는지
  3. 결과물: 최종적으로 뭐가 나오는지, 어디에 공유하는지

Phase 4: Show Possibilities

맥락 파악 후 비슷한 자동화 사례 제시. See examples.md for role-specific automation examples.

Phase 4.5: Tech Detection

외부 연동 필요성 파악. Phase 3에서 파악한 "결과물 목적지"를 기반으로 질문.

핵심 질문:

  • "이 결과물은 어디에 저장하거나 공유하세요?"
  • "혹시 이메일로 보내거나, 슬랙에 올리거나, 드라이브에 저장하시나요?"

답변 분석: 사용자 답변에서 키워드를 감지하여 필요한 연동 도구 파악. See integrations.md for keyword-to-MCP mapping.

키워드 예시연동 도구
이메일, 메일, GmailGoogle Workspace
슬랙, Slack, 채널Slack
드라이브, Drive, 파일 저장Google Workspace
줌, Zoom, 녹화Zoom
유튜브, 영상 업로드YouTube
노션, NotionNotion

연동 방식 판단 (단방향 vs 양방향):

패턴예시연동 방식
단방향 (발송/출력만)슬랙에 보내기, 드라이브에 업로드, 이메일 발송스크립트
양방향 (읽기+쓰기)에어테이블 조회 후 수정, 노션 검색 후 업데이트, 시트에서 읽고 쓰기MCP

⚠️ DB/스프레드시트는 무조건 MCP:

  • Airtable, Google Sheets, Excel, Supabase, Firebase, PostgreSQL 등
  • 이유: CRUD가 기본이고, AI가 상황에 맞게 조회/수정을 판단해야 함
  • 단순 "행 추가"만 해도 MCP 권장 (나중에 확장 가능성 높음)

감지 후 확인 (⚠️ 반드시 추천 포함):

원칙: 사용자는 스스로 뭘 원하는지 모른다. 열린 질문을 하면 "그것도 좋겠네요!"하며 범위가 폭발한다. 현재 워크플로의 끝점에 맞춰 추천하고, 확장은 사용자가 명시적으로 요청할 때만.

❌ 나쁜 질문 (열린 질문):

  • "슬랙에서 보내기만 하세요, 아니면 찾아보기도 하세요?"

✅ 좋은 질문 (추천 포함):

  • "[현재 워크플로 요약]이니까, [추천 방식]으로 충분할 것 같아요! 맞죠?"

예시:

  • "회의록 정리해서 노션에 올리시는 거니까, 페이지 생성만 하면 될 것 같아요!"
  • "데이터 모아서 시트에 기록하시는 거니까, 행 추가만 하면 될 것 같아요!"
  • "결과 요약해서 슬랙에 공유하시는 거니까, 메시지 발송만 하면 충분해요!"
  • 여러 서비스 감지 시: "이메일이랑 슬랙 둘 다 사용하시는데, 둘 다 보내기만 하시면 될 것 같아요!"

확장 질문은 사용자가 먼저 언급했을 때만:

  • "혹시 기존 데이터 찾아서 수정하는 것도 필요하세요?" (사용자가 검색/수정 언급한 경우만)

복잡도 안내:

  • 연동 도구 0개: "별도 설정 없이 바로 시작할 수 있어요!"
  • 연동 도구 1개 (쉬움): "당일 워크샵에서 금방 설정할 수 있어요."
  • 연동 도구 1개 (중간/어려움) 또는 2개 이상: "이 연동은 워크샵 전에 미리 설정해두시면 좋아요. 설계서에 가이드 넣어드릴게요!"

Phase 5: Crystallize

아이디어 정리 및 확정.

  • 당신의 반복 업무: [파악한 내용]
  • 스킬로 만들면: [스킬 이름], [트리거], [결과물]

스킬명 영문화 규칙:

  • 스킬 이름은 영어 kebab-case 필수
  • 예시: "주간 보고서 생성기" → "weekly-report-generator"
  • 안내 문구: "스킬 이름은 영어로 지어야 해요. 예를 들어 'weekly-report' 이런 식으로요!"
  • 변환 도움: 한글명 → 영문 제안 제공

범위 판단 (⚠️ 기본은 "다 해도 돼요!"):

원칙: Claude Code가 구현하면 연동만 세팅되어 있으면 대부분 금방 만든다. 스콥이 적절하면 적극적으로 "다 하자!"고 추천. 줄이는 건 정말 클 때만.

스콥기준대응
적절연동 3개 이하, 단방향 위주"이 정도면 다 만들 수 있어요! 전부 해볼까요?"
약간 큼연동 4개 또는 양방향 2개 이상"다 할 수 있는데, 우선순위만 정해둘까요? 시간 남으면 나머지도!"
너무 큼연동 5개 이상 + 복잡한 로직"4시간 워크샵이라 핵심만 먼저 해보고, 나머지는 확장 과제로 남겨둘까요?"
  • 너무 작으면 → "더 추가하고 싶은 거 있으세요?"

Phase 6: Generate Design Doc

확정되면 설계서 출력. See template.md for full template.

병렬 Context7 조사:

  • 감지된 서비스 목록 확정
  • 각 서비스별로 병렬 조사 (librarian agent 사용)
  • 조사 결과로 연동가이드/{서비스}.md 생성

연동가이드 파일 상단 안내 (필수): 각 연동가이드 파일 상단에 다음 내용 포함:

> 📚 **참고 문서**: [Context7에서 조사한 공식 문서 URL 또는 라이브러리 ID]
> 
> ⚠️ **안내**: 이 가이드는 AI가 공식 문서를 참고하여 작성했으며, 정확하지 않을 수 있습니다.
> 설정하다가 막히면 Claude Code에게 "이 부분이 안 돼요"라고 물어보면서 진행하세요!
> Claude Code가 최신 문서를 다시 찾아서 도와드릴 거예요 😊

외부 연동 테이블 가이드 링크 (필수):

  • "한눈에 보기" 섹션의 외부 연동 테이블에 가이드 컬럼 필수
  • 각 서비스별로 연동가이드 파일 링크 연결
  • 형식: [📘 설정 가이드](연동가이드/{서비스명}.md)
  • 사용자가 테이블에서 바로 클릭해서 가이드로 이동 가능

워크플로 시각화 규칙 (필수):

  • 방향: 반드시 flowchart LR (가로 방향) 사용
    • 세로(TB)는 길어서 스크롤 필요 → 한눈에 안 들어옴
    • 가로(LR)는 "시작→끝" 흐름이 직관적
  • 노드 텍스트: 이모지 + 짧은 키워드 (2-4글자)로 간결하게
  • 스타일: 일반(노란), API(보라 테두리), 성공(초록), 오류(빨강)

저장 위치: 현재 열려있는 프로젝트 폴더 하위에 {스킬명}/ 폴더 생성

폴더 구조:

프로젝트루트/
└── {스킬명}/
    ├── {스킬명}-설계서.md
    ├── 사전설문응답.md          # 인터뷰 Q&A 기록
    ├── .env.example            # 필요한 환경변수 목록 (배포용)
    ├── .gitignore              # .env 제외 설정
    └── 연동가이드/              # 외부 연동 있을 때만
        ├── {서비스1}.md
        └── {서비스2}.md

환경변수 자동 설정 (외부 연동 시):

감지된 서비스가 있으면, 환경변수 설정을 안내하고 자동으로 설정해줌.

  1. 안내: 필요한 환경변수와 발급 방법 안내

    이 스킬에는 Slack 연동이 필요해요!
    
    📋 필요한 환경변수: SLACK_BOT_TOKEN
    
    🔑 발급 방법:
    1. https://api.slack.com/apps 접속
    2. "Create New App" → "From scratch" 선택
    3. Bot Token Scopes에 chat:write 추가
    4. "Install to Workspace" 클릭
    5. Bot User OAuth Token 복사 (xoxb-로 시작)
    
    토큰을 알려주시면 제가 .env 파일에 설정해드릴게요!
    (나중에 해도 돼요. 지금은 엔터를 눌러 넘어가세요)
    
  2. 입력 처리: 사용자가 키를 알려주면 자동 저장

    • "슬랙 토큰은 xoxb-xxxx야" → .env에 SLACK_BOT_TOKEN=xoxb-xxxx 저장
    • 여러 키도 한 번에: "슬랙은 xoxb-xxx, 노션은 secret_xxx"
    • 나중에 설정하겠다고 하면 → 스킵하고 진행
  3. 파일 생성:

    • .env: 실제 값 저장 (로컬 전용)
    • .env.example: 변수명만 + 발급 URL 코멘트 (배포용)
    • .gitignore: .env 제외 설정
  4. .env.example 형식:

    # Slack Bot Token
    # 발급: https://api.slack.com/apps
    SLACK_BOT_TOKEN=
    
    # Notion API Key  
    # 발급: https://www.notion.so/my-integrations
    NOTION_API_KEY=
    
  5. .gitignore 내용:

    # 환경변수 (민감정보)
    .env
    .env.local
    

환경변수 매핑: See integrations.md - "환경변수" 컬럼 참조

사전설문응답.md 생성:

  • 인터뷰 중 모든 질문/답변을 넘버링하여 기록
  • 포맷:
    # 사전설문 응답 기록
    
    **스킬명**: {스킬명}
    **일시**: {날짜}
    
    ---
    
    ## Q1. 지금 회사에서 어떤 일을 맡고 계세요?
    **A1.** {사용자 답변}
    
    ## Q2. 하루가 어떻게 흘러가나요?
    **A2.** {사용자 답변}
    
    ...
    

동적 가이드 생성 (Context7 실시간 조사):

Phase 4.5에서 감지된 연동 도구가 있다면, 설계서의 "기술 셋업 가이드" 섹션을 실시간으로 생성:

  1. 서비스 확정: Phase 4.5에서 감지된 서비스 목록 확인
  2. Context7로 조사: 각 서비스별로 최신 MCP 설정 방법 검색
    "{서비스명} MCP 서버 설정 방법"
    - 설치 명령어
    - 필요한 API 키/토큰
    - 인증 설정 단계
    
  3. 가이드 생성: 조사 결과를 비개발자 친화적으로 정리
  4. 플레이스홀더 대체: template.md의 플레이스홀더를 실제 내용으로 대체
    • [MCP_LIST] → 감지된 서비스 목록 (예: "Gmail, Slack")
    • [PREP_REQUIRED] → 복잡도 기반 안내
    • [SETUP_TIME] → 조사된 예상 시간 합산
    • [DYNAMIC_SETUP_GUIDE] → Context7 조사 결과 기반 맞춤 가이드

Edge Cases:

  • 감지된 서비스 0개 → B 섹션 전체 생략, 연동가이드 폴더 미생성
  • Context7 조사 실패 → 정적 복잡도 정보만 사용

복잡도 기반 안내 (See integrations.md):

  • 연동 0개: "별도 설정 불필요"
  • 쉬움 (API 키만): "당일 설정 가능 (약 10-15분)"
  • 중간 (OAuth): "사전 설정 권장 (약 20-30분)"
  • 어려움 (앱 등록): "사전 설정 필수 (약 30-40분)"

Phase 7: Deploy (워크샵 후)

⚠️ 이 Phase는 워크샵 당일 스킬을 실제로 만든 후에만 실행됩니다. 사용자가 "이 스킬 배포해줘", "GitHub에 올려줘" 등 명시적으로 요청할 때만 진행.

스킬 구현 완료 후, GitHub에 배포하여 다른 사람도 설치할 수 있게 함.

트리거 문구:

  • "스킬 배포해줘"
  • "GitHub에 올려줘"
  • "공유할 수 있게 해줘"

사전 조건 확인:

  1. 스킬 폴더 확인: SKILL.md 파일이 존재하는지 확인
    • 없으면: "아직 스킬이 없는 것 같아요! 설계서만 있으면 배포할 수 없어요."
  2. Git 설치 확인: git --version 확인
    • 없으면: Git 설치 안내
  3. GitHub CLI 확인: gh --version 확인
    • 없으면:
      GitHub CLI가 필요해요! 설치해드릴까요?
      
      macOS: brew install gh
      Windows: winget install GitHub.cli
      
      설치 후 다시 "배포해줘"라고 말씀해주세요!
      

GitHub 로그인 확인:

gh auth status
  • 로그인 안 되어 있으면:
    GitHub에 로그인이 필요해요!
    
    1. 아래 명령어를 터미널에 입력하세요:
       gh auth login
    
    2. 화면 안내에 따라 GitHub 계정으로 로그인
    
    완료되면 다시 "배포해줘"라고 말씀해주세요!
    

배포 워크플로우:

  1. README.md 자동 생성:

    • 설계서 기반으로 배포용 README 생성
    • 포함 내용:
      • 스킬 이름 및 설명
      • 설치 방법 (curl/powershell 원클릭)
      • 환경변수 설정 방법 (.env.example 참조)
      • 사용법 (트리거, 예시)
      • 라이선스
  2. 파일 준비 확인:

    배포 전 확인할게요!
    
    ✓ SKILL.md - 스킬 정의
    ✓ README.md - 설치 가이드
    ✓ .env.example - 환경변수 예시
    ✓ .gitignore - .env 제외
    
    이 파일들로 GitHub 레포를 만들까요?
    
  3. 레포 생성:

    # 현재 폴더에서 git 초기화 (없으면)
    git init
    
    # GitHub 레포 생성 (공개)
    gh repo create {스킬명} --public --source=. --push
    
  4. 완료 안내:

    🎉 배포 완료!
    
    📦 레포지토리: https://github.com/{username}/{스킬명}
    
    📋 설치 명령어 (다른 사람에게 공유):
    
    macOS/Linux:
    curl -fsSL https://raw.githubusercontent.com/{username}/{스킬명}/main/install.sh | bash
    
    Windows:
    irm https://raw.githubusercontent.com/{username}/{스킬명}/main/install.ps1 | iex
    
    이 링크를 팀원들에게 공유하면 누구나 설치할 수 있어요! 🚀
    

(deploy-templates.md는 유실됨 — 배포 시 각 단계별 입력에서 필요한 템플릿 실시간 생성)

Conversation Style

  • 한 번에 한 질문만
  • 답변에 공감 ("아 그거 진짜 귀찮죠!")
  • 모르겠다고 하면 예시로 힌트
  • 막히면: "최근에 '아 이거 왜 매번 내가 해야 해...' 싶었던 순간 있으세요? 사소한 것도 좋아요."

Sponsors

Details

Marketplace
bam-bam-2/solo-skills
Author
안태현 (밤밤)
Category
Community
License
MIT
Keywords
productivity, automation, solopreneur, korean, agent-skills