Playbook 패턴

docs.axelabs.ai 의 일부 페이지는 단순 reference 가 아니라 행위 단위 (셋업 / 배포 / 공지 / 복구) 다. 이런 페이지는 사람이 직접 read 해서 따라가는 것 외에, 사용자가 자기 AI session 에 URL + 짧은 prompt 를 던져 step-by-step interactive 로 진행시키는 방식이 표준이다 (D-docs-playbook).

본 페이지 = 새 playbook 작성 시 따를 형식의 SSOT. 형식 drift 가 곧 페이지마다 사용자 mental model 재학습 비용 = 패턴 가치 훼손이라 박제한다.

무엇이 playbook 이고 무엇이 아닌가

페이지 성격	playbook?	이유
셋업 (SSH 진입, vault setup, MCP connector 추가)	✅	사용자가 단계 따라가야 끝남
배포 (release-flow, customer onboarding D-day)	✅	운영자 손에서 N 명령 순차 실행
운영자 공지 (Teams DM broadcast, mail broadcast)	✅	한 번에 N 사람 대상으로 행위
복구 (vault recovery, postgres restore)	✅	사고 시 명령 순서 + 검증 매 step
decision / 결정 기록 (D-ops-*)	❌	사실 기록. 행위 트리거 아님
아키텍처/모델 (domains, data, artifacts)	❌	reference. 사용자가 행위로 변환 안 함
backlog / known-gaps / updates	❌	메타 운영 — 페이지가 entry point 지만 행위 단위 X

판단 기준: “본 페이지를 끝까지 따라가면 사용자 환경 또는 외부 시스템 상태가 변하는가?” → 변하면 playbook.

표준 형식

Frontmatter


---
title: <행위 명사구 또는 짧은 페이지명>
description: <한 줄 — 행위 + 외부 dependency + 완료 기준. 본 페이지 fetch 한 AI 가 prereq 판단할 수 있게 명시>
playbook: true
---

playbook: true 는 machine-readable marker — 후속 build-time catalog 자동 생성 / search filter / 외부 agent 가 “행위 단위 페이지만” 골라낼 때 anchor. 본 SSOT 의 “현 playbook 목록” 표가 수동 인덱스, frontmatter 가 자동 인덱스의 단일 진실.

Sidebar marker

해당 페이지의 _meta.js entry title 앞에 ⚡ prefix 추가 — Nextra sidebar 에서 사람이 페이지 열기 전 “이 페이지는 AI 던지기 가능한 행위 단위” 식별:


// content/onboard/_meta.js (예)
export default {
  index: '신규 직원 가이드',                       // 안내, marker 없음
  'ssh-access': '⚡ SSH 로컬 작업',                // playbook
  'vault-setup': '⚡ Vault setup (KDF + 4 client)', // playbook
  troubleshooting: '문제 해결',                    // reference, marker 없음
}

본문 구조 (필수 순서)


# <행위 명사구>
 
(선택) 1-2 문장 페이지 정체성 — 무엇을 하는 페이지인지, legacy 페이지가 있다면 cross-link.
 
## AI 요청 프롬프트
 
```
<표준 prompt block — 다음 절 참고>
```
 
본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.
 
페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.
 
## Prereq
 
- <권한 / 자격>
- <환경 / 머신 / 네트워크>
- <사전 자료 (email, key, manifest 등)>
 
## Step 1: <첫 단계>
## Step 2: ...
 
(또는 단계가 크면 `## Phase 1 (...)` / `## Phase 2 (...)` 패턴)
 
## 함정 정리
 
| # | 함정 | 우회 |
|---|---|---|
| 1 | <증상> | <대응> |
 
## 완료 후 (선택)
 
- <done criteria>
- <후속 회신 / Ship Log / 운영자 통보>

표준 prompt block 템플릿

코드 블록 안의 내용:


https://docs.axelabs.ai/<path> 따라 <행위 한 줄 요약> 해줘.

진행:
1. <환경/머신 진단 — OS, 기존 설치 여부, 권한>
2. <페이지 Prereq 확인 + 조건 분기 (해당 시 skip)>
3. 페이지의 각 Step 명령 실행 + 검증, 매 step 결과 받고 다음
4. 함정 발생 시 페이지 "함정 정리" 표 따라 우회
5. <완료 후 done criteria — 운영자 회신 / Ship Log / 검증 산출물>

고정 element (모든 playbook 동일):

첫 줄 = 페이지 URL + “따라” + 행위 + “해줘”
step 3 = “페이지의 각 Step 명령 실행 + 검증, 매 step 결과 받고 다음” (낱말 그대로)
step 4 = “함정 발생 시 페이지 ‘함정 정리’ 표 따라 우회” (낱말 그대로)

가변 element:

step 1-2 = 행위에 따른 사전 진단 (운영자 broadcast 는 “Blueprint LIVE 확인” / SSH 셋업은 “OS 진단” 등)
step 5 = 완료 기준 (Teams 회신 / Ship Log / 운영자 통보 등)

표준 꼬리 (prompt block 다음 2줄)


본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

낱말 그대로 복붙. AI session 후보 4 개 순서 고정 (Claude Code · Cursor · ChatGPT 데스크탑 · Claude.app · 기타).

현 playbook 목록

표 = scripts/generate-playbook-catalog.mjs 가 frontmatter playbook: true 페이지 인덱싱해서 marker 사이 자동 채움. package.json 의 prebuild 가 자동 hook — npm run build 마다 갱신. ad-hoc 호출은 npm run catalog. script idempotent (변경 없을 때 file 안 만짐) 라 매 build 마다 working tree dirty 0. 본 표 직접 편집 X — 새 playbook 추가 = 페이지 frontmatter 만, build (또는 catalog) 한 번 → 표 + JSON 갱신 → 결과 commit.

