워크플로우

최상위 원칙

계획이 승인되기 전까지 코드를 절대 작성하지 않는다. 유저는 회장이자 감독자다. 회장이 내린 결정을 임의로 변경하지 않는다. 대화 중 MD에 반영할 내용이 생기면 즉시 반영한다. 미루지 않는다. 무조건 프리티어만 사용한다. 유료 서비스는 회장 승인 필수.

Bugfix Protocol

증상 완화 금지. 처음부터 근본 해결. 이 프로세스는 모든 버그/이슈에 적용한다. 단계를 건너뛰지 않는다.

Phase 1. 근본 원인 파악 (5-Whys)

• 로그, 코드, 재현 테스트 등으로 근본 원인을 특정한다.
• 5-Whys 기법 사용: 증상에서 출발하여 "왜?"를 5회 반복, 구조적 원인까지 도달.
• 증거(로그 라인, 코드 위치, 재현 조건)를 반드시 첨부한다.
• 5-Whys 완료 전 해결방안 논의 금지.
• 벤더 종속 튜닝은 근본 원인이 아니다. effort 레벨(Claude 전용), 모델 변경(haiku↔sonnet), 타임아웃 단순 증감 — 이것들은 특정 벤더의 특정 모델에서 임계값을 밀어올리는 증상 완화이지 구조적 원인 제거가 아니다. Gemma, Codex 등 다른 LLM으로 교체하면 처음부터 다시 튜닝해야 하는 "해결책"은 근본 해결이 아닌 증거. 5-Whys가 벤더 설정에서 멈추면 Why가 부족한 것이다 — 더 파야 한다.

Phase 2. 다이아몬드 토론 (4개 방안 비교)

• 근본 원인에 대한 해결 방안을 최소 4개 도출한다.
• 다이아몬드 수렴 구조로 토론: 각 방안의 장단점을 대비한다.
• 프롬프트 의존 방안은 탈락 사유 (feedback_structure_over_prompt.md).

Phase 3. 4척도 검증

도출된 방안을 아래 4가지 척도로 검증한다. 전부 통과해야 채택 가능.

Phase 4. 채택 및 도입

• 4척도 전부 통과한 방안을 코드에 도입한다.
• 문서화 선행: ISSUES.md 등록 → 코드 수정 → ISSUES.md RESOLVED 업데이트.
• 회귀 차단: test-pipeline.ts에 회귀 테스트 추가 (가능한 경우).
• tsc 0에러 확인 후 완료.

요약 플로우

버그 발견
  → Phase 1: 5-Whys (근본 원인)
  → Phase 2: 다이아몬드 토론 (4개 방안)
  → Phase 3: 4척도 검증 (타협/양보/근본/증상완화)
  → Phase 4: 채택 도입 (문서→코드→테스트→문서)

아키텍처

모바일/웹 회장(유저) → Supabase DB → Node.js 서버 → Claude Code CLI 세션 (persistent)
                           ↑                              ↓
                     Realtime 구독              응답 → Supabase DB → 웹 실시간 표시

조직 계층

회장 (유저) — 큰 방향 지시, 최종 결재
    ↓
CEO 에이전트 (상시 존재, Sonnet) — 조직 운영 총괄, C레벨 고용
    ↓
C레벨 에이전트들 (CEO가 고용, 상시 Council) — 도메인 전략
    ↓
간부급 리더 (Sonnet) — 섹션 내 설계/판단
    ↓
워커 에이전트들 (Haiku) — 실무 실행

상세 설계: docs/spec/chairman-ceo-arch.md

C레벨 체계

CEO 에이전트 아래 C레벨 리더 → 간부급 → 워커 계층 구조. C레벨은 CEO가 프로젝트 분석 후 동적 고용. Phase 하드코딩 제거. C레벨 Council이 365일 24시간 상시 토론 — 방향/우선순위 자율 합의.

C레벨 리더

Phase 참고값 (I71)

Phase는 더 이상 C레벨 활성/비활성을 강제하지 않는다. Council이 현재 상황을 자율 합의하여 방향을 결정한다. Phase 레이블은 참고/문서화 용도로만 유지.

