Consigliere — 명세 + 적용 가이드

BigBoss OS 도메인 특화 메모리 시스템. MD 파일 기반 + 시맨틱 검색 + 버전 추적 + MCP 연동. Capomastro처럼 독립 라이브러리로 에이전트가 CLI에서 호출.

1. 배경 및 목적

현재 시스템 한계

목표

• 할루시네이션 제로: 문서 내용만 반환. 생성/추론 없음
• 시맨틱 검색: 의미 기반 검색
• 버전 추적: 특정 시점 메모리 조회/복원
• BigBoss OS 도메인 특화: 범용보다 높은 정확도
• 에이전트 CLI 호출: bin/consigliere --search (Capomastro 패턴)
• 완전 무료, self-hosted, 오프라인

경쟁 분석

2. 아키텍처

┌──────────────────────────────────────────────────────────┐
│                    Source of Truth                         │
│  docs/CHANGELOG.md  docs/ISSUES.md  docs/rules.md        │
│  docs/workflow.md   docs/DASHBOARD.md  docs/memory/*.md  │
│  CLAUDE.md  *.md (전체)                                   │
└────────────────────┬──────────────────────────────────────┘
                     │ 자동 인덱싱 (VCS hook / fs.watch / CLI 수동)
                     ▼
┌──────────────────────────────────────────────────────────┐
│                   Consigliere DB (SQLite)                       │
│  chunks     → 문서 청크 + 임베딩 벡터                       │
│  snapshots  → VCS commit별 인덱스 스냅샷                    │
│  metadata   → 파일별 인덱싱 상태                            │
│  tags       → 자동 태깅 (역할, 상태, 날짜)                   │
│  relations  → 문서 간 관계 (모순, 참조, 업데이트)              │
└────────────────────┬──────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│   CLI    │  │   MCP    │  │   API    │
│ bin/     │  │ Claude   │  │ Node.js  │
│ consigliere   │  │ Code 연동 │  │ 서버 연동 │
└──────────┘  └──────────┘  └──────────┘

3. 핵심 기능

3.1 자동 인덱싱

트리거:

• git post-commit hook → 커밋마다 자동 인덱싱
• fs.watch → 파일 변경 실시간 감지 (선택적)
• bin/consigliere index → 수동 인덱싱

청킹 전략 (BigBoss OS 도메인 특화):

시스템 문서 | 파일 유형 | 청크 단위 | 자동 메타데이터 | |-----------|----------|----------------| | CHANGELOG.md | ## [날짜] 제목 섹션 | 날짜, 결정/구현 분류 | | ISSUES.md | ## ISSUE-N: 제목 항목 | 상태(OPEN/CLOSED), 심각도 | | rules.md | 결정 항목 단위 | 회장 결정, 날짜 | | workflow.md | ## 제목 섹션 | 워크플로우 단계 | | DASHBOARD.md | 전체 (단일 청크) | 현재 상태 | | memory/*.md | 전체 파일 | 메모리 유형 | | 기타 .md | ## 제목 섹션 | 일반 |

C레벨 PM 문서 (archi//specs/) | 파일 유형 | 청크 단위 | 자동 메타데이터 | Mind Palace 방 | |-----------|----------|----------------|--------------| | -spec.md | ## 제목 섹션 | C레벨, Phase, 발급일 | architecture | | -wbs.md | ## N. 대분류 섹션 | C레벨, 작업 계층 | architecture | | -gantt.md | 전체 (단일 청크) | C레벨, 타임라인 | history | | -raci.md | 전체 (단일 청크) | C레벨, 담당자 매트릭스 | architecture | | -risk.md | 리스크 항목 단위 | C레벨, 심각도, 상태 | security | | -status.md | 전체 (단일 청크) | C레벨, 갱신일, 완료율 | history | | -adr.md | ADR 항목 단위 | 결정일, 상태(accepted/deprecated) | architecture | | -tech-debt.md | 항목 단위 | 심각도, 담당자 | architecture | | -budget.md | ## 항목 섹션 | Phase, 예산 범주 | (cfo 전용) | | -gtm.md | ## 항목 섹션 | Phase, 채널 | (cmo 전용) | | tasks/-tasks.md | 체크박스 항목 단위 | C레벨, 완료여부, 담당자 | (전 방 공통) |

임베딩:

• 1순위: Ollama nomic-embed-text (768차원, 로컬)
• 2순위: sentence-transformers/all-MiniLM-L6-v2 (384차원, Python)
• 경량 모드: BM25 (임베딩 없이 키워드 기반)

3.2 시맨틱 검색

쿼리 → 임베딩 → 벡터 유사도(cosine) + BM25 키워드 → 가중 합산 → Top-K 반환
score = α × vector_similarity + (1-α) × bm25_score   (α = 0.7 기본값)

필터: | 필터 | 예시 | |------|------| | 파일 유형 | --type changelog | | 날짜 범위 | --after 2026-03-28 --before 2026-03-30 | | 태그 | --tag security | | 역할 | --role director | | 상태 | --status open |

3.3 할루시네이션 제로

• 인덱싱된 MD 파일 원문만 반환
• 요약/변환/생성 없음
• 항상 출처 표시 (파일:라인)
• 관련 문서 없으면 "검색 결과 없음" (추측 금지)

3.4 버전 추적

bin/consigliere search "에이전트 구조" --at HEAD~10  # 10커밋 전 시점 검색
bin/consigliere diff HEAD~5 HEAD                     # 변경 diff
bin/consigliere restore abc123                       # 해당 커밋 인덱스로 전환

3.5 모순 감지

bin/consigliere check
# ⚠️ CONTRADICTION: rules.md:12 "PM이 관리" ↔ CHANGELOG.md:45 "Director로 변경"
#    → 최신: CHANGELOG (2026-03-29) 우선. rules.md 업데이트 필요.

3.6 에이전트 역할별 검색 우선순위

4. CLI 인터페이스

# 인덱싱
bin/consigliere index                          # 전체 인덱싱
bin/consigliere index docs/CHANGELOG.md        # 특정 파일
bin/consigliere index --watch                  # 실시간 감시

# 검색
bin/consigliere search "보안 관련 결정"
bin/consigliere search "에이전트 구조" --type changelog
bin/consigliere search "버그" --after 2026-03-28
bin/consigliere search "로그인" --role ios_developer
bin/consigliere search "에이전트" --at HEAD~5

# 버전
bin/consigliere snapshot                       # 현재 스냅샷
bin/consigliere diff HEAD~5 HEAD               # 차이
bin/consigliere restore abc123                 # 시점 조회

# 모순
bin/consigliere check                          # 모순 스캔
bin/consigliere check --fix                    # 자동 해결 제안

# 상태
bin/consigliere status

5. 데이터 모델

-- 청크
CREATE TABLE chunks (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  file TEXT NOT NULL,
  heading TEXT,
  content TEXT NOT NULL,
  content_hash TEXT NOT NULL,
  embedding BLOB,
  file_type TEXT NOT NULL,
  date TEXT,
  tags TEXT DEFAULT '',
  status TEXT DEFAULT 'active',
  commit_hash TEXT,
  line_start INTEGER,
  line_end INTEGER,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 스냅샷
CREATE TABLE snapshots (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  commit_hash TEXT NOT NULL UNIQUE,
  commit_message TEXT,
  commit_date TIMESTAMP,
  chunk_count INTEGER,
  file_count INTEGER,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 관계 (모순/참조)
CREATE TABLE relations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  chunk_a INTEGER REFERENCES chunks(id),
  chunk_b INTEGER REFERENCES chunks(id),
  relation_type TEXT NOT NULL,     -- contradiction, reference, update, duplicate
  confidence REAL DEFAULT 0.0,
  resolved BOOLEAN DEFAULT FALSE,
  resolution TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

6. 기술 스택

7. 성능 목표

8. CodePipe — 코드 전용 파이프라인

코딩 특화 모델의 외장 메모리. DocumentPipe(문서용)와 함께 통합 저장 + 이중 파이프 구조.

지원 언어: Swift (1순위), TypeScript/JS (1순위), Python (1순위), Go (2순위), Kotlin (2순위)

# 코드 인덱싱/검색
bin/consigliere code index
bin/consigliere code search "login"
bin/consigliere code refs loginUser
bin/consigliere code callers login
bin/consigliere code deps auth.swift
bin/consigliere search "로그인 수정" --unified   # 코드+문서 동시 검색

9. BigBoss OS 통합 방법

설치

cp bin/consigliere /path/to/bigbossos/bin/consigliere
cd bigbossos/
bin/consigliere index
bin/consigliere hook install

.consigliere.toml

[index]
paths = ["docs/**/*.md", "CLAUDE.md", "docs/memory/*.md"]
exclude = [".consigliere/**", ".git/**", "node_modules/**"]

[search]
default_top_k = 5
min_score = 0.3

[embedding]
enabled = false
model = "nomic-embed-text"
endpoint = "http://localhost:11434"
dimensions = 768

서버 코드 (server/src/orchestrator/consigliere.ts)

import { execSync } from 'child_process';
import path from 'path';

const CONSIGLIERE_BIN = path.resolve(__dirname, '../../../bin/consigliere');

export function getConsigliereContext(task: string, role: string, cwd: string, topK = 5): string {
  try {
    const result = execSync(
      `"${CONSIGLIERE_BIN}" search "${task.replace(/["\\\n]/g, '')}" --role ${role} --top ${topK}`,
      { cwd, timeout: 5000, encoding: 'utf-8' }
    );
    if (!result || result.includes('검색 결과 없음')) return '';
    return `\n\n## 참고 문서 (Consigliere)\n\n${result.trim()}`;
  } catch {
    return '';
  }
}

llm.ts 수정 — callAgent()에 주입

+ import { getConsigliereContext } from './consigliere';

  // callAgent() (Line ~789)
+ const consigliereContext = getConsigliereContext(message, role, cwd);
+ args.push('--append-system-prompt', getHardRules(role) + consigliereContext);

  // callClaude() — Director (Line ~548)
+ const consigliereContext = getConsigliereContext(message, 'director', cwd);
+ args.push('--append-system-prompt', getHardRules('director') + consigliereContext);

토큰 절약 효과

10. 개발 로드맵

11. Mind Palace — Phase 2 도메인 방 설계

토론 합의 결과 (2026-04-10): 완전 격리(hard partition) 아닌 가중치 기반 연성 분리 채택.

방 구조

스키마 변경

-- chunks 테이블에 room 가중치 필드 추가
ALTER TABLE chunks ADD COLUMN rooms TEXT DEFAULT '';
-- 예: "ios,security" (다중 방 소속 가능)

검색 점수 공식 (Phase 2)

score = α × vector_sim + (1-α) × bm25 + β × room_match_bonus

• α = 0.7 (벡터 vs BM25 비율, 기존 유지)
• β = Phase 2 실측 후 결정 (하드코딩 금지)
• room_match_bonus = 에이전트 역할의 주요 방과 청크의 방이 일치하면 +1, 아니면 0

방 자동 분류 (.consigliere.toml)

[rooms]
ios      = ["swift", "swiftui", "xcode", "ios_dev", "contentview"]
android  = ["kotlin", "gradle", "android", "room", "manifest"]
security = ["rls", "auth", "injection", "owasp", "cve", "sanitize"]
api      = ["endpoint", "route", "express", "node", "api"]
db       = ["schema", "migration", "supabase", "postgres", "sqlite"]
architecture = ["mvvm", "mvp", "clean", "architect", "pattern"]
history  = ["changelog", "completed", "resolved", "fixed"]

키워드 매칭으로 자동 분류. 새 도메인은 TOML만 수정 (재빌드 불필요).

미결 사항 (실측 후 결정)

• room TEXT 컬럼 추가 vs 기존 tags 컬럼 활용 비교 실험 필요
• β 하이퍼파라미터: Phase 2 벡터 검색 실측 데이터 기반으로 결정

12. 능동적 문서화 요청 시스템 (Active Documentation Enforcer)

배경: 에이전트는 컨텍스트 한계로 인해 WBS·간트·RACI 등 PM 문서화를 건너뛸 수 있다. Consigliere는 수동적 메모리 저장소가 아니라 능동적 문서화 감시자로 동작한다.

12.1 트리거 3종

12.2 요청 방식 — 브로드캐스트 금지, 개별 타겟

브로드캐스트 (금지):
  Consigliere → "전체 에이전트 문서화해" (X)

개별 타겟 요청 (올바른 방식):
  Consigliere → ios_dev:    "iOS 개발 완료분 문서화 요청"
  Consigliere → android_dev: "Android 개발 완료분 문서화 요청"
  Consigliere → api_dev:    "API 개발 완료분 문서화 요청"
  Consigliere → cto:        "CTO WBS·간트·상태보고서 갱신 요청"
  Consigliere → coo:        "COO 리스크 등록부·SLA 갱신 요청"
  ...

각 에이전트에게 역할에 맞는 문서 목록을 특정하여 요청한다.

12.3 누락 감지 로직

for each project in archi/*/specs/:
  for each active_clevel in current_phase:
    required_docs = 공통 7종 + C레벨별 추가 문서
    for each doc in required_docs:
      if doc 파일 없음 OR 마지막 갱신 > 24h:
        → 해당 C레벨 에이전트에게 문서화 요청
    for each worker under clevel:
      if tasks/{worker}-tasks.md 없음 OR 미갱신:
        → 해당 워커 에이전트에게 task 문서화 요청