machine catalog = public/playbooks.json (count + URL + title + action + audience, deterministic, no timestamp).

Playbook	행위	대상
AXE MCP connectors (claude.ai + Claude Code 자동 sync)	claude.ai 의 Custom Connector 등록에 Bitwarden 브라우저 확장 + AXE Vault `MCP Connectors` collection 활용	직원 / customer 직원
Microsoft 365 connector	OneDrive · Outlook · Teams 통합 (Anthropic 제공)	직원 / customer 직원
SSH 로컬 작업 (Claude Code / Cursor / 기타 AI session)	AXE macmini 에 SSH 진입해 로컬 작업하는 표준 절차	직원 / customer 직원
Vault setup — KDF rotation + 4 client + Bitwarden Authenticator	AXE Vaultwarden 의 SSO→MP unlock 정상화 (KDF rotation, 옛 user 만) + 데스크톱/Chrome/Mobile 3 client + Bitwarden Authenticator 표준 setup	직원 / customer 직원
Cloudflared 재기동	cloudflared 가 죽었거나 config 변경 시 5초 다운타임 절차	운영자
신규 Customer Onboarding	운영자 측 자동화 + 수동 touchpoints	운영자
Frame DB 복구	frame-postgres 손상/migration 사고/silent corruption 대응	운영자
Blue/Green Deploy	frame 무중단 배포 절차	운영자
직원 퇴사	퇴사한 직원의 모든 access 차단 절차	운영자
신규 직원 등록	customer admin 으로부터 신규 직원 추가 요청 받았을 때 운영자 절차	운영자
macmini 손실	customer macmini 도난/화재/완전 손실 시 1-day 복구	운영자
운영자 broadcast — Teams DM 으로 임직원 1:N 공지	Blueprint `/api/admin/broadcast-dm` REST 로 bot identity ([email protected]) → AXE 임직원 1:N Teams DM	운영자
Release flow (axe ship)	코드 변경 → 운영 반영까지의 release-gate	운영자
Secret Rotation	모든 비밀 회전의 단일 명령 — axe secret rotate	운영자
Vaultwarden 복구	self-host vault 복구, OIDC 깨짐 대응, sso_nonce 수동 패치	운영자

신규 playbook 추가 흐름 = (1) 페이지 frontmatter playbook: true + 본문 표준 형식 + sidebar ⚡ prefix → (2) npm run build (또는 npm run catalog) 한 번 실행 → 본 표 + JSON 자동 갱신 → (3) git commit 묶음.

함정 / drift 회피

함정	우회
AI session 후보 나열 순서를 자기 임의로 바꿈 (예: Claude.app 을 첫 자리)	본 SSOT 의 4 후보 순서 (Claude Code · Cursor · ChatGPT 데스크탑 · Claude.app) 낱말 그대로
꼬리 2줄을 1줄로 압축 (vault-setup·operator-broadcast 의 초기 drift)	2줄 분리 유지 — 읽기 부담 ↓ + AI 가 첫줄 (후보 식별) 과 둘째줄 (행위 지시) 별도 cue 로 파싱
`## AI 요청 프롬프트` 헤딩 변형 (옛 `🤖 AI 에 던질 prompt (...)` 잔존 / 다른 단어로 paraphrase)	낱말 그대로. 사람 + AI 둘 다 visual anchor 로 사용 — 일치 안 하면 “이 페이지 playbook 인가?” 재판단 비용
prompt block 안 첫 줄에 URL 안 적고 페이지 안에서 “위 페이지” 식 indirect 참조	URL 명시 — AI 가 본 prompt 만 보고 페이지 fetch 가능해야 self-contained
step 3-4 의 표준 문구를 paraphrase (“각 step 따라가 줘” / “함정 표 보고” 등)	낱말 그대로 — AI 가 페이지의 `## 함정 정리` 표를 anchor 로 매핑하는 cue
페이지 본문에 prompt 안 step 과 실제 `## Step N` heading 의 번호 불일치	prompt step 5 = 페이지의 마지막 행위, prompt 안 step N = 페이지 Step N 으로 1:1 매핑 권장

새 playbook 추가 체크리스트

신규 페이지가 위 “무엇이 playbook 인가” 판단으로 playbook 이면:

Frontmatter title + description + playbook: true 작성 (description 한 줄에 행위 + dependency + 완료 기준)
## AI 요청 프롬프트 헤딩 + code block + 표준 꼬리 2줄 복붙 — code block 안만 행위에 맞게 가변
## Prereq / ## Step N 또는 ## Phase N / ## 함정 정리 / ## 완료 후 순서 — 누락 시 본 SSOT 표 한 줄로 reject
본 페이지 (architecture/playbooks) 의 “현 playbook 목록” 표 = script 자동 생성, 수동 편집 X — scripts/generate-playbook-catalog.mjs 가 frontmatter playbook: true 페이지 인덱싱해서 marker 사이 표 + public/playbooks.json 갱신. prebuild 자동 hook 또는 npm run catalog (ad-hoc) → 결과 commit. script idempotent 라 build 마다 dirty 0
해당 폴더의 _meta.js entry title 앞에 ⚡ prefix 추가 (sidebar marker)
페이지가 운영자 행위면 content/ops/runbook/, 직원/customer 행위면 content/onboard/ — 위치 혼동 시 sidebar 카테고리 가시성 ↓ + catalog audience 매핑 잘못