• mvp: 초기 빌드, 빌드 성공 3회 미만
• scale: 배포 이후, 사용자 유입 시작
• stable: 배포 + 마케팅 + 분석 안정화

Multi-C레벨 토론 (I74)

C레벨 Council 상시 토론 + DELEGATE가 2+ C레벨에 걸칠 때 자동 발동:

1. 관련 C레벨이 각자 관점에서 DELEGATE 계획 평가
2. 합의 도출 → DELEGATE 재조정 (또는 기존 유지)
3. 기존 debate 인프라(Consigliere, NodeTree) 재사용

CFO 비용 분석 (I73)

scale/stable Phase에서 매 세션 종료 시 자동 실행:

• 에이전트별 비용 비중, Top spender, 최근 평균 대비 분석
• 콘솔 리포트 (회장 응답에는 미삽입)

에이전트 계층 (기본 구성)

파이프라인 — C4I 아키텍처

2026-04-18 회장 결정: 모놀리스 index.ts 해체 → C4I(군사 지휘체계) 기반 전면 재구축. 상세 명세: docs/spec/pipeline-c4i.md (14섹션 + 부록 3개)

뼈대: C4I + 7개 체계 차용

실행 모델

• 순차 실행 + ViewHolder 풀 — 메모리/CPU 제약(셀프호스팅). 동시 실행 = ViewHolder 슬롯 수(기본 3).
• 유일한 병렬: C레벨이 콘실리에리 활용하여 토론 + 섹션 작업 동시 진행.
• 모델/CLI 무관: Agent Adapter 패턴으로 추상화. Claude CLI, Ollama, Codex, 미래 모델 교체 = 환경변수 1개.

파이프라인 흐름

1. Intake — 회장 메시지 수신, SIL 분류, Task Strip 생성
2. CEO Phase — OPORD(작전명령서) 형식으로 C레벨 지시 생성
   - 핸드오프 프로토콜: request → accept/reject → confirm (3단계)
3. C-Level Phase — 도메인 과업(WHAT)만 출력, 인원 배치(WHO)는 시스템 결정
   - 2+ C레벨 충돌 시 Multi-C레벨 토론 (I74)
4. Leader Phase — 구현 계획 수립, 워커 작업 분해
5. Worker Phase — 코드 실행 (ViewHolder 슬롯 내 순차)
6. Review Phase — BuildValidator + Evaluator (Generate-Verify 분리)
7. Report Phase — 4홉 상향 보고 (Worker→Leader→C-Level→CEO→회장)

안전장치:
- 안돈: 토큰 150%·에러 3연속·타임아웃 2연속 → 일시정지 + 상위 판단
- SCRAM: 토큰 300%·미인가 SIL-4·메모리 임계 → 전체 즉시 중단
- 핸드오프 거부 2회 → 자동 에스컬레이션

구현 현황 (server/src/pipeline/)

진행률 계산

전체 명세서 + task 파일 파싱 → 완료 task 백분율. GameStatsBar "진행" 바에 실시간 표시. 상세: docs/spec/clevel-spec-flow.md §6 참조.

에이전트 관리

기본 제공 에이전트 (프리셋)

• PM, CTO, Backend Lead/Dev, Frontend Lead/Dev, Security Lead/Researcher, QA, Perf, DevOps, DBA, Tech Writer, Data Analyst, API Dev
• 각각 CLAUDE.md + skills 파일이 미리 작성되어 제공
• 유저가 프리셋을 편집(이름/역할/CLAUDE.md/skills 수정) 가능

커스텀 에이전트 생성 흐름

회장: "마케터 추가해줘. 데이터 기반으로 분석하는 역할"
  ↓
PM이 개입:
  - 역할 정의 다듬기
  - CLAUDE.md 초안 작성
  - skills 파일 초안 작성
  - 회장에게 제안:
    "이렇게 설정하면 어떨까요?"
    ┌──────────────────────────┐
    │ 이름: 데이터 마케터        │
    │ 역할: Growth Marketer     │
    │ CLAUDE.md: (초안 표시)     │
    │ skills: (초안 표시)        │
    │                           │
    │ [컨펌]  [수정요청]  [내가 직접 작성] │
    └──────────────────────────┘
  ↓
