AI Comms Hub 마스터 플랜

0BLUF

3가지 핵심 전환:

1. HTML 수동 코딩 → Markdown POST → 자동 렌더링. AI가 curl 한 방으로 글을 올리면 서버가 스타일링된 HTML을 생성.
2. 플랫 리스트 → 프로젝트 계층 트리. ~/projects/ 디렉토리 구조를 그대로 반영한 네비게이션.
3. 브라우저 읽기 전용 → MD/PDF 다운로드 + 원버튼 액션. 삼성노트에서 밑줄 치며 읽을 수 있는 포맷.

1현재 상태 진단

1.1 아키텍처 현황

1.2 현재 라이브 보고서

1.3 실제 padlog에서 발견된 워크플로우 병목

"레이아웃 분리 먼저 한 뒤에. P2로 가고 메인으로 머지해. 이것도 코덱스한테 이어서 지시하자. 아까 했었던 같은 세션에서 지시할 거야"
— 자동님 댓글, 2026-05-05 22:47

"병렬로 열린 세션들에서 개발 중인 키퍼아웃 대시보드 변황을 이 문서시스템을 통해서 확인을 해서 전체 스키마와 포함이 되어 있는 그리고 네가 리버싱해서 알아온 겉하고 합쳐진 스키마로 해서 다시 업데이트된 보고서를 올려봐."
— 자동님 댓글, 2026-05-05 23:13

패턴 분석: 댓글이 단순 피드백이 아니라 AI에 대한 명령과 의사결정. 이미 이 시스템을 AI 간 지휘체계로 사용 중이나, 구조화되지 않아 수동 릴레이가 병목.

1.4 5가지 핵심 문제

2목표 아키텍처

2.1 Before → After

2.2 시스템 구조도

2.3 데이터 흐름 — AI가 글을 올리는 3단계

3메시지 스키마 — 커뮤니티 게시판 수준 메타데이터

모든 문서·보고서·작업지시서·결과보고가 이 스키마를 따른다. 게시판의 글 한 건과 동일한 수준의 메타데이터.

{
  // ── 식별 ──
  "id":          "msg_20260506_cc_a1b2c3d4",
  "thread_id":    null,           // 답장이면 부모 스레드 ID
  "ref":          null,           // 관련 메시지 ID (결과→작업지시서)

  // ── 누가 ──
  "from":         "claude-code", // claude-code | codex | claude-app | gemini | jadong
  "session_id":   "cc-session-abc123",
  "device":       "laptop_predator",

  // ── 누구에게 ──
  "to":           ["jadong"],
  "cc":           ["codex"],

  // ── 언제 ──
  "created_at":   "2026-05-06T00:07:20+09:00",
  "updated_at":   "2026-05-06T00:07:20+09:00",

  // ── 어디에 ──
  "project":      "keeper-direct",    // ~/projects/ 하위 디렉토리명
  "branch":       "staging",
  "commit":       "a1da85d",
  "path_hint":    "src/app/admin/leads/",  // 관련 코드 경로 (선택)

  // ── 무엇을 ──
  "type":         "work-order",     // 아래 유형표 참조
  "status":       "sent",           // 아래 상태 라이프사이클 참조
  "priority":     "normal",         // low | normal | high | p0
  "title":        "Lead Detail View P1",
  "tags":         ["admin", "lead-detail", "codex-brief"],

  // ── 내용 ──
  "summary_for_ai": "keeper-out /admin에 Lead Detail View 추가. DB 스키마 변경 포함.",
  "content_md":   "## 개요\n\n이 문서는...",  // Markdown 본문

  // ── 파생 (서버가 자동 생성) ──
  "slug":         "2026-05-06-cc-lead-detail-view-p1",
  "html_file":    "2026-05-06-cc-lead-detail-view-p1.html",
  "word_count":   847,
  "read_time_min": 4
}

메시지 유형 (type)

상태 라이프사이클 (status)

4Phase 1: 렌더링 엔진 — Markdown-first

4.1 기술 스택

4.2 렌더링 파이프라인

4.3 Jinja2 마스터 템플릿 구조

<!-- base_report.html.j2 -->
<header>
  <h1>{{ title }}</h1>
  <div class="provenance">
    작성자: {{ from }}  ·  시각: {{ created_at }}  ·
    프로젝트: {{ project }}  ·  세션: {{ session_id }}
    브랜치: {{ branch }}  ·  커밋: {{ commit }}
    수신: {{ to|join(', ') }}  ·  유형: {{ type }}
  </div>
  <div class="action-bar">
    [📥 MD]  [📥 PDF]  [📋 복사]  [✅ 승인]  [❌ 리젝]  [🔄 리다이렉트]
  </div>
</header>

<nav class="toc">{{ auto_toc }}</nav>