12.4 문서화 요청 포맷

[CONSIGLIERE → {agent_role}]
문서화 요청: {doc_type}
대상 프로젝트: {project_name}
미갱신 경과: {hours}시간
파일 경로: archi/{project}/specs/{filename}

요청 내용:
  - 현재 작업 완료분을 위 파일에 반영해주세요.
  - 포맷: docs/spec/clevel-spec-flow.md §2.4 참조
  - 완료 후 Consigliere에 자동 인덱싱됩니다.

12.5 요청 실패 시 처리

12.6 CLI 명령

# 수동 문서화 감사 + 요청
bin/consigliere audit-docs                     # 전 에이전트 문서 누락 스캔
bin/consigliere audit-docs --project StreamApp # 특정 프로젝트
bin/consigliere request-doc --agent cto --type wbs --project StreamApp  # 특정 요청
bin/consigliere audit-docs --fix               # 누락 감지 즉시 요청 실행

12.7 서버 연동 (구현 위치)

// server/src/orchestrator/consigliere.ts 확장

// 실시간 트리거 — Evaluator 완료 시 호출
export async function onTaskCompleted(agentRole: string, projectName: string): Promise<void>

// 작업량 업데이트 트리거 — progress.json 갱신 시 호출
export async function onProgressUpdated(projectName: string): Promise<void>

// 크론 트리거 — 서버 시작 시 등록 (매일 00:00)
export function scheduleDocAudit(): void

12.8 개발 로드맵 추가 항목

변경 이력