회장 선택:
  A. 컨펌 → 즉시 생성 + 세션 시작
  B. 수정요청 → PM이 수정 후 재제안
  C. 내가 직접 작성 → 회장이 쓴 그대로 적용

• 설정 항목:
• 이름 (예: "김마케터", "UX전문가 박씨")
• 역할 (예: "마케터", "UX 리서처", "SEO 전문가")
• CLAUDE.md (역할 정의)
• skills (특수 능력)
• PM이 초안 작성 → 회장 컨펌/수정/직접작성 중 선택
• 컨펌 후 서버에 반영:

1. DB에 에이전트 저장
2. agents/<id>/CLAUDE.md 자동 생성
3. agents/<id>/.claude/skills/ 에 skills 파일 생성
4. 서버가 해당 에이전트의 세션 시작

에이전트 편집

• 이름, 역할, CLAUDE.md, skills 언제든 수정 가능
• 편집 시에도 PM 개입:
• 회장이 수정 → PM이 검토/다듬기 → 회장 컨펌
• 또는 회장이 "그대로 적용해" → PM 검토 없이 즉시 반영
• 컨펌 후 즉시 반영:

1. DB 업데이트
2. CLAUDE.md 파일 덮어쓰기
3. skills 파일 업데이트
4. 해당 에이전트 세션 재시작 (변경사항 적용)

리소스 관리

• 에이전트 수 제한 없음 — 본인이 원하는 만큼 생성
• PM이 서버 시작 시 호스트 PC 리소스 조사 → 최대 에이전트 수 보고
• 계산: (가용 메모리 - OS/앱 사용량) ÷ 세션당 ~300MB
• 최대 수 초과 시 PM이 경고
• 서버가 동적으로 세션 시작/종료

세션 프로토콜

세션 시작

1. docs/memory/MEMORY.md 읽기 (컨텍스트 복구)
2. docs/DASHBOARD.md 읽기 (현재 상태 파악)

세션 중

세션 종료

1. CHANGELOG.md에 세션 요약
2. DASHBOARD.md 현황 갱신

실측 테스트 절차

표준 테스트 조건 (고정)

• 앱: 넷플릭스 클론 (스트리밍 UI, 콘텐츠 목록, 상세 페이지)
• iOS 최소 버전: 14
• Android 최소 버전: 마시멜로우 (API 23)
• 프로젝트명: StreamApp / 패키지: com.jupond.streamapp

레포 구분 (필수)

실측 시 git pull은 서버 레포만 필요하다. iOS/Android는 로컬 개발+배포 방식이므로 별도 pull 불필요.

실행 절차

1. archi/ 폴더 초기화
   rm -rf ~/Desktop/archi && mkdir ~/Desktop/archi

2. 실사용 인스턴스 동기화 + 서버 백그라운드 실행
   # ⚠️ 오픈소스 레포가 아닌 실사용 인스턴스에서 서버를 띄운다
   cd ~/Desktop/bigbossos && git pull
   cd ~/Desktop/bigbossos/server && npm start &

3. 회장 메시지 DB에 직접 INSERT (Claude가 node 스크립트로 실행)
   node -e "
     import('dotenv/config').then(async () => {
       const { createClient } = await import('@supabase/supabase-js');
       const sb = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY);
       await sb.from('messages').insert({
         node_type: 'root',
         agent_id: 'ceo',
         content: '넷플릭스같은 동영상 스트리밍 앱 만들어줘. iOS 최소 버전 14, Android 최소 API 23. 프로젝트명: StreamApp, 패키지: com.jupond.streamapp',
         msg_type: 'user_message'
       });
     });
   "

4. 서버 로그 모니터링 (Claude가 직접 관찰)

5. 완료 후 결과 확인
   - archi/ios/ xcodebuild 빌드 성공 여부
   - G9 자동수정 횟수
   - 비용 → token-optimization.md 기록

측정 항목 (G10 판정 기준)

코딩 규약

• 메모리: 최소 사용, 메모리 누수 없을 것
• 설계: 모듈화, 캡슐화, 낮은 종속성
• 성능: 캐시/로컬 최대 활용, API 호출 최소화
• 보안: 항상 고려, 프리티어 범위 내
• 코드 작성은 개발자만: 아키텍트, 보안, PM은 리뷰/지시만

금지사항