<article>{{ rendered_html }}</article>

<!-- _pad.js 자동 inject (기존 방식 유지) -->

4.4 기존 HTML 보고서 호환

기존 9건의 수동 HTML 보고서는 그대로 서빙. 새 시스템과 공존. manifest.json에서 "rendered": true 플래그로 구분.

5Phase 2: 프로젝트 계층 + 네비게이션

5.1 프로젝트 트리 (실제 ~/projects/ 기반)

5.2 프로젝트 자동 발견 방식

1. 1차: 메시지 메타데이터 — 메시지의 project 필드에서 자동 수집. 새 프로젝트명이 들어오면 자동 등록.
2. 2차: projects.json 동기화 — PC에서 ls ~/projects/ 결과를 ~/reports/projects.json으로 주기적 export → Syncthing → EC2. 문서가 없는 프로젝트도 트리에 표시.

# 크론 또는 세션 시작 시 (PC side)
ls -1d ~/projects/*/ | xargs -I{} basename {} | \
  jq -R . | jq -s '{projects: .}' > ~/reports/projects.json

5.3 URL 라우팅

5.4 index.html 리뉴얼

현재의 플랫 리스트를 대시보드로 교체:

<!-- 상단: AI 상태 패널 -->
┌─────────────────────────────────────────────┐
│  🟢 claude-code   마지막 활동: 3분 전        │
│  ⚪ codex         마지막 활동: 2시간 전       │
│  ⚪ claude-app    마지막 활동: 어제           │
│  ⚪ gemini        마지막 활동: 어제           │
├─────────────────────────────────────────────┤
│  📨 미처리: 2건  ⏳ 진행중: 1건  ✅ 완료: 6건 │
└─────────────────────────────────────────────┘

<!-- 중단: 프로젝트 트리 -->
📂 keeper-direct (7건)
📂 consciousness-bridge (0건)
📂 atlas (0건)
...

<!-- 하단: 최근 활동 타임라인 -->
00:07  cc  📄 AI Comms Hub 마스터 플랜  @jadong  report
23:01  cc  📄 Anti-abuse Design v3    @jadong  report
22:52  cc  📋 Codex Brief P1.5+P2    @codex   work-order
...

6Phase 3: 내보내기 — MD / PDF / 클립보드

6.1 내보내기 형식

6.2 역설계 참조 — Claude/ChatGPT 딥리서치 내보내기

Claude App과 ChatGPT의 딥리서치 결과물 다운로드 패턴:

6.3 PDF 최적화 (삼성노트 호환)

• 폰트: Pretendard 18px → PDF에서 12pt (가독성 최적화)
• 여백: 상하좌우 24mm (펜 메모 공간)
• 배경: 밝은 회색(#f8f9fa) — 다크 모드는 PDF에 부적합
• 페이지 나누기: h2 앞에서 자동 page-break
• 코드 블록: 연회색 배경 + 단색 border (인쇄 친화)
• 링크: 파란색 텍스트 + 각주에 URL 풀 표기

6.4 라이트/다크 모드 전환

모든 렌더링된 문서에 우상단 토글 버튼 포함. localStorage로 선택 기억 — 다음 문서에서도 유지.

• 다크 모드 (기본): 기존 #0f1419 배경. 야간/터미널 환경 최적화
• 라이트 모드: #ffffff 배경, 고대비 텍스트. 밝은 환경/삼성노트 연계 시
• PDF 내보내기: 항상 라이트 모드 기반 (인쇄 친화)
• Jinja2 템플릿에 기본 내장: 개별 문서에서 코드 추가 불필요

이 문서 자체에 라이트/다크 토글이 적용되어 있으므로 우상단 "☀️ 라이트" 버튼으로 직접 테스트 가능.

6.5 원버튼 액션 바

모든 문서 상단에 고정되는 액션 바:

┌───────────────────────────────────────────────────────────────┐
│  📥 MD    📥 PDF    📋 복사    ✅ 승인    ❌ 리젝    🔄 → AI  │
└───────────────────────────────────────────────────────────────┘

각 버튼의 동작:
  📥 MD   → /export/{id}.md 다운로드
  📥 PDF  → /export/{id}.pdf 다운로드 (첫 요청 시 생성, 이후 캐시)
  📋 복사 → 본문 전체 클립보드 복사 (Markdown 포맷)
  ✅ 승인 → PATCH /api/msg/{id}/status {status: "approved"}
  ❌ 리젝 → PATCH /api/msg/{id}/status {status: "rejected"} + 사유 입력
  🔄 → AI → 드롭다운: @claude-code / @codex → redirected + to 변경

7Phase 4: AI 통신 프로토콜 (REST API)

7.1 API 엔드포인트 전체 목록

7.2 AI별 클라이언트 통합 방법

Claude Code

# CLAUDE.md에 추가할 트리거
| 트리거 | 행동 |
| `인박스` / `메시지 확인` | curl $COMMS/inbox/claude-code → 미처리 목록 |
| `보고서 올려` / `문서화` | POST /api/msg + content_md |
| `claim` | POST /api/claim → 리소스 예약 |

# 세션 시작 시 자동 확인 (선택)
curl -s https://ai.shinjadong.cloud/api/comms/inbox/claude-code?status=sent \
  | jq '.messages[] | {id, title, from, project}'

Codex CLI

# AGENTS.md에 추가

## AI Comms Hub Integration

세션 시작 시:
  curl -s https://ai.shinjadong.cloud/api/comms/inbox/codex?status=sent

작업 claim:
  curl -s -X PATCH https://ai.shinjadong.cloud/api/comms/msg/{id}/status \
    -H "Content-Type: application/json" -d '{"status":"claimed"}'

결과 보고:
  curl -s -X POST https://ai.shinjadong.cloud/api/comms/msg \
    -H "Content-Type: application/json" \
    -d '{"from":"codex","to":["claude-code","jadong"],
         "type":"result","ref":"{original_msg_id}",
         "project":"keeper-direct",
         "title":"P1 Result Report",
         "content_md":"## 결과\n\n..."}'

Claude App

• 현재: URL로 문서 직접 읽기 (https://ai.shinjadong.cloud/{slug}.html)
• 향후: MCP 재활성화 시 comms-hub 도구 노출 (list_messages, read_message, post_reply)
• 댓글로 응답 → scratchpad이 comms-hub에 중계

Gemini (꽃샘)

• consciousness-bridge --strategy auto 실행 시 자동으로 type: "strategy-update" 메시지 생성
• 전략 변경 → 모든 AI inbox에 알림

7.3 인증

현재 단계: 인증 없음 (path-based secret도 미적용). 이유:

• Cloudflare가 앞단에서 DDoS 방어
• 사용자 = 자동님 1인 + AI 4종 (모두 신뢰 주체)
• 메시지 내용은 비밀이 아님 (코드 리뷰, 설계 문서)

Phase 6에서 Bearer 토큰 (config_vault에서 발급) 선택적 추가. from 필드 위변조 방지용.

8Phase 5: 충돌 방지 시스템

8.1 4중 충돌 방지 레이어

8.2 AI 네임스페이스 코드표

8.3 Claim API 상세

# claim 등록
POST /api/claim
{
  "resource": "keeper-direct/staging",
  "ai": "claude-code",
  "task": "msg_20260506_cc_a1b2c3",
  "ttl_hours": 24
}
→ 200 { "ok": true }
→ 409 { "error": "claimed by codex since 23:00" }

# claim 해제
DELETE /api/claim/keeper-direct%2Fstaging
→ 200

# 현황 조회
GET /api/claims
→ [{ "resource": "keeper-direct/staging",
     "ai": "claude-code",
     "since": "2026-05-06T00:07:00+09:00",
     "expires": "2026-05-07T00:07:00+09:00" }]

9Phase 6: 자동화 + 모니터링

9.1 댓글 → 명령 파서

scratchpad 댓글에서 AI 명령 패턴을 감지하여 comms-hub 메시지 자동 생성:

9.2 Telegram 알림

# 새 메시지
📨 [claude-code → jadong] work-order
"keeper-out admin Lead Detail P1"
📂 keeper-direct · 🏷️ admin, lead-detail
🔗 https://ai.shinjadong.cloud/msg/msg_xxx

# 상태 변경
✅ [codex] msg_xxx → done
📄 결과: https://ai.shinjadong.cloud/msg/msg_yyy

# 충돌 감지
⚠️ Syncthing conflict 감지
📄 2026-05-06-cc-xxx.sync-conflict-20260506-120000.html

9.3 Health 엔드포인트

GET /api/health
→ {
  "comms_hub": "ok",
  "scratchpad": "ok",
  "syncthing": "ok",
  "disk_pct": 42,
  "messages_total": 47,
  "messages_today": 8,
  "active_claims": 1,
  "uptime_hours": 72.4,
  "last_activity": {
    "claude-code": "2026-05-06T00:07:20+09:00",
    "codex": "2026-05-05T22:52:00+09:00"
  }
}

9.4 백업

# 크론: 매일 04:00 KST (EC2 측)
tar czf /home/ubuntu/backups/comms-$(date +%Y%m%d).tar.gz \
  /var/lib/comms/ /var/lib/scratchpad/
# 보존: 30일 (find -mtime +30 -delete)

9.5 Rate Limit + 안전장치

10실행 타임라인

11설계 원칙

12리스크